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

Spec Delta

Purpose

Enable a contract product line to carry multiple package specifications that share one quantity pool, while transport-plan arrange checks and contract detail arranged-qty displays consume and present that pool correctly (with per-package consumption breakdown).

ADDED Requirements

Requirement: Contract product line supports multiple package specs with one quantity

The system SHALL allow each contract product line to store one or more package specifications and exactly one line quantity. The line quantity SHALL be the shared quota for all package specifications on that line. The system SHALL still allow the same product to appear on multiple lines. Within one contract, for the same productId, each distinct package specification MUST appear on at most one line (no duplicate package specs across lines for that product). Each line MUST have at least one package specification.

Scenario: Multi-package shared pool on one line

• WHEN a user saves a contract product line with package specs 25kg/桶 and 槽罐车 and quantity 715
• THEN the system persists both package specs on that single line with quantity 715 as the shared pool

Scenario: Reject duplicate package spec for same product across lines

• WHEN a user attempts to save two lines for the same product where both include package spec 槽罐车
• THEN the system rejects the save with a clear validation error and does not persist the change

Scenario: Same product separate pools via separate lines

• WHEN a user saves line A with only 25kg/桶 quantity 15 and line B with only 槽罐车 quantity 700 for the same product
• THEN the system persists two lines with independent quantities (legacy split-quota behavior remains valid)

Requirement: Transport plan consumes shared package pool by line

When a transport plan is bound to a contract, arranging a stop product with a given package specification SHALL locate the unique contract product line whose package-spec set contains that specification (for the same product). Available quantity and arrange hard-checks SHALL use that line's quantity minus the sum of arranged quantities for all package specifications belonging to that line (across counted plans), not a per-package independent quota. Plan stop products SHALL continue to carry exactly one package specification per plan line.

Scenario: Shared remaining after mixed package arrange

• WHEN a contract line has packages [25kg/桶, 槽罐车] and quantity 715, and counted plans have arranged 10 for 25kg/桶 and 10 for 槽罐车
• THEN querying arrange-qty for either package returns remaining 695 (same pool), and arranging additional quantity that would exceed 695 is rejected at arrange time

Scenario: Split-quota lines remain independent

• WHEN the same product has two lines with single packages 25kg/桶/15 and 槽罐车/700
• THEN arranging against 槽罐车 does not reduce the available quantity of the 25kg/桶 line

Scenario: Package must belong to contract line set

• WHEN a plan stop product uses a package specification not present on any contract line for that product
• THEN the system rejects save/arrange package validation with an explicit error

Requirement: Contract detail shows per-package arranged breakdown and line-level remaining

Contract detail (and equivalent product tables that show plan qty columns) SHALL display arranged / archived quantities broken down by package specification under each multi-package line, and SHALL show contract quantity and remaining only at the line aggregate level. Remaining MUST equal line quantity minus the sum of arranged totals across that line's packages. The system MUST NOT present an independent "remaining" per package that implies a separate quota.

Scenario: Detail breakdown for shared pool line

• WHEN a user opens contract detail for a line with packages [25kg/桶, 槽罐车], quantity 715, arranged 10 + 10
• THEN the UI shows per-package arranged (and archived / unarchived-arranged as applicable) for each package, and a line total arranged 20 with remaining 695 (or equivalent line-level remaining presentation)

Requirement: Contract print and PDF include multi-package lines

Contract print / PDF generation SHALL render each product line's package specifications (all values on the line) and SHALL aggregate contract-level {{packageSpecs}} from the union of all line package specs (deduplicated), without treating a multi-package line as a single opaque string that breaks dedupe.

Scenario: Print table cell lists multiple packages

• WHEN a user prints a contract containing a line with packages 25kg/桶 and 槽罐车
• THEN the product table package column (or equivalent) shows both package specs for that line

Requirement: API exposes packageSpecs list with backward-compatible read

Contract product create/update/detail APIs SHALL accept and return packageSpecs as a non-empty string array. For backward compatibility, responses MAY also include scalar packageSpec equal to the first package in the list (or the sole value). Legacy stored single scalar values MUST be readable as a one-element packageSpecs list.

Scenario: Legacy single value round-trip

• WHEN the system reads an existing contract product row that stores a single legacy package_spec string (not a multi-value encoding)
• THEN API packageSpecs is a one-element array containing that value and clients can edit/save without data loss