# 任务清单（质量闭环：分析 → 实施 → 验证 → 优化）

## 0) 推送至 Gitea 并启用 CI/CD（Woodpecker）
- 分析：需要标准化远程仓库与流水线，以便每个任务完成后自动执行完整验证。
- 实施：
  - 在 Gitea 上创建仓库（建议名称：mosquito）。
  - 本地添加远程并推送：`git remote add origin <gitea_url>; git push -u origin <branch>`。
  - 使用 Woodpecker：已添加 `.woodpecker.yml`，默认在 push/PR 触发 `mvn clean verify` 全量验证与打包。
- 验证：在 Gitea 中查看流水线执行成功（build+test 通过，产物成功构建）。
- 优化：后续按需要加入缓存、制品归档、分支保护与质量门禁。

## 1) 统一异常处理与错误响应格式
- 分析：当前仅部分异常带 `@ResponseStatus`，无统一错误结构（code/message/path/timestamp）。
- 实施：新增 `GlobalExceptionHandler`（`@ControllerAdvice`），覆盖验证异常、业务异常与兜底异常；定义标准错误响应模型。
- 验证：
  - 控制器集成测试断言 400/403/404 等状态码与错误体结构。
  - 示例：`mvn -q -Dtest=*ControllerTest test`。
- 优化：记录错误码表到 `docs/api.md`，引入日志关联 ID。

## 2) 移除 `Thread.sleep` 模拟延迟
- 分析：`ActivityService#getLeaderboard` 阻塞线程，影响吞吐与可测试性。
- 实施：引入 `DelayProvider` 接口并在生产实现为无延迟，测试实现可配置；删除 `Thread.sleep`。
- 验证：缓存测试通过且时延显著下降；`ActivityServiceCacheTest` 仍然命中缓存。
- 优化：必要时改为异步计算与预热策略。

## 3) 领域模型与数据库对齐（引入 JPA / Repository）
- 分析：领域为内存态，与 Flyway 表（如 JSONB、状态字段）不一致。
- 实施：为 `Activity / ApiKey / DailyActivityStats / MultiLevelRewardRule` 增加 JPA 注解与映射；新增 `Repository`；服务改用持久化。
- 验证：
  - H2 下 `@DataJpaTest` 与 `@SpringBootTest` 通过；`SchemaVerificationTest` 增强校验关键列与约束。
  - 示例：`mvn -q -Dtest=*Jpa* test`。
- 优化：实体与 Flyway 迁移保持前滚兼容；引入测试数据工厂。

## 4) 缓存策略与配置
- 分析：仅使用 `@Cacheable`，缺少 TTL、序列化与命名规范。
- 实施：添加 `CacheConfig` 设置默认 TTL（如 5m）、`RedisCacheConfiguration` 与 JSON 序列化；键空间命名统一。
- 验证：集成测试校验缓存生效与过期；命中率指标可观测。
- 优化：按端点分组 TTL；加入手动失效接口或消息驱动失效。

## 5) API Key 安全增强
- 分析：当前为 `UUID + salt + SHA-256`；建议 KDF（BCrypt/Argon2）并完善审计。
- 实施：引入 `BCryptPasswordEncoder` 存储哈希，新增校验与轮换逻辑，记录 `last_used_at` 更新。
- 验证：
  - 单测验证加密强度（无法逆推）与匹配成功；
  - 集成测试覆盖创建/撤销/使用审计。
- 优化：支持密钥前缀与分段展示；限流与告警。

## 6) 覆盖率与质量门禁
- 分析：无覆盖率阈值；关键逻辑测试缺口。
- 实施：引入 JaCoCo 插件并设置最低阈值（例如 80%）；补充奖励计算、多级奖励、上传大小/类型、权限异常等单测。
- 验证：`mvn -q verify` 通过且生成 `target/site/jacoco/index.html`。
- 优化：在 CI 中发布覆盖率报告与趋势。

## 7) 多环境配置（dev/test/prod）
- 分析：仅 `application.properties`，未分环境。
- 实施：新增 `application-dev.yml`、`application-test.yml`、`application-prod.yml`；区分数据源/Flyway/日志级别/缓存设置。
- 验证：本地 `SPRING_PROFILES_ACTIVE=dev` 可运行，测试默认 `test`，构建产物默认 `prod`。
- 优化：敏感配置使用环境变量或外部化配置。

## 8) 依赖治理（JPA/AMQP）
- 分析：已引入 `spring-boot-starter-data-jpa`、`spring-boot-starter-amqp`，暂未落地。
- 实施：二选一：
  1) 近期不引入消息与持久化：移除未用 starter；
  2) 落地仓储与消息接口：新增最小可用实现与集成测试。
- 验证：`mvn -q verify` 通过；依赖树精简（`mvn -q dependency:tree`）。
- 优化：定期审计依赖、锁定版本、启用漏洞扫描。

## 9) 注解迁移（javax → jakarta，仅测试配置）
- 分析：`EmbeddedRedisConfiguration` 使用 `javax.annotation`。
- 实施：迁移至 `jakarta.annotation`；清理 `javax.annotation-api` 依赖或限定 test scope。
- 验证：测试环境可正常启动嵌入式 Redis，端口注入仍生效。
- 优化：统一全仓库注解命名空间。