docs: add implementation plan for plan single-contract product rules
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
zlwuandCursor committed
1 parent
051c6b6fea
commit
98db382e70
1 file changed
+837
@@ -0,0 +1,837 @@
|
||||
# 运输计划段次合同单选 + 装货产品限合同内 Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** 非内置客户每段最多 1 份合同；装货「添加产品」只能选自该合同明细；内置客户不限产品；送货可删本段产品；前后端强校验。
|
||||
|
||||
**Architecture:** 保留 `contracts[]`，业务上限为 1。后端在 `validate_plan_stops_write` / `update_plan_stop_contracts`（及仍使用的 side contracts）校验份数与装货产品归属。前端 `PlPlanContractMultiSelect` 改为单选；`ProductSelector` 支持 `allowedProductIds`；装货未选合同禁用添加；换合同按 `productId` 过滤装货行；送货表 `allow-remove=true`。
|
||||
|
||||
**Tech Stack:** FastAPI、SQLAlchemy、pytest、Vue 3、Element Plus、TypeScript
|
||||
|
||||
**Spec:** `docs/superpowers/specs/2026-08-30-pl-plan-single-contract-products-design.md`
|
||||
|
||||
**注意：** 工作区可能有与本需求无关的未提交改动（如地磅勾选）。实现时只改本计划列出的文件，提交时勿夹带无关 diff。
|
||||
|
||||
---
|
||||
|
||||
## 文件结构
|
||||
|
||||
| 操作 | 文件 | 职责 |
|
||||
|------|------|------|
|
||||
| Create | `backend/tests/test_pl_plan_single_contract_rules.py` | 合同上限 / 装货产品归属纯函数单测 |
|
||||
| Modify | `backend/app/services/pl_plan_stop_service.py` | `_resolve_stop_contracts` 上限 1；装货产品归属校验 |
|
||||
| Modify | `backend/app/services/pl_plan_contract_gap.py` | `update_plan_stop_contracts` 上限 1 |
|
||||
| Modify | `backend/app/services/pl_plan_service.py` | `validate_plan_party_contracts` 上限 1（旧路径） |
|
||||
| Create | `web-admin/src/utils/pl-plan-contract-product.ts` | 合同 productId 集合、按合同过滤装货产品 |
|
||||
| Modify | `web-admin/src/components/business/pl-plan-contract-multi-select/index.vue` | 单选合同 + 历史多合同提示 |
|
||||
| Modify | `web-admin/src/components/business/product-selector/index.vue` | `allowedProductIds` 限制可选集 |
|
||||
| Modify | `web-admin/src/components/business/pl-plan-load-section/index.vue` | 未选合同禁用添加产品 |
|
||||
| Modify | `web-admin/src/components/business/pl-plan-delivery-section/index.vue` | 送货产品允许删除 |
|
||||
| Modify | `web-admin/src/components/business/pl-plan-form-dialog/index.vue` | 传 allowedProductIds；换合同过滤；保存校验 >1 |
|
||||
| Modify | `web-admin/src/views/pl/plan-contract/index.vue` | 保存前校验最多 1 份 |
|
||||
|
||||
---
|
||||
|
||||
### Task 1: 后端纯函数 — 合同最多 1 份
|
||||
|
||||
**Files:**
|
||||
- Create: `backend/tests/test_pl_plan_single_contract_rules.py`
|
||||
- Modify: `backend/app/services/pl_plan_stop_service.py`
|
||||
|
||||
- [ ] **Step 1: 写失败单测**
|
||||
|
||||
在 `backend/tests/test_pl_plan_single_contract_rules.py`：
|
||||
|
||||
```python
|
||||
import pytest
|
||||
from fastapi import HTTPException
|
||||
|
||||
from app.schemas.pl.plan import PlanContractLink
|
||||
from app.services.pl_plan_stop_service import assert_at_most_one_contract
|
||||
|
||||
|
||||
def test_assert_at_most_one_contract_allows_zero_or_one():
|
||||
assert assert_at_most_one_contract([], "装货合同") == []
|
||||
one = [PlanContractLink(contractId="c1", contractNo="N1")]
|
||||
assert assert_at_most_one_contract(one, "装货合同") == one
|
||||
|
||||
|
||||
def test_assert_at_most_one_contract_rejects_two():
|
||||
links = [
|
||||
PlanContractLink(contractId="c1", contractNo="N1"),
|
||||
PlanContractLink(contractId="c2", contractNo="N2"),
|
||||
]
|
||||
with pytest.raises(HTTPException) as exc:
|
||||
assert_at_most_one_contract(links, "装货合同")
|
||||
assert exc.value.status_code == 422
|
||||
assert "只能选择 1 份" in str(exc.value.detail)
|
||||
```
|
||||
|
||||
- [ ] **Step 2: 运行确认失败**
|
||||
|
||||
```bash
|
||||
cd backend && source venv/bin/activate && pytest tests/test_pl_plan_single_contract_rules.py::test_assert_at_most_one_contract_rejects_two -v
|
||||
```
|
||||
|
||||
Expected: FAIL（`assert_at_most_one_contract` 未定义）
|
||||
|
||||
- [ ] **Step 3: 实现函数并挂到 `_resolve_stop_contracts`**
|
||||
|
||||
在 `pl_plan_stop_service.py`（`_normalize_contract_links` 附近）新增：
|
||||
|
||||
```python
|
||||
def assert_at_most_one_contract(
|
||||
links: list[PlanContractLink],
|
||||
side_label: str,
|
||||
) -> list[PlanContractLink]:
|
||||
if len(links) > 1:
|
||||
raise HTTPException(
|
||||
status_code=422,
|
||||
detail=f"{side_label}只能选择 1 份",
|
||||
)
|
||||
return links
|
||||
```
|
||||
|
||||
在 `_resolve_stop_contracts` 中，`links = _normalize_contract_links(contracts)` 之后立刻：
|
||||
|
||||
```python
|
||||
links = assert_at_most_one_contract(links, side_label)
|
||||
```
|
||||
|
||||
- [ ] **Step 4: 跑通单测**
|
||||
|
||||
```bash
|
||||
cd backend && source venv/bin/activate && pytest tests/test_pl_plan_single_contract_rules.py -v
|
||||
```
|
||||
|
||||
Expected: PASS
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add backend/app/services/pl_plan_stop_service.py backend/tests/test_pl_plan_single_contract_rules.py
|
||||
git commit -m "$(cat <<'EOF'
|
||||
feat(pl): enforce at most one contract per plan stop
|
||||
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 2: 后端 — 装货产品必须属于所选合同
|
||||
|
||||
**Files:**
|
||||
- Modify: `backend/tests/test_pl_plan_single_contract_rules.py`
|
||||
- Modify: `backend/app/services/pl_plan_stop_service.py`
|
||||
|
||||
- [ ] **Step 1: 写失败单测（产品归属）**
|
||||
|
||||
追加到同测试文件：
|
||||
|
||||
```python
|
||||
from types import SimpleNamespace
|
||||
from app.schemas.pl.plan import PlanLoadBody, PlanStopProductBody
|
||||
from app.services.pl_plan_stop_service import assert_load_products_in_selected_contract
|
||||
|
||||
|
||||
class _FakeQuery:
|
||||
def __init__(self, rows):
|
||||
self._rows = rows
|
||||
|
||||
def filter(self, *args, **kwargs):
|
||||
return self
|
||||
|
||||
def all(self):
|
||||
return self._rows
|
||||
|
||||
|
||||
class _FakeDb:
|
||||
def __init__(self, product_ids):
|
||||
self._rows = [SimpleNamespace(product_id=pid) for pid in product_ids]
|
||||
|
||||
def query(self, model):
|
||||
return _FakeQuery(self._rows)
|
||||
|
||||
|
||||
def _load_with_products(product_ids, contract_id="c1"):
|
||||
return PlanLoadBody(
|
||||
customerId="cust-1",
|
||||
customerName="外部客户A",
|
||||
contracts=[PlanContractLink(contractId=contract_id, contractNo="N1")],
|
||||
products=[
|
||||
PlanStopProductBody(
|
||||
productId=pid,
|
||||
productNo=pid,
|
||||
productName=f"产品{pid}",
|
||||
unit="吨",
|
||||
quantity=1,
|
||||
)
|
||||
for pid in product_ids
|
||||
],
|
||||
)
|
||||
|
||||
|
||||
def test_assert_load_products_in_contract_passes_when_all_match():
|
||||
db = _FakeDb(["p1", "p2"])
|
||||
load = _load_with_products(["p1"])
|
||||
assert_load_products_in_selected_contract(db, "shanxia2.0", load)
|
||||
|
||||
|
||||
def test_assert_load_products_in_contract_rejects_outside():
|
||||
db = _FakeDb(["p1"])
|
||||
load = _load_with_products(["p2"])
|
||||
with pytest.raises(HTTPException) as exc:
|
||||
assert_load_products_in_selected_contract(db, "shanxia2.0", load)
|
||||
assert exc.value.status_code == 422
|
||||
assert "不在所选合同明细中" in str(exc.value.detail)
|
||||
|
||||
|
||||
def test_assert_load_products_skips_when_no_contract():
|
||||
db = _FakeDb([])
|
||||
load = PlanLoadBody(
|
||||
customerId="cust-1",
|
||||
customerName="外部客户A",
|
||||
contracts=[],
|
||||
products=[
|
||||
PlanStopProductBody(
|
||||
productId="p1",
|
||||
productNo="p1",
|
||||
productName="产品p1",
|
||||
unit="吨",
|
||||
quantity=1,
|
||||
)
|
||||
],
|
||||
)
|
||||
assert_load_products_in_selected_contract(db, "shanxia2.0", load)
|
||||
|
||||
|
||||
def test_assert_load_products_skips_internal_customer():
|
||||
from app.services.pl_internal_customer import INTERNAL_CUSTOMER_NAMES
|
||||
|
||||
internal = next(iter(INTERNAL_CUSTOMER_NAMES))
|
||||
db = _FakeDb([])
|
||||
load = PlanLoadBody(
|
||||
customerId="cust-1",
|
||||
customerName=internal,
|
||||
contracts=[],
|
||||
products=[
|
||||
PlanStopProductBody(
|
||||
productId="p1",
|
||||
productNo="p1",
|
||||
productName="产品p1",
|
||||
unit="吨",
|
||||
quantity=1,
|
||||
)
|
||||
],
|
||||
)
|
||||
assert_load_products_in_selected_contract(db, "shanxia2.0", load)
|
||||
```
|
||||
|
||||
若 `PlanLoadBody` / `PlanStopProductBody` 构造字段与现网不一致，按 `backend/app/schemas/pl/plan.py` 实际必填字段微调测试（保持语义不变）。
|
||||
|
||||
- [ ] **Step 2: 运行确认失败**
|
||||
|
||||
```bash
|
||||
cd backend && source venv/bin/activate && pytest tests/test_pl_plan_single_contract_rules.py::test_assert_load_products_in_contract_rejects_outside -v
|
||||
```
|
||||
|
||||
Expected: FAIL（函数未定义）
|
||||
|
||||
- [ ] **Step 3: 实现 `assert_load_products_in_selected_contract`**
|
||||
|
||||
```python
|
||||
from app.models.crm_models import CrmContractProduct
|
||||
|
||||
|
||||
def assert_load_products_in_selected_contract(
|
||||
db: Session,
|
||||
tenant_no: str,
|
||||
load: PlanLoadBody,
|
||||
) -> None:
|
||||
if is_internal_customer_name(load.customer_name):
|
||||
return
|
||||
links = _normalize_contract_links(load.contracts)
|
||||
if not links:
|
||||
return
|
||||
contract_id = (links[0].contract_id or "").strip()
|
||||
if not contract_id:
|
||||
return
|
||||
rows = (
|
||||
db.query(CrmContractProduct)
|
||||
.filter(
|
||||
CrmContractProduct.contract_id == contract_id,
|
||||
CrmContractProduct.tenant_no == tenant_no,
|
||||
CrmContractProduct.del_flag == 0,
|
||||
)
|
||||
.all()
|
||||
)
|
||||
allowed = {
|
||||
str(r.product_id).strip()
|
||||
for r in rows
|
||||
if getattr(r, "product_id", None) and str(r.product_id).strip()
|
||||
}
|
||||
for prod in load.products or []:
|
||||
pid = str(getattr(prod, "product_id", None) or "").strip()
|
||||
name = (getattr(prod, "product_name", None) or pid or "未命名").strip()
|
||||
if not pid or pid not in allowed:
|
||||
raise HTTPException(
|
||||
status_code=422,
|
||||
detail=f"装货产品「{name}」不在所选合同明细中",
|
||||
)
|
||||
```
|
||||
|
||||
在 `validate_plan_stops_write` 中，装货合同 resolve 完成、deliveries 循环结束后、`return` 前调用：
|
||||
|
||||
```python
|
||||
assert_load_products_in_selected_contract(db, tenant_no, load)
|
||||
```
|
||||
|
||||
注意：调用时 `load.contracts` 应为已 resolve 的列表；若 resolve 清空了内置客户合同，上述函数会因无合同而跳过。
|
||||
|
||||
- [ ] **Step 4: 跑通单测**
|
||||
|
||||
```bash
|
||||
cd backend && source venv/bin/activate && pytest tests/test_pl_plan_single_contract_rules.py -v
|
||||
```
|
||||
|
||||
Expected: PASS
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add backend/app/services/pl_plan_stop_service.py backend/tests/test_pl_plan_single_contract_rules.py
|
||||
git commit -m "$(cat <<'EOF'
|
||||
feat(pl): require load products to belong to selected contract
|
||||
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 3: 后端 — 合同完善与旧 side contracts 上限
|
||||
|
||||
**Files:**
|
||||
- Modify: `backend/app/services/pl_plan_contract_gap.py`
|
||||
- Modify: `backend/app/services/pl_plan_service.py`
|
||||
- Modify: `backend/tests/test_pl_plan_single_contract_rules.py`（可选：补文档化用例注释即可；合同完善路径复用同一 `assert_at_most_one_contract`）
|
||||
|
||||
- [ ] **Step 1: 在 `update_plan_stop_contracts` 规范化后校验**
|
||||
|
||||
`pl_plan_contract_gap.py` 中 `links = _normalize_contract_links(contracts)` 之后（约 566 行后）：
|
||||
|
||||
```python
|
||||
from app.services.pl_plan_stop_service import assert_at_most_one_contract
|
||||
|
||||
links = assert_at_most_one_contract(links, side_label)
|
||||
```
|
||||
|
||||
若该文件已有本地 `_normalize_contract_links`，仍复用 stop_service 的 `assert_at_most_one_contract`，避免两套上限逻辑。
|
||||
|
||||
- [ ] **Step 2: 在 `validate_plan_party_contracts` 校验供/需两侧**
|
||||
|
||||
`pl_plan_service.py` 中规范化后：
|
||||
|
||||
```python
|
||||
from app.services.pl_plan_stop_service import assert_at_most_one_contract
|
||||
|
||||
supplier_links = assert_at_most_one_contract(supplier_links, "供方合同")
|
||||
demander_links = assert_at_most_one_contract(demander_links, "需方合同")
|
||||
```
|
||||
|
||||
- [ ] **Step 3: 回归相关单测**
|
||||
|
||||
```bash
|
||||
cd backend && source venv/bin/activate && pytest tests/test_pl_plan_single_contract_rules.py tests/test_pl_plan_contract_gap.py tests/test_pl_plan_stop_service.py -v
|
||||
```
|
||||
|
||||
Expected: PASS（`test_pl_plan_contract_gap` 中「demander_contract_count=2」仅测缺口判定计数，不走写入校验，应仍通过）
|
||||
|
||||
- [ ] **Step 4: Commit**
|
||||
|
||||
```bash
|
||||
git add backend/app/services/pl_plan_contract_gap.py backend/app/services/pl_plan_service.py
|
||||
git commit -m "$(cat <<'EOF'
|
||||
feat(pl): enforce single contract on stop-contracts and legacy side paths
|
||||
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 4: 前端工具函数 — 合同产品过滤
|
||||
|
||||
**Files:**
|
||||
- Create: `web-admin/src/utils/pl-plan-contract-product.ts`
|
||||
|
||||
- [ ] **Step 1: 新增工具**
|
||||
|
||||
```typescript
|
||||
/** 从合同明细行收集 CRM productId */
|
||||
export function collectContractProductIds(
|
||||
products?: Array<{ productId?: string | null }> | null
|
||||
): string[] {
|
||||
const ids: string[] = []
|
||||
const seen = new Set<string>()
|
||||
for (const row of products || []) {
|
||||
const id = String(row?.productId || '').trim()
|
||||
if (!id || seen.has(id)) continue
|
||||
seen.add(id)
|
||||
ids.push(id)
|
||||
}
|
||||
return ids
|
||||
}
|
||||
|
||||
/** 保留 productId 落在 allowed 内的装货行；allowed 为空则全部移除（换合同且新合同无产品） */
|
||||
export function filterProductsByAllowedProductIds<T extends { productId?: string | null }>(
|
||||
products: T[],
|
||||
allowedProductIds: string[]
|
||||
): T[] {
|
||||
const allowed = new Set(
|
||||
(allowedProductIds || []).map((id) => String(id).trim()).filter(Boolean)
|
||||
)
|
||||
if (!allowed.size) return []
|
||||
return (products || []).filter((row) => allowed.has(String(row.productId || '').trim()))
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Commit**
|
||||
|
||||
```bash
|
||||
git add web-admin/src/utils/pl-plan-contract-product.ts
|
||||
git commit -m "$(cat <<'EOF'
|
||||
feat(web-admin): add helpers to filter plan products by contract
|
||||
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 5: `PlPlanContractMultiSelect` 改为单选
|
||||
|
||||
**Files:**
|
||||
- Modify: `web-admin/src/components/business/pl-plan-contract-multi-select/index.vue`
|
||||
|
||||
- [ ] **Step 1: ContractSelector 改单选**
|
||||
|
||||
将：
|
||||
|
||||
```vue
|
||||
<ContractSelector
|
||||
v-if="!readonly"
|
||||
v-model:visible="selectorVisible"
|
||||
:customer-id="customerId"
|
||||
:selectable-statuses="selectableStatuses"
|
||||
multiple
|
||||
:selected-ids="selectedIds"
|
||||
hide-amount
|
||||
@confirm-multiple="handleConfirmMultiple"
|
||||
/>
|
||||
```
|
||||
|
||||
改为：
|
||||
|
||||
```vue
|
||||
<ContractSelector
|
||||
v-if="!readonly"
|
||||
v-model:visible="selectorVisible"
|
||||
:customer-id="customerId"
|
||||
:selectable-statuses="selectableStatuses"
|
||||
:selected-id="selectedIds[0] || ''"
|
||||
hide-amount
|
||||
@confirm="handleConfirmSingle"
|
||||
/>
|
||||
```
|
||||
|
||||
（若 `ContractSelector` 的单选 prop 名为 `selectedId` / 事件为 `confirm`，以组件 `defineProps` / `defineEmits` 为准对齐。）
|
||||
|
||||
- [ ] **Step 2: 替换确认处理与提示文案**
|
||||
|
||||
```typescript
|
||||
async function handleConfirmSingle(contract: ContractVO) {
|
||||
const enriched = await enrichContractProducts(contract)
|
||||
detailRows.value = [enriched]
|
||||
emitLinksFromDetails(detailRows.value)
|
||||
}
|
||||
|
||||
const hintText = computed(() => {
|
||||
if (!props.customerId) return '请先选择客户'
|
||||
if (selectedIds.value.length > 1) {
|
||||
return '只能保留一份合同，请移除多余合同后再保存'
|
||||
}
|
||||
if (hintWarn.value) return '请选择合同'
|
||||
if (selectedIds.value.length) return '已选 1 份'
|
||||
return ''
|
||||
})
|
||||
|
||||
const hintWarn = computed(() => {
|
||||
if (!props.customerId) return false
|
||||
if (selectedIds.value.length > 1) return true
|
||||
return !!props.required && !selectedIds.value.length
|
||||
})
|
||||
```
|
||||
|
||||
删除或停用 `handleConfirmMultiple`（若无其它引用）。
|
||||
|
||||
- [ ] **Step 3: `defineExpose` 增加合同产品 id 读取（供表单使用）**
|
||||
|
||||
```typescript
|
||||
defineExpose({
|
||||
openSelector,
|
||||
getContractProductIds: () =>
|
||||
collectContractProductIds(detailRows.value.flatMap((row) => row.products || []))
|
||||
})
|
||||
```
|
||||
|
||||
从 `@/utils/pl-plan-contract-product` 引入 `collectContractProductIds`。
|
||||
|
||||
- [ ] **Step 4: Commit**
|
||||
|
||||
```bash
|
||||
git add web-admin/src/components/business/pl-plan-contract-multi-select/index.vue
|
||||
git commit -m "$(cat <<'EOF'
|
||||
feat(web-admin): make plan stop contract selector single-choice
|
||||
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 6: `ProductSelector` 支持 `allowedProductIds`
|
||||
|
||||
**Files:**
|
||||
- Modify: `web-admin/src/components/business/product-selector/index.vue`
|
||||
|
||||
- [ ] **Step 1: 增加 prop**
|
||||
|
||||
```typescript
|
||||
const props = defineProps<{
|
||||
visible: boolean
|
||||
supplierId?: string | number
|
||||
/** 非空时仅允许选择这些 CRM 产品 id（运输计划按合同限制） */
|
||||
allowedProductIds?: string[]
|
||||
}>()
|
||||
```
|
||||
|
||||
- [ ] **Step 2: 列表加载后过滤；限制模式下隐藏「新增」**
|
||||
|
||||
在 `getList` 赋值 `productList` 之后：
|
||||
|
||||
```typescript
|
||||
let list = data.list || data.rows || []
|
||||
const allowed = (props.allowedProductIds || [])
|
||||
.map((id) => String(id).trim())
|
||||
.filter(Boolean)
|
||||
if (allowed.length) {
|
||||
const allowSet = new Set(allowed)
|
||||
list = list.filter((p: ProductVO) => allowSet.has(String(p.id)))
|
||||
}
|
||||
productList.value = list
|
||||
```
|
||||
|
||||
模板中「新增」按钮：
|
||||
|
||||
```vue
|
||||
<el-button
|
||||
v-if="!allowedProductIds?.length"
|
||||
class="btn-main"
|
||||
type="primary"
|
||||
@click="handleAddProduct"
|
||||
>
|
||||
```
|
||||
|
||||
（`allowedProductIds` 需在 script 中通过 `props.allowedProductIds` 暴露到模板，或 `const allowedProductIds = computed(() => props.allowedProductIds || [])`。）
|
||||
|
||||
当 `allowed.length > 0` 且过滤后为空：`ElMessage.warning('所选合同暂无产品明细')`（仅在打开时提示一次即可，避免刷屏）。
|
||||
|
||||
> 说明：合同产品通常远少于一页商品库结果；若联调发现合同产品因分页未出现在当前页，改为：有 `allowedProductIds` 时用 `fetchProductDetail` 逐个拉取组装列表（实现时优先保证正确性）。
|
||||
|
||||
- [ ] **Step 3: Commit**
|
||||
|
||||
```bash
|
||||
git add web-admin/src/components/business/product-selector/index.vue
|
||||
git commit -m "$(cat <<'EOF'
|
||||
feat(web-admin): allow ProductSelector to restrict by product ids
|
||||
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 7: 装货禁用添加 + 表单联动过滤与校验
|
||||
|
||||
**Files:**
|
||||
- Modify: `web-admin/src/components/business/pl-plan-load-section/index.vue`
|
||||
- Modify: `web-admin/src/components/business/pl-plan-form-dialog/index.vue`
|
||||
|
||||
- [ ] **Step 1: 装货「添加产品」禁用条件**
|
||||
|
||||
`pl-plan-load-section/index.vue`：
|
||||
|
||||
```vue
|
||||
<el-button
|
||||
v-if="!readonly"
|
||||
class="btn-main"
|
||||
type="primary"
|
||||
size="small"
|
||||
:disabled="addProductsDisabled"
|
||||
@click="handleAddProductsClick"
|
||||
>
|
||||
<el-icon><Plus /></el-icon>添加产品
|
||||
</el-button>
|
||||
```
|
||||
|
||||
```typescript
|
||||
const addProductsDisabled = computed(() => {
|
||||
if (isInternal.value) return false
|
||||
return !(props.modelValue.contracts || []).some((c) => String(c.contractId || '').trim())
|
||||
})
|
||||
|
||||
function handleAddProductsClick() {
|
||||
if (addProductsDisabled.value) {
|
||||
ElMessage.warning('请先选择装货合同后再添加产品')
|
||||
return
|
||||
}
|
||||
emit('add-products')
|
||||
}
|
||||
```
|
||||
|
||||
引入 `ElMessage`（若页面尚未导入）。
|
||||
|
||||
- [ ] **Step 2: 表单 `ProductSelector` 传入 allowedProductIds**
|
||||
|
||||
在 `pl-plan-form-dialog/index.vue`：
|
||||
|
||||
```typescript
|
||||
const loadContractProductIds = ref<string[]>([])
|
||||
|
||||
const productSelectorAllowedIds = computed(() => {
|
||||
if (isPlInternalCustomerName(loadForm.value.customerName)) return undefined
|
||||
return loadContractProductIds.value
|
||||
})
|
||||
```
|
||||
|
||||
模板：
|
||||
|
||||
```vue
|
||||
<ProductSelector
|
||||
:visible="productSelectorVisible"
|
||||
:allowed-product-ids="productSelectorAllowedIds"
|
||||
@update:visible="productSelectorVisible = $event"
|
||||
@confirm="handleProductConfirm"
|
||||
/>
|
||||
```
|
||||
|
||||
用 `ref` 拿到装货区 `PlPlanContractMultiSelect`（若当前未挂 ref，给 multi-select 加 `ref="loadContractSelectRef"`，或在合同 `v-model` 变更时 `getContract(id)` 拉取 products：
|
||||
|
||||
```typescript
|
||||
watch(
|
||||
() => loadForm.value.contracts,
|
||||
async (contracts, prev) => {
|
||||
const id = String(contracts?.[0]?.contractId || '').trim()
|
||||
const prevId = String(prev?.[0]?.contractId || '').trim()
|
||||
if (!id) {
|
||||
loadContractProductIds.value = []
|
||||
return
|
||||
}
|
||||
try {
|
||||
const res = await getContract(id)
|
||||
const detail = (res as any)?.data ?? res
|
||||
loadContractProductIds.value = collectContractProductIds(detail?.products || [])
|
||||
} catch {
|
||||
loadContractProductIds.value = []
|
||||
}
|
||||
// 合同变化时过滤装货产品（首次加载同 id 不刷）
|
||||
if (prev && id !== prevId) {
|
||||
const nextProducts = filterProductsByAllowedProductIds(
|
||||
loadForm.value.products || [],
|
||||
loadContractProductIds.value
|
||||
)
|
||||
loadForm.value = { ...loadForm.value, products: nextProducts }
|
||||
// 触发现有送货同步逻辑（若有 mirror/sync 函数则调用；无则依赖现有 watch）
|
||||
}
|
||||
},
|
||||
{ deep: true }
|
||||
)
|
||||
```
|
||||
|
||||
从 `@/api/crm/contract` 引入 `getContract`；从 `@/utils/pl-plan-contract-product` 引入两个 helper。若表单已有装货产品 mirror watch，过滤后确保调用现有 `mirrorPlanProductsFromLoad` / sync，避免送货残留合同外产品。
|
||||
|
||||
- [ ] **Step 3: 保存 / 安排前校验 `contracts.length > 1`**
|
||||
|
||||
在 `validateBusinessRules` 或单独函数中：
|
||||
|
||||
```typescript
|
||||
function validateSingleContractPerStop(): boolean {
|
||||
if (
|
||||
!isPlInternalCustomerName(loadForm.value.customerName) &&
|
||||
(loadForm.value.contracts || []).length > 1
|
||||
) {
|
||||
ElMessage.warning('装货合同只能保留 1 份，请移除多余合同后再保存')
|
||||
return false
|
||||
}
|
||||
for (let i = 0; i < deliveryForms.value.length; i += 1) {
|
||||
const row = deliveryForms.value[i]
|
||||
if (isPlInternalCustomerName(row.customerName)) continue
|
||||
if ((row.contracts || []).length > 1) {
|
||||
ElMessage.warning(`送货段#${i + 1}合同只能保留 1 份，请移除多余合同后再保存`)
|
||||
return false
|
||||
}
|
||||
}
|
||||
return true
|
||||
}
|
||||
```
|
||||
|
||||
在暂存/保存/安排运输提交路径中、现有 `validateBusinessRules` 之后调用；安排运输仍保留现有「至少 1 份」校验。
|
||||
|
||||
非内置且已选 1 份合同时，前端可用 `loadContractProductIds` 再校验装货产品（与后端一致）；失败文案：`装货产品须属于所选合同`。
|
||||
|
||||
- [ ] **Step 4: Commit**
|
||||
|
||||
```bash
|
||||
git add web-admin/src/components/business/pl-plan-load-section/index.vue \
|
||||
web-admin/src/components/business/pl-plan-form-dialog/index.vue
|
||||
git commit -m "$(cat <<'EOF'
|
||||
feat(web-admin): gate load products by selected contract
|
||||
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 8: 送货产品允许删除
|
||||
|
||||
**Files:**
|
||||
- Modify: `web-admin/src/components/business/pl-plan-delivery-section/index.vue`
|
||||
|
||||
- [ ] **Step 1: 打开删除**
|
||||
|
||||
将：
|
||||
|
||||
```vue
|
||||
<PlPlanStopProductTable
|
||||
:products="delivery.products"
|
||||
:editable="!readonly"
|
||||
:compact="compactProducts"
|
||||
:allow-remove="false"
|
||||
:shared-readonly="true"
|
||||
@remove="(productIndex) => removeStopProduct(index, productIndex)"
|
||||
/>
|
||||
```
|
||||
|
||||
改为：
|
||||
|
||||
```vue
|
||||
<PlPlanStopProductTable
|
||||
:products="delivery.products"
|
||||
:editable="!readonly"
|
||||
:compact="compactProducts"
|
||||
:allow-remove="!readonly"
|
||||
:shared-readonly="true"
|
||||
@remove="(productIndex) => removeStopProduct(index, productIndex)"
|
||||
/>
|
||||
```
|
||||
|
||||
确认 `removeStopProduct` 只改该送货段 `products`，不回写装货（现有实现应已满足）。
|
||||
|
||||
- [ ] **Step 2: Commit**
|
||||
|
||||
```bash
|
||||
git add web-admin/src/components/business/pl-plan-delivery-section/index.vue
|
||||
git commit -m "$(cat <<'EOF'
|
||||
feat(web-admin): allow removing products on delivery stops
|
||||
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 9: 合同完善页保存校验
|
||||
|
||||
**Files:**
|
||||
- Modify: `web-admin/src/views/pl/plan-contract/index.vue`
|
||||
|
||||
- [ ] **Step 1: 保存前最多 1 份**
|
||||
|
||||
在 `handleSaveStopContracts` 中，`contracts.length` 检查处改为：
|
||||
|
||||
```typescript
|
||||
if (!supplementDraft.contracts.length) {
|
||||
ElMessage.warning('请先选择合同')
|
||||
return
|
||||
}
|
||||
if (supplementDraft.contracts.length > 1) {
|
||||
ElMessage.warning('只能保留一份合同，请移除多余合同后再保存')
|
||||
return
|
||||
}
|
||||
```
|
||||
|
||||
（单选组件落地后正常不会 >1；历史数据打开弹窗仍可能 >1，故保留拦截。）
|
||||
|
||||
- [ ] **Step 2: Commit**
|
||||
|
||||
```bash
|
||||
git add web-admin/src/views/pl/plan-contract/index.vue
|
||||
git commit -m "$(cat <<'EOF'
|
||||
feat(web-admin): enforce single contract on plan-contract supplement save
|
||||
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 10: 联调验收与图谱更新
|
||||
|
||||
- [ ] **Step 1: 跑后端测试**
|
||||
|
||||
```bash
|
||||
cd backend && source venv/bin/activate && pytest tests/test_pl_plan_single_contract_rules.py tests/test_pl_plan_contract_gap.py tests/test_pl_plan_stop_service.py -v
|
||||
```
|
||||
|
||||
Expected: PASS
|
||||
|
||||
- [ ] **Step 2: 手工验收（对照 spec §8）**
|
||||
|
||||
- 非内置：合同单选；再选替换
|
||||
- 非内置未选合同：添加产品禁用
|
||||
- 非内置已选合同：只能勾选合同内产品
|
||||
- 换合同：仅移除不匹配装货行
|
||||
- 送货可删产品；「从装货同步」可补回
|
||||
- 历史多合同：提示 + 保存失败直到剩 1 份
|
||||
- 合同完善页同样最多 1 份
|
||||
- 内置客户：无合同、产品全量可选
|
||||
|
||||
- [ ] **Step 3: 更新知识图谱**
|
||||
|
||||
```bash
|
||||
./scripts/update-graph.sh all
|
||||
```
|
||||
|
||||
（若脚本仅支持 `backend|frontend|all`，按仓库实际参数执行。）
|
||||
|
||||
- [ ] **Step 4: 如有图谱文件变更可另提交；功能代码勿与无关 WIP 混提**
|
||||
|
||||
---
|
||||
|
||||
## Spec 覆盖自检
|
||||
|
||||
| Spec 要求 | Task |
|
||||
|-----------|------|
|
||||
| 非内置每段最多 1 份合同（前后端） | 1, 3, 5, 7, 9 |
|
||||
| 装货产品限合同内（前后端） | 2, 4, 6, 7 |
|
||||
| 内置不限产品、免合同 | 2（skip）、7（不传 allowed） |
|
||||
| 送货同步 + 可删 | 8 |
|
||||
| 换合同保留匹配行 | 4, 7 |
|
||||
| 历史多合同提示 + 保存强拦 | 5, 7, 9 |
|
||||
| 合同完善页 | 3, 5, 9 |
|
||||
| 不改 contracts[] 模型 / 不做送货独立添加 | 全计划未引入相反改动 |
|
||||
|
||||
无 TBD/TODO 占位；函数名 `assert_at_most_one_contract` / `assert_load_products_in_selected_contract` / `filterProductsByAllowedProductIds` 前后一致。
|
||||
Reference in new issue
Block a user