wenzi/docs/tasks-2025-09-30.md

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

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 Actions：已添加 .gitea/workflows/ci.yml，同样在 push/PR 上执行 Maven 构建与测试。
• 验证：在 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，端口注入仍生效。
• 优化：统一全仓库注解命名空间。