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