15 KiB
15 KiB
后台管理系统开发总结
文档版本：V1.0
编制日期：2026-10-08
需求基线：后台管理系统需求文档
概要设计：后台管理系统概要设计
项目目录：/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.sql20261008_002_governance_menu.sql
4. 第 4 章：首页数据看板
4.1 已实现功能
- 今日新增会员、订单、充值、提现等核心指标。
- 业务金额、订单和会员数据汇总。
- 待审批和异常业务入口。
- 按管理员权限控制敏感金额展示。
- 原 HotGo 控制台菜单复用并扩展业务统计接口。
4.2 主要接口
GET /console/statGET /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_versionhg_contenthg_content_versionhg_bannerhg_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_memberhg_app_member_profilehg_app_member_addresshg_app_member_payment_accounthg_app_member_status_loghg_wallet_accounthg_wallet_ledgerhg_wallet_adjustment_requesthg_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_levelhg_app_member_level_versionhg_task_hallhg_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_orderhg_payment_channelhg_recharge_orderhg_withdrawal_orderhg_finance_reviewhg_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_categoryhg_taskhg_task_levelhg_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 前缀。
可重复执行的数据脚本：
server/storage/data/seeds/20261008_business_demo_data.sql
本地重新导入命令：
mysql -h127.0.0.1 -P3306 -uroot -proot olons_admin \
< server/storage/data/seeds/20261008_business_demo_data.sql
正式上线前仍需执行完整的接口回归、权限角色矩阵检查、并发资金测试和生产配置核对。
补充项：第 12 章状态机与数据模型补强
第 12 章不是新的一级菜单，而是对现有会员、资金、任务和内容模块的业务约束补强。当前核心数据表、审批、台账和审计基础已经具备，但以下内容尚未列入“已完成”：
- 会员状态合法转换和注销不可逆。
- 充值成功后的审批冲正。
- 已结算任务佣金的审批冲正。
- 文本内容归档和历史版本生成回滚草稿。
- 状态转换、重复执行、并发执行和余额不足测试。
专项设计已单独整理，后续开发以该文档为实施依据：
建议后续新增迁移：
server/storage/data/migrations/20261008_009_state_machine_hardening.sql
MFA 真实认证流程不与本次状态机补强混合实施，后续作为独立安全增强项处理。