# mosquito

Spring Boot 3 (Java 17) 应用，用于活动传播、邀请奖励与运营分析。

快速开始
- 构建与测试：`mvn -B -DskipTests=false clean verify`（将触发 Flyway 迁移与覆盖率门禁）
- 运行（开发）：`mvn spring-boot:run`（默认 `dev` 配置）

关键端点
- 所有 JSON 响应统一为 `ApiResponse`，业务数据位于 `data` 字段。
- `/api/**` 需要 `X-API-Key`；`/api/v1/me/**`、`/api/v1/activities/**`、`/api/v1/api-keys/**`、`/api/v1/share/**` 还需要 `Authorization: Bearer <token>`。
- API 密钥
  - 创建：`POST /api/v1/api-keys`
  - 吊销：`DELETE /api/v1/api-keys/{id}`
  - 使用（按 ID 校验并打点）：`POST /api/v1/api-keys/{id}/use`
  - 使用（仅凭明文密钥，无需 ID）：`POST /api/v1/api-keys/validate`

- 用户端体验
  - 邀请信息：`GET /api/v1/me/invitation-info`
  - 邀请好友分页：`GET /api/v1/me/invited-friends`
  - 海报图片：`GET /api/v1/me/poster/image`
  - 海报 HTML：`GET /api/v1/me/poster/html`
  - 海报配置：`GET /api/v1/me/poster/config`

- 缓存管理（需要管理令牌）
  - 清空缓存：`DELETE /api/v1/cache/{cacheName}`
  - 失效键：`DELETE /api/v1/cache/{cacheName}/{key}`

运维与安全
- 配置管理令牌：`app.cache.admin-token`（通过环境变量或配置文件注入）
- 缓存失效限流：`app.cache.rate-limit-per-minute`（默认 60）
- Redis 缓存分组 TTL（可在 `CacheConfig` 中调整）：
  - `leaderboards` 5m、`activities` 1m、`activity_stats` 2m、`activity_graph` 10m
- 生产环境必须设置 `app.security.encryption-key`（例如环境变量 `APP_SECURITY_ENCRYPTION_KEY`）
- 覆盖率门禁：`pom.xml` 中启用 JaCoCo，阈值 80%，在 `verify` 阶段校验

更多接口与错误码见 `docs/api.md`。