platforms/docs/项目文档_配送订单合同调度约束_v1.0.md

项目文档_配送订单合同调度约束_v1.0

1. 项目概述

本次修复平台总后台“分配订单”弹窗忽略订单配送合同和组织范围的问题。旧实现会独立加载配送点与配送人员，允许管理员组合跨气站或跨配送点数据，直到提交后才收到泛化的“请求参数不正确”。

修复后，分配动作继承订单创建时保存的合同履约气站和配送点快照，并由服务端执行相同的最终校验。

2. 业务规则

• 配送合同绑定签约用户、签约气站和可选配送点，不直接绑定配送人员。
• 合同已指定配送点时，订单分配弹窗自动带出并锁定该点。
• 合同未指定配送点时，仅展示合同气站直属且启用的配送点。
• 选择配送点后，仅展示同时满足以下条件的工作人员：
  • 角色为配送人员；
  • 属于订单履约气站和目标配送点；
  • 账号启用且当前在岗；
  • 至少拥有一条启用且未过期的资质。
• 已分配订单只允许在当前配送点内改派配送人员，不允许更换配送点。
• 每次分配或改派继续填写原因，并追加不可覆盖的分配记录。
• 前端候选限制不构成安全控制，服务端对合同范围、组织归属、岗位状态和有效资质进行重复校验。

3. 目录结构与核心文件

platforms/
├── backend/api/internal/logic/platform/
│   ├── gasorder/gasorder.go              # 分配事务、合同范围和人员准入校验
│   ├── gasorder/gasorder_test.go         # 合同固定点、同点改派及资质回归测试
│   ├── delivery/delivery.go              # 启用配送点候选筛选
│   └── staff/staff.go                    # 有效资质人员候选筛选
├── frontend/platform_admin/
│   ├── src/api/resources.ts              # 分配动作候选规则
│   ├── src/api/resource-staff-relation.ts # 有效资质筛选策略
│   ├── src/views/resource/ResourceActionDialog.vue # 动作弹窗履约联动
│   └── scripts/check-gasorder-assignment-linkage.mjs # 前端回归检查
└── docs/                                 # 需求基线、项目文档与操作日志

4. 接口行为

分配接口路径和请求字段保持不变：

POST /gasorder_basic/:identity/assign

{
  "delivery_basic_identity": "配送点唯一标识",
  "staff_account_identity": "配送人员唯一标识",
  "reason": "分配或改派原因"
}

候选列表新增兼容性查询条件：

• /delivery_basic?gas_basic_identities=<气站标识>&status=1
• /staff_account?gas_basic_identities=<气站标识>&delivery_basic_identities=<配送点标识>&role_code=delivery&status=1&work_status=on_duty&valid_credential_only=1

未携带新增查询条件时，原有管理列表行为保持不变。

5. 行为变化

场景	修改前	修改后
合同指定配送点	弹窗仍可选择其他配送点	自动带出并锁定合同配送点
合同未指定配送点	可看到全平台配送点	仅展示合同气站直属启用配送点
配送人员候选	仅按角色、启用和在岗筛选	追加气站、配送点和有效资质约束
已分配订单改派	可再次提交不同配送点	只能在当前配送点内改派人员
非法组合错误	统一显示请求参数不正确	返回合同点、组织、状态或资质的具体原因

6. 维护指南

• 调整合同配送点语义时，必须同步检查订单创建快照、分配弹窗和服务端分配校验。
• 新增配送人员准入条件时，应同时更新人员候选查询和服务端事务校验。
• 不得取消服务端校验或只依赖前端禁用状态。
• 修改本功能后至少运行后端 gasorder、staff、delivery 单元测试，以及前端类型检查、分配联动检查和生产构建。

7. 版本记录

• v1.0（2026-08-15）：建立合同履约范围内的订单分配与同点改派规则，补充有效资质约束和具体业务错误。