Files

T

richjohnrambo f646a0cbf6 docs: add admin and development documentation

2026-10-10 20:56:36 +08:00

64 KiB

Raw Blame History

后台管理系统概要设计

文档版本：V1.0
编制日期：2026-10-08
依据：后台管理系统需求文档
技术基线：Go 1.24 + GoFrame v2.10 + Vue 3 + TypeScript + Naive UI + MySQL 8.0 + Redis

1. 文档目标
2. 设计原则
3. 技术架构
4. 系统模块设计
5. 核心业务流程
6. 数据库设计
7. 字典与状态设计
8. 接口设计约定
9. 缓存、队列与定时任务
10. 安全设计
11. 可观测性与运维
12. 性能与容量设计
13. 开发与数据库迁移顺序
14. 测试策略
15. 分阶段交付
16. 需进一步确认的设计决策

1. 文档目标

本文档用于将需求基线转换为可实施的系统概要设计，作为后续详细设计、数据库建模、接口定义、代码开发、测试与上线评审的共同输入。

本版设计重点解决：

C 端与后台在配置、状态、金额和业务单号上的一致性。
会员隐私数据、银行卡与钱包账户的加密、脱敏、临时授权和审计。
充值、提现、账变、奖励金等资金操作的幂等、台账、冻结、复核与冲正。
站点配置、文本、Banner、会员等级等高影响配置的草稿、审批、发布、版本和回滚。
管理员 RBAC、数据权限、敏感操作复核与不可篡改审计。

1.1 范围边界

本设计覆盖需求文档中的 21 个后台页面和对应 C 端业务闭环。不包含支付机构的具体 SDK 选型、实名认证供应商选型、法律合规结论和生产密钥管理实施细节。这些内容需在接入真实资金前单独评审。

2. 设计原则

单一事实源：字典、状态、金额口径和配置版本由后端统一提供，前端不硬编码枚举。
台账驱动资金：余额不允许普通 CRUD 直接修改，所有变动必须由不可变台账产生。
敏感数据分离：会员主表不保存可直接展示的完整敏感值；密文、检索哈希和脱敏值分字段存储。
最小权限：菜单权限、接口权限、数据权限和敏感值查看权限分层判定。
高风险双人复核：资金、权限、禁用会员和发布配置采用“申请人 ≠ 复核人”。
服务端状态机：客户端只发送意图，不直接指定结果状态。
可追溯与可冲正：已生效的资金与审批记录不原地覆盖，通过反向记录冲正。
兼容 HotGo 规范：遵循 api → controller → service → logic → dao 分层，字典由 internal/consts 注册，路由由 genrouter 加载。

3. 技术架构

flowchart LR
    A[后台 Web<br/>Vue 3 + Naive UI] -->|HTTPS /admin| B[GoFrame HTTP API]
    C[C 端] -->|HTTPS /api| B
    B --> D[认证、RBAC<br/>Casbin + Middleware]
    B --> E[业务 Service / Logic]
    E --> F[(MySQL 8.0)]
    E --> G[(Redis / Cache)]
    E --> H[对象存储<br/>附件/凭证/图片]
    E --> I[队列 / Outbox]
    I --> J[通知、统计、对账消费者]
    E --> K[支付/客服/实名等外部服务]
    B --> L[日志、Trace、指标、告警]

3.1 部署单元

单元	职责	状态
`web`	后台 SPA，路由由后端菜单驱动	无状态
`server`	管理 API、C 端 API、业务状态机、审批和台账	无状态，可水平扩展
MySQL	核心业务数据、台账、审批和审计	主从/高可用
Redis	会话、限流、短期缓存、分布式锁	不作资金最终事实源
对象存储	Banner、商品、任务、凭证和收款码	通过 `hg_sys_attachment` 管理元数据
队列	通知、统计、回调重试和对账	必须与 Outbox 表组合

3.2 代码模块划分

本项目属于系统核心业务，采用主模块实现，不作为临时 Addon。

业务域	后端模块建议	前端视图建议
看板	`dashboard`	`views/dashboard/business`
站点与内容	`siteConfig`, `content`, `banner`, `customerService`	`views/content/*`
会员	`appMember`, `memberLevel`, `memberPaymentAccount`	`views/member/*`
商品	`productCategory`, `product`	`views/product/*`
任务	`taskHall`, `task`, `taskSubmission`	`views/task/*`
交易	`tradeOrder`, `recharge`, `withdrawal`	`views/trade/*`
资产	`wallet`, `walletLedger`, `walletAdjustment`	`views/finance/*`
治理	`approval`, `sensitiveAccess`, `bizAudit`	`views/governance/*`

每个模块依次在以下位置实现：

server/api/admin/<module>/
server/internal/controller/admin/sys/<module>.go
server/internal/service/sys.go
server/internal/logic/sys/<module>.go
server/internal/model/input/sysin/<module>.go
server/internal/router/genrouter/<module>.go
web/src/api/<module>/index.ts
web/src/views/<module>/

4. 系统模块设计

4.1 认证与权限

复用现有 hg_admin_member、hg_admin_role、hg_admin_menu、hg_admin_member_role、hg_admin_role_menu 和 Casbin 能力。

权限判定顺序：

校验管理员会话、账号状态和 MFA 状态。
按路由权限标识判定功能权限。
通过 handler.FilterAuth 或 FilterAuthWithField 施加数据范围。
对完整手机号、银行卡、收款码等额外校验敏感值查看权限和二次认证。
资金、权限和配置发布类操作进入审批流，申请人不得审批自己的申请。

4.2 站点配置与内容发布

站点配置按版本存储为 JSON，同时记录 Schema 版本、摘要和生效时间。
业务代码不从零散 key-value 直接组装核心规则，而是读取唯一的“已发布版本”。
文本内容使用主表 + 版本表；发布仅更新主表的 published_version_id。
Banner 和客服渠道为结构化数据，支持有效期、排序、启停和作用域。
发布后删除缓存，通过 Outbox 发送“配置已更新”事件。

4.3 会员与隐私数据

C 端会员使用 hg_app_member，不与后台管理员 hg_admin_member 混用。
登录检索使用 mobile_hash，列表展示使用 mobile_mask，完整手机号仅存在 mobile_cipher。
哈希使用带服务端 Pepper 的 HMAC-SHA-256，避免穷举原始手机号。
收款账户、地址和身份信息分表存储，列表查询不联表返回完整密文。
敏感值查看接口使用一次性授权令牌，返回短时数据，不缓存且写入专用审计表。

4.4 商品、任务和交易订单

商品、任务和会员等级均可停用；被历史订单引用后不得物理删除。
交易订单保存商品、任务、等级和佣金规则快照，后续修改基础配置不影响在途订单。
订单状态由 Logic 层状态机转换，更新时携带 version 作为乐观锁。
任务提交通过独立审核表流转，任务通过后由结算服务写入佣金台账。

4.5 钱包与资金安全

资金字段统一使用 bigint 存储最小货币单位（CNY 为分），字段名以 _amount 或 _balance 结尾，不使用 float64 参与资金计算。每个资金动作在单个数据库事务内完成：

锁定业务单和钱包行。
校验业务单状态、幂等键、可用/冻结余额和审批结果。
写入不可变台账，台账同时记录变更前后值。
更新钱包汇总值和版本号。
更新业务单状态并写入 Outbox 事件。
事务提交后异步通知 C 端、更新看板和执行对账。

4.6 统一审批

hg_approval_request 和 hg_approval_action 提供通用审批能力，覆盖：

提现审核与大额复核。
人工充值、账变、奖励金和冲正。
会员禁用、解禁和异常解冻。
角色权限变更。
站点配置、会员等级和重要内容发布。

审批请求保存目标类型、目标 ID、操作类型、变更摘要和完整 payload 快照。业务表只引用审批单号，审批通过后由对应业务 Logic 执行最终变更。

5. 核心业务流程

5.1 充值入账

sequenceDiagram
    participant U as C 端会员
    participant API as API
    participant P as 支付渠道
    participant R as 充值订单
    participant W as 钱包/台账
    U->>API: 创建充值订单
    API->>R: 写入 pending_payment
    API->>P: 创建支付
    P-->>API: 异步回调
    API->>R: 验签、金额、商户、幂等校验
    API->>W: 事务内写台账并增加余额
    API->>R: 置为 success
    API-->>U: 通知到账

人工凭证充值不经过自动回调，进入初审和复核。两条路径共用同一个入账方法和幂等约束。

5.2 提现与资金冻结

stateDiagram-v2
    [*] --> pending_review: 提交申请并冻结金额
    pending_review --> reviewing: 初审通过
    pending_review --> rejected: 初审驳回
    reviewing --> processing: 复核通过
    reviewing --> rejected: 复核驳回
    processing --> success: 通道付款成功
    processing --> failed: 付款失败
    pending_review --> cancelled: 会员撤销
    rejected --> [*]: 解冻
    cancelled --> [*]: 解冻
    failed --> pending_review: 审核后重试
    success --> [*]: 扣减冻结金额

创建提现订单时立即将 available_balance 转入 frozen_balance；驳回或撤销时解冻；付款成功时扣减冻结余额。每一步均产生台账。

5.3 任务审核与佣金

会员领取任务时生成交易订单，固化商品、任务、等级和佣金快照。
会员提交任务证据，产生 task_submission。
后台审核通过时更新提交记录，调用结算服务写入佣金台账。
同一提交记录仅允许产生一笔有效佣金台账。
已结算记录如需撤销，必须新建冲正审批并写入反向台账。

5.4 配置发布

编辑者基于已发布版本创建草稿。
前端完成基础校验，后端 Filter() 完成 Schema 和跨字段校验。
提交审批后草稿锁定，禁止再编辑。
审批人查看前后差异并通过或驳回。
即时或定时发布，原版本置为历史版本。
清理配置缓存，通知 C 端与后台重新拉取版本。

6. 数据库设计

6.1 数据库基线

生产基线为 MySQL 8.0，存储引擎 InnoDB，字符集 utf8mb4，排序规则统一为 utf8mb4_0900_ai_ci。
时间字段使用 datetime(3) 保存 UTC，展示时根据用户时区转换。
主键使用 bigint unsigned；全局业务单号使用时间有序 ID 或雪花 ID，字符串形式最长 32 位。
金额使用 bigint 最小货币单位；比例使用 int 万分比，10000 = 100%。
新增业务表使用 hg_ 前缀；不直接修改 CLI 生成的 entity、do 和 dao/internal。
为适配 HotGo 代码生成和多库兼容，业务关系使用逻辑外键 + 索引，默认不创建物理外键。
可编辑业务表使用软删除；台账、审批动作、回调、幂等、Outbox 和审计表禁止删除。

6.2 通用字段

所有新表至少包含 id、tenant_id 和 created_at。可编辑业务表默认使用以下完整模板；台账、审批动作、回调、幂等、Outbox 和审计等不可变表仅保留上述三个基础字段与各自明确定义的业务字段，不设置 updated_at、deleted_at、updated_by 和 deleted_by。

字段	类型	约束	说明
`id`	bigint unsigned	PK, auto_increment	主键
`tenant_id`	bigint unsigned	NOT NULL DEFAULT 0, INDEX	租户；单租户部署为 0
`status`	tinyint	NOT NULL DEFAULT 1, INDEX	仅需通用启停时复用 `sys_normal_disable`：1正常、2停用；已有完整业务状态字段的表可省略此字段
`sort`	int	NOT NULL DEFAULT 0	排序值，越小越靠前
`version`	int unsigned	NOT NULL DEFAULT 0	乐观锁
`remark`	varchar(500)	NULL	内部备注
`created_by`	bigint unsigned	NOT NULL DEFAULT 0	后台创建人；C 端创建时为 0
`updated_by`	bigint unsigned	NOT NULL DEFAULT 0	最后后台更新人
`deleted_by`	bigint unsigned	NOT NULL DEFAULT 0	软删除人
`created_at`	datetime(3)	NOT NULL	创建时间
`updated_at`	datetime(3)	NOT NULL	更新时间
`deleted_at`	datetime(3)	NULL, INDEX	软删除时间

6.3 表关系概览

一期共规划 39 张新业务表，按域划分如下：

业务域	表数	主要表
配置与内容	5	配置版本、内容与版本、Banner、客服渠道
会员	8	等级与版本、会员、隐私资料、地址、收款账户、会话、状态记录
商品与任务	7	分类、商品、任务大厅、任务、等级关系、任务提交
交易与资金	11	交易订单、钱包、台账、支付渠道、充值、提现、账变、审核、回调、对账
治理与可靠性	7	审批、敏感查看、审计、幂等、Outbox、看板汇总
通知	1	C 端通知

erDiagram
    APP_MEMBER_LEVEL ||--o{ APP_MEMBER : owns
    APP_MEMBER ||--|| APP_MEMBER_PROFILE : has
    APP_MEMBER ||--o{ APP_MEMBER_ADDRESS : has
    APP_MEMBER ||--o{ APP_MEMBER_PAYMENT_ACCOUNT : binds
    APP_MEMBER ||--o{ APP_MEMBER_SESSION : logs_in
    APP_MEMBER ||--|| WALLET_ACCOUNT : owns
    WALLET_ACCOUNT ||--o{ WALLET_LEDGER : produces
    PRODUCT_CATEGORY ||--o{ PRODUCT : contains
    TASK_HALL ||--o{ TASK_HALL_LEVEL : permits
    APP_MEMBER_LEVEL ||--o{ TASK_HALL_LEVEL : allowed
    TASK_HALL ||--o{ TASK : groups
    TASK ||--o{ TASK_LEVEL : permits
    APP_MEMBER_LEVEL ||--o{ TASK_LEVEL : allowed
    TASK ||--o{ TRADE_ORDER : creates
    APP_MEMBER ||--o{ TRADE_ORDER : places
    TRADE_ORDER ||--o| TASK_SUBMISSION : submits
    APP_MEMBER ||--o{ RECHARGE_ORDER : recharges
    APP_MEMBER ||--o{ WITHDRAWAL_ORDER : withdraws
    APP_MEMBER_PAYMENT_ACCOUNT ||--o{ WITHDRAWAL_ORDER : receives
    APPROVAL_REQUEST ||--o{ APPROVAL_ACTION : contains
    APPROVAL_REQUEST ||--o{ FINANCE_REVIEW : drives
    CONTENT ||--o{ CONTENT_VERSION : versions
    SITE_CONFIG_VERSION ||--o| APPROVAL_REQUEST : publishes
    PAYMENT_CHANNEL ||--o{ RECHARGE_ORDER : handles
    PAYMENT_CHANNEL ||--o{ WITHDRAWAL_ORDER : handles

6.4 现有系统表复用

表	用途	设计处理
`hg_admin_member`	后台管理员	直接复用，不存 C 端会员
`hg_admin_role` / `hg_admin_menu`	角色、菜单、接口权限	直接复用，增加业务菜单数据
`hg_admin_member_role` / `hg_admin_role_menu`	RBAC 关系	直接复用
`hg_sys_attachment`	文件与对象存储元数据	图片、凭证、收款码统一引用附件 ID
`hg_sys_dict_type` / `hg_sys_dict_data`	可维护字典	用于非核心动态选项
`hg_sys_config`	HotGo 系统自身配置	仅保留框架配置，不承载需审批的业务配置
`hg_sys_log` / `hg_sys_login_log`	请求与登录日志	保留，与业务审计表互补

字典功能不新建表、不新建 API、不另做前端 Store。统一复用 hg_sys_dict_type、hg_sys_dict_data、server/internal/library/dict、/dictData/option、/dictData/options 和 web/src/store/modules/dict.ts。详细复用规则见第 7 章。

6.5 配置与内容域

6.5.1 `hg_site_config_version` 站点配置版本

字段	类型	约束/索引	说明
`config_no`	varchar(32)	NOT NULL, UNIQUE(`tenant_id`,`config_no`)	配置版本号
`config_group`	varchar(64)	NOT NULL, INDEX	`site_basic`/`trade_rule`/`time_window` 等
`schema_version`	varchar(32)	NOT NULL	校验 Schema 版本
`config_json`	json	NOT NULL	完整配置快照
`config_digest`	char(64)	NOT NULL	SHA-256，用于差异与一致性校验
`publish_status`	tinyint	NOT NULL, INDEX	1草稿 2待审 3已发布 4已回滚 5已失效
`effective_at`	datetime(3)	NULL, INDEX	计划生效时间
`published_at`	datetime(3)	NULL	实际发布时间
`approval_request_id`	bigint unsigned	NOT NULL DEFAULT 0, INDEX	关联审批单
`base_version_id`	bigint unsigned	NOT NULL DEFAULT 0	基础版本

索引：INDEX idx_config_current (tenant_id, config_group, publish_status, effective_at)。同一租户和配置组在某一时点只允许一个有效已发布版本，由发布事务保证。

6.5.2 `hg_content` 内容主表

字段	类型	约束/索引	说明
`content_key`	varchar(64)	UNIQUE(`tenant_id`,`content_key`)	稳定内容标识，删除后不复用
`content_type`	varchar(32)	NOT NULL, INDEX	notice/about/faq/rule/activity/popup
`title`	varchar(200)	NOT NULL	后台标题
`published_version_id`	bigint unsigned	NOT NULL DEFAULT 0	当前发布版本
`publish_status`	tinyint	NOT NULL, INDEX	内容状态
`published_at`	datetime(3)	NULL	发布时间

6.5.3 `hg_content_version` 内容版本

字段	类型	约束/索引	说明
`content_id`	bigint unsigned	NOT NULL, INDEX	内容主表 ID
`version_no`	int unsigned	UNIQUE(`content_id`,`version_no`)	递增版本
`title`	varchar(200)	NOT NULL	展示标题
`summary`	varchar(500)	NULL	摘要
`body_html`	longtext	NOT NULL	服务端清洗后 HTML
`body_text`	longtext	NULL	搜索与降级文本
`asset_ids`	json	NULL	正文引用附件 ID
`publish_status`	tinyint	NOT NULL, INDEX	1草稿 2待审 3已发布 4已下线 5已归档
`effective_at`	datetime(3)	NULL	定时发布
`approval_request_id`	bigint unsigned	NOT NULL DEFAULT 0	审批单

6.5.4 `hg_banner` Banner

字段	类型	约束/索引	说明
`name`	varchar(100)	NOT NULL	后台名称
`position`	varchar(32)	NOT NULL, INDEX	home_top/home_popup 等
`image_attachment_id`	bigint unsigned	NOT NULL	图片附件
`alt_text`	varchar(200)	NOT NULL	替代文本
`target_type`	tinyint	NOT NULL	1无跳转 2内部路由 3外部 URL
`target_value`	varchar(500)	NULL	跳转值
`start_at` / `end_at`	datetime(3)	NULL, INDEX	有效期
`publish_status`	tinyint	NOT NULL, INDEX	草稿/已发布/已下线

6.5.5 `hg_customer_service_channel` 客服渠道

字段	类型	约束/索引	说明
`name`	varchar(100)	NOT NULL	渠道名称
`channel_type`	tinyint	NOT NULL	1内置工单 2外部链接 3客服电话 4即时通讯
`entry_url_cipher`	varchar(1024)	NULL	加密入口地址
`fallback_text`	varchar(500)	NULL	降级联系方式
`work_time_json`	json	NOT NULL	工作时段及时区
`allowed_origins`	json	NULL	iframe 来源白名单

6.6 会员域

6.6.1 `hg_app_member_level` 会员等级

字段	类型	约束/索引	说明
`level_code`	varchar(32)	UNIQUE(`tenant_id`,`level_code`)	稳定等级编码
`name`	varchar(64)	NOT NULL	等级名称
`current_version_id`	bigint unsigned	NOT NULL DEFAULT 0	当前规则版本
`member_count`	bigint unsigned	NOT NULL DEFAULT 0	可重建的统计值

6.6.2 `hg_app_member_level_version` 等级规则版本

字段	类型	约束/索引	说明
`level_id`	bigint unsigned	NOT NULL, INDEX	等级 ID
`version_no`	int unsigned	UNIQUE(`level_id`,`version_no`)	版本号
`upgrade_amount`	bigint	NOT NULL DEFAULT 0	升级金额，分
`gift_amount`	bigint	NOT NULL DEFAULT 0	赠送金额，分
`daily_order_limit`	int unsigned	NOT NULL DEFAULT 0	每日接单次数
`commission_rate`	int unsigned	NOT NULL DEFAULT 0	佣金万分比
`daily_withdraw_limit`	int unsigned	NOT NULL DEFAULT 0	每日提现次数
`rule_json`	json	NULL	扩展规则快照
`publish_status`	tinyint	NOT NULL, INDEX	发布状态
`effective_at`	datetime(3)	NULL	生效时间

6.6.3 `hg_app_member` C 端会员

字段	类型	约束/索引	说明
`member_no`	varchar(32)	UNIQUE(`tenant_id`,`member_no`)	对外会员号
`username`	varchar(64)	UNIQUE(`tenant_id`,`username`)	登录名，注销后不复用
`mobile_cipher`	varchar(512)	NOT NULL	手机号密文
`mobile_hash`	char(64)	UNIQUE(`tenant_id`,`mobile_hash`)	带 Pepper 检索哈希，注销后按合规策略做不可逆匿名化
`mobile_mask`	varchar(32)	NOT NULL	脱敏手机号
`password_hash`	varchar(255)	NOT NULL	Argon2id/bcrypt 结果
`trade_password_hash`	varchar(255)	NULL	交易密码，不可回显
`level_id`	bigint unsigned	NOT NULL, INDEX	会员等级
`parent_id`	bigint unsigned	NOT NULL DEFAULT 0, INDEX	直接上级
`level`	int unsigned	NOT NULL DEFAULT 1	关系树级别
`tree`	varchar(1024)	NOT NULL DEFAULT ''	关系树路径
`invite_code`	varchar(32)	UNIQUE(`tenant_id`,`invite_code`)	邀请码
`member_status`	tinyint	NOT NULL DEFAULT 1, INDEX	会员生命周期：正常/受限/禁用/注销
`risk_status`	tinyint	NOT NULL DEFAULT 1, INDEX	1正常 2观察 3限制 4冻结
`auto_dispatch`	tinyint	NOT NULL DEFAULT 2	复用 `sys_switch`：1开启、2关闭
`credit_score`	int	NOT NULL DEFAULT 100	信用分
`last_login_at`	datetime(3)	NULL	最后登录时间
`last_login_ip_cipher`	varchar(512)	NULL	加密 IP
`last_login_region`	varchar(128)	NULL	IP 地区粗粒度结果

重要索引：idx_member_parent (tenant_id,parent_id,status)、idx_member_level (tenant_id,level_id,status)、idx_member_created (tenant_id,created_at,id)。

6.6.4 `hg_app_member_profile` 会员隐私资料

字段	类型	约束/索引	说明
`member_id`	bigint unsigned	UNIQUE	会员 ID
`real_name_cipher`	varchar(512)	NULL	姓名密文
`real_name_mask`	varchar(64)	NULL	脱敏姓名
`id_no_cipher`	varchar(1024)	NULL	证件号密文
`id_no_hash`	char(64)	NULL, INDEX	证件检索哈希
`id_no_mask`	varchar(64)	NULL	脱敏证件号
`avatar_attachment_id`	bigint unsigned	NOT NULL DEFAULT 0	头像
`kyc_status`	tinyint	NOT NULL DEFAULT 0, INDEX	0未认证 1审核中 2已认证 3驳回
`kyc_verified_at`	datetime(3)	NULL	认证时间

6.6.5 `hg_app_member_address` 会员地址

字段	类型	约束/索引	说明
`member_id`	bigint unsigned	NOT NULL, INDEX	会员 ID
`receiver_name_cipher` / `receiver_name_mask`	varchar(512)/varchar(64)	NOT NULL	收件人密文/脱敏值
`receiver_mobile_cipher` / `receiver_mobile_mask`	varchar(512)/varchar(32)	NOT NULL	电话密文/脱敏值
`province_id` / `city_id` / `district_id`	bigint unsigned	NOT NULL DEFAULT 0	省市区
`address_cipher`	varchar(1024)	NOT NULL	详细地址密文
`is_default`	tinyint	NOT NULL DEFAULT 0	默认地址

6.6.6 `hg_app_member_payment_account` 收款账户

字段	类型	约束/索引	说明
`member_id`	bigint unsigned	NOT NULL, INDEX	会员 ID
`account_type`	tinyint	NOT NULL, INDEX	1银行卡 2数字钱包 3云闪付 4支付宝 5微信
`bank_code`	varchar(32)	NULL	银行编码
`bank_name`	varchar(100)	NULL	银行名称快照
`holder_name_cipher` / `holder_name_mask`	varchar(512)/varchar(64)	NOT NULL	户名
`account_no_cipher`	varchar(1024)	NOT NULL	账号密文
`account_no_hash`	char(64)	NOT NULL, INDEX	检索与去重哈希
`account_no_mask`	varchar(64)	NOT NULL	脱敏账号
`qr_attachment_id`	bigint unsigned	NOT NULL DEFAULT 0	收款码附件
`verify_status`	tinyint	NOT NULL DEFAULT 0	校验状态
`is_default`	tinyint	NOT NULL DEFAULT 0	默认收款账户

唯一约束：UNIQUE (tenant_id,member_id,account_type,account_no_hash)。已解绑账户可重新启用，不重复插入。MySQL 中 NULL 不能可靠表示“仅未删除数据唯一”，因此本设计不将可空 deleted_at 加入唯一索引。

6.6.7 `hg_app_member_session` 会员会话

字段	类型	约束/索引	说明
`member_id`	bigint unsigned	NOT NULL, INDEX	会员 ID
`session_no`	varchar(64)	UNIQUE	会话号
`refresh_token_hash`	char(64)	NOT NULL	刷新令牌哈希
`device_id_hash`	char(64)	NULL, INDEX	设备标识哈希
`ip_cipher`	varchar(512)	NULL	IP 密文
`user_agent`	varchar(512)	NULL	客户端信息
`expires_at`	datetime(3)	NOT NULL, INDEX	过期时间
`revoked_at`	datetime(3)	NULL	撤销时间

6.6.8 `hg_app_member_status_log` 会员状态记录

字段	类型	约束/索引	说明
`member_id`	bigint unsigned	NOT NULL, INDEX	会员 ID
`from_status` / `to_status`	tinyint	NOT NULL	状态变更
`reason_code`	varchar(64)	NOT NULL	标准原因
`reason_text`	varchar(500)	NULL	补充说明
`effective_at` / `expire_at`	datetime(3)	NULL	生效和到期时间
`approval_request_id`	bigint unsigned	NOT NULL DEFAULT 0	审批单
`operator_id`	bigint unsigned	NOT NULL	操作人

该表为追加表，不软删除。

6.7 商品与任务域

6.7.1 `hg_product_category` 商品分类

字段	类型	约束/索引	说明
`pid`	bigint unsigned	NOT NULL DEFAULT 0, INDEX	父级 ID
`level`	int unsigned	NOT NULL DEFAULT 1	树等级
`tree`	varchar(512)	NOT NULL DEFAULT ''	关系树
`category_code`	varchar(32)	UNIQUE(`tenant_id`,`category_code`)	分类编码
`name`	varchar(100)	NOT NULL	分类名称

6.7.2 `hg_product` 商品

字段	类型	约束/索引	说明
`product_no`	varchar(32)	UNIQUE(`tenant_id`,`product_no`)	商品编号
`category_id`	bigint unsigned	NOT NULL, INDEX	分类
`product_type`	tinyint	NOT NULL DEFAULT 1, INDEX	1标准商品 2手工商城商品
`payment_type`	varchar(32)	NOT NULL DEFAULT 'balance', INDEX	优先复用并按需扩展现有 `payType` 枚举字典
`name`	varchar(200)	NOT NULL, INDEX	商品名称
`shop_name`	varchar(100)	NOT NULL	店铺名称快照
`price_amount`	bigint	NOT NULL	单价，分
`currency`	char(3)	NOT NULL DEFAULT 'CNY'	币种
`cover_attachment_id`	bigint unsigned	NOT NULL	封面
`detail_html`	longtext	NULL	清洗后富文本
`is_recommended`	tinyint	NOT NULL DEFAULT 2, INDEX	复用 `sys_switch`：1推荐、2不推荐
`publish_status`	tinyint	NOT NULL, INDEX	草稿/上架/下架
`start_at` / `end_at`	datetime(3)	NULL	展示时间

6.7.3 `hg_task_hall` 任务大厅

字段	类型	约束/索引	说明
`hall_code`	varchar(32)	UNIQUE(`tenant_id`,`hall_code`)	大厅编码
`name`	varchar(100)	NOT NULL	名称
`icon_attachment_id`	bigint unsigned	NOT NULL	图标
`summary`	varchar(500)	NULL	简介
`commission_rate`	int unsigned	NOT NULL DEFAULT 0	万分比
`publish_status`	tinyint	NOT NULL, INDEX	发布状态

6.7.4 `hg_task_hall_level` 任务大厅可用等级

字段	类型	约束/索引	说明
`id`	bigint unsigned	PK, auto_increment	主键
`tenant_id`	bigint unsigned	NOT NULL DEFAULT 0	租户
`hall_id`	bigint unsigned	NOT NULL, INDEX	任务大厅
`level_id`	bigint unsigned	NOT NULL, INDEX	会员等级
`created_at`	datetime(3)	NOT NULL	创建时间

唯一约束：UNIQUE (tenant_id,hall_id,level_id)。

6.7.5 `hg_task` 任务

字段	类型	约束/索引	说明
`task_no`	varchar(32)	UNIQUE(`tenant_id`,`task_no`)	任务编号
`hall_id`	bigint unsigned	NOT NULL, INDEX	任务大厅
`title`	varchar(200)	NOT NULL	标题
`description`	varchar(1000)	NULL	描述
`detail_html`	longtext	NULL	详情
`cover_attachment_id`	bigint unsigned	NOT NULL	封面
`commission_amount`	bigint	NOT NULL DEFAULT 0	固定佣金，分
`commission_rate`	int unsigned	NOT NULL DEFAULT 0	比例佣金，万分比
`daily_limit`	int unsigned	NOT NULL DEFAULT 0	每日总量，0 不限
`per_member_limit`	int unsigned	NOT NULL DEFAULT 1	单会员限制
`start_at` / `end_at`	datetime(3)	NULL, INDEX	任务周期
`publish_status`	tinyint	NOT NULL, INDEX	发布状态

6.7.6 `hg_task_level` 任务可用等级

字段	类型	约束/索引	说明
`id`	bigint unsigned	PK, auto_increment	主键
`tenant_id`	bigint unsigned	NOT NULL DEFAULT 0	租户
`task_id`	bigint unsigned	NOT NULL, INDEX	任务
`level_id`	bigint unsigned	NOT NULL, INDEX	会员等级
`created_at`	datetime(3)	NOT NULL	创建时间

唯一约束：UNIQUE (tenant_id,task_id,level_id)。

6.7.7 `hg_task_submission` 会员任务提交

字段	类型	约束/索引	说明
`submission_no`	varchar(32)	UNIQUE	提交单号
`trade_order_id`	bigint unsigned	UNIQUE	交易订单
`task_id`	bigint unsigned	NOT NULL, INDEX	任务
`member_id`	bigint unsigned	NOT NULL, INDEX	会员
`evidence_text`	varchar(2000)	NULL	提交说明
`evidence_attachment_ids`	json	NULL	证据附件 ID
`submission_status`	tinyint	NOT NULL, INDEX	1待审 2通过 3驳回 4已结算 5已冲正
`commission_amount`	bigint	NOT NULL DEFAULT 0	审核时的佣金快照
`reviewed_by`	bigint unsigned	NOT NULL DEFAULT 0	审核人
`reviewed_at`	datetime(3)	NULL	审核时间
`review_reason`	varchar(500)	NULL	审核意见
`settled_at`	datetime(3)	NULL	结算时间

6.8 交易与资金域

6.8.1 `hg_trade_order` 交易订单

字段	类型	约束/索引	说明
`order_no`	varchar(32)	UNIQUE	订单号
`member_id`	bigint unsigned	NOT NULL, INDEX	会员
`task_id` / `product_id`	bigint unsigned	NOT NULL DEFAULT 0, INDEX	任务/商品
`order_type`	tinyint	NOT NULL, INDEX	1商品 2任务 3手工商城
`quantity`	int unsigned	NOT NULL DEFAULT 1	数量
`unit_price_amount`	bigint	NOT NULL	单价，分
`total_amount`	bigint	NOT NULL	订单金额，分
`commission_amount`	bigint	NOT NULL DEFAULT 0	佣金，分
`currency`	char(3)	NOT NULL DEFAULT 'CNY'	币种
`member_level_id`	bigint unsigned	NOT NULL	下单时等级
`rule_snapshot`	json	NOT NULL	商品、等级、佣金规则快照
`order_status`	tinyint	NOT NULL, INDEX	匹配中/待处理/处理中/完成/超时/冻结/取消/失败
`freeze_status`	tinyint	NOT NULL DEFAULT 0	冻结状态
`matched_at` / `completed_at` / `unfrozen_at`	datetime(3)	NULL	业务节点

索引：idx_order_member_time (tenant_id,member_id,created_at,id)、idx_order_status_time (tenant_id,order_status,created_at,id)。

6.8.2 `hg_wallet_account` 钱包账户

字段	类型	约束/索引	说明
`member_id`	bigint unsigned	UNIQUE(`tenant_id`,`member_id`,`currency`)	会员
`currency`	char(3)	NOT NULL DEFAULT 'CNY'	币种
`available_balance`	bigint	NOT NULL DEFAULT 0	可用余额，分
`frozen_balance`	bigint	NOT NULL DEFAULT 0	冻结余额，分
`total_income`	bigint	NOT NULL DEFAULT 0	累计收入，可重建
`total_expense`	bigint	NOT NULL DEFAULT 0	累计支出，可重建
`account_status`	tinyint	NOT NULL DEFAULT 1	1正常 2只收不付 3冻结 4关闭
`version`	int unsigned	NOT NULL DEFAULT 0	乐观锁

检查约束：available_balance >= 0、frozen_balance >= 0。

6.8.3 `hg_wallet_ledger` 钱包台账

字段	类型	约束/索引	说明
`ledger_no`	varchar(32)	UNIQUE	台账号
`account_id`	bigint unsigned	NOT NULL, INDEX	钱包账户
`member_id`	bigint unsigned	NOT NULL, INDEX	会员
`biz_type`	varchar(32)	NOT NULL, INDEX	recharge/withdraw/freeze/unfreeze/commission/adjust/reversal
`biz_no`	varchar(32)	NOT NULL	业务单号
`entry_type`	tinyint	NOT NULL	1可用余额 2冻结余额
`direction`	tinyint	NOT NULL	1收入 2支出
`amount`	bigint	NOT NULL	变动绝对值，分
`before_balance` / `after_balance`	bigint	NOT NULL	变动前后值
`currency`	char(3)	NOT NULL	币种
`reversal_of`	bigint unsigned	NOT NULL DEFAULT 0, INDEX	被冲正台账 ID
`idempotency_key`	varchar(128)	NOT NULL	幂等键
`occurred_at`	datetime(3)	NOT NULL, INDEX	业务发生时间
`created_at`	datetime(3)	NOT NULL	入库时间

唯一约束：UNIQUE (account_id,idempotency_key)。表中不设置 updated_at、deleted_at，禁止 UPDATE 和 DELETE。

6.8.4 `hg_payment_channel` 支付渠道

字段	类型	约束/索引	说明
`channel_code`	varchar(32)	UNIQUE(`tenant_id`,`channel_code`)	渠道编码
`name`	varchar(100)	NOT NULL	渠道名称
`channel_type`	tinyint	NOT NULL, INDEX	1微信 2支付宝 3银行卡 4人工
`direction`	tinyint	NOT NULL	1充值 2提现 3双向
`config_cipher`	longtext	NULL	渠道密钥加密密文，不返回前端
`min_amount` / `max_amount`	bigint	NOT NULL DEFAULT 0	金额限制
`fee_type`	tinyint	NOT NULL DEFAULT 1	1固定 2比例 3混合
`fee_fixed_amount`	bigint	NOT NULL DEFAULT 0	固定手续费
`fee_rate`	int unsigned	NOT NULL DEFAULT 0	费率万分比

6.8.5 `hg_recharge_order` 充值订单

字段	类型	约束/索引	说明
`recharge_no`	varchar(32)	UNIQUE	充值单号
`member_id`	bigint unsigned	NOT NULL, INDEX	会员
`channel_id`	bigint unsigned	NOT NULL, INDEX	支付渠道
`request_amount` / `paid_amount`	bigint	NOT NULL	申请/实付金额
`currency`	char(3)	NOT NULL DEFAULT 'CNY'	币种
`external_no`	varchar(128)	NULL, INDEX	外部支付单号
`voucher_attachment_ids`	json	NULL	人工凭证
`recharge_status`	tinyint	NOT NULL, INDEX	待支付/待审/成功/驳回/过期/取消
`paid_at` / `reviewed_at` / `credited_at`	datetime(3)	NULL	关键时间
`approval_request_id`	bigint unsigned	NOT NULL DEFAULT 0	人工审核单
`ledger_id`	bigint unsigned	NOT NULL DEFAULT 0	入账台账

索引：idx_recharge_member_time、idx_recharge_status_time；外部单号在非空时必须唯一，由 Logic 与幂等表联合保证。

6.8.6 `hg_withdrawal_order` 提现订单

字段	类型	约束/索引	说明
`withdrawal_no`	varchar(32)	UNIQUE	提现单号
`member_id`	bigint unsigned	NOT NULL, INDEX	会员
`payment_account_id`	bigint unsigned	NOT NULL	收款账户
`channel_id`	bigint unsigned	NOT NULL DEFAULT 0	付款渠道
`request_amount`	bigint	NOT NULL	申请金额
`fee_amount`	bigint	NOT NULL DEFAULT 0	手续费
`actual_amount`	bigint	NOT NULL	实际到账
`currency`	char(3)	NOT NULL DEFAULT 'CNY'	币种
`account_snapshot_cipher`	longtext	NOT NULL	收款账户加密快照
`account_mask`	varchar(128)	NOT NULL	脱敏快照
`risk_result`	json	NULL	风控命中摘要
`withdrawal_status`	tinyint	NOT NULL, INDEX	待审/复核中/处理中/成功/失败/驳回/取消
`approval_request_id`	bigint unsigned	NOT NULL DEFAULT 0	审批单
`external_no`	varchar(128)	NULL, INDEX	外部付款单号
`freeze_ledger_id` / `final_ledger_id`	bigint unsigned	NOT NULL DEFAULT 0	冻结/完成台账
`reviewed_at` / `processed_at` / `completed_at`	datetime(3)	NULL	关键时间

6.8.7 `hg_wallet_adjustment_request` 账变申请

字段	类型	约束/索引	说明
`request_no`	varchar(32)	UNIQUE	申请单号
`member_id` / `account_id`	bigint unsigned	NOT NULL, INDEX	会员与钱包
`adjust_type`	tinyint	NOT NULL	1奖励 2补款 3扣款 4冲正 5其他
`direction`	tinyint	NOT NULL	收入/支出
`amount`	bigint	NOT NULL	金额，分
`reason_code` / `reason_text`	varchar(64)/varchar(500)	NOT NULL	原因
`evidence_attachment_ids`	json	NULL	凭证
`request_status`	tinyint	NOT NULL, INDEX	草稿/待审/通过/驳回/已执行/失败
`approval_request_id`	bigint unsigned	NOT NULL DEFAULT 0	审批单
`ledger_id`	bigint unsigned	NOT NULL DEFAULT 0	执行后台账

6.8.8 `hg_finance_review` 财务审核记录

字段	类型	约束/索引	说明
`approval_request_id`	bigint unsigned	NOT NULL, INDEX	审批单
`biz_type` / `biz_id`	varchar(32)/bigint unsigned	NOT NULL, INDEX	充值/提现/账变等
`review_stage`	tinyint	NOT NULL	1初审 2复核 3放款
`reviewer_id`	bigint unsigned	NOT NULL, INDEX	审核人
`decision`	tinyint	NOT NULL	1通过 2驳回 3退回补充
`reason_code` / `reason_text`	varchar(64)/varchar(500)	NOT NULL	意见
`snapshot_json`	json	NOT NULL	审核时数据快照
`created_at`	datetime(3)	NOT NULL	审核时间

唯一约束：UNIQUE (approval_request_id,review_stage,reviewer_id)。申请人与审核人不同的约束由 Logic 保证。

6.8.9 `hg_payment_callback` 支付回调记录

字段	类型	约束/索引	说明
`channel_id`	bigint unsigned	NOT NULL, INDEX	渠道
`callback_no`	varchar(128)	UNIQUE	渠道回调唯一号
`biz_type` / `biz_no`	varchar(32)/varchar(32)	NOT NULL, INDEX	业务定位
`headers_digest`	char(64)	NOT NULL	Header 摘要
`payload_cipher`	longtext	NOT NULL	回调加密原文
`verify_status`	tinyint	NOT NULL	验签结果
`process_status`	tinyint	NOT NULL, INDEX	待处理/成功/失败/已忽略
`error_message`	varchar(1000)	NULL	处理失败摘要
`received_at` / `processed_at`	datetime(3)	NOT NULL/NULL	回调时间

该表不软删除，原文禁止直接记入通用日志。

6.8.10 `hg_reconciliation_batch` 对账批次

字段	类型	约束/索引	说明
`batch_no`	varchar(32)	UNIQUE	对账批次号
`channel_id`	bigint unsigned	NOT NULL DEFAULT 0, INDEX	渠道，0 表示内部台账对账
`reconcile_date`	date	NOT NULL, INDEX	对账日期
`source_type`	tinyint	NOT NULL	1渠道账单 2业务单/台账 3钱包/台账
`file_attachment_id`	bigint unsigned	NOT NULL DEFAULT 0	原始账单文件
`total_count` / `matched_count` / `difference_count`	bigint unsigned	NOT NULL DEFAULT 0	数量汇总
`total_amount` / `difference_amount`	bigint	NOT NULL DEFAULT 0	金额汇总
`batch_status`	tinyint	NOT NULL, INDEX	1待执行 2执行中 3完成 4有差异 5失败
`started_at` / `finished_at`	datetime(3)	NULL	执行时间

唯一约束：UNIQUE (tenant_id,channel_id,reconcile_date,source_type)。

6.8.11 `hg_reconciliation_item` 对账差异项

字段	类型	约束/索引	说明
`batch_id`	bigint unsigned	NOT NULL, INDEX	对账批次
`biz_type` / `biz_no`	varchar(32)/varchar(32)	NOT NULL, INDEX	内部业务单
`external_no`	varchar(128)	NULL, INDEX	渠道单号
`difference_type`	tinyint	NOT NULL, INDEX	1内部多 2渠道多 3金额差 4状态差 5时间差
`internal_amount` / `external_amount`	bigint	NOT NULL DEFAULT 0	内部/外部金额
`internal_status` / `external_status`	varchar(32)	NULL	状态快照
`item_status`	tinyint	NOT NULL, INDEX	1待处理 2已确认 3已修复 4已忽略
`handler_id`	bigint unsigned	NOT NULL DEFAULT 0	处理人
`handle_reason`	varchar(500)	NULL	处理说明
`handled_at`	datetime(3)	NULL	处理时间

差异修复如涉及资金，必须发起账变或冲正审批，禁止在对账页面直接修改台账。

6.9 审批、审计与可靠性域

6.9.1 `hg_approval_request` 审批请求

字段	类型	约束/索引	说明
`approval_no`	varchar(32)	UNIQUE	审批单号
`approval_type`	varchar(32)	NOT NULL, INDEX	withdrawal/config/permission/member_status/adjustment
`target_type` / `target_id`	varchar(32)/bigint unsigned	NOT NULL, INDEX	目标定位
`action`	varchar(64)	NOT NULL	拟执行动作
`title`	varchar(200)	NOT NULL	审批摘要
`payload_json`	json	NOT NULL	待执行数据快照
`diff_json`	json	NULL	前后差异
`risk_level`	tinyint	NOT NULL DEFAULT 1	1低 2中 3高 4极高
`required_approvals`	int unsigned	NOT NULL DEFAULT 1	需要的通过数
`approval_status`	tinyint	NOT NULL, INDEX	草稿/待审/审批中/通过/驳回/取消/已执行/失败
`applicant_id`	bigint unsigned	NOT NULL, INDEX	申请人
`submitted_at` / `decided_at` / `executed_at`	datetime(3)	NULL	关键时间
`expire_at`	datetime(3)	NULL	超时时间

6.9.2 `hg_approval_action` 审批动作

字段	类型	约束/索引	说明
`approval_request_id`	bigint unsigned	NOT NULL, INDEX	审批请求
`step_no`	int unsigned	NOT NULL	节点顺序
`actor_id`	bigint unsigned	NOT NULL, INDEX	操作人
`action`	tinyint	NOT NULL	1提交 2通过 3驳回 4退回 5取消 6执行
`reason_code` / `comment`	varchar(64)/varchar(1000)	NULL	原因和意见
`snapshot_json`	json	NOT NULL	当时快照
`actor_ip_cipher`	varchar(512)	NULL	操作 IP 密文
`mfa_verified`	tinyint	NOT NULL DEFAULT 0	是否二次认证
`created_at`	datetime(3)	NOT NULL	动作时间

追加表，不允许 UPDATE/DELETE。

6.9.3 `hg_sensitive_access_log` 敏感数据查看日志

字段	类型	约束/索引	说明
`access_no`	varchar(32)	UNIQUE	查看流水号
`actor_id`	bigint unsigned	NOT NULL, INDEX	管理员
`target_type` / `target_id`	varchar(32)/bigint unsigned	NOT NULL, INDEX	被查看对象
`field_set`	json	NOT NULL	查看的字段集，不保存字段值
`purpose_code` / `purpose_text`	varchar(64)/varchar(500)	NOT NULL	用途
`authorization_no`	varchar(64)	NULL	授权号
`mfa_verified`	tinyint	NOT NULL	二次认证
`result`	tinyint	NOT NULL	允许/拒绝/失败
`trace_id`	varchar(64)	NOT NULL, INDEX	链路 ID
`created_at`	datetime(3)	NOT NULL, INDEX	查看时间

6.9.4 `hg_biz_audit_log` 业务审计日志

字段	类型	约束/索引	说明
`audit_no`	varchar(32)	UNIQUE	审计号
`actor_type` / `actor_id`	tinyint/bigint unsigned	NOT NULL, INDEX	管理员/会员/系统
`module` / `action`	varchar(64)	NOT NULL, INDEX	模块与动作
`target_type` / `target_id`	varchar(64)/bigint unsigned	NOT NULL, INDEX	目标
`before_digest` / `after_digest`	char(64)	NULL	变更前后摘要
`change_json`	json	NULL	已脱敏差异
`reason`	varchar(500)	NULL	操作原因
`approval_no`	varchar(32)	NULL, INDEX	审批单号
`trace_id`	varchar(64)	NOT NULL, INDEX	链路 ID
`prev_hash` / `row_hash`	char(64)	NULL/NOT NULL	防篡改哈希链
`created_at`	datetime(3)	NOT NULL, INDEX	时间

不在 change_json 中存储密码、令牌、完整手机、卡号、证件号和渠道密钥。

6.9.5 `hg_idempotency_record` 幂等记录

字段	类型	约束/索引	说明
`scope`	varchar(64)	NOT NULL	业务作用域
`idempotency_key`	varchar(128)	NOT NULL	客户端/系统幂等键
`request_digest`	char(64)	NOT NULL	请求摘要
`resource_type` / `resource_id`	varchar(64)/bigint unsigned	NULL	产生的资源
`process_status`	tinyint	NOT NULL	1处理中 2成功 3失败
`response_code`	int	NULL	结果码
`response_digest`	char(64)	NULL	响应摘要
`expire_at`	datetime(3)	NOT NULL, INDEX	保留到期时间
`created_at` / `updated_at`	datetime(3)	NOT NULL	时间

唯一约束：UNIQUE (tenant_id,scope,idempotency_key)。

6.9.6 `hg_outbox_event` 事件出站箱

字段	类型	约束/索引	说明
`event_no`	varchar(32)	UNIQUE	事件号
`aggregate_type` / `aggregate_id`	varchar(64)/bigint unsigned	NOT NULL, INDEX	聚合根
`event_type`	varchar(128)	NOT NULL, INDEX	`wallet.credited` 等
`payload_json`	json	NOT NULL	已脱敏事件数据
`publish_status`	tinyint	NOT NULL DEFAULT 1, INDEX	1待发送 2已发送 3失败 4死信
`retry_count`	int unsigned	NOT NULL DEFAULT 0	重试次数
`next_retry_at`	datetime(3)	NULL, INDEX	下次重试
`last_error`	varchar(1000)	NULL	最后错误
`created_at` / `published_at`	datetime(3)	NOT NULL/NULL	时间

6.9.7 `hg_dashboard_daily_stat` 看板日汇总

字段	类型	约束/索引	说明
`stat_date`	date	NOT NULL	统计日期
`dimension_type` / `dimension_value`	varchar(32)/varchar(64)	NOT NULL	全局/渠道/等级等
`metric_code`	varchar(64)	NOT NULL	指标编码
`metric_count`	bigint	NOT NULL DEFAULT 0	数量
`metric_amount`	bigint	NOT NULL DEFAULT 0	金额，分
`calculated_at`	datetime(3)	NOT NULL	计算时间

唯一约束：UNIQUE (tenant_id,stat_date,dimension_type,dimension_value,metric_code)。看板可展示汇总值，但财务对账必须以业务单和台账为准。

6.10 通知表

`hg_app_notification` C 端通知

字段	类型	约束/索引	说明
`notification_no`	varchar(32)	UNIQUE	通知号
`member_id`	bigint unsigned	NOT NULL, INDEX	接收会员
`notification_type`	varchar(32)	NOT NULL, INDEX	system/order/finance/task/security
`title`	varchar(200)	NOT NULL	标题
`content`	varchar(2000)	NOT NULL	纯文本内容
`biz_type` / `biz_id`	varchar(32)/bigint unsigned	NULL, INDEX	关联业务
`read_at`	datetime(3)	NULL	已读时间
`expire_at`	datetime(3)	NULL	过期时间
`created_at`	datetime(3)	NOT NULL, INDEX	创建时间

需求中的“弹幕/模拟会员”不作为真实会员行为实现。如确需运营轮播消息，使用显式标注为“平台消息”的通知类型，不关联伪造会员 ID，不进入真实统计。

6.11 核心索引和分区策略

场景	策略
会员查询	手机精确查询走 `mobile_hash`；用户名走唯一索引；列表按 `(tenant_id,created_at,id)` 游标分页
订单查询	业务单号唯一索引；高频列表索引必须以 `tenant_id` 开头，紧跟状态/会员和时间
台账	`(account_id,occurred_at,id)` 和 `(biz_type,biz_no)`；按月度作冷热分层，不盲目对在线主表分区
审计	`(target_type,target_id,created_at)`、`(actor_id,created_at)`、`trace_id`；超过在线保留期后归档到独立存储
Outbox	`(publish_status,next_retry_at,id)` 供消费者抢占；已发送数据定期归档
看板	当日数据可实时聚合，历史数据读日汇总表

7. 字典与状态设计

本系统不建设新的字典体系，完整复用 HotGo 已有的三类字典能力。三类字典通过同一组接口和前端 Store 向页面提供选项。

7.1 HotGo 现有字典机制

类型	现有实现	适用场景	是否可在后台修改
数据库字典	`hg_sys_dict_type` + `hg_sys_dict_data`	驳回原因、内容分类等运营可维护选项	是
枚举字典	`internal/consts` + `dict.RegisterEnums()`	状态机、资金方向、账户类型等稳定业务枚举	否，随代码版本发布
方法字典	`dict.RegisterFunc()`	会员等级、商品分类、任务大厅、支付渠道等数据库动态选项	数据由对应业务模块维护

后端选项查询继续使用现有 /dictData/option/{type} 和 /dictData/options。SysDictData.Select() 已按“内置枚举/方法字典优先，数据库字典兜底”加载，新业务不重复实现查询逻辑。

7.2 直接复用的现有字典

现有字典 key	复用场景	处理
`sys_normal_disable`	所有可维护业务表的 `status`	直接使用 1正常、2停用，不再定义启停枚举
`sys_switch`	自动派单、是否推荐、默认开关	直接使用 1开启、2关闭
`sys_user_sex`	会员或管理员性别	如业务确需则直接使用
`payType`	支付方式选项	优先复用现有微信/支付宝/QQ 值；为原 `PayTypeOptions` 补充 `balance`、`bank_transfer`、`manual` 等本项目确需值，不另建同义字典
`payStatus`	简单支付结果展示	仅在“待支付/已支付”语义完全一致时复用
`creditType` / `creditGroup`	旧资金日志兼容、余额/积分分类	数据迁移时复用映射；新钱包台账扩展原枚举而不建第二套同义字典

orderStatus 是 HotGo 原商品订单状态（待付款、已发货、退款等），与本项目的任务匹配订单状态语义不同，不强行复用其数值。保留原字典供框架旧模块使用，新增独立的 tradeOrderStatus 枚举字典，避免同一值在两种业务中含义不同。

7.3 新增枚举字典（依然使用 HotGo 注册机制）

以下仅新增 internal/consts 常量和 dict.RegisterEnums() 注册，不新增字典表或接口：

字典 key	Go 选项变量	核心值
`appMemberStatus`	`AppMemberStatusOptions`	1正常 2受限 3禁用 4注销
`appMemberRiskStatus`	`AppMemberRiskStatusOptions`	1正常 2观察 3限制 4冻结
`bizPublishStatus`	`BizPublishStatusOptions`	1草稿 2待审 3已发布 4已下线 5已归档
`tradeOrderStatus`	`TradeOrderStatusOptions`	1匹配中 2待处理 3处理中 4完成 5超时 6冻结 7取消 8失败
`rechargeStatus`	`RechargeStatusOptions`	1待支付 2待审 3成功 4驳回 5过期 6取消
`withdrawalStatus`	`WithdrawalStatusOptions`	1待审 2复核中 3处理中 4成功 5失败 6驳回 7取消
`taskSubmissionStatus`	`TaskSubmissionStatusOptions`	1待审 2通过 3驳回 4已结算 5已冲正
`approvalStatus`	`ApprovalStatusOptions`	1草稿 2待审 3审批中 4通过 5驳回 6取消 7已执行 8执行失败
`ledgerBizType`	`LedgerBizTypeOptions`	recharge/withdraw/freeze/unfreeze/commission/reward/adjust/reversal
`paymentAccountType`	`PaymentAccountTypeOptions`	1银行卡 2数字钱包 3云闪付 4支付宝 5微信

资金、审批和状态机值必须是代码枚举，因为 Logic 会依赖其稳定语义。它们在 HotGo 字典管理页面中仍会以“内置字典 → 枚举字典”展示，但不允许运营人员修改值。

7.4 复用数据库字典的运营选项

以下选项在现有“系统设置 → 字典管理”中新增类型和数据，不新建业务字典表：

数据库字典 key	用途	修改影响
`member_disable_reason`	会员禁用/限制标准原因	只影响后续新申请，历史记录保留 label 快照
`recharge_reject_reason`	充值驳回原因	同上
`withdrawal_reject_reason`	提现驳回原因	同上
`task_reject_reason`	任务审核驳回原因	同上
`wallet_adjust_reason`	账变/奖励金原因	同上，且操作仍需审批
`content_type`	公告、简介、FAQ、规则、活动等内容分类	新类型可由运营增加，但 C 端特殊展示类型需代码支持

这些字典的 value_type、list_class、sort、status 继续由 hg_sys_dict_data 承载。删除前必须检查是否已被业务使用；已使用选项应停用而不是删除。

7.5 方法字典

下列选择器来自业务表，使用 dict.RegisterFunc() 注册，不将业务数据复制到 hg_sys_dict_data：

方法字典 key	数据源	缓存策略
`memberLevelOption`	`hg_app_member_level`	可缓存，等级更新后 `dict.ClearFuncCache()`
`productCategoryOption`	`hg_product_category`	可缓存，分类更新后清理
`taskHallOption`	`hg_task_hall`	可缓存，大厅更新后清理
`paymentChannelOption`	`hg_payment_channel`	可缓存，渠道更新后清理

7.6 后端与前端用法

后端在 Filter(ctx) 或 Logic 中使用现有方法校验字典值：

if !dict.HasOptionKey(consts.WithdrawalStatusOptions, in.WithdrawalStatus) {
    return gerror.New("提现状态不合法")
}

前端在每个模块 model.ts 中继续使用现有 Pinia 字典 Store：

const dict = useDictStore();

export function loadOptions() {
  dict.loadOptions([
    'sys_normal_disable',
    'sys_switch',
    'withdrawalStatus',
    'withdrawal_reject_reason',
    'paymentChannelOption',
  ]);
}

// 表格显示
dict.getLabel('withdrawalStatus', row.withdrawalStatus);

// 下拉选项
computed(() => dict.getOptionUnRef('withdrawal_reject_reason'));

不在 Vue 模板、model.ts 或 API 文件中重复定义 label/value 数组。

7.7 字典与业务配置的边界

字典：为字段提供有限选项、标签、颜色和排序，复用 HotGo 字典系统。
业务配置：交易时段、最低余额、佣金比例、额度和功能开关等会直接影响 C 端和资金，使用 hg_site_config_version 的审批、发布和回滚机制，不塞入字典表。
业务主数据：会员等级、商品分类、支付渠道等有独立属性和关系，使用业务表，只通过方法字典提供下拉选项。

8. 接口设计约定

8.1 路由与方法

后台路由使用 HotGo 现有 /admin 前缀，不再叠加 /admin-api/v1。
列表与详情使用 GET；新增、编辑、状态变更和审批使用 POST。
标准 CRUD 按 /module/list、/view、/edit、/delete、/status、/export 组织。
高风险动作不复用通用 edit，使用显式语义接口，如 /withdrawal/review、/walletAdjustment/submit、/approval/approve。

8.2 写请求通用要求

资金、审核、发布类接口必须携带 idempotencyKey。
更新可并发编辑的数据必须携带 version，冲突返回明确错误。
审核、驳回、禁用、删除、导出和敏感查看必须携带原因。
资金与权限写接口返回审计号或审批单号。
Controller 仅做参数透传和结果组装；所有业务校验在 sysin.Filter() 或 Logic 中完成。

8.3 错误码分类

分类	示例	前端处理
参数错误	时间区间反向、金额超限	定位到字段
状态冲突	订单已处理、版本过期	刷新当前数据
权限拒绝	无敏感值查看权限	不展示目标数据
审批约束	申请人尝试审批自己	提示职责分离
余额不足	可用余额小于提现金额	显示当前可用余额
外部服务错误	支付通道超时	显示可重试状态与 `traceId`

9. 缓存、队列与定时任务

9.1 缓存

Key	TTL	用途
`site:config:{tenant}:{group}`	5 分钟	当前已发布站点配置
`content:published:{tenant}:{key}`	10 分钟	已发布内容
`member:level:{tenant}:{id}`	10 分钟	当前等级规则
`dashboard:summary:{tenant}:{date}`	1 分钟	看板汇总
`sensitive:grant:{token}`	1–5 分钟	一次性敏感查看授权
`lock:finance:{bizNo}`	小于 30 秒	防止跨实例重复处理

统一通过 cache.Instance() 使用，不在业务代码中直接调用 Redis。更新成功后主动删除缓存。

9.2 队列主题

Topic 常量	事件	消费者
`QueueBizNotification`	订单、充值、提现、任务状态变更	C 端站内信/短信/推送
`QueueDashboardStat`	会员、订单、台账事件	看板汇总
`QueuePaymentCallback`	通道回调待处理	支付处理器
`QueueReconciliation`	入账、付款和冲正	对账服务
`QueueAuditArchive`	审计日志归档	审计归档服务

9.3 定时任务

任务名	频率	职责
`publishScheduledContent`	每分钟	发布到期内容、Banner 和配置
`expireTradeOrders`	每分钟	处理超时订单
`retryOutboxEvents`	每 10 秒	发送 Outbox 并执行指数退避
`reconcileFinanceDaily`	每日	业务单、台账、钱包和渠道对账
`aggregateDashboardDaily`	每小时/每日	重建看板汇总
`expireSessionsAndGrants`	每 10 分钟	清理会话与临时授权

10. 安全设计

10.1 数据保护

密文字段使用 AEAD（AES-256-GCM 或等价算法），每条记录使用唯一 nonce。
业务库只保存密文；主密钥位于 KMS/密钥管理系统，不存在代码、数据库和普通配置文件。
密钥定期轮换，密文保存密钥版本，支持惰性重加密。
通用请求日志对密码、令牌、卡号、证件号、收款码 URL 和渠道密钥执行强制红线过滤。

10.2 Web 安全

富文本在服务端执行标签、属性和 URL 协议白名单清洗。
设置 CSP、X-Content-Type-Options、Referrer-Policy 和合理的 iframe sandbox。
文件上传校验 MIME、扩展名、文件头、尺寸和大小，异步病毒扫描，不使用用户原始文件名作为存储键。
后台使用 MFA；资金、完整敏感值和权限修改触发再认证。

10.3 资金安全不变式

钱包可用余额和冻结余额不得为负数。
每笔台账的 after_balance = before_balance ± amount。
同一账户同一幂等键只能有一条台账。
充值成功必须且只能对应一笔入账台账。
提现成功必须存在冻结和扣减冻结两类台账。
资金纠错只能冲正，不得修改或删除历史台账。
申请人、初审人和复核人按风险级别实施职责分离。

11. 可观测性与运维

11.1 指标

API 请求数、成功率、P50/P95/P99 延迟和错误码分布。
待审充值/提现数、审批时长、通道成功率、回调验签失败数。
钱包与台账对账差异数、重复幂等请求数、事务冲突数。
Outbox 积压、重试数、死信数和消费延迟。
敏感数据查看次数、拒绝次数、非工作时段查看和大量导出。

11.2 告警

级别	场景
P0	钱包与台账不平、重复入账、未经审批的资金变更、密钥泄漏
P1	支付通道大面积失败、Outbox 严重积压、异常批量敏感查看
P2	单个外部服务降级、定时发布延迟、看板汇总延迟

11.3 备份与恢复

MySQL 全量备份 + binlog 时点恢复，目标 RPO ≤ 5 分钟，RTO ≤ 30 分钟。
对象存储开启版本和生命周期，资金凭证在留存期内不得物理删除。
每季度执行恢复演练，演练必须验证业务单、钱包和台账的一致性。

12. 性能与容量设计

指标	一期目标
会员	10 万
交易订单	1,000 万级历史数据
钱包台账	3,000 万级历史数据
后台并发用户	200
后台列表	P95 < 1s
普通写操作	P95 < 1.5s
资金事务	P95 < 2s，不包外部通道等待

列表默认使用索引覆盖的时间倒序与游标分页。需跳页的后台页面可保留普通分页，但必须限制最大页深；大量数据导出使用异步任务，不在 HTTP 请求中生成。

13. 开发与数据库迁移顺序

基础治理：字典常量、审批、审计、幂等、Outbox、敏感字段加密工具。
会员域：会员等级、会员、隐私资料、收款账户、状态记录和会话。
内容配置域：站点配置版本、内容版本、Banner、客服渠道。
商品任务域：分类、商品、任务大厅、任务、交易订单和任务提交。
资金域沙箱：钱包、台账、充值、提现、账变、财务审核和回调。
外部通道：支付、实名、短信和客服等外部服务。
历史迁移：脱敏盘点、数据清洗、密文转换、台账校验和切换。

每批建表 SQL 合入前，使用 GoFrame CLI 重新生成 entity、do、dao/internal 和 dao；禁止手动修改生成文件。

14. 测试策略

14.1 单元测试

金额计算、手续费计算、佣金计算和边界值。
所有状态机的允许与禁止转换。
脱敏、加密、哈希检索和密钥版本轮换。
站点配置跨字段校验，特别是时间反向和比例超限。
审批人与申请人分离、审批数量与权限校验。

14.2 集成测试

重复充值回调只入账一次。
并发提现不得使钱包余额为负。
提现驳回、撤销和付款失败的冻结与解冻一致。
任务重复审核不得重复发放佣金。
已发布配置回滚后，C 端和后台读取同一版本。
敏感查看令牌单次使用、过期失效并产生审计记录。

14.3 数据不变式测试

在 CI 和生产对账中定期执行：

钱包可用余额 = 对应可用余额台账累计值
钱包冻结余额 = 对应冻结台账累计值
充值成功单数 = 充值入账唯一业务单数
提现成功单数 = 提现最终扣款唯一业务单数
已结算任务数 = 任务佣金有效台账业务单数

15. 分阶段交付

阶段	后端	前端	数据库	退出条件
S1 基础	RBAC、审批、审计、幂等、Outbox	统一列表/弹窗/审批组件	治理域表	安全评审通过
S2 配置会员	配置、内容、会员、脱敏	对应页面	配置与会员域表	C 端版本联调通过
S3 商品任务	商品、任务、订单、审核	对应页面	商品任务域表	沙箱任务闭环通过
S4 资金沙箱	钱包、台账、充值、提现、对账	财务页面	资金域表	并发、幂等、对账测试通过
S5 生产通道	外部支付与风控	运营看板与降级	回调与统计	小流量、限额、人工对账通过

16. 需进一步确认的设计决策

生产是否需要真实资金、支持币种以及法定小数位。
单租户还是多租户部署；本设计预留 tenant_id，单租户使用 0。
提现初审、复核、放款的金额阈值和岗位矩阵。
会员实名认证所需字段、外部供应商与数据留存期。
会员关系树与层级返佣是否保留；若保留，需先完成合规评审和返佣规则详细设计。
客服使用自建工单还是第三方服务；第三方可接收的会员数据范围。
原系统历史数据的字段映射、缺失值处理、重复账号合并和台账校验方案。

上述决策不阻塞 S1–S3 的基础开发，但在真实充值、提现和历史资金数据迁移前必须完成确认。

64 KiB Raw Blame History Unescape Escape

后台管理系统概要设计

目录

1. 文档目标

1.1 范围边界

2. 设计原则

3. 技术架构

3.1 部署单元

3.2 代码模块划分

4. 系统模块设计

4.1 认证与权限

4.2 站点配置与内容发布

4.3 会员与隐私数据

4.4 商品、任务和交易订单

4.5 钱包与资金安全

4.6 统一审批

5. 核心业务流程

5.1 充值入账

5.2 提现与资金冻结

5.3 任务审核与佣金

5.4 配置发布

6. 数据库设计

6.1 数据库基线

6.2 通用字段

6.3 表关系概览

6.4 现有系统表复用

6.5 配置与内容域

6.5.1 hg_site_config_version 站点配置版本

6.5.2 hg_content 内容主表

6.5.3 hg_content_version 内容版本

6.5.4 hg_banner Banner

6.5.5 hg_customer_service_channel 客服渠道

6.6 会员域

6.6.1 hg_app_member_level 会员等级

6.6.2 hg_app_member_level_version 等级规则版本

6.6.3 hg_app_member C 端会员

6.6.4 hg_app_member_profile 会员隐私资料

6.6.5 hg_app_member_address 会员地址

6.6.6 hg_app_member_payment_account 收款账户

6.6.7 hg_app_member_session 会员会话

6.6.8 hg_app_member_status_log 会员状态记录

6.7 商品与任务域

6.7.1 hg_product_category 商品分类

6.7.2 hg_product 商品

6.7.3 hg_task_hall 任务大厅

6.7.4 hg_task_hall_level 任务大厅可用等级

6.7.5 hg_task 任务

6.7.6 hg_task_level 任务可用等级

6.7.7 hg_task_submission 会员任务提交