From 3e6ae41e4bf5efa591d1e8260269715e2979a79f Mon Sep 17 00:00:00 2001 From: wuzilong <704541015@qq.com> Date: Thu, 10 Sep 2026 17:50:13 +0800 Subject: [PATCH] docs: add implementation plan for plan product+package qty key. Co-authored-by: Cursor --- .../2026-09-10-plan-product-package-key.md | 612 ++++++++++++++++++ 1 file changed, 612 insertions(+) create mode 100644 docs/superpowers/plans/2026-09-10-plan-product-package-key.md diff --git a/docs/superpowers/plans/2026-09-10-plan-product-package-key.md b/docs/superpowers/plans/2026-09-10-plan-product-package-key.md new file mode 100644 index 000000000..4e3a106dc --- /dev/null +++ b/docs/superpowers/plans/2026-09-10-plan-product-package-key.md @@ -0,0 +1,612 @@ +# 运输计划合同用量按「产品+包装」唯一键 — 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:** 合同用量统计、可安排量、安排硬拦与合同详情三列改为按 `(productId, packageSpec)` 分桶；绑合同时计划行包装必填且选项仅来自合同。 + +**Architecture:** 在 `pl_contract_plan_qty.py` 引入归一化与复合键，所有累加/挂量/校验统一换键；API `contract-product-arrange-qty` 增加 `packageSpec`；前端缓存合同行摘要、包装下拉与 cacheKey/保存校验对齐。无 DB 迁移。 + +**Tech Stack:** FastAPI / SQLAlchemy / pytest；Vue 3 + Element Plus（web-admin） + +**Spec:** `docs/superpowers/specs/2026-09-10-plan-product-package-key-design.md` + +--- + +## File map + +| 文件 | 职责 | +|------|------| +| `backend/app/services/pl_contract_plan_qty.py` | 复合键、聚合、挂量、可安排量、硬拦 | +| `backend/app/api/pl/plan.py` | arrange-qty Query 透传 `packageSpec`；create/update 调包装校验 | +| `backend/app/services/pl_plan_stop_service.py` 或新建小 helper | 绑合同段产品包装必填校验（可放 qty 服务旁） | +| `backend/tests/test_pl_contract_plan_qty.py` | 聚合/挂量复合键单测 | +| `backend/tests/test_pl_contract_qty_arrange_check.py` | 必要时扩展；主要改 plan_qty 侧集成式纯函数测 | +| `web-admin/src/utils/pl-plan-contract-product.ts` | 合同行收集、包装列表、归一化、缺货比对 | +| `web-admin/src/api/pl/index.ts` | arrange-qty / reminder 类型 | +| `web-admin/src/components/business/pl-plan-stop-product-table/index.vue` | 包装下拉、cacheKey、请求 | +| `web-admin/src/components/business/pl-plan-form-dialog/index.vue` | 合同行缓存、选品自动填包装、保存校验 | +| `web-admin/src/utils/pl-plan-stop-form.ts` | `matchPrevStopProduct` 带包装 | +| `web-admin/src/utils/pl-contract-qty-reminder.ts` | 展示包装 | +| `web-admin/src/components/business/pl-contract-product-arrange-qty-dialog/*` | 若有：传 packageSpec | + +--- + +### Task 1: 后端复合键工具 + 更新累加/合并 + 单测 + +**Files:** +- Modify: `backend/app/services/pl_contract_plan_qty.py` +- Modify: `backend/tests/test_pl_contract_plan_qty.py` + +- [ ] **Step 1: 在测试中增加复合键用例（先写失败断言）** + +在 `test_pl_contract_plan_qty.py` 顶部 import 增加 `normalize_package_spec`, `product_package_key`, `attach_plan_qty_fields_to_products`。 + +追加： + +```python +def test_normalize_package_spec(): + from app.services.pl_contract_plan_qty import normalize_package_spec + assert normalize_package_spec(None) == "" + assert normalize_package_spec(" ") == "" + assert normalize_package_spec(" 槽罐车 ") == "槽罐车" + assert normalize_package_spec("25kg/桶") != normalize_package_spec("25Kg/袋") + + +def test_accumulate_splits_same_product_different_package(): + acc = defaultdict(float) + accumulate_stop_products( + acc, + [ + SimpleNamespace(product_id="SXWL007344", package_spec="25kg/桶", plan_qty=15), + SimpleNamespace(product_id="SXWL007344", package_spec="槽罐车", plan_qty=700), + SimpleNamespace(product_id="SXWL007344", package_spec=" 槽罐车 ", plan_qty=10), + ], + ) + k_bucket = ("SXWL007344", "25kg/桶") + k_tank = ("SXWL007344", "槽罐车") + assert acc[k_bucket] == 15.0 + assert acc[k_tank] == 710.0 + + +def test_merge_product_qty_maps_composite_keys(): + out = merge_product_qty_maps( + archived={("p1", "A"): 10.0}, + arranged_unarchived={("p1", "B"): 20.0, ("p1", "A"): 5.0}, + ) + assert out[("p1", "A")]["arrangedTotalQty"] == 15.0 + assert out[("p1", "B")]["arrangedTotalQty"] == 20.0 + + +def test_attach_plan_qty_fields_matches_package(): + qty_map = { + ("pid1", "25kg/桶"): { + "archivedQty": 1.0, + "arrangedUnarchivedQty": 2.0, + "arrangedTotalQty": 3.0, + }, + ("pid1", "槽罐车"): { + "archivedQty": 10.0, + "arrangedUnarchivedQty": 20.0, + "arrangedTotalQty": 30.0, + }, + } + products = [ + {"productId": "pid1", "packageSpec": "25kg/桶"}, + {"productId": "pid1", "packageSpec": "槽罐车"}, + ] + attach_plan_qty_fields_to_products(products, qty_map) + assert products[0]["arrangedTotalQty"] == 3.0 + assert products[1]["arrangedTotalQty"] == 30.0 +``` + +同时把**既有**依赖裸 `product_id` 键的测试改为复合键：无 `package_spec` 时键为 `(pid, "")`。例如： + +```python +# test_accumulate_stop_products 期望 +assert acc[("p1", "")] == 20.0 + +# test_sum_qtys_explicit_delivery_stop_only 等 +assert qtys == {("p1", ""): 40.0} +``` + +所有 `SimpleNamespace(product_id=...)` 行可不显式加 `package_spec`（实现用 getattr 默认空）。 + +- [ ] **Step 2: 跑测确认失败** + +```bash +cd backend && source venv/bin/activate && pytest tests/test_pl_contract_plan_qty.py -v +``` + +Expected: FAIL（`normalize_package_spec` 未定义或键仍为 str） + +- [ ] **Step 3: 实现工具与累加/合并/挂量** + +在 `pl_contract_plan_qty.py` 顶部 typing 增加 `Tuple`。 + +```python +ProductPackageKey = Tuple[str, str] + + +def normalize_package_spec(value: Any) -> str: + if value is None: + return "" + return str(value).strip() + + +def product_package_key(product_id: Any, package_spec: Any = None) -> Optional[ProductPackageKey]: + pid = str(product_id or "").strip() + if not pid: + return None + return (pid, normalize_package_spec(package_spec)) +``` + +改 `merge_product_qty_maps`：参数/返回键改为 `ProductPackageKey`（dict key 为 tuple）。 + +改 `accumulate_stop_products`： + +```python +key = product_package_key( + getattr(row, "product_id", None), + getattr(row, "package_spec", None), +) +if not key: + continue +... +target[key] += qty +``` + +改 `attach_plan_qty_fields_to_products`： + +```python +key = product_package_key(item.get("productId"), item.get("packageSpec") or item.get("package_spec")) +stats = (qty_by_product_id.get(key) if key else None) or { + "archivedQty": 0.0, + "arrangedUnarchivedQty": 0.0, + "arrangedTotalQty": 0.0, +} +``` + +（参数名可保留 `qty_by_product_id` 或改名为 `qty_by_key`，调用处一并改。） + +`aggregate_contract_product_plan_qtys` 返回类型自然变为复合键 dict（`archived`/`arranged_unarchived` 已是 defaultdict）。 + +- [ ] **Step 4: 跑测通过** + +```bash +pytest tests/test_pl_contract_plan_qty.py -v +``` + +Expected: PASS + +- [ ] **Step 5: Commit** + +```bash +git add backend/app/services/pl_contract_plan_qty.py backend/tests/test_pl_contract_plan_qty.py +git commit -m "feat(pl): key contract plan qty by product and package spec" +``` + +--- + +### Task 2: 可安排量 API + 硬拦按复合键 + +**Files:** +- Modify: `backend/app/services/pl_contract_plan_qty.py`（`get_contract_product_arrange_qty_detail`、`collect_plan_contract_qty_checks`） +- Modify: `backend/app/api/pl/plan.py`（Query `packageSpec`） +- Modify: `backend/tests/test_pl_contract_plan_qty.py`（纯函数级：可测合同行匹配 helper，或在同文件加小测） + +- [ ] **Step 1: 抽出合同行匹配辅助并单测** + +```python +def match_contract_product_for_key( + products: Iterable[Any], + key: ProductPackageKey, +) -> Optional[Any]: + """同键多行时 quantity 相加的合成对象可选；业务约定唯一，取第一行并防御求和。""" + pid, pkg = key + matched = [] + for p in products or []: + k = product_package_key(getattr(p, "product_id", None), getattr(p, "package_spec", None)) + if k == key: + matched.append(p) + if not matched: + return None + if len(matched) == 1: + return matched[0] + # 防御：合并 quantity 到第一个的 SimpleNamespace 副本或改写 quantity + total_qty = sum(_to_float(getattr(p, "quantity", None)) for p in matched) + first = matched[0] + first.quantity = total_qty # 仅当 ORM 对象可写；否则用 SimpleNamespace 拷贝字段 + return first +``` + +单测：两行同 pid 不同包装，按包装取到对应 quantity（15 vs 700）。 + +- [ ] **Step 2: 改 `get_contract_product_arrange_qty_detail`** + +签名增加 `package_spec: Optional[str] = None`。 + +- empty 响应增加 `"packageSpec": normalize_package_spec(package_spec)` +- 查合同行：先 `filter(product_id==pid, del_flag==0)` 拉列表，再用 `match_contract_product_for_key(..., product_package_key(pid, package_spec))` +- `qty_map.get(key)` 取 arranged +- 列计划明细时过滤/展示同一 key（若现有 plans 列表按 product 过滤，改为复合键） + +- [ ] **Step 3: 改 API** + +`plan.py`： + +```python +package_spec: Optional[str] = Query(default=None, alias="packageSpec"), +... +return get_contract_product_arrange_qty_detail( + ..., + product_id=product_id, + package_spec=package_spec, + exclude_plan_id=exclude_plan_id, +) +``` + +- [ ] **Step 4: 改 `collect_plan_contract_qty_checks`** + +- `products_by_key = { product_package_key(p.product_id, p.package_spec): p for p in products if product_package_key(...) }` + （同键多行先用 match helper 建 map） +- `for key, new_qty_raw in plan_qtys.items():` 解包 `pid, pkg = key` +- item 增加 `"packageSpec": pkg or None` +- `qty_map.get(key)` + +- [ ] **Step 5: 跑测** + +```bash +pytest tests/test_pl_contract_plan_qty.py tests/test_pl_contract_qty_arrange_check.py -v +``` + +Expected: PASS（evaluate_* 纯函数无需改签名） + +- [ ] **Step 6: Commit** + +```bash +git add backend/app/services/pl_contract_plan_qty.py backend/app/api/pl/plan.py backend/tests/test_pl_contract_plan_qty.py +git commit -m "feat(pl): arrange-qty and overflow checks use product+package key" +``` + +--- + +### Task 3: 计划保存时包装必填（绑合同） + +**Files:** +- Create or Modify: `backend/app/services/pl_contract_plan_qty.py` 增加 `assert_plan_products_package_spec_for_contracts` + 或 `backend/app/services/pl_plan_package_validate.py` +- Modify: `backend/app/api/pl/plan.py`（`create-full` / `update` 在写库前调用） +- Create: `backend/tests/test_pl_plan_package_validate.py` + +- [ ] **Step 1: 写失败单测（纯函数，传入合同产品行 + 计划段产品）** + +```python +def test_require_package_when_contract_bound(): + from app.services.pl_contract_plan_qty import validate_stop_products_package_against_contract + + contract_products = [ + SimpleNamespace(product_id="p1", package_spec="25kg/桶"), + SimpleNamespace(product_id="p1", package_spec="槽罐车"), + ] + ok, err = validate_stop_products_package_against_contract( + contract_products=contract_products, + stop_products=[SimpleNamespace(product_id="p1", package_spec="")], + ) + assert ok is False + assert "包装" in (err or "") + +def test_package_must_be_in_contract_set(): + ... + stop_products=[SimpleNamespace(product_id="p1", package_spec="吨桶")] + assert ok is False + +def test_valid_package_passes(): + ... + stop_products=[SimpleNamespace(product_id="p1", package_spec="槽罐车")] + assert ok is True +``` + +规则（与 spec 一致）： +- 仅校验「出现在合同产品集合中的 productId」 +- 该 productId 在合同上的包装集合（归一后）非空 → 计划行必须非空且 ∈ 集合 +- 计划产品不在合同明细：跳过（归属另有规则） + +- [ ] **Step 2: 实现 `validate_stop_products_package_against_contract` + 在 create-full/update 对每个绑定合同的装/送货段产品调用；失败 `HTTPException 422`** + +定位：`create_full` 在 `validate_create_full` 之后、持久化之前；`update` 对称位置。若段产品嵌在 payload.loads/deliveries，遍历 `products`。 + +- [ ] **Step 3: 跑测并 Commit** + +```bash +pytest tests/test_pl_plan_package_validate.py -v +git add ... && git commit -m "feat(pl): require contract package spec on plan save" +``` + +--- + +### Task 4: 前端工具函数 + +**Files:** +- Modify: `web-admin/src/utils/pl-plan-contract-product.ts` +- 可选 Create: `web-admin/src/utils/pl-plan-contract-product.spec.ts`（若项目已有 vitest；无则跳过单测，手工验） + +- [ ] **Step 1: 增加类型与函数** + +```typescript +export type ContractProductRowLite = { + productId?: string | null + packageSpec?: string | null + productName?: string | null + productNo?: string | null + quantity?: number | null + quantityMode?: string | null +} + +export function normalizePackageSpec(value?: string | null): string { + return String(value ?? '').trim() +} + +export function productPackageKey( + productId?: string | null, + packageSpec?: string | null +): string { + const pid = String(productId || '').trim() + if (!pid) return '' + return `${pid}\0${normalizePackageSpec(packageSpec)}` +} + +export function collectContractProductRows( + products?: ContractProductRowLite[] | null +): ContractProductRowLite[] { + return (products || []) + .map((row) => ({ + productId: String(row?.productId || '').trim(), + packageSpec: normalizePackageSpec(row?.packageSpec), + productName: row?.productName, + productNo: row?.productNo, + quantity: row?.quantity, + quantityMode: row?.quantityMode + })) + .filter((row) => row.productId) +} + +/** 本合同该产品的包装列表（去重，保序）；过滤空串 */ +export function packageSpecsForProduct( + rows: ContractProductRowLite[], + productId: string +): string[] { + const pid = String(productId || '').trim() + const out: string[] = [] + const seen = new Set() + for (const row of rows || []) { + if (String(row.productId || '').trim() !== pid) continue + const pkg = normalizePackageSpec(row.packageSpec) + if (!pkg || seen.has(pkg)) continue + seen.add(pkg) + out.push(pkg) + } + return out +} + +export function isPackageAllowedForContractProduct( + rows: ContractProductRowLite[], + productId: string, + packageSpec?: string | null +): boolean { + const allowed = packageSpecsForProduct(rows, productId) + if (!allowed.length) return true // 无合同包装行：不在此强制（后端/脏数据） + return allowed.includes(normalizePackageSpec(packageSpec)) +} +``` + +保留 `collectContractProductIds`（可由 rows 派生）。 + +改 `findDeliveryProductsMissingFromLoad`：用 `productPackageKey` 比对；展示名建议 `` `${name}（${pkg || '无包装'}）` ``。 + +- [ ] **Step 2: Commit** + +```bash +git add web-admin/src/utils/pl-plan-contract-product.ts +git commit -m "feat(web-admin): add contract product package helper utils" +``` + +--- + +### Task 5: 前端 API 类型与 arrange-qty 传参 + +**Files:** +- Modify: `web-admin/src/api/pl/index.ts` +- Modify: `web-admin/src/components/business/pl-contract-product-arrange-qty-dialog/index.vue`（若存在） +- Modify: `web-admin/src/utils/pl-contract-qty-reminder.ts` + +- [ ] **Step 1: 扩展类型** + +```typescript +export interface ContractProductArrangeQtyDetail { + ... + packageSpec?: string | null +} + +getContractProductArrangeQty: (params: { + contractId: string + productId: string + packageSpec?: string + excludePlanId?: string +}) => ... + +export interface ContractQtyReminderItem { + ... + packageSpec?: string | null +} +``` + +- [ ] **Step 2: reminder 文案带包装** + +在 `pl-contract-qty-reminder.ts` 产品名后追加包装（有值时）：`` `${productName}（${packageSpec}）` ``。 + +- [ ] **Step 3: Commit** + +```bash +git commit -m "feat(web-admin): pass packageSpec on arrange-qty API types" +``` + +--- + +### Task 6: 段产品表 — 包装下拉 + 可安排量 cacheKey + +**Files:** +- Modify: `web-admin/src/components/business/pl-plan-stop-product-table/index.vue` +- 检查 `PlPlanFormProductTable.vue` 是否仍用于主路径；主路径以 stop-product-table 为准，旧表若仍展示包装则同步。 + +- [ ] **Step 1: Props 增加合同行** + +```typescript +contractProductRows?: ContractProductRowLite[] +``` + +父组件传入 Task 4 缓存的 rows。 + +- [ ] **Step 2: 绑合同时包装列改 el-select** + +```vue + + + + +``` + +`packageOptionsFor(row) => packageSpecsForProduct(props.contractProductRows || [], row.productId)` + +- [ ] **Step 3: cacheKey / ensureArrangeQty** + +```typescript +function cacheKey(productId: string, packageSpec?: string | null) { + return `${props.contractId}::${productId}::${normalizePackageSpec(packageSpec)}::${excludePlanId || ''}` +} + +// ensureArrangeQty：若有合同且 packageSpecsForProduct 非空且行上包装为空 → 不请求，available 显示提示 +await planApi.getContractProductArrangeQty({ + contractId, + productId: pid, + packageSpec: normalizePackageSpec(row.packageSpec), + excludePlanId +}) +``` + +包装变更时清 cache 并重新拉取。弹窗 props 增加 `packageSpec`。 + +- [ ] **Step 4: Commit** + +```bash +git commit -m "feat(web-admin): plan stop products select package from contract" +``` + +--- + +### Task 7: 计划表单 — 缓存、选品、保存校验、匹配 + +**Files:** +- Modify: `web-admin/src/components/business/pl-plan-form-dialog/index.vue` +- Modify: `web-admin/src/utils/pl-plan-stop-form.ts` +- Modify: `web-admin/src/components/business/pl-plan-delivery-section/index.vue`（缺货提醒若需） + +- [ ] **Step 1: 合同缓存** + +将 `contractProductIdsCache` 扩展为同时存 `ContractProductRowLite[]`（或并行 `contractProductRowsCache`）。`fetchContractProductIds` 改为拉详情后 `collectContractProductRows` + ids。 + +向 `PlPlanLoadSection` / `PlPlanDeliverySection` / `PlPlanStopProductTable` 传入 `contract-product-rows`。 + +- [ ] **Step 2: 选品确认** + +`handleProductConfirm`：不要再无脑 `packageSpec: ''` 后结束；若 `packageSpecsForProduct(rows, id).length === 1`，自动填入该包装；多个则 `''` 待选。 + +- [ ] **Step 3: 保存校验** + +在 `validateSingleContractPerStop` 之后： + +```typescript +function validateContractPackageSpecs(): boolean { + // 遍历装/送货段：有 contractId 且该产品 packageSpecs 非空 → 必填且 in 列表 + // ElMessage.error(`请选择包装规格：${productName}`) +} +``` + +`submit` 路径调用；失败 return。 + +- [ ] **Step 4: `matchPrevStopProduct`** + +在 `pl-plan-stop-form.ts`：`byProductId` 改为先匹配 `productId + normalizePackageSpec(packageSpec)`，再回退仅 productId（兼容旧空包装行）。 + +- [ ] **Step 5: Commit** + +```bash +git commit -m "feat(web-admin): enforce package spec on plan form save" +``` + +--- + +### Task 8: 验收与图谱 + +- [ ] **Step 1: 后端全量相关测** + +```bash +cd backend && source venv/bin/activate +pytest tests/test_pl_contract_plan_qty.py tests/test_pl_contract_qty_arrange_check.py tests/test_pl_plan_package_validate.py -v +``` + +- [ ] **Step 2: 前端类型检查（按需）** + +```bash +cd web-admin && pnpm exec vue-tsc --noEmit 2>&1 | head -50 +``` + +- [ ] **Step 3: 手工验收清单（对照生产 309 逻辑，可用本地/测试合同造数）** + +1. 同 productId 两包装：下拉仅两选项；不选不能保存 +2. 选槽罐车：可安排量按大额度 +3. 选 25kg/桶：按小额度 +4. 合同详情两行三列不串量 +5. 安排运输超限文案含包装 + +- [ ] **Step 4: 更新 graphify** + +```bash +./scripts/update-graph.sh all +# 或分别 backend / frontend +``` + +- [ ] **Step 5: 最终 commit（若有 graph/文档微调）** + +```bash +git commit -m "chore: update graphify after plan product package key" +``` + +--- + +## Spec coverage checklist + +| Spec 项 | Task | +|---------|------| +| 复合键 + 归一化 | Task 1 | +| 聚合 / 合同详情三列挂量 | Task 1（attach） | +| 可安排量 API | Task 2 | +| 安排硬拦 + reminder packageSpec | Task 2 + Task 5 | +| 保存包装必填 | Task 3 + Task 7 | +| 选品仍按产品 + 合同包装下拉 | Task 6–7 | +| 缺货/段匹配带包装 | Task 4 + Task 7 | +| 无 schema / 不刷历史 | 全程遵守 | +| 309 验收 | Task 8 | + +## Self-review notes + +- 键类型：后端用 `Tuple[str,str]`；前端 cache 用 `` `${pid}\0${pkg}` `` 字符串，勿混用未归一的 raw。 +- 既有单测凡断言 `{"p1": n}` 必须改为 `{("p1",""): n}`，否则 Task 1 绿测假象。 +- `products_by_pid` last-wins 必须删除，改为 `products_by_key` / match helper。 +- 旧前端不传 `packageSpec` ≈ 空键：仅兼容窗口；正式前端绑合同必传非空包装。