shanxia2.0/openspec/changes/crm-contract-multi-package-shared-qty/proposal.md

Proposal

Why

合同录入时，客户希望同一产品行可勾选多个包装规格，并用一个数量作为这些包装的共享额度；运输计划无论安排其中哪种包装，都从该行总量扣减。现行模型一行仅一个 packageSpec，额度按 (productId, packageSpec) 分桶，无法表达「一行多包装、共享数量池」，也无法在详情中按包装拆开展示已安排构成。

What Changes

• 合同产品明细：包装规格改为多选（至少选 1 个）；同品仍可多行；同一合同同一产品下包装规格全局不重复
• 行上仍填一个数量：该行所有包装共享此额度（例：[25kg/桶, 槽罐车] × 715；两种各安排 10 → 已安排合计 20，剩余 695）
• 合同详情 / 列表展开：包装维度拆开展示已归档 / 未归档已安排 / 已安排；剩余与合同数量仅挂在行合计
• 打印 / PDF：产品表与 {{packageSpecs}} 聚合适配多包装
• 运输计划：选包装白名单来自行内集合；可安排量 / 安排硬拦 / 详情挂量改为按合同产品行共享池扣减（BREAKING 相对现行「按包装分桶」——仅对「一行多包装」的新数据；一行一包装行为与旧分额度兼容）
• 报价转合同：对称支持多包装字段映射（若报价暂未多选，则单值映射为单元素列表）

Capabilities

New Capabilities

• contract-multi-package-shared-qty: 合同产品行多包装共享数量池；详情按包装拆开展示已安排；运输计划可安排量与硬拦按行池扣减

Modified Capabilities

• （无基线 openspec/specs/ 可 delta；本变更以新 capability 为准。落地后废止/覆盖 docs/superpowers/specs/2026-09-10-plan-product-package-key-design.md 中「一行一包装、按包装独立额度」对多包装行的假定。）

Impact

• 后端：crm_contract_product.package_spec 存储形态与读写；schemas/crud 合同产品；pl_contract_plan_qty.py 匹配/聚合/硬拦/arrange-qty；合同详情挂量；计划 create/update 包装校验；报价→合同映射
• 前端：合同表单 DictSelect 多选与去重校验；详情/列表嵌套或子行展示；打印 HTML；pl-plan-contract-product / 计划表单可安排量文案；可选报价表单对齐
• 数据库：扩列或约定序列化（见 design）；需同步 docs/sql/
• 测试：合同保存唯一性、共享池剩余、同品分行分额度仍可用、详情拆分展示、打印聚合