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

## 1. 项目概述

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

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

## 2. 业务规则

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

## 3. 目录结构与核心文件

```text
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. 接口行为

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

```text
POST /gasorder_basic/:identity/assign
```

```json
{
  "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）：建立合同履约范围内的订单分配与同点改派规则，补充有效资质约束和具体业务错误。