# 气站管理系统需求 ## 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. 后端测试、路由权限测试、前端类型检查、契约检查和生产构建通过。