docs: add design for plan single-contract and load products from contract
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
zlwuandCursor committed
1 parent
63a1209620
commit
051c6b6fea
1 file changed
+180
@@ -0,0 +1,180 @@
|
||||
# 运输计划：段次合同单选 + 装货产品限合同内
|
||||
|
||||
**日期：** 2026-08-30
|
||||
**状态：** 已确认设计（方案 1：最小改动）
|
||||
**范围：** `web-admin` 运输计划表单 / 合同完善页 + `backend` 计划段次写入与补合同接口
|
||||
|
||||
## 1. 背景与目标
|
||||
|
||||
现状：装货/送货非内置客户可多选合同；装货「添加产品」走全量 CRM 商品库，与合同无关。业务要求：
|
||||
|
||||
1. 非内置客户（非安庆山峡 / 安徽云栋）每段合同**只能选 1 份**。
|
||||
2. 装货「添加产品」**只能选该合同明细内的产品**。
|
||||
3. 内置客户（`isPlInternalCustomerName` / `is_internal_customer_name`）不限制产品选择，且仍免合同。
|
||||
4. 送货产品仍从装货同步；送货段**允许删除**本段产品（如装 3 送 1）。
|
||||
5. 前后端均强校验。
|
||||
|
||||
## 2. 已确认决策
|
||||
|
||||
| 项 | 决策 |
|
||||
|----|------|
|
||||
| 产品约束范围 | 仅装货「添加产品」；送货从装货同步，自然受装货约束 |
|
||||
| 换合同 | 仅移除「不在新合同内」的装货产品行，保留仍匹配的 |
|
||||
| 历史多合同 | 打开时提示；用户手动删到 1 份；保存强校验 |
|
||||
| 合同完善页 | 与计划表单同一规则（每段最多 1 份） |
|
||||
| 校验落点 | 前端体验 + 后端 API 兜底 |
|
||||
| 实现路径 | 方案 1：不改 `contracts[]` 模型，业务上限为 1 |
|
||||
| 数量不平衡 | 保持现状：仅告警，可暂存 |
|
||||
|
||||
内置客户全称（与现网一致）：
|
||||
|
||||
- `安庆市山峡化工有限公司`
|
||||
- `安徽云栋化工有限公司`
|
||||
|
||||
## 3. 非目标
|
||||
|
||||
- 不把段次 `contracts[]` 改为单字段 `contractId`
|
||||
- 不做送货区独立「添加产品」
|
||||
- 不做数量不平衡硬拦截
|
||||
- 不改库表结构 / 迁移脚本
|
||||
|
||||
## 4. 前端设计
|
||||
|
||||
### 4.1 `PlPlanContractMultiSelect`
|
||||
|
||||
- `ContractSelector` 改为**单选**（去掉 `multiple` / `@confirm-multiple`，走单份确认）。
|
||||
- 默认 `maxContracts = 1`；再选新合同为**替换**，非追加。
|
||||
- 提示：未选 →「请选择合同」；已选 →「已选 1 份」。
|
||||
- `modelValue.length > 1`（历史数据）→ 警告「只能保留一份合同，请移除多余合同后再保存」。
|
||||
- 装货、送货、合同完善页共用该组件行为。
|
||||
|
||||
### 4.2 装货区与产品选择
|
||||
|
||||
- `PlPlanLoadSection`：非内置且未选合同时，「添加产品」禁用并提示先选合同。
|
||||
- 内置客户：行为不变，全量 `ProductSelector`。
|
||||
- `ProductSelector` 增加可选 prop（如 `allowedProductIds?: string[]`）：有值时列表仅展示/允许勾选这些 id（优先前端过滤已加载的合同明细，不强制改商品列表 API）。
|
||||
- `PlPlanFormDialog` 打开选择器时：非内置传入当前装货合同产品 id；内置不传。
|
||||
- 合同变更：用合同明细 `productId` 集合过滤装货 `products`，再走现有送货同步/清理逻辑。
|
||||
|
||||
### 4.3 送货区
|
||||
|
||||
- `PlPlanDeliverySection`：`PlPlanStopProductTable` 的 `allow-remove` 改为 `true`。
|
||||
- 删除只影响该送货段，不回写装货。
|
||||
- 「从装货同步」可将装货产品补回该段。
|
||||
|
||||
### 4.4 保存前校验（表单 + 合同完善）
|
||||
|
||||
- 非内置且 `contracts.length > 1` → **一律拦截**（表单保存 / 安排运输 / 合同完善保存）。
|
||||
- 非内置且 `contracts.length === 0` → **保持现网**：计划草稿/暂存可不选合同；「安排运输」与「合同完善」保存仍按现有必填逻辑。
|
||||
- 非内置且已选 1 份合同时：装货每个产品 `productId` 必须属于该合同明细；否则拦截。未选合同时不做产品归属校验（与「可先建计划再补合同」一致）；但若未选合同却已有装货产品，添加入口应在选合同时再按新合同过滤（见换合同规则）。
|
||||
- 内置：跳过合同份数与产品归属校验。
|
||||
|
||||
## 5. 后端设计
|
||||
|
||||
### 5.1 挂点
|
||||
|
||||
1. `validate_plan_stops_write`（创建/更新计划 full 写入前）
|
||||
2. `update_plan_stop_contracts`（`PUT .../stop-contracts`）
|
||||
3. 若仍走旧 `validate_plan_party_contracts` / side contracts，同样加「最多 1 份」
|
||||
|
||||
### 5.2 规则
|
||||
|
||||
**合同份数（非内置）**
|
||||
|
||||
- 规范化后 `len(contracts) > 1` → `422`，文案如：`装货合同只能选择 1 份` / `送货段#N合同只能选择 1 份`
|
||||
- 内置客户：继续清空合同关联（现有逻辑）
|
||||
|
||||
**装货产品归属（非内置且已选合同）**
|
||||
|
||||
- 仅当装货段已选 1 份合同时执行；未选合同则跳过（允许先建计划再补合同）
|
||||
- 取合同 CRM 明细 `product_id` 集合
|
||||
- 装货段产品（及实际落库权威产品行）凡带 `productId` 的必须 ∈ 该集合
|
||||
- 不在集合 → `422`，文案如：`装货产品「xxx」不在所选合同明细中`
|
||||
- 内置客户：不做产品归属校验
|
||||
- **送货段产品**：不做「必须在送货合同内」校验（产品来自装货同步/删减；送货合同只管商务关联）
|
||||
|
||||
> 说明：本设计将「每段可多选合同」收紧为最多 1 份，覆盖 `2026-08-20-pl-plan-contract-complete-design.md` 中「每侧可多选」的约定。
|
||||
|
||||
**合同完善接口**
|
||||
|
||||
- 仅校验该段规范化后 `contracts` 长度 ≤ 1（及现有客户匹配、可选状态）
|
||||
- 不在此接口改产品
|
||||
|
||||
### 5.3 错误策略
|
||||
|
||||
- 与邻近 `validate_plan_stops_write` 一致，优先 `HTTP 422`
|
||||
- 前端用接口 `detail` 直接展示，不吞错
|
||||
|
||||
## 6. 数据流
|
||||
|
||||
```
|
||||
选装货客户（非内置）
|
||||
→ 选择 1 份合同
|
||||
→ 添加产品（仅合同 productId）
|
||||
→ 写入装货产品 → 同步到送货段
|
||||
→ 送货段可删除不需要的行（可再「从装货同步」）
|
||||
→ 换合同：过滤装货不匹配行 → 影响送货同步
|
||||
→ 保存：前端校验 → 后端校验
|
||||
```
|
||||
|
||||
## 7. 边界情况
|
||||
|
||||
| 情况 | 处理 |
|
||||
|------|------|
|
||||
| 打开编辑时已有 >1 份合同 | 提示；允许查看/移除；保存前必须 ≤1 |
|
||||
| 合同无产品明细 | 允许选合同；添加产品列表为空并提示 |
|
||||
| 产品无 `productId`（脏数据） | 非内置时保存拦截 |
|
||||
| 装货删产品 | 送货对应行按现有联动处理 |
|
||||
| 仅送货删产品 | 装货不变；数量不平衡仍只告警 |
|
||||
| 客户从非内置改为内置 | 清空合同；产品保留 |
|
||||
| 客户从内置改为非内置 | 要求选合同；保存时校验产品归属 |
|
||||
|
||||
## 8. 测试计划
|
||||
|
||||
### 后端单测
|
||||
|
||||
- 非内置 2 份合同 → 失败
|
||||
- 非内置 1 份合同 + 合同外产品 → 失败
|
||||
- 非内置 1 份 + 合同内产品 → 通过
|
||||
- 内置客户多产品无合同 → 通过
|
||||
- `stop-contracts` 传 2 份 → 失败
|
||||
|
||||
### 前端 / 手工验收
|
||||
|
||||
- [ ] 非内置：合同选择器只能确认 1 份；再选则替换
|
||||
- [ ] 非内置未选合同：添加产品禁用
|
||||
- [ ] 非内置已选合同：只能勾选合同内产品
|
||||
- [ ] 换合同：仅移除不匹配装货行
|
||||
- [ ] 送货可删产品；同步可补回
|
||||
- [ ] 历史多合同：提示 + 保存失败直到剩 1 份
|
||||
- [ ] 合同完善页同样最多 1 份
|
||||
- [ ] 内置客户：无合同限制，产品全量可选
|
||||
|
||||
## 9. 主要改动文件（预期）
|
||||
|
||||
**前端**
|
||||
|
||||
- `web-admin/src/components/business/pl-plan-contract-multi-select/index.vue`
|
||||
- `web-admin/src/components/business/pl-plan-load-section/index.vue`
|
||||
- `web-admin/src/components/business/pl-plan-delivery-section/index.vue`
|
||||
- `web-admin/src/components/business/pl-plan-form-dialog/index.vue`
|
||||
- `web-admin/src/components/business/product-selector/index.vue`
|
||||
- `web-admin/src/views/pl/plan-contract/index.vue`（保存校验对齐）
|
||||
|
||||
**后端**
|
||||
|
||||
- `backend/app/services/pl_plan_stop_service.py`（`validate_plan_stops_write` / `_resolve_stop_contracts`）
|
||||
- `backend/app/services/pl_plan_contract_gap.py`（`update_plan_stop_contracts`）
|
||||
- `backend/app/services/pl_plan_service.py`（若 side contracts 仍在用）
|
||||
- `backend/tests/test_pl_plan_stop_*.py` / 合同相关单测增补
|
||||
|
||||
## 10. 方案取舍说明
|
||||
|
||||
采用方案 1（最小改动）：保留 `contracts[]`，业务层上限为 1。相对方案 2（专用合同产品弹窗）改动更小；相对方案 3（模型改单字段）避免迁移与大范围兼容成本。
|
||||
|
||||
## 11. 自检记录
|
||||
|
||||
- 无 TBD/TODO 占位。
|
||||
- 合同「必填」与「最多 1 份」已区分：仅 `>1` 全路径强拦；`===0` 保持可先建计划再补合同。
|
||||
- 送货不做合同内产品校验，与「仅约束装货添加」一致。
|
||||
- 范围可单次实现计划覆盖，无需再拆子项目。
|
||||
Reference in new issue
Block a user