platforms/docs/06-气站管理系统需求.md

# 气站管理系统需求

## 1. 文档目的

本文以 `docs/05-平台总后台需求.md` 的资源、权限、状态机和验收口径为基线，定义气站管理系统的实施范围。

- 前端：`frontend/gas_admin`，基于平台管理端公共机制建设。
- 后端：复用 `backend/api`，业务逻辑位于 `internal/logic/gas`。
- API 前缀：`/heqi/gas/v1`。
- 开发端口：`5175`。
- 数据模型：复用现有 `backend/api/internal/models`，本期不新增气站角色、菜单或邀请表。

## 2. 系统定位与边界

气站管理系统面向气站管理员，管理当前气站的运营数据。所有资源必须以后端 JWT 中的 `gas_basic_identity` 为数据范围，前端隐藏菜单不构成权限控制。

本期包含：

- 数据概述与订单状态报表。
- 当前气站的配送点及配送点账号管理。
- 当前气站的工作人员及资质管理。
- 当前气站服务用户、地址和唯一服务关系管理。
- 配送合同、合同气瓶和合同修订记录。
- 燃气配送订单创建、分配及气站职责内状态动作。
- 当前气站钱包、支付、流水、退款、提现、结算和对账视图。
- 当前气站用户的客服工单。
- 基于气站 identity 的用户注册邀请二维码。

本期不包含：

- 库存、库存流水及配送点内部调度。
- 商品、分类、购物车、商城订单、评价及营销等电商功能。
- 生产、设备入网、设备检修和平台全局治理。
- 平台资金充值、冻结、提现审批、驳回和打款完成。
- 配送人员或用户端负责的开始配送、等待签收和完成订单。

## 3. 技术、身份与鉴权

### 3.1 登录与会话

- 气站账号由平台总后台创建；气站端不允许自助创建管理员。
- 仅启用状态、关联启用气站且 `role_code = admin` 的 `gas_account` 可以登录。
- JWT 客户端固定为 `gas_admin`，与平台总后台会话隔离。
- 登录后由后端 `gas_menu` 接口按 `role_code` 返回静态菜单，前端据此渲染。
- 修改密码必须校验当前密码；新密码仅校验长度不少于 6 位。
- 用户、配送点和工作人员账号在创建或修改密码时同样仅要求不少于 6 位，不校验其他复杂度。

### 3.2 数据身份与归属

- HTTP、前端和审计统一使用 `identity`，不暴露数据库自增 ID。
- 每个用户只能存在一条未归档的 `user_service_relation`，且只能归属一个气站和一个配送点。
- 配送点、工作人员、用户、合同、订单、钱包和工单均须由后端验证属于当前气站。
- 禁止通过提交其他气站 identity、猜测 URL 或修改请求体越权。
- 删除均为归档；订单、合同修订、资金事实和轨迹事实不得物理删除。

## 4. 菜单与功能

### 4.1 数据概述

| 菜单 | 能力 |
| --- | --- |
| 运营概览 | 当前气站配送点、工作人员、用户、合同和订单数量 |
| 统计报表 | 当前气站订单状态分布 |

统计必须来源于真实业务表，不能混入其他气站或电商数据。

### 4.2 配送点管理

- 配送点支持列表、详情、新增、编辑、启停和归档。
- 配送点账号支持新增、编辑、启停、修改密码和归档。
- 创建和更新时，气站归属由服务端写入，不能由前端指定。
- 配送点存在未完成订单或有效用户服务关系时不得归档。
- 归档配送点时同步归档其账号，不自动迁移用户或订单。

### 4.3 工作人员管理

角色仅包括：

- 安装人员 `installer`
- 配送人员 `delivery`
- 运维人员 `operations`

工作人员支持新增、编辑、启停和归档；资质支持新增、编辑、启停和归档。工作人员只能归属当前气站，可选归属当前气站的一个配送点。存在未完成订单时不得归档。删除工作人员和资质均更新为已归档。

### 4.4 用户管理

- 支持用户新增、编辑、启停和归档。
- 创建用户时在同一事务内创建其当前气站、当前配送点服务关系。
- 支持当前气站用户地址新增、编辑、启停和归档。
- 可修改用户归属的当前气站配送点，不支持跨气站迁移。
- 用户存在未完成配送订单、未关闭工单、钱包余额、可提现余额或待处理提现时不得归档。
- 归档用户时同时归档地址和服务关系。

### 4.5 合同管理

- 配送合同支持创建、草稿编辑、启用、续签和终止。
- 合同只能选择当前气站用户及当前气站配送点。
- 合同气瓶支持绑定和受控解绑。
- 合同修订记录只读，不允许修改或删除。
- 合同状态只能通过专用动作接口推进，不能通用编辑 `contract_status`。

### 4.6 燃气配送订单

- 气站可基于当前气站生效合同创建订单。
- 服务端强制订单创建方为当前气站，不接受前端伪造创建方。
- 可将订单分配到当前气站配送点及当前气站工作人员。
- 气站端允许动作：分配、开始罐装、待配送、标记异常、恢复、取消。
- 气站端不得执行：开始配送、等待签收、完成订单。
- 订单明细、分配记录、状态记录、轨迹、签收和支付记录均为只读事实。

### 4.7 财务管理

- 钱包、银行卡、支付记录、钱包流水、退款记录、结算记录只读。
- 气站可以创建提现申请并查看处理结果。
- 气站不能充值、冻结钱包，不能审批、驳回或标记提现完成。
- 所有金额使用最小货币单位整数，服务端校验余额和归属。
- `fin_reconciliation` 当前模型没有气站主体字段，为避免泄露平台全局渠道数据，气站端在补齐可验证归属前不返回全局记录。

### 4.8 工单管理

- 支持当前气站用户的客服工单新增、编辑、状态调整和归档。
- 不得读取或操作其他气站用户的工单。
- 不新增重复工单模型，统一复用 `cs_ticket`。

### 4.9 邀请注册

- 邀请二维码不持久化，不新增邀请表。
- 注册基础地址由配置项 `Gas.UserRegisterURL` 提供。
- 后端按当前气站生成：
  `UserRegisterURL?gas_identity={gas_basic_identity}`。
- 前端将 URL 生成二维码并支持下载 PNG。
- 二维码只携带气站业务 identity，不携带内部 ID、密码或 JWT。

## 5. 资源与页面模式

| 资源 | 模式 | 说明 |
| --- | --- | --- |
| `delivery_basic`、`delivery_account` | `writable` | 当前气站范围 |
| `staff_account`、`staff_credential` | `writable` | 删除为归档 |
| `user_account`、`user_address` | `writable` | 服务关系由后端事务维护 |
| `gasorder_contract` | `managed` | 生命周期使用专用动作 |
| `gasorder_contract_product` | `append_only` | 解绑使用专用动作 |
| `gasorder_contract_revision` | `readonly` | 不可变历史 |
| `gasorder_basic` | `append_only` | 创建及专用状态动作 |
| `wallet_basic`、`wallet_bank`、`wallet_payment`、`wallet_record`、`wallet_refund` | `readonly` | 当前气站钱包范围 |
| `wallet_apply_cash` | `append_only` | 只允许申请，不允许审核 |
| `fin_settlement`、`fin_reconciliation` | `readonly` | 不开放通用写入 |
| `cs_ticket` | `writable` | 当前气站用户范围 |

## 6. 菜单输出

菜单定义保存在 `backend/api/internal/logic/gas/menu.go`，仅 `admin` 角色返回：

1. 数据概述：运营概览、统计报表。
2. 配送点管理：配送点列表；配送点账号为隐藏子资源。
3. 工作人员管理：新增工作人员、安装人员、配送人员、运维人员；资质为隐藏子资源。
4. 用户管理：用户账户；地址和服务关系为隐藏子资源。
5. 合同管理：配送合同；合同气瓶和修订记录为隐藏子资源。
6. 燃气配送订单：创建订单、配送订单；过程子资源只读且隐藏。
7. 财务管理：钱包、银行卡、支付记录、钱包流水、退款记录、提现申请、财务结算、财务对账。
8. 工单管理：客服工单。
9. 邀请注册：邀请二维码。

## 7. 接口与安全要求

- 匿名接口仅有登录；其余接口必须通过 JWT 和当前气站账号校验。
- 路由、资源模式、后端契约和前端页面必须同步。
- 状态流转、账号归属、用户唯一服务关系、金额和归档阻断全部由服务端校验。
- 密码、银行卡密文、证件密文等敏感字段不得返回前端。
- 手机号、地址、合同文件和定位等敏感信息按现有统一响应保护规则处理。
- 订单和提现创建必须使用业务幂等号；重复请求不得重复创建业务事实。
- 写操作及敏感访问应纳入统一审计能力。

## 8. 验收标准

1. 气站账号登录后由后端菜单数据渲染前端菜单，非 `admin` 角色无菜单。
2. 平台 JWT 不能作为气站 JWT 使用，气站 JWT 不能访问平台后台。
3. 所有业务资源只能访问当前气站数据。
4. 配送点管理、工作人员管理、用户管理、合同管理、订单、财务、工单和邀请功能可用。
5. 气站端无库存、调度、电商、生产设备和平台治理功能。
6. 气站端不暴露开始配送、等待签收、完成订单及提现审批动作。
7. 所有删除均为归档，并正确执行未完成业务阻断。
8. 每个用户只能归属一个气站和一个配送点。
9. 邀请二维码由配置 URL 和当前气站 identity 实时生成，不产生持久化记录。
10. 后端测试、路由权限测试、前端类型检查、契约检查和生产构建通过。