# Account-level Governing Contract Validation for Orders

## Problem Statement

Deal managers can have a valid Contract on the Account and still be blocked when uploading the signed Archived Order Form because the current Order activation validation follows the optional Order Contract Link. In production, this surfaced as an upload failure saying the associated Contract does not cover the Order end date, even though the Account had an Effective CSA covering the Order period.

The user-facing problem is not file upload itself. The upload succeeds far enough to apply final Order field updates, then the Status transition to Activated fails validation. The validation is checking the wrong business authority.

## Salesforce-compatible Implementation Understanding

The standard Salesforce-compatible implementation assumes an Order is activated against its associated Contract. The standard app-pack create-order flow requires an Accepted Quote, creates a Draft Order, stamps the Order effective date, and can copy the Quote Contract lookup to the Order when the source Quote has one. Standard Order activation validation then requires a Contract link, checks the linked Contract status, and compares the linked Contract dates with the Order dates.

That standard model is useful Salesforce parity, but it is not PingCAP's governing-contract rule. PingCAP must validate against the Account's governing Contract even when the Order Contract Link is blank or stale.

## Status Quo

The PingCAP pack currently mixes two models. At Order creation, it already performs an Account-level Contract existence check, but it requires the Contract to be Activated or Effective and only checks coverage of the Order effective date. At Order activation, it falls back to the standard associated-Contract model and rejects Orders whose Account has a valid governing Contract but whose Order Contract Link is blank.

The visible PingCAP Create Order quick action on a Quote currently opens a new Order form and prefills Quote, Account, optional Contract, Opportunity, pricebook, billing, contact, owner, currency, description, and total fields. It does not reliably prefill Product Family or service-period dates. A standard create-order flow also exists, and direct API Order creation is covered by watchdog cases. This PRD targets every Order create where `QuoteId` is present, regardless of which entry point created the draft Order.

The Archived Order Form quick action uploads a file as a generic record attachment, then updates the Order to Activated, archived, and linked to the uploaded file URL. That Status update is the validation seam for this PRD.

The runtime already has a generic validation primitive for "does at least one related record exist matching these filters." It can compare Account, Record Type, Status, Start Date, and End Date without adding PingCAP-specific upstream code.

## Solution

Replace PingCAP Order creation and activation validation with Account-level governing-contract checks.

At Order creation from an Accepted Quote, the system checks whether the Quote's Account has a Contract of the correct governing type whose validity dates cover the Quote-derived Order Service Period. Cloud Orders require a CSA. OP Orders require an MA. Contract status is ignored at this stage.

At final archive and activation, after the signed Archived Order Form is uploaded and the Order is being moved to Activated, the system checks whether the Order's Account has a Contract of the correct governing type whose validity dates cover the final Order Service Period and whose Status is Effective.

The Order Contract Link is not required, read, or written by these PingCAP governing-contract validations. Existing Orders with blank or stale Contract links can still be valid if their Account has the correct governing Contract.

The existing Activate Order permission gate remains in force.

## Canonical Validation Contract

| Seam | Account source | Family source | Service start source | Service end source | Contract type | Contract status |
| --- | --- | --- | --- | --- | --- | --- |
| Create Order from Accepted Quote | Quote Account | Quote governing family | Quote governing service start | Quote governing service end | Cloud requires CSA or CSAO; OP requires MA | ignored |
| Activate Order from Archived Order Form upload | Order Account | Order governing family | Order governing service start | Order governing service end | Cloud requires CSA or CSAO; OP requires MA | Effective |

The implementation should add or reuse canonical validation-only fields rather than encoding fallback behavior separately in every validation rule:

- Quote governing contract family: Cloud when Quote Product Family is `TiDB Cloud`; OP when Quote Product Family is `TiDB Enterprise Subscription`; blank otherwise.
- Quote governing service start: Quote Service Start Date.
- Quote governing service end: Quote Service End Date.
- Order governing contract family: the normalized family from Order Product Family when available; otherwise the related Quote governing contract family.
- Order governing service start: Order Effective Date; if blank, fall back to Quote Service Start Date.
- Order governing service end: `Order.EndDate`; if blank, fall back to Quote Service End Date. Do not include the legacy `Order_End_Date__c` field in the frozen validation helper, because runtime validation evaluates both `IF` branches and can null out the helper when that legacy field is absent from the validation context.

Do not use rollup-summary fields in frozen validation inputs. The local NexusCRM runtime validates frozen formulas before install and rejects rollup-summary dependencies there, so the canonical validation fields must use write-safe date fields.

If either canonical service-period endpoint is blank at the relevant seam, the system should fail with a service-period-specific validation error before the governing-contract existence rule. A missing period should not be reported as a missing Contract.

For Contract type matching, CSA means `TiDB Cloud Services Agreement` and `TiDB Cloud Services Agreement Online`; MA means `PingCAP Master Agreement`. Use the record-type field shape already supported by validation metadata for these names.

Cloud is `TiDB Cloud`. OP is `TiDB Enterprise Subscription` for this PRD. Other Product Family values remain outside this gate until Sales Ops supplies their governing-contract family.

## Validation Rule Shape

Use these record-set facts in validation metadata:

| Fact | Candidate object | Filters |
| --- | --- | --- |
| `HasCoveringCloudCSAForQuote` | Contract | Contract Account equals Quote Account; Contract type is CSA or CSAO; Contract start is on or before Quote governing service start; Contract end is on or after Quote governing service end |
| `HasCoveringOPMAForQuote` | Contract | Contract Account equals Quote Account; Contract type is MA; Contract start is on or before Quote governing service start; Contract end is on or after Quote governing service end |
| `HasCoveringCloudCSAForOrder` | Contract | Contract Account equals Order Account; Contract type is CSA or CSAO; Contract start is on or before Order governing service start; Contract end is on or after Order governing service end |
| `HasEffectiveCoveringCloudCSAForOrder` | Contract | Same as `HasCoveringCloudCSAForOrder`, plus Contract Status is Effective |
| `HasCoveringOPMAForOrder` | Contract | Contract Account equals Order Account; Contract type is MA; Contract start is on or before Order governing service start; Contract end is on or after Order governing service end |
| `HasEffectiveCoveringOPMAForOrder` | Contract | Same as `HasCoveringOPMAForOrder`, plus Contract Status is Effective |

Creation should be expressed as two family-specific coverage rules, plus a service-period prerequisite:

- `Order_Create_Requires_Quote_Service_Period`: fires when a Quote-sourced Order is created and the Quote governing service start or end is blank.
- `Order_Create_Requires_Covering_Cloud_CSA`: fires when the Quote governing family is Cloud and no covering CSA or CSAO exists on the Quote Account.
- `Order_Create_Requires_Covering_OP_MA`: fires when the Quote governing family is OP and no covering MA exists on the Quote Account.

Creation rules apply only when `QuoteId` is present. Creation Contract bindings must not filter by Contract Status.

Activation should be expressed as family-specific coverage and effective-status rules, plus a service-period prerequisite:

- `Order_Activate_Requires_Order_Service_Period`: fires when Status changes to Activated and the Order governing service start or end is blank.
- `Order_Activate_Requires_Covering_Cloud_CSA`: fires when a Quote-sourced Order governing family is Cloud and no covering CSA or CSAO exists on the Order Account.
- `Order_Activate_Requires_Effective_Cloud_CSA`: fires when a Quote-sourced Order has a covering CSA or CSAO but no Effective covering CSA or CSAO exists.
- `Order_Activate_Requires_Covering_OP_MA`: fires when the Order governing family is OP and no covering MA exists on the Order Account.
- `Order_Activate_Requires_Effective_OP_MA`: fires when a covering MA exists but no Effective covering MA exists.

Activation rules apply only when Status changes to Activated. The two Cloud CSA rules additionally apply only when `QuoteId` is present: this preserves the commercial Quote-to-Order archive workflow while allowing Finance/data-trans direct Cloud Orders, which do not set `QuoteId`, to activate without CSA coverage. The service-period rule remains applicable to both paths. The Effective variants should depend on the corresponding covering fact, so users get a coverage error when no same-family Contract covers the period and a status error only when coverage exists but no covering Contract is Effective.

The old PingCAP activation rules that require the Order Contract Link, dereference the linked Contract start date, dereference the linked Contract end date, or validate linked Contract status should be disabled or superseded for PingCAP. The Activate Order permission rule remains active.

## User Stories

1. As a deal manager creating an Order from an Accepted Cloud Quote, I want the Account's covering CSA to satisfy the creation gate regardless of Contract status, so that I can create the Order before the signed Contract is fully effective.

2. As a deal manager creating an Order from an Accepted OP Quote, I want the Account's covering MA to satisfy the creation gate regardless of Contract status, so that OP Orders follow the correct agreement family.

3. As a deal manager creating an Order from an Accepted Quote, I want the system to reject creation when no Contract of the correct type covers the full Order Service Period, so that Orders cannot be created outside the Account's commercial agreement.

4. As a deal manager uploading a signed Archived Order Form, I want activation to succeed when the Account has an Effective governing Contract covering the final Order Service Period, so that valid Orders are not blocked by a missing Order Contract Link.

5. As a deal manager uploading a signed Archived Order Form, I want activation to fail when the Account only has Draft, Approved, Expired, or otherwise non-Effective Contracts, so that archived Orders only activate after the governing Contract is effective.

6. As a deal manager uploading a signed Archived Order Form, I want activation to fail when the governing Contract starts after the Order Service Period starts, so that there is no uncovered beginning of service.

7. As a deal manager uploading a signed Archived Order Form, I want activation to fail when the governing Contract ends before the Order Service Period ends, so that there is no uncovered tail of service.

8. As a sales operations user, I want Cloud Orders to ignore MAs and OP Orders to ignore CSAs, so that each product family is governed by the correct legal agreement type.

9. As a sales operations user, I want an Order with a blank or incorrect Order Contract Link to be evaluated by Account-level governing Contracts, so that optional data hygiene does not block valid archive workflows.

10. As a sales operations user, I want clear creation and activation error messages that distinguish missing coverage from non-Effective activation status, so that production triage points to the real corrective action.

11. As a system administrator, I want Activate Order permission checks to remain independent of governing-contract checks, so that security and business eligibility remain separate.

12. As a migration operator, I want imported Orders not to require Contract writeback just to pass PingCAP validation, so that migrated data can follow the same business rules as newly created Orders.

13. As a QA owner, I want API and browser watchdog cases proving both success and failure paths, so that future pack changes cannot regress the archive workflow.

## Implementation Decisions

- Keep this as PingCAP pack policy. Do not add PingCAP-specific upstream runtime logic, because the generic record-existence validation primitive already supports the needed query shape.

- Replace, disable, or supersede PingCAP Order activation rules that require or dereference the Order Contract Link. These checks are valid for the standard Salesforce-compatible pack but not for PingCAP's governing-contract policy.

- Keep the Activate Order permission validation as a separate active rule.

- Rename the creation validation concept away from "Effective CSA/MA Contract" because creation must ignore Contract status. The creation error should say that the Account needs a CSA or MA covering the Order Service Period.

- Model the validation with separate Account-level existence checks for Cloud CSA and OP MA rather than one broad CSA/MA check. This keeps wrong-family Contracts from satisfying the rule.

- For creation, use the Accepted Quote as the source of the intended Order Service Period and governing family because the visible Create Order action and direct API create path do not reliably populate those Order fields before validation.

- For activation, use canonical Order fields for the final Order Service Period and governing family. These canonical fields may derive from the related Quote when Order-level fields are absent.

- Add hidden validation-only formula fields if the existing metadata cannot expose the canonical family and service-period sources cleanly. Contract existence bindings compare against those fields. This is preferable to teaching the runtime PingCAP-specific fallback semantics.

- Name the canonical fields consistently on Quote and Order: `Governing_Contract_Family__c`, `Governing_Service_Start_Date__c`, and `Governing_Service_End_Date__c`. These fields are validation inputs, not user-facing sales fields.

- Treat `TiDB Cloud` as Cloud for CSA and CSAO validation. Treat `TiDB Enterprise Subscription` as OP for MA validation. Other Product Family values need explicit business mapping before they are brought under this gate.

- Treat any matching governing Contract as sufficient. If more than one Contract covers the same period, validation only needs existence and does not choose a winner.

- Do not write back the matched Contract to the Order Contract Link. Writeback is out of scope and not required for the business validation.

- Existing create surfaces may continue to prefill or pass through an Order Contract Link from the source Quote. That lookup remains optional data and must not affect PingCAP governing-contract validation.

- Keep Archived Order Form upload behavior unchanged: store the file, update archive fields, and let the Status transition perform validation.

- Update watchdog expectations that currently require seeded Orders to have an Order Contract Link. Those tests should assert the Account-level governing Contract shape instead.

## Testing Decisions

- The highest-value test seam is the API workflow that creates an Order from an Accepted Quote and the API workflow that applies the same final field updates as Archived Order Form upload. These test the external behavior without depending on UI implementation details.

- Keep the browser case that proves the Archived Order Form upload action is reachable and still opens the upload dialog. The browser test does not need to duplicate every validation matrix case.

- Creation tests should cover Cloud with a covering CSA in a non-Effective status, Cloud with only a covering MA, OP with a covering MA in a non-Effective status, OP with only a covering CSA, and a same-family Contract whose dates do not cover the full service period.

- Activation tests should cover Cloud with an Effective covering CSA and blank Order Contract Link, Cloud with an Effective CSAO and blank Order Contract Link, Cloud with a Draft or Approved covering CSA, Cloud with an Effective CSA ending too early, OP with an Effective covering MA and blank Order Contract Link, and wrong-family Contracts.

- Permission tests should continue proving that activation is rejected without Activate Order permission even when the governing Contract is valid.

- Regression data should include the production-shaped case where the Account has an Effective long-running CSA, the Order has a valid end date, and the Order Contract Link is blank.

- Pack verification should ensure record-existence bindings validate successfully against relationship paths, Record Type filters, date comparisons, and Product Family branches.

- Update `order-archived-form-file-contract-api` so it no longer asserts that seeded Orders have an Order Contract Link and instead queries the Account's covering governing Contract.

- Replace `order-create-requires-effective-contract-api` with creation cases that prove status is ignored but service-period coverage and family-specific Contract type are enforced.

- Ensure watchdog seed data sets both service-period start and service-period end for Quote-sourced Order creation and archived Order activation fixtures.

## Out of Scope

- Editing production data or hot-patching production validation rules directly.

- Writing the matched Contract into the Order Contract Link.

- Changing generic file upload storage.

- Reworking Order line rollups or migrating Order date rollups from legacy custom child objects.

- Changing the standard Salesforce-compatible app pack behavior for non-PingCAP tenants.

- Defining governing-contract behavior for Product Family values outside Cloud and OP without a business decision.

## Further Notes

This PRD intentionally diverges from the standard Salesforce-compatible Order activation model. That divergence should stay localized to PingCAP pack metadata so standard Salesforce parity remains intact while PingCAP production follows the real governing-contract rule.