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

Design

Context

See proposal.md for motivation. Current constraints that shape the approach:

• Contract uniqueness is application-level (validateContractProductPackageSpecs / _validate_contract_product_package_specs), not a DB unique index.
• pl_plan_contract already stores N contracts per stop/side; assert_at_most_one_contract and frontend validateSingleContractPerStop cap it at 1.
• Stop products (pl_plan_load_product, pl_plan_delivery_product) have product_id + package_spec + plan_qty / inbound|outbound actuals, no contract_product_id.
• Occupancy in pl_contract_plan_qty.py matches by product + package membership so uniqueness can uniquely identify a line. Dirty duplicates are summed.
• Occupancy buckets already use plan qty for unarchived-arranged and archive actuals for archived (QTY_MODE_PLAN / QTY_MODE_ARCHIVE_ACTUAL).
• UI mock: docs/superpowers/demos/2026-10-05-contract-plan-line-qty-demo.html.

Goals / Non-Goals

Goals:

• Persist stop-product → contract-line binding and key all occupancy on that id.
• Lift the one-contract-per-stop cap with same-customer validation.
• Keep existing plan-qty vs archive-actual field split; add over-delivery confirm only on formal archive.
• Leave driver/site UX product-centric.

Non-Goals:

• Plan-time single physical row with archive-only allocation (方案乙).
• Auto-splitting a weighbridge total by ratio.
• Replacing crm_contract_product_price_tier (date-based price on one line remains).
• Changing driver/site to select contracts.
• Migrating historical plans onto line ids (fallback match only).

Decisions

1. Occupancy key = contract_product_id

Choice	Rationale
Adopted: Bind and aggregate by contract product line id	Duplicate product+package is otherwise unresolvable
Rejected: Keep (productId, packageSpec) uniqueness	Contradicts price-split lines
Rejected: Sum duplicates (current dirty-data path)	Cannot split 10 vs 20 on two lines

Arrange-qty API MUST accept contractProductId (keep product+package as fallback for old clients / history).

2. Schema: columns on stop product tables

Add nullable contract_id, contract_product_id to pl_plan_load_product and pl_plan_delivery_product. Prefer also storing snapshot contract_no only if list/print needs it without join; otherwise join pl_plan_contract + CRM.

Do not encode allocation as a child table of one physical product row: planner already splits rows.

pl_plan_product remains the plan-level product rollup (same product may still be one rollup row for vehicle/certs). Stop-level rows carry the binding. If current code requires 1:1 plan_product_id per stop row of the same product, keep sharing one pl_plan_product for identical product+package or clone plan_product rows per binding—prefer share one plan_product when product+package match so driver/certs stay one SKU, and put binding only on stop products.

3. Multi-contract: remove at-most-one, keep same customer

Remove assert_at_most_one_contract for load/delivery (and supplier/demander only if those UIs must also multi-select; default this change: load + delivery only; supplier/demander stay 1 unless the same form already reuses the helper—if the helper is shared, split load/delivery from supplier/demander or add a max_count argument).

Product whitelist = union of selected contracts' lines. Each stop product's contract_id MUST be one of the stop's linked contracts.

4. Picker = contract lines

Frontend add-product opens lines from selected contracts: contract no, product name, package (if multi-package line, pick one package for the stop row), price, remaining. Do not open a “split dialog after picking SKU” as the primary path (supersedes 2026-09-29 demo).

Optional later: picking a SKU that hits multiple lines could pre-open those lines; v1 is explicit line pick.

5. Validation split

Gate	Rule
Contract save	Duplicate package allowed
Plan save	Package ∈ bound line; product matches; contract on stop; no remaining hard-block
Arrange	Remaining hard-block per contractProductId
Archive draft	Warn over remaining; persist
Archive submit	Actuals sum = vehicle/IO total when present; over remaining → confirm then post to that line

Confirmation is a dedicated archive request flag or two-step API (confirmOverage: true) so a plain retry cannot skip the dialog.

Negative remaining is stored as archived > contract qty; UI shows 超交. Subsequent arrange against that line treats remaining ≤ 0 as hard-block.

6. Driver / site aggregation

Existing driver/site APIs that list stop products by product+package SHOULD continue to show one card with summed qty when multiple bound rows share product+package. Do not add contract fields to those payloads unless already present; if present, omit from UI.

Risks / Trade-offs

Risk	Mitigation
Historical plans lack line id	Fallback match; new writes require id when contracts selected
Sharing one pl_plan_product vs cloning	Certs/hazard stay on SKU; occupancy never uses plan_product id
User confirms huge over-delivery	Dialog lists excess; audit log of confirm
crm-contract-multi-package-shared-qty uniqueness tests	Update those tests in the same implementation wave
Arrange helper used for supplier contracts	Parameterize max-one vs multi

Migration Plan

1. Add nullable columns; deploy backend that writes ids when provided and occupancy prefers id.
2. Deploy frontend plan/contract/archive together.
3. Rollback: occupancy can still sum by package if ids absent; do not re-enable uniqueness until UI rolled back.

Open Questions

• Whether load and delivery must always have the same set of bound lines after “sync from load” (keep current optional sync button; not required equal).