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. 已实现功能域

当前资源契约共 47 个资源。下表中的路径均相对于 /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 智能气阀管理

资源	路径	模式	已实现能力
类型	/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	只读	查询配送订单支付事实

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

订单状态机如下：

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

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

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	只读 + 动作	审核通过、审核驳回、标记处理完成

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

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

提现流程为：

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

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

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