--- id: CAP-BIL-BIL-002 title: Configure a notice and its recipients feature: FEAT-BIL-BIL-01 product_area: billing module: billing revision: 1 status: draft product_intent: proposed implementation_evidence: partially-observed supersedes: - CAP-ACC-BIL-002 - CAP-ACC-BIL-003 source_sha: services-accounting: f47cb263875bbc0c5640fba7dae6785ec32695f8 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f intent_sources: - 'services-accounting:docs/milestones/plans/ACCT-M4-plan.md#D10' - >- services-accounting:docs/milestones/ACCT-M4-contracts-and-events-for-commerce.md#M4-D13 (to be confirmed by Andrew) purpose: >- Administrators choose a notice purpose, audience settings and the message template reused by billing work. outcomes: - Recipient settings support resolving people for each target record. - >- A notice selects a published message template rather than storing its own content. - >- Send-notice references protect notices from deletion; installment-action references have a recorded gap. concepts: - CON-BIL-BIL-001 actors: - ACT-BIL-001 - ACT-BIL-003 surfaces: - console - api permissions: - key: accounting.billing-notices.read where_checked: api scope: tenant - key: accounting.billing-notices.create where_checked: api scope: tenant - key: accounting.billing-notices.update where_checked: api scope: tenant - key: accounting.billing-notices.delete where_checked: api scope: tenant rules: - id: BR-CAP-BIL-BIL-002-01 proved_by: [ATS-BIL-BIL-002-01, TST-BIL-BIL-002, TST-BIL-BIL-077] statement: >- Direct-recipient notices require an empty role list, while role-recipient notices require one to fifty distinct roles and reject invalid combinations with a field explanation. kind: validation enforced_at: - api - service - database must_prove: true provenance: test source: >- services-accounting:modules/billing/tests/unit/rules/billing-rules.spec.js#refuses a notice to roles naming fifty-one contact roles origin: none - id: BR-CAP-BIL-BIL-002-02 proved_by: [ATS-BIL-BIL-002-02, TST-BIL-BIL-002, TST-BIL-BIL-025] statement: >- Notices default to the billing-notice purpose and reject any purpose outside that sole supported choice, listing the available purpose. kind: validation enforced_at: - api - service must_prove: true provenance: test source: >- services-accounting:modules/billing/tests/e2e/billing-notices.e2e.spec.js#answers 400 purpose_unknown to a purpose that is not on the pick-list origin: 'services-accounting:docs/milestones/plans/ACCT-M4-plan.md#D10' - id: BR-CAP-BIL-BIL-002-03 proved_by: [ATS-BIL-BIL-002-03, ATS-BIL-BIL-002-08, TST-BIL-BIL-025] statement: >- A notice selects the communications template it sends, cannot send without that selection, and loses the selection when a replacement omits it. kind: policy enforced_at: - service must_prove: true provenance: test source: >- services-accounting:modules/billing/tests/integration/services/persistence/billing-notices.integration.spec.js#clears the template when a replacement does not state one origin: none - id: BR-CAP-BIL-BIL-002-04 proved_by: [] statement: >- Message content belongs to the communications template rather than the billing notice. kind: invariant enforced_at: - service - database must_prove: false provenance: documented source: 'services-accounting:docs/accounting/billing-api.md#Billing notices' origin: >- services-accounting:docs/milestones/plans/ACCT-M4-plan.md#4a (rule 47, D-2 Platform communications) - id: BR-CAP-BIL-BIL-002-05 proved_by: [ATS-BIL-BIL-002-04, TST-BIL-BIL-002, TST-BIL-BIL-025] statement: >- A send-notice reference from any template prevents notice deletion, including references from inactive templates, with up to twenty dependent templates named. kind: lifecycle enforced_at: - service must_prove: true provenance: test source: >- services-accounting:modules/billing/tests/integration/services/persistence/billing-notices.integration.spec.js#refuses a notice only an inactive template names, naming the template origin: none - id: BR-CAP-BIL-BIL-002-06 proved_by: [ATS-BIL-BIL-002-05, TST-BIL-BIL-024, TST-BIL-BIL-103] statement: >- An installment-only notice reference does not prevent deletion, leaving subsequent work blocked by the missing notice. kind: lifecycle enforced_at: - service must_prove: true provenance: test source: >- services-accounting:modules/billing/tests/integration/services/persistence/billing-notice-references.queries.integration.spec.js#never answers a template whose action of another kind carries the notice’s id origin: none - id: BR-CAP-BIL-BIL-002-07 proved_by: [] statement: >- Notice names remain unique within the workspace, and whole-record replacement refuses a version older than the current notice. kind: validation enforced_at: - api - service - database must_prove: true provenance: test source: >- services-accounting:modules/billing/tests/e2e/billing-notices.e2e.spec.js#answers 409 StaleObject to a replacement at the version before the last origin: none - id: BR-CAP-BIL-BIL-002-08 proved_by: [ATS-BIL-BIL-002-06, TST-BIL-BIL-005] statement: >- Notice readers may inspect configuration, while creation, replacement and deletion require administrator permissions. kind: permission enforced_at: - api must_prove: true provenance: test source: >- services-accounting:modules/billing/tests/e2e/billing-security.e2e.spec.js#is refused the billing notice create 403 permission_missing origin: none - id: BR-CAP-BIL-BIL-002-09 proved_by: [ATS-BIL-BIL-002-07] statement: >- The console has no communications-template selector and disables the message designer, so notices created there require template selection elsewhere before sending. kind: policy enforced_at: - console must_prove: true provenance: observed source: >- react-console:components/configuration/billing-notice-sections.tsx:NoticeMessageField origin: none - id: BR-CAP-BIL-BIL-002-10 proved_by: [] statement: >- A full configuration lock refuses updates, and either lock refuses deletion. kind: policy enforced_at: - service must_prove: true provenance: observed source: >- services-accounting:modules/billing/services/persistence/billing-notices.ts:updateBillingNotice origin: none scenarios: - id: SC-CAP-BIL-BIL-002-01 given: The administrator supplies a notice name without optional settings. when: The notice is created. then: >- It defaults to active direct recipients, no roles and the billing-notice purpose. provenance: test source: >- services-accounting:modules/billing/tests/e2e/billing-notices.e2e.spec.js#defaults the purpose to accounting.billing.notice, the contact roles to none and the notice to active - id: SC-CAP-BIL-BIL-002-02 given: A template uses a notice for direct sending. when: >- The administrator tries deletion, changes the template reference, then tries deletion again. then: >- The first attempt names the dependent template and refuses; the second removes the unreferenced notice. provenance: test source: >- services-accounting:modules/billing/tests/integration/services/persistence/billing-notices.integration.spec.js#deletes a notice once the template that named it names another edge_cases: [] depends_on: [] related: - CAP-BIL-BIL-001 - CAP-BIL-BIL-009 journeys: - JNY-BIL-BIL-001 open_questions: [] evidence: - >- services-accounting at f47cb263: docs/accounting/billing-api.md (Billing notices); docs/billing/architecture.md §5.3; docs/milestones/ACCT-M4-contracts-and-events-for-commerce.md (M4-D13); docs/milestones/plans/ACCT-M4-plan.md (D10, rules 43-50); docs/debt/billing-notice-owned-templates-deferred.md; aws/api/billing-notices.routes.ts (createBillingNotice, listBillingNotices, getBillingNotice, updateBillingNotice, deleteBillingNotice); services/persistence/billing-notices.ts, billing-notice-references.ts; db/billing-notices.table.ts. - >- services-accounting tests: e2e/billing-notices, billing-security; integration/services/persistence/billing-notices, billing-notices.queries, billing-notice-references.queries; unit/rules/billing-rules; unit/carried/billing-notices/**. - >- react-console at baf6dae3: components/configuration/resources/billing-notices.tsx, billing-notice-sections.tsx; acceptance/accounting/inventory/parts/billing.json (CAP-ACC-BIL-002, CAP-ACC-BIL-003, RUL-ACC-BIL-002); journeys ACT-ACC-0421, 0422, 0454. controls: - TC-AZ-001 - TC-AZ-002 - TC-AZ-003 - TC-AZ-004 - TC-AZ-005 - TC-AZ-006 - TC-CRY-001 - TC-DAT-004 - TC-IAM-001 - TC-IAM-002 - TC-IAM-004 - TC-IAM-005 - TC-LOG-001 - TC-LOG-002 - TC-LOG-004 - TC-LOG-005 - TC-PI-001 - TC-PI-003 - TC-PI-005 - TC-TEN-001 - TC-TEN-002 - TC-TEN-003 exercised_by: [FAS-BIL-BIL-01-01, FAS-BIL-BIL-01-02, FAS-BIL-BIL-01-03, FAS-BIL-BIL-01-04, FAS-BIL-BIL-01-05] suites: [TST-BIL-BIL-002, TST-BIL-BIL-005, TST-BIL-BIL-024, TST-BIL-BIL-025, TST-BIL-BIL-077, TST-BIL-BIL-103] --- # Configure a notice and its recipients ## Purpose Administrators choose a notice purpose, audience settings and the message template reused by billing work. ## How It Works Administrators choose a notice purpose, audience settings and the message template reused by billing work. Direct-recipient notices require an empty role list, while role-recipient notices require one to fifty distinct roles and reject invalid combinations with a field explanation. Notices default to the billing-notice purpose and reject any purpose outside that sole supported choice, listing the available purpose. A notice selects the communications template it sends, cannot send without that selection, and loses the selection when a replacement omits it. Message content belongs to the communications template rather than the billing notice. A send-notice reference from any template prevents notice deletion, including references from inactive templates, with up to twenty dependent templates named. An installment-only notice reference does not prevent deletion, leaving subsequent work blocked by the missing notice. Notice names remain unique within the workspace, and whole-record replacement refuses a version older than the current notice. Notice readers may inspect configuration, while creation, replacement and deletion require administrator permissions. The console has no communications-template selector and disables the message designer, so notices created there require template selection elsewhere before sending. The product should expose the published-template choice in the notice editor. Configuration locks can also refuse changes or deletion. ## Relationships Templates reference configured notices. During execution, notice sending uses their recipient and message settings.