Hygiene Subscriptions

Editing technical v0.1 — published

Tab to switch the tab. Save writes a vNEW-DRAFT.md alongside the published file.

Markdown source

# Hygiene Subscriptions – Technical Specification

## 1. Module Purpose & Scope (Authoritative)

Hygiene Subscriptions is Primoro's clinician-led, product-based membership module. It enables hygienists to compose bespoke at-home oral-care subscriptions chair-side, which are then billed and fulfilled automatically to patients on a recurring basis. The module exists to extend hygienist recommendations beyond the appointment, support preventive care between visits, and generate predictable recurring product revenue while eliminating manual billing and logistics overhead.

It governs:

- Chair-side subscription plan composition by hygienists, including product selection and per-item supply intervals
- Patient enrolment, consent capture, and Direct Debit mandate creation via GoCardless
- Interval-driven fulfilment order generation and supplier dispatch
- Subscription billing lifecycle, including failure handling, escalation, and cancellation
- Patient and staff communications related to the subscription lifecycle

It explicitly does not:

- Manage clinical care plans, recall intervals, or appointment entitlements (owned by Care Plans and Appointment Manager)
- Process card payments or operate any payment surface outside GoCardless Direct Debit (owned by Integrated Payments)
- Store or generate signed documents beyond handing off to Document Hub
- Write any data to the PMS
- Sell individual products on a one-off, non-recurring basis (owned by Product Shop; see §2.3)

## 2. Ownership & Responsibilities

### 2.1 Hygiene Subscriptions IS Responsible For

- Composing, persisting, and lifecycle-managing patient-specific Hygiene Subscription records within Primoro
- Calculating real-time monthly pricing as the hygienist builds the plan
- Enforcing minimum commitment terms, rolling notice periods, and cancellation rules
- Generating fulfilment orders on the correct per-item interval schedule
- Pausing fulfilment when payments fail and escalating persistent failures to Communication Hub
- Emitting all patient- and staff-facing communication events to Communication Hub
- Maintaining an immutable audit trail for all state transitions and data operations
- Updating the patient's Primoro record (subscription status and label) on status change
- Emitting participation signals to Rewards Manager for eligible earning events (see §10.1)
- Emitting subscription revenue and fulfilment cost signals to Financial Insights (see §12.2)
- Exposing read-only engagement signals for consumption by Loyalty Insights (see §3.4)

### 2.2 Hygiene Subscriptions IS NOT Responsible For

- Collecting or vaulting payment credentials (owned by GoCardless; surfaced via Integrated Payments)
- Displaying payment status dashboards or exception banners to staff (owned by Integrated Payments)
- Storing signed subscription agreements (owned by Document Hub)
- Scheduling or modifying patient appointments or recall intervals (owned by Appointment Manager and Care Plans)
- Sending communications directly to patients (owned by Communication Hub)
- Writing any record to the PMS (explicitly prohibited; no PMS integration exists for this module)
- Processing one-off, non-recurring product purchases (owned by Product Shop)

### 2.3 Product Shop Boundary

Product Shop manages one-off, non-recurring product sales to patients through the patient mobile app and web storefront. It does not manage recurring billing or subscription-based product supply. Hygiene Subscriptions manages recurring product delivery under a hygienist-authored plan and does not expose a general-purpose product purchase surface. The two modules share access to the product catalogue (via Admin Control Plane) but operate entirely separate billing and fulfilment mechanics. A product appearing in both modules is normal; the billing model — recurring Direct Debit vs one-off transaction — is the governing distinction.

## 3. Core Objects (Normative)

### 3.1 Hygiene Subscription (Canonical Artefact)

A Hygiene Subscription is a patient-specific, recurring product plan governing which oral-care products are delivered to a patient, at what intervals, and at what price.

Minimum required fields:

- SubscriptionID
- PatientID
- Status (see §3.2)
- CommitmentModel (minimum term + notice period)
- BillingSchedule (monthly)
- DeliveryAddress
- PaymentMandateRef (GoCardless mandate reference)
- LineItems (one or more; see §3.3)
- CreatedBy (hygienist user ID)
- CreatedAt
- AuditTrail (immutable)

### 3.2 Hygiene Subscription State Machine (Authoritative)

States:

- **Draft** — plan is being composed chair-side; not yet presented to patient
- **Pending Enrolment** — plan saved; patient has not yet completed consent and mandate setup
- **Active** — mandate confirmed, billing running, fulfilment live
- **Paused** — fulfilment suspended due to unresolved payment failure
- **Cancelling** — notice period in progress; final payment cycle not yet complete
- **Ended** — subscription lifecycle complete; no further billing or fulfilment

Rules:

- All state transitions are auditable and time-stamped with the acting user ID.
- A subscription MUST NOT revert from Active to Draft.
- A subscription MUST NOT move to Ended while an outstanding payment remains unresolved.
- Paused may transition back to Active only on confirmed payment resolution.
- Only hygienists or authorised clinicians may transition a Draft to Pending Enrolment.
- Reception staff and admins MAY assist with enrolment steps but MUST NOT author product selection.

### 3.3 Line Item (Canonical Sub-Object)

A Line Item defines a single product within a Hygiene Subscription.

Minimum required fields:

- LineItemID
- SubscriptionID (FK)
- ProductID (catalogue reference)
- Quantity
- SupplyInterval (monthly / bi-monthly / quarterly)
- NextDueDate
- SupplierMapping (SKU / fulfilment code)

### 3.4 Loyalty Insights Signal Contract (Read-Only)

Loyalty Insights consumes Hygiene Subscriptions module signals as Category 4 optional inputs for its engagement-scoring model. This module MUST expose the following signals via the platform event feed; Loyalty Insights reads them and this module does not call Loyalty Insights directly.

| Signal | Description | Null / unavailable state |
|---|---|---|
| `hygiene_subscription.activated` | Emitted when a subscription transitions to Active | Not applicable (event-driven) |
| `hygiene_subscription.fulfilment_dispatched` | Emitted per fulfilment order dispatched | Not applicable (event-driven) |
| `hygiene_subscription.paused` | Emitted when subscription transitions to Paused | Not applicable (event-driven) |
| `hygiene_subscription.ended` | Emitted when subscription transitions to Ended | Not applicable (event-driven) |
| `hygiene_subscription.active_count` | Current count of Active subscriptions for a patient | Returns `0` if the patient has no Active subscriptions |

Where a patient has no Hygiene Subscription record, all signals MUST return a null or zero value and MUST NOT cause Loyalty Insights scoring to error or be suppressed. Signal availability follows the same contract as Care Plan Subscriptions signals consumed by Loyalty Insights.

## 4. Plan Builder (Chair-Side, Hygienist-Led)

### 4.1 Builder Access & Authorship

- Hygienists and authorised clinicians own plan composition.
- Admins own catalogue availability, pricing rules, and supplier mappings.
- Reception staff MAY assist with enrolment steps but MUST NOT author clinical product selection.

### 4.2 Product Categories (Authoritative)

The builder MUST support product selection across the following hygiene categories:

- Interdental cleaning (e.g. interdental brushes, silicone picks)
- Toothbrushes and brush heads
- Toothpastes (standard, sensitive, high-fluoride where clinically appropriate)
- Rinses and gels
- Floss and flossing aids
- Specialty brushes (e.g. interspace brushes)
- Plaque-disclosing aids (optional)

### 4.3 Supply Intervals (Authoritative)

Each line item MUST independently support one of the following intervals:

- Monthly
- Bi-monthly
- Quarterly

The module MUST calculate a per-item delivery schedule and generate fulfilment orders only when each item is individually due. Fulfilment MUST NOT batch all items to a single uniform interval unless all items share the same interval.

### 4.4 Real-Time Pricing (Authoritative)

As the hygienist builds the plan, the system MUST compute and display a single clear monthly price in real time.

Rules:

- Pricing MUST reflect selected items and their respective supply intervals.
- The monthly price MUST be shown to the patient before enrolment is confirmed.
- Practices MAY configure cost price vs patient-facing price to encode margin (configurable via Admin Control Plane).
- The patient-facing price shown at enrolment is the binding price for the billing run.

## 5. Enrolment & Onboarding (Governed)

### 5.1 Enrolment Channels

Patients MAY enrol:

- Immediately in clinic, staff-assisted via tablet or web portal
- Later via the patient mobile app, using a plan saved at the chair-side visit

The system MUST support deferred sign-up:

- A saved plan in Pending Enrolment state MUST persist after the appointment ends.
- Communication Hub MUST send mobile-app reminders prompting the patient to complete enrolment.
- Pending enrolments MUST be visible in staff dashboards with follow-up status.

### 5.2 Eligibility Rules (Optional)

Practices MAY enable an eligibility gate (e.g. "patient must have had a hygiene visit within the last X days"). If enabled, the system MUST block enrolment when the patient does not meet the configured criteria and MUST surface a clear reason to staff.

### 5.3 Contract & Consent (Authoritative)

Enrolment MUST include:

- Presentation of subscription terms to the patient
- Explicit patient acceptance and e-signature capture
- Direct Debit mandate creation via GoCardless

On completion:

- A signed subscription agreement MUST be generated and practice-branded.
- The signed agreement MUST be stored in Document Hub and linked to the patient record.
- The mandate reference returned by GoCardless MUST be stored against the Hygiene Subscription record as PaymentMandateRef.

## 6. Billing & Payments (Authoritative)

### 6.1 Direct Debit Billing (GoCardless)

- Billing MUST be monthly via GoCardless Direct Debit.
- Card payments are not permitted under any configuration.
- Billing day MAY be fixed practice-wide or aligned to each patient's first payment date (configurable via Admin Control Plane).
- Primoro stores only the GoCardless mandate reference; no raw payment credentials are held within this module.

### 6.2 Commitment & Cancellation Rules

- Every subscription MUST enforce a minimum 3-month commitment period.
- After the minimum term, cancellation operates on a rolling one-month notice model.

Cancellation flow:

- Patient MAY request cancellation via the patient mobile app.
- The system MUST confirm the effective end date and the amount of the final payment to the patient before confirming the request.
- The GoCardless mandate MUST be cancelled only after the final payment lifecycle is complete.
- The subscription status MUST transition to Cancelling on notice and to Ended when the mandate is cancelled and all payments are settled.

### 6.3 Failed Payments & Pause Behaviour (Authoritative)

Hygiene Subscriptions receives payment state updates from Integrated Payments via inbound webhook events (see §12.1). The `Failed` payment state emitted by Integrated Payments is the authoritative trigger for pausing fulfilment; this module MUST NOT maintain its own independent payment-failure detection logic.

If a Direct Debit payment fails:

1. The payment is marked Failed in Integrated Payments.
2. Integrated Payments emits a `Failed` payment state event to this module.
3. A retry is initiated per GoCardless retry rules; Integrated Payments surfaces retry status to staff via exception banners.
4. On receipt of the `Failed` event, fulfilment MUST be paused immediately; no new fulfilment orders are generated while a payment failure is unresolved.
5. The patient MUST receive a mobile-app notification of the failure; email or SMS fallback is applied via Communication Hub policy.
6. A Communication Hub task MUST be created for staff intervention.
7. Fulfilment MUST NOT resume until this module receives a confirmed payment-resolved event from Integrated Payments.

**Persistent failure escalation.** Where a payment failure remains unresolved after GoCardless retries are exhausted, the system MUST escalate by creating a mandatory staff intervention task in Communication Hub. This escalated task MUST remain open and actionable until the failure is explicitly resolved — by payment recovery, staff-initiated pause, or subscription end. This is distinct from the initial failure notification task.

### 6.4 Integrated Payments Surface

Whilst collection is handled by GoCardless, Integrated Payments is the platform surface responsible for displaying subscription payment status and surfacing exception alerts to staff. Integrated Payments exposes the following payment states for each subscription: Active mandate, Payment pending, Paid, Failed, and Cancelled. Exception banners and status indicators within Integrated Payments reflect these states in real time, giving staff a single location in which to review payment health across all active subscriptions.

This module provides Integrated Payments with the subscription record and mandate reference (see §12.2) so that payment states can be displayed in context. The authoritative source of payment state for fulfilment-gating purposes is always the inbound event from Integrated Payments, not any local cache held within this module.

## 7. AI Boundaries (Non-Negotiable)

Module does not embed AI surfaces directly.

Should AI-assisted product recommendation or subscription summary features be considered in a future release, the following boundaries apply as a baseline:

AI MAY:

- Explain subscription options to patients or staff in informational copy
- Summarise a patient's subscription status or history for staff review

AI MAY NOT:

- Auto-select products for a subscription on behalf of a hygienist
- Trigger any billing, fulfilment, or state-transition action
- Bypass audit, access control, or consent requirements
- Replace the hygienist's clinical judgement in product selection

## 8. Audit & Compliance

The system MUST log the following events with actor identity and timestamp:

- All Hygiene Subscription state transitions (Draft → Pending Enrolment → Active → Paused → Cancelling → Ended)
- All Line Item additions, removals, or modifications
- Patient consent and e-signature capture at enrolment
- GoCardless mandate creation and cancellation events
- Each payment event received from GoCardless (pending, paid, failed, retried)
- Each fulfilment order generated, dispatched, or deferred
- Each Communication Hub event emitted by this module (notification type and recipient)
- All staff intervention task creations and resolutions
- All read/write operations on patient-bound Hygiene Subscription data
- Eligibility gate evaluations (if feature is enabled), including outcome and criteria applied
- All participation signals emitted to Rewards Manager
- All revenue and fulfilment cost signals emitted to Financial Insights

Audit logs MUST be immutable, tamper-evident, and exportable for compliance inspection.

Service communications (enrolment confirmation, payment notices, shipping updates, cancellation confirmations) are sent regardless of marketing opt-in status. Marketing or promotional communications require explicit patient consent managed via Communication Hub.

## 9. Access Control

Access is governed by Access Manager roles. The following operations are role-gated:

| Operation | Permitted Roles |
|---|---|
| Create / compose a plan (Draft) | Hygienist, Authorised Clinician |
| Assist enrolment (non-authoring steps) | Reception, Admin |
| Read subscription records | Hygienist, Admin, Reception (practice-scoped) |
| Modify product selection on a Draft | Hygienist, Authorised Clinician |
| Approve and submit for enrolment | Hygienist, Authorised Clinician |
| Pause or cancel a subscription | Admin, Hygienist |
| Configure catalogue, pricing rules, supplier mappings | Admin |
| View outcomes dashboard | Admin, Hygienist |
| Export audit logs | Admin |

MFA MUST be required for any operation that triggers or cancels a GoCardless Direct Debit mandate, in line with platform-wide sensitive-action policy defined in Access Manager.

## 10. Fulfilment & Supplier Integration (Authoritative)

### 10.1 Fulfilment Model

- Fulfilment is interval-driven: items ship only when individually due per their SupplyInterval.
- The system generates fulfilment orders containing the minimum data required for delivery: patient name, delivery address, and supplier item mapping (SKU / fulfilment code).
- Fulfilment MUST NOT generate orders for items that are not yet due.
- Fulfilment MUST be paused for all items on a subscription while a payment failure is unresolved (§6.3). The trigger for pausing is the `Failed` payment state received from Integrated Payments; fulfilment resumes only on a confirmed payment-resolved event from Integrated Payments.

**Rewards Manager participation signals.** When a fulfilment order is confirmed dispatched, the module MUST emit a `hygiene_plan.participation` event to Rewards Manager. This event MUST include the SubscriptionID, PatientID, fulfilment date, and line item count, enabling Rewards Manager to accrue points for eligible Hygiene Plan participation in accordance with its earning-behaviour rules. Where a fulfilment order is deferred or cancelled due to a payment failure, no participation event is emitted for that cycle.

### 10.2 Stock & Availability

- Supplier stock availability MUST be respected via periodic sync or point-of-enrolment availability checks.
- If an item becomes unavailable after a subscription is Active, a staff-visible exception MUST be created (via Communication Hub task) to prompt a substitution or deferral decision.
- If an item is unavailable at the point of enrolment, the system MUST warn or block as configured by the Admin.

### 10.3 First Fulfilment Options

The system MAY support a "first delivery mode" selection:

- Shipped immediately after enrolment activation, or
- Handed out in clinic (if the practice holds starter stock)

When first fulfilment is handed out in clinic, the system MUST log the event to prevent duplicate shipment.

### 10.4 Shipping Notifications

When an order ships:

- The patient MUST receive a mobile-app notification; where tracking information is available, it MUST be included.
- Communication Hub MUST record the shipment event.

## 11. Delivery Surfaces & Access (Authoritative)

### 11.1 Web Portal

Staff access subscription management via the web portal: plan composition, enrolment tracking, outcomes dashboard, failed payment exception handling, and fulfilment exception review.

### 11.2 Tablet App

Chair-side plan composition for hygienists is the primary tablet use case. The tablet surface MUST support the full plan builder (§4) and in-clinic enrolment flow (§5.1).

### 11.3 Patient Mobile App

The patient mobile app is the default patient-facing surface for:

- Completing deferred enrolment
- Viewing active subscription details and upcoming deliveries
- Receiving all subscription lifecycle notifications
- Requesting cancellation

### 11.4 Engagement Signals

The module MUST emit the following signals for staff visibility and platform analytics:

- Pending enrolment count (saved plans not yet activated)
- Active subscriber count
- Paused subscription count (payment failure)
- Cancellation requests in notice period
- Ended subscriptions (period-over-period)
- Fulfilment exceptions outstanding

## 12. Integration Contracts

### 12.1 Inbound (this module consumes from)

| From Module | What | Contract |
|---|---|---|
| Integrated Payments | Payment state updates (Active mandate, Payment pending, Paid, Failed, Cancelled) | Event / webhook |
| GoCardless | Mandate confirmation, payment events, retry outcomes | Webhook (via Integrated Payments surface) |
| Product Catalogue (Admin Control Plane) | Product definitions, pricing, supplier SKU mappings, availability status | Sync / periodic pull |
| Access Manager | Role and permission data for access control enforcement | Sync |

### 12.2 Outbound (this module emits to)

| To Module | What | Contract |
|---|---|---|
| Communication Hub | Enrolment confirmation, payment notices, failure alerts, shipping notifications, cancellation confirmations, staff intervention tasks | Event |
| Document Hub | Signed subscription agreement (on enrolment completion) | Event / push |
| Integrated Payments | Subscription record and mandate reference (for payment status display) | Sync |
| Audit & Compliance | All auditable events listed in §8 | Event (immutable log) |
| Rewards Manager | `hygiene_plan.participation` event per confirmed fulfilment dispatch (SubscriptionID, PatientID, fulfilment date, line item count) | Event |
| Financial Insights | Subscription revenue signals (billing amount, billing date, payment status) and fulfilment cost signals (fulfilment order generated, cost price, patient-facing price) per subscription cycle | Event |
| Loyalty Insights (platform feed) | Read-only engagement signals per §3.4 (`hygiene_subscription.activated`, `fulfilment_dispatched`, `paused`, `ended`, `active_count`) | Event (platform feed; read-only by Loyalty Insights) |

**Financial Insights signal detail.** For each billing cycle, this module MUST emit a revenue signal containing: SubscriptionID, PatientID, billing amount (patient-facing price), billing date, and payment outcome (Paid / Failed / Pending). For each fulfilment order dispatched, this module MUST emit a fulfilment cost signal containing: SubscriptionID, PatientID, order date, total cost price, and total patient-facing price for items in that order. These signals enable Financial Insights to report recurring subscription revenue, payment failure impact, and margin (cost vs patient price) in its headline metrics and Insight Cards. Where a billing cycle results in a Failed payment, the revenue signal MUST reflect the failure status; no positive revenue event is emitted until payment is confirmed Paid.

### 12.3 PMS Boundary

Hygiene Subscriptions is Primoro-native. The module MUST NOT write any records, flags, clinical notes, or status fields to the PMS. When a patient subscribes or cancels, the system MUST update only the patient's Primoro record (subscription status: Active or Ended, and the hygiene subscription label). No PMS integration or write-back is required or permitted.

## 13. Integration Summary

- **GoCardless** — Direct Debit mandate creation, monthly billing, payment events, and retries (via Integrated Payments)
- **Integrated Payments** — inbound payment state events; staff-facing payment status and exception banners; authoritative source of `Failed` payment state for fulfilment-gating
- **Communication Hub** — all outbound patient and staff notifications; staff intervention task creation and tracking
- **Document Hub** — storage of signed subscription agreements
- **Access Manager** — RBAC enforcement for all read/write/approve operations
- **Audit & Compliance** — immutable event log for all state transitions and data operations
- **Admin Control Plane** — product catalogue, pricing configuration, supplier mappings, eligibility rules, billing day settings
- **Rewards Manager** — receives `hygiene_plan.participation` events per confirmed fulfilment dispatch to accrue points for eligible patients
- **Financial Insights** — receives subscription revenue signals and fulfilment cost signals per billing cycle and per dispatch for recurring revenue, margin, and payment failure reporting
- **Loyalty Insights** — reads engagement signals from the platform event feed (activated, dispatched, paused, ended, active count); this module emits; Loyalty Insights consumes read-only
- **Product Shop** — no direct integration; both modules share the product catalogue via Admin Control Plane but operate separate billing and fulfilment mechanics with no overlapping transactional surface

## 14. Analytics, KPIs & Reporting

The system MUST provide reporting on:

- Active subscribers and growth over time
- Churn rate and cancellation reasons (where captured)
- Gross subscription revenue
- Cost of fulfilment vs patient price (margin)
- Payment failure rates
- Fulfilment timeliness and exceptions

Dashboards SHOULD support filtering by:

- Clinician (plan creator)
- Subscription value band
- Product category mix
- First fulfilment mode (shipped vs handed out in clinic)

## 15. Explicit Non-Goals

- **Clinical care plans or appointment entitlements** — scope belongs to Care Plans and Appointment Manager
- **Card payment processing** — not permitted; no card payment surface will be added to this module
- **Pre-bundled product kits** — subscriptions are always composed per-patient by a clinician; fixed kits are out of scope
- **PMS write-back** — no PMS integration is planned or permitted for this module
- **Long-term locked-in contracts** — the commitment model is limited to the 3-month minimum term with rolling notice; perpetual lock-in constructs are out of scope
- **One-off product purchases** — non-recurring product sales are owned by Product Shop; this module manages only recurring subscription-based supply

## 16. Versioning & Governance

This specification is owned by: the Hygiene Subscriptions module owner (Post-MVP tier).

Changes to this spec require:

- Review by the Post-MVP module owner
- Impact analysis across all declared related modules (see /propose)
- Version bump (patch for clarifications, minor for behaviour changes, major for contract-breaking changes)

## 17. Build Contract (Engineering & QA)

### 17.1 Canonical Data Model

*(no schema DDL captured in original — needs definition by engineering)*

The following canonical tables are implied by the object model in §3:

- `hygiene_subscriptions` — one row per Hygiene Subscription (§3.1 fields)
- `hygiene_subscription_line_items` — one row per Line Item (§3.3 fields)
- `hygiene_subscription_audit_events` — immutable append-only log (§8)

Full DDL to be produced by engineering during sprint planning; this spec defines the field-level contract, not physical column types.

### 17.2 Core Behaviour Rules

1. A subscription in Draft state MUST NOT trigger any billing or fulfilment action.
2. A subscription MUST NOT move to Active without a confirmed GoCardless mandate reference stored as PaymentMandateRef.
3. A signed subscription agreement MUST be stored in Document Hub before the subscription transitions from Pending Enrolment to Active.
4. The system MUST compute and display the monthly price in real time as line items are added or removed in the builder.
5. A fulfilment order for a line item MUST NOT be generated before that item's NextDueDate.
6. Fulfilment MUST be paused across all line items when the subscription's payment status is Failed (as signalled by Integrated Payments); it MUST NOT resume until a payment-resolved event is received from Integrated Payments.
7. A persistent payment failure (GoCardless retries exhausted) MUST generate an escalated intervention task in Communication Hub that remains open until explicitly resolved by staff.
8. The minimum 3-month commitment MUST be enforced; a cancellation request received before the minimum term is reached MUST be rejected or deferred to the end of the minimum term.
9. A GoCardless mandate MUST NOT be cancelled until the final payment lifecycle is confirmed complete.
10. The patient's Primoro record MUST be updated (subscription status and label) on transition to Active and on transition to Ended.
11. No data MAY be written to the PMS at any point in the subscription lifecycle.
12. All state transitions MUST be recorded in the audit log with actor ID and timestamp before the transition is confirmed.
13. If an eligibility gate is configured and the patient does not meet the criteria, enrolment MUST be blocked and a human-readable reason MUST be surfaced to staff.
14. When first fulfilment is recorded as handed out in clinic, the system MUST set a flag preventing a duplicate shipment order for that first delivery cycle.
15. A `hygiene_plan.participation` event MUST be emitted to Rewards Manager for each confirmed fulfilment dispatch; no participation event is emitted for cycles where a fulfilment order is deferred or cancelled due to payment failure.
16. Revenue and fulfilment cost signals MUST be emitted to Financial Insights per billing cycle and per dispatch; a Failed payment cycle MUST emit a failed-status revenue signal and MUST NOT emit a positive revenue event until payment is confirmed Paid.
17. Loyalty Insights engagement signals (§3.4) MUST be emitted to the platform event feed for all relevant state transitions; a null or zero value MUST be returned for patients with no active subscription, without causing downstream errors.

### 17.3 Configuration Surfaces

| Setting | Configurable By | Surface |
|---|---|---|
| Product catalogue, pricing, supplier SKU mappings | Admin | Admin Control Plane |
| Practice-wide billing day | Admin | Admin Control Plane |
| Eligibility gate (enabled/disabled, criteria) | Admin | Admin Control Plane |
| Cost price vs patient-facing price (margin) | Admin | Admin Control Plane |
| Communication fallback policy (email/SMS) | Admin | Communication Hub settings |
| First fulfilment mode (ship vs in-clinic) | Admin / Hygienist | Plan builder |

### 17.4 Filtering & Views

Staff dashboards MUST support the following standard filters:

- Subscription status (Draft, Pending Enrolment, Active, Paused, Cancelling, Ended)
- Clinician (plan creator)
- Subscription value band
- Product category mix
- Fulfilment mode (shipped vs in-clinic first kit)
- Payment exception status (no exception / failure pending / escalated)

### 17.5 Module Extension Map

The following extension points are reserved for future versions without breaking this contract:

- Additional supply intervals (e.g. annual) may be added to the SupplyInterval enum without schema breaking change.
- Eligibility gate criteria may be extended with additional configurable rule types via the Admin Control Plane without changing the enrolment flow contract.
- Additional product categories may be added to the builder catalogue without schema change.
- AI-assisted product recommendation (if introduced) MUST be implemented as a suggestion surface only, subject to §7 boundaries, and MUST NOT alter the hygienist-authorship contract in §4.1.
- Additional Loyalty Insights signal types may be added to the §3.4 contract as minor version changes; Loyalty Insights MUST handle unknown signal types gracefully without error.

### 17.6 Acceptance Criteria

The build of Hygiene Subscriptions is complete when:

- [ ] Hygienists can create a bespoke subscription plan chair-side using supported categories and per-item supply intervals
- [ ] Monthly price computes in real time and is displayed clearly to the patient before enrolment confirmation
- [ ] Patients can enrol in clinic or later via the patient mobile app; saved plans in Pending Enrolment are tracked in staff dashboards and followed up via Communication Hub reminders
- [ ] Direct Debit billing via GoCardless runs monthly; minimum 3-month commitment and rolling 1-month notice are enforced
- [ ] Payment failures trigger retries, pause fulfilment, notify the patient (mobile-first), and create a staff task in Communication Hub; persistent failures escalate to a mandatory open intervention task until resolved
- [ ] Fulfilment pause and resume are gated exclusively on `Failed` and payment-resolved events received from Integrated Payments; no independent failure detection is implemented
- [ ] Integrated Payments surfaces subscription payment states (Active mandate, Payment pending, Paid, Failed, Cancelled) and exception banners to staff
- [ ] Fulfilment orders are generated only when each item's NextDueDate is reached; shipping notifications include tracking information where available
- [ ] A `hygiene_plan.participation` event is emitted to Rewards Manager for each confirmed fulfilment dispatch; no event is emitted for deferred or cancelled cycles
- [ ] Revenue and fulfilment cost signals are emitted to Financial Insights per billing cycle and per dispatch with correct payment status; Failed cycles do not emit positive revenue events
- [ ] Loyalty Insights engagement signals (§3.4) are emitted to the platform event feed for all relevant state transitions; null/zero values are returned gracefully for patients with no active subscription
- [ ] Communication Hub logs all lifecycle events; staff dashboards show all subscription states and exceptions
- [ ] Signed subscription agreements are stored in Document Hub and linked to the patient record
- [ ] Patient Primoro records are updated on Active and Ended transitions; no data is written to the PMS
- [ ] All state transitions and auditable events in §8 are captured in the immutable audit log
- [ ] Access control per §9 is enforced; MFA is required for mandate creation and cancellation
- [ ] All non-functional requirements in §18 are met

## 18. Non-Functional Requirements

- **Performance:** Plan builder pricing computation MUST return an updated monthly price within 500 ms of a line item change. Fulfilment order generation batch MUST complete within a configurable nightly window without impacting daytime API responsiveness.
- **Reliability:** The module MUST target 99.9% availability for enrolment and billing-critical paths. Fulfilment order generation MUST be idempotent; duplicate orders MUST NOT be dispatched in the event of retry.
- **Scalability:** The module MUST support multi-site, multi-tenant operation; subscription records and dashboards MUST be scoped to the authenticated practice with no cross-practice data leakage.
- **Security:** Payment credentials are never held by this module; only the GoCardless mandate reference is stored. All data in transit MUST be encrypted (TLS 1.2+). All data at rest MUST be encrypted. Secrets (API keys for GoCardless and supplier integrations) MUST be managed via the platform secrets management service and MUST NOT be embedded in application code or configuration files.
- **Privacy:** Patient delivery addresses and subscription data are personal data under GDPR. The module MUST honour subject access requests, right-to-erasure requests (subject to billing retention obligations), and data portability requirements as defined by the platform privacy policy. The supplier receives only the minimum data required for fulfilment dispatch; no marketing data is passed to the supplier.
- **Observability:** The module MUST export: (a) structured logs for all state transitions and integration events; (b) metrics for active subscriptions, payment failure rate, fulfilment order lag, and pending enrolment age; (c) distributed traces for the enrolment flow, billing trigger path, and fulfilment order generation path. Alerts MUST be configured for elevated payment failure rates and fulfilment order generation failures.

## 19. Open Questions

1. **Billing day configuration scope:** The original states billing day may be fixed practice-wide or aligned to first payment date. It is unresolved whether both modes must be supported at launch or whether one is the default with the other deferred.
2. **Deferred enrolment reminder cadence:** The spec requires Communication Hub to send reminders for saved plans in Pending Enrolment but does not define the reminder schedule or maximum reminder count before a plan is archived.
3. **Eligibility gate criteria definition:** The eligibility gate example ("hygiene visit within the last X days") is illustrative. The full set of supported eligibility criteria and whether practices can define custom rules has not been specified.
4. **Substitution approval workflow:** When a supplier item becomes unavailable for an existing subscriber, the spec requires a staff-visible exception but does not define whether staff must approve a substitution before it ships, or whether a configured substitute ships automatically pending staff review.
5. **Cancellation request by staff vs patient:** The cancellation UX describes patient self-service via the app, but it is not specified whether staff may also initiate cancellation on the patient's behalf through the portal, and if so, what audit and consent requirements apply.
6. **PMS status flagging discrepancy:** The acceptance criteria state "PMS status flagging is supported for Active/Ended states" but §8.1 explicitly prohibits any PMS write-back. This contradiction must be resolved before the spec is promoted from draft.
7. **Supplier integration protocol:** The spec refers to supplier SKU/fulfilment codes and periodic stock sync but does not name the supplier(s) or define the integration protocol (API, SFTP, EDI). This must be defined before fulfilment engineering can begin.
8. **Financial Insights signal granularity:** It is unresolved whether Financial Insights requires per-line-item cost signals or whether an order-level aggregate (total cost price vs total patient-facing price per fulfilment dispatch) is sufficient for margin reporting.
9. **Rewards Manager eligibility scope:** It is unresolved whether all Hygiene Plan participants are eligible for point accrual by default or whether Rewards Manager applies its own eligibility filter (e.g. patient must be enrolled in the rewards programme) before awarding points. The participation signal contract defined in §10.1 covers emission; eligibility filtering is owned by Rewards Manager.

Live preview