2026-09-10-plan-product-package-key-design.md 6.9 KB

运输计划合同用量:按「产品 + 包装规格」唯一键

2026-09-23 补充:合同产品行现支持「一行多个包装规格 + 共享数量池」(见 OpenSpec crm-contract-multi-package-shared-qty)。

  • 一行一包装:行为仍等同下文复合键独立额度。
  • 一行多包装:额度按合同产品行共享;计划仍选单个包装,扣减计入该行池;详情按包装拆开展示已安排构成,剩余仅行级。
    下文「合同允许同一 product_id 多行、包装规格不同」仍然有效;多包装共享池是额外能力,不是替代。

日期: 2026-09-10
状态: 已确认(方案 1:复合键贯穿用量链路);多包装共享池见上述补充
关联: 2026-08-30-pl-plan-form-available-qty-design.md、2026-08-30-pl-plan-contract-qty-check-design.md、2026-08-30-crm-contract-plan-linkage-design.md
触发案例: 生产合同 AQFD-HT-[2025]309号,产品 SXWL007344(次氯酸钠)两行:25kg/桶 15 吨 vs 槽罐车 700 吨;现行按 product_id 聚合导致可安排量误用 15 吨。

背景

合同允许同一 product_id 多行、包装规格不同。运输计划装/送货段产品来自合同,但下列链路均以 product_id only 为键:

  • 可安排数量 API / 前端 cache
  • 安排运输硬拦(assert_contract_qty_for_arrange)
  • 合同详情产品列表「已归档数量 / 未归档已安排 / 已安排合计」挂量

同品多包装时会出现 last-wins / .first(),额度串行。

合同管理界面要求包装规格必填,故正常业务下合同行必有非空 packageSpec。

已确认决策

项 决策
唯一键 (productId + packageSpec),空值归一后比较
合同同品同包装两行 业务上不会出现;脏数据防御为数量相加
选品 UX 仍按产品选,再选包装(不改为按合同行 id 选品)
包装选项(绑合同) 仅本合同该产品已有包装,不用全局字典全量
包装必填(绑合同) 必填;合同侧本身也要求包装必填
无合同 / 内部客户 不强制合同包装;可继续字典下拉;无合同额度复合键硬拦
历史计划空包装 不批量刷库;再次保存/安排前须补选
数量硬拦时机 仍仅安排运输硬拦;保存可超合同量(仅警告);包装必填在保存即拦
合同详情三列 同迭代改后端挂量,按行复合键,前端列定义可不动
DB schema 不新增列、不加唯一索引

设计

1. 复合键与归一化

key = (product_id, normalize_package_spec(package_spec))

normalize_package_spec:

输入 结果
null / 缺失 ''
仅空白 ''
其它 strip() 后原文字符串(区分大小写与写法,如 25kg/桶 ≠ 25Kg/袋)

实现建议:map 内部用 tuple[str, str];或稳定拼接串(须保证 product_id 不含分隔歧义)。前后端归一规则必须一致。

2. 后端(真相源)

文件:backend/app/services/pl_contract_plan_qty.py

函数 / API 改动
accumulate_stop_products 按复合键累加;读取计划行 package_spec
merge_product_qty_maps key 改为复合键
aggregate_contract_product_plan_qtys 返回复合键 → 三数量
attach_plan_qty_fields_to_products 按行 productId + packageSpec 挂 archivedQty / arrangedUnarchivedQty / arrangedTotalQty
get_contract_product_arrange_qty_detail 入参增加 packageSpec;合同行按 product_id + 归一包装匹配,禁止裸 .first()
collect_plan_contract_qty_checks / assert_contract_qty_for_arrange 本计划量、已安排、合同 quantity 均按复合键;violation/reminder 带 packageSpec
GET .../contract-product-arrange-qty Query 增加 packageSpec;响应带回 packageSpec

计划 create/update:绑定合同时校验段产品 packageSpec 非空且属于该合同该产品包装集合;失败返回明确错误(与前端保存校验一致)。

不变: _bucket_for_plan、装/送范围、customer_demand 不硬拦数量、create/update 不硬拦合同数量超额。

测试:test_pl_contract_plan_qty.py、test_pl_contract_qty_arrange_check.py 覆盖同品异包装分桶与 309 类场景。

3. 前端(运输计划)

主路径:PlPlanFormDialog → 装/送货段 → PlPlanStopProductTable。

  1. 合同缓存:除 productId[] 外缓存合同产品行摘要(至少 productId、packageSpec、数量相关字段)。工具:utils/pl-plan-contract-product.ts 增补收集与 packageSpecsForProduct。
  2. 选品:ProductSelector 仍按去重 productId 限制。选中后若该产品合同侧仅一个包装可自动填入;多个则留空待选。
  3. 包装控件(绑合同):el-select options = 本合同该产品包装列表;换产品/合同时非法包装清空。无合同则保持字典 crm_product_gg。
  4. 可安排量:cacheKey 含归一后 packageSpec;请求 API 传 packageSpec;未选包装时不请求或提示先选包装。
  5. 保存校验:绑合同 → 包装必填且 ∈ 合同该产品包装集合。
  6. 提醒 / 弹窗:超限与可安排弹窗展示包装以区分行。
  7. 次要一致性(同迭代):findDeliveryProductsMissingFromLoad、matchPrevStopProduct 等按 productId + packageSpec 匹配。

合同详情 detail.vue / ContractDetailDialog.vue:列可不改,依赖后端挂量正确。

4. 数据流(概念)

合同明细行 (productId, packageSpec, quantity)
        │
        ├─► 计划选品:productId 限制 + 包装下拉来自合同行
        │
        ▼
计划装/送货行 (productId, packageSpec, planQty)
        │
        ▼
pl_contract_plan_qty 按 (productId, norm(packageSpec)) 聚合
        │
        ├─► 合同详情三列
        ├─► 可安排数量 API
        └─► 安排运输硬拦

验收用例

合同 AQFD-HT-[2025]309号,SXWL007344:

  1. 选产品后包装下拉仅 25kg/桶、槽罐车;不选包装不能保存。
  2. 选 槽罐车:可安排量按 700 吨额度,不被 15 吨占用。
  3. 选 25kg/桶:额度按 15 吨。
  4. 合同详情两行三列各自独立、不串量。
  5. 安排运输时两包装额度互不影响;超限文案含包装规格。

上线与回滚

  • 前后端同发;旧前端不传 packageSpec 视为空键(仅短窗口兼容)。
  • 无 schema 迁移;回滚恢复代码即可。
  • 不批量修复历史计划空包装。

非目标

  • 不改为 contractProductId 选品/绑行。
  • 不为合同表加 (product_id, package_spec) DB 唯一约束。
  • 不改变「保存可超合同量、安排再硬拦」的数量策略(包装必填除外)。
  • 不改装+送双边绑定的计数范围语义。