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个核心文档 - 建立清晰的文档导航体系 - 完善文档间的交叉引用
2.0 KiB
2.0 KiB
代码审查报告（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、序列化策略与命名规范。
建议优先级
- 统一异常处理与错误响应格式（高）。
- 去除
Thread.sleep模拟延迟（高）。 - 对齐领域模型与数据库（引入 JPA 实体/仓储）（高）。
- 缓存策略（TTL、序列化、命名）与多环境配置（中）。
- API Key 安全增强与审计（中）。
- 测试覆盖补齐（奖励/多级奖励/上传/权限）（中）。
- 依赖精简或尽快落地 AMQP/JPA（中）。
- 覆盖率基线（JaCoCo）与质量门禁（中）。