Refactor authentication logic to unify user account handling and update database schema for user accounts

docs/开发文档.md

@@ -0,0 +1,122 @@
+# 开发文档（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 规则将在后续迭代落地
+