platforms/docs/05-平台总后台需求.md

# 平台总后台需求（现状基线）

## 1. 文档目的

本文根据当前已完成的 `frontend/platform_admin` 与 `backend/api` 代码反向整理，是平台总后台现阶段的功能、权限、数据和验收基线。

本文只描述代码中已经存在的能力。原始产品规划中尚未实现的安全运营中心、邀请注册二维码、全局地图、生产管理、API 中心等能力统一列入“未实现范围”，不得据此文档认定为已交付。

实现事实来源按以下顺序核对：

1. `backend/api/internal/routers/platform.go`：实际 HTTP 路由。
2. `frontend/platform_admin/src/contracts/platform-resources.json`：前后端资源契约。
3. `frontend/platform_admin/src/api/resources.ts`：字段、关系、页面模式和业务动作。
4. `frontend/platform_admin/src/router/routes/modules/platform.ts`：菜单、页面与隐藏子资源。
5. `backend/api/internal/logic/platform`：状态机、事务、权限和业务校验。

## 2. 系统定位与边界

平台总后台是和气平台当前已落地的 Web 管理端，面向平台管理员提供跨组织主数据、人员用户、智能气阀、配送合同与订单、电商数据、钱包财务、内容客服和后台权限管理。

当前系统不替代以下业务系统：

- 气站管理系统：站点经营、站内库存和日常订单运营仍由后续气站端主责。
- 配送点管理系统：末端调度、配送仓和配送作业仍由后续配送点端主责。
- 生产管理系统：设备生产、质检、序列号注入和出厂追溯仍由独立生产端主责；平台后台仅治理生产商账户主数据及智能气阀的生产商归属。
- API 中心：开放 API 产品、调用方、凭证和配额管理尚未实现。
- 用户端与服务端 App：本后台不承担用户设备控制、配送员定位采集或现场取证。

当前后端 API 基础路径为 `/heqi/platform/v1`。除健康检查和登录外，其余接口均要求 JWT，并继续执行平台菜单权限校验。

## 3. 技术与数据约定

### 3.1 实现目录

| 范围 | 当前目录 | 职责 |
| --- | --- | --- |
| 管理端 | `frontend/platform_admin` | Vue 3、TypeScript、Vite、Pinia、Arco Design |
| 页面 | `frontend/platform_admin/src/views` | 仪表盘、报表及契约驱动的资源页面 |
| 资源定义 | `frontend/platform_admin/src/api/resources.ts` | 字段、关联、读写模式和详情动作 |
| 前端契约 | `frontend/platform_admin/src/contracts/platform-resources.json` | 后端资源和路由生成清单 |
| 前端路由 | `frontend/platform_admin/src/router/routes/modules/platform.ts` | 一级菜单、二级菜单和隐藏详情资源 |
| 后端 API | `backend/api` | Gin HTTP API、JWT、事务和统一响应 |
| 路由 | `backend/api/internal/routers/platform.go` | 平台 API 唯一路由注册入口 |
| 业务逻辑 | `backend/api/internal/logic/platform` | 各领域查询、动作、权限和状态流转 |
| 模型 | `backend/api/internal/models` | GORM 模型、表名与中文注释 |
| 初始化 | `backend/api/internal/initdb` | root 账户和系统必需数据的幂等初始化 |

### 3.2 数据身份

- 每一张表均使用 `id bigint` 自增主键，Go 模型对应 `ID uint64`。
- 主表额外使用应用生成的 UUID V7 `identity`，并建立唯一索引。
- `id` 仅用于数据库内部关联；HTTP 路径、前端选择器、审计和跨服务关联使用 `identity`。
- 前端不得提交数据库内部 `id`，关联字段统一提交业务 `identity`。
- 通用记录状态包括草稿、启用、停用、归档和冻结；业务状态另设专用字段。
- 删除接口执行归档或受控删除语义；资金流水、订单过程记录、归属记录等事实资源不开放通用删除。
- 金额由后端以最小货币单位整数保存；前端展示时换算为元。

### 3.3 资源页面模式

| 模式 | 能力 |
| --- | --- |
| `writable` | 列表、详情、新增、编辑、状态调整和归档 |
| `editable` | 列表、详情、新增、编辑和状态调整，不提供归档 |
| `readonly` | 列表和详情；可通过显式业务动作处理，但无通用增删改 |
| `append_only` | 可创建事实记录，既有记录不通用编辑或删除 |
| `managed` | 可创建和编辑，但生命周期必须通过专用动作推进 |

普通资源统一复用 `ResourcePage.vue` 和共享列表组件。账户、钱包、关联记录等从所属资源详情进入；隐藏子资源不单独授予菜单权限。

## 4. 登录、账户与权限

### 4.1 登录与个人账户

- 管理员使用用户名和密码登录。
- 停用账户不得登录；密码使用 bcrypt 校验。
- 登录成功返回 JWT、账户 `identity`、显示名称和角色编码。
- `Authorization` 请求头当前直接传 JWT 原始值，不使用 `Bearer` 前缀。
- 已登录账户可查看个人资料、角色和菜单编码。
- 修改密码必须校验当前密码，新密码不少于 6 位。
- 系统启动时幂等创建 `root` 管理账户；root 初始密码优先读取环境变量 `HEQI_PLATFORM_ROOT_PASSWORD`。

### 4.2 RBAC 与数据能力

- `root` 角色拥有全部平台菜单能力。
- 非 root 账户必须关联处于启用状态的平台角色，并按角色菜单逐请求鉴权。
- 创建工作人员、安装人员、配送人员和运维人员是相互独立的菜单能力。
- 工作人员资质权限跟随所属人员角色，不能凭任一人员菜单访问其他类型人员资质。
- 创建配送订单使用独立的 `gasorder_create` 权限，不因拥有订单列表权限自动获得。
- 合同气瓶、合同修订、订单明细、分配记录、状态记录和确认记录等隐藏资源继承所属主菜单权限。
- 气站、配送点、人员和用户菜单可读取其详情内的钱包摘要；提现菜单可读取钱包信息用于审核。
- 角色的定位范围只允许 `standard`（脱敏坐标）或 `precise`（精确坐标）。root 默认使用精确坐标。
- 前端菜单隐藏只负责展示，最终权限由后端中间件执行。

## 5. 首页与报表

首页从真实数据库聚合以下指标：

- 启用气站、启用配送点、在岗工作人员、启用用户和启用智能气阀数量。
- 生效配送合同数量。
- 今日配送订单数量与今日应付金额。
- 待受理客服工单数量。
- 累计支付成功金额。
- 配送订单状态分布、智能气阀状态分布、支付渠道实收金额。
- 最近 7 个自然日的订单数量和订单金额趋势；无数据日期补零。

首页快捷入口根据当前角色菜单过滤。统计报表页复用同一真实汇总接口，不生成虚构报表数据，不提供报表配置或导出。

## 6. 已实现功能域

当前资源契约共 48 个资源。下表中的路径均相对于 `/heqi/platform/v1`。

### 6.1 机构管理

| 资源 | 路径 | 模式 | 已实现能力 |
| --- | --- | --- | --- |
| 气站 | `/gas_basic` | 可写 | 新增草稿、详情、编辑、审核、启停、归档；管理气站账户和钱包 |
| 气站账户 | `/gas_account` | 可写 | 账号新增、编辑、启停和归档；必须关联气站 |
| 配送点 | `/delivery_basic` | 可写 | 新增、编辑、启停和归档；可关联气站；管理配送点账户和钱包 |
| 配送点账户 | `/delivery_account` | 可写 | 账号新增、编辑、启停和归档；必须关联配送点 |

气站创建后为草稿状态。气站审核通过后进入启用，审核不通过进入停用且必须填写理由；只有已启用或已停用气站可继续切换启停状态。审核过程写入独立审核记录。

### 6.2 工作人员管理

| 资源 | 路径 | 模式 | 已实现能力 |
| --- | --- | --- | --- |
| 工作人员 | `/staff_account` | 可写 | 新增、编辑、启停、归档、查看钱包 |
| 人员资质 | `/staff_credential` | 可写 | 新增、编辑、启停和归档 |

工作人员支持安装人员 `installer`、配送人员 `delivery`、运维人员 `operations` 三种角色，可关联气站或配送点，并记录在岗/离岗状态。前端按角色提供独立列表和新增入口；后端按菜单和人员实际角色校验详情、修改及资质访问。

### 6.3 用户管理

| 资源 | 路径 | 模式 | 已实现能力 |
| --- | --- | --- | --- |
| 用户账户 | `/user_account` | 可写 | 新增、编辑、启停、归档、查看钱包 |
| 用户地址 | `/user_address` | 可写 | 新增、编辑、默认地址、启停和归档 |
| 用户服务关系 | `/user_service_relation` | 可写 | 维护用户与气站、配送点、工作人员的关系 |

用户页面同时提供配送合同入口。当前后台可直接维护用户、地址和服务关系，但尚未实现邀请二维码注册、服务关系审批和完整历史时间线。

### 6.4 智能气阀管理

| 资源 | 路径 | 模式 | 已实现能力 |
| --- | --- | --- | --- |
| 生产商 | `/producer_account` | 可写 | 生产商企业与登录账户新增、查询、编辑、启停和软删除；已被智能气阀引用时禁止删除 |
| 类型 | `/product_type` | 可编辑 | 类型新增、编辑和启停 |
| 库房 | `/product_warehouse` | 可编辑 | 库房新增、编辑和启停 |
| 智能气阀 | `/product_info` | 可编辑 | 档案新增、编辑、启停和专用生命周期流转 |
| 检修记录 | `/product_repair` | 可编辑 | 检修记录新增、编辑和状态调整 |
| 归属记录 | `/product_owner` | 只读 | 查询每次归属变更的动作、操作者、原因和时间 |

智能气阀必须关联生产商和类型，可选关联库房、气站、配送点或用户。生产商登录密码仅保存哈希且不通过资源接口返回；独立生产端登录路由待生产管理系统落地时接入。归属组合由后端校验，不允许形成非法多重归属。生命周期支持待处理、在库、运输中、使用中、维修中和已报废；状态变化使用 `/product_info/:identity/lifecycle`，不能通过通用编辑直接改写。归属变化自动追加归属记录。

### 6.5 配送合同

| 资源 | 路径 | 模式 | 已实现能力 |
| --- | --- | --- | --- |
| 配送合同 | `/gasorder_contract` | 受管 | 创建、草稿编辑、启用、续签、终止 |
| 合同气瓶 | `/gasorder_contract_product` | 仅追加 | 绑定气瓶、按理由解绑 |
| 合同修订 | `/gasorder_contract_revision` | 只读 | 查询启用、续签和终止形成的版本记录 |

合同关联用户和气站，可选关联配送点，记录合同编号、条款、附件、默认配送费及有效期。合同生命周期为草稿、生效、过期、终止。只有符合当前状态的专用动作可执行，启用、续签、终止和解绑均记录原因及操作者。

合同气瓶必须属于合同用户、处于可用状态且未报废；订单只能使用有效合同中仍绑定的气瓶。

### 6.6 气体配送订单

| 资源 | 路径 | 模式 | 已实现能力 |
| --- | --- | --- | --- |
| 配送订单 | `/gasorder_basic` | 仅追加 | 创建及专用状态动作 |
| 订单明细 | `/gasorder_item` | 只读 | 查询合同气瓶、数量和金额快照 |
| 分配记录 | `/gasorder_assign` | 只读 | 查询配送点和工作人员分配历史 |
| 状态记录 | `/gasorder_status` | 只读 | 查询每次状态变化及原因 |
| 运行轨迹 | `/gasorder_track` | 只读 | 查询订单轨迹主记录 |
| 轨迹点 | `/gasorder_track_point` | 只读 | 查询轨迹节点或定位点 |
| 确认记录 | `/gasorder_confirm` | 只读 | 查询签收类型、人员和凭证 |
| 支付记录 | `/gasorder_payment` | 只读 | 查询配送订单支付事实 |

创建订单时必须提交唯一请求号、有效合同、创建方、用户地址、合同气瓶集合、联系人和联系方式。后端根据合同价格和默认配送费计算订单金额，不接受前端自行决定最终金额。

订单状态机如下：

```text
已创建 -> 已分配 -> 充装中 -> 已就绪 -> 配送中 -> 待确认 -> 已完成
   └------> 已取消
充装中/已就绪/配送中/待确认 -> 异常 -> 恢复到异常前状态
```

- 分配时必须选择启用配送点和处于启用、在岗状态的工作人员。
- 开始充装前必须已完成配送点分配。
- 每个状态动作要求当前状态合法，并追加状态记录。
- 完成订单必须处于待确认状态，并提交确认类型、收件人和可选凭证。
- 异常状态保留异常前状态，恢复时回到原状态。
- 通用资源编辑和状态字段直改不开放。

### 6.7 电商平台管理

| 资源 | 路径 | 模式 | 已实现能力 |
| --- | --- | --- | --- |
| 商品分类 | `/ec_category` | 可写树 | 分类新增、编辑、排序、启停和归档 |
| 商品管理 | `/ec_product` | 可写 | 商品编码、名称、售价、库存及状态管理 |
| 商品属性 | `/ec_product_attribute` | 可写 | 商品属性和值管理 |
| 商品图片 | `/ec_product_image` | 可写 | 图片地址、排序和封面管理 |
| 购物车 | `/ec_cart` | 只读 | 查询购物车事实 |
| 商城订单 | `/ec_order` | 只读 | 查询商城订单 |
| 商城订单明细 | `/ec_order_item` | 只读 | 查询商品和成交快照 |
| 商品评价 | `/ec_review` | 只读 | 查询评分和评价 |

平台当前只维护商品主数据。购物车、商城订单、订单明细和评价不允许平台后台通用新增、编辑、状态变更或删除。

### 6.8 钱包与提现

| 资源 | 路径 | 模式 | 已实现能力 |
| --- | --- | --- | --- |
| 钱包 | `/wallet_basic` | 只读 + 动作 | 按拥有者查询或幂等创建、后台充值、启用/停用/冻结 |
| 银行卡 | `/wallet_bank` | 只读 | 查询脱敏银行卡信息 |
| 钱包支付 | `/wallet_payment` | 只读 | 查询钱包支付记录 |
| 钱包流水 | `/wallet_record` | 只读 | 查询不可变余额流水 |
| 退款 | `/wallet_refund` | 只读 | 查询退款记录 |
| 提现 | `/wallet_apply_cash` | 只读 + 动作 | 审核通过、审核驳回、标记处理完成 |

钱包拥有者类型限定为气站、配送点、工作人员或用户。账户号等敏感字段在列表和非精确权限下脱敏。

后台充值必须携带唯一请求号、金额、是否进入可提现余额、原因和备注；后端在事务中更新余额并追加钱包流水，重复请求不得重复入账。

提现流程为：

```text
待处理 -> 已通过 -> 已完成
      └-> 已驳回
```

驳回必须填写原因；完成处理必须填写第三方流水号，可记录回调信息。申请人不能通过通用更新直接改变提现状态。

### 6.9 财务管理

| 资源 | 路径 | 模式 | 已实现能力 |
| --- | --- | --- | --- |
| 支付记录 | `/fin_payment` | 只读 | 查询支付渠道、金额和支付状态 |
| 财务结算 | `/fin_settlement` | 可写 | 结算单新增、编辑、启停和归档 |
| 财务对账 | `/fin_reconciliation` | 只读 | 查询渠道账单和差异 |

结算单记录结算编号、主体类型、主体 `identity` 和结算周期。支付与对账是外部或异步形成的事实，当前平台只提供查询。

### 6.10 内容与客服

| 资源 | 路径 | 模式 | 已实现能力 |
| --- | --- | --- | --- |
| 内容 | `/cms_content` | 可写 | 内容类型、标题、正文、版本和发布状态管理 |
| 客服工单 | `/cs_ticket` | 可写 | 用户、工单号、分类、优先级和状态管理 |

客服工单必须关联用户。首页将处于待受理状态的客服工单纳入待办指标。当前尚未实现客服会话、自动分派、SLA 升级和消息触达。

### 6.11 平台管理

| 资源 | 路径 | 模式 | 已实现能力 |
| --- | --- | --- | --- |
| 平台账户 | `/platform_account` | 可写 | 账户新增、编辑、启停和归档 |
| 平台角色 | `/platform_role` | 可写 | 角色新增、编辑、启停、归档和菜单分配 |
| 平台菜单 | `/platform_menu` | 只读树 | 查询系统初始化的菜单结构 |

平台账户必须关联角色编码。系统角色和 root 账户受保护，不能通过普通管理动作破坏。角色菜单通过 `/platform_role/:identity/menu` 整体读取和替换，菜单自身由系统初始化，不在后台任意增删改。

## 7. 通用页面与接口行为

- 列表资源提供分页、字段筛选、状态展示、详情和关联资源选择。
- 树资源用于商品分类和平台菜单层级展示。
- 关联选择器提交关联资源 `identity`，后端解析为内部自增外键。
- 密码字段只用于创建或显式更新，不在详情与列表返回明文。
- 所有资源响应经过统一响应封装；前端统一处理登录失效和错误提示。
- 业务动作在详情页按当前业务状态显示；即使前端未隐藏，后端仍必须拒绝非法状态转换。
- 路由、资源模式和页面能力由后端资源契约校验，任一层缺失时契约审计失败。

## 9. 现状验收标准

1. 匿名用户只能访问健康检查和登录；受保护资源缺少有效 JWT 时被拒绝。
2. 非 root 角色只能访问已分配菜单及其明确依赖资源，不能通过猜测路径访问同级资源。
3. 48 个资源的后端契约、实际路由、前端资源定义和页面加载关系一致。
4. 所有表保留自增 `id` 主键；主资源通过 UUID V7 `identity` 对外访问，前端不依赖内部 ID。
5. 气站必须先审核再启停，驳回原因和审核人可追溯。
6. 智能气阀归属和生命周期变更合法，并自动记录归属历史。
7. 合同启用、续签、终止和气瓶解绑只能在合法状态执行，并生成修订或操作记录。
8. 配送订单只能沿规定状态机流转；分配、异常、恢复、取消和完成均生成过程记录。
9. 钱包充值幂等、余额与流水在同一事务更新；提现只能按审核状态机处理。
10. 只读与仅追加资源不存在通用更新、状态修改或删除路由。
11. 首页指标来自数据库真实聚合，金额口径和最近 7 日补零正确。
12. 修改后端模型或路由后，`contract:sync`、`contract:check`、后端测试和前端构建均通过。