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

Tasks

1. Storage codec & schema

• 1.1 Add backend util to encode/decode package_spec (JSON array ↔ list[str], legacy scalar → one-element list) and unit-test round-trip + legacy cases
• 1.2 Widen crm_contract_product.package_spec (and quote product column if sharing codec) via SQL script + update docs/sql/shanxia2.0.sql; verify migration applies on local DB
• 1.3 Wire codec into contract_product CRUD _row_to_dict / create-update; expose packageSpecs (+ compat packageSpec); verify get/create/update with multi and legacy rows

2. Contract validation & quote bridge

• 2.1 On contract create/update, validate each line has ≥1 package, and same productId has no duplicate package across lines; verify API returns clear 4xx on violation
• 2.2 Map quote→contract _quote_products_to_contract_products so scalar quote package becomes one-element packageSpecs; verify create-from-quote still works
• 2.3 Update Pydantic ContractProductItem (and quote item if needed) for packageSpecs; run field-consistency check if applicable

3. Shared pool qty service (PL)

• 3.1 Refactor pl_contract_plan_qty matching: resolve contract line by productId + package ∈ line set; pool arranged = sum over all packages on that line; verify unit tests for shared remaining 715-10-10=695
• 3.2 Keep split-quota (two single-package lines) independent; extend/adjust test_pl_contract_plan_qty.py / arrange-check tests for both patterns
• 3.3 Update attach_plan_qty_fields_to_products to return line aggregates + per-package breakdown fields; verify contract detail payload shape
• 3.4 Update get_contract_product_arrange_qty_detail (+ API response) to return pool availableQty / contractQty and optional packageBreakdown; verify GET arrange-qty for either package on a shared line returns same remaining
• 3.5 Update assert_contract_qty_for_arrange / package-against-contract validation messages for pool semantics; verify arrange hard-block when pool exceeded
• 3.6 Annotate or supersede note on docs/superpowers/specs/2026-09-10-plan-product-package-key-design.md for multi-package shared lines

4. Contract web-admin UI

• 4.1 Contract form (ContractFormDialog / form.vue): packaging multi-select + client uniqueness checks; verify save of multi-package line and reject duplicate package across rows
• 4.2 Contract detail / list expand: nested or stacked per-package arranged columns + line-level quantity/remaining; verify shared-pool scenario display
• 4.3 Print / PDF paths in ContractDetailDialog / detail.vue: multi-package cell + {{packageSpecs}} aggregation; verify printed HTML shows both specs
• 4.4 Types in api/crm/contract for packageSpecs; smoke-check list/detail/form compile

5. Transport plan web-admin UI

• 5.1 Update pl-plan-contract-product.ts (and consumers) to read packageSpecs[] / decode legacy; verify packageSpecsForProduct lists all packages from multi lines
• 5.2 Plan form / stop product table: arrange-qty dialog copy uses pool remaining; verify selecting either package shows same remaining for a shared line
• 5.3 usePlContractToPlan / contract→plan mapping still sets single plan packageSpec; verify no regression on single-package contracts

6. Verification / docs sync

• 6.1 Run backend pytest for contract package codec + pl_contract_plan_qty / arrange-check / package-validate suites; fix failures
• 6.2 Manual checklist: create shared-pool contract → arrange two packages → detail breakdown + remaining → print; create split two-line contract → quotas independent
• 6.3 Run ./scripts/update-graph.sh for touched backend/frontend after code changes