docs: add admin and development documentation

docs/admin_reference_prd/后台功能与数据库表映射.md

@@ -0,0 +1,130 @@
+# 后台功能与数据库表映射
+
+> 更新时间：2026-10-09  
+> 范围：当前 HotGo 后台、已实现业务模块及数据库 `olons_admin` 现有表  
+> 说明：一个页面可能关联多张表；部分公共表会被多个业务模块共同使用。
+
+## 1. 当前业务菜单
+
+| 一级菜单 | 功能 | 核心表 | 关联表 | 说明 |
+| --- | --- | --- | --- | --- |
+| 主页 | 首页数据看板 | `hg_dashboard_daily_stat` | `hg_app_member`、`hg_trade_order`、`hg_recharge_order`、`hg_withdrawal_order`、`hg_task_submission` | 展示会员、订单、充值、提现、任务等汇总数据；部分指标实时统计，日指标可落汇总表。 |
+| 主页 | 网站设置 | `hg_site_config_version` | — | 站点名称、Logo、隐私网址、交易限制、佣金、时间段、功能开关、自动派单等整份保存在 `config_json`；当前页面直接保存并生效。 |
+| 主页 | 文本管理 | `hg_content` | `hg_content_version` | `hg_content` 保存内容主档，`hg_content_version` 保存正文版本。 |
+| 主页 | Banner 设置 | `hg_banner` | `hg_sys_attachment` | 管理 Banner 图片、位置、跳转方式、展示时间和排序。 |
+| 主页 | 手工商城 | `hg_product` | `hg_sys_attachment` | 与商品管理共用商品表，以 `product_type=2` 区分手工商城商品；当前只维护名称、价格和展示图片。 |
+| 会员管理 | 会员列表 | `hg_app_member` | `hg_app_member_profile`、`hg_app_member_address`、`hg_app_member_payment_account`、`hg_app_member_status_log` | 会员主档、实名/扩展资料、地址、银行卡或收款账户、状态变更记录。 |
+| 会员管理 | 会员列表—余额与账变 | `hg_wallet_account` | `hg_wallet_ledger`、`hg_wallet_adjustment_request` | 钱包余额保存在账户表，所有变动写入不可变流水；人工账变入口保留在会员列表操作栏。 |
+| 会员管理 | 会员等级 | `hg_app_member_level` | `hg_app_member_level_version`、`hg_app_member` | 等级规则及等级版本；会员主档关联当前等级。 |
+| 会员管理 | 任务大厅 | `hg_task_hall` | `hg_task_hall_level`、`hg_app_member_level` | 配置大厅入口及允许参与的会员等级。 |
+| 交易管理 | 订单列表 | `hg_trade_order` | `hg_app_member`、`hg_product`、`hg_task`、`hg_wallet_ledger` | 交易订单主档及会员、商品、任务、资金流水关联。 |
+| 交易管理 | 充值管理 | `hg_recharge_order` | `hg_payment_channel`、`hg_wallet_account`、`hg_wallet_ledger`、`hg_finance_review` | 充值申请、渠道信息、审核结果和入账流水。 |
+| 交易管理 | 提现管理 | `hg_withdrawal_order` | `hg_wallet_account`、`hg_wallet_ledger`、`hg_finance_review`、`hg_app_member_payment_account` | 提现申请、余额冻结/扣减/退回、审核以及收款账户信息。 |
+| 交易管理 | 客服管理 | `hg_customer_service` | — | 客服名称、联系方式、工作时间、在线状态和排序。 |
+| 商品管理 | 商品列表 | `hg_product` | `hg_product_category`、`hg_sys_attachment` | 正式商品主档，以 `product_type=1` 区分；分类保存在商品分类表。 |
+| 任务管理 | 任务列表 | `hg_task` | `hg_task_level`、`hg_product`、`hg_app_member_level` | 任务主体、关联商品、适用会员等级及佣金规则。 |
+| 任务管理 | 会员任务审核 | `hg_task_submission` | `hg_task`、`hg_app_member`、`hg_app_member_level`、`hg_wallet_account`、`hg_wallet_ledger` | 审核会员提交的任务；通过后结算佣金并生成钱包流水。 |
+
+## 2. 已隐藏菜单但保留的业务能力
+
+| 原菜单 | 保留表 | 当前入口/处理方式 |
+| --- | --- | --- |
+| 资金调账 | `hg_wallet_adjustment_request`、`hg_wallet_account`、`hg_wallet_ledger` | 独立菜单已隐藏；相关权限和接口保留，由会员列表中的“账变”操作进入。 |
+| 会员通知 | `hg_app_member_notice` | 独立菜单已隐藏；通知/弹幕相关能力和接口保留，可从会员列表操作或后续 C 端消息中心复用。 |
+| 审批中心 | `hg_approval_request`、`hg_approval_action` | 独立治理菜单已移除；表和服务仍可供高风险业务复用。 |
+| 业务审计 | `hg_biz_audit_log` | 独立菜单已移除；重要操作仍可写入审计记录。 |
+
+## 3. HotGo 原生后台功能
+
+### 3.1 组织与权限
+
+| 功能 | 核心表 | 说明 |
+| --- | --- | --- |
+| 后台用户 | `hg_admin_member` | 后台管理员账号。 |
+| 部门管理 | `hg_admin_dept` | 组织部门树。 |
+| 岗位管理 | `hg_admin_post`、`hg_admin_member_post` | 岗位定义及管理员岗位关系。 |
+| 角色权限 | `hg_admin_role`、`hg_admin_member_role` | 角色树、管理员角色关系。子角色可选菜单不得超过直接父角色范围。 |
+| 菜单权限 | `hg_admin_menu`、`hg_admin_role_menu` | 菜单、页面、按钮权限及角色菜单关系。 |
+| 接口鉴权 | `hg_admin_role_casbin` | Casbin 接口权限规则。 |
+| 第三方登录 | `hg_admin_oauth` | 后台账号第三方授权关系。 |
+
+### 3.2 系统设置与运维
+
+| 功能 | 核心表 | 说明 |
+| --- | --- | --- |
+| 配置管理 | `hg_sys_config` | HotGo 系统配置。网站业务配置不写入此表，而写入 `hg_site_config_version`。 |
+| 字典管理 | `hg_sys_dict_type`、`hg_sys_dict_data` | 动态字典类型和选项数据；代码枚举通过 HotGo 字典注册机制提供。 |
+| 定时任务 | `hg_sys_cron_group`、`hg_sys_cron` | 定时任务分组、执行策略及状态。 |
+| 黑名单 | `hg_sys_blacklist` | IP 等访问黑名单。 |
+| 通知公告 | `hg_admin_notice`、`hg_admin_notice_read` | 面向后台管理员的公告及阅读状态，与会员通知不是同一张表。 |
+| 附件管理 | `hg_sys_attachment` | 上传文件和图片元数据。 |
+| 地区编码 | `hg_sys_provinces` | 省市区层级数据。 |
+| 操作日志 | `hg_sys_log` | 后台接口操作日志。 |
+| 登录日志 | `hg_sys_login_log` | 后台登录记录。 |
+| 短信/邮件日志 | `hg_sys_sms_log`、`hg_sys_ems_log` | 短信和邮件发送记录。 |
+| 服务日志 | `hg_sys_serve_log` | 服务运行日志。 |
+| 服务授权/监控 | `hg_sys_serve_license` | 服务连接与授权状态；在线用户主要依赖会话/缓存，不单独落业务表。 |
+
+### 3.3 HotGo 资金与支付基础能力
+
+| 功能 | 核心表 | 说明 |
+| --- | --- | --- |
+| 后台资金账户 | `hg_admin_cash`、`hg_admin_credits_log` | HotGo 原生后台账户资金及积分/余额变动。与 C 端会员钱包表分离。 |
+| HotGo 订单 | `hg_admin_order` | HotGo 原生支付订单，与业务交易订单 `hg_trade_order` 分离。 |
+| 支付与退款日志 | `hg_pay_log`、`hg_pay_refund` | 支付请求、回调及退款记录。 |
+
+### 3.4 插件与开发工具
+
+| 功能 | 核心表 | 说明 |
+| --- | --- | --- |
+| 插件管理 | `hg_sys_addons_install`、`hg_sys_addons_config` | 插件安装状态及插件配置。 |
+| 代码生成 | `hg_sys_gen_codes` | 代码生成配置。 |
+| 示例插件 | `hg_addon_hgexample_table`、`hg_addon_hgexample_tenant_order` | HotGo 示例数据，不属于正式业务。 |
+| 生成示例 | `hg_sys_gen_curd_demo`、`hg_sys_gen_tree_demo`、`hg_test_category` | CRUD/树表/分类演示，不属于正式业务。 |
+
+## 4. 公共支撑表
+
+| 表 | 用途 | 典型使用模块 |
+| --- | --- | --- |
+| `hg_approval_request` | 审批请求主表 | 会员状态、资金调账、充值、提现等高风险操作。 |
+| `hg_approval_action` | 审批动作流水 | 记录提交、通过、拒绝等动作。 |
+| `hg_biz_audit_log` | 业务审计日志 | 资金、任务审核、状态变化等重要操作。 |
+| `hg_sensitive_access_log` | 敏感数据查看记录 | 会员手机号、实名、银行卡等完整信息查看。 |
+| `hg_idempotency_record` | 幂等控制 | 支付、审核执行、钱包入账等不可重复操作。 |
+| `hg_outbox_event` | 事务消息/事件出站箱 | 业务提交后异步通知或跨模块事件。 |
+| `hg_dashboard_daily_stat` | 每日统计快照 | 首页看板。 |
+
+## 5. 核心数据关系
+
+```text
+会员 hg_app_member
+├── 扩展资料 hg_app_member_profile
+├── 地址 hg_app_member_address
+├── 收款账户 hg_app_member_payment_account
+├── 等级 hg_app_member_level
+├── 钱包 hg_wallet_account
+│   ├── 账变流水 hg_wallet_ledger
+│   └── 人工调账 hg_wallet_adjustment_request
+├── 交易订单 hg_trade_order
+├── 充值订单 hg_recharge_order
+├── 提现订单 hg_withdrawal_order
+└── 任务提交 hg_task_submission
+
+商品 hg_product
+├── 分类 hg_product_category
+├── 交易订单 hg_trade_order
+└── 任务 hg_task
+    ├── 等级投放 hg_task_level
+    └── 会员提交 hg_task_submission
+```
+
+## 6. 数据存储约定
+
+- 业务金额统一以“分”存入 `bigint` 字段，页面负责格式化为元。
+- 会员敏感信息采用密文、检索哈希和脱敏展示值分离保存。
+- 钱包余额以 `hg_wallet_account` 为当前值，`hg_wallet_ledger` 为不可变账变依据。
+- 网站设置字段集中保存在 `hg_site_config_version.config_json`，因此新增配置项通常无需增加数据库列。
+- 商品管理和手工商城共用 `hg_product`，通过 `product_type` 区分。
+- 后台管理员资金表与 C 端会员钱包表完全分离，禁止混用。
+- 带 `tenant_id` 的业务表通过 HotGo 多租户过滤器隔离数据。
+- 带 `deleted_at` 的表使用软删除，不直接物理删除历史业务记录。

docs/admin_reference_prd/后台管理系统开发总结.md

@@ -0,0 +1,453 @@
+# 后台管理系统开发总结
+
+> 文档版本：V1.0  
+> 编制日期：2026-10-08  
+> 需求基线：[后台管理系统需求文档](./后台管理系统需求文档.md)  
+> 概要设计：[后台管理系统概要设计](./后台管理系统概要设计.md)  
+> 项目目录：`/Users/youshunlai/go_workspace/olons_admin`
+
+## 1. 文档说明
+
+本文档汇总当前已经完成的后台管理系统开发内容，用于后续联调、测试、验收和继续开发。
+
+文档中的状态分为：
+
+- **已开发**：已完成数据库、后端接口、前端页面和菜单权限的主体实现。
+- **复用现有系统**：HotGo 已提供对应能力，本项目不重复开发。
+- **后续补充**：已有基础模型，但仍需按专项设计补齐业务闭环。
+
+## 2. 总体完成情况
+
+| 章节 | 模块 | 当前状态 | 说明 |
+| --- | --- | --- | --- |
+| 第 4 章 | 首页数据看板 | 已开发 | 已接入真实业务统计与待办入口 |
+| 第 5 章 | 门户、内容与 Banner | 已开发 | 已完成配置版本、文本、Banner、手工商城 |
+| 第 6 章 | 会员管理 | 已开发 | 已完成会员、隐私、团队、钱包调账和通知 |
+| 第 7 章 | 会员等级与任务大厅 | 已开发 | 已完成等级版本发布和任务大厅管理 |
+| 第 8 章 | 交易管理 | 已开发 | 已完成订单、充值、提现和客服管理 |
+| 第 9 章 | 商品与任务管理 | 已开发 | 已完成商品、任务和会员任务审核 |
+| 第 10 章 | 管理员、角色与权限 | 复用现有系统 | HotGo 原有组织、管理员、角色和菜单权限满足主体需求 |
+| 第 11 章 | 数据字典与个人设置 | 复用现有系统 | HotGo 原有字典、个人资料和安全设置满足主体需求 |
+| 第 12 章 | 状态机与数据模型 | 后续补充 | 核心模型已有，冲正、归档和严格状态转换仍需补强 |
+
+## 3. 技术实现概况
+
+### 3.1 后端
+
+- Go + GoFrame v2。
+- 遵循 `api → controller → service → logic → dao` 分层。
+- 业务模块使用主模块实现，没有引入额外 Addon。
+- 表字段通过 `dao.Xxx.Columns()` 引用。
+- 多租户数据通过现有 `handler.Model` 和 `hook.SaveTenant` 处理。
+- 金额统一按“分”存储，比例统一按“万分比”存储。
+- 业务字典优先复用 HotGo 字典系统，代码枚举统一在 `internal/consts` 注册。
+
+### 3.2 前端
+
+- Vue 3 + Vite + TypeScript。
+- UI 统一使用 Naive UI 和项目已有的 `BasicTable`、`BasicForm`、`BasicModal`。
+- HTTP 请求统一通过 `@/utils/http/axios` 的 `http.request`。
+- 菜单由后端数据驱动，页面操作使用接口路径进行权限判断。
+- 状态标签和筛选项从后端字典加载，不在页面硬编码业务枚举。
+
+### 3.3 基础治理
+
+在业务模块开发前已建设以下共用能力：
+
+- 审批请求与审批动作。
+- 业务审计日志和哈希链。
+- 敏感信息查看记录。
+- 幂等记录。
+- Outbox 事件表。
+- 看板每日汇总表。
+- 高风险操作的申请、审批、执行分离。
+
+对应迁移：
+
+- `20261008_001_governance.sql`
+- `20261008_002_governance_menu.sql`
+
+## 4. 第 4 章：首页数据看板
+
+### 4.1 已实现功能
+
+- 今日新增会员、订单、充值、提现等核心指标。
+- 业务金额、订单和会员数据汇总。
+- 待审批和异常业务入口。
+- 按管理员权限控制敏感金额展示。
+- 原 HotGo 控制台菜单复用并扩展业务统计接口。
+
+### 4.2 主要接口
+
+- `GET /console/stat`
+- `GET /dashboard/summary`
+
+### 4.3 主要代码
+
+- 后端：`server/internal/logic/sys/dashboard.go`
+- 前端：`web/src/views/dashboard/console/`
+- 前端 API：`web/src/api/dashboard/console.ts`
+- 菜单迁移：`20261008_003_dashboard_menu.sql`
+
+### 4.4 测试
+
+- 已增加 `server/internal/logic/sys/dashboard_test.go`。
+
+## 5. 第 5 章：门户、内容与 Banner 管理
+
+### 5.1 网站设置
+
+- 站点配置按完整快照保存。
+- 支持草稿保存、提交审批、发布和历史版本查看。
+- 支持根据历史版本生成回滚草稿。
+- 使用摘要和乐观锁避免并发覆盖。
+
+主要接口：
+
+- `/siteConfig/current`
+- `/siteConfig/history`
+- `/siteConfig/save`
+- `/siteConfig/submit`
+- `/siteConfig/publish`
+- `/siteConfig/rollback`
+
+### 5.2 文本管理
+
+- 文本内容列表、详情、新增和编辑。
+- 内容正文按版本保存。
+- 支持发布、下线和软删除。
+- 保存当前发布版本 ID，历史版本不被覆盖。
+
+主要接口：
+
+- `/portalContent/list`
+- `/portalContent/view`
+- `/portalContent/edit`
+- `/portalContent/publish`
+- `/portalContent/offline`
+- `/portalContent/delete`
+
+### 5.3 Banner 管理
+
+- Banner 列表、详情、新增、编辑和删除。
+- 支持投放位置、图片、替代文本、跳转方式、生效时间、排序和发布状态。
+- 支持发布和下线状态切换。
+
+### 5.4 手工商城
+
+- 手工商城商品列表、详情、新增、编辑、删除和上下架。
+- 支持商品类型、支付方式、金额、封面、详情、推荐和展示时间。
+
+### 5.5 数据表与代码
+
+新增数据表：
+
+- `hg_site_config_version`
+- `hg_content`
+- `hg_content_version`
+- `hg_banner`
+- `hg_product`
+
+主要代码：
+
+- 后端：`server/internal/logic/sys/portal.go`
+- API：`server/api/admin/portal/portal.go`
+- 前端：`web/src/views/portal/`
+- 前端 API：`web/src/api/portal/index.ts`
+- 迁移：`20261008_004_portal_content.sql`
+- 测试：`server/internal/logic/sys/portal_test.go`
+
+## 6. 第 6 章：会员管理
+
+### 6.1 会员主档
+
+- 会员列表、详情、新增、编辑和注销。
+- 用户名、等级、上级、风控、信用分、自动派单和测试账号管理。
+- 手机号、姓名、证件号按密文、检索哈希和脱敏值分离保存。
+- 注销采用状态和软删除标记，不删除历史审计主体。
+
+### 6.2 收款账户和地址
+
+- 多类型收款账户管理。
+- 银行卡、开户名和手机号敏感字段加密及脱敏。
+- 会员地址列表、新增、编辑和删除。
+
+### 6.3 敏感信息查看
+
+- 完整敏感值通过独立授权接口查看。
+- 必须填写查看目的。
+- 记录操作人、目标、字段集、授权号和查看结果。
+
+### 6.4 团队关系
+
+- 支持查询会员下级团队。
+- 使用 `pid`、`level` 和 `tree` 保存层级关系。
+- 支持控制查询层级和分页。
+
+### 6.5 会员状态
+
+- 支持发起会员状态变更审批。
+- 审批通过后由执行接口完成状态变更。
+- 保存状态变更原因、审批单和操作记录。
+
+### 6.6 钱包调账
+
+- 钱包账户区分可用余额和冻结余额。
+- 调账必须先申请审批，再执行入账。
+- 每次资金变化写入不可变台账。
+- 支持幂等键、前后余额和冲正关联字段。
+
+### 6.7 会员通知
+
+- 支持全体或指定会员通知。
+- 区分真实通知与运营模拟。
+- 支持有效期和撤回。
+
+### 6.8 数据表与代码
+
+新增数据表：
+
+- `hg_app_member`
+- `hg_app_member_profile`
+- `hg_app_member_address`
+- `hg_app_member_payment_account`
+- `hg_app_member_status_log`
+- `hg_wallet_account`
+- `hg_wallet_ledger`
+- `hg_wallet_adjustment_request`
+- `hg_app_member_notice`
+
+主要代码：
+
+- 后端：`server/internal/logic/sys/app_member.go`
+- API：`server/api/admin/appmember/appmember.go`
+- 前端：`web/src/views/app-member/list/`、`wallet/`、`notice/`
+- 前端 API：`web/src/api/appMember/index.ts`
+- 迁移：`20261008_005_member_management.sql`
+
+## 7. 第 7 章：会员等级与任务大厅
+
+### 7.1 会员等级
+
+- 会员等级列表和详情。
+- 等级规则保存为不可变版本。
+- 支持草稿、提交审批、发布、历史版本和回滚草稿。
+- 使用乐观锁防止并发覆盖。
+- 支持等级启停和删除。
+
+主要接口：
+
+- `/memberLevel/list`
+- `/memberLevel/view`
+- `/memberLevel/save`
+- `/memberLevel/submit`
+- `/memberLevel/publish`
+- `/memberLevel/rollback`
+- `/memberLevel/history`
+- `/memberLevel/status`
+- `/memberLevel/delete`
+
+### 7.2 任务大厅
+
+- 任务大厅列表、详情、新增和编辑。
+- 支持封面、描述、开放时间、排序和发布状态。
+- 支持配置允许进入的会员等级。
+- 支持发布、下线和删除。
+
+### 7.3 数据表与代码
+
+新增数据表：
+
+- `hg_app_member_level`
+- `hg_app_member_level_version`
+- `hg_task_hall`
+- `hg_task_hall_level`
+
+主要代码：
+
+- 后端：`member_level.go`、`task_hall.go`
+- API：`server/api/admin/memberlevel/`、`taskhall/`
+- 前端：`web/src/views/app-member/level/`、`task-hall/`
+- 前端 API：`web/src/api/memberLevel/`、`taskHall/`
+- 迁移：`20261008_006_member_level_task_hall.sql`
+
+## 8. 第 8 章：交易管理
+
+### 8.1 交易订单
+
+- 订单列表和详情。
+- 支持商品、任务和手工商城订单类型。
+- 保存商品名称、金额、会员等级和规则快照。
+- 人工取消匹配、重新匹配和解冻必须经过审批。
+- 执行时重新检查订单和审批状态。
+
+### 8.2 充值管理
+
+- 充值列表、金额汇总和详情。
+- 支持线上支付和人工充值。
+- 人工审核采用申请与执行分离。
+- 审核通过后在事务内更新钱包并写入台账。
+- 审核结果保存审批单、财务复核快照和审核原因。
+
+### 8.3 提现管理
+
+- 提现列表和脱敏详情。
+- 支持初审、复核、付款中、成功、失败和驳回状态。
+- 提现审核和执行通过事务、行锁、审批和台账处理。
+- 付款结果单独登记，保存外部付款单号。
+
+### 8.4 客服管理
+
+- 客服列表、详情、新增、编辑、启停和删除。
+- 支持客服类型、显示名称、联系方式、工作时间和排序。
+
+### 8.5 数据表与代码
+
+新增数据表：
+
+- `hg_trade_order`
+- `hg_payment_channel`
+- `hg_recharge_order`
+- `hg_withdrawal_order`
+- `hg_finance_review`
+- `hg_customer_service`
+
+主要代码：
+
+- 后端：`trade_order.go`、`recharge_order.go`、`withdrawal_order.go`、`customer_service.go`
+- API：`server/api/admin/tradeorder/`、`rechargeorder/`、`withdrawalorder/`、`customerservice/`
+- 前端：`web/src/views/trade/`
+- 前端 API：`web/src/api/trade/index.ts`
+- 迁移：`20261008_007_trade_management.sql`
+
+## 9. 第 9 章：商品与任务管理
+
+### 9.1 商品管理
+
+- 商品列表、详情、新增和编辑。
+- 支持分类、类型、支付方式、店铺、价格、封面、详情和展示时间。
+- 支持上下架、推荐切换和删除。
+
+### 9.2 任务管理
+
+- 任务列表、详情、新增和编辑。
+- 支持任务大厅、会员等级、封面、详情、固定佣金和比例佣金。
+- 支持每日数量、单会员限制和任务有效期。
+- 支持发布、下线和删除。
+
+### 9.3 会员任务审核
+
+- 按会员、任务和审核状态查询提交记录。
+- 展示任务、会员、等级、佣金、成功率、证据和审核结果。
+- 待审核记录支持通过和驳回。
+- 驳回保存标准原因、补充说明和是否允许重新提交。
+- 审核通过后在事务内结算佣金并写入钱包台账。
+
+### 9.4 数据表与代码
+
+新增数据表：
+
+- `hg_product_category`
+- `hg_task`
+- `hg_task_level`
+- `hg_task_submission`
+
+主要代码：
+
+- 后端：`product.go`、`task.go`、`task_submission.go`
+- API：`server/api/admin/product/`、`task/`、`tasksubmission/`
+- 前端：`web/src/views/product-task/`
+- 前端 API：`web/src/api/productTask/index.ts`
+- 迁移：`20261008_008_product_task_management.sql`
+
+菜单“商品与任务”的根布局标识已统一为 HotGo 识别的 `LAYOUT`，进入子页面时左侧菜单和顶部布局可以正常保留。
+
+## 10. 复用 HotGo 的现有功能
+
+### 10.1 管理员、角色与权限
+
+第 10 章不重复开发，复用：
+
+- 组织管理中的管理员维护。
+- 角色管理和菜单权限树。
+- 接口路径权限控制。
+- 部门、岗位和数据权限。
+- 登录、禁用、密码重置等现有能力。
+
+### 10.2 数据字典与个人设置
+
+第 11 章不重复开发，复用：
+
+- “系统设置 → 字典管理”的字典类型和字典数据 CRUD。
+- 字典标签、键值、值类型、标签样式、排序和状态。
+- “个人中心 → 个人设置”的基本资料维护。
+- 手机号和邮箱验证码换绑。
+- 当前密码校验和登录密码修改。
+
+密码强度、全部会话撤销、敏感配置版本管理等属于后续安全增强，不纳入当前已开发范围。
+
+## 11. 数据库迁移清单
+
+| 顺序 | 文件 | 用途 |
+| ---: | --- | --- |
+| 1 | `20261008_001_governance.sql` | 审批、审计、幂等、Outbox、看板汇总 |
+| 2 | `20261008_002_governance_menu.sql` | 治理模块菜单和权限 |
+| 3 | `20261008_003_dashboard_menu.sql` | 首页看板菜单和权限 |
+| 4 | `20261008_004_portal_content.sql` | 门户、内容、Banner、手工商城 |
+| 5 | `20261008_005_member_management.sql` | 会员、敏感资料、钱包和通知 |
+| 6 | `20261008_006_member_level_task_hall.sql` | 会员等级和任务大厅 |
+| 7 | `20261008_007_trade_management.sql` | 订单、充值、提现和客服 |
+| 8 | `20261008_008_product_task_management.sql` | 商品、任务和会员任务审核 |
+
+以上迁移均采用可重复执行的建表或条件插入方式，菜单、字典和角色权限随对应业务迁移配置。
+
+## 12. 当前运行与交付状态
+
+- 本地后端运行地址：`http://127.0.0.1:8000`。
+- 本地前端运行地址：`http://127.0.0.1:8001`。
+- 动态菜单已加载首页、治理、门户、会员、交易、商品与任务模块。
+- 第 4～9 章页面已经可以从后台菜单进入查看。
+- 第 10、11 章继续使用 HotGo 原有页面。
+
+### 12.1 本地演示数据
+
+已为本次新增的 35 张业务表写入关联演示数据，覆盖审批、发布、会员、风控、订单、充值、提现、任务审核、调账和客服等全部已定义状态。演示业务编号统一使用 `DEMO` 前缀。
+
+可重复执行的数据脚本：
+
+```text
+server/storage/data/seeds/20261008_business_demo_data.sql
+```
+
+本地重新导入命令：
+
+```bash
+mysql -h127.0.0.1 -P3306 -uroot -proot olons_admin \
+  < server/storage/data/seeds/20261008_business_demo_data.sql
+```
+
+正式上线前仍需执行完整的接口回归、权限角色矩阵检查、并发资金测试和生产配置核对。
+
+---
+
+## 补充项：第 12 章状态机与数据模型补强
+
+第 12 章不是新的一级菜单，而是对现有会员、资金、任务和内容模块的业务约束补强。当前核心数据表、审批、台账和审计基础已经具备，但以下内容尚未列入“已完成”：
+
+1. 会员状态合法转换和注销不可逆。
+2. 充值成功后的审批冲正。
+3. 已结算任务佣金的审批冲正。
+4. 文本内容归档和历史版本生成回滚草稿。
+5. 状态转换、重复执行、并发执行和余额不足测试。
+
+专项设计已单独整理，后续开发以该文档为实施依据：
+
+[第12章状态机与数据模型补强设计](./第12章状态机与数据模型补强设计.md)
+
+建议后续新增迁移：
+
+```text
+server/storage/data/migrations/20261008_009_state_machine_hardening.sql
+```
+
+MFA 真实认证流程不与本次状态机补强混合实施，后续作为独立安全增强项处理。

docs/admin_reference_prd/后台管理系统需求文档.md

@@ -0,0 +1,508 @@
+# 后台管理系统需求文档
+
+参考管理端功能拆解、C 端映射与安全重构方案
+
+目标：基于参考管理系统的实际页面、按钮、链接与弹窗，形成可直接用于产品设计、前后端开发、测试和运维的后台需求基线；保留业务闭环，不复制品牌资产和真实用户数据。
+
+主要读者：产品负责人、交互设计师、前端开发、后端开发、测试、运营、客服、财务、风控、安全与审计。
+
+观察日期：2026-10-07    参考环境：Web 管理后台    文档版本：V1.0
+
+> **结论：** 后台覆盖门户配置、会员、交易、商品、任务、RBAC 与个人设置七大域。复刻时应优先修复敏感数据裸露、资金操作单人审批、配置无校验、接口错误和审计不足。
+
+## 目录
+
+- [1 文档范围与走查方法](#1-文档范围与走查方法)
+- [2 产品定位与后台角色](#2-产品定位与后台角色)
+- [3 C 端与后台功能映射](#3-c-端与后台功能映射)
+- [4 首页数据看板](#4-首页数据看板)
+- [5 门户、内容与 Banner 管理](#5-门户内容与-banner-管理)
+- [6 会员管理](#6-会员管理)
+- [7 会员等级与任务大厅](#7-会员等级与任务大厅)
+- [8 交易管理](#8-交易管理)
+- [9 商品与任务管理](#9-商品与任务管理)
+- [10 管理员、角色与权限](#10-管理员角色与权限)
+- [11 数据字典与个人设置](#11-数据字典与个人设置)
+- [12 状态机与数据模型](#12-状态机与数据模型)
+- [13 推荐接口清单](#13-推荐接口清单)
+- [14 安全、隐私与审计](#14-安全隐私与审计)
+- [15 非功能需求](#15-非功能需求)
+- [16 端到端验收场景](#16-端到端验收场景)
+- [17 研发里程碑](#17-研发里程碑)
+- [18 原型图说明](#18-原型图说明)
+- [19 待确认事项](#19-待确认事项)
+
+---
+
+## 1 文档范围与走查方法
+
+本需求对后台 21 个可见页面入口进行了逐项走查，并打开新增、编辑、查看、分配、审核等代表性弹窗。为了保护现网数据，没有执行最终确定、上传、删除、禁用、设为假人、审核通过或驳回、资金调整、奖励金发放、权限保存和改密。
+
+### 1.1 已覆盖入口
+
+| 一级模块 | 页面 | 主要控件 |
+| --- | --- | --- |
+| 主页 | 首页、网站设置、文本管理、Banner 设置、手工商城 | 指标卡、保存、上传、编辑、删除、发布 |
+| 会员管理 | 会员列表、会员等级、任务大厅 | 搜索、新增、编辑、团队、账变、奖励金、等级配置 |
+| 交易管理 | 订单、充值、提现、客服 | 筛选、自动刷新、匹配、凭证、审核、客服嵌入 |
+| 商城管理 | 商品列表 | 搜索、新增、编辑、推荐、删除、富文本 |
+| 任务管理 | 任务列表、会员任务审核 | 任务新增、编辑、通过、驳回 |
+| 管理员 | 后台管理员、角色、权限、数据字典 | 账号、角色、权限树、配置项 |
+| 设置 | 基本资料、修改密码 | 资料修改、密码修改 |
+
+### 1.2 操作边界
+
+- 只验证页面、按钮和弹窗是否可达，未提交会改变会员、资金、权限或配置的数据。
+- 删除、禁用、设为假人、审核、账变、奖励金、改密等高风险入口仅记录需求，不执行最终动作。
+- 原型图基于实测界面脱敏重绘，手机号、姓名、IP、银行卡、订单号均为掩码或虚构值。
+- 接口名称以推荐实现命名；现网真实接口需在开发前通过代码或服务端文档二次核验。
+
+### 1.3 证据等级
+
+| 等级 | 定义 | 使用方式 |
+| --- | --- | --- |
+| A 实测 | 页面、按钮、表格或弹窗在走查中直接可见 | 可作为复刻基线 |
+| B 推导 | 由相邻页面、C 端闭环或字段关系推导 | 开发前需确认 |
+| C 建议 | 为安全、合规、可用性提出的重构要求 | 作为新系统强制规范 |
+
+## 2 产品定位与后台角色
+
+该后台用于运营一个移动端会员任务与账户平台。C 端会员进行注册、余额储入、领取订单、任务提交、佣金结算、提现和客服咨询；后台完成内容配置、会员治理、商品与任务配置、交易审核、财务对账和权限审计。
+
+| 角色 | 职责 | 允许范围 | 禁止范围 |
+| --- | --- | --- | --- |
+| 超级管理员 | 系统与权限治理 | 账号、角色、权限、系统参数 | 不得绕过双人复核直接放款 |
+| 运营 | 内容、Banner、商品、任务、等级 | 草稿、预览、发布申请 | 不得查看完整银行卡或改余额 |
+| 客服 | 会员与订单查询、工单 | 脱敏资料、只读订单、备注 | 不得资金审核或导出全量用户 |
+| 财务 | 充值、提现、对账 | 凭证、审核、支付状态 | 不得修改会员身份与权限 |
+| 风控 | 异常行为与冻结复核 | 设备、IP 风险、冻结申请 | 不得单人完成冻结与解冻 |
+| 审计 | 只读复核与导出 | 日志、审批链、差异报表 | 不得修改业务数据 |
+
+### 2.1 信息架构
+
+采用“一级业务域 + 二级页面 + 多标签工作区”的桌面后台结构。一级菜单固定在左侧，二级页面以标签页打开；标签支持关闭、刷新和回到首页。任何页面刷新后，应保持当前路由但不保留未提交敏感表单。
+
+### 2.2 全局交互规范
+
+- 列表页统一：查询区、主操作区、表格、固定操作列、分页；查询条件可重置并写入 URL。
+- 弹窗统一：标题、关闭、表单、确定、取消；确定前做前后端双重校验，提交后禁止重复点击。
+- 危险操作使用红色按钮并要求对象、影响、理由和二次确认；资金与权限操作额外要求复核人。
+- 敏感值默认脱敏；查看完整值需单独权限、再次确认、限定时长，并记录操作者、目标、时间和用途。
+- 加载超过 2 秒展示骨架与取消，接口失败展示错误码、重试和上报入口，不长期停留空白页。
+- 操作成功后提供结果提示与审计编号；失败不得只显示“error”。
+
+## 3 C 端与后台功能映射
+
+后台不是独立工具，其配置和操作必须能解释 C 端每个入口、状态和金额。以下矩阵为联调的单一事实源。
+
+| C 端能力 | 后台来源 | 后台操作 | 一致性要求 |
+| --- | --- | --- | --- |
+| 首页横幅与快捷入口 | Banner、网站设置 | 排序、有效期、跳转、开关 | 发布后按版本生效 |
+| 平台简介/规则/公告 | 文本管理 | 富文本编辑、预览、发布 | CSP 与 HTML 白名单 |
+| 手工商城 | 手工商城 | 商品增删改、图片、价格、时间 | C 端仅显示已上架 |
+| 会员等级 | 会员等级 | 门槛、赠送、次数、佣金、提现次数 | 计算与展示同源 |
+| 领取中心 | 网站设置、商品、订单 | 营业时间、最低余额、匹配规则 | 服务端状态机判定 |
+| 订单记录 | 订单列表 | 查询、冻结、匹配、异常处理 | 业务单号和台账可追溯 |
+| 储入 | 充值管理 | 凭证、审核、入账、驳回 | 幂等入账与自动对账 |
+| 取出 | 提现管理、银行卡信息 | 收款资料、审核、通道、结果 | 金额、手续费、到账同源 |
+| 任务大厅与任务 | 任务大厅、任务列表、会员任务审核 | 配置、分发、审核 | 等级、佣金、状态一致 |
+| 个人资料 | 会员列表 | 资料、团队、状态、风控 | 敏感字段默认脱敏 |
+| 通知与弹幕 | 文本、会员弹幕 | 发布、定向、撤回、查看记录 | 真实性标识和审计 |
+| 客服 | 客服管理 | 客服入口、工作时间、会话映射 | 失败有备用通道 |
+
+![C 端与后台业务闭环原型](assets/prototype_06_flow.png)
+
+图 1  C 端与后台业务闭环（脱敏重绘原型）
+
+## 4 首页数据看板
+
+首页展示用户、商品、订单、充值、提现、佣金、利息宝转入、下级返佣与账户余额等汇总卡，并展示微信、支付宝和银行卡渠道统计。新系统应把口径、时间区间、刷新时间和数据延迟显式化。
+
+| 指标 | 定义 | 筛选维度 | 权限 |
+| --- | --- | --- | --- |
+| 用户总量/新增 | 去重有效会员数 | 今日、昨日、自定义日期 | 运营只读 |
+| 充值用户 | 至少一笔成功充值的会员数 | 时间、渠道、等级 | 财务/运营 |
+| 订单量与金额 | 按订单状态和完成时间统计 | 状态、商品、等级 | 运营/财务 |
+| 充值/提现 | 成功与待处理金额分开 | 渠道、状态、时间 | 财务 |
+| 佣金/返佣 | 任务佣金与层级返佣分开 | 类型、等级、时间 | 财务/审计 |
+| 账户余额 | 钱包可用与冻结余额总和 | 币种、账户状态 | 财务/审计 |
+
+- 卡片可点击进入对应明细页，并继承时间筛选；无权限用户只能看到隐藏金额或不可点击状态。
+- 页面顶部展示“数据截至时间”和刷新按钮；自动刷新不得造成重复请求风暴。
+
+![后台首页看板脱敏原型](assets/prototype_01_dashboard.png)
+
+图 2  后台首页看板（按实测界面脱敏重绘）
+
+## 5 门户、内容与 Banner 管理
+
+### 5.1 网站设置
+
+| 配置组 | 字段 | 要求 |
+| --- | --- | --- |
+| 品牌 | Logo、站点名称、隐私政策 URL | Logo 可预览；URL 仅允许 HTTPS 白名单 |
+| 交易 | 交易余额、等待时间、每日次数、奖励次数 | 数值范围校验；修改按版本发布 |
+| 佣金 | 0–5 级普通佣金 | Decimal；总和上限；法务开关 |
+| 时间 | 提现、充值、交易、签到时间 | 支持多区间；禁止结束早于开始 |
+| 门槛 | 最低充值、自动派单时间与金额 | 最小值≤最大值；币种与单位清晰 |
+| 开关 | 免费领取、手工商城、首页任务、签到、商品模式、验证码 | 每项写明 C 端影响和降级文案 |
+
+实测问题：交易等待时间输入框提示语与字段无关；签到时段出现“18:00–17:00”反向区间。新系统保存前必须做语义校验，并支持草稿、预览、发布、回滚。
+
+### 5.2 文本管理
+
+内容类型包括平台公告、平台简介、订单规则、代理合作、FAQ、指南、利息宝规则、首页滚动、订单提示、活动、首页弹窗和公司资质。编辑器需支持标题、正文、图片、链接、预览、定时发布、版本和回滚。
+
+- 富文本使用标签/属性白名单；禁止 script、事件属性、javascript: URL 和未知 iframe。
+- 现网编辑弹窗标题错误显示“编辑商品”，新系统标题必须与内容类型一致。
+
+### 5.3 Banner 设置
+
+支持多张首页 Banner 的上传、删除、排序、上下线、有效期、跳转类型与替代文本。上传前预览并校验尺寸、比例、MIME、文件大小和恶意内容。删除需要二次确认，已发布素材优先下线而非物理删除。
+
+### 5.4 手工商城
+
+列表字段为图片、名称、价格、时间与操作；新增/编辑字段为产品名称、价格、图片与展示时间。现网新增弹窗曾长时间停留 loading，需增加 8 秒超时、重试和错误上报。
+
+## 6 会员管理
+
+### 6.1 会员列表
+
+查询条件：用户名、手机号、注册时间、状态、自动派单。列表字段：ID、账号、绑卡姓名、用户名、账户余额、冻结金额、上级用户、邀请码、注册时间、最后登录 IP、IP 属地、自动抢单、状态、当日交易次数。
+
+| 操作 | 页面或弹窗 | 关键校验 | 审计要求 |
+| --- | --- | --- | --- |
+| 添加/编辑 | 会员表单 | 手机号唯一；余额不可由普通编辑修改；密码强度 | 记录前后值，密码永不回显 |
+| 银行卡信息 | 开户人、银行、电话、卡号、数字钱包、云闪付、收款码 | 必要性与格式；图片扫描 | 完整值查看留痕 |
+| 地址信息 | 姓名、电话、地区、详细地址 | 最小化收集；字段脱敏 | 查看和修改留痕 |
+| 查看团队 | 当前用户、层级、人数、余额、佣金、充值、提现 | 仅展示授权层级 | 导出单独授权 |
+| 账变 | 余额调整或流水 | 金额、类型、理由、业务单号 | 双人复核；不可直接改余额 |
+| 弹幕 | 会员定向或模拟内容 | 标注来源、有效期、撤回 | 禁止伪造真实用户行为 |
+| 奖励金 | 奖励金额与原因 | 非负、额度、幂等 | 财务复核与凭证 |
+| 设为假人 | 账号标记 | 不得混入真实统计或 C 端荣誉榜 | 仅测试环境默认启用 |
+| 禁用 | 账号状态 | 理由、范围、时长、申诉 | 双人复核；通知用户 |
+| 删除 | 软删除/注销 | 检查资金与订单；不可物理删台账 | 高风险二次确认 |
+
+> **P0 风险：** 现网页面默认显示完整手机号、姓名与登录 IP。新系统必须默认脱敏，按角色和目的临时授权查看；列表、导出、日志、埋点和截图统一执行同一脱敏规则。
+
+![会员列表脱敏原型](assets/prototype_02_member_list.png)
+
+图 3  会员列表脱敏原型
+
+![会员编辑弹窗原型](assets/prototype_03_member_modal.png)
+
+图 4  添加会员弹窗原型
+
+## 7 会员等级与任务大厅
+
+### 7.1 会员等级
+
+列表字段为等级名称、升级价格、赠送金额、接单次数、佣金比例和提现次数；支持编辑与受控删除。等级配置直接影响 C 端充值、领取和提现，必须使用版本化发布，不得修改后立即影响进行中的订单。
+
+| 规则 | 校验 | 生效策略 |
+| --- | --- | --- |
+| 升级价格/赠送金额 | ≥0；货币精度；赠送比例上限 | 新会员或下个结算周期 |
+| 接单次数 | 整数；按日重置时区明确 | 发布后次日生效 |
+| 佣金比例 | 0–1 Decimal；展示百分比 | 锁定到任务订单快照 |
+| 提现次数 | 整数；与提现时间窗一致 | 发布后次日生效 |
+| 删除等级 | 无有效会员与在途订单方可删除 | 优先停用并保留历史 |
+
+### 7.2 任务大厅
+
+页面字段为名称、图标、比例、简介、创建时间；新增弹窗还包含会员等级。实测列表接口直接显示“数据接口请求异常：error”，但新增弹窗可打开。新系统需要标准错误码、可重试状态、traceId 与空数据区分。
+
+- 任务大厅条目必须绑定可用会员等级、比例单位、图标和 C 端跳转。
+- 停用条目不影响已领取任务；删除仅允许无历史引用的数据，建议统一软删除。
+
+## 8 交易管理
+
+### 8.1 订单列表
+
+查询条件：订单号、手机号、用户名、日期；支持开启/关闭自动刷新。列表含绑卡姓名、用户名、自动派单、余额、手机号、当日交易次数、商品、数量、金额、佣金、下单时间、解冻时间、消息、订单状态、冻结状态和操作。
+
+| 状态 | 后台操作 | 约束 |
+| --- | --- | --- |
+| 匹配中 | 查看进度、取消匹配 | 同一会员仅一笔匹配；需幂等 |
+| 待处理 | 查看详情、发送提醒 | 不可手动完成；服务端倒计时 |
+| 冻结 | 查看风险、发起解冻复核 | 冻结理由、时长、申诉路径 |
+| 已完成 | 查看台账 | 金额、佣金、解冻三方一致 |
+| 异常/失败 | 重新匹配、人工处理申请 | 人工改状态必须双人审批 |
+
+### 8.2 充值管理
+
+顶部展示全部、用户已支付、用户未支付、手动审核、手动驳回等汇总金额。列表字段：订单号、真实姓名、手机号、余额、交易金额、打款凭证、添加时间、支付方式、类型、处理时间、备注和操作。
+
+- 审核通过前校验凭证、订单金额、收款主体、重复订单和账户状态；入账使用幂等键。
+- 驳回必须选择标准原因并可补充说明；通知 C 端且允许补充材料。
+
+### 8.3 提现管理
+
+查询条件：订单号、用户名、日期。列表含用户余额、提现金额、手续费、实际到账、银行名称、开户名称、银行卡号、云闪付、数字钱包、支付宝/微信收款码、发起与处理时间、操作。
+
+> **P0 风险：** 现网直接显示完整银行卡号与多个钱包账号。新系统列表只显示掩码，完整值不进入普通 DOM；付款处理时通过一次性授权查看，超时自动隐藏。
+
+![提现审核脱敏原型](assets/prototype_04_withdrawal.png)
+
+图 5  提现审核脱敏原型
+
+### 8.4 客服管理
+
+实测页面在加载后保持空白。新系统至少提供客服账号、名称、工作时间、在线状态、跳转 URL、排序、启停和会话映射；第三方 iframe 失败时显示备用联系方式和错误编号。
+
+## 9 商品与任务管理
+
+### 9.1 商品列表
+
+查询条件：商品名称、支付类型。列表：ID、图片、名称、商品价格、店铺名称、创建时间、是否推荐、操作。新增/编辑字段：商品名称、分类、店铺名称、商品单价、展示图片、商品详情富文本。
+
+- 推荐/不推荐为明确状态切换，提交前展示影响范围；列表筛选和 C 端排序一致。
+- 价格采用 Decimal；图片与富文本执行内容安全校验；商品被订单引用后只允许停用。
+
+### 9.2 任务列表
+
+按会员类型筛选；字段为任务编号、封面、标题、描述、等级、佣金、创建时间。新增弹窗含标题、描述、封面、等级、佣金和详情。实测新增任务弹窗标题误用“添加大厅任务”，需修正。
+
+### 9.3 会员任务审核
+
+按手机号、用户名查询；列表含记录 ID、用户名、手机、任务标题、等级、佣金、成功率、状态、备注、创建时间和操作。待审核记录支持通过与驳回。
+
+| 动作 | 前置条件 | 提交内容 | 结果 |
+| --- | --- | --- | --- |
+| 通过 | 任务存在、会员有效、未重复审核 | 审核意见、证据摘要、幂等键 | 发放佣金或进入结算队列 |
+| 驳回 | 记录为待审核 | 标准原因、补充说明、是否允许重提 | 通知会员并保留证据 |
+| 撤回审核 | 仅异常且未结算 | 变更单与复核人 | 冲正而非修改历史记录 |
+
+## 10 管理员、角色与权限
+
+### 10.1 后台管理员
+
+查询条件为登录名、手机、邮箱、角色；列表含姓名、登录名、手机号、邮箱、角色、更新时间和创建时间。新增字段为姓名、用户名、密码、手机、邮箱和多选角色。
+
+- 密码强度至少 12 位，禁止默认密码，首次登录强制改密；密码永不回显。
+- 禁用优先于删除；删除账号时保留历史审计主体，不得影响日志可追溯性。
+
+### 10.2 角色管理
+
+角色列表支持新增、编辑、删除和分配权限。分配弹窗为可展开/折叠的权限树。保存权限属于高风险操作，必须展示新增与移除差异，并由另一名管理员复核。
+
+### 10.3 权限管理
+
+权限树字段为 ID、名称、权限标识、父级 ID 和操作；支持添加顶级权限、添加子级、编辑、删除、展开/折叠。权限标识唯一且不可随意改名；被角色引用时禁止删除。
+
+![RBAC 角色权限原型](assets/prototype_05_rbac.png)
+
+图 6  建议 RBAC 权限矩阵
+
+## 11 数据字典与个人设置
+
+### 11.1 数据字典
+
+列表字段为 ID、名称、值、创建时间；支持新增、编辑、删除。现网同时存在英文 key、中文名称和缺失名称的条目，并与网站设置重复维护。建议将字典拆为“系统常量”和“业务配置”，以结构化 Schema 管理。
+
+| 字段 | 要求 |
+| --- | --- |
+| key | 全局唯一；小写或大写规范统一；发布后不可改名 |
+| value | 按 Schema 校验类型、范围、枚举、时间段和单位 |
+| description | 必填，说明业务含义、C 端影响和默认值 |
+| scope | 环境、租户、渠道、会员等级等作用域 |
+| version | 草稿、已发布、已回滚；记录生效时间 |
+| secret | 敏感配置不得明文显示，使用密钥管理系统 |
+
+### 11.2 基本资料
+
+字段为用户名（不可修改）、名称、手机、邮箱，提交按钮为“确认修改”。修改手机或邮箱需验证当前身份和新联系方式；成功后记录审计并通知原联系方式。
+
+### 11.3 修改密码
+
+字段为当前密码、新密码、确认新密码，现网提示 6–16 个字符。新系统建议至少 12 位并支持密码管理器；最终提交必须由用户本人完成，成功后撤销其他会话并发送安全通知。
+
+## 12 状态机与数据模型
+
+### 12.1 核心状态机
+
+| 实体 | 状态 | 允许转换 |
+| --- | --- | --- |
+| 会员 | 正常、受限、禁用、注销 | 正常→受限/禁用；复核后恢复；注销不可逆 |
+| 订单 | 匹配中、待处理、处理中、完成、超时、冻结、取消、失败 | 仅服务端状态机转换 |
+| 充值 | 待支付、待审核、成功、驳回、过期、取消 | 成功后只允许冲正 |
+| 提现 | 待审核、复核中、处理中、成功、失败、驳回、取消 | 付款前可取消；成功后只允许冲正 |
+| 任务审核 | 待审核、通过、驳回、已结算、已冲正 | 结算后不可回到待审核 |
+| 内容 | 草稿、待审、已发布、已下线、已归档 | 发布需审批；可回滚版本 |
+| 配置 | 草稿、待发布、已发布、已回滚 | 发布后生成不可变版本 |
+
+### 12.2 核心实体
+
+| 实体 | 关键字段 | 约束 |
+| --- | --- | --- |
+| AdminUser | id, loginName, roles, status, mfa, lastLogin | 管理员身份与会话 |
+| Role/Permission | roleId, permissionKey, scope | 最小权限与数据范围 |
+| Member | id, mobileEnc, nameEnc, levelId, status | 敏感字段加密、索引分离 |
+| Wallet | available, frozen, currency, version | 只允许台账事务修改 |
+| LedgerEntry | bizNo, type, amount, before, after, reversalOf | 不可变、幂等、可冲正 |
+| Order | orderNo, memberId, productSnapshot, amount, commission, status | 保存规则快照 |
+| Deposit/Withdrawal | bizNo, amount, fee, channel, status, reviewer | 审批链与支付回执 |
+| Content/Banner | type, body, version, publishAt, operator | 预览与版本化发布 |
+| ConfigVersion | key, value, schema, effectiveAt | 语义校验与回滚 |
+| AuditLog | actor, action, target, before, after, reason, traceId | 防篡改与长期留存 |
+
+## 13 推荐接口清单
+
+接口为新系统建议设计，统一前缀 /admin-api/v1。响应包含 data、code、message、traceId；所有写接口必须携带 Idempotency-Key，资金与权限写操作同时携带审批单号。
+
+| 方法 | 路径 | 用途 | 关键参数 |
+| --- | --- | --- | --- |
+| GET | /dashboard/summary | 首页指标 | timeRange, dimensions |
+| GET/PUT | /site-settings | 读取/保存站点配置草稿 | version, settings |
+| POST | /site-settings/publish | 发布配置 | draftVersion, reason |
+| GET/POST | /contents | 内容列表/新建 | type, status, body |
+| POST | /contents/{id}/publish | 内容发布 | publishAt, approver |
+| GET/POST | /banners | Banner 查询/新建 | imageAssetId, sort, target |
+| GET/POST | /members | 会员查询/新建 | filters, profile |
+| GET/PATCH | /members/{id} | 会员详情/编辑 | editableProfile, version |
+| POST | /members/{id}/adjustment-requests | 账变申请 | type, amount, reason, evidence |
+| POST | /members/{id}/status-requests | 禁用/解禁申请 | targetStatus, reason, duration |
+| GET/POST | /member-levels | 等级查询/草稿 | rules, effectiveAt |
+| GET/POST | /products | 商品查询/新建 | category, price, assets, detail |
+| GET/POST | /tasks | 任务查询/新建 | levelIds, commission, detail |
+| GET | /orders | 订单列表 | orderNo, member, status, timeRange |
+| POST | /orders/{id}/exception-requests | 异常处理申请 | action, reason |
+| GET | /deposits | 充值列表 | status, channel, timeRange |
+| POST | /deposits/{id}/review | 充值审核 | decision, reason, version |
+| GET | /withdrawals | 提现列表 | status, member, timeRange |
+| POST | /withdrawals/{id}/review | 提现审核 | decision, reason, version |
+| GET | /withdrawals/{id}/sensitive-view | 一次性查看收款信息 | purpose, challengeToken |
+| GET/POST | /task-submissions | 任务审核列表/决定 | decision, reason |
+| GET/POST | /admin-users | 管理员查询/新建 | profile, roleIds |
+| GET/POST | /roles | 角色查询/新建 | name, scope |
+| POST | /roles/{id}/permission-change-requests | 权限变更申请 | add, remove, reason |
+| GET | /audit-logs | 审计查询 | actor, action, target, timeRange |
+
+## 14 安全、隐私与审计
+
+| 风险 | 现网表现 | 新系统要求 | 优先级 |
+| --- | --- | --- | --- |
+| 个人信息裸露 | 完整手机号、姓名、IP | 默认脱敏；临时授权；全链路审计 | P0 |
+| 金融信息裸露 | 完整银行卡与钱包账号 | 应用层加密；非 DOM 展示；一次性查看 | P0 |
+| 资金单人操作 | 通过/驳回、账变、奖励入口直接可达 | 职责分离、双人复核、额度和幂等 | P0 |
+| 伪造行为 | 设为假人、弹幕入口 | 测试数据隔离；禁止混入真实榜单与统计 | P0 |
+| 富文本 XSS | 商品与内容支持富文本 | 白名单、CSP、上传扫描、预览隔离 | P0 |
+| 配置误发布 | 时间反向、字段提示错误 | Schema 校验、预览、审批、回滚 | P0 |
+| 接口不可用 | 任务大厅 error、客服空白 | 错误码、重试、熔断、监控和降级 | P1 |
+| 权限漂移 | 多角色与权限树直接保存 | 差异预览、审批、定期复核 | P0 |
+
+### 14.1 审计日志
+
+- 记录登录、查看敏感信息、导出、查询大范围数据、资金审核、账变、奖励、冻结、配置发布、权限变更和改密。
+- 字段至少包含操作者、角色、MFA、目标、动作、前值、后值、理由、审批人、IP、设备、traceId、时间和结果。
+- 日志写入独立存储并防篡改；业务管理员无删除权限；按监管与公司政策设定留存期。
+- 导出文件水印、加密、限时下载；下载与转发均可追踪。
+
+### 14.2 登录与会话
+
+- 管理员必须启用 MFA；高风险动作触发再次认证。
+- 闲置 15–30 分钟自动锁定；会话撤销、设备列表和异地登录提醒。
+- 连续失败触发限流与告警；不得依赖前端验证码作为唯一防护。
+- 服务端密码使用 Argon2id 或 bcrypt；任何日志、监控和前端状态都不得保存密码。
+
+## 15 非功能需求
+
+| 类别 | 目标 | 验收指标 |
+| --- | --- | --- |
+| 性能 | 常用列表与详情快速可用 | 列表 P95<1s；写操作 P95<1.5s；首屏<2.5s |
+| 可用性 | 关键交易全年可用 | 资金审核 99.95%；其余 99.9% |
+| 容量 | 支持 10 万会员与百万级订单 | 游标分页、索引与冷热分层 |
+| 并发 | 自动刷新与多运营并发安全 | 乐观锁、版本号、冲突提示 |
+| 可观测 | 定位每次请求与资金变更 | traceId、指标、日志、告警、审计关联 |
+| 兼容 | 主流桌面浏览器 | Chrome/Edge 最近两个稳定版；1366×768 可用 |
+| 可访问 | 键盘与读屏可操作 | 焦点、标签、颜色对比、44px 点击区 |
+| 灾备 | 配置与交易可恢复 | RPO≤5 分钟，RTO≤30 分钟；季度演练 |
+
+### 15.1 列表与弹窗通用验收
+
+- 查询条件、分页、排序、刷新后可恢复；空数据、加载中、失败、无权限均有独立状态。
+- 横向宽表固定关键列和操作列；敏感字段不因横向滚动或 tooltip 意外暴露。
+- 弹窗关闭与取消不产生写操作；表单脏数据关闭前提示；成功后只刷新受影响区域。
+- 重复点击、网络重试和浏览器回退不会重复创建、重复审核或重复入账。
+- 所有时间显示时区，金额显示币种和精度，百分比与小数含义统一。
+
+## 16 端到端验收场景
+
+| 编号 | 场景与验收路径 |
+| --- | --- |
+| A01 内容发布 | 运营新建公告→预览→提交审核→审批→定时发布→C 端显示相同版本→回滚 |
+| A02 会员查询 | 客服按掩码手机号查询→查看脱敏资料→申请查看完整值→审计留痕→超时隐藏 |
+| A03 任务闭环 | 配置任务→C 端领取→生成订单→提交→后台审核→佣金入账→台账核对 |
+| A04 充值审核 | C 端提交→后台待审核→重复回调→单次入账→通知→对账一致 |
+| A05 提现复核 | C 端申请→风控命中→财务初审→复核→通道付款→状态与到账金额一致 |
+| A06 禁用会员 | 客服发起→填写理由和时长→风控复核→会员受限→通知与申诉→解禁 |
+| A07 账变 | 运营申请奖励→财务复核→台账入账→重复提交被幂等拦截→审计可追溯 |
+| A08 权限变更 | 管理员申请新增提现审核权限→展示差异→复核→即时生效→历史会话重新鉴权 |
+| A09 配置错误 | 输入反向时间/非法比例→前后端阻止→错误定位到字段→不生成草稿版本 |
+| A10 服务降级 | 任务大厅 API 失败/客服 iframe 失败→清晰错误→重试/备用入口→告警产生 |
+
+### 16.1 发布门槛
+
+- P0 风险全部关闭；资金、权限、隐私与上传通过专项安全测试。
+- C 端和后台使用同一配置版本、状态枚举、金额口径和错误码。
+- 关键写操作完成幂等、并发、回滚、重试、超时与断网测试。
+- 审计日志可以从一次用户投诉还原完整操作者、审批链和资金流水。
+- 备份恢复、支付对账、权限复核和事故响应完成演练。
+
+## 17 研发里程碑
+
+| 阶段 | 范围 | 退出条件 |
+| --- | --- | --- |
+| M0 设计基线 | 信息架构、组件、状态机、RBAC、字段字典 | 产品/设计/技术/安全评审通过 |
+| M1 基础后台 | 登录、管理员、角色、权限、审计、内容、Banner | MFA、审计、发布流可用 |
+| M2 会员与配置 | 会员、等级、团队、配置中心 | 脱敏、临时授权、版本发布完成 |
+| M3 商品与任务 | 商品、任务、任务大厅、审核 | C 端联调与佣金快照通过 |
+| M4 交易与资金 | 订单、充值、提现、对账、复核 | 支付沙箱、幂等、双人复核通过 |
+| M5 运营与稳定性 | 看板、客服、监控、灾备、性能 | SLO、告警、恢复演练通过 |
+
+### 17.1 建议开发顺序
+
+1. 先建设统一认证、RBAC、审计、脱敏和配置发布，再开发具体业务页。
+1. 会员、商品、任务可先使用模拟资金；充值和提现必须最后接真实通道。
+1. 资金域上线前实行沙箱、小流量、额度限制和人工对账。
+1. 上线后第一周每日权限复核、账务核对和错误率复盘。
+
+## 18 原型图说明
+
+文档中的界面图按实测后台的布局、菜单、表格、弹窗和业务字段脱敏重绘，可直接用于讨论信息层级和交互。它们不是视觉稿：品牌、颜色、图标和真实数据应在 UI 设计阶段重新建立。
+
+### 18.1 首页看板（脱敏重绘）
+
+![后台首页看板脱敏原型](assets/prototype_01_dashboard.png)
+
+### 18.2 会员列表（脱敏重绘）
+
+![会员列表脱敏原型](assets/prototype_02_member_list.png)
+
+### 18.3 会员弹窗（脱敏重绘）
+
+![会员编辑弹窗原型](assets/prototype_03_member_modal.png)
+
+### 18.4 提现审核（脱敏重绘）
+
+![提现审核脱敏原型](assets/prototype_04_withdrawal.png)
+
+### 18.5 角色权限（脱敏重绘）
+
+![RBAC 角色权限原型](assets/prototype_05_rbac.png)
+
+### 18.6 业务闭环（脱敏重绘）
+
+![C 端与后台业务闭环原型](assets/prototype_06_flow.png)
+
+## 19 待确认事项
+
+- 目标系统是否处理真实资金，适用司法辖区、支付牌照与实名要求是什么。
+- “设为假人、弹幕、奖励金、层级返佣”是否保留；若保留，业务合法性和真实性如何证明。
+- 充值、提现、账变和会员禁用的初审/复核角色与金额阈值。
+- C 端现有接口能否修改，还是需要后台兼容旧字段和状态枚举。
+- 客服使用自建工单还是第三方服务，允许向第三方传输哪些数据。
+- 运营内容是否需要多语言、定时发布、区域差异与灰度发布。
+- 历史用户、订单、银行卡和台账的迁移范围、清洗规则和保留年限。
+- 生产环境数据导出、敏感值查看和紧急权限的审批人。
+
+在上述事项确认前，可以完成认证、RBAC、审计、内容、会员脱敏查询、商品任务配置和沙箱交易；不得接入真实收款、放款或自动资金调整。

docs/admin_reference_prd/第12章状态机与数据模型补强设计.md

@@ -0,0 +1,484 @@
+# 第 12 章状态机与数据模型补强设计
+
+> 文档版本：V1.0  
+> 编制日期：2026-10-08  
+> 依据：[后台管理系统需求文档](./后台管理系统需求文档.md)第 12 章  
+> 关联设计：[后台管理系统概要设计](./后台管理系统概要设计.md)  
+> 适用项目：`olons_admin`
+
+## 1. 文档目标
+
+本文档用于补齐需求文档第 12 章中尚未闭环的状态机、资金冲正、内容归档与历史版本回滚能力，作为数据库迁移、后端接口、前端操作、权限配置和测试验收的实施依据。
+
+本次设计遵循以下原则：
+
+1. 复用现有 HotGo 分层、字典、审批、审计、权限和多租户能力。
+2. 不修改已经投入使用的状态编号，只追加新状态或转换规则。
+3. 客户端只提交业务意图，最终状态由服务端状态机决定。
+4. 已生效资金不得修改或删除历史台账，只能生成反向流水冲正。
+5. 历史内容和配置不得原地覆盖，回滚必须生成新的草稿版本。
+6. 所有高风险执行都必须重新检查业务状态、审批状态和当前数据版本。
+
+## 2. 实施范围
+
+### 2.1 本期范围
+
+- 会员状态合法转换和注销不可逆。
+- 充值入账后的审批冲正。
+- 任务佣金结算后的审批冲正。
+- 文本内容归档和历史版本生成回滚草稿。
+- 状态转换、重复执行、并发执行和资金一致性测试。
+- 新增操作对应的菜单权限、业务审计和幂等保护。
+
+### 2.2 不在本期范围
+
+- 管理员 MFA 的真实认证流程。
+- 支付渠道退款接口和外部清算实现。
+- 新建独立的状态机管理页面。
+- 修改 HotGo 原有管理员、角色、字典和个人设置模块。
+- 直接修改 GoFrame CLI 生成的 `entity`、`do`、`dao/internal` 文件。
+
+MFA 数据字段继续保留，但真实验证码、再认证凭证和会话升级机制后续单独设计开发。
+
+## 3. 现状评估
+
+| 领域 | 已有能力 | 本次缺口 |
+| --- | --- | --- |
+| 会员 | 正常、禁用、注销；风险状态；双人审批；状态日志 | 未限制全部非法转换，注销后仍可能被旧审批恢复 |
+| 钱包 | 可用余额、冻结余额、乐观锁、不可变台账、幂等键、`reversal_of` | 充值和任务佣金尚未提供完整冲正入口 |
+| 充值 | 待支付、待审核、成功、驳回、过期、取消；审核入账 | 成功后无冲正状态、审批和执行流程 |
+| 任务审核 | 待审核、通过、驳回、已结算、已冲正；佣金台账字段 | 已冲正仅有字典和字段，缺少业务实现 |
+| 内容 | 草稿、待审、已发布、已下线、已归档；内容版本 | 缺少归档和历史版本生成回滚草稿接口 |
+| 配置 | 草稿、审批、发布、版本、回滚草稿 | 已满足本章要求，本期不重做 |
+| 审计 | Trace ID、前后摘要、哈希链、审批单号 | 新增流程需要补充结构化差异和冲正关联信息 |
+
+## 4. 状态机设计
+
+### 4.1 通用规则
+
+每个状态变更必须依次执行：
+
+1. 查询目标记录并加行锁。
+2. 校验记录存在且属于当前租户。
+3. 校验当前状态与申请时的 `fromStatus` 一致。
+4. 校验 `fromStatus → toStatus` 在允许转换表中。
+5. 校验审批已通过、尚未执行，且申请人与执行人符合职责分离要求。
+6. 在同一事务内完成业务状态、台账、审批执行时间和审计记录更新。
+7. 事务提交后再触发缓存清理、通知或 Outbox 事件。
+
+状态转换判断统一放在后端，不接受前端直接指定任意结果状态。
+
+### 4.2 会员状态
+
+现有会员状态编号保持不变：
+
+| 常量 | 值 | 含义 |
+| --- | ---: | --- |
+| `AppMemberStatusNormal` | 1 | 正常 |
+| `AppMemberStatusDisabled` | 2 | 禁用 |
+| `AppMemberStatusCancelled` | 3 | 已注销 |
+
+允许转换：
+
+| 当前状态 | 目标状态 | 是否允许 | 说明 |
+| --- | --- | --- | --- |
+| 正常 | 禁用 | 是 | 必须审批 |
+| 正常 | 注销 | 是 | 必须审批，执行后不可恢复 |
+| 禁用 | 正常 | 是 | 必须审批 |
+| 禁用 | 注销 | 是 | 必须审批 |
+| 注销 | 任意状态 | 否 | 注销不可逆 |
+| 任意状态 | 相同状态 | 否 | 防止无意义重复申请 |
+
+需求中的“受限”继续由现有 `risk_status` 表达，不新增或重排会员主状态：
+
+- `AppMemberRiskNormal`：正常。
+- `AppMemberRiskWatch`：观察或限制部分能力。
+- `AppMemberRiskBlocked`：拦截高风险能力。
+
+发起状态审批时保存 `fromStatus`；执行时必须重新比对。如果会员状态已变化，则旧审批失效，不得覆盖最新状态。
+
+### 4.3 充值状态
+
+保留现有 1～6 状态，追加：
+
+| 常量 | 值 | 含义 |
+| --- | ---: | --- |
+| `RechargeReversed` | 7 | 已冲正 |
+
+核心转换：
+
+| 当前状态 | 目标状态 | 触发方式 |
+| --- | --- | --- |
+| 用户未支付 | 手动审核 | 支付凭证或支付结果进入审核 |
+| 用户未支付 | 已过期/已取消 | 超时任务或用户取消 |
+| 手动审核 | 已入账 | 审批通过并写入入账台账 |
+| 手动审核 | 手动驳回 | 审批驳回 |
+| 已入账 | 已冲正 | 冲正审批通过并生成反向台账 |
+
+`已入账 → 已冲正` 是成功充值唯一允许的后续资金状态转换。已冲正记录不得再次冲正。
+
+### 4.4 任务审核状态
+
+保留现有状态编号：
+
+| 常量 | 值 | 含义 |
+| --- | ---: | --- |
+| `TaskSubmissionPending` | 1 | 待审核 |
+| `TaskSubmissionApproved` | 2 | 已通过 |
+| `TaskSubmissionRejected` | 3 | 已驳回 |
+| `TaskSubmissionSettled` | 4 | 已结算 |
+| `TaskSubmissionReversed` | 5 | 已冲正 |
+
+当前佣金为同步结算时，可在同一事务中完成“待审核 → 已通过 → 已结算”，数据库最终状态为“已结算”；若以后改为异步结算，“已通过”可作为中间状态。
+
+允许转换：
+
+| 当前状态 | 目标状态 | 说明 |
+| --- | --- | --- |
+| 待审核 | 已驳回 | 保存驳回原因和是否允许重提 |
+| 待审核 | 已结算 | 审核通过并成功写入佣金台账 |
+| 已结算 | 已冲正 | 冲正审批通过并写入反向台账 |
+| 已驳回 | 其他状态 | 禁止；重新提交需生成新提交记录 |
+| 已冲正 | 其他状态 | 禁止 |
+
+### 4.5 内容状态
+
+使用现有 `BizPublishStatusOptions`：
+
+```text
+草稿 → 待审 → 已发布 → 已下线 → 已归档
+```
+
+规则：
+
+- 只有草稿可以提交审核。
+- 只有审批通过的版本可以发布。
+- 只有已发布内容可以下线。
+- 只有已下线内容可以归档。
+- 已归档内容不可直接编辑、发布或恢复。
+- 历史版本回滚不修改历史版本，而是复制为一个版本号更大的新草稿。
+
+站点配置继续使用现有“历史版本 → 新回滚草稿 → 审批 → 发布”流程，不增加直接覆盖线上配置的接口。
+
+## 5. 数据库变更
+
+新增迁移文件：
+
+```text
+server/storage/data/migrations/20261008_009_state_machine_hardening.sql
+```
+
+### 5.1 `hg_recharge_order`
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `reversal_approval_id` | bigint unsigned | 0 | 冲正审批单 ID |
+| `reversal_ledger_id` | bigint unsigned | 0 | 冲正台账 ID |
+| `reversed_at` | datetime(3) | NULL | 冲正执行时间 |
+
+建议增加索引：
+
+```sql
+KEY `idx_recharge_reversal_approval` (`tenant_id`,`reversal_approval_id`)
+```
+
+### 5.2 `hg_task_submission`
+
+保留已有 `reversal_approval_id`，新增：
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `reversal_ledger_id` | bigint unsigned | 0 | 佣金冲正台账 ID |
+| `reversed_at` | datetime(3) | NULL | 冲正执行时间 |
+
+建议增加索引：
+
+```sql
+KEY `idx_task_submission_reversal` (`tenant_id`,`reversal_approval_id`)
+```
+
+### 5.3 `hg_content_version`
+
+为了保留回滚来源，新增：
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `base_version_id` | bigint unsigned | 0 | 新版本来源的历史版本 ID |
+
+正常新增版本可为 0；通过回滚生成的新草稿必须保存来源版本 ID。
+
+### 5.4 生成代码
+
+迁移执行后，使用 GoFrame CLI 重新生成下列表对应的代码：
+
+- `hg_recharge_order`
+- `hg_task_submission`
+- `hg_content_version`
+
+生成范围包括 `entity`、`do`、`dao/internal` 和 `dao`，禁止手工修改生成文件。
+
+## 6. 后端接口设计
+
+### 6.1 会员状态
+
+复用现有接口：
+
+- `POST /appMember/statusRequest`
+- `POST /appMember/statusExecute`
+
+补强内容：
+
+- `StatusRequest` 校验允许转换并写入申请时状态。
+- `StatusExecute` 锁定会员记录后再次校验允许转换。
+- 已注销会员禁止发起和执行任何恢复状态请求。
+- 业务审计必须记录 `before.memberStatus` 和 `after.memberStatus`。
+
+### 6.2 充值冲正
+
+新增接口：
+
+| 接口 | Method | 权限 | 说明 |
+| --- | --- | --- | --- |
+| `/rechargeOrder/reversalRequest` | POST | `/rechargeOrder/reversalRequest` | 发起充值冲正审批 |
+| `/rechargeOrder/reversalExecute` | POST | `/rechargeOrder/reversalExecute` | 执行已通过的充值冲正 |
+
+申请参数至少包括：
+
+- 充值单 ID。
+- 标准原因编码。
+- 补充说明。
+- 幂等键。
+- 证据附件或证据摘要，按现有 JSON 附件格式保存。
+
+申请前置条件：
+
+- 充值单状态为“已入账”。
+- 存在原入账台账。
+- 尚未发起或执行冲正。
+- 原审批和入账结果有效。
+
+执行必须在同一事务中：
+
+1. 锁定审批单、充值单、钱包账户和原台账。
+2. 校验审批已通过且未执行。
+3. 校验充值单仍为“已入账”。
+4. 校验原台账属于该充值单和该钱包。
+5. 生成金额相同、方向相反的新台账，并设置 `reversal_of=原台账ID`。
+6. 更新钱包余额和乐观锁版本，余额不得为负数。
+7. 更新充值单为“已冲正”，保存冲正审批、台账和时间。
+8. 标记审批已执行并写入业务审计。
+
+### 6.3 任务佣金冲正
+
+新增接口：
+
+| 接口 | Method | 权限 | 说明 |
+| --- | --- | --- | --- |
+| `/taskSubmission/reversalRequest` | POST | `/taskSubmission/reversalRequest` | 发起佣金冲正审批 |
+| `/taskSubmission/reversalExecute` | POST | `/taskSubmission/reversalExecute` | 执行已通过的佣金冲正 |
+
+申请前置条件：
+
+- 提交记录状态为“已结算”。
+- `ledger_id` 有效。
+- 尚未发起或执行冲正。
+- 必须填写标准原因和补充说明。
+
+执行逻辑与充值冲正一致，但业务状态更新为 `TaskSubmissionReversed`，冲正流水指向佣金原流水。
+
+### 6.4 内容归档与回滚
+
+新增接口：
+
+| 接口 | Method | 权限 | 说明 |
+| --- | --- | --- | --- |
+| `/content/archive` | POST | `/content/archive` | 将已下线内容归档 |
+| `/content/rollback` | POST | `/content/rollback` | 根据历史版本生成新草稿 |
+
+归档规则：
+
+- 当前内容必须为“已下线”。
+- 归档后不可编辑或直接重新发布。
+- 保存操作人、原因和审计记录。
+
+回滚规则：
+
+- 指定内容 ID 和历史版本 ID。
+- 历史版本必须属于该内容。
+- 新版本号为当前最大版本号加 1。
+- 复制历史版本正文、摘要、封面和附件信息。
+- 新版本状态为“草稿”，`base_version_id` 指向来源版本。
+- 不修改当前线上版本和历史版本。
+
+## 7. 后端代码影响范围
+
+按 HotGo 分层补充以下内容：
+
+| 层级 | 主要文件 |
+| --- | --- |
+| 常量与字典 | `server/internal/consts/trade.go`、`product_task.go`、`portal.go` |
+| API 契约 | `server/api/admin/rechargeorder/`、`tasksubmission/`、`portal/` |
+| Controller | `server/internal/controller/admin/sys/` 对应薄控制器 |
+| Service | 在 `server/internal/service/sys.go` 的现有接口中追加方法 |
+| Input | `server/internal/model/input/sysin/` 对应模块文件 |
+| Logic | `app_member.go`、`recharge_order.go`、`task_submission.go`、`portal.go` |
+| 路由 | 复用现有模块控制器注册，无需新增一级菜单 |
+| 迁移 | `20261008_009_state_machine_hardening.sql` |
+
+状态值合法性通过后端字典校验；字段名使用 `dao.Xxx.Columns()`，禁止在 Logic 中硬编码数据库列名。
+
+## 8. 前端设计
+
+不增加一级菜单，只在现有页面增加操作入口。
+
+### 8.1 充值管理
+
+- 状态为“已入账”且拥有申请权限时显示“申请冲正”。
+- 已存在冲正审批时显示审批状态，不允许重复申请。
+- 审批通过且拥有执行权限时显示“执行冲正”。
+- 已冲正记录显示原台账和冲正台账关联信息。
+
+### 8.2 会员任务审核
+
+- 状态为“已结算”时显示“申请冲正”。
+- 申请弹窗包含原因字典、补充说明和证据。
+- 审批通过后由有执行权限的管理员执行。
+- 状态为“已冲正”后不再显示审核或冲正按钮。
+
+### 8.3 文本管理
+
+- 已下线内容显示“归档”。
+- 历史版本列表显示“生成回滚草稿”。
+- 回滚前明确提示“不会覆盖当前线上版本”。
+- 已归档内容的编辑和发布按钮禁用。
+
+前端继续使用 Naive UI、`BasicTable`、`BasicForm`、`BasicModal` 和 `http.request`，状态标签通过后端字典渲染。
+
+## 9. 权限设计
+
+新增操作权限：
+
+```text
+/rechargeOrder/reversalRequest
+/rechargeOrder/reversalExecute
+/taskSubmission/reversalRequest
+/taskSubmission/reversalExecute
+/content/archive
+/content/rollback
+```
+
+权限规则：
+
+- 申请权限和执行权限分离。
+- 申请人不得审批或执行自己的高风险申请。
+- 执行接口必须独立校验权限，不能只依赖前端按钮隐藏。
+- 新权限通过 `hg_admin_menu` 的按钮类型记录配置，并授权给管理角色和业务角色。
+
+## 10. 台账、幂等与审计
+
+### 10.1 台账要求
+
+- 原台账不可更新和删除。
+- 冲正台账金额必须等于原台账金额。
+- 冲正台账方向必须与原台账相反。
+- `reversal_of` 必须指向原台账 ID。
+- 同一原台账只能存在一条有效冲正台账。
+- 钱包变更后必须满足 `after_amount = before_amount ± amount`。
+- 可用余额和冻结余额不得小于 0。
+
+### 10.2 幂等要求
+
+- 申请接口使用调用方传入的幂等键。
+- 执行接口以审批单 ID 和业务单 ID 共同保证幂等。
+- 重复执行已完成审批时返回清晰业务错误，不重复写钱包和台账。
+- 数据库唯一索引冲突必须转换为用户可理解的业务错误。
+
+### 10.3 审计要求
+
+业务审计至少记录：
+
+- 模块和动作。
+- 操作人、目标类型和目标 ID。
+- 原状态和目标状态。
+- 原台账 ID 和冲正台账 ID。
+- 冲正金额、原因和证据摘要。
+- 审批单号和 Trace ID。
+- 变更前后摘要与结构化差异。
+
+## 11. 异常与并发处理
+
+| 场景 | 处理要求 |
+| --- | --- |
+| 重复点击执行 | 只允许第一次成功，后续返回“审批已执行” |
+| 两个管理员同时执行 | 通过事务行锁保证只有一个事务成功 |
+| 审批后业务状态变化 | 拒绝执行，要求重新发起审批 |
+| 钱包余额不足以冲正 | 整体回滚，不产生台账和状态变化 |
+| 原台账不存在或归属不符 | 拒绝执行并记录 Warning 日志 |
+| 审批通过但事务失败 | 审批保持未执行，可排查后重试 |
+| 审计写入失败 | 核心事务整体回滚 |
+| 通知发送失败 | 不回滚核心事务，记录 Warning 并通过队列重试 |
+
+## 12. 测试方案
+
+### 12.1 状态机测试
+
+每个状态机都要覆盖：
+
+- 所有允许转换成功。
+- 所有禁止转换失败。
+- 相同状态重复申请失败。
+- 注销会员恢复失败。
+- 申请后状态变化导致执行失败。
+- 已执行审批重复执行失败。
+
+### 12.2 资金测试
+
+- 充值入账冲正后余额正确。
+- 任务佣金冲正后余额正确。
+- 原台账保持不变。
+- 冲正台账方向、金额和 `reversal_of` 正确。
+- 幂等键重复提交不产生重复台账。
+- 两个并发执行请求只生成一条冲正台账。
+- 余额不足时业务状态、钱包和台账均不变化。
+- 审计日志、审批单和台账可以相互追溯。
+
+### 12.3 内容测试
+
+- 只有已下线内容可以归档。
+- 已归档内容不可编辑和发布。
+- 历史版本回滚生成新草稿。
+- 回滚不改变当前发布版本。
+- 新草稿的 `base_version_id`、版本号和内容正确。
+
+### 12.4 回归测试
+
+- 原充值审核、提现审核和任务审核流程不受影响。
+- 原会员禁用和恢复流程仍可使用。
+- 原站点配置版本与回滚流程不受影响。
+- 字典加载、权限菜单和审计列表正常。
+
+## 13. 验收标准
+
+满足以下条件后视为第 12 章补强完成：
+
+1. 注销会员无法通过任何后台状态接口恢复。
+2. 充值成功后只能通过审批冲正，不允许直接修改余额或原台账。
+3. 已结算任务佣金可以通过审批冲正，且不可重复冲正。
+4. 每次冲正都能从业务单追溯到原台账、冲正台账、审批单和审计记录。
+5. 已下线内容可以归档，历史版本可以生成新草稿且不覆盖线上数据。
+6. 所有新增接口具有后端权限校验和明确的中文业务错误。
+7. 非法转换、重复执行、并发执行和余额不足测试全部通过。
+8. 后端编译、前端类型检查和现有模块回归测试通过。
+
+## 14. 推荐实施顺序
+
+1. 新增数据库迁移并用 GoFrame CLI 重新生成模型和 DAO。
+2. 补充状态字典和统一转换判断。
+3. 修复会员状态申请与执行校验。
+4. 实现充值冲正申请与执行。
+5. 实现任务佣金冲正申请与执行。
+6. 实现内容归档和历史版本回滚草稿。
+7. 增加按钮权限和角色授权。
+8. 增加前端操作按钮、弹窗和状态展示。
+9. 完成状态机、资金并发和回归测试。
+