PSA/ee/docs/plans/2026-03-21-service-catalog-billing-mode-decoupling/PRD.md

PRD — Service Catalog Billing Mode Decoupling

• Slug: service-catalog-billing-mode-decoupling
• Date: 2026-03-21
• Status: Draft (Hard Cutover)

Summary

Decouple service identity from billing behavior so the same catalog service can be billed differently per contract line (fixed, hourly, usage) while still supporting default pricing. Remove hard gating that currently treats service_catalog.billing_method as eligibility truth, enforce allocation by contract-line service membership, and make non-contract time/usage explicit instead of silently sweeping null-linked entries into arbitrary contract lines.

Problem

• Today, contract authoring gates services by service_catalog.billing_method, so a service marked hourly cannot be added under fixed, even when the business contract requires fixed pricing for that same service.
• Billing engine still includes contract_line_id IS NULL time/usage in each contract-line calculation pass, which can cause ambiguous or duplicate allocation behavior.
• API and UI surfaces conflate catalog metadata with billing behavior and expose billing_method as if it is immutable service identity.
• Product teams need the model to be:

1. item_kind describes what it is (service vs product).
2. contract line mode describes how it is billed.
3. catalog can provide optional mode-specific defaults.

Goals

• Allow any item_kind='service' service to be added to fixed/hourly/usage contract-line contexts.
• Make contract-line context the authoritative billing mode, not catalog billing_method.
• Preserve defaulting ergonomics via mode-specific default prices/rates in catalog metadata.
• Ensure time/usage allocation only bills through valid matching contract-line services.
• Treat unresolved (non-contract) time/usage as explicit work, not implicit fallback.
• Keep existing invoice persistence semantics intact (including mixed assignment support), while giving deterministic allocation.

Non-goals

• Replacing the full invoice data model.
• Reworking tax/export/GL behavior.
• Replacing service types taxonomy (custom_service_type_id remains identity taxonomy).
• Full redesign of manual invoice creation UX.
• Changing permission model for service catalog CRUD.

Users and Primary Flows

• Billing admin configures a catalog service once and optionally sets default prices per billing mode.
• Contract author creates/edits contract lines and can add any service under fixed/hourly/usage sections; defaults prefill but remain editable.
• Technician enters time with service; explicit contract-line assignment is preferred but not required.
• Billing engine allocates approved uninvoiced records:

1. explicit line assignment first,
2. unique service-based contract match second,
3. unresolved remains non-contract work.

• Invoicing user can bill contract-backed work and non-contract work separately, and optionally combine only when compatible.

UX / UI Notes

• Contract wizard/service pickers:

1. remove hard billingMethods gating for service items by section,
2. still gate item_kind where needed (service vs product).

• In each section, show “Default for this mode” when a mode-specific default exists.
• Contract-line service forms should display effective mode + source of default (catalog default, contract override, none).
• Time entry contract info banner should clearly show:

1. assigned contract line,
2. uniquely inferred contract line,
3. unresolved non-contract billing path.

• Automatic invoicing grouped UI should represent non-contract candidates as first-class items.

Requirements

Functional Requirements

L0 Objective

Establish a single behavioral rule: service identity is catalog-level; billing mode is contract-line-level.

L1.A Data Model and Vocabulary

• Keep item_kind as identity discriminator.
• Introduce a mode-specific default-rate structure keyed by:

1. service_id,
2. billing_mode,
3. currency_code,
4. tenant.

• Canonicalize vocabulary to fixed | hourly | usage and remove active per_unit writes.
• Do not preserve compatibility reads for legacy fields after cutover migration is applied.

L1.B Contract Authoring and Mutation

• Wizard/template authoring must no longer reject services based on catalog billing_method.
• Server-side submission validation must enforce contract context requirements, not catalog-method matching.
• Adjacent APIs (add service to contract line, preset/template line service actions) must align with same policy.

L1.C Pricing Defaults

• Default selection precedence for contract-line service config:

1. explicit contract override,
2. catalog mode default for contract currency,
3. no default (user must enter/confirm).

• Defaults must be applied consistently in wizard, template wizard, and line-edit screens.

L1.D Time/Usage Allocation

• Replace unconditional null-line fallback with service-aware allocation.
• Allocation precedence:

1. explicit contract_line_id,
2. unique eligible active contract-line service match for (client, service, date),
3. unresolved non-contract.

• Never allocate a record to a contract line that does not include the record’s service.

L1.E Invoicing Behavior

• Non-contract approved billable records must be selectable as explicit invoice candidates.
• Contract-backed and non-contract candidates can be generated separately.
• Combination is allowed only under compatibility rules (client/window/currency/tax/export/PO scope).

L1.F API/Schema Compatibility

• Hard-cutover API contracts and remove legacy alias fields (including service_type compatibility fields).
• Update Zod/api/interface contracts that currently require catalog billing_method as behavioral truth.

L1.G Migration and Backfill

• Backfill mode defaults from current catalog data into new default-rate structure.
• Normalize per_unit legacy values to usage in writes and validation.
• Migration is one-way; no dual-read/dual-write compatibility path is retained.

Non-functional Requirements

• Deterministic allocation: same input set must always produce same contract/non-contract partition.
• No regression in existing cadence/materialization paths introduced by this plan.
• DB-backed integration tests required for new reads/writes and migration backfill behavior.
• No hidden fallback paths that silently remap unresolved records.

Data / API / Integrations

• Primary touched areas:

1. packages/billing/src/actions/contractWizardActions.ts
2. packages/billing/src/actions/contractLineServiceActions.ts
3. packages/billing/src/lib/billing/billingEngine.ts
4. packages/scheduling/src/actions/timeEntryCrudActions.ts
5. packages/billing/src/actions/serviceActions.ts
6. server/src/lib/api/services/ServiceCatalogService.ts
7. server/src/lib/api/services/ProductCatalogService.ts

• Add/update schema contracts:

1. server/src/lib/api/schemas/serviceSchemas.ts
2. server/src/lib/api/schemas/productSchemas.ts
3. server/src/lib/api/schemas/financialSchemas.ts
4. server/src/lib/api/schemas/contractLineSchemas.ts

• Identity handling alignment:

1. assignment-scoped IDs already used in clients stack,
2. billing-engine readers must handle/parse correctly where needed.

Security / Permissions

• No new permissions introduced.
• Existing service catalog and contract authoring permissions remain unchanged.

Observability

• Not adding new telemetry scope in this plan.
• Error messages for unresolved allocation must remain actionable and non-ambiguous.

Rollout / Migration

• Phase 0: apply one-way schema migration/backfill and canonical value normalization.
• Phase 1: update wizard/picker/API validations to contract-context semantics.
• Phase 2: update engine allocation to service-aware matching and explicit non-contract outputs.
• Phase 3: land strict schema/API hard cutover and remove all compatibility branches in same release.

Execution Order

Wave 0 — Schema and Canonicalization Gate

• Scope: F001-F003.
• Entry criteria:

1. migration scripts authored,
2. backfill mapping rules documented.

• Exit criteria:

1. canonical vocabulary enforced in writes,
2. mode-default storage created and populated,
3. migration tests green (T001-T005).

• Stop-the-line conditions:

1. residual per_unit write paths remain,
2. backfill cannot produce complete defaults for active services.

Wave 1 — Contract Authoring Cutover

• Scope: F004-F017.
• Depends on: Wave 0.
• Entry criteria:

1. schema is migrated in dev/test DB,
2. default resolver available to wizard/form code.

• Exit criteria:

1. wizard/template and line service actions use contract-context validation only,
2. no catalog-method eligibility gates remain in these paths,
3. prefill behavior is deterministic for fixed/hourly/usage,
4. tests green (T006-T027).

• Stop-the-line conditions:

1. contract creation/edit can still fail solely due to catalog billing_method,
2. wizard resume loses or mutates selected service/rate state.

Wave 2 — Engine Allocation Integrity

• Scope: F018-F025.
• Depends on: Wave 1.
• Entry criteria:

1. contract authoring can produce decoupled line/service mappings reliably.

• Exit criteria:

1. unconditional null-line fallbacks removed for time and usage,
2. service-membership-constrained allocation enforced,
3. pricing and bucket regressions absent,
4. tests green (T028-T040).

• Stop-the-line conditions:

1. same unassigned record can be billed by multiple lines,
2. rounding/minimum/overtime/tiering regressions are detected.

Wave 3 — Invoicing Candidate and Generation Behavior

• Scope: F026-F032.
• Depends on: Wave 2.
• Entry criteria:

1. engine returns deterministic contract/non-contract partitioning.

• Exit criteria:

1. non-contract candidates appear as first-class due work,
2. separate vs combined generation works with compatibility guards,
3. preview/generate summary accuracy verified,
4. tests green (T041-T049).

• Stop-the-line conditions:

1. non-contract work is invisible/inaccessible,
2. incompatible mixed selections combine incorrectly.

Wave 4 — API/Schema/Downstream Hard Cutover

• Scope: F033-F043.
• Depends on: Wave 3.
• Entry criteria:

1. core behavior is stable in billing flows.

• Exit criteria:

1. all affected APIs/schemas/interfaces reflect decoupled semantics,
2. no legacy alias contracts retained,
3. onboarding/settings/usage tracking callers aligned,
4. tests green (T050-T060).

• Stop-the-line conditions:

1. any consumer still requires legacy alias payloads,
2. compile/schema suites fail due to mixed old/new contracts.

Wave 5 — Final Debt Purge and Guard Rails

• Scope: F044.
• Depends on: Wave 4.
• Entry criteria:

1. all functional paths migrated.

• Exit criteria:

1. compatibility/fallback branches removed,
2. static guards prevent reintroduction,
3. e2e bootstrap no longer injects stale constraints,
4. final DB-backed sanity run passes,
5. tests green (T061-T066).

• Stop-the-line conditions:

1. any lingering compatibility branch is still executed in production paths,
2. static guards fail to catch reintroduced legacy gates/fallbacks.

Open Questions

• Resolved (2026-03-21): Canonical billing mode vocabulary is fixed | hourly | usage; per_unit is legacy compatibility only.
• Resolved (2026-03-21): Source of billing behavior truth is contract-line context; catalog stores defaults, not enforcement.
• Resolved (2026-03-21): Products remain item_kind='product'; product billing behavior is handled in product line flows and not used to gate service line eligibility.
• Resolved (2026-03-21): Non-contract time/usage must be first-class selectable invoice candidates, not implicit sweep-in.
• Resolved (2026-03-21): No compatibility compromises: no dual-read/dual-write and no transitional alias fields retained post-migration.

Acceptance Criteria (Definition of Done)

• A single service can be added under fixed or hourly contract sections without catalog-method rejection.
• Wizard/template and line-edit actions no longer hard-fail on catalog billing_method mismatch for services.
• Mode-specific defaults prefill rates in each contract-line context and remain editable.
• Billing engine no longer uses unconditional contract_line_id IS NULL fallback in a way that can multi-claim records.
• Unresolved approved billable time/usage appears as explicit non-contract invoice candidates.
• Users can invoice contract-backed and non-contract work separately; combined generation only occurs when compatibility checks pass.
• API schemas/interfaces are consistent with decoupled semantics and tests are green.
• Legacy alias fields and compatibility branches are removed in the same cutover release.
• Migration/backfill tests prove existing data remains billable and deterministic post-cutover.