122 lines
5.8 KiB
Markdown
122 lines
5.8 KiB
Markdown
# 开发文档（Game Platform Server）
|
||
|
||
本项目为 Spring Boot 3 + WebFlux + MyBatis + MySQL 的后端服务。文档用于：
|
||
- 统一开发风格与规范
|
||
- 明确分层、目录结构与模块边界
|
||
- 约定接口设计、异常与日志规范
|
||
- 指导环境搭建、数据库迁移与交付流程
|
||
- 便于新同学快速接手
|
||
|
||
## 技术栈与版本
|
||
- Java 17、Maven 3.9+
|
||
- Spring Boot 3.x（WebFlux、Actuator、Security）
|
||
- MyBatis（JDBC，XML 映射）
|
||
- MySQL 8+
|
||
- JWT（JJWT 0.11.x）
|
||
|
||
## 目录结构（分层优先 layer-first）
|
||
- `src/main/java/com/gameplatform/server`
|
||
- `config`：全局配置（WebFlux、CORS、Jackson 等）
|
||
- `security`：`SecurityConfig`、`JwtService`、认证授权
|
||
- `exception`：全局异常处理、错误码
|
||
- `common`：常量、工具、拦截器、审计
|
||
- `model`
|
||
- `entity`：与数据库表对应的实体（如 `entity.account.UserAccount`）
|
||
- `dto`：请求/响应 DTO（如 `dto.auth.LoginRequest`）
|
||
- `controller`：按模块子包（`auth`, `link`, `batch`, `points`, `announcement`, ...）
|
||
- `service`：按模块子包（与 controller 对应）
|
||
- `mapper`：按模块子包（接口 + XML）
|
||
- `src/main/resources`
|
||
- `mapper/**.xml`：MyBatis XML 映射
|
||
- `application.yml`：多环境配置（建议扩展 `application-dev.yml` 等）
|
||
- 可选：`db/migration`（建议引入 Flyway 管理 SQL）
|
||
- `docs/`：需求、数据库结构、开发文档（本文件）
|
||
|
||
## 数据库与模型
|
||
- 统一账户表：`user_account`（ADMIN/AGENT 共用，通过 `user_type` 区分）
|
||
- 关键字段：`username` 唯一、`password_hash`（BCrypt 或初始化阶段 `PLAIN:<password>`）、`role`（ADMIN 用）、`points_balance`（AGENT 用）
|
||
- 初始账户：`admin / admin7uqweh12`（以 `PLAIN:` 方式插入，部署后务必改为 BCrypt）
|
||
- 相关表：`agent_points_tx`、`link_batch`、`link_task`、`operation_log`、`announcement`
|
||
- SQL 参考：`docs/game.sql`
|
||
- 建议：后续改为 Flyway 迁移（`V001__init.sql` 起步），避免手工执行 SQL
|
||
|
||
## 安全与认证
|
||
- 登录：`POST /api/auth/login`（`username` + `password`，角色自动识别）
|
||
- 自我信息：`GET /api/auth/me`（Authorization: Bearer <JWT>）
|
||
- JWT：HS256；配置在 `security.jwt.*`（`application.yml`）
|
||
- 密码：默认 `BCrypt`；兼容 `PLAIN:` 前缀以便初始化迁移
|
||
|
||
## API 设计规范
|
||
- 路径：REST 风格、资源复数，如 `/api/links`、`/api/batches`
|
||
- 状态码：201 创建、204 删除、400/401/403/404/409/429、500 异常
|
||
- 统一返回（推荐）：`{code, message, data, traceId}` 或直接返回资源对象（二选一并全局统一）
|
||
- 分页：`page,size,sort`；返回 `{items,total,page,size}`；热点列表优先 keyset 分页
|
||
- 幂等：写操作支持 `Idempotency-Key`
|
||
- 速率限制：对轮询/二维码代理端点限流，返回 429
|
||
|
||
## 异常与日志
|
||
- 全局异常：`exception/GlobalExceptionHandler` 映射为统一 JSON
|
||
- 关联 ID：响应体与日志注入 `traceId`（落地可加 Filter/MDC）
|
||
- 日志：结构化、脱敏（token/手机号/IP 末段）
|
||
|
||
## WebFlux + MyBatis 指南
|
||
- MyBatis 基于 JDBC 阻塞；在 Service 层用 `Schedulers.boundedElastic()` 包裹
|
||
- 事务在 Service；XML 使用 `resultMap` + `Base_Column_List`，避免 N+1
|
||
- 命名：DB 下划线、Java 驼峰；启用 `map-underscore-to-camel-case`
|
||
|
||
## 开发流程与规范
|
||
- 分支：`main`（稳定） / `feat/*`（功能） / `fix/*`（修复） / `chore/*`
|
||
- 提交规范（建议）：`type(scope): subject`，如 `feat(auth): add login api`
|
||
- 代码风格：
|
||
- Controller 瘦、Service 厚；禁止直接在 Controller 写 SQL
|
||
- DTO 与 Entity 分离；禁止直接暴露 Entity 给前端
|
||
- 单一职责、接口优先；跨模块通过 Service 接口交互
|
||
- 注释清晰，公共逻辑放 `common`/工具类
|
||
- 代码评审：PR 必须通过基本 CI 与至少 1 名评审
|
||
|
||
## 环境与配置
|
||
- `application.yml`：数据库连接、`security.jwt.secret`（务必替换默认 secret）
|
||
- 多环境：添加 `application-dev.yml`/`-prod.yml` 并通过 `SPRING_PROFILES_ACTIVE` 选择
|
||
- 机密：使用环境变量/密钥管理器，不要提交到仓库
|
||
|
||
## 构建与运行
|
||
- 本地：`mvn spring-boot:run`
|
||
- Jar：`mvn clean package` → `java -jar target/*.jar`
|
||
- Docker（建议后续补）：多阶段构建 + 健康检查 + 环境变量注入
|
||
|
||
## 测试策略
|
||
- 单元测试：Service 规则、扣点/状态机
|
||
- 切片测试：`@WebFluxTest`（控制器）、`@MybatisTest`（Mapper）
|
||
- 集成测试：Testcontainers MySQL 覆盖关键闭环（批次→扣点→链接→二维码→登录）
|
||
|
||
## 任务分解与进度追踪（示例）
|
||
- V1 基础闭环
|
||
- [ ] 统一返回体与错误码
|
||
- [x] 登录与 JWT（admin/agent 合表）
|
||
- [ ] 批次创建、扣点流水、链接生成
|
||
- [ ] 二维码代理与状态轮询
|
||
- [ ] 操作日志、公告 CRUD
|
||
- V2 稳态与风控
|
||
- [ ] 幂等、限流、黑名单/刷新令牌
|
||
- [ ] 报表与导出、对账
|
||
- V3 优化
|
||
- [ ] 乐观锁/并发扣点优化、观测/告警
|
||
|
||
## 接口清单（节选）
|
||
- `POST /api/auth/login`：登录获取 JWT（仅需 `username`、`password`）
|
||
- `GET /api/auth/me`：当前用户信息
|
||
- `GET /api/link/{codeNo}`：查询链接元数据（待实现）
|
||
- `POST /api/link/{codeNo}/select-region`：选择区服（待实现）
|
||
- `GET /api/link/{token}/qr.png`：二维码代理（待实现）
|
||
|
||
## 上手步骤
|
||
1) 配置数据库连接与 `security.jwt.secret`
|
||
2) 执行 `docs/game.sql` 初始化库与默认管理员
|
||
3) `mvn spring-boot:run` 启动服务
|
||
4) 调用 `POST /api/auth/login` 获取 token，再访问 `GET /api/auth/me`
|
||
|
||
## 注意事项
|
||
- 默认管理员以 `PLAIN:` 存储密码，仅用于初始化。上线前必须改为 BCrypt：
|
||
- 方案：使用项目内 `BCryptPasswordEncoder` 生成哈希，更新 `user_account.password_hash`
|
||
- 统一返回体与 RBAC 规则将在后续迭代落地
|