shanxia2.0/openspec/changes/pl-contract-line-qty-bind/tasks.md

Tasks

1. Schema and contract uniqueness

• 1.1 Add nullable contract_id and contract_product_id to pl_plan_load_product and pl_plan_delivery_product (models, docs/sql/, migration script) and verify SQLAlchemy metadata and DDL comments match
• 1.2 Remove same-product package uniqueness in _validate_contract_product_package_specs and validateContractProductPackageSpecs while keeping ≥1 spec per line; verify a unit/frontend-equivalent test saves two lines with the same product and package
• 1.3 Update or drop tests in crm-contract-multi-package-shared-qty that require global package uniqueness; verify remaining shared-pool tests still pass

2. Occupancy by contract product line

• 2.1 Change pl_contract_plan_qty.py aggregation and match to prefer contract_product_id, with product+package fallback only when id is missing; verify tests that two same-package lines do not share remaining
• 2.2 Extend arrange-qty API to accept contractProductId and return that line's pool remaining; verify query with two duplicate-package lines returns distinct remaining
• 2.3 Update arrange hard-check to name the overflowing contract line and never apply excess to a sibling line; verify assert_contract_qty (or equivalent) tests

3. Plan stop multi-contract and product write

• 3.1 Relax assert_at_most_one_contract for load/delivery (keep or parameterize supplier/demander); verify test_pl_plan_single_contract_rules.py allows two load/delivery contracts and still rejects missing contract on external stops
• 3.2 Persist stop product contractId/contractProductId on create/update and validate product+package against that line and stop contract set; verify API save round-trip
• 3.3 Union allowed products/packages across selected contracts; verify a stop product from contract B is accepted when A and B are both linked

4. Web-admin contract and plan UI

• 4.1 Allow duplicate package rows in ContractFormDialog (and form.vue if still used); verify save no longer toasts 「同一产品的包装规格不能重复」
• 4.2 Allow multiple contracts on load/delivery in PlPlanFormDialog; replace add-product with contract-line picker (contract no, package, price, remaining); verify two rows of the same SKU can be added
• 4.3 Keep save-draft without remaining hard-block; show remaining warning styling if target exceeds remaining; verify arrange still blocked via existing arrange flow

5. Archive and contract detail

• 5.1 Archive form keeps one actual field per bound stop row, defaults to target qty, requires sum = weighbridge/IO total when present; verify mismatch cannot submit
• 5.2 On formal archive, over-remaining rows are highlighted, dialog lists line identity and excess, submit requires confirmOverage; verify without flag 422 and with flag posts only to named lines
• 5.3 Contract detail remaining uses line id; negative remaining displays as 超交; verify two same-package lines show independent archived/remaining
• 5.4 Archive draft warns but does not require overage confirm; verify draft save succeeds with warning

6. Driver/site and regression

• 6.1 Confirm driver/site payloads or UI still show product+qty without requiring contract selection; if multiple bound rows share SKU, quantity is summed; verify no new contract fields on those screens
• 6.2 Run backend occupancy/plan-contract tests and python scripts/check_field_consistency.py for touched entities; verify CI-relevant tests pass
• 6.3 Point implementers at docs/superpowers/demos/2026-10-05-contract-plan-line-qty-demo.html for UI parity (picker, overage dialog, driver card)