lawless/docs/技术文档/TDD-08-GM与运营后台设计.md

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 动态配置，服务端实现时以运行时配置为准，不硬编码。