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. 后端测试、路由权限测试、前端类型检查、契约检查和生产构建通过。