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

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

1. 文档目的

本文按照 docs/05-平台总后台需求.md 的章节、资源模式、权限和验收口径，定义配送点管理系统的规划基线。

前端工作目录： frontend/delivery_admin 完全复制：frontend/platform_admin内所有文件在修改 后端工作目录：backend/api 与总平台复用一个API目录 后端API的URL前缀：/heqi/delivery/v1

后续实现事实按以下顺序核对并回写本文：

1. 配送点端实际 HTTP 路由。
2. 配送点端前后端资源契约。
3. 配送点端字段、关系、页面模式和业务动作定义。
4. 配送点端菜单、页面与隐藏子资源。
5. 配送点端状态机、事务、权限和数据范围校验。

2. 系统定位与边界

配送点管理系统面向配送点负责人、调度员、仓管员和配送质控人员，负责本点当班能力、配送调度、配送仓、轨迹异常、交接质控、邀请注册和对账异议。

当前规划不替代以下系统：

• 平台总后台：全局组织、用户与人员账号、角色资质、资金审核和安全规则仍由平台主责。
• 气站管理系统：气站库存、燃气配送订单主责、跨配送点协调和气站结算仍由所属气站主责。
• 生产管理系统：生产批次、出厂质检、设备身份和召回仍由生产系统主责。
• 用户端与服务端 App：用户注册确认、配送员接单、定位、扫码、签收和现场取证仍由对应 App 完成。
• 电商平台：商品、分类、购物车、商城订单、评价和营销活动不属于配送点管理系统。

配送点不能创建全局用户或人员账号，不能授予安全角色，不能创建交易订单、审核提现、修改资金流水、关闭安全事件或跨点调度。组织、人员、用户关系和跨点事项只能向所属气站或平台申请。

独立 API 基础路径和鉴权请求头格式须在实现时通过契约确定；确定前不得沿用平台 API 路径冒充配送点端接口。

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	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 的分层。

3.2 数据身份

• 每一张表均使用 id bigint 自增主键，Go 模型对应 ID uint64。
• 主表及需要单独访问、跨系统引用或审计定位的明细表使用 UUID V7 identity。
• id 仅用于数据库内部关联；HTTP、前端、事件、审计和跨服务调用使用 identity。
• 配送点数据范围至少校验 delivery_basic_identity、任务归属和订单/调拨关系。
• 通用状态与任务、库存、邀请、质控和对账等业务状态分离。
• 删除执行归档或受控删除；任务过程、库存流水、轨迹、证据、邀请使用和对账事实不得物理删除。
• 金额使用最小货币单位整数；配送点只能读取权威金额快照。

3.3 资源页面模式

模式	能力
writable	列表、详情、新增、编辑、状态调整和归档
editable	列表、详情、新增、编辑和状态调整，不提供归档
readonly	列表和详情；可通过显式业务动作处理，但无通用增删改
append_only	可创建事实记录，既有记录不通用编辑或删除
managed	可创建和编辑，但生命周期必须通过专用动作推进

普通资源应复用共享资源页面。库存流水、轨迹、证据、邀请使用记录和对账事实使用只读或仅追加模式；任务状态不得通过通用 CRUD 直接修改。

4. 登录、账户与权限

4.1 登录与个人账户

• 配送点后台账号由平台创建或关联，配送点系统不提供自助创建管理员账号。
• 停用、冻结、未关联本点或角色无效的账户不得登录。
• 登录成功返回 JWT、账户 identity、显示名称、角色编码、配送点 identity 和菜单编码。
• 已登录账户只能查看和修改本人的非敏感资料；角色、组织归属和数据范围不能自行修改。
• 修改密码必须校验当前密码，新密码不少于 6 位。
• 配送点系统不得初始化共享默认管理员密码；首次账号由平台受控创建。

4.2 RBAC 与数据能力

• 配送点负责人、调度员、仓管员和配送质控人员使用独立菜单能力。
• 配送点负责人不自动拥有仓管、调度、质控、敏感导出和资金能力。
• 调度员只能选择已关联本点、角色有效、资质有效且在岗的配送员。
• 仓管员只能操作本点配送仓，不能修改任务、金额、资金、安全事件和人员权限。
• 质控人员只能查看和标记本点证据异常，不能修改原始证据或关闭平台安全事件。
• 邀请管理权限独立授予；邀请码只能绑定当前配送点和已授权服务区域。
• 精确轨迹回放、完整证据和敏感导出使用独立权限并记录用途。
• 配送员不使用 Web 后台，只通过服务端 App 处理本人任务。
• 前端菜单隐藏只负责展示，最终权限由服务端执行。

5. 首页与报表

首页规划聚合以下本点指标：

• 待接收、待分配、待接单、配送中、待确认、异常和已完成任务数量。
• 当前在岗、可接单、任务占用和作业前置异常人员数量。
• 配送仓可用、冻结、在途、待退回和盘点差异数量。
• 超时、无定位、偏航、轨迹中断、拒收和货损数量。
• 待质控任务、证据缺失、疑似冲突和退回补充数量。
• 邀请二维码启用数、扫码数、注册数和服务关系建立数。
• 当前周期配送服务费快照和对账差异数量。
• 最近 7 个自然日的任务数量、完成率和平均时效趋势；无数据日期补零。

首页快捷入口按角色菜单过滤。报表只聚合本点真实任务、库存和质控事实，不展示其他配送点明细，不生成虚构数据，不提供电商报表。

6. 规划功能域

规划路径必须在独立配送点端契约中确认。下表的“路径”统一标记为待确认，不得直接复用平台资源路径。

6.1 配送点经营设置

资源	路径	模式	规划能力
配送点资料	待契约确认	readonly	查看平台维护的组织、地址、区域、归属气站和状态
营业设置	待契约确认	managed	维护营业时段、预约容量、值班联系和临时接单状态
组织变更申请	待契约确认	append_only	提交地址、区域、冻结、归档和迁移申请

配送点不能直接修改组织主数据、覆盖区域或归属气站。

6.2 当班人员

资源	路径	模式	规划能力
人员名册	待契约确认	readonly	查看平台已关联本点的人员
作业能力	待契约确认	readonly	查看角色、资质、培训、车辆、在岗和可接单结果
班次	待契约确认	managed	在已授权角色和区域内安排本点班次
人员变更申请	待契约确认	append_only	申请新增关联、角色变更、冻结、离职和跨点支援

配送点不能创建人员账号、授予角色、修改资质和培训结论，也不能查看无关证件和银行卡数据。

6.3 配送任务调度

资源	路径	模式	规划能力
配送任务	待契约确认	managed	接收气站需求并执行本点职责范围内的状态动作
分配记录	待契约确认	append_only	记录分配、回收和本点改派
订单摘要	待契约确认	readonly	查看履约必需的订单、预约和金额快照
异常协调申请	待契约确认	append_only	提交跨点、超区域和高风险任务协调

配送点不能创建交易订单、修改最终金额或跳过任务状态机。跨点改派只能由气站或平台协调。

6.4 配送仓

资源	路径	模式	规划能力
库存余额	待契约确认	readonly	查询本点可用、冻结、在途和待退回数量
库存流水	待契约确认	append_only	记录接收、入库、拣货、出库、退回和损耗
调拨接收	待契约确认	managed	核对所属气站调拨并确认差异
盘点单	待契约确认	managed	创建盘点、记录实盘和差异，按阈值复核

库存余额不能直接编辑。无有效任务不得出库，跨气站调拨不能由配送点创建。

6.5 履约与轨迹质控

资源	路径	模式	规划能力
轨迹	待契约确认	readonly	查看本点任务状态时间线和授权范围内轨迹
现场证据	待契约确认	readonly	查看扫码、照片、视频、签名、收款确认和空瓶回收
质控记录	待契约确认	append_only	标记材料缺失、数据冲突、疑似造假和复核结果
轨迹异常	待契约确认	managed	处理无定位、偏航、异常速度和轨迹中断提醒

后台不能补造或修改 App 产生的到达、定位、扫码、签收和收款事实。旧任务轨迹在改派后只读保留。

6.6 用户履约视图

资源	路径	模式	规划能力
用户履约摘要	待契约确认	readonly	查看当前任务所需的脱敏联系人、地址和交接要求
服务记录	待契约确认	append_only	记录本点预约、联系、配送异常和回访
用户变更申请	待契约确认	append_only	提交资料纠错和服务关系变更申请

配送点不能创建或编辑全局用户、查看完整钱包、冻结账号、注销用户或直接改变服务关系。

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. 契约检查、权限测试、状态机测试、后端测试和前端构建全部通过。