game_server/docs/开发文档.md

开发文档（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：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 基础闭环
  • 统一返回体与错误码
  • 登录与 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 规则将在后续迭代落地