# 开发文档（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`（`userType=admin|agent` + `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
- `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 规则将在后续迭代落地