feat: implement gas and delivery admin systems

This commit is contained in:
david
2026-07-30 14:16:58 +08:00
parent 1093385f95
commit f5ecc0d973
252 changed files with 49385 additions and 363 deletions

View File

@@ -1,228 +1,185 @@
# 气站管理系统需求(规划基线)
# 气站管理系统需求
## 1. 文档目的
本文按照 `docs/05-平台总后台需求.md`章节、资源模式、权限和验收口径,定义气站管理系统的规划基线
本文 `docs/05-平台总后台需求.md`资源、权限、状态机和验收口径为基线,定义气站管理系统的实施范围
前端工作目录: `frontend/gas_admin` 完全复制:`frontend/platform_admin`内所有文件在修改
后端工作目录:`backend/api` 与总平台复用一个API目录
后端API的URL前缀:/heqi/gas/v1
后续实现事实按以下顺序核对并回写本文:
1. 气站端实际 HTTP 路由。
2. 气站端前后端资源契约。
3. 气站端字段、关系、页面模式和业务动作定义。
4. 气站端菜单、页面与隐藏子资源。
5. 气站端状态机、事务、权限和数据范围校验。
- 前端:`frontend/gas_admin`,基于平台管理端公共机制建设。
- 后端:复用 `backend/api`,业务逻辑位于 `internal/logic/gas`
- API 前缀:`/heqi/gas/v1`
- 开发端口:`5175`
- 数据模型:复用现有 `backend/api/internal/models`,本期不新增气站角色、菜单或邀请表。
## 2. 系统定位与边界
气站管理系统面向站长、站内运营、仓管、订单客服、站点调度和站点财务人员,负责本站库存、燃气配送订单、配送协同、客户服务、邀请注册和经营对账
气站管理系统面向气站管理员,管理当前气站的运营数据。所有资源必须以后端 JWT 中的 `gas_basic_identity` 为数据范围,前端隐藏菜单不构成权限控制
当前规划不替代以下系统
本期包含
- 平台总后台:全局组织、用户与人员账号、角色资质、跨站协同、资金审核和安全规则仍由平台主责
- 配送点管理系统:配送点内部派员、配送仓和末端配送质控仍由配送点主责
- 生产管理系统:生产批次、出厂质检、设备身份和召回仍由生产系统主责
- 用户端与服务端 App用户注册确认、配送员定位、现场检查、签收和取证仍由对应 App 完成
- 电商平台:商品、分类、购物车、商城订单、评价和营销活动不属于气站管理系统
- 数据概述与订单状态报表
- 当前气站的配送点及配送点账号管理
- 当前气站的工作人员及资质管理
- 当前气站服务用户、地址和唯一服务关系管理
- 配送合同、合同气瓶和合同修订记录
- 燃气配送订单创建、分配及气站职责内状态动作。
- 当前气站钱包、支付、流水、退款、提现、结算和对账视图。
- 当前气站用户的客服工单。
- 基于气站 identity 的用户注册邀请二维码。
气站不能创建全局用户、人员或配送点主体,不能授予安全角色,不能审核提现、修改资金流水、关闭平台安全事件或解除设备控制限制。新增主体、跨站调拨、人员角色和用户关系变更只能向平台申请。
本期不包含:
独立 API 基础路径和鉴权请求头格式须在实现时通过契约确定;确定前不得沿用平台 API 路径冒充气站端接口
- 库存、库存流水及配送点内部调度
- 商品、分类、购物车、商城订单、评价及营销等电商功能。
- 生产、设备入网、设备检修和平台全局治理。
- 平台资金充值、冻结、提现审批、驳回和打款完成。
- 配送人员或用户端负责的开始配送、等待签收和完成订单。
## 3. 技术与数据约定
## 3. 技术、身份与鉴权
### 3.1 实现目录
### 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 | `backend/api` | Gin HTTP API、JWT、事务和统一响应 |
| 路由 | `backend/api/internal/routers/gas.go` | 平台 API 唯一路由注册入口 |
| 业务逻辑 | `backend/api/internal/logic/gas` | 各领域查询、动作、权限和状态流转 |
| 模型 | `backend/api/internal/models` | 复用现在的,没特殊要求不可新增 |
- 气站账号由平台总后台创建;气站端不允许自助创建管理员。
- 仅启用状态、关联启用气站且 `role_code = admin``gas_account` 可以登录。
- JWT 客户端固定为 `gas_admin`,与平台总后台会话隔离。
- 登录后由后端 `gas_menu` 接口按 `role_code` 返回静态菜单,前端据此渲染。
- 修改密码必须校验当前密码;新密码仅校验长度不少于 6 位。
- 用户、配送点和工作人员账号在创建或修改密码时同样仅要求不少于 6 位,不校验其他复杂度。
以上目录均为规划归属,任务未明确要求前不得提前创建空壳工程。新管理端须复用 `sample/front` 的公共机制,新 Go 进程须遵循 `sample/server` 的分层。
### 3.2 数据身份与归属
### 3.2 数据身份
- HTTP、前端和审计统一使用 `identity`,不暴露数据库自增 ID。
- 每个用户只能存在一条未归档的 `user_service_relation`,且只能归属一个气站和一个配送点。
- 配送点、工作人员、用户、合同、订单、钱包和工单均须由后端验证属于当前气站。
- 禁止通过提交其他气站 identity、猜测 URL 或修改请求体越权。
- 删除均为归档;订单、合同修订、资金事实和轨迹事实不得物理删除。
- 每一张表均使用 `id bigint` 自增主键Go 模型对应 `ID uint64`
- 主表及需要单独访问、跨系统引用或审计定位的明细表使用 UUID V7 `identity`
- `id` 仅用于数据库内部关联HTTP、前端、事件、审计和跨服务调用使用 `identity`
- 气站数据范围至少校验 `gas_basic_identity`、资源归属和订单/任务关系。
- 通用状态与库存、订单、邀请、售后和结算等业务状态分离。
- 删除执行归档或受控删除;订单、库存流水、支付、结算、邀请使用记录和现场事实不得物理删除。
- 金额使用最小货币单位整数;前端不得自行决定订单最终金额、结算结果或余额。
## 4. 菜单与功能
### 3.3 资源页面模式
### 4.1 数据概述
| 模式 | 能力 |
| 菜单 | 能力 |
| --- | --- |
| `writable` | 列表、详情、新增、编辑、状态调整和归档 |
| `editable` | 列表、详情、新增、编辑和状态调整,不提供归档 |
| `readonly` | 列表和详情;可通过显式业务动作处理,但无通用增删改 |
| `append_only` | 可创建事实记录,既有记录不通用编辑或删除 |
| `managed` | 可创建和编辑,但生命周期必须通过专用动作推进 |
| 运营概览 | 当前气站配送点、工作人员、用户、合同和订单数量 |
| 统计报表 | 当前气站订单状态分布 |
普通资源应复用共享资源页面。库存流水、订单过程、邀请使用记录、支付和结算事实使用只读或仅追加模式;业务状态不得通过通用 CRUD 直接修改
统计必须来源于真实业务表,不能混入其他气站或电商数据
## 4. 登录、账户与权限
### 4.2 配送点管理
### 4.1 登录与个人账户
- 配送点支持列表、详情、新增、编辑、启停和归档。
- 配送点账号支持新增、编辑、启停、修改密码和归档。
- 创建和更新时,气站归属由服务端写入,不能由前端指定。
- 配送点存在未完成订单或有效用户服务关系时不得归档。
- 归档配送点时同步归档其账号,不自动迁移用户或订单。
- 气站后台账号由平台创建或关联,气站系统不提供自助创建管理员账号。
- 停用、冻结、未关联本站或角色无效的账户不得登录。
- 登录成功返回 JWT、账户 `identity`、显示名称、角色编码、气站 `identity` 和菜单编码。
- 已登录账户只能查看和修改本人的非敏感资料;角色、气站归属和数据范围不能自行修改。
- 修改密码必须校验当前密码,新密码不少于 6 位。
- 气站系统不得初始化共享默认管理员密码;首次账号由平台受控创建。
### 4.3 工作人员管理
### 4.2 RBAC 与数据能力
角色仅包括:
- 站长、站内运营、仓管、订单客服、站点调度和站点财务使用独立菜单能力。
- 站长不自动拥有财务、仓管、敏感导出或安全相关能力。
- 仓管只能操作本站库存,不能修改订单金额、资金、安全事件和人员权限。
- 订单客服只能访问完成本站服务所需的脱敏用户信息。
- 站点调度只能向已归属本站的配送点发布需求,不能代替配送点分配普通配送员。
- 站点财务只能查看本站对账和提交异议、提现申请,不能审核申请、改流水或确认打款。
- 邀请管理权限独立授予;邀请码只能绑定当前气站和已授权服务区域。
- 精确定位、完整证据和敏感导出使用独立权限并记录用途。
- 前端菜单隐藏只负责展示,最终权限由服务端执行。
- 安装人员 `installer`
- 配送人员 `delivery`
- 运维人员 `operations`
## 5. 首页与报表
工作人员支持新增、编辑、启停和归档;资质支持新增、编辑、启停和归档。工作人员只能归属当前气站,可选归属当前气站的一个配送点。存在未完成订单时不得归档。删除工作人员和资质均更新为已归档。
首页规划聚合以下本站指标:
### 4.4 用户管理
- 当前库存、在途调拨、待处理盘点差异和库存预警
- 今日燃气配送订单、待配送、配送中、待确认、异常和已完成数量
- 已启用配送点数量及其容量、超时和异常摘要
- 本站关联在岗人员数量和作业前置异常数量
- 待处理售后、投诉和安全协同事项
- 邀请二维码启用数、扫码数、注册数和服务关系建立数
- 当前结算周期的订单金额、配送服务费和对账差异。
- 最近 7 个自然日的燃气配送订单数量与金额趋势;无数据日期补零。
- 支持用户新增、编辑、启停和归档
- 创建用户时在同一事务内创建其当前气站、当前配送点服务关系
- 支持当前气站用户地址新增、编辑、启停和归档
- 可修改用户归属的当前气站配送点,不支持跨气站迁移
- 用户存在未完成配送订单、未关闭工单、钱包余额、可提现余额或待处理提现时不得归档
- 归档用户时同时归档地址和服务关系。
首页快捷入口按角色菜单过滤。报表只聚合本站真实业务事实,不展示其他气站明细,不生成虚构数据,不提供电商销售报表。
### 4.5 合同管理
## 6. 规划功能域
- 配送合同支持创建、草稿编辑、启用、续签和终止。
- 合同只能选择当前气站用户及当前气站配送点。
- 合同气瓶支持绑定和受控解绑。
- 合同修订记录只读,不允许修改或删除。
- 合同状态只能通过专用动作接口推进,不能通用编辑 `contract_status`
规划路径必须在独立气站端契约中确认。下表的“路径”统一标记为待确认,不得直接复用平台资源路径。
### 4.6 燃气配送订单
### 6.1 气站经营设置
- 气站可基于当前气站生效合同创建订单。
- 服务端强制订单创建方为当前气站,不接受前端伪造创建方。
- 可将订单分配到当前气站配送点及当前气站工作人员。
- 气站端允许动作:分配、开始罐装、待配送、标记异常、恢复、取消。
- 气站端不得执行:开始配送、等待签收、完成订单。
- 订单明细、分配记录、状态记录、轨迹、签收和支付记录均为只读事实。
| 资源 | 路径 | 模式 | 规划能力 |
| --- | --- | --- | --- |
| 气站资料 | 待契约确认 | `readonly` | 查看平台维护的主体、证照、地址、服务区域和组织状态 |
| 营业设置 | 待契约确认 | `managed` | 维护营业时段、预约容量、值班联系方式和临时接单状态 |
| 组织变更申请 | 待契约确认 | `append_only` | 提交地址、区域、主体、冻结、归档等平台审核申请 |
### 4.7 财务管理
气站不能直接修改平台组织主数据。服务能力只能查看平台授权结果,不能自行增加配送、安装维修或安检能力
- 钱包、银行卡、支付记录、钱包流水、退款记录、结算记录只读
- 气站可以创建提现申请并查看处理结果。
- 气站不能充值、冻结钱包,不能审批、驳回或标记提现完成。
- 所有金额使用最小货币单位整数,服务端校验余额和归属。
- `fin_reconciliation` 当前模型没有气站主体字段,为避免泄露平台全局渠道数据,气站端在补齐可验证归属前不返回全局记录。
### 6.2 站内库存
### 4.8 工单管理
| 资源 | 路径 | 模式 | 规划能力 |
| --- | --- | --- | --- |
| 库存余额 | 待契约确认 | `readonly` | 查询本站设备、气瓶、批次和可用/冻结/在途数量 |
| 库存流水 | 待契约确认 | `append_only` | 记录入库、出库、退回、损耗和盘点调整依据 |
| 调拨单 | 待契约确认 | `managed` | 向本站配送点调拨;跨站调拨提交平台审批 |
| 盘点单 | 待契约确认 | `managed` | 创建盘点、记录实盘和差异,按阈值复核 |
- 支持当前气站用户的客服工单新增、编辑、状态调整和归档。
- 不得读取或操作其他气站用户的工单。
- 不新增重复工单模型,统一复用 `cs_ticket`
库存余额不能直接编辑。每次变化必须关联业务单据、批次、数量、来源、去向、操作者和幂等键。
### 4.9 邀请注册
### 6.3 配送点协同
- 邀请二维码不持久化,不新增邀请表。
- 注册基础地址由配置项 `Gas.UserRegisterURL` 提供。
- 后端按当前气站生成:
`UserRegisterURL?gas_identity={gas_basic_identity}`
- 前端将 URL 生成二维码并支持下载 PNG。
- 二维码只携带气站业务 identity不携带内部 ID、密码或 JWT。
| 资源 | 路径 | 模式 | 规划能力 |
| --- | --- | --- | --- |
| 配送点能力 | 待契约确认 | `readonly` | 查看已归属本站配送点的状态、区域、容量和异常摘要 |
| 配送需求 | 待契约确认 | `managed` | 向已启用配送点发布本站履约需求并跟踪确认 |
| 配送异常 | 待契约确认 | `append_only` | 记录超时、拒收、货损、退回和协调结果 |
| 配送点变更申请 | 待契约确认 | `append_only` | 申请新增、迁移、冻结、归档或区域调整 |
## 5. 资源与页面模式
气站不能直接进入配送点后台代替调度,不能修改配送员 App 产生的接单、定位、扫码和签收事实。
| 资源 | 模式 | 说明 |
| --- | --- | --- |
| `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.4 人员协同
## 6. 菜单输出
| 资源 | 路径 | 模式 | 规划能力 |
| --- | --- | --- | --- |
| 人员名册 | 待契约确认 | `readonly` | 查看平台已关联本站或本站配送点的人员 |
| 作业能力 | 待契约确认 | `readonly` | 查看角色、资质、培训、服务区域、在岗和可接单结果 |
| 人员变更申请 | 待契约确认 | `append_only` | 申请新增关联、角色变更、冻结、离职和跨站调动 |
菜单定义保存在 `backend/api/internal/logic/gas/menu.go`,仅 `admin` 角色返回:
气站不能创建人员全局账号,不能授予安全角色、修改资质结论或代替现场人员完成任务
1. 数据概述:运营概览、统计报表
2. 配送点管理:配送点列表;配送点账号为隐藏子资源。
3. 工作人员管理:新增工作人员、安装人员、配送人员、运维人员;资质为隐藏子资源。
4. 用户管理:用户账户;地址和服务关系为隐藏子资源。
5. 合同管理:配送合同;合同气瓶和修订记录为隐藏子资源。
6. 燃气配送订单:创建订单、配送订单;过程子资源只读且隐藏。
7. 财务管理:钱包、银行卡、支付记录、钱包流水、退款记录、提现申请、财务结算、财务对账。
8. 工单管理:客服工单。
9. 邀请注册:邀请二维码。
### 6.5 燃气配送订单
## 7. 接口与安全要求
| 资源 | 路径 | 模式 | 规划能力 |
| --- | --- | --- | --- |
| 配送订单 | 待契约确认 | `managed` | 查看本站订单并执行本站职责范围内的专用动作 |
| 订单明细 | 待契约确认 | `readonly` | 查看合同气瓶、数量、金额和联系人快照 |
| 订单状态记录 | 待契约确认 | `readonly` | 查询每次状态变化、操作者和原因 |
| 配送分配摘要 | 待契约确认 | `readonly` | 查看配送点和任务分配结果,不直接改配送员 |
| 签收与现场证据 | 待契约确认 | `readonly` | 查看 App 形成的签收、扫码、照片和收款确认 |
- 匿名接口仅有登录;其余接口必须通过 JWT 和当前气站账号校验。
- 路由、资源模式、后端契约和前端页面必须同步。
- 状态流转、账号归属、用户唯一服务关系、金额和归档阻断全部由服务端校验。
- 密码、银行卡密文、证件密文等敏感字段不得返回前端。
- 手机号、地址、合同文件和定位等敏感信息按现有统一响应保护规则处理。
- 订单和提现创建必须使用业务幂等号;重复请求不得重复创建业务事实。
- 写操作及敏感访问应纳入统一审计能力。
后端依据有效合同、气瓶、库存和服务费规则读取或计算金额。取消、异常、恢复和完成必须通过专用动作并追加状态记录。
## 8. 验收标准
### 6.6 客户服务
| 资源 | 路径 | 模式 | 规划能力 |
| --- | --- | --- | --- |
| 本站客户视图 | 待契约确认 | `readonly` | 查看本站服务必需的脱敏联系人、地址和服务摘要 |
| 服务记录 | 待契约确认 | `append_only` | 记录预约、回访、通知和客户联系结果 |
| 售后与投诉 | 待契约确认 | `managed` | 受理本站售后、投诉并按状态流转 |
| 用户变更申请 | 待契约确认 | `append_only` | 提交资料纠错、关系解除或注销协办申请 |
气站不能创建或编辑全局用户、查看完整钱包、冻结登录、修改其他气站关系或解除设备安全限制
### 6.7 邀请注册
| 资源 | 路径 | 模式 | 规划能力 |
| --- | --- | --- | --- |
| 邀请二维码 | 待契约确认 | `managed` | 创建、预览、下载、启停和重新生成本站邀请 |
| 邀请使用记录 | 待契约确认 | `readonly` | 查询扫码、注册、关系建立和失败原因 |
| 邀请统计 | 待契约确认 | `readonly` | 聚合扫码、注册和服务关系转化 |
二维码只承载平台签名、可撤销且可过期的令牌或短链接。新用户完成平台统一注册;已有用户确认后只建立本站服务关系。重复扫码不得覆盖既有关系。
### 6.8 对账与提现申请
| 资源 | 路径 | 模式 | 规划能力 |
| --- | --- | --- | --- |
| 对账视图 | 待契约确认 | `readonly` | 查看本站订单、支付、服务费、库存交接和差异 |
| 对账异议 | 待契约确认 | `append_only` | 提交差异、凭证和处理意见 |
| 结算单 | 待契约确认 | `readonly` | 查看平台生成的本站结算结果 |
| 提现申请 | 待契约确认 | `append_only` | 在校验通过后提交申请并查看处理状态 |
气站不能创建资金流水、调整余额、审核提现、调整分账比例或确认实际打款。
## 7. 通用页面与接口行为
- 列表资源提供分页、字段筛选、状态展示、详情和受数据范围约束的关联选择。
- 关联字段提交业务 `identity`,后端解析为内部关联。
- 账户密码不在详情和列表返回明文。
- 响应使用统一封装;前端统一处理登录失效和稳定错误码。
- 写操作携带幂等键;异步操作返回可查询标识。
- 业务动作按当前状态展示,但后端仍必须拒绝非法流转。
- 现场证据、轨迹、支付、资金流水和安全事件仅查询,不开放通用修改或删除。
- 邀请、订单、库存、对账和敏感访问记录完整审计。
- 路由、资源模式、菜单、权限和前端页面必须通过契约检查保持一致。
## 9. 规划验收标准
1. 匿名用户只能访问登录和明确公开接口;所有业务资源要求有效认证。
2. 账户只能访问所属气站及已分配菜单,不能猜测路径访问其他气站数据。
3. 实际路由、资源契约、页面定义、菜单和本文资源模式一致。
4. 所有表保留自增 `id`;对外统一使用 UUID V7 `identity`
5. 气站不能创建全局用户、人员或配送点主体,不能授予安全角色。
6. 库存变化由业务流水驱动,余额不能直接编辑。
7. 配送点内部调度和 App 现场事实不能由气站后台代填或修改。
8. 燃气配送订单只能沿服务端状态机流转并追加过程记录。
9. 邀请只能在本站授权区域内生效,不能重复建用户或覆盖既有服务关系。
10. 气站只能提交对账异议和提现申请,不能修改资金或审核打款。
11. 首页与报表来自本站真实数据,不包含电商或其他气站数据。
12. 契约检查、权限测试、状态机测试、后端测试和前端构建全部通过。
1. 气站账号登录后由后端菜单数据渲染前端菜单,非 `admin` 角色无菜单。
2. 平台 JWT 不能作为气站 JWT 使用,气站 JWT 不能访问平台后台。
3. 所有业务资源只能访问当前气站数据。
4. 配送点管理、工作人员管理、用户管理、合同管理、订单、财务、工单和邀请功能可用。
5. 气站端无库存、调度、电商、生产设备和平台治理功能。
6. 气站端不暴露开始配送、等待签收、完成订单及提现审批动作。
7. 所有删除均为归档,并正确执行未完成业务阻断。
8. 每个用户只能归属一个气站和一个配送点。
9. 邀请二维码由配置 URL 和当前气站 identity 实时生成,不产生持久化记录。
10. 后端测试、路由权限测试、前端类型检查、契约检查和生产构建通过

View File

@@ -1,227 +1,225 @@
# 配送点管理系统需求(规划基线)
# 配送点管理系统需求
## 1. 文档目的
本文按照 `docs/05-平台总后台需求.md`章节、资源模式、权限和验收口径,定义配送点管理系统的规划基线
本文 `docs/05-平台总后台需求.md`资源、权限、状态机和验收口径为基线,定义配送点管理系统的实施范围
前端工作目录: `frontend/delivery_admin` 完全复制:`frontend/platform_admin`内所有文件在修改
后端工作目录:`backend/api` 与总平台复用一个API目录
后端API的URL前缀:/heqi/delivery/v1
后续实现事实按以下顺序核对并回写本文:
1. 配送点端实际 HTTP 路由。
2. 配送点端前后端资源契约。
3. 配送点端字段、关系、页面模式和业务动作定义。
4. 配送点端菜单、页面与隐藏子资源。
5. 配送点端状态机、事务、权限和数据范围校验。
- 前端:`frontend/delivery_admin`
- 后端:复用 `backend/api`,业务逻辑位于 `internal/logic/delivery`
- API 前缀:`/heqi/delivery/v1`
- 前端开发端口:`5176`
- 数据模型:复用现有 `backend/api/internal/models`,本期不新增角色、菜单、邀请、库存或质控表。
## 2. 系统定位与边界
配送点管理系统面向配送点负责人、调度员、仓管员和配送质控人员,负责本点当班能力、配送调度、配送仓、轨迹异常、交接质控、邀请注册和对账异议
配送点管理系统面向配送点管理员,负责当前配送点的人员、用户、合同、订单调度、财务和邀请注册。所有资源必须以后端 JWT 中的 `delivery_basic_identity` 为数据范围
当前规划不替代以下系统
本期包含
- 平台总后台:全局组织、用户与人员账号、角色资质、资金审核和安全规则仍由平台主责
- 气站管理系统:气站库存、燃气配送订单主责、跨配送点协调和气站结算仍由所属气站主责
- 生产管理系统:生产批次、出厂质检、设备身份和召回仍由生产系统主责
- 用户端与服务端 App用户注册确认、配送员接单、定位、扫码、签收和现场取证仍由对应 App 完成
- 电商平台:商品、分类、购物车、商城订单、评价和营销活动不属于配送点管理系统
- 本点运营概览及订单状态报表
- 配送点资料只读视图
- 本点配送人员、账号和资质管理
- 本点用户、地址和唯一服务关系管理
- 本点用户配送合同、合同气瓶和修订记录
- 创建配送订单、调整金额、分配、回收及本点改派。
- 订单异常、恢复和取消。
- 本点钱包、银行卡、支付、流水、退款、充值、提现和结算。
- 基于所属气站及当前配送点 identity 的邀请二维码。
配送点不能创建全局用户或人员账号,不能授予安全角色,不能创建交易订单、审核提现、修改资金流水、关闭安全事件或跨点调度。组织、人员、用户关系和跨点事项只能向所属气站或平台申请。
本期明确不包含:
独立 API 基础路径和鉴权请求头格式须在实现时通过契约确定;确定前不得沿用平台 API 路径冒充配送点端接口
- 库存、配送仓、库存流水、调拨和盘点
- 电商商品、购物车、商城订单、评价和营销。
- 营业设置、班次、组织变更申请、独立质控记录、服务记录、用户变更申请和对账异议。
- 平台治理、生产设备和客服工单。
- Web 后台补录配送、定位、扫码、签收、收款或现场证据。
## 3. 技术与数据约定
## 3. 配置、身份与鉴权
### 3.1 实现目录
### 3.1 全局配置
| 范围 | 规划目录 | 职责 |
| --- | --- | --- |
| 管理端 | `frontend/delivery_admin` | Vue 3、TypeScript、Vite、Pinia、Arco Design |
| 页面 | `frontend/delivery_admin/src/views` | 首页、报表及按业务域组织的资源页面 |
| 资源定义 | `frontend/delivery_admin/src/api` | 字段、关系、页面模式和业务动作 |
| 前端契约 | `frontend/delivery_admin/src/contracts` | 后端资源与路由生成清单 |
| 前端路由 | `frontend/delivery_admin/src/router` | 菜单、受控本地路由和隐藏详情资源 |
| 后端 API | `backend/api` | Gin HTTP API、JWT、事务和统一响应 |
| 路由 | `backend/api/internal/routers/delivery.go` | 平台 API 唯一路由注册入口 |
| 业务逻辑 | `backend/api/internal/logic/delivery` | 各领域查询、动作、权限和状态流转 |
| 模型 | `backend/api/internal/models` | 复用现在的,没特殊要求不可新增 |
气站端、配送点端和平台钱包共用:
以上目录均为规划归属,任务未明确要求前不得提前创建空壳工程。新管理端须复用 `sample/front` 的公共机制,新 Go 进程须遵循 `sample/server` 的分层。
```yaml
Global:
UserRegisterURL: http://localhost:5174/register
ManualRechargeMaxAmount: 100000000
```
### 3.2 数据身份
充值上限单位为分。启动时必须校验注册地址为有效 HTTP/HTTPS URL充值上限大于零。
- 每一张表均使用 `id bigint` 自增主键Go 模型对应 `ID uint64`
- 主表及需要单独访问、跨系统引用或审计定位的明细表使用 UUID V7 `identity`
- `id` 仅用于数据库内部关联HTTP、前端、事件、审计和跨服务调用使用 `identity`
- 配送点数据范围至少校验 `delivery_basic_identity`、任务归属和订单/调拨关系。
- 通用状态与任务、库存、邀请、质控和对账等业务状态分离。
- 删除执行归档或受控删除;任务过程、库存流水、轨迹、证据、邀请使用和对账事实不得物理删除。
- 金额使用最小货币单位整数;配送点只能读取权威金额快照。
### 3.2 登录与会话
### 3.3 资源页面模式
- 配送点管理员账号由平台或所属气站创建。
- 仅启用、关联启用配送点且 `role_code = admin``delivery_account` 可以登录。
- JWT 客户端固定为 `delivery_admin`,与平台和气站管理端会话隔离。
- 菜单由后端 `delivery_menu` 接口按 `role_code` 返回,前端登录后据此渲染。
- 修改本人密码必须校验当前密码;新密码只要求不少于 6 位。
- 配送人员和用户账号新增或重置密码时同样只要求不少于 6 位。
- 不新增角色表或菜单表。
| 模式 | 能力 |
### 3.3 数据身份与归属
- HTTP、前端、日志和审计统一使用 `identity`,不暴露数据库自增 ID。
- 配送点只能访问 `delivery_basic_id` 为当前配送点的人员、用户关系、合同和订单。
- 当前配送点所属气站由后端解析,前端不能提交其他气站或配送点改变归属。
- 每个用户只能存在一条未归档服务关系,并固定归属一个气站和一个配送点。
- 所有删除均为归档;订单、合同修订、资金流水、轨迹、签收和支付事实不得物理删除。
## 4. 菜单与功能
### 4.1 数据概述
| 菜单 | 能力 |
| --- | --- |
| `writable` | 列表、详情、新增、编辑、状态调整和归档 |
| `editable` | 列表、详情、新增、编辑和状态调整,不提供归档 |
| `readonly` | 列表和详情;可通过显式业务动作处理,但无通用增删改 |
| `append_only` | 可创建事实记录,既有记录不通用编辑或删除 |
| `managed` | 可创建和编辑,但生命周期必须通过专用动作推进 |
| 运营概览 | 本点配送人员、用户、合同和订单数量 |
| 订单报表 | 本点订单状态分布 |
普通资源应复用共享资源页面。库存流水、轨迹、证据、邀请使用记录和对账事实使用只读或仅追加模式;任务状态不得通过通用 CRUD 直接修改
报表只使用当前配送点真实数据,不混入其他配送点或电商数据
## 4. 登录、账户与权限
### 4.2 配送点资料
### 4.1 登录与个人账户
- 查看当前配送点编码、名称、负责人、地址、所属气站和状态。
- 配送点不能在本系统修改组织主数据、归属气站或状态。
- 配送点后台账号由平台创建或关联,配送点系统不提供自助创建管理员账号。
- 停用、冻结、未关联本点或角色无效的账户不得登录。
- 登录成功返回 JWT、账户 `identity`、显示名称、角色编码、配送点 `identity` 和菜单编码。
- 已登录账户只能查看和修改本人的非敏感资料;角色、组织归属和数据范围不能自行修改。
- 修改密码必须校验当前密码,新密码不少于 6 位。
- 配送点系统不得初始化共享默认管理员密码;首次账号由平台受控创建。
### 4.3 配送人员管理
### 4.2 RBAC 与数据能力
- 配送点可创建、编辑、启停、重置密码和归档本点配送人员。
- 新建人员的 `role_code` 由服务端固定为 `delivery`
- 人员的气站及配送点归属由服务端固定为当前范围。
- 资质支持新增、编辑、启停和归档。
- 删除均为归档;存在未完成订单时禁止归档人员。
- 不允许创建安装、运维、仓管、调度员或质控角色账号。
- 配送点负责人、调度员、仓管员和配送质控人员使用独立菜单能力。
- 配送点负责人不自动拥有仓管、调度、质控、敏感导出和资金能力。
- 调度员只能选择已关联本点、角色有效、资质有效且在岗的配送员。
- 仓管员只能操作本点配送仓,不能修改任务、金额、资金、安全事件和人员权限。
- 质控人员只能查看和标记本点证据异常,不能修改原始证据或关闭平台安全事件。
- 邀请管理权限独立授予;邀请码只能绑定当前配送点和已授权服务区域。
- 精确轨迹回放、完整证据和敏感导出使用独立权限并记录用途。
- 配送员不使用 Web 后台,只通过服务端 App 处理本人任务。
- 前端菜单隐藏只负责展示,最终权限由服务端执行。
### 4.4 用户管理
## 5. 首页与报表
- 支持本点用户新增、编辑、启停、重置密码和归档。
- 创建用户时在同一事务内建立所属气站与当前配送点服务关系。
- 支持本点用户地址新增、编辑、启停和归档。
- 配送点不能将用户迁移到其他配送点或其他气站。
- 归档用户时同时归档地址及服务关系。
- 用户存在未完成订单、未关闭工单、钱包余额、可提现余额或待处理提现时禁止归档。
首页规划聚合以下本点指标:
### 4.5 合同管理
- 待接收、待分配、待接单、配送中、待确认、异常和已完成任务数量
- 当前在岗、可接单、任务占用和作业前置异常人员数量
- 配送仓可用、冻结、在途、待退回和盘点差异数量
- 超时、无定位、偏航、轨迹中断、拒收和货损数量
- 待质控任务、证据缺失、疑似冲突和退回补充数量
- 邀请二维码启用数、扫码数、注册数和服务关系建立数
- 当前周期配送服务费快照和对账差异数量。
- 最近 7 个自然日的任务数量、完成率和平均时效趋势;无数据日期补零。
- 配送点可完整管理当前配送点用户的配送合同
- 支持创建、草稿编辑、启用、续签和终止
- 支持绑定和受控解绑当前用户已有气瓶
- 合同修订记录只读
- 服务端强制合同所属气站和配送点为当前范围
- 不得查看或操作所属气站下其他配送点的合同
首页快捷入口按角色菜单过滤。报表只聚合本点真实任务、库存和质控事实,不展示其他配送点明细,不生成虚构数据,不提供电商报表。
### 4.6 配送订单与调度
## 6. 规划功能域
- 配送点可根据当前配送点生效合同创建订单。
- 服务端强制订单创建方为当前配送点。
- 商品金额依据合同气瓶单价由服务端计算。
- 配送点可分配、回收或在本点配送人员之间改派。
- 可选配送人员必须同时满足:
- 属于当前配送点及所属气站;
- 账号启用且未归档;
- `role_code = delivery`
- `work_status = on_duty`
- 至少有一条启用且未过期的资质。
- 不支持跨配送点调度。
- 配送点后台可执行:创建、分配、回收、改派、调整金额、标记异常、恢复、取消。
- 配送点后台不得执行:开始罐装、罐装完成、开始配送、到达、等待签收、完成订单。
- App 产生的定位、扫码、照片、视频、签名、收款、签收和现场证据只读,后台不得补造或修改。
规划路径必须在独立配送点端契约中确认。下表的“路径”统一标记为待确认,不得直接复用平台资源路径。
### 4.7 订单金额调整
### 6.1 配送点经营设置
- 仅待处理或已分配订单允许调整。
- 存在成功支付记录后禁止调整。
- 只允许修改配送费和优惠金额。
- 商品金额保持合同计算结果。
- 应付金额由服务端重新计算:
| 资源 | 路径 | 模式 | 规划能力 |
| --- | --- | --- | --- |
| 配送点资料 | 待契约确认 | `readonly` | 查看平台维护的组织、地址、区域、归属气站和状态 |
| 营业设置 | 待契约确认 | `managed` | 维护营业时段、预约容量、值班联系和临时接单状态 |
| 组织变更申请 | 待契约确认 | `append_only` | 提交地址、区域、冻结、归档和迁移申请 |
```text
应付金额 = 商品金额 + 配送费 - 优惠金额
```
配送点不能直接修改组织主数据、覆盖区域或归属气站
- 配送费和优惠金额不得为负,应付金额必须大于零,并校验整数溢出
- 每次调整必须填写原因,记录调整操作人和不可变历史。
- 前端不得直接提交或覆盖商品金额和最终应付金额。
### 6.2 当班人员
### 4.8 财务管理
| 资源 | 路径 | 模式 | 规划能力 |
| --- | --- | --- | --- |
| 人员名册 | 待契约确认 | `readonly` | 查看平台已关联本点的人员 |
| 作业能力 | 待契约确认 | `readonly` | 查看角色、资质、培训、车辆、在岗和可接单结果 |
| 班次 | 待契约确认 | `managed` | 在已授权角色和区域内安排本点班次 |
| 人员变更申请 | 待契约确认 | `append_only` | 申请新增关联、角色变更、冻结、离职和跨点支援 |
- 本点钱包、银行卡、支付记录、钱包流水、退款和结算结果只读。
- 配送点可以创建提现申请,但不能审批、驳回或标记完成。
- 配送点管理员可以给当前配送点钱包自主充值。
- 充值必须填写幂等号、金额、原因和备注。
- 单笔充值金额必须大于零且不超过 `Global.ManualRechargeMaxAmount`
- 充值在数据库事务内增加钱包余额并创建不可变 `wallet_record`
- 自主充值不增加可提现余额,防止充值后直接提现。
- 充值流水记录配送点管理员 identity 和显示名称。
- 禁止给其他配送点充值,禁止修改或删除充值流水。
- 现有对账模型没有配送点归属字段,因此本期不展示平台全局对账记录,也不新增对账异议模型。
配送点不能创建人员账号、授予角色、修改资质和培训结论,也不能查看无关证件和银行卡数据。
### 4.9 邀请注册
### 6.3 配送任务调度
- 邀请二维码不持久化,不新增邀请表。
- 后端基于 `Global.UserRegisterURL` 实时生成:
| 资源 | 路径 | 模式 | 规划能力 |
| --- | --- | --- | --- |
| 配送任务 | 待契约确认 | `managed` | 接收气站需求并执行本点职责范围内的状态动作 |
| 分配记录 | 待契约确认 | `append_only` | 记录分配、回收和本点改派 |
| 订单摘要 | 待契约确认 | `readonly` | 查看履约必需的订单、预约和金额快照 |
| 异常协调申请 | 待契约确认 | `append_only` | 提交跨点、超区域和高风险任务协调 |
```text
register?gas_identity={所属气站identity}&delivery_identity={当前配送点identity}
```
配送点不能创建交易订单、修改最终金额或跳过任务状态机。跨点改派只能由气站或平台协调
- 前端生成二维码并支持下载 PNG
- 不提供启停、过期、扫码记录和邀请统计。
- 二维码不得携带数据库 ID、密码或 JWT。
### 6.4 配送仓
## 5. 资源页面模式
| 资源 | 路径 | 模式 | 规划能力 |
| --- | --- | --- | --- |
| 库存余额 | 待契约确认 | `readonly` | 查询本点可用、冻结、在途和待退回数量 |
| 库存流水 | 待契约确认 | `append_only` | 记录接收、入库、拣货、出库、退回和损耗 |
| 调拨接收 | 待契约确认 | `managed` | 核对所属气站调拨并确认差异 |
| 盘点单 | 待契约确认 | `managed` | 创建盘点、记录实盘和差异,按阈值复核 |
| 资源 | 模式 | 说明 |
| --- | --- | --- |
| `delivery_profile` | `readonly` | 当前配送点资料 |
| `staff_account``staff_credential` | `writable` | 仅配送角色,删除为归档 |
| `user_account``user_address` | `writable` | 服务关系由服务端事务维护 |
| `gasorder_contract` | `managed` | 生命周期使用专用动作 |
| `gasorder_contract_product` | `append_only` | 解绑使用专用动作 |
| `gasorder_contract_revision``product_info` | `readonly` | 合同历史及可选气瓶 |
| `gasorder_basic` | `append_only` | 创建及专用调度/状态动作 |
| `wallet_basic``wallet_bank``wallet_payment``wallet_record``wallet_refund` | `readonly` | 当前配送点钱包范围 |
| `wallet_recharge``wallet_apply_cash` | `append_only` | 充值及提现申请 |
| `fin_settlement` | `readonly` | 当前配送点结算结果 |
库存余额不能直接编辑。无有效任务不得出库,跨气站调拨不能由配送点创建。
## 6. 菜单输出
### 6.5 履约与轨迹质控
菜单定义位于 `backend/api/internal/logic/delivery/menu.go`,仅 `admin` 返回:
| 资源 | 路径 | 模式 | 规划能力 |
| --- | --- | --- | --- |
| 轨迹 | 待契约确认 | `readonly` | 查看本点任务状态时间线和授权范围内轨迹 |
| 现场证据 | 待契约确认 | `readonly` | 查看扫码、照片、视频、签名、收款确认和空瓶回收 |
| 质控记录 | 待契约确认 | `append_only` | 标记材料缺失、数据冲突、疑似造假和复核结果 |
| 轨迹异常 | 待契约确认 | `managed` | 处理无定位、偏航、异常速度和轨迹中断提醒 |
1. 数据概述:运营概览、订单报表。
2. 配送点资料:本点资料。
3. 配送人员管理:新增配送人员、配送人员列表;资质为隐藏子资源。
4. 用户管理:用户账户;地址和服务关系为隐藏子资源。
5. 合同管理:配送合同;合同气瓶、修订记录、可选气瓶为隐藏子资源。
6. 配送订单:创建订单、订单列表;分配、状态、轨迹、签收、支付记录为隐藏只读子资源。
7. 财务管理:钱包、银行卡、支付记录、钱包流水、退款记录、钱包充值、提现申请、结算结果。
8. 邀请注册:邀请二维码。
后台不能补造或修改 App 产生的到达、定位、扫码、签收和收款事实。旧任务轨迹在改派后只读保留
菜单中不得出现库存、配送仓、电商、平台治理、生产设备、客服工单或独立质控模块
### 6.6 用户履约视图
## 7. 接口与安全要求
| 资源 | 路径 | 模式 | 规划能力 |
| --- | --- | --- | --- |
| 用户履约摘要 | 待契约确认 | `readonly` | 查看当前任务所需的脱敏联系人、地址和交接要求 |
| 服务记录 | 待契约确认 | `append_only` | 记录本点预约、联系、配送异常和回访 |
| 用户变更申请 | 待契约确认 | `append_only` | 提交资料纠错和服务关系变更申请 |
- 匿名接口仅允许登录,其余接口必须验证 JWT、客户端、角色、账号状态和当前配送点。
- 路由、菜单、资源模式、后端契约和前端页面必须同步。
- 状态流转、金额、归属、调度资质、用户唯一服务关系和归档阻断均由服务端校验。
- 密码、银行卡密文和证件密文不得返回前端。
- 手机号、地址、定位、合同文件及现场证据遵循统一敏感数据保护规则。
- 订单创建、金额调整、分配、回收、改派、充值和提现必须记录操作人及原因。
- 充值、订单创建和提现使用幂等号,重复请求不得重复生成业务事实。
- 前端菜单隐藏和按钮禁用不构成权限控制。
配送点不能创建或编辑全局用户、查看完整钱包、冻结账号、注销用户或直接改变服务关系。
## 8. 验收标准
### 6.7 邀请注册
| 资源 | 路径 | 模式 | 规划能力 |
| --- | --- | --- | --- |
| 邀请二维码 | 待契约确认 | `managed` | 创建、预览、下载、启停和重新生成本点邀请 |
| 邀请使用记录 | 待契约确认 | `readonly` | 查询扫码、注册、关系建立和失败原因 |
| 邀请统计 | 待契约确认 | `readonly` | 聚合扫码、注册和服务关系转化 |
二维码只承载平台签名、可撤销且可过期的令牌或短链接。新用户完成平台统一注册;已有用户确认后只建立本点服务关系。重复扫码不得覆盖既有关系
### 6.8 对账视图
| 资源 | 路径 | 模式 | 规划能力 |
| --- | --- | --- | --- |
| 任务对账 | 待契约确认 | `readonly` | 查看任务金额、配送服务费、库存交接和异常差异 |
| 对账异议 | 待契约确认 | `append_only` | 提交签收、货损、拒收、收款或库存差异 |
| 结算结果 | 待契约确认 | `readonly` | 查看气站或平台生成的处理结果 |
配送点不能创建资金流水、调整余额、审核提现、修改分账比例或确认打款。
## 7. 通用页面与接口行为
- 列表资源提供分页、字段筛选、状态展示、详情和受数据范围约束的关联选择。
- 关联字段提交业务 `identity`,后端解析为内部关联。
- 账户密码不在详情和列表返回明文。
- 响应使用统一封装;前端统一处理登录失效和稳定错误码。
- 写操作携带幂等键;异步操作返回可查询标识。
- 业务动作按当前状态展示,但后端仍必须拒绝非法流转。
- 轨迹、现场证据、支付、资金流水和安全事件仅查询,不开放通用修改或删除。
- 邀请、派单、改派、库存、质控、对账和敏感访问记录完整审计。
- 路由、资源模式、菜单、权限和前端页面必须通过契约检查保持一致。
## 9. 规划验收标准
1. 匿名用户只能访问登录和明确公开接口;所有业务资源要求有效认证。
2. 账户只能访问所属配送点及已分配菜单,不能猜测路径访问其他配送点数据。
3. 实际路由、资源契约、页面定义、菜单和本文资源模式一致。
4. 所有表保留自增 `id`;对外统一使用 UUID V7 `identity`
5. 配送点不能创建全局用户或人员账号,不能授予安全角色。
6. 调度只能选择已关联本点、角色与资质有效且在岗的配送员。
7. 配送仓库存变化由调拨、任务和交接流水驱动,余额不能直接编辑。
8. 后台不能补造或修改定位、扫码、照片、视频、签名、收款和签收事实。
9. 邀请只能在本点授权区域内生效,不能重复建用户或覆盖既有服务关系。
10. 配送点只能提交对账异议,不能修改资金、分账或提现状态。
11. 首页与报表来自本点真实数据,不包含电商或其他配送点数据。
12. 契约检查、权限测试、状态机测试、后端测试和前端构建全部通过。
1. 配送点管理员登录后由后端菜单渲染前端,非 `admin` 角色无菜单。
2. 平台、气站和配送点 JWT 互相隔离。
3. 所有业务资源只能访问当前配送点数据。
4. 配送人员、用户、合同、订单调度、财务和邀请功能可用。
5. 系统中没有库存、配送仓、电商和无模型支撑的规划功能。
6. 调度严格校验本点归属、配送角色、在岗状态和有效资质。
7. 金额调整只影响配送费和优惠金额,成功支付后不可调整。
8. Web 后台不暴露罐装、开始配送、到达、签收或完成订单动作。
9. 自主充值只增加余额、不增加可提现余额,并产生不可变资金流水
10. 用户、人员等删除均为归档,并正确执行未完成业务阻断。
11. 邀请二维码实时生成且不持久化。
12. 后端测试、权限路由测试、契约检查、前端类型检查和生产构建全部通过。