0eed01e9eb
新增文档： - API_INTEGRATION_GUIDE.md: API集成指南（快速开始、SDK示例、常见场景） - DEPLOYMENT_GUIDE.md: 部署指南（环境要求、生产部署、Docker部署） - CONFIGURATION_GUIDE.md: 配置指南（环境配置、数据库、Redis、安全） - DEVELOPMENT_GUIDE.md: 开发指南（环境搭建、项目结构、开发规范） 文档更新： - api.md: 补充8个缺失的API端点（分享跟踪、回调、用户奖励） 文档清理： - 归档18个过时文档到 docs/archive/2026-03-04-cleanup/ - 删除3个调试文档（ralph-loop-*） 代码清理： - 删除4个.bak备份文件 - 删除1个.disabled测试文件 文档结构优化： - 从~40个文档精简到12个核心文档 - 建立清晰的文档导航体系 - 完善文档间的交叉引用
31 lines
2.0 KiB
Markdown
31 lines
2.0 KiB
Markdown
# 代码审查报告（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）与质量门禁（中）。
|
||
|