# TDD-08 GM与运营后台设计

> 文档类型：技术设计文档（Technical Design Document）
> 版本：1.0
> 日期：2026-07-02
> 关联文档：TDD-04《数据库表结构设计》、TDD-05《API接口设计》、TDD-07《反作弊与安全设计》、PRD-03《热更新与活动系统需求文档》、GDD-06《经济系统设计》、GDD-21《数值平衡与联调参数总表》

---

## 1. 文档信息

| 项目 | 说明 |
|------|------|
| 目标 | 为《洪荒大陆》挂机手游定义 GM/运营后台的技术设计方案，覆盖 GM 指令系统、经济监控仪表盘、活动配置后台、客服工单系统、数据报表、权限管理六大模块。 |
| 读者 | 运营策划、客服、后端开发、运维 |
| 技术栈 | 前端 Vue3 + Element Plus；后端 Gin（独立服务，不走 Nakama）；数据源 PostgreSQL 16 / Valkey / Nacos 2.x / Prometheus |
| 核心约束 | 无任务系统、无赛季重置、概率/机遇驱动；GM 操作不得破坏经济平衡；所有 GM 操作必须审计 |

---

## 2. 系统总览

### 2.1 架构分层

```
┌─────────────────────────────────────────────────────────────────┐
│                    GM/运营后台（Vue3 SPA）                        │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐│
│  │ GM指令台  │ │ 经济监控  │ │ 活动配置  │ │ 客服工单  │ │数据报表││
│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └───┬────┘│
└───────┼────────────┼────────────┼────────────┼────────────┼─────┘
        │            │            │            │            │
┌───────┼────────────┼────────────┼────────────┼────────────┼─────┐
│       ▼            ▼            ▼            ▼            ▼     │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │           GM API 网关（Gin，独立端口 :8090）              │    │
│  │  - JWT 认证 + RBAC 权限校验                               │    │
│  │  - 操作审计中间件                                         │    │
│  │  - 敏感操作二次确认拦截                                    │    │
│  └─────────────────────────────────────────────────────────┘    │
│       │            │            │            │            │     │
│  ┌────▼────┐ ┌─────▼────┐ ┌────▼────┐ ┌─────▼────┐ ┌─────▼───┐│
│  │Nakama   │ │Prometheus│ │  Nacos  │ │PostgreSQL│ │  Valkey ││
│  │Go Plugin│ │ + Grafana│ │  2.x    │ │   16     │ │         ││
│  └─────────┘ └──────────┘ └─────────┘ └──────────┘ └─────────┘│
│                        服务端集群                                │
└─────────────────────────────────────────────────────────────────┘
```

### 2.2 设计原则

| 原则 | 说明 |
|------|------|
| **审计优先** | 所有 GM 操作写入 `gm_audit_logs`，不可删除、不可篡改 |
| **最小权限** | GM 角色分级，操作权限逐项授权，非必要不给写权限 |
| **经济安全** | GM 发放/回收物品、调整货币必须写入 `economy_audit_logs`（TDD-04 §5.4），纳入经济监控 |
| **服务端权威** | GM 指令最终由 Nakama Go Plugin 或 Gin 后端执行，前端仅提交意图（TDD-07 §2.1） |
| **配置热更** | 活动/数值参数通过 Nacos 热更，不走 GM 直接改库（PRD-03 §3.2） |
| **双人确认** | 敏感操作（批量发放、经济调整、配置发布）需双人审批（PRD-03 §3.2） |

### 2.3 数据库新增表

#### gm_users

GM 后台用户表。

| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | uuid | PK | |
| username | varchar(64) | UQ | 登录名 |
| display_name | varchar(64) | | 显示名 |
| password_hash | varchar(256) | | bcrypt 哈希 |
| role | varchar(32) | IX | super_gm / gm / cs / observer |
| permissions | jsonb | | 细粒度权限列表 |
| is_active | boolean | | 是否启用 |
| last_login_at | timestamptz | | |
| created_at | timestamptz | | |
| created_by | uuid | FK → gm_users.id | |

#### gm_audit_logs

GM 操作审计日志（按 `created_at` 月分区，保留 24 个月）。

| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | bigint | PK | 雪花 ID |
| operator_id | uuid | FK → gm_users.id, IX | 操作人 |
| operator_role | varchar(32) | | 操作时角色 |
| action | varchar(64) | IX | 操作类型枚举（见 §3.8） |
| target_type | varchar(32) | | player / character / guild / item / config / event |
| target_id | varchar(128) | IX | 目标 ID |
| params | jsonb | | 请求参数快照 |
| before_snapshot | jsonb | | 操作前状态快照 |
| after_snapshot | jsonb | | 操作后状态快照 |
| approval_id | uuid | nullable | 关联审批单（敏感操作） |
| ip_address | inet | | 操作者 IP |
| user_agent | varchar(256) | | |
| result | varchar(16) | | success / failed / rejected |
| error_message | text | | 失败原因 |
| created_at | timestamptz | IX | |

#### gm_tickets

客服工单表。

| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | uuid | PK | |
| ticket_no | varchar(32) | UQ | 工单编号（如 T20260702-0001） |
| category | varchar(32) | IX | bug / econ_dispute / account / report / suggestion |
| sub_category | varchar(32) | | 细分类别 |
| title | varchar(256) | | 标题 |
| description | text | | 详情 |
| reporter_player_id | uuid | FK → players.id, IX | 提交玩家 |
| reporter_character_id | uuid | FK → characters.id | 关联角色 |
| assigned_to | uuid | FK → gm_users.id, nullable, IX | 分配客服 |
| priority | smallint | | 1=紧急 2=高 3=中 4=低 |
| status | varchar(16) | IX | open / assigned / processing / resolved / closed |
| resolution | text | | 处理结果 |
| related_battle_id | uuid | nullable | 关联战报（BUG/纠纷） |
| related_order_id | uuid | nullable | 关联交易订单 |
| attachments | jsonb | | 截图/附件 URL 列表 |
| created_at | timestamptz | IX | |
| assigned_at | timestamptz | | |
| resolved_at | timestamptz | | |
| closed_at | timestamptz | | |

#### gm_ticket_messages

工单对话记录。

| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | bigint | PK | |
| ticket_id | uuid | FK → gm_tickets.id, IX | |
| sender_type | varchar(16) | | player / gm / system |
| sender_id | varchar(128) | | 发送者 ID |
| message | text | | 内容 |
| attachments | jsonb | | 附件 |
| created_at | timestamptz | | |

#### gm_approvals

敏感操作审批单。

| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | uuid | PK | |
| action | varchar(64) | IX | 审批的操作类型 |
| target_type | varchar(32) | | |
| target_id | varchar(128) | | |
| params | jsonb | | 操作参数 |
| requested_by | uuid | FK → gm_users.id | 申请人 |
| approved_by | uuid | FK → gm_users.id, nullable | 审批人 |
| status | varchar(16) | IX | pending / approved / rejected / expired |
| reject_reason | text | | 拒绝原因 |
| created_at | timestamptz | | |
| decided_at | timestamptz | | |
| expires_at | timestamptz | | 超时自动过期（默认 24h） |

---

## 3. GM 指令系统

### 3.1 玩家管理

#### 3.1.1 玩家查询

| 项目 | 说明 |
|------|------|
| 接口 | `GET /api/gm/v1/players?q={keyword}` |
| 权限 | `player.read`（所有 GM 角色） |
| 查询维度 | 角色名 / 角色 ID / 玩家 ID / 设备 ID / IP 地址 |
| 返回字段 | 玩家基础信息、角色列表、当前在线状态、封禁状态、最后登录时间、所在世界层级、境界、货币余额概览 |

#### 3.1.2 封禁 / 解封

| 项目 | 说明 |
|------|------|
| 接口 | `POST /api/gm/v1/players/{player_id}/ban` / `POST .../unban` |
| 权限 | `player.ban`（GM 以上） |
| 参数 | `ban_type`（temporary / permanent）、`duration_hours`、`reason`、`evidence` |
| 执行逻辑 | 更新 `players.status = 'banned'`；强制断开 WebSocket 连接；Valkey 写入 ban 标记，登录时拦截 |
| 审计 | 写入 `gm_audit_logs`，action = `player.ban` / `player.unban` |

#### 3.1.3 禁言

| 项目 | 说明 |
|------|------|
| 接口 | `POST /api/gm/v1/characters/{character_id}/mute` |
| 权限 | `player.mute`（CS 以上） |
| 参数 | `duration_hours`、`reason`、`channels`（world / region / guild / private） |
| 执行逻辑 | Valkey 写入 `mute:{character_id}` 哈希，包含到期时间和频道列表；聊天服务发送前校验 |

#### 3.1.4 强制下线

| 项目 | 说明 |
|------|------|
| 接口 | `POST /api/gm/v1/characters/{character_id}/kick` |
| 权限 | `player.kick`（GM 以上） |
| 执行逻辑 | Nakama 断开指定 session；客户端重连时检测 kick 标记并提示原因 |

### 3.2 物品管理

#### 3.2.1 发放物品

| 项目 | 说明 |
|------|------|
| 接口 | `POST /api/gm/v1/characters/{character_id}/items/grant` |
| 权限 | `item.grant`（GM 以上，需审批） |
| 参数 | `item_id`、`quantity`、`reason`、`source_tag`（固定 `GM_GRANT`） |
| 执行逻辑 | 调用 Nakama Go Plugin 的发放接口；写入 `inventories`，`source_tag = 'GM_GRANT'`；写入 `economy_audit_logs`，`reason_code = 'admin_compensation'` |
| 审批 | 单次发放价值超过阈值（由 Nacos 配置 `gm.item_grant.approval_threshold` 控制）需双人审批 |

#### 3.2.2 回收物品

| 项目 | 说明 |
|------|------|
| 接口 | `POST /api/gm/v1/characters/{character_id}/items/revoke` |
| 权限 | `item.revoke`（GM 以上） |
| 参数 | `inventory_id`、`quantity`、`reason` |
| 执行逻辑 | 从 `inventories` 扣除物品；写入 `economy_audit_logs`，`reason_code = 'admin_revoke'` |

#### 3.2.3 物品日志查询

| 项目 | 说明 |
|------|------|
| 接口 | `GET /api/gm/v1/characters/{character_id}/items/logs` |
| 权限 | `item.read`（CS 以上） |
| 查询维度 | 时间范围、物品 ID、来源类型（GM / 战斗掉落 / 交易 / 拍卖 / 弟子） |
| 数据源 | `economy_audit_logs` + `inventories` 联查 |

### 3.3 角色管理

#### 3.3.1 属性修改

| 项目 | 说明 |
|------|------|
| 接口 | `PUT /api/gm/v1/characters/{character_id}/stats` |
| 权限 | `character.modify`（超级 GM） |
| 参数 | `base_stats`（JSON，可部分更新）、`reason` |
| 执行逻辑 | 更新 `characters.base_stats`；同步更新 `characters.battle_stats`；写入 `gm_audit_logs`，保留 before/after 快照 |
| 审批 | 必须双人审批（`gm.approvals` 表） |

#### 3.3.2 境界调整

| 项目 | 说明 |
|------|------|
| 接口 | `POST /api/gm/v1/characters/{character_id}/realm/adjust` |
| 权限 | `character.realm`（超级 GM） |
| 参数 | `target_realm_tier`、`target_minor_realm`、`reason` |
| 执行逻辑 | 更新 `characters.realm_tier` / `minor_realm` / `world_tier`；写入 `character_realms` 和 `realm_breakthrough_records`（标记来源为 GM） |
| 审批 | 必须双人审批 |

#### 3.3.3 传送

| 项目 | 说明 |
|------|------|
| 接口 | `POST /api/gm/v1/characters/{character_id}/teleport` |
| 权限 | `character.teleport`（GM 以上） |
| 参数 | `target_region_id` 或 `target_world_tier` |
| 执行逻辑 | 更新 `characters.world_tier`；写入 `gm_audit_logs` |

#### 3.3.4 复活

| 项目 | 说明 |
|------|------|
| 接口 | `POST /api/gm/v1/characters/{character_id}/resurrect` |
| 权限 | `character.resurrect`（GM 以上） |
| 参数 | `restore_realm`（是否恢复掉境）、`reason` |
| 执行逻辑 | 更新 `characters.status = 'active'`；根据参数决定是否恢复境界；写入 `gm_audit_logs` + `economy_audit_logs`（若涉及经济恢复） |

### 3.4 经济管理

#### 3.4.1 货币调整

| 项目 | 说明 |
|------|------|
| 接口 | `POST /api/gm/v1/characters/{character_id}/currencies/adjust` |
| 权限 | `economy.adjust`（超级 GM） |
| 参数 | `currency_code`、`amount`（正数发放/负数扣除）、`reason` |
| 执行逻辑 | 原子更新 `currency_balances`；写入 `economy_audit_logs`，`reason_code = 'admin_compensation'` 或 `'admin_revoke'` |
| 审批 | 金额绝对值超过阈值需双人审批 |

#### 3.4.2 交易回滚

| 项目 | 说明 |
|------|------|
| 接口 | `POST /api/gm/v1/trades/{trade_id}/rollback` |
| 权限 | `economy.rollback`（超级 GM） |
| 参数 | `reason` |
| 执行逻辑 | 回滚 `market_orders` / `auctions` 成交；恢复双方物品与货币；写入 `economy_audit_logs`，`reason_code = 'admin_rollback'` |
| 审批 | 必须双人审批 |
| 约束 | 仅支持 72 小时内的交易回滚 |

#### 3.4.3 经济快照

| 项目 | 说明 |
|------|------|
| 接口 | `POST /api/gm/v1/economy/snapshot` |
| 权限 | `economy.snapshot`（GM 以上） |
| 执行逻辑 | 按世界层级/种族/货币类型汇总全服货币持有量、产出/消耗速率、基尼系数；结果存储到 `economy_snapshots` 表（新增），供仪表盘展示 |

### 3.5 世界管理

#### 3.5.1 事件触发

| 项目 | 说明 |
|------|------|
| 接口 | `POST /api/gm/v1/world/events/trigger` |
| 权限 | `world.event`（GM 以上） |
| 参数 | `event_template_id`、`world_tier`、`region_id`（可选）、`duration_minutes` |
| 执行逻辑 | 调用世界事件调度器，立即生成指定事件实例并广播（PRD-03 §4.2） |

#### 3.5.2 Boss 刷新

| 项目 | 说明 |
|------|------|
| 接口 | `POST /api/gm/v1/world/boss/spawn` |
| 权限 | `world.boss`（GM 以上） |
| 参数 | `boss_template_id`、`region_id`、`difficulty_modifier` |
| 执行逻辑 | 在指定区域生成 Boss 实例；区域广播通知 |

#### 3.5.3 活动开关

| 项目 | 说明 |
|------|------|
| 接口 | `POST /api/gm/v1/world/events/{event_id}/toggle` |
| 权限 | `world.event`（GM 以上） |
| 参数 | `enabled`（true/false）、`reason` |
| 执行逻辑 | 更新 Nacos 配置中的活动开关；服务端监听变更后即时生效（PRD-03 §3.2） |
| 审批 | 关闭全服活动需双人审批 |

### 3.6 全服公告

| 项目 | 说明 |
|------|------|
| 接口 | `POST /api/gm/v1/broadcast` |
| 权限 | `broadcast.send`（GM 以上） |
| 参数 | `content`、`channels`（world / region / all）、`duration_minutes`、`priority`（normal / urgent） |
| 执行逻辑 | 通过 Nakama 实时推送写入目标频道；紧急公告全服弹窗 |

### 3.7 GM 指令快捷操作台

运营后台提供命令行风格的快捷操作台，支持以下 GM 指令语法：

```
/query player <keyword>                    # 查询玩家
/ban <player_id> <duration> <reason>       # 封禁
/unban <player_id>                         # 解封
/mute <char_id> <duration> <reason>        # 禁言
/kick <char_id>                            # 踢下线
/grant <char_id> <item_id> <qty> <reason>  # 发放物品
/revoke <char_id> <inv_id> <qty> <reason>  # 回收物品
/adjust <char_id> <currency> <amount>      # 调整货币
/teleport <char_id> <region_id>            # 传送
/resurrect <char_id> [restore_realm]       # 复活
/trigger <event_id> [region_id]            # 触发事件
/broadcast <channels> <message>            # 全服公告
/snapshot                                  # 经济快照
```

所有指令执行前在操作台展示预览（影响范围、目标信息），确认后执行。

### 3.8 操作审计

GM 操作类型枚举（`gm_audit_logs.action`）：

| 分类 | action 值 | 说明 |
|------|-----------|------|
| 玩家管理 | `player.query` / `player.ban` / `player.unban` / `player.mute` / `player.kick` | |
| 物品管理 | `item.grant` / `item.revoke` | |
| 角色管理 | `character.modify_stats` / `character.adjust_realm` / `character.teleport` / `character.resurrect` | |
| 经济管理 | `economy.adjust_currency` / `economy.rollback_trade` / `economy.snapshot` | |
| 世界管理 | `world.trigger_event` / `world.spawn_boss` / `world.toggle_event` | |
| 公告 | `broadcast.send` | |
| 配置 | `config.publish` / `config.rollback` / `config.approve` | |
| 审批 | `approval.create` / `approval.approve` / `approval.reject` | |
| 工单 | `ticket.create` / `ticket.assign` / `ticket.resolve` / `ticket.close` | |

---

## 4. 经济监控仪表盘

### 4.1 实时指标

仪表盘从以下数据源采集实时指标：

| 指标 | 数据源 | 刷新频率 | 说明 |
|------|--------|---------|------|
| 各货币日净产出/消耗比 | `economy_audit_logs` 按 `flow_type` + `currency_code` 聚合 | 5 分钟 | `faucet_sum / sink_sum`，健康区间 0.8~1.2（GDD-06 §14.1） |
| 交易行均价 | `market_orders` 按 `item_id` + `status='sold'` 聚合 | 15 分钟 | 最近 24h 成交均价，按世界层级分组 |
| 死亡修复 sink / 总 faucet | `economy_audit_logs` 中 `reason_code = 'death_penalty'` | 1 小时 | 验证高惩罚经济回收是否生效（GDD-06 ✅5） |
| 鸿蒙紫气净增发/充值额 | `economy_audit_logs` 中 `currency_code` 含紫气相关 | 1 小时 | 监控偷渡补贴（GDD-06 ✅C02） |
| 在线人数 | Valkey `online:{world_tier}` 计数器 | 实时 | 按世界层级分组 |
| DAU / 新增 | `players.last_login_at` + `players.created_at` | 每日 08:00 结算 | |

### 4.2 异常告警

| 告警项 | 检测逻辑 | 阈值（Nacos 可配） | 告警级别 |
|--------|---------|-------------------|---------|
| 产出速率异常 | 单货币 faucet 日产量 > 过去 7 日均值 × 系数 | ×2.0 | P1 |
| 价格操纵 | 单物品 1h 内成交价偏离 24h 均价 | ±50% | P2 |
| 刷金检测 | 单角色 1h 内 faucet 累计 > 阈值 | 按世界层级配置 | P1 |
| 异常交易 | 单角色 1h 内 market_orders 成交笔数 > 阈值 | 50 笔 | P2 |
| 垄断检测 | 单角色持有某物品占全服该物品活跃挂单量 | >30% | P3 |
| 经济健康度下降 | 综合评分低于阈值 | <60 分 | P1 |

告警推送渠道：后台弹窗 + 钉钉/飞书 Webhook + 短信（P1 级别）。

### 4.3 经济健康度评分

综合评分模型（满分 100）：

| 维度 | 权重 | 计算方式 |
|------|------|---------|
| 货币通胀率 | 30% | 各货币 faucet/sink 比偏离 1.0 的加权平均；偏离越大扣分越多 |
| 交易活跃度 | 20% | 24h 交易行成交量 / 7 日均值；过低或过高扣分 |
| 货币基尼系数 | 20% | 各层级货币持有分布的基尼系数；>0.7 扣分 |
| 死亡修复回收率 | 15% | death_penalty sink / 总 faucet；低于 10% 扣分 |
| 紫气渗透率 | 15% | 紫气兑换产出 / 总 faucet；超过 5% 扣分 |

评分等级：>=80 健康（绿）/ 60~79 关注（黄）/ <60 告警（红）。

### 4.4 趋势图表

| 图表 | 维度 | 时间范围 |
|------|------|---------|
| 货币供需趋势 | 各货币 faucet/sink 每日净额折线图 | 最近 7/14/30 天 |
| 交易行热力图 | 物品分类 × 世界层级的成交量热力图 | 最近 7 天 |
| 死亡修复趋势 | 死亡惩罚 sink 占比趋势 | 最近 30 天 |
| 紫气流向 | 充值 → 兑换 → 消耗漏斗 | 最近 30 天 |
| 种族货币分布 | 各种族独属货币持有量饼图 | 实时快照 |

支持导出 CSV / Excel 报表。

---

## 5. 活动配置后台

### 5.1 Nacos 配置可视化编辑

| 项目 | 说明 |
|------|------|
| 接口 | `GET /api/gm/v1/configs` / `PUT /api/gm/v1/configs` |
| 权限 | `config.read` / `config.write` |
| 功能 | 以树形结构展示 Nacos 中的配置项（PRD-03 §3.1 四大分类：economy / combat / event / map）；支持 JSON 编辑器在线修改；修改前展示 diff 对比 |
| 校验 | 提交时经 JSON Schema + 数值范围校验（PRD-03 §3.4）；非法值拒绝提交 |
| 审批 | 发布到 Nacos 需双人审批（PRD-03 §3.2）；审批通过后调用 Nacos Open API 发布 |
| 回滚 | 展示历史版本列表，支持一键回滚到指定版本（PRD-03 §3.4） |

配置分类与关键参数映射：

| 分类 | 示例配置键 | 来源 |
|------|-----------|------|
| economy | `economy.faucet.afk.output_rate`、`economy.tax.trade_rate`、`economy.sink.repair.cost_rate` | GDD-06 §14.3 |
| combat | `combat.atb.tick_ms`、`combat.damage.formula.*`、`combat.cap.crit` | GDD-03 / GDD-21 |
| event | `event.world.trigger_interval`、`event.world.weights.*`、`event.player_initiated.costs.*` | GDD-18 / GDD-22 |
| map | `map.cross_layer.cost_rate`、`map.降维护佑.damage_cap`、`map.realm_tier.pvp_rule` | GDD-08 / PRD-02 |

### 5.2 活动日历管理

| 项目 | 说明 |
|------|------|
| 接口 | `GET /api/gm/v1/events/calendar` / `POST ...` / `PUT .../{id}` |
| 权限 | `event.manage`（GM 以上） |
| 功能 | 接入 PRD-03 §5.3 活动日历服务；以日历视图展示固定副本排程、世界事件预告、玩家发起事件、破界分红 |
| 操作 | 新增/编辑/删除活动排程；调整活动权重与参数；设置活动预告文案 |

活动日历条目结构：

| 字段 | 说明 |
|------|------|
| event_id | 活动模板 ID |
| event_type | fixed_dungeon / world_event / player_event / dividend |
| title | 活动标题 |
| start_at / end_at | 生效时间范围 |
| world_tiers | 适用世界层级 |
| params | 活动参数（掉落倍率、参与人数上限等） |
| status | scheduled / active / ended / cancelled |

### 5.3 灰度发布控制面板

| 项目 | 说明 |
|------|------|
| 接口 | `POST /api/gm/v1/gray-release` / `PUT .../{id}` |
| 权限 | `config.gray`（GM 以上） |
| 功能 | 管理 Nacos 灰度配置（PRD-03 §2.4）；支持按百分比、分组、渠道、地区多维度灰度 |

灰度计划管理：

| 操作 | 说明 |
|------|------|
| 创建灰度计划 | 指定目标版本、灰度维度（百分比/分组/渠道/地区）、监控阈值 |
| 灰度推进 | 5% → 20% → 50% → 100%，每步需手动确认 |
| 自动暂停 | 崩溃率 > 5%、热更失败率 > 5%、启动失败率 > 3% 时自动暂停（PRD-03 §2.4） |
| 回滚 | 一键回滚到上一稳定版本 |

### 5.4 配置变更审批流

审批流程（PRD-03 §3.2）：

```
运营A编辑配置 → 提交审批单 → 审批队列展示
    → 运营B（或超级GM）审核 diff → 批准/拒绝
    → 批准后自动发布到 Nacos
    → 写入 gm_audit_logs + dynamic_configs（TDD-04 §5.13）
    → 推送配置版本号到在线客户端
```

| 项目 | 说明 |
|------|------|
| 审批超时 | 24 小时内未审批自动过期，需重新提交 |
| 紧急通道 | 超级 GM 可跳过审批直接发布（需二次确认 + 审计日志标记 `emergency`） |
| 审批队列 | 按优先级排序：P0 经济参数 > P1 战斗参数 > P2 活动配置 > P3 地图配置 |

---

## 6. 客服工单系统

### 6.1 工单分类

| 分类 | sub_category 示例 | 优先级 | 说明 |
|------|-------------------|--------|------|
| BUG 反馈 | 战斗异常 / 界面错误 / 功能失效 / 数据丢失 | 2~3 | 关联战报 ID / 截图 |
| 经济纠纷 | 交易异常 / 物品丢失 / 货币异常 / 拍卖纠纷 | 2 | 关联交易订单 / economy_audit_logs |
| 账号问题 | 封号申诉 / 找回账号 / 角色异常 / 被盗 | 1~2 | |
| 举报 | 外挂 / 刷金 / 恶意 PK / 辱骂 / 违规昵称 | 2~3 | 关联被举报角色 ID |
| 建议 | 玩法建议 / 平衡建议 / UI 建议 | 4 | |

### 6.2 工单流转

状态机：

```
open → assigned → processing → resolved → closed
  │                      │
  │                      └──→ reopened（玩家不满意）→ processing
  │
  └──→ closed（玩家撤回）
```

| 节点 | 触发 | 说明 |
|------|------|------|
| 创建 | 玩家提交 / GM 代建 | 自动生成 ticket_no；按分类自动分配队列 |
| 分配 | 手动 / 自动轮询 | 按分类分配给对应客服；支持负载均衡 |
| 处理 | 客服操作 | 客服可查看玩家角色信息、战报、交易记录、审计日志；可在工单内直接执行 GM 指令（受限权限） |
| 解决 | 客服标记 | 填写 resolution；若涉及补偿则调用物品/货币发放接口 |
| 关闭 | 玩家确认 / 超时自动关闭 | 解决后 7 天无回复自动关闭 |
| 重开 | 玩家不满意 | 重开次数上限 3 次 |

### 6.3 客服专用操作

客服角色可执行的受限 GM 指令：

| 指令 | 权限 | 说明 |
|------|------|------|
| 查询玩家信息 | `player.read` | 包含角色详情、背包、战报、交易记录 |
| 发放补偿物品 | `item.grant`（受限） | 仅限预设补偿模板，单次价值不超阈值 |
| 解封 | `player.unban` | 仅限封禁到期前 24h 内的操作 |
| 查看经济日志 | `economy.read` | 只读，不可修改 |

### 6.4 玩家自助查询

玩家在游戏内可自助查询以下信息，减少工单量：

| 查询项 | 说明 | 接口 |
|--------|------|------|
| 封号原因 | 展示封禁类型、原因、到期时间 | `GET /api/v1/players/me/ban-info` |
| 交易记录 | 最近 30 天交易行/拍卖成交记录 | `GET /api/v1/characters/{id}/trades` |
| 战报回看 | 最近 100 场战报列表与详情 | `GET /api/v1/combats?character_id={id}` |
| 经济流水 | 最近 7 天货币收支明细 | `GET /api/v1/characters/{id}/economy-logs` |
| 工单状态 | 我的工单列表与进度 | `GET /api/v1/tickets/me` |

---

## 7. 数据报表

### 7.1 核心指标

| 指标 | 计算方式 | 刷新频率 |
|------|---------|---------|
| DAU | 当日 `last_online_at` 去重 `player_id` 数 | 每日 08:00 |
| 次日留存 | D0 新增玩家中 D1 有登录的比例 | 每日 |
| 7 日留存 | D0 新增玩家中 D7 有登录的比例 | 每日 |
| 30 日留存 | D0 新增玩家中 D30 有登录的比例 | 每日 |
| LTV | 累计充值额 / 累计新增玩家数 | 每日 |
| ARPU | 累计充值额 / DAU | 每日 |
| 付费率 | 有充值记录的玩家数 / DAU | 每日 |
| 平均在线时长 | 会话时长均值 | 每日 |

### 7.2 系统参与度

| 系统 | 指标 | 数据源 |
|------|------|--------|
| 副本 | 各副本进入人次 / 完成率 / 平均通关时间 | `instance_runs` |
| 拍卖 | 活跃拍卖数 / 成交率 / 均价 | `auctions` + `auction_bids` |
| 佣兵 | 发布委托数 / 接取率 / 完成率 | `contracts` |
| 社交 | 新增关系数 / 活跃关系数 / 帮派创建数 | `social_relations` + `guilds` |
| 游历 | 游历时长分布 / 事件触发率 / 遭遇完成率 | 离线结算日志 |
| 渡劫 | 渡劫人次 / 成功率 / 境界分布 | `tribulation_records` |
| 交易行 | 活跃挂单数 / 成交率 / 税收额 | `market_orders` |
| 天机阁 | 情报发布数 / 购买率 / 平均价格 | `intelligence_orders` |

### 7.3 种族 / 职业 / 境界分布

| 维度 | 展示方式 | 数据源 |
|------|---------|--------|
| 种族分布 | 饼图，按创建数 / 活跃数 | `characters.race_id` |
| 职业分布 | 饼图 | `characters` 关联职业数据 |
| 境界分布 | 柱状图，按 `realm_tier` 分组 | `characters.realm_tier` |
| 世界层级分布 | 柱状图 | `characters.world_tier` |
| 种族×境界交叉 | 热力图 | `characters` 聚合 |

### 7.4 付费转化漏斗

```
新增注册 → 首次登录 → 完成新手引导 → 首次充值 → 复充 → 大R（累计>阈值）
```

| 阶段 | 转化率计算 |
|------|-----------|
| 注册→登录 | 登录玩家数 / 注册玩家数 |
| 登录→新手完成 | 完成引导数 / 登录数 |
| 新手→首充 | 首充玩家数 / 完成引导数 |
| 首充→复充 | 复充玩家数 / 首充玩家数 |
| 复充→大R | 大R 数 / 复充数 |

### 7.5 报表导出

| 格式 | 说明 |
|------|------|
| CSV | 原始数据导出 |
| Excel | 含图表的格式化报表 |
| PDF | 定期运营报告模板 |
| API | `GET /api/gm/v1/reports/{report_type}?date_range=...`，供外部 BI 工具对接 |

---

## 8. 权限管理

### 8.1 GM 角色分级

| 角色 | 角色标识 | 说明 |
|------|---------|------|
| 超级 GM | `super_gm` | 全部权限；可审批敏感操作；可跳过审批紧急发布 |
| 普通 GM | `gm` | 玩家管理/物品管理/世界管理/公告；敏感操作需审批 |
| 客服 | `cs` | 工单管理；受限物品发放；玩家信息查询 |
| 角色观察员 | `observer` | 只读权限；查看仪表盘/报表/日志；不可执行任何写操作 |

### 8.2 权限矩阵

| 权限项 | super_gm | gm | cs | observer |
|--------|----------|----|----|----------|
| `player.read` | Y | Y | Y | Y |
| `player.ban` | Y | Y | N | N |
| `player.unban` | Y | Y | Y | N |
| `player.mute` | Y | Y | Y | N |
| `player.kick` | Y | Y | N | N |
| `item.read` | Y | Y | Y | Y |
| `item.grant` | Y | Y（审批） | Y（受限模板） | N |
| `item.revoke` | Y | Y（审批） | N | N |
| `character.modify` | Y | N | N | N |
| `character.realm` | Y | N | N | N |
| `character.teleport` | Y | Y | N | N |
| `character.resurrect` | Y | Y | N | N |
| `economy.read` | Y | Y | Y | Y |
| `economy.adjust` | Y | N | N | N |
| `economy.rollback` | Y | N | N | N |
| `economy.snapshot` | Y | Y | N | Y |
| `world.event` | Y | Y | N | N |
| `world.boss` | Y | Y | N | N |
| `broadcast.send` | Y | Y | N | N |
| `config.read` | Y | Y | N | Y |
| `config.write` | Y | Y（审批） | N | N |
| `config.gray` | Y | Y | N | N |
| `ticket.read` | Y | Y | Y | Y |
| `ticket.manage` | Y | Y | Y | N |
| `report.read` | Y | Y | Y | Y |

### 8.3 敏感操作二次确认

以下操作执行前必须弹出二次确认对话框，要求输入确认文本（如输入 "CONFIRM"）：

| 操作 | 确认内容 |
|------|---------|
| 永久封禁 | 展示封禁原因、影响范围，输入 "CONFIRM_BAN" |
| 批量发放（>10 件） | 展示物品清单、总价值，输入 "CONFIRM_GRANT" |
| 货币调整（>阈值） | 展示金额、目标角色，输入 "CONFIRM_ADJUST" |
| 交易回滚 | 展示交易详情、影响双方，输入 "CONFIRM_ROLLBACK" |
| 境界调整 | 展示前后境界、影响，输入 "CONFIRM_REALM" |
| 配置紧急发布 | 展示变更 diff，输入 "CONFIRM_PUBLISH" |

### 8.4 操作审计日志

所有 GM 操作（含查询）均写入 `gm_audit_logs`（§2.3），审计日志：

- 不可删除、不可修改（数据库层面禁止 DELETE/UPDATE）
- 按月分区，保留 24 个月
- 支持按操作人、操作类型、目标、时间范围检索
- 超级 GM 可导出审计日志用于合规审查

---

## 9. API 接口清单

### 9.1 认证

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/gm/v1/auth/login` | POST | GM 用户登录，返回 JWT |
| `/api/gm/v1/auth/refresh` | POST | 刷新 JWT |
| `/api/gm/v1/auth/logout` | POST | 登出 |

JWT 有效期 4 小时，refresh token 有效期 7 天。JWT payload 包含 `user_id`、`role`、`permissions`。

### 9.2 接口总览

| 模块 | 接口数 | 前缀 |
|------|--------|------|
| 玩家管理 | 5 | `/api/gm/v1/players` |
| 物品管理 | 3 | `/api/gm/v1/characters/{id}/items` |
| 角色管理 | 4 | `/api/gm/v1/characters/{id}` |
| 经济管理 | 3 | `/api/gm/v1/economy` + `/api/gm/v1/trades` |
| 世界管理 | 3 | `/api/gm/v1/world` |
| 公告 | 1 | `/api/gm/v1/broadcast` |
| 配置管理 | 4 | `/api/gm/v1/configs` |
| 灰度管理 | 3 | `/api/gm/v1/gray-release` |
| 工单管理 | 6 | `/api/gm/v1/tickets` |
| 报表 | 5 | `/api/gm/v1/reports` |
| 审计日志 | 2 | `/api/gm/v1/audit-logs` |
| 审批 | 3 | `/api/gm/v1/approvals` |

### 9.3 限流

| 接口类型 | 速率 | Burst |
|---------|------|-------|
| 查询接口 | 120 次/分钟 | 20 |
| 写操作接口 | 30 次/分钟 | 5 |
| 敏感操作接口 | 10 次/分钟 | 3 |

---

## 10. 已确认决策记录表

| # | 决策 | 来源 |
|---|------|------|
| TDD08-✅1 | GM 后台为独立 Gin 服务（端口 8090），不走 Nakama，避免 GM 操作影响游戏服务稳定性 | 本文档 §2.1 |
| TDD08-✅2 | GM 操作审计日志按月分区保留 24 个月，数据库层面禁止 DELETE/UPDATE | 本文档 §2.3 / §8.4 |
| TDD08-✅3 | 敏感操作（批量发放、经济调整、境界调整、配置发布、交易回滚）必须双人审批 | PRD-03 §3.2 / 本文档 §3.8 |
| TDD08-✅4 | GM 发放/回收物品和货币统一写入 `economy_audit_logs`，纳入经济监控 | TDD-04 §5.4 / 本文档 §3.2 |
| TDD08-✅5 | 经济健康度评分模型由五维度加权组成，阈值通过 Nacos 可配 | 本文档 §4.3 |
| TDD08-✅6 | 配置变更审批超时 24 小时自动过期；超级 GM 可紧急通道跳过审批（需审计标记） | 本文档 §5.4 |
| TDD08-✅7 | 客服角色仅限预设补偿模板发放，单次价值受 Nacos 阈值控制 | 本文档 §6.3 |
| TDD08-✅8 | 玩家自助查询覆盖封号原因、交易记录、战报回看、经济流水、工单状态五类 | 本文档 §6.4 |
| TDD08-✅9 | 灰度发布支持百分比、分组、渠道、地区四维度；崩溃率 >5% 自动暂停 | PRD-03 §2.4 / 本文档 §5.3 |
| TDD08-✅10 | GM 角色分四级（超级GM/普通GM/客服/观察员），权限逐项授权 | 本文档 §8.1 |

---

## 11. 验收标准

| # | 验收条目 | 测试方法 |
|---|----------|----------|
| 1 | 使用无效 JWT 或过期 token 访问任何 GM 接口时返回 401 | 使用过期/篡改 token 调用接口 |
| 2 | observer 角色尝试执行封禁/发放/修改等写操作时返回 403 | 用 observer token 调用写接口 |
| 3 | 所有 GM 操作（含查询）均在 `gm_audit_logs` 中有对应记录，且记录不可被 DELETE/UPDATE | 执行操作后查审计日志；尝试直接 SQL 删除/更新验证约束 |
| 4 | 敏感操作（境界调整、批量发放超阈值、配置发布）触发审批流，单人操作被拦截，双人审批后才执行 | 提交敏感操作，验证需审批；另一人审批后验证执行 |
| 5 | GM 发放物品后，`economy_audit_logs` 中有对应 `admin_compensation` 记录，经济监控仪表盘实时反映 | 发放物品后查审计日志和仪表盘 |
| 6 | 经济监控仪表盘能在 5 分钟内反映最新的货币产出/消耗变化 | 执行货币调整后观察仪表盘刷新 |
| 7 | 经济异常告警（产出速率 >2 倍均值）在发生后 15 分钟内触发通知 | 模拟异常产出，验证告警触发 |
| 8 | Nacos 配置修改经审批发布后，所有 Nakama/Gin 实例在 10 秒内生效 | 修改配置发布后，查询各实例配置版本 |
| 9 | 灰度发布崩溃率超过 5% 阈值时自动暂停灰度 | 模拟崩溃样本，验证自动暂停 |
| 10 | 客服工单从创建到关闭的完整流转（创建→分配→处理→解决→关闭）可正常执行 | 创建工单并走完全流程 |
| 11 | 玩家自助查询（封号原因/交易记录/战报回看）返回正确数据 | 用对应状态的玩家账号调用自助查询接口 |
| 12 | 数据报表 DAU/留存/LTV 计算结果与手动 SQL 查询一致 | 手动 SQL 验证报表数据 |
| 13 | GM 指令快捷操作台执行 `/ban`、`/grant`、`/adjust` 等指令后，对应数据库状态正确变更 | 执行指令后验证数据库 |
| 14 | 配置紧急发布通道需输入确认文本 + 审计日志标记 `emergency` | 使用紧急发布后查审计日志 |

---

## 12. 版本记录

| 版本 | 日期 | 修订内容 | 作者 |
|------|------|----------|------|
| v1.0 | 2026-07-02 | 初始版本：GM指令系统（6大类）、经济监控仪表盘、活动配置后台（Nacos可视化/活动日历/灰度/审批流）、客服工单系统、数据报表、权限管理（四级角色）、10条决策记录、14条验收标准 | Claude Code |

---

*本文档数值/阈值均引用 GDD-21《数值平衡与联调参数总表》与 Nacos 动态配置，服务端实现时以运行时配置为准，不硬编码。*