# 代码审查报告（2025-09-30）

## 概览
- 技术栈：Spring Boot 3、Java 17、Maven、JUnit 5、MockMvc、Flyway、Redis（缓存，测试为嵌入式）。
- 构建与测试：已联网执行 `mvn clean verify` 成功。产物 `target/mosquito-0.0.1-SNAPSHOT.jar` 生成。
- 测试统计：共 26 个测试，全通过（0 失败/0 错误/0 跳过），详见 `target/surefire-reports/`。

## 结构与模块
- 包结构清晰：`controller / service / domain / dto / exception / job`。
- 资源与迁移：`application.properties` 与 Flyway 迁移（V1–V5）完整，命名规范。
- 文档完善：`docs/`（API、架构、数据模型、测试计划）与 `specs/` 分层合理。

## 主要发现
- 控制器：输入校验充分（`@Valid`），返回码语义正确；异常部分依赖注解映射，建议统一异常处理。
- 服务：`ActivityService` 为内存态实现，具备并发安全；`getLeaderboard` 使用 `Thread.sleep` 模拟耗时，建议替换为可注入的延迟或移除。
- 领域模型：当前未持久化（无 JPA 注解），与 Flyway 表结构存在偏差（如 JSONB 字段、状态字段等）。
- 定时任务：`StatisticsAggregationJob` 逻辑简单明确，易扩展为真实数据聚合。
- 依赖：引入了 JPA/AMQP 但暂未使用；`javax.annotation-api` 在 Boot 3 生态建议迁移至 `jakarta.annotation`（仅测试配置中使用）。
- 缓存：`@Cacheable("leaderboards")` 生效，建议补充 TTL、序列化策略与命名规范。

## 建议优先级
1) 统一异常处理与错误响应格式（高）。
2) 去除 `Thread.sleep` 模拟延迟（高）。
3) 对齐领域模型与数据库（引入 JPA 实体/仓储）（高）。
4) 缓存策略（TTL、序列化、命名）与多环境配置（中）。
5) API Key 安全增强与审计（中）。
6) 测试覆盖补齐（奖励/多级奖励/上传/权限）（中）。
7) 依赖精简或尽快落地 AMQP/JPA（中）。
8) 覆盖率基线（JaCoCo）与质量门禁（中）。