zyh/game_server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
zyh
2025-08-24 15:54:21 +08:00
parent be437a360d
commit c65c03b933
22 changed files with 256 additions and 288 deletions
Download Patch File Download Diff File Expand all files Collapse all files

163
docs/game.sql
View File

@@ -12,89 +12,84 @@ SET NAMES utf8mb4;
SET sql_mode = 'STRICT_ALL_TABLES,NO_ZERO_DATE,NO_ZERO_IN_DATE,ERROR_FOR_DIVISION_BY_ZERO';
-- -----------------------------------------------------------------------------
-- 1) 管理员（平台侧）
-- 1) 统一账户表（管理员/代理商共用）
-- 用 user_type 区分：ADMIN | AGENT
-- -----------------------------------------------------------------------------
CREATE TABLE IF NOT EXISTS admin_user (
id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
username VARCHAR(64) NOT NULL UNIQUE,
password_hash VARBINARY(100) NOT NULL, -- 建议存储 bcrypt/argon2 等
role ENUM('SUPER','ADMIN') NOT NULL DEFAULT 'ADMIN',
CREATE TABLE IF NOT EXISTS user_account (
id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
user_type ENUM('ADMIN','AGENT') NOT NULL,
username VARCHAR(64) NOT NULL UNIQUE, -- 登录名（两类共用）
display_name VARCHAR(100) NULL, -- 展示名（AGENT 可用）
password_hash VARCHAR(120) NOT NULL, -- 建议存储 BCrypt（或临时 PLAIN:<pwd> 便于初始化）
role ENUM('SUPER','ADMIN') NULL, -- 仅 ADMIN 使用
status ENUM('ENABLED','DISABLED') NOT NULL DEFAULT 'ENABLED',
created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
-- -----------------------------------------------------------------------------
-- 2) 代理商（商家）
-- -----------------------------------------------------------------------------
CREATE TABLE IF NOT EXISTS agent (
id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
name VARCHAR(100) NOT NULL,
login_account VARCHAR(64) NOT NULL UNIQUE,
password_hash VARBINARY(100) NOT NULL,
status ENUM('ENABLED','DISABLED') NOT NULL DEFAULT 'ENABLED',
points_balance BIGINT UNSIGNED NOT NULL DEFAULT 0, -- 当前可用点数
points_balance BIGINT UNSIGNED NOT NULL DEFAULT 0, -- 仅 AGENT 使用
created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
CONSTRAINT chk_agent_points_nonneg CHECK (points_balance >= 0)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
CONSTRAINT chk_points_nonneg CHECK (points_balance >= 0)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
-- 默认管理员账号（密码：admin7uqweh12）。
-- 生产环境请尽快替换为 BCrypt 哈希；此处为 PLAIN 方便首次初始化。
INSERT INTO user_account(user_type, username, display_name, password_hash, role, status, points_balance)
VALUES ('ADMIN', 'admin', 'Super Admin', 'PLAIN:admin7uqweh12', 'SUPER', 'ENABLED', 0)
ON DUPLICATE KEY UPDATE username = username;
-- -----------------------------------------------------------------------------
-- 3) 代理商点数流水
-- 记录加点/扣点（生成链接时扣 Times×Quantity×BatchSize）
-- 2) 代理商点数流水
-- -----------------------------------------------------------------------------
CREATE TABLE IF NOT EXISTS agent_points_tx (
id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
agent_id BIGINT UNSIGNED NOT NULL,
type ENUM('ADD','DEDUCT') NOT NULL,
id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
account_id BIGINT UNSIGNED NOT NULL, -- 指向 user_account(AGENT)
type ENUM('ADD','DEDUCT') NOT NULL,
before_points BIGINT UNSIGNED NOT NULL,
delta_points BIGINT SIGNED NOT NULL, -- 可为负/正；与 type 对应
delta_points BIGINT SIGNED NOT NULL, -- 可为正/负；与 type 对应
after_points BIGINT UNSIGNED NOT NULL,
reason ENUM('create_links','manual','refund_no_rollback','other') NOT NULL DEFAULT 'other',
ref_id BIGINT UNSIGNED NULL, -- 可关联到 link_batch.id
operator_id BIGINT UNSIGNED NULL, -- 操作者（管理员）
operator_id BIGINT UNSIGNED NULL, -- 操作者（管理员，指向 user_account）
created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
INDEX idx_agent_points_tx_agent_time (agent_id, created_at),
CONSTRAINT fk_apx_agent FOREIGN KEY (agent_id) REFERENCES agent(id),
CONSTRAINT fk_apx_operator FOREIGN KEY (operator_id) REFERENCES admin_user(id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
INDEX idx_apx_account_time (account_id, created_at),
CONSTRAINT fk_apx_account FOREIGN KEY (account_id) REFERENCES user_account(id),
CONSTRAINT fk_apx_operator FOREIGN KEY (operator_id) REFERENCES user_account(id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
-- -----------------------------------------------------------------------------
-- 4) 链接批次（一次生成 N 个链接，按统一设置扣费）
-- 3) 链接批次（一次生成 N 个链接，按统一设置扣费）
-- -----------------------------------------------------------------------------
CREATE TABLE IF NOT EXISTS link_batch (
id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
agent_id BIGINT UNSIGNED NOT NULL,
quantity INT UNSIGNED NOT NULL, -- 每次奖励数量（如 50）
times INT UNSIGNED NOT NULL, -- 重复执行次数（如 20）
batch_size INT UNSIGNED NOT NULL, -- 本批生成链接数量（如 10）
deduct_points BIGINT UNSIGNED NOT NULL, -- 扣点=quantity*times*batch_size
operator_id BIGINT UNSIGNED NULL, -- 操作者（管理员或代理自己为空）
created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
agent_id BIGINT UNSIGNED NOT NULL, -- 指向 user_account(AGENT)
quantity INT UNSIGNED NOT NULL, -- 每次奖励数量（如 50）
times INT UNSIGNED NOT NULL, -- 重复执行次数（如 20）
batch_size INT UNSIGNED NOT NULL, -- 本批生成链接数量（如 10）
deduct_points BIGINT UNSIGNED NOT NULL, -- 扣点=quantity*times*batch_size
operator_id BIGINT UNSIGNED NULL, -- 操作者（管理员）
created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
INDEX idx_lb_agent_time (agent_id, created_at),
CONSTRAINT chk_lb_quantity_pos CHECK (quantity > 0),
CONSTRAINT chk_lb_times_pos CHECK (times > 0),
CONSTRAINT chk_lb_batch_pos CHECK (batch_size > 0),
CONSTRAINT fk_lb_agent FOREIGN KEY (agent_id) REFERENCES agent(id),
CONSTRAINT fk_lb_operator FOREIGN KEY (operator_id) REFERENCES admin_user(id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
CONSTRAINT fk_lb_agent FOREIGN KEY (agent_id) REFERENCES user_account(id),
CONSTRAINT fk_lb_operator FOREIGN KEY (operator_id) REFERENCES user_account(id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
-- -----------------------------------------------------------------------------
-- 5) 单链接任务（用户访问的“加密链接”对应的实体）
-- 4) 单链接任务（用户访问的“加密链接”对应的实体）
-- -----------------------------------------------------------------------------
CREATE TABLE IF NOT EXISTS link_task (
id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
batch_id BIGINT UNSIGNED NOT NULL,
agent_id BIGINT UNSIGNED NOT NULL,
code_no VARCHAR(32) NOT NULL, -- 后端生成的全局唯一编号
token_hash CHAR(64) NOT NULL, -- 加密token的SHA-256十六进制（用于失效/撤销）
expire_at DATETIME(3) NOT NULL, -- 链接有效期（默认 24h）
id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
batch_id BIGINT UNSIGNED NOT NULL,
agent_id BIGINT UNSIGNED NOT NULL, -- 指向 user_account(AGENT)
code_no VARCHAR(32) NOT NULL, -- 后端生成的全局唯一编号
token_hash CHAR(64) NOT NULL, -- 加密token的SHA-256（用于失效/撤销）
expire_at DATETIME(3) NOT NULL, -- 链接有效期（默认 24h）
status ENUM('NEW','USING','LOGGED_IN','REFUNDED','EXPIRED') NOT NULL DEFAULT 'NEW',
region ENUM('Q','V') NULL, -- 选区；未选择前为 NULL
machine_id VARCHAR(64) NULL, -- 绑定的脚本端机器编号
region ENUM('Q','V') NULL, -- 选区；未选择前为 NULL
machine_id VARCHAR(64) NULL, -- 绑定的脚本端机器编号
login_at DATETIME(3) NULL,
refund_at DATETIME(3) NULL,
revoked_at DATETIME(3) NULL, -- 主动撤销（如需要立即失效）
revoked_at DATETIME(3) NULL, -- 主动撤销（如需要立即失效）
created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
UNIQUE KEY uk_code_no (code_no),
@@ -103,15 +98,15 @@ CREATE TABLE IF NOT EXISTS link_task (
INDEX idx_expire_at (expire_at),
INDEX idx_created_at (created_at),
CONSTRAINT fk_lt_batch FOREIGN KEY (batch_id) REFERENCES link_batch(id),
CONSTRAINT fk_lt_agent FOREIGN KEY (agent_id) REFERENCES agent(id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
CONSTRAINT fk_lt_agent FOREIGN KEY (agent_id) REFERENCES user_account(id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
-- -----------------------------------------------------------------------------
-- 6) 操作日志（审计/可观测性）
-- 5) 操作日志（审计/可观测性）
-- -----------------------------------------------------------------------------
CREATE TABLE IF NOT EXISTS operation_log (
id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
actor_type ENUM('admin','agent','system','user') NOT NULL,
id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
actor_type ENUM('admin','agent','system','user') NOT NULL,
actor_id BIGINT UNSIGNED NULL, -- 不强制外键，避免多态复杂度
code_no VARCHAR(32) NULL,
op VARCHAR(64) NOT NULL, -- 如：create_links / refund / select_region / create_qr / poll_login / release_machine
@@ -121,54 +116,18 @@ CREATE TABLE IF NOT EXISTS operation_log (
created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
INDEX idx_log_code_time (code_no, created_at),
INDEX idx_log_time (created_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
-- -----------------------------------------------------------------------------
-- 7) 公告
-- 6) 公告
-- -----------------------------------------------------------------------------
CREATE TABLE IF NOT EXISTS announcement (
id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
title VARCHAR(100) NOT NULL,
content TEXT NOT NULL, -- 简单文本
id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
title VARCHAR(100) NOT NULL,
content TEXT NOT NULL, -- 富文本
enabled TINYINT(1) NOT NULL DEFAULT 1,
jump_url VARCHAR(255) NULL,
created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
INDEX idx_announce_enabled (enabled)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
-- -----------------------------------------------------------------------------
-- 8) 平台级配置（商家不可配）
-- -----------------------------------------------------------------------------
CREATE TABLE IF NOT EXISTS sys_config (
cfg_key VARCHAR(64) PRIMARY KEY,
cfg_value TEXT NOT NULL,
description VARCHAR(255) NULL,
updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
-- 预置关键配置（可按需改值）
INSERT INTO sys_config (cfg_key, cfg_value, description) VALUES
('LINK_EXPIRE_HOURS', '24', '链接有效期（小时）'),
('QR_EXPIRE_SECONDS', '60', '二维码过期秒数（脚本端未返回TTL时使用）'),
('REFRESH_WAIT_SECONDS', '10', '刷新后强制等待秒数（商家不可配置）'),
('MACHINE_COOLDOWN_MINUTES','10', '同一机器复用冷却时长（分钟）'),
('DEFAULT_BATCH_SIZE', '10', '批量生成默认数量'),
('SECOND_SCREEN_URL_TEMPLATE','https://你的域名/{codeNo}','二界面URL模板（包含编号占位）')
ON DUPLICATE KEY UPDATE
cfg_value = VALUES(cfg_value),
description = VALUES(description);
-- -----------------------------------------------------------------------------
-- 推荐的视图 / 物化统计可按需追加（此处略）
-- -----------------------------------------------------------------------------
-- =============================================================================
-- 说明：
-- 1) 生成链接时，请在业务层完成：
-- - 计算扣点 = quantity * times * batch_size
-- - 扣减 agent.points_balance，并写入 agent_points_tx
-- - 写入 link_batch 及其下的若干 link_task（生成 code_no / token 及 token_hash、expire_at）
-- 2) 用户端所有页面均以“加密链接 token”为入口，通过 token_hash 可实现失效/撤销。
-- 3) operation_log.detail 建议仅存必要字段并脱敏；日志保留 90 天可通过定时归档或分区处理。
-- =============================================================================

122
docs/开发文档.md Normal file
View File

@@ -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 规则将在后续迭代落地