14 KiB
气站管理系统需求（规划基线）
1. 文档目的
本文按照 docs/05-平台总后台需求.md 的章节、资源模式、权限和验收口径，定义气站管理系统的规划基线。
当前仓库尚未创建 frontend/gas_admin，也没有气站管理系统独立后端、资源契约和实际路由。本文描述的是待实现能力，不得认定为已交付，不得为了完成本文而在平台总后台中增加气站日常操作。
后续实现事实按以下顺序核对并回写本文：
- 气站端实际 HTTP 路由。
- 气站端前后端资源契约。
- 气站端字段、关系、页面模式和业务动作定义。
- 气站端菜单、页面与隐藏子资源。
- 气站端状态机、事务、权限和数据范围校验。
2. 系统定位与边界
气站管理系统面向站长、站内运营、仓管、订单客服、站点调度和站点财务人员，负责本站库存、燃气配送订单、配送协同、客户服务、邀请注册和经营对账。
当前规划不替代以下系统：
- 平台总后台：全局组织、用户与人员账号、角色资质、跨站协同、资金审核和安全规则仍由平台主责。
- 配送点管理系统：配送点内部派员、配送仓和末端配送质控仍由配送点主责。
- 生产管理系统：生产批次、出厂质检、设备身份和召回仍由生产系统主责。
- 用户端与服务端 App：用户注册确认、配送员定位、现场检查、签收和取证仍由对应 App 完成。
- 电商平台：商品、分类、购物车、商城订单、评价和营销活动不属于气站管理系统。
气站不能创建全局用户、人员或配送点主体，不能授予安全角色，不能审核提现、修改资金流水、关闭平台安全事件或解除设备控制限制。新增主体、跨站调拨、人员角色和用户关系变更只能向平台申请。
独立 API 基础路径和鉴权请求头格式须在实现时通过契约确定；确定前不得沿用平台 API 路径冒充气站端接口。
3. 技术与数据约定
3.1 实现目录
| 范围 | 规划目录 | 职责 |
|---|---|---|
| 管理端 | frontend/gas_admin |
Vue 3、TypeScript、Vite、Pinia、Arco Design |
| 页面 | frontend/gas_admin/src/views |
首页、报表及按业务域组织的资源页面 |
| 资源定义 | frontend/gas_admin/src/api |
字段、关系、页面模式和业务动作 |
| 前端契约 | frontend/gas_admin/src/contracts |
后端资源与路由生成清单 |
| 前端路由 | frontend/gas_admin/src/router |
菜单、受控本地路由和隐藏详情资源 |
| 后端 API | 待技术设计确认 | 气站同步业务事务、鉴权和统一响应 |
| 业务逻辑 | 待技术设计确认 | 本站库存、订单、邀请、协同和对账规则 |
| 模型 | 待技术设计确认 | 气站主责事实模型与中文注释 |
| 初始化 | 待技术设计确认 | 系统必需角色与菜单，不包含演示数据 |
以上目录均为规划归属，任务未明确要求前不得提前创建空壳工程。新管理端须复用 sample/front 的公共机制，新 Go 进程须遵循 sample/server 的分层。
3.2 数据身份
- 每一张表均使用
id bigint自增主键，Go 模型对应ID uint64。 - 主表及需要单独访问、跨系统引用或审计定位的明细表使用 UUID V7
identity。 id仅用于数据库内部关联；HTTP、前端、事件、审计和跨服务调用使用identity。- 气站数据范围至少校验
gas_basic_identity、资源归属和订单/任务关系。 - 通用状态与库存、订单、邀请、售后和结算等业务状态分离。
- 删除执行归档或受控删除；订单、库存流水、支付、结算、邀请使用记录和现场事实不得物理删除。
- 金额使用最小货币单位整数；前端不得自行决定订单最终金额、结算结果或余额。
3.3 资源页面模式
| 模式 | 能力 |
|---|---|
writable |
列表、详情、新增、编辑、状态调整和归档 |
editable |
列表、详情、新增、编辑和状态调整，不提供归档 |
readonly |
列表和详情；可通过显式业务动作处理，但无通用增删改 |
append_only |
可创建事实记录，既有记录不通用编辑或删除 |
managed |
可创建和编辑，但生命周期必须通过专用动作推进 |
普通资源应复用共享资源页面。库存流水、订单过程、邀请使用记录、支付和结算事实使用只读或仅追加模式；业务状态不得通过通用 CRUD 直接修改。
4. 登录、账户与权限
4.1 登录与个人账户
- 气站后台账号由平台创建或关联，气站系统不提供自助创建管理员账号。
- 停用、冻结、未关联本站或角色无效的账户不得登录。
- 登录成功返回 JWT、账户
identity、显示名称、角色编码、气站identity和菜单编码。 - 已登录账户只能查看和修改本人的非敏感资料；角色、气站归属和数据范围不能自行修改。
- 修改密码必须校验当前密码，新密码不少于 6 位。
- 气站系统不得初始化共享默认管理员密码；首次账号由平台受控创建。
4.2 RBAC 与数据能力
- 站长、站内运营、仓管、订单客服、站点调度和站点财务使用独立菜单能力。
- 站长不自动拥有财务、仓管、敏感导出或安全相关能力。
- 仓管只能操作本站库存，不能修改订单金额、资金、安全事件和人员权限。
- 订单客服只能访问完成本站服务所需的脱敏用户信息。
- 站点调度只能向已归属本站的配送点发布需求，不能代替配送点分配普通配送员。
- 站点财务只能查看本站对账和提交异议、提现申请，不能审核申请、改流水或确认打款。
- 邀请管理权限独立授予；邀请码只能绑定当前气站和已授权服务区域。
- 精确定位、完整证据和敏感导出使用独立权限并记录用途。
- 前端菜单隐藏只负责展示，最终权限由服务端执行。
5. 首页与报表
首页规划聚合以下本站指标：
- 当前库存、在途调拨、待处理盘点差异和库存预警。
- 今日燃气配送订单、待配送、配送中、待确认、异常和已完成数量。
- 已启用配送点数量及其容量、超时和异常摘要。
- 本站关联在岗人员数量和作业前置异常数量。
- 待处理售后、投诉和安全协同事项。
- 邀请二维码启用数、扫码数、注册数和服务关系建立数。
- 当前结算周期的订单金额、配送服务费和对账差异。
- 最近 7 个自然日的燃气配送订单数量与金额趋势；无数据日期补零。
首页快捷入口按角色菜单过滤。报表只聚合本站真实业务事实，不展示其他气站明细，不生成虚构数据，不提供电商销售报表。
6. 规划功能域
规划路径必须在独立气站端契约中确认。下表的“路径”统一标记为待确认，不得直接复用平台资源路径。
6.1 气站经营设置
| 资源 | 路径 | 模式 | 规划能力 |
|---|---|---|---|
| 气站资料 | 待契约确认 | readonly |
查看平台维护的主体、证照、地址、服务区域和组织状态 |
| 营业设置 | 待契约确认 | managed |
维护营业时段、预约容量、值班联系方式和临时接单状态 |
| 组织变更申请 | 待契约确认 | append_only |
提交地址、区域、主体、冻结、归档等平台审核申请 |
气站不能直接修改平台组织主数据。服务能力只能查看平台授权结果，不能自行增加配送、安装维修或安检能力。
6.2 站内库存
| 资源 | 路径 | 模式 | 规划能力 |
|---|---|---|---|
| 库存余额 | 待契约确认 | readonly |
查询本站设备、气瓶、批次和可用/冻结/在途数量 |
| 库存流水 | 待契约确认 | append_only |
记录入库、出库、退回、损耗和盘点调整依据 |
| 调拨单 | 待契约确认 | managed |
向本站配送点调拨；跨站调拨提交平台审批 |
| 盘点单 | 待契约确认 | managed |
创建盘点、记录实盘和差异，按阈值复核 |
库存余额不能直接编辑。每次变化必须关联业务单据、批次、数量、来源、去向、操作者和幂等键。
6.3 配送点协同
| 资源 | 路径 | 模式 | 规划能力 |
|---|---|---|---|
| 配送点能力 | 待契约确认 | readonly |
查看已归属本站配送点的状态、区域、容量和异常摘要 |
| 配送需求 | 待契约确认 | managed |
向已启用配送点发布本站履约需求并跟踪确认 |
| 配送异常 | 待契约确认 | append_only |
记录超时、拒收、货损、退回和协调结果 |
| 配送点变更申请 | 待契约确认 | append_only |
申请新增、迁移、冻结、归档或区域调整 |
气站不能直接进入配送点后台代替调度，不能修改配送员 App 产生的接单、定位、扫码和签收事实。
6.4 人员协同
| 资源 | 路径 | 模式 | 规划能力 |
|---|---|---|---|
| 人员名册 | 待契约确认 | readonly |
查看平台已关联本站或本站配送点的人员 |
| 作业能力 | 待契约确认 | readonly |
查看角色、资质、培训、服务区域、在岗和可接单结果 |
| 人员变更申请 | 待契约确认 | append_only |
申请新增关联、角色变更、冻结、离职和跨站调动 |
气站不能创建人员全局账号，不能授予安全角色、修改资质结论或代替现场人员完成任务。
6.5 燃气配送订单
| 资源 | 路径 | 模式 | 规划能力 |
|---|---|---|---|
| 配送订单 | 待契约确认 | managed |
查看本站订单并执行本站职责范围内的专用动作 |
| 订单明细 | 待契约确认 | readonly |
查看合同气瓶、数量、金额和联系人快照 |
| 订单状态记录 | 待契约确认 | readonly |
查询每次状态变化、操作者和原因 |
| 配送分配摘要 | 待契约确认 | readonly |
查看配送点和任务分配结果，不直接改配送员 |
| 签收与现场证据 | 待契约确认 | readonly |
查看 App 形成的签收、扫码、照片和收款确认 |
后端依据有效合同、气瓶、库存和服务费规则读取或计算金额。取消、异常、恢复和完成必须通过专用动作并追加状态记录。
6.6 客户服务
| 资源 | 路径 | 模式 | 规划能力 |
|---|---|---|---|
| 本站客户视图 | 待契约确认 | readonly |
查看本站服务必需的脱敏联系人、地址和服务摘要 |
| 服务记录 | 待契约确认 | append_only |
记录预约、回访、通知和客户联系结果 |
| 售后与投诉 | 待契约确认 | managed |
受理本站售后、投诉并按状态流转 |
| 用户变更申请 | 待契约确认 | append_only |
提交资料纠错、关系解除或注销协办申请 |
气站不能创建或编辑全局用户、查看完整钱包、冻结登录、修改其他气站关系或解除设备安全限制。
6.7 邀请注册
| 资源 | 路径 | 模式 | 规划能力 |
|---|---|---|---|
| 邀请二维码 | 待契约确认 | managed |
创建、预览、下载、启停和重新生成本站邀请 |
| 邀请使用记录 | 待契约确认 | readonly |
查询扫码、注册、关系建立和失败原因 |
| 邀请统计 | 待契约确认 | readonly |
聚合扫码、注册和服务关系转化 |
二维码只承载平台签名、可撤销且可过期的令牌或短链接。新用户完成平台统一注册；已有用户确认后只建立本站服务关系。重复扫码不得覆盖既有关系。
6.8 对账与提现申请
| 资源 | 路径 | 模式 | 规划能力 |
|---|---|---|---|
| 对账视图 | 待契约确认 | readonly |
查看本站订单、支付、服务费、库存交接和差异 |
| 对账异议 | 待契约确认 | append_only |
提交差异、凭证和处理意见 |
| 结算单 | 待契约确认 | readonly |
查看平台生成的本站结算结果 |
| 提现申请 | 待契约确认 | append_only |
在校验通过后提交申请并查看处理状态 |
气站不能创建资金流水、调整余额、审核提现、调整分账比例或确认实际打款。
7. 通用页面与接口行为
- 列表资源提供分页、字段筛选、状态展示、详情和受数据范围约束的关联选择。
- 关联字段提交业务
identity，后端解析为内部关联。 - 账户密码不在详情和列表返回明文。
- 响应使用统一封装；前端统一处理登录失效和稳定错误码。
- 写操作携带幂等键；异步操作返回可查询标识。
- 业务动作按当前状态展示，但后端仍必须拒绝非法流转。
- 现场证据、轨迹、支付、资金流水和安全事件仅查询，不开放通用修改或删除。
- 邀请、订单、库存、对账和敏感访问记录完整审计。
- 路由、资源模式、菜单、权限和前端页面必须通过契约检查保持一致。
9. 规划验收标准
- 匿名用户只能访问登录和明确公开接口；所有业务资源要求有效认证。
- 账户只能访问所属气站及已分配菜单，不能猜测路径访问其他气站数据。
- 实际路由、资源契约、页面定义、菜单和本文资源模式一致。
- 所有表保留自增
id；对外统一使用 UUID V7identity。 - 气站不能创建全局用户、人员或配送点主体，不能授予安全角色。
- 库存变化由业务流水驱动，余额不能直接编辑。
- 配送点内部调度和 App 现场事实不能由气站后台代填或修改。
- 燃气配送订单只能沿服务端状态机流转并追加过程记录。
- 邀请只能在本站授权区域内生效，不能重复建用户或覆盖既有服务关系。
- 气站只能提交对账异议和提现申请，不能修改资金或审核打款。
- 首页与报表来自本站真实数据，不包含电商或其他气站数据。
- 契约检查、权限测试、状态机测试、后端测试和前端构建全部通过。