platforms/docs/07-配送点管理系统需求.md

配送点管理系统需求（规划基线）

1. 文档目的

本文定义配送点管理系统的业务范围、角色权限、数据边界、核心流程和验收口径，作为后续 frontend/delivery_admin 及对应后端能力的规划基线。

当前仓库尚未实现配送点管理系统，本文描述的能力不得认定为已交付，也不得为了复用页面而塞入平台总后台。后续落地时应以实际路由、资源契约、权限和测试反向更新本文。

2. 系统定位与边界

配送点管理系统是气站下属配送组织的日常履约工作台，面向配送点负责人、调度员、仓管员和配送质控人员，主责本点配送任务、配送仓库存、人员当班能力、轨迹异常和交接质控。

配送点管理系统不承担以下主责：

• 不创建、审核或注销平台全局用户账户。
• 不创建服务人员全局账号，不授予安装维修、安检等安全角色，不审批实名、资质或培训结论。
• 不维护电商商品、分类、购物车、商城订单、评价或营销活动。
• 不维护合同条款、平台安全规则或设备控制策略。
• 不审核提现、修改资金流水、计算平台分账或确认实际打款。
• 不管理生产型号、生产批次、出厂质检、设备证书或固件发布。
• 不查看其他配送点、其他气站或与本点履约无关的用户和人员数据。

配送点需要新增人员、变更人员角色、调整覆盖区域、解除用户服务关系或执行跨点调拨时，只能向所属气站或平台发起申请，不得在本系统直接生效。

3. 角色与权限

3.1 角色职责

角色	可用能力	明确禁止
配送点负责人	查看本点运营概览、安排本点班次、管理本点邀请、审批本点普通改派和库存盘点差异、发起组织变更申请	创建平台账号、授予安全角色、跨点调度、资金审核、修改安全规则
调度员	查看本点可调度人员、分配与改派配送任务、处理时效和轨迹异常	修改人员身份/资质、补造现场证据、修改订单金额、调度其他配送点人员
仓管员	执行本点调拨接收、入库、拣货、出库、退回、盘点和损耗登记	修改订单状态、质检结论、资金数据或其他仓库存
配送质控人员	查看本点签收、拒收、货损、随瓶安检和轨迹质量，提交复核结论	修改原始照片、视频、签名、定位或收款事实，直接关闭平台安全事件

配送员不使用 Web 配送点后台，其接单、定位、扫码、随瓶安检、签收和现场取证均在服务端 App 完成，只能访问分配给本人的任务。

3.2 权限规则

• 权限必须由服务端同时校验角色、配送点归属、任务归属和数据状态。
• 配送点负责人不能自动获得仓管、调度或质控的全部操作能力；角色可组合，但每项能力独立授权。
• 高风险改派、跨点支援、库存报损、精确轨迹回放和敏感数据导出需要上级授权或审批。
• 前端菜单隐藏和按钮禁用不构成权限控制。

4. 技术与数据约定

• 每张表包含 id bigint 自增主键、created_at 和 updated_at。
• 主表及需要被接口单独访问的明细表包含 UUID V7 identity。
• HTTP、事件、审计和前端只使用 identity；不得暴露数据库内部 ID。
• 金额使用最小货币单位整数。配送点只能读取订单和结算快照，不得自行重算最终应收、人员收益或平台分账。
• 订单、任务、库存流水、轨迹、签收证据和质控结论不得物理删除。
• 现场证据由服务端 App 产生，后台只能查看、标记异常或提交复核，不得代替现场人员补录为已完成。

5. 规划功能域

5.1 配送点资料

配送点仅查看平台或气站维护的组织编码、所属气站、地址、覆盖区域、联系人、营业状态和能力上限。

本点负责人可维护营业时段、值班联系方式、预约容量和临时接单状态。地址、覆盖区域、主体归属、组织冻结和归档等主数据变更必须发起申请，由所属气站或平台审核生效。

5.2 当班人员与能力

能力	规则
人员名册	只显示已由气站或平台关联至本点的人员，不提供创建账号、删除账号或授予角色功能
当班状态	查看上/下班、可接单、当前负载、定位可用性和任务占用情况
班次安排	在人员已授权角色、有效资质和服务区域内安排本点班次
作业前置	只读展示培训、资质、车辆、工具和授权设备校验结果；不允许配送点人员自行改为“已通过”
组织变更	离职、冻结、角色变更、跨点支援和调动只能发起申请，由气站或平台处理

配送点不能查看人员完整身份证件、银行卡、平台级违规档案或与本点任务无关的个人信息。

5.3 配送任务调度

• 接收所属气站或平台下发至本点的待配送任务。
• 按覆盖区域、预约窗口、人员当班状态、配送角色、车辆能力、当前负载、库存和风险限制进行分配。
• 普通改派仅限本点已授权且在岗人员，必须填写原因并保留原分配记录。
• 跨点改派、超区域履约和高风险任务转移只能发起上级协调申请。
• 配送点不得创建交易订单、改写订单最终金额或跳过订单状态机。
• 配送任务状态以服务端校验和 App 履约事实为准，后台不能直接把任务改为已到达、已签收或已完成。

5.4 配送仓

资源	能力	关键规则
调拨接收	核对所属气站发出的调拨单并确认收货差异	不得自行创建跨气站调拨
入库与批次	记录实收数量、批次、扫码结果和异常	来源批次只读，不得修改生产事实
拣货与出库	按已分配配送任务拣货、复核和交接	无有效任务不得出库
在途与退回	跟踪配送员交接、拒收、空瓶和货损退回	在途记录不可覆盖或删除
盘点与损耗	创建盘点、登记差异和损耗原因	超阈值差异需负责人及所属气站复核

库存扣减、回流和冻结必须由订单、任务和交接事实驱动，不能由页面任意修改库存余额。

5.5 履约与轨迹质控

• 查看本点任务的分配、接单、出发、位置上报、到达、签收、异常、改派和取消时间线。
• 识别长时间无位置、偏离授权区域、异常速度、轨迹中断和签收前未到达等异常。
• 查看气瓶/设备扫码、随瓶安检、照片/视频、用户签名或签收码、收款确认和空瓶回收完成情况。
• 质控人员可标记材料缺失、数据冲突或疑似造假，并退回任务补充合法证据或上报气站/平台。
• 改派后旧任务轨迹只读保留，新任务单独采集，不覆盖原责任人和时间线。
• 精确坐标、完整回放和导出按最小权限控制并记录用途；普通仓管和无关人员不得访问。

5.6 用户履约视图

配送点只读取完成本点任务所必需的用户信息：

• 当前任务联系人、脱敏手机号、配送地址、预约时段和交接要求。
• 与本点任务相关的订单、售后、投诉和配送偏好。
• 会影响本次履约的设备或安全限制摘要。

配送点不得创建或编辑用户全局账户、查看完整钱包和支付流水、修改用户地址主档、冻结账号、注销用户或直接变更服务关系。发现资料错误时只能提交纠错或关系变更申请。

5.7 邀请注册

配送点可在平台和所属气站授权的服务区域内创建和管理本点邀请注册二维码，用于社区服务、自提点和线下客户注册。

能力	规则
创建邀请	配置本配送点、所属气站、服务区域、有效期、使用次数和邀请来源
二维码操作	生成、预览、下载、复制注册链接、停用和重新生成
注册处理	新用户完成平台统一注册；已有用户登录确认后只建立本点服务关系
范围校验	地址不在本点配送范围时不得建立错误归属
统计	查看扫码、注册、服务关系建立和失败原因，不展示无关用户隐私

二维码只承载平台签名、可撤销且可过期的邀请码或短链接，不包含配送点账号、用户资料、库存或接口密钥。重复扫码不得覆盖既有服务关系；已有关系变更必须提示影响并取得用户确认。

5.8 对账视图

• 按本点任务查看订单金额快照、配送服务费快照、库存交接和异常差异。
• 对缺少签收、货损、拒收、收款不一致或库存不平的任务提交对账异议。
• 查看所属气站或平台生成的结算结果及异议处理状态。

配送点不得创建资金流水、调整余额、审核提现、确认打款或修改分账比例。

6. 核心流程

6.1 调度与履约

接收配送需求 -> 校验本点范围和库存 -> 选择已授权当班配送员
-> 分配任务 -> App 接单与履约 -> 签收/异常 -> 质控检查 -> 回传气站

• 校验失败时进入待协调，不得通过手工改状态绕过。
• 配送员未接单、定位异常或超时，可在本点范围内回收并改派。
• 现场不合格或触发安全规则时必须上报安全事件，配送点不能自行解除设备或订单限制。

6.2 库存交接

气站调拨出库 -> 配送点核对接收 -> 任务拣货 -> 配送员交接
-> 签收扣减 / 拒收退回 / 货损冻结 -> 盘点与对账

每次交接均保留操作者、时间、任务、批次、数量、来源、去向和差异原因。

7. 审计与安全

• 邀请创建与停用、派单、改派、班次调整、库存交接、盘点差异、质控结论、敏感查看和导出必须审计。
• 手机号、地址、定位、照片、视频和签名按最小权限脱敏或受控访问。
• 离线补传保留原始采集时间、服务端接收时间、操作者、任务、来源、完整性标记和幂等键。
• 任何配送点角色都不能修改原始轨迹、签名、支付、资金流水、安全事件或设备命令事实。
• 数据范围至少同时包含 delivery_basic_identity 和任务归属校验，禁止仅依靠前端筛选。

8. 未实现范围

当前仓库不存在 frontend/delivery_admin 及其独立业务实现。配送点后台、配送仓、调度、质控和本点对账均属于规划能力。

电商、全局用户管理、人员账号与资质审批、跨点调配、平台资金审核、全局安全规则和生产追溯不属于配送点后台建设范围。

9. 规划验收标准

1. 所有页面和接口只返回当前配送点及其任务范围内的数据。
2. 配送点不能创建全局人员或用户账号，不能授予安全角色或修改资质结论。
3. 配送点邀请二维码只能在授权范围内生效，不能重复创建用户或覆盖既有服务关系。
4. 调度只能选择已关联本点、角色有效、资质有效且在岗的配送员。
5. 后台不能补造到达、签收、定位、照片、视频、扫码和收款事实。
6. 跨点改派、跨区域履约和组织主数据变更必须走上级申请。
7. 库存变化由调拨、任务和交接流水驱动，余额不可直接编辑。
8. 配送点只能提出对账异议，不能修改资金流水、分账或提现状态。
9. 敏感字段、精确轨迹和导出按权限控制并完整审计。
10. 状态机、数据范围、幂等和越权场景具有服务端测试。