Lab Manager

Editing technical v0.1 — published

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

Markdown source

# Lab Manager – Technical Specification

## 1. Module Purpose & Scope (Authoritative)

Lab Manager provides a governed, end-to-end system for managing all laboratory work — from case creation through to receipt and fitting — with full visibility, accountability, and auditability. It exists to eliminate lost or delayed lab cases, protect appointment integrity, remove manual chasing and spreadsheet tracking, and ensure lab work is always linked to clinical schedules and downstream financial outcomes. Lab Manager improves reliability, not speed at all costs.

It governs:

- Creating and tracking Lab Cases through a defined, governed lifecycle.
- Maintaining a Primoro-managed Lab Directory and all lab-facing interaction surfaces (portal and email).
- Linking lab cases to patients, treatments, dependent appointments, and financial outcomes, including invoice handling and associate chargeback.

It explicitly does not:

- Own appointment scheduling or appointment-integrity enforcement — those concerns are owned by Appointment Manager.
- Own financial reporting, accounting exports, or associate statement rendering — those concerns are owned by Financial Insights and the relevant finance integration module.
- Own task creation or routing — tasks generated by Lab Manager are owned and managed by Task Manager.

---

## 2. Ownership & Responsibilities

### 2.1 Lab Manager IS Responsible For

- Creating and tracking Lab Cases through a governed lifecycle with every transition timestamped, attributable, and immutable.
- Maintaining a Primoro-managed Lab Directory containing lab identity, contact methods, supported work types, turnaround times, portal availability, and invoicing metadata.
- Providing labs with governed portal or email-only interaction options and capturing all lab communications in a single authoritative timeline.
- Linking Lab Cases to patients, treating clinicians, treatment context, dependent appointments, and expected delivery dates.
- Monitoring SLAs and triggering governed reminders, tasks, and escalations.
- Handling Lab Invoices and posting governed charges for finance export and associate chargeback.
- Exposing read-only `LabRequired` and `LabCaseReference` fields to the Surgery & Decon Day View surface.
- Emitting governed metrics to Performance Dashboards and Financial Insights.

### 2.2 Lab Manager IS NOT Responsible For

- Appointment scheduling or session integrity — owned by Appointment Manager.
- Financial reporting, accounting export rendering, or associate statement generation — owned by Financial Insights.
- Task routing, assignment, or lifecycle management — owned by Task Manager.
- Clinical decision-making of any kind — no lab or system action may substitute for clinical judgement.
- Rendering or visualising the metrics it emits — owned by Performance Dashboards and Financial Insights.

---

## 3. Core Objects (Normative)

### 3.1 Lab Case (Canonical Artefact)

A Lab Case is a governed digital artefact representing one outsourced item of clinical work.

Minimum required fields:

- LabCaseID
- PatientID (FK to patient record)
- ClinicianID (FK to treating clinician)
- TreatmentContext
- DependentAppointmentID(s)
- LabEntityID (FK to Lab Directory Entry)
- ExpectedDeliveryDate
- LabCaseState
- CreatedBy (user/role)
- CreatedAt
- AuditTrail (immutable)

Lab Cases are structured objects and MUST NOT exist as free-text or email-only artefacts.

### 3.2 Lab Case State Machine (Authoritative)

States:

- Created
- Sent to Lab
- Accepted
- On Hold (awaiting practice input)
- Completed (dispatched by lab)
- Received
- Cancelled

Rules:

- Cases MUST NOT bypass states; every transition must follow the declared sequence.
- Overdue is a condition assessed against ExpectedDeliveryDate, not a lifecycle state.
- Every state transition is timestamped, attributable, and immutable in audit history.
- A Lab Case MUST NOT reach Received without either a linked follow-up appointment or an explicit acknowledged exception recorded in the audit trail.

### 3.3 Lab Directory Entry

A Lab Directory Entry is a centrally-managed lab profile containing:

- Lab identity and contact methods
- Supported work types
- Standard turnaround times
- Portal availability flag
- Invoicing and payment metadata

### 3.4 Lab Invoice (Canonical Artefact)

A Lab Invoice is a governed financial object representing one or more completed Lab Cases submitted for payment, forming the basis for finance export and associate chargeback.

Minimum required fields:

- LabInvoiceID
- LabEntityID (FK to Lab Directory Entry)
- LinkedLabCaseID(s)
- LabInvoiceState
- CreatedBy (user/role)
- CreatedAt
- AuditTrail (immutable)

### 3.5 Lab Invoice State Machine (Authoritative)

States:

- Draft
- Submitted by Lab
- Under Practice Review
- Approved
- Exported to Accounting
- Paid (confirmed)
- Associate Charges Posted

Rules:

- Associate deductions MUST occur only after payment confirmation, not on approval.
- Invoice line items MUST reconcile to recorded Lab Cases before the invoice may advance beyond Under Practice Review.
- Every state transition is timestamped, attributable, and immutable in audit history, consistent with the Lab Case state machine rules above.

### 3.6 SLA / Escalation Lifecycle

The following conditions are tracked against each Lab Case but are not lifecycle states of the Lab Case itself:

- SLA Timer Starts — triggered on transition to Accepted
- Reminder Triggered — pre-due date, per configured threshold
- At-Risk — within configured proximity threshold to ExpectedDeliveryDate
- Overdue — ExpectedDeliveryDate passed without Received or Completed
- Escalation Task Created — emitted to Task Manager

---

## 4. Core Capabilities

### 4.1 Case Creation & Update Sources

#### 4.1.1 Practice-Initiated

- Lab Cases may be created from the Web Portal or Surgery Tablet (context-aware).
- Practice staff may perform manual updates: received confirmation, cancellation, and internal notes.

#### 4.1.2 Lab-Initiated

- Labs with portal access may accept cases, update status and due date, upload files, mark cases complete, and submit invoices.
- Labs without portal access interact via secure email: single-use action links (accept / need-info / complete) and inbound email parsing mapped to Lab Cases.
- The shared lab mailbox is the authoritative inbound channel. No lab email MUST bypass Lab Manager capture.

#### 4.1.3 Scanner / Digital Impression-Initiated

- Authorised scanners (e.g. iTero) may automatically create or enrich Lab Cases.
- Digital impression artefacts are attached to the relevant Lab Case.
- Status events from authorised scanners are treated as governed lifecycle updates.

#### 4.1.4 System-Initiated

- SLA reminders and escalations.
- Appointment dependency validation.
- Invoice validation, export triggering, and charge allocation.

### 4.2 SLA Monitoring & Escalation (Authoritative)

The module MUST:

- Start an SLA timer automatically when a Lab Case transitions to Accepted.
- Evaluate SLA status continuously against ExpectedDeliveryDate.
- Trigger pre-due reminders and At-Risk notifications per configured thresholds.
- Emit an escalation task-creation event to Task Manager when a case becomes Overdue. The escalation task is owned and managed exclusively by Task Manager; Lab Manager MUST NOT create, route, assign, or resolve task records autonomously. Lab Manager's responsibility ends at emitting a well-formed task-creation payload containing, at minimum, the LabCaseID, OverdueSince timestamp, assigned ClinicianID, and escalation severity.

The module MAY:

- Allow per-lab or per-case SLA threshold configuration by authorised roles.

The module MUST NOT:

- Resolve or dismiss escalation tasks — that lifecycle is owned by Task Manager.
- Emit independent alerts to staff as a substitute for task creation; all human follow-up on Overdue cases MUST be routed through Task Manager.

### 4.3 Appointment Dependency Validation (Authoritative)

The module MUST:

- Maintain a link between every Lab Case and one or more dependent appointments.
- Expose read-only `LabRequired` (boolean) and `LabCaseReference` (string, nullable) fields to the Surgery & Decon Day View surface for each appointment carrying a lab dependency.
- Ensure `LabRequired` is rendered on both the Decon Wall Tablet and Surgery Tablet appointment headers.
- Where no Lab Case has yet been linked, `LabCaseReference` MUST be null and `LabRequired` MUST default to false.

The module MUST NOT:

- Allow `LabRequired` or `LabCaseReference` to be set or overridden via the Day View interface. Updates to these values originate exclusively from Lab Manager and are consumed by the Day View as governed data.

### 4.4 Invoice & Finance Handling (Authoritative)

The module MUST:

- Validate that invoice line items reconcile to recorded Lab Cases before advancing an invoice beyond Under Practice Review.
- Post associate deductions only after Paid (confirmed) status, not on approval.
- Export approved invoices to the accounting integration on confirmation of payment.

The module MUST NOT:

- Own or render associate statements — that responsibility belongs to Financial Insights.

### 4.5 Metrics Emission

Lab Manager emits the following read-only metrics to Performance Dashboards and Financial Insights:

- Average lab turnaround time
- On-time delivery rate
- Overdue case count
- Re-impression / on-hold rate
- Percentage of lab cases with a follow-up appointment scheduled
- Lab fees (gross, practice share, associate share)

For the purposes of the Performance Dashboards Compliance domain, Lab Manager specifically declares the following turnaround and SLA metrics as its governed output:

- **Average lab turnaround time** — measured in calendar days from the Lab Case transitioning to Sent to Lab through to Received, computed per lab entity and aggregated across the practice. Emitted as an event on each Received transition and available for rolling-period aggregation by Performance Dashboards.
- **On-time delivery rate** — the proportion of Lab Cases that reached Received on or before ExpectedDeliveryDate within a given period, expressed as a percentage. Emitted as a periodic aggregate event.
- **Overdue case count** — a point-in-time count of Lab Cases in an Overdue condition. Emitted on each SLA evaluation cycle.
- **SLA breach events** — individual timestamped events emitted each time a case transitions into the Overdue condition, consumable by Performance Dashboards for trend and cohort analysis.

These signals constitute the authoritative source for lab turnaround rates within the Performance Dashboards Compliance domain. Performance Dashboards MUST NOT derive turnaround metrics from any other source.

Lab Manager MUST NOT analyse or visualise these metrics itself.

---

## 5. Delivery Surfaces & Access (Authoritative)

### 5.1 Web Portal

The practice web portal MUST include:

- Lab case list with status, due date, and appointment dependency.
- At-risk / overdue indicators.
- Filters by lab, clinician, date, and status.
- Full, immutable communication timeline per case.

### 5.2 Tablet App

#### Surgery Tablet

- Today-only lab cases linked to the current session's surgeries.
- Visibility of cases awaiting receipt before sessions.
- Read-only `LabRequired` flag and `LabCaseReference` on appointment headers.
- Read-only confirmation status.

#### Decon Wall Tablet (Surgery & Decon Day View)

- Read-only `LabRequired` flag and `LabCaseReference` on appointment headers.
- Both fields are populated exclusively by Lab Manager; the Day View surface may not write to either field.

##### Day View Signal Contract

The Surgery & Decon Day View is entitled to consume and display the following Lab Manager signals on the `AppointmentDayRow` for any appointment carrying a lab dependency:

- `LabRequired` (boolean) — indicates that the appointment has an associated Lab Case; defaults to `false` when no Lab Case is linked.
- `LabCaseReference` (string, nullable) — the human-readable or system identifier of the linked Lab Case; `null` when no Lab Case is linked.
- `LabCaseState` (read-only enum, nullable) — the current lifecycle state of the linked Lab Case as defined in §3.2, surfaced to allow the Day View to indicate cases that are not yet Received ahead of a session.
- `LabAtRisk` (boolean) — `true` when the linked Lab Case is within the configured At-Risk proximity window relative to ExpectedDeliveryDate; `false` otherwise.
- `LabOverdue` (boolean) — `true` when the linked Lab Case is in an Overdue condition; `false` otherwise.

Lab Manager MUST push updated values for these signals to the Day View surface whenever a relevant Lab Case state transition occurs or an SLA condition changes (At-Risk or Overdue). The Day View MUST NOT poll for these values independently; updates are event-driven from Lab Manager. The Day View surface MUST NOT write to any of these fields; all values are set exclusively by Lab Manager.

### 5.3 Patient Mobile App

*(no content captured in original — needs definition)*

### 5.4 Lab Portal (External, Optional)

External labs with portal access MUST be able to:

- Accept assigned cases.
- Update status and due date.
- Upload files.
- Mark cases complete.
- Submit invoices.

### 5.5 Engagement Signals

Lab Manager emits the following signals for staff visibility:

- At-risk and overdue case indicators surfaced in the web portal and day view.
- Escalation tasks emitted to Task Manager for human follow-up.
- Metrics emitted to Performance Dashboards and Financial Insights (see §4.5).

---

## 6. Integration Contracts

### 6.1 Inbound (this module consumes from)

| From module | What | Contract |
| --- | --- | --- |
| Appointment Manager | Dependent appointment data; appointment scheduling events; appointment-linkage query interface (see §6.1.1) | sync / event |
| Task Manager | Task resolution acknowledgements | event |
| Authorised scanners (e.g. iTero) | Digital impression artefacts and status events | async |

#### 6.1.1 Appointment Manager — Appointment-Linkage Query Interface

Appointment Manager exposes a queryable appointment-linkage interface that Lab Manager MUST use to validate appointment dependencies at Lab Case creation and throughout the case lifecycle. Lab Manager's use of this interface is governed as follows:

- Lab Manager MUST query Appointment Manager for appointment validity (existence, patient match, scheduling status) before associating a `DependentAppointmentID` with a Lab Case.
- Lab Manager MUST consume appointment scheduling events from Appointment Manager (e.g. cancellation, rescheduling) and re-evaluate `LabRequired` and `LabCaseReference` propagation accordingly.
- Lab Manager MUST NOT write to appointment records; all appointment data consumed via this interface is read-only.
- If Appointment Manager returns an appointment as cancelled or no longer schedulable, Lab Manager MUST flag the linked Lab Case for practice review and MUST NOT silently retain a stale appointment link.
- The query contract (endpoint shape, payload schema, and versioning) is owned by Appointment Manager; Lab Manager MUST conform to the declared interface version and MUST NOT infer appointment state from any other source.

### 6.2 Outbound (this module emits to)

| To module | What | Contract |
| --- | --- | --- |
| Appointment Manager | `LabRequired` flag and `LabCaseReference` for appointment headers | sync / read-only |
| Task Manager | Escalation and follow-up task-creation event payloads (LabCaseID, OverdueSince, ClinicianID, severity) | event |
| Communication Hub | Lab notification triggers (reminders, escalations, confirmations) | event |
| Financial Insights | Lab fee metrics (gross, practice share, associate share) | event / read-only |
| Performance Dashboards | SLA and turnaround metrics (average turnaround time, on-time delivery rate, overdue case count, SLA breach events — see §4.5) | event / read-only |
| Audit & Compliance | Immutable audit log events for all state transitions and interactions | event |

### 6.3 External Provider API Gateway & Rate Governance

All outbound API calls from Lab Manager to external lab providers (including case creation submissions, result and status retrieval, invoice exchange, and digital impression transfers) MUST be routed through the External Provider API Gateway & Rate Governance layer. Lab Manager MUST NOT call external lab provider endpoints directly.

Lab Manager declares the following traffic classifications for rate governance purposes:

- **Case lifecycle interactions** (case submission, status updates, completion receipt) — standard priority; subject to per-provider rate limits as configured in the gateway.
- **Invoice exchange** (invoice submission, payment confirmation retrieval) — standard priority; subject to per-provider rate limits.
- **Digital impression / file transfer** (artefact upload and retrieval for scanner integrations) — bulk/background priority; MUST be scheduled to avoid contention with case lifecycle interactions during peak session periods.

The following rules govern the interaction between SLA monitoring (§3.6) and provider rate limits:

- If a provider API call required to progress a Lab Case (e.g. status retrieval or acceptance confirmation) is throttled or returns a rate-limit response, Lab Manager MUST NOT treat the absence of a response as an implicit state transition or SLA trigger.
- Throttled calls MUST be retried by the gateway per its declared retry policy; Lab Manager MUST consume the eventual success or terminal failure response before updating Lab Case state.
- If a throttle condition persists beyond a configurable timeout threshold, Lab Manager MUST flag the affected Lab Case as requiring manual review and MUST emit an At-Risk SLA signal where the associated ExpectedDeliveryDate is within the at-risk window.
- SLA timers (§3.6) MUST NOT be paused or reset solely on account of a throttle condition; the SLA clock continues against ExpectedDeliveryDate regardless of gateway state.

### 6.4 PMS Boundary

Lab Manager owns the governed Lab Case lifecycle and all lab-facing interactions within Primoro. The PMS is the source of patient and appointment record truth; Lab Manager consumes patient and appointment identifiers from the PMS but does not write back to PMS appointment or patient records directly. Financial exports originating from Lab Manager flow through the declared accounting integration, not through the PMS billing layer.

Any PMS integration for lab-adjacent data (e.g. treatment plans) is consumed read-only by Lab Manager; Lab Manager does not modify PMS clinical records.

---

## 7. AI Boundaries (Non-Negotiable)

Module does not embed AI surfaces directly.

Should AI capabilities be added in a future version, the following constraints apply as a floor:

AI MAY:

- Summarise lab case activity for staff review.
- Suggest escalation actions from approved workflows, with explicit human approval before commit.

AI MAY NOT:

- Auto-decide on SLA policy actions or invoice approvals.
- Bypass governance, audit, or access checks.
- Make commitments to labs or patients on behalf of the practice.
- Replace required clinical judgement at any stage of the lab case lifecycle.

---

## 8. Audit & Compliance

The system MUST log:

- All Lab Case state transitions, with actor identity, role, and timestamp.
- All Lab Invoice state transitions, with actor identity, role, and timestamp.
- All lab and staff interactions recorded against the Lab Case communication timeline.
- All SLA evaluations, including threshold triggers, at-risk assessments, and overdue events.
- Invoice approvals, payment confirmations, and associate charge allocations.
- All cross-module events emitted or consumed (escalation tasks, appointment dependency updates, finance exports).
- All exceptions acknowledged when a Lab Case reaches Received without a linked follow-up appointment.
- All rate-limit or throttle responses received from the External Provider API Gateway, including the affected LabCaseID, provider, timestamp, and resolution outcome.

Audit logs MUST be immutable and exportable for inspection. No lab or financial interaction MUST occur without attribution.

---

## 9. Access Control

Role-based access is managed via Access Manager. Roles are tenant-scoped and fully auditable.

| Role | Create | Read | Update | Approve/Promote | Delete/Cancel |
| --- | --- | --- | --- | --- | --- |
| Lab Coordinator | ✓ | ✓ | ✓ | — | ✓ (cancel only) |
| Clinician | — | Own cases only | — | — | — |
| Practice Manager | ✓ | ✓ | ✓ | ✓ (cases, SLAs) | ✓ (cancel only) |
| Finance Role | — | ✓ | — | ✓ (invoices) | — |
| Lab User (External) | — | Assigned cases only | Assigned cases only | — | — |

MFA requirements for sensitive operations (invoice approval, associate charge posting) are governed by Access Manager policy and are not overridden by Lab Manager.

---

## 10. Integration Summary

- **Appointment Manager** — bidirectional: consumes appointment data via the appointment-linkage query interface (§6.1.1) and scheduling events; exposes `LabRequired` and `LabCaseReference` read-only fields to the Day View surface.
- **Task Manager** — outbound: escalation and follow-up task-creation event payloads; task lifecycle is owned exclusively by Task Manager.
- **Communication Hub** — outbound: lab notification triggers (reminders, escalations, confirmations).
- **Financial Insights** — outbound: lab fee metrics (gross, practice share, associate share), read-only.
- **Performance Dashboards** — outbound: SLA and turnaround metrics (average turnaround time, on-time delivery rate, overdue case count, SLA breach events), read-only.
- **Access Manager** — RBAC for all read/write/approve operations, tenant-scoped.
- **Audit & Compliance** — outbound: immutable event log for all state transitions and interactions.
- **External Provider API Gateway & Rate Governance** — all outbound calls to external lab providers are routed through the gateway; rate governance and retry policy are owned by the gateway (§6.3).

---

## 11. Explicit Non-Goals

- **Appointment scheduling** — Lab Manager surfaces appointment dependency risk indicators but does not schedule or reschedule appointments. Owned by Appointment Manager.
- **Associate statement generation** — Lab Manager posts chargeback data but does not render or distribute associate statements. Owned by Financial Insights.
- **Task lifecycle management** — Lab Manager creates escalation task-creation event payloads but does not own task routing, reassignment, or resolution. Owned by Task Manager.
- **Metric visualisation** — Lab Manager emits metrics but does not build dashboards or charts. Owned by Performance Dashboards and Financial Insights.
- **Clinical decision support** — No lab status or system action may substitute for clinical judgement.
- **Direct external provider API calls** — Lab Manager does not call external lab provider endpoints directly; all such calls are routed through the External Provider API Gateway & Rate Governance layer.

---

## 12. Versioning & Governance

This specification is owned by: Operations Suite module owner.

Changes to this spec require:

- Review by the Post-MVP module owner.
- Impact analysis across declared related modules (see §10).
- Version bump (patch / minor / major depending on scope of change).

---

## 13. Build Contract (Engineering & QA)

### 13.1 Canonical Data Model

*(Canonical schema to be finalised by engineering in alignment with §3. Minimum fields are normatively declared in §3.1 and §3.4. No additional schema fields are specified here to avoid fabrication.)*

### 13.2 Core Behaviour Rules

1. Every Lab Case MUST be linked to a patient, treating clinician, treatment context, at least one dependent appointment, a lab entity, and an expected delivery date at creation.
2. A Lab Case MUST NOT bypass declared lifecycle states; every transition must follow the sequence defined in §3.2.
3. Overdue is a computed condition assessed against ExpectedDeliveryDate; it MUST NOT be stored as a lifecycle state.
4. A Lab Case MUST NOT transition to Received unless either a linked follow-up appointment exists or an explicit acknowledged exception is recorded in the audit trail.
5. The SLA timer MUST start automatically when a Lab Case transitions to Accepted.
6. Escalation task-creation event payloads MUST be emitted to Task Manager when a case becomes Overdue; Lab Manager does not own the task lifecycle. Lab Manager MUST NOT create, route, or resolve task records independently.
7. `LabRequired` and `LabCaseReference` MUST be read-only from the Surgery & Decon Day View surface; writes to these fields originate exclusively from Lab Manager.
8. `LabRequired` MUST default to false and `LabCaseReference` MUST be null when no Lab Case has been linked to an appointment.
9. Lab Invoice line items MUST reconcile to recorded Lab Cases before the invoice may advance beyond Under Practice Review.
10. Associate deductions MUST be posted only after a Lab Invoice reaches Paid (confirmed), not on Approved.
11. No lab or financial interaction MUST occur without a complete attribution record in the audit log.
12. All lab communications (portal and email) MUST be captured in the Lab Case communication timeline; no lab interaction may bypass Lab Manager.
13. Status events from authorised scanners (e.g. iTero) MUST be treated as governed lifecycle updates and attached to the relevant Lab Case.
14. All outbound calls to external lab providers MUST be routed through the External Provider API Gateway & Rate Governance layer. A throttle or rate-limit response MUST NOT be treated as an implicit state transition; SLA timers MUST continue to run during throttle conditions.
15. Lab Manager MUST query Appointment Manager via the appointment-linkage query interface before associating a DependentAppointmentID with a Lab Case; stale or cancelled appointment links MUST NOT be retained silently.
16. The `LabCaseState`, `LabAtRisk`, and `LabOverdue` signals MUST be pushed to the Day View surface on each relevant state transition or SLA condition change; the Day View MUST NOT poll for these values.

### 13.3 Configuration Surfaces

- **Practice-level settings (Admin Control Plane):** SLA thresholds (reminder lead time, at-risk window), portal availability per lab, accounting export triggers, rate-limit timeout threshold for external provider gateway interactions.
- **Per-user preferences (Access Manager):** Role assignments, tenant-scoped RBAC configuration.
- **Per-Lab Case overrides (Lab Manager):** Explicit exception acknowledgement when receiving a case without a linked follow-up appointment.

### 13.4 Filtering & Views

The web portal MUST support filtering Lab Cases by:

- Lab entity
- Treating clinician
- Status
- Date range (created, due, received)
- At-risk / overdue condition

Saved views for common filters (e.g. "Overdue today", "Awaiting receipt this week") MAY be supported as a configurable feature in a future iteration; this is not a requirement for initial build.

### 13.5 Module Extension Map

- Scanner integrations beyond iTero MAY be added by registering additional authorised scanner sources without breaking the Lab Case creation contract.
- Additional lab interaction methods (beyond portal and email) MAY be added as governed interaction channels without altering the Lab Case lifecycle.
- Additional metric signals MAY be emitted to Performance Dashboards without altering core state machine behaviour.
- Additional external provider integrations MAY be registered with the External Provider API Gateway under new traffic class declarations without altering the Lab Case lifecycle or SLA contracts.
- All extensions MUST preserve the audit, RBAC, and state machine contracts declared in this specification.

### 13.6 Acceptance Criteria

The build of Lab Manager is complete when:

- [ ] All Lab Cases can be created, read, and updated through the API with minimum required fields enforced.
- [ ] Lab Case state machine transitions enforce all rules in §3.2 and §13.2.
- [ ] Lab Invoice state machine transitions enforce all rules in §3.5 and §13.2.
- [ ] A Lab Case cannot reach Received without a linked follow-up appointment or an acknowledged exception in the audit log.
- [ ] SLA timers start automatically on Accepted and trigger reminders, at-risk flags, and escalation task-creation event payloads per configured thresholds.
- [ ] All integrations in §6 are wired and verified, including the Appointment Manager appointment-linkage query interface and the External Provider API Gateway routing.
- [ ] `LabRequired`, `LabCaseReference`, `LabCaseState`, `LabAtRisk`, and `LabOverdue` are correctly exposed to and rendered on both the Decon Wall Tablet and Surgery Tablet appointment headers in the Surgery & Decon Day View, and cannot be written from that surface.
- [ ] Day View signal updates are pushed event-driven from Lab Manager on state transitions and SLA condition changes; the Day View does not poll.
- [ ] All lab communications (portal and email, including scanner events) are captured in the Lab Case communication timeline.
- [ ] Lab Invoice line items reconcile to Lab Cases before advancing beyond Under Practice Review.
- [ ] Associate deductions are posted only after Paid (confirmed) status.
- [ ] Throttle/rate-limit responses from the External Provider API Gateway do not trigger implicit state transitions; SLA timers continue to run during throttle conditions, and affected cases are flagged for manual review on timeout.
- [ ] Escalation tasks are emitted exclusively as task-creation event payloads to Task Manager; Lab Manager does not create, route, or resolve task records autonomously.
- [ ] Turnaround and SLA metrics (average turnaround time, on-time delivery rate, overdue case count, SLA breach events) are emitted to Performance Dashboards per the contract in §4.5.
- [ ] AI boundaries in §7 are enforced (negative tests pass).
- [ ] Audit log captures every event in §8 with full attribution, including gateway throttle events.
- [ ] Access control is enforced per §9 for all roles.
- [ ] All non-functional requirements in §14 are met.

---

## 14. Non-Functional Requirements

- **Performance:** Status changes and SLA evaluations MUST propagate in near-real-time. Web portal list views MUST load within an acceptable latency target to be agreed with engineering at build kick-off.
- **Reliability:** Offline capture on the Surgery Tablet MUST be supported with deterministic replay when connectivity is restored. The module MUST degrade gracefully under connectivity loss — no lab case data MUST be silently dropped.
- **Scalability:** Lab Manager MUST support multi-site, multi-tenant operation with strict tenant isolation. A single practice's lab case volume MUST not degrade performance for other tenants.
- **Security:** Strict tenant isolation MUST be enforced at the data layer. Files and communications MUST be encrypted at rest and in transit. RBAC is enforced via Access Manager with no bypass paths. Secure email action links MUST be single-use and expire after a defined period to be agreed at build kick-off.
- **Privacy:** Lab Cases are patient-bound records subject to applicable data protection regulations. The module MUST honour patient data access and erasure rights as defined by the platform's GDPR compliance policy, including audit log retention periods.
- **Observability:** Lab Manager MUST export structured logs and trace events for all state transitions, integration calls, and SLA evaluations. Metrics emitted to Performance Dashboards (§4.5) constitute the primary operational signal. Alerting on Overdue case counts and escalation task emission rates MUST be available to platform operators. Gateway throttle events and retry outcomes for external provider calls MUST be included in structured logs.

---

## 15. Open Questions

> Outstanding decisions before this spec can be promoted from `draft` to `published`.

1. **Offline replay behaviour:** The original states that offline capture on the tablet is supported with replay, but does not define conflict-resolution behaviour if a lab case is updated remotely while the tablet is offline. What is the authoritative conflict resolution strategy?
2. **SLA threshold defaults:** The spec requires SLA monitoring and configurable thresholds but does not specify default reminder lead times or at-risk window values. What are the platform defaults?
3. **Lab portal availability:** The Lab Portal is described as optional. What determines whether a given lab is offered portal access vs. email-only — is this a practice-level configuration, a lab-level configuration, or both?
4. **Secure email link expiry:** Single-use secure action links are required for email-only lab interactions but no expiry period is specified. What is the expiry policy for these links?
5. **Associate chargeback rules:** The spec states deductions follow paid invoices, but does not define the chargeback calculation method or whether it is configurable per associate or per lab. This is needed before the finance integration can be built.
6. **Lab Case cancellation rules:** Cancellation is a valid terminal state but no rules are specified for who may cancel, under what conditions, and whether a cancelled case can be superseded by a new case. These rules must be defined before the state machine can be fully implemented.
7. **External provider gateway traffic class defaults:** The rate governance traffic classifications declared in §6.3 require per-provider rate limit values to be configured in the gateway. Who owns the initial configuration of these limits, and what are the platform defaults for case lifecycle vs. file transfer interactions?

Live preview