docs: align gas and delivery requirements

This commit is contained in:
david
2026-07-30 10:38:18 +08:00
parent 268c8d062c
commit 2e6df1d18d
2 changed files with 333 additions and 283 deletions

View File

@@ -2,182 +2,223 @@
## 1. 文档目的
本文定义配送点管理系统的业务范围、角色权限、数据边界、核心流程和验收口径,作为后续 `frontend/delivery_admin` 及对应后端能力的规划基线。
本文按照 `docs/05-平台总后台需求.md` 的章节、资源模式、权限和验收口径,定义配送点管理系统的规划基线。
当前仓库尚未实现配送点管理系统,本文描述的能力不得认定为已交付,不得为了复用页面而塞入平台总后台。后续落地时应以实际路由、资源契约、权限和测试反向更新本文
当前仓库尚未创建 `frontend/delivery_admin`,也没有配送点管理系统独立后端、资源契约和实际路由。本文描述的是待实现能力不得认定为已交付,不得为了完成本文而在平台总后台中增加配送点日常操作
后续实现事实按以下顺序核对并回写本文:
1. 配送点端实际 HTTP 路由。
2. 配送点端前后端资源契约。
3. 配送点端字段、关系、页面模式和业务动作定义。
4. 配送点端菜单、页面与隐藏子资源。
5. 配送点端状态机、事务、权限和数据范围校验。
## 2. 系统定位与边界
配送点管理系统是气站下属配送组织的日常履约工作台,面向配送点负责人、调度员、仓管员和配送质控人员,责本点配送任务、配送仓库存、人员当班能力、轨迹异常交接质控。
配送点管理系统面向配送点负责人、调度员、仓管员和配送质控人员,责本点当班能力、配送调度、配送仓、轨迹异常交接质控、邀请注册和对账异议
配送点管理系统不承担以下主责
当前规划不替代以下系统
- 不创建、审核或注销平台全局用户账户
- 不创建服务人员全局账号,不授予安装维修、安检等安全角色,不审批实名、资质或培训结论
- 不维护电商商品、分类、购物车、商城订单、评价或营销活动
- 不维护合同条款、平台安全规则或设备控制策略
- 不审核提现、修改资金流水、计算平台分账或确认实际打款
- 不管理生产型号、生产批次、出厂质检、设备证书或固件发布。
- 不查看其他配送点、其他气站或与本点履约无关的用户和人员数据。
- 平台总后台:全局组织、用户与人员账号、角色资质、资金审核和安全规则仍由平台主责
- 气站管理系统:气站库存、燃气配送订单主责、跨配送点协调和气站结算仍由所属气站主责
- 生产管理系统:生产批次、出厂质检、设备身份和召回仍由生产系统主责
- 用户端与服务端 App用户注册确认、配送员接单、定位、扫码、签收和现场取证仍由对应 App 完成
- 电商平台:商品、分类、购物车、商城订单、评价和营销活动不属于配送点管理系统
配送点需要新增人员、变更人员角色、调整覆盖区域、解除用户服务关系或执行跨点调拨时,只能向所属气站或平台发起申请,不得在本系统直接生效
配送点不能创建全局用户或人员账号,不能授予安全角色,不能创建交易订单、审核提现、修改资金流水、关闭安全事件或跨点调度。组织、人员、用户关系和跨点事项只能向所属气站或平台申请
## 3. 角色与权限
独立 API 基础路径和鉴权请求头格式须在实现时通过契约确定;确定前不得沿用平台 API 路径冒充配送点端接口。
### 3.1 角色职责
## 3. 技术与数据约定
| 角色 | 可用能力 | 明确禁止 |
### 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 | 待技术设计确认 | 配送点同步业务事务、鉴权和统一响应 |
| 业务逻辑 | 待技术设计确认 | 本点调度、配送仓、质控、邀请和对账规则 |
| 模型 | 待技术设计确认 | 配送点主责事实模型与中文注释 |
| 初始化 | 待技术设计确认 | 系统必需角色与菜单,不包含演示数据 |
配送员不使用 Web 配送点后台,其接单、定位、扫码、随瓶安检、签收和现场取证均在服务端 App 完成,只能访问分配给本人的任务
以上目录均为规划归属,任务未明确要求前不得提前创建空壳工程。新管理端须复用 `sample/front` 的公共机制,新 Go 进程须遵循 `sample/server` 的分层
### 3.2 权限规则
### 3.2 数据身份
- 权限必须由服务端同时校验角色、配送点归属、任务归属和数据状态
- 配送点负责人不能自动获得仓管、调度或质控的全部操作能力;角色可组合,但每项能力独立授权
- 高风险改派、跨点支援、库存报损、精确轨迹回放和敏感数据导出需要上级授权或审批
- 前端菜单隐藏和按钮禁用不构成权限控制
- 每一张表均使用 `id bigint` 自增主键Go 模型对应 `ID uint64`
- 主表及需要单独访问、跨系统引用或审计定位的明细表使用 UUID V7 `identity`
- `id` 仅用于数据库内部关联HTTP、前端、事件、审计和跨服务调用使用 `identity`
- 配送点数据范围至少校验 `delivery_basic_identity`、任务归属和订单/调拨关系
- 通用状态与任务、库存、邀请、质控和对账等业务状态分离。
- 删除执行归档或受控删除;任务过程、库存流水、轨迹、证据、邀请使用和对账事实不得物理删除。
- 金额使用最小货币单位整数;配送点只能读取权威金额快照。
## 4. 技术与数据约定
### 3.3 资源页面模式
- 每张表包含 `id bigint` 自增主键、`created_at``updated_at`
- 主表及需要被接口单独访问的明细表包含 UUID V7 `identity`
- HTTP、事件、审计和前端只使用 `identity`;不得暴露数据库内部 ID。
- 金额使用最小货币单位整数。配送点只能读取订单和结算快照,不得自行重算最终应收、人员收益或平台分账。
- 订单、任务、库存流水、轨迹、签收证据和质控结论不得物理删除。
- 现场证据由服务端 App 产生,后台只能查看、标记异常或提交复核,不得代替现场人员补录为已完成。
## 5. 规划功能域
### 5.1 配送点资料
配送点仅查看平台或气站维护的组织编码、所属气站、地址、覆盖区域、联系人、营业状态和能力上限。
本点负责人可维护营业时段、值班联系方式、预约容量和临时接单状态。地址、覆盖区域、主体归属、组织冻结和归档等主数据变更必须发起申请,由所属气站或平台审核生效。
### 5.2 当班人员与能力
| 能力 | 规则 |
| 模式 | 能力 |
| --- | --- |
| 人员名册 | 只显示已由气站或平台关联至本点的人员,不提供创建账号、删除账号或授予角色功能 |
| 当班状态 | 查看上/下班、可接单、当前负载、定位可用性和任务占用情况 |
| 班次安排 | 在人员已授权角色、有效资质和服务区域内安排本点班次 |
| 作业前置 | 只读展示培训、资质、车辆、工具和授权设备校验结果;不允许配送点人员自行改为“已通过” |
| 组织变更 | 离职、冻结、角色变更、跨点支援和调动只能发起申请,由气站或平台处理 |
| `writable` | 列表、详情、新增、编辑、状态调整和归档 |
| `editable` | 列表、详情、新增、编辑和状态调整,不提供归档 |
| `readonly` | 列表和详情;可通过显式业务动作处理,但无通用增删改 |
| `append_only` | 可创建事实记录,既有记录不通用编辑或删除 |
| `managed` | 可创建和编辑,但生命周期必须通过专用动作推进 |
配送点不能查看人员完整身份证件、银行卡、平台级违规档案或与本点任务无关的个人信息
普通资源应复用共享资源页面。库存流水、轨迹、证据、邀请使用记录和对账事实使用只读或仅追加模式;任务状态不得通过通用 CRUD 直接修改
### 5.3 配送任务调度
## 4. 登录、账户与权限
- 接收所属气站或平台下发至本点的待配送任务。
- 按覆盖区域、预约窗口、人员当班状态、配送角色、车辆能力、当前负载、库存和风险限制进行分配。
- 普通改派仅限本点已授权且在岗人员,必须填写原因并保留原分配记录。
- 跨点改派、超区域履约和高风险任务转移只能发起上级协调申请。
- 配送点不得创建交易订单、改写订单最终金额或跳过订单状态机。
- 配送任务状态以服务端校验和 App 履约事实为准,后台不能直接把任务改为已到达、已签收或已完成。
### 4.1 登录与个人账户
### 5.4 配送仓
- 配送点后台账号由平台创建或关联,配送点系统不提供自助创建管理员账号。
- 停用、冻结、未关联本点或角色无效的账户不得登录。
- 登录成功返回 JWT、账户 `identity`、显示名称、角色编码、配送点 `identity` 和菜单编码。
- 已登录账户只能查看和修改本人的非敏感资料;角色、组织归属和数据范围不能自行修改。
- 修改密码必须校验当前密码,新密码不少于 6 位。
- 配送点系统不得初始化共享默认管理员密码;首次账号由平台受控创建。
| 资源 | 能力 | 关键规则 |
| --- | --- | --- |
| 调拨接收 | 核对所属气站发出的调拨单并确认收货差异 | 不得自行创建跨气站调拨 |
| 入库与批次 | 记录实收数量、批次、扫码结果和异常 | 来源批次只读,不得修改生产事实 |
| 拣货与出库 | 按已分配配送任务拣货、复核和交接 | 无有效任务不得出库 |
| 在途与退回 | 跟踪配送员交接、拒收、空瓶和货损退回 | 在途记录不可覆盖或删除 |
| 盘点与损耗 | 创建盘点、登记差异和损耗原因 | 超阈值差异需负责人及所属气站复核 |
### 4.2 RBAC 与数据能力
库存扣减、回流和冻结必须由订单、任务和交接事实驱动,不能由页面任意修改库存余额
- 配送点负责人、调度员、仓管员和配送质控人员使用独立菜单能力
- 配送点负责人不自动拥有仓管、调度、质控、敏感导出和资金能力。
- 调度员只能选择已关联本点、角色有效、资质有效且在岗的配送员。
- 仓管员只能操作本点配送仓,不能修改任务、金额、资金、安全事件和人员权限。
- 质控人员只能查看和标记本点证据异常,不能修改原始证据或关闭平台安全事件。
- 邀请管理权限独立授予;邀请码只能绑定当前配送点和已授权服务区域。
- 精确轨迹回放、完整证据和敏感导出使用独立权限并记录用途。
- 配送员不使用 Web 后台,只通过服务端 App 处理本人任务。
- 前端菜单隐藏只负责展示,最终权限由服务端执行。
### 5.5 履约与轨迹质控
## 5. 首页与报表
- 查看本点任务的分配、接单、出发、位置上报、到达、签收、异常、改派和取消时间线。
- 识别长时间无位置、偏离授权区域、异常速度、轨迹中断和签收前未到达等异常。
- 查看气瓶/设备扫码、随瓶安检、照片/视频、用户签名或签收码、收款确认和空瓶回收完成情况。
- 质控人员可标记材料缺失、数据冲突或疑似造假,并退回任务补充合法证据或上报气站/平台。
- 改派后旧任务轨迹只读保留,新任务单独采集,不覆盖原责任人和时间线。
- 精确坐标、完整回放和导出按最小权限控制并记录用途;普通仓管和无关人员不得访问。
首页规划聚合以下本点指标:
### 5.6 用户履约视图
- 待接收、待分配、待接单、配送中、待确认、异常和已完成任务数量。
- 当前在岗、可接单、任务占用和作业前置异常人员数量。
- 配送仓可用、冻结、在途、待退回和盘点差异数量。
- 超时、无定位、偏航、轨迹中断、拒收和货损数量。
- 待质控任务、证据缺失、疑似冲突和退回补充数量。
- 邀请二维码启用数、扫码数、注册数和服务关系建立数。
- 当前周期配送服务费快照和对账差异数量。
- 最近 7 个自然日的任务数量、完成率和平均时效趋势;无数据日期补零。
配送点只读取完成本点任务所必需的用户信息:
首页快捷入口按角色菜单过滤。报表只聚合本点真实任务、库存和质控事实,不展示其他配送点明细,不生成虚构数据,不提供电商报表。
- 当前任务联系人、脱敏手机号、配送地址、预约时段和交接要求。
- 与本点任务相关的订单、售后、投诉和配送偏好。
- 会影响本次履约的设备或安全限制摘要。
## 6. 规划功能域
配送点不得创建或编辑用户全局账户、查看完整钱包和支付流水、修改用户地址主档、冻结账号、注销用户或直接变更服务关系。发现资料错误时只能提交纠错或关系变更申请
规划路径必须在独立配送点端契约中确认。下表的“路径”统一标记为待确认,不得直接复用平台资源路径
### 5.7 邀请注册
### 6.1 配送点经营设置
配送点可在平台和所属气站授权的服务区域内创建和管理本点邀请注册二维码,用于社区服务、自提点和线下客户注册。
| 资源 | 路径 | 模式 | 规划能力 |
| --- | --- | --- | --- |
| 配送点资料 | 待契约确认 | `readonly` | 查看平台维护的组织、地址、区域、归属气站和状态 |
| 营业设置 | 待契约确认 | `managed` | 维护营业时段、预约容量、值班联系和临时接单状态 |
| 组织变更申请 | 待契约确认 | `append_only` | 提交地址、区域、冻结、归档和迁移申请 |
| 能力 | 规则 |
| --- | --- |
| 创建邀请 | 配置本配送点、所属气站、服务区域、有效期、使用次数和邀请来源 |
| 二维码操作 | 生成、预览、下载、复制注册链接、停用和重新生成 |
| 注册处理 | 新用户完成平台统一注册;已有用户登录确认后只建立本点服务关系 |
| 范围校验 | 地址不在本点配送范围时不得建立错误归属 |
| 统计 | 查看扫码、注册、服务关系建立和失败原因,不展示无关用户隐私 |
配送点不能直接修改组织主数据、覆盖区域或归属气站。
二维码只承载平台签名、可撤销且可过期的邀请码或短链接,不包含配送点账号、用户资料、库存或接口密钥。重复扫码不得覆盖既有服务关系;已有关系变更必须提示影响并取得用户确认。
### 6.2 当班人员
### 5.8 对账视图
| 资源 | 路径 | 模式 | 规划能力 |
| --- | --- | --- | --- |
| 人员名册 | 待契约确认 | `readonly` | 查看平台已关联本点的人员 |
| 作业能力 | 待契约确认 | `readonly` | 查看角色、资质、培训、车辆、在岗和可接单结果 |
| 班次 | 待契约确认 | `managed` | 在已授权角色和区域内安排本点班次 |
| 人员变更申请 | 待契约确认 | `append_only` | 申请新增关联、角色变更、冻结、离职和跨点支援 |
- 按本点任务查看订单金额快照、配送服务费快照、库存交接和异常差异
- 对缺少签收、货损、拒收、收款不一致或库存不平的任务提交对账异议。
- 查看所属气站或平台生成的结算结果及异议处理状态。
配送点不能创建人员账号、授予角色、修改资质和培训结论,也不能查看无关证件和银行卡数据
配送点不得创建资金流水、调整余额、审核提现、确认打款或修改分账比例。
### 6.3 配送任务调度
## 6. 核心流程
| 资源 | 路径 | 模式 | 规划能力 |
| --- | --- | --- | --- |
| 配送任务 | 待契约确认 | `managed` | 接收气站需求并执行本点职责范围内的状态动作 |
| 分配记录 | 待契约确认 | `append_only` | 记录分配、回收和本点改派 |
| 订单摘要 | 待契约确认 | `readonly` | 查看履约必需的订单、预约和金额快照 |
| 异常协调申请 | 待契约确认 | `append_only` | 提交跨点、超区域和高风险任务协调 |
### 6.1 调度与履约
配送点不能创建交易订单、修改最终金额或跳过任务状态机。跨点改派只能由气站或平台协调。
```text
接收配送需求 -> 校验本点范围和库存 -> 选择已授权当班配送员
-> 分配任务 -> App 接单与履约 -> 签收/异常 -> 质控检查 -> 回传气站
```
### 6.4 配送仓
- 校验失败时进入待协调,不得通过手工改状态绕过。
- 配送员未接单、定位异常或超时,可在本点范围内回收并改派。
- 现场不合格或触发安全规则时必须上报安全事件,配送点不能自行解除设备或订单限制。
| 资源 | 路径 | 模式 | 规划能力 |
| --- | --- | --- | --- |
| 库存余额 | 待契约确认 | `readonly` | 查询本点可用、冻结、在途和待退回数量 |
| 库存流水 | 待契约确认 | `append_only` | 记录接收、入库、拣货、出库、退回和损耗 |
| 调拨接收 | 待契约确认 | `managed` | 核对所属气站调拨并确认差异 |
| 盘点单 | 待契约确认 | `managed` | 创建盘点、记录实盘和差异,按阈值复核 |
### 6.2 库存交接
库存余额不能直接编辑。无有效任务不得出库,跨气站调拨不能由配送点创建。
```text
气站调拨出库 -> 配送点核对接收 -> 任务拣货 -> 配送员交接
-> 签收扣减 / 拒收退回 / 货损冻结 -> 盘点与对账
```
### 6.5 履约与轨迹质控
每次交接均保留操作者、时间、任务、批次、数量、来源、去向和差异原因。
| 资源 | 路径 | 模式 | 规划能力 |
| --- | --- | --- | --- |
| 轨迹 | 待契约确认 | `readonly` | 查看本点任务状态时间线和授权范围内轨迹 |
| 现场证据 | 待契约确认 | `readonly` | 查看扫码、照片、视频、签名、收款确认和空瓶回收 |
| 质控记录 | 待契约确认 | `append_only` | 标记材料缺失、数据冲突、疑似造假和复核结果 |
| 轨迹异常 | 待契约确认 | `managed` | 处理无定位、偏航、异常速度和轨迹中断提醒 |
## 7. 审计与安全
后台不能补造或修改 App 产生的到达、定位、扫码、签收和收款事实。旧任务轨迹在改派后只读保留。
- 邀请创建与停用、派单、改派、班次调整、库存交接、盘点差异、质控结论、敏感查看和导出必须审计。
- 手机号、地址、定位、照片、视频和签名按最小权限脱敏或受控访问。
- 离线补传保留原始采集时间、服务端接收时间、操作者、任务、来源、完整性标记和幂等键。
- 任何配送点角色都不能修改原始轨迹、签名、支付、资金流水、安全事件或设备命令事实。
- 数据范围至少同时包含 `delivery_basic_identity` 和任务归属校验,禁止仅依靠前端筛选。
### 6.6 用户履约视图
## 8. 未实现范围
| 资源 | 路径 | 模式 | 规划能力 |
| --- | --- | --- | --- |
| 用户履约摘要 | 待契约确认 | `readonly` | 查看当前任务所需的脱敏联系人、地址和交接要求 |
| 服务记录 | 待契约确认 | `append_only` | 记录本点预约、联系、配送异常和回访 |
| 用户变更申请 | 待契约确认 | `append_only` | 提交资料纠错和服务关系变更申请 |
当前仓库不存在 `frontend/delivery_admin` 及其独立业务实现。配送点后台、配送仓、调度、质控和本点对账均属于规划能力
配送点不能创建或编辑全局用户、查看完整钱包、冻结账号、注销用户或直接改变服务关系
电商、全局用户管理、人员账号与资质审批、跨点调配、平台资金审核、全局安全规则和生产追溯不属于配送点后台建设范围。
### 6.7 邀请注册
| 资源 | 路径 | 模式 | 规划能力 |
| --- | --- | --- | --- |
| 邀请二维码 | 待契约确认 | `managed` | 创建、预览、下载、启停和重新生成本点邀请 |
| 邀请使用记录 | 待契约确认 | `readonly` | 查询扫码、注册、关系建立和失败原因 |
| 邀请统计 | 待契约确认 | `readonly` | 聚合扫码、注册和服务关系转化 |
二维码只承载平台签名、可撤销且可过期的令牌或短链接。新用户完成平台统一注册;已有用户确认后只建立本点服务关系。重复扫码不得覆盖既有关系。
### 6.8 对账视图
| 资源 | 路径 | 模式 | 规划能力 |
| --- | --- | --- | --- |
| 任务对账 | 待契约确认 | `readonly` | 查看任务金额、配送服务费、库存交接和异常差异 |
| 对账异议 | 待契约确认 | `append_only` | 提交签收、货损、拒收、收款或库存差异 |
| 结算结果 | 待契约确认 | `readonly` | 查看气站或平台生成的处理结果 |
配送点不能创建资金流水、调整余额、审核提现、修改分账比例或确认打款。
## 7. 通用页面与接口行为
- 列表资源提供分页、字段筛选、状态展示、详情和受数据范围约束的关联选择。
- 关联字段提交业务 `identity`,后端解析为内部关联。
- 账户密码不在详情和列表返回明文。
- 响应使用统一封装;前端统一处理登录失效和稳定错误码。
- 写操作携带幂等键;异步操作返回可查询标识。
- 业务动作按当前状态展示,但后端仍必须拒绝非法流转。
- 轨迹、现场证据、支付、资金流水和安全事件仅查询,不开放通用修改或删除。
- 邀请、派单、改派、库存、质控、对账和敏感访问记录完整审计。
- 路由、资源模式、菜单、权限和前端页面必须通过契约检查保持一致。
## 9. 规划验收标准
1. 所有页面和接口只返回当前配送点及其任务范围内的数据
2. 配送点不能创建全局人员或用户账号,不能授予安全角色或修改资质结论
3. 配送点邀请二维码只能在授权范围内生效,不能重复创建用户或覆盖既有服务关系
4. 调度只能选择已关联本点、角色有效、资质有效且在岗的配送员
5. 后台不能补造到达、签收、定位、照片、视频、扫码和收款事实
6. 跨点改派、跨区域履约和组织主数据变更必须走上级申请
7. 库存变化由调拨、任务和交接流水驱动,余额不直接编辑。
8. 配送点只能提出对账异议,不能修改资金流水、分账或提现状态
9. 敏感字段、精确轨迹和导出按权限控制并完整审计
10. 状态机、数据范围、幂等和越权场景具有服务端测试
1. 匿名用户只能访问登录和明确公开接口;所有业务资源要求有效认证
2. 账户只能访问所属配送点及已分配菜单,不能猜测路径访问其他配送点数据
3. 实际路由、资源契约、页面定义、菜单和本文资源模式一致
4. 所有表保留自增 `id`;对外统一使用 UUID V7 `identity`
5. 配送点不能创建全局用户或人员账号,不能授予安全角色
6. 调度只能选择已关联本点、角色与资质有效且在岗的配送员
7. 配送仓库存变化由调拨、任务和交接流水驱动,余额不直接编辑。
8. 后台不能补造或修改定位、扫码、照片、视频、签名、收款和签收事实
9. 邀请只能在本点授权区域内生效,不能重复建用户或覆盖既有服务关系
10. 配送点只能提交对账异议,不能修改资金、分账或提现状态
11. 首页与报表来自本点真实数据,不包含电商或其他配送点数据。
12. 契约检查、权限测试、状态机测试、后端测试和前端构建全部通过。