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