# 后台管理系统开发总结 > 文档版本：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 真实认证流程不与本次状态机补强混合实施，后续作为独立安全增强项处理。