# Verixa — User Requirements Specification
# Module 14: Complaints
| Field | Value |
|---|---|
| Document ID | VRX-URS-14 |
| Version | 1.0 |
| Status | Final — ready for QA, Validation, Regulatory Affairs, Information Security, Pharmacovigilance, Customer Quality Manager, and Founder approval. URS approval is separate from validation execution. This document becomes "Approved Controlled URS — released for engineering implementation and validation planning" only after signature capture in the Document Approval block. It becomes "Released for validation execution" only after the module migration evidence gate (URS-14-VAL-008) and validation evidence pack are satisfied. |
| Document Type | User Requirements Specification (URS) |
| GAMP 5 Category | Category 5 — Custom Application |
| Code Modules | Target implementation binding: expected primary code module `complaints`. Expected API mount `/api/v1/complaints`. Expected route / service / schema / type / DB-schema / context-filter / authority-hook ownership within the `complaints` module. Implementation evidence remains subject to repository verification and validation evidence. |
| Architecture Bindings | Verixa treats **EU GMP Annex 22 (Draft 2025)** as an internal forward-looking architectural control for AI governance; it is not cited as an enacted predicate rule. Under that internal control, adverse-event reportability decisions, recall initiation decisions, and field-alert issuance decisions on a regulated product **PROHIBIT** LLM / generative-AI use in the decision path. Static deterministic AI may be used in advisory roles (complaint classification suggestion, similarity / signal detection, trend surfacing) under internal AI governance aligned with EU AI Act Article 13 transparency principles, governed by ARCH-AI-001 AC-1..AC-7 (manual primary path, advisory secondary, visible advisory labelling, no autonomous write to system of record, full AI audit trail, override capability, graceful degradation). No AI service may be the sole path to triage, classify, investigate, respond to, escalate, recall, or close a complaint. Jurisdiction-specific legal enforceability of Annex 22 and the EU AI Act remains subject to a future jurisdiction-specific legal assessment. |
| Regulatory Classification | Critical infrastructure substrate — operates the canonical Complaints register, the complaint lifecycle state machine, the complaint classification taxonomy, the investigation workflow with deviation / RCA / CAPA linkage, the adverse-event capture and pharmacovigilance escalation, the customer-response approval and issuance, the field-alert workflow with regulator notification, the recall initiation and execution workflow, the complaint similarity / signal / trend analytics surface, and the cross-module linkage to documents, products, suppliers, batches, deviations, OOS/OOT, RCA, CAPA, findings, inspections, regulatory submissions, and URS-13. |
| Date of Issue | 2026-05-06 |
| Module Owner (Engineering) | Complaints / Field Action Squad |
| Module Owner (Quality Validation) | CSV / CSA Lead — Complaints |
| Module Owner (Compliance) | Quality Assurance, Regulatory Affairs, Pharmacovigilance, Customer Quality Manager |
| Approving Authority | Founder / Chairman & MD; QA Head; Validation Head; RA Head; PV Head; Information Security Head; Customer Quality Manager |
---
## 0. Document Framing
### 0.1 Purpose of this document
This URS defines the target expected state for Verixa's Complaints module (Module 14). It is the binding contract between product, engineering, quality validation, regulatory affairs, pharmacovigilance, customer quality, manufacturing, supply chain, information security, and the executive authority for the design, implementation, validation, release, and on-going periodic review of the regulated complaints-handling substrate: the canonical complaint register; the complaint lifecycle state machine (`received → triaged → under_investigation → field_action_pending → pending_response → response_issued → closed`, plus terminal `rejected_invalid` and intermediate `reopened`); the complaint classification taxonomy with controlled subcategories; the investigation workflow with deviation / RCA / CAPA linkage and SoD enforcement; the adverse-event capture with PV review, reportability assessment, and authority-gated FDA MedWatch / EMA EudraVigilance / MHRA Yellow Card / Health Canada / PMDA escalation; the customer-response drafting, approval, and issuance with watermarked external letter export; the field-alert workflow with FDA Field Alert Report governance; the recall initiation, classification (Class I / Class II / Class III), execution, and effectiveness verification with regulatory notification; the complaint similarity / signal / trend analytics surface (advisory only per ARCH-AI-001); the closure prerequisites with non-bypassable workflow gates; and the cross-module linkage to URS-10 products, URS-11 suppliers, URS-12 documents, URS-13 records, URS-16 deviations, URS-17 RCA, URS-18 CAPA, URS-21 findings, URS-23 batch records, URS-27 regulatory submissions, and URS-30 notifications. Compliance with this URS is mandatory.
### 0.2 Audience
Engineering, QA, Validation, Regulatory Affairs, Pharmacovigilance, Customer Quality, Manufacturing, Supply Chain / Distribution, Information Security, executive authority, the platform's Implementation team, internal and external auditors, and inspectors from regulatory bodies (FDA, EMA, MHRA, Health Canada, CDSCO, PIC/S, PMDA). The plain-language primer (§0.4) and worked examples (§3.5) make Module 14 accessible to non-domain engineers, product owners, validation engineers, customer-quality coordinators, and PV specialists.
### 0.3 How to read this document
Each requirement has a unique identifier. "MUST" denotes a mandatory requirement; "SHOULD" denotes a strong recommendation; "MAY" denotes an option. The document is self-contained: front end (§5), back end (§6), data model (§6.2), application programming interface (§6.3), workflow (§6.4), business rules (§6.5), audit (§6.6), security (§12), regulatory mapping (§14), test cases (§16), and validation evidence (§17) are all in this single file. Every requirement is mandatory unless explicitly marked SHOULD (strong recommendation) or MAY (option).
### 0.4 Plain-language primer for non-domain readers
In a regulated pharmaceutical operation, **a customer complaint is a regulatory event**, not just a service-quality issue. When a patient, prescriber, dispensing pharmacist, hospital, distributor, or care-giver reports a problem with a marketed product — broken tablet, suspected adulteration, foreign particle, suspected lack of efficacy, suspected counterfeiting, suspected adverse reaction, packaging defect, labelling error, temperature excursion, suspected contamination — the marketing authorisation holder is obligated by **21 CFR Part 211.198 (Complaint Files), 21 CFR Part 314.80 (Postmarketing reporting of adverse drug experiences), EU GMP Chapter 8 (Complaints, Quality Defects and Product Recalls), ICH Q10, ICH E2D (Post-Approval Safety Data), MHRA Yellow Card Scheme, Health Canada Vigilance, and PMDA reporting requirements** to record the complaint, evaluate it, investigate it, decide whether the product is implicated, decide whether the complaint reflects a quality defect that requires field action (field alert, recall) or a safety signal that requires pharmacovigilance reporting, respond to the complainant, and close the complaint with documented disposition. Module 14 is the target specification for this regulated workflow.
A **complaint** is the regulated record. It is created by intake (call centre, web form, email, fax, paper-form, regulator notification, distributor escalation), captures the complainant identity (with privacy / GDPR controls), the product implicated (URS-10), the lot / batch (URS-23), the symptom / observation, the date of receipt, the priority (Standard / Expedited / Critical), and starts in `received` state. The intake user enters initial details; the platform assigns a tenant-and-year-scoped server-authoritative complaint number per CMP-014 (e.g., `CMP-2026-000123`).
In **triage**, a customer-quality reviewer evaluates whether the complaint is valid (related to a registered product, with sufficient information to investigate), classifies it via the controlled `complaint_classifications` taxonomy (e.g., "particulate matter — drug substance", "broken tablet — packaging", "labelling error — secondary pack", "suspected adverse reaction — efficacy"), assesses initial PV implications (any indication of adverse event), assesses initial field-action implications (any indication of broader product issue), and decides routing. SoD enforced: the intake user cannot also be the triage reviewer.
If the complaint indicates a **quality defect**, an **investigation** is opened. The investigation links to existing URS-16 deviation records (if a manufacturing deviation is the suspected cause), to URS-17 RCA records (if a deeper investigation is needed), and may produce a URS-18 CAPA. The investigation captures the root-cause analysis, the disposition (e.g., "isolated event — no field action", "manufacturing defect — field alert + recall recommended"), and is signed.
If the complaint indicates an **adverse event** (suspected adverse drug reaction, suspected lack of efficacy with safety implication, suspected drug-drug interaction with adverse outcome, suspected counterfeit causing harm), the **pharmacovigilance** workflow opens. The PV reviewer assesses **reportability** under jurisdictional rules: FDA 21 CFR §314.80 (15-day expedited for serious / unexpected; periodic for non-serious), EMA EudraVigilance ICSR (15-day for serious; 90-day for non-serious; 7-day for fatal / life-threatening), MHRA Yellow Card (UK), Health Canada Vigilance (Canada), PMDA AE reporting (Japan), CDSCO (India). The PV reviewer signs a reportability decision; reportable events are escalated to the named PV authority for FDA MedWatch / EudraVigilance / Yellow Card submission per URS-27. Per **EU GMP Annex 22 / DEC-14-18**, the reportability decision **prohibits** generative / probabilistic AI in the decision path; static deterministic AI may suggest reportability based on jurisdictional rules but the human reviewer's signed decision is the system of record.
A **customer response** is drafted by the customer-quality team, reviewed and approved by the named approver per the response approval matrix, and issued to the complainant via the chosen channel (letter, email). The response is watermarked, the issuance event is e-signed and recorded, and an externally-issued response copy is preserved with hash for audit. SoD enforced: the response drafter cannot be the response approver.
A **field alert** (FDA 21 CFR §314.81 Field Alert Reports, NDA / ANDA holders) is issued when a complaint indicates a significant problem affecting a marketed batch (incident of bacterial contamination, significant chemical / physical / biological / microbiological change in a marketed batch, mix-up of containers / labels). The field alert is FDA-reportable within 3 working days of the awareness event. Module 14 captures the field alert with **complaint linkage preserved** , regulatory submission via URS-27, and authority-gated approval.
A **recall** (FDA 21 CFR §7, EU GMP Chapter 8 §8.21-8.25, MHRA, Health Canada, PMDA) is initiated when a complaint or quality defect indicates the marketed product needs to be removed from the market. Recall **classification** per FDA: Class I (reasonable probability of serious adverse health consequences or death), Class II (temporary or medically reversible adverse health consequences, or remote probability of serious health consequences), Class III (not likely to cause adverse health consequences). Recall workflow includes: initiation, regulatory notification (FDA / EMA / MHRA / Health Canada / PMDA / CDSCO), customer / distribution channel notification per URS-30, recovery / quarantine / destruction execution, effectiveness verification, and closure. The recall is **complaint-linked** . Recall initiation requires executive authority co-sign per DEC-14-21.
The complaint **closure** is non-bypassable: closure cannot occur until investigation is complete, response is issued, field action (if any) has been initiated, PV reportability decision (if any) has been signed, and the closure attestation is e-signed by the named closure authority. SoD-14-07 enforced: closure authority cannot be the original intake user.
Complaint **similarity / signal detection** is an **advisory** surface (per ARCH-AI-001 AC-2): the platform may surface "this complaint resembles N prior complaints in the last 90 days" using static deterministic similarity scoring on the `complaint_embedding` vector (per CMP-016). The advisory is visibly labelled "AI-suggested — requires human review"; the human signal-assessment decision is the system of record. Per Annex 22 / DEC-14-18, generative AI is prohibited in the trend / signal decision path; only static deterministic surfacing is permitted.
Module 14 is the **substrate that converts a customer voice into a controlled regulatory record**, and the **substrate that triggers field action and pharmacovigilance reporting** when product or safety signals warrant it. Inspectors review the complaint register routinely; the complaint history is one of the first artefacts requested in any inspection of a marketed product.
### 0.5 Complaint lifecycle diagram
```mermaid
stateDiagram-v2
state "Complaint Lifecycle" as CMPLC {
[*] --> received : Intake creates complaint
received --> triaged : Customer-quality reviewer triages (SoD-14-01)
triaged --> under_investigation : Investigation opened
triaged --> rejected_invalid : Reviewer determines complaint invalid (terminal pre-investigation)
triaged --> pending_response : No investigation needed (e.g., information request)
under_investigation --> pending_response : Investigation complete + signed
under_investigation --> field_action_pending : Investigation indicates field alert / recall
field_action_pending --> pending_response : Field action initiated; response drafting
pending_response --> response_issued : Response approved + e-signed + issued (SoD-14-04)
response_issued --> closed : Closure prerequisites satisfied + closure e-signed (SoD-14-07)
closed --> reopened : executive authority co-sign + reason (DEC-14-22)
reopened --> under_investigation : Re-evaluation
rejected_invalid --> [*]
closed --> [*]
note right of under_investigation
Linkage: deviation_id (URS-16),
RCA (URS-17), CAPA (URS-18)
end note
note right of field_action_pending
Field alert per CMP-006
Recall per CMP-007 (executive authority co-sign DEC-14-21)
end note
note right of pending_response
PV reportability decision (if AE)
signed before response issuance
end note
}
```
Diagram 0.5-A — Complaint lifecycle. Every transition is electronically signed; SoD enforced at intake-vs-triage, drafter-vs-approver-of-response, intake-vs-closure boundaries; field action and recall are non-bypassable for complaints with quality-defect or safety findings; reopen requires executive authority co-sign per DEC-14-22.
### 0.6 Glossary of key terms used in this document
| Term | Definition |
|---|---|
| Adverse Event (AE) | Suspected adverse drug reaction, lack of efficacy with safety implication, suspected drug-drug interaction, suspected harm from counterfeit / adulterated / contaminated product. |
| Annex 22 | EU GMP Annex 22 (Draft 2025) governing AI in pharmaceutical manufacturing; prohibits generative / probabilistic AI in critical safety / quality decisions. |
| ARCH-AI-001 | Platform architecture binding requiring manual continuity for every AI surface (AC-1..AC-7). |
| Class I Recall (FDA) | Recall where there is a reasonable probability that use will cause serious adverse health consequences or death. |
| Class II Recall (FDA) | Recall where use may cause temporary or medically reversible adverse health consequences, or remote probability of serious adverse consequences. |
| Class III Recall (FDA) | Recall where use is not likely to cause adverse health consequences. |
| Closed | Terminal complaint state after closure prerequisites satisfied + closure e-signed (SoD-14-07). |
| Complaint | Regulated complaint record per 21 CFR §211.198 / EU GMP Chapter 8. |
| Complaint Classification | Controlled taxonomy entry mapping the complaint to a regulated category. |
| ECTSE | EudraVigilance Common Technical Standard for ICSR — reporting format for EMA. |
| EudraVigilance | EU centralised pharmacovigilance database for ICSR reports. |
| Field Action | Generic term for field alert OR recall (regulator-notified product action). |
| Field Alert Report (FAR) | FDA 21 CFR §314.81 report from NDA / ANDA holder for significant batch problems. |
| ICSR | Individual Case Safety Report — the per-AE reporting unit for PV. |
| MedWatch | FDA's safety information and adverse event reporting program. |
| PV (Pharmacovigilance) | The science / activity of detection, assessment, understanding, and prevention of adverse effects or other drug-related problems. |
| Reportability | The PV-reviewer-signed decision that an AE meets jurisdictional reporting thresholds. |
| Reopened | executive-authority-co-signed governed transition from `closed` back to `under_investigation`. |
| Recall | Removal of a marketed product from the market; classified per FDA / EMA / MHRA / regional rules. |
| Recall Initiation | The signed decision to initiate a recall; executive authority co-sign required per DEC-14-21. |
| Triage | The customer-quality-reviewer-signed step that validates the complaint and routes it. |
| Yellow Card | UK MHRA voluntary AE reporting scheme. |
### 0.7 Module 14 architectural picture
```mermaid
graph LR
subgraph M14 [Module 14 — Complaints]
CMP[Complaint Registry
code: complaints]
CMPLC[Complaint Lifecycle]
CLASS[Complaint Classifications]
INV[Investigations
complaint_investigations]
AE[Adverse Events + PV
adverse_events]
RESP[Customer Responses
complaint_responses]
FA[Field Alerts
field_alerts
complaint_id PRESERVED CMP-006]
REC[Recall Initiations
recall_initiations
complaint_id PRESERVED CMP-007]
SIM[Similarity / Signal / Trend
complaint_embedding
advisory only]
AUTH[Authority + SoD + E-Sign]
end
M01[URS-01 Auth] --> AUTH
M02[URS-02 RBAC] --> CMP
M03[URS-03 Active Scope] --> CMP
M04[URS-04 Workflow / E-Sign] --> AUTH
M05[URS-05 Authority Profiles] --> AUTH
M06[URS-06 Audit Substrate] <-- CMP
M10[URS-10 Product] --> CMP
M11[URS-11 Supplier] --> CMP
M12[URS-12 Documents] --> CMP
M13[URS-13] --> CMP
M16[URS-16 Deviations] <--> INV
M17[URS-17 RCA] <--> INV
M18[URS-18 CAPA] <--> INV
M21[URS-21 Findings] <-- CMP
M22[URS-22 Inspection Mgmt] <-- CMP
M23[URS-23 Batch Records] --> CMP
M27[URS-27 Reg Intelligence] <-- AE
M27 <-- FA
M27 <-- REC
M30[URS-30 Notifications] <-- CMPLC
ANNEX22[Annex 22 GenAI prohibition in critical safety / quality decisions] -.governs.-> AE
ANNEX22 -.governs.-> FA
ANNEX22 -.governs.-> REC
ARCHAI[ARCH-AI-001 advisory AI] -.governs.-> SIM
```
Diagram 0.7-A — Module 14 architectural picture. The target `complaints` code module is the expected owner of the registry, lifecycle, classifications, investigations (with cross-linkage to URS-16/17/18), adverse-event PV workflow, customer responses, field alerts (linkage preserved per CMP-006), recall initiations (linkage preserved per CMP-007), and similarity / signal / trend advisory surface; ownership is target binding and remains subject to repository verification and validation evidence. Verixa treats EU GMP Annex 22 Draft 2025 and EU AI Act high-risk / transparency concepts as internal forward-looking AI governance controls unless a jurisdiction-specific legal assessment determines otherwise; under the internal control, generative AI is prohibited in adverse-event reportability, field-alert issuance, and recall classification decision paths. ARCH-AI-001 governs advisory deterministic AI. Binding predicate-rule obligations remain those listed in §14.
---
## 1. Module Purpose
Module 14 establishes Complaints as the canonical substrate for "every customer complaint about a marketed product" in Verixa. It owns the complaint master registry, the complaint lifecycle state machine, the classification taxonomy, the investigation workflow with deviation / RCA / CAPA linkage, the adverse-event capture with pharmacovigilance review and reportability assessment, the customer-response approval and issuance, the field-alert workflow with regulator notification, the recall initiation / classification / execution / effectiveness verification, the similarity / signal / trend advisory surface, the closure prerequisites, and the cross-module linkage to products, suppliers, documents, batches, deviations, RCAs, CAPAs, findings, inspections, and regulatory submissions. Module 14 is consumed by URS-21 (complaint findings precipitate Findings), URS-22 (complaints inform inspection readiness), and triggers URS-13 records when complaints precipitate changes (e.g., labelling change required by complaint, packaging change, specification change).
Module 14 is the **single source of truth for "show me the complaint, the investigation, the response, the field action, and the closure"** — a routine inspector's first request when reviewing a marketed product.
---
## 2. Scope
### 2.1 In scope
#### Complaint Registry
- The complaint master registry per DEC-14-01: per-tenant registry with `id`, `tenant_id`, `complaint_number` (server-authoritative `CMP-{YYYY}-{nnnnnn}` per CMP-014), `priority` (`standard` / `expedited` / `critical`), `status` (lifecycle state per DEC-14-02), `received_date`, `received_via` (channel: `phone` / `email` / `web` / `fax` / `paper` / `regulator` / `distributor`), `complainant_identity_jsonb` (PII-tokenised per privacy policy), `complainant_contact_jsonb`, `product_id` (FK URS-10), `batch_id` (FK URS-23 nullable), `lot_number` (text nullable for unstructured complaints), `symptom_description`, `incident_date` (nullable), `discovery_date`, `study_id` (FK URS-07 nullable; per CMP-011 must be consistent across schema/type/persistence), `created_by` / `updated_by`, `created_at` / `updated_at`, `complaint_embedding` (vector for similarity per CMP-016).
- Complaint number per CMP-014: server-authoritative, tenant-and-year-scoped, monotonic.
#### Complaint Lifecycle
- Lifecycle state machine per DEC-14-02: `received → triaged → under_investigation → field_action_pending | pending_response → response_issued → closed`, plus `triaged → rejected_invalid` (terminal pre-investigation), `triaged → pending_response` (no-investigation path for information-request complaints), `closed → reopened → under_investigation` (executive authority co-sign per DEC-14-22).
- Each transition is electronically signed; all transitions log to URS-06 audit substrate.
#### Complaint Classifications
- Controlled `complaint_classifications` taxonomy per DEC-14-03 with `id`, `tenant_id`, `code`, `display_label`, `category` (`quality_defect` / `adverse_event` / `efficacy` / `packaging` / `labelling` / `dispensing` / `storage_temperature_excursion` / `counterfeit` / `tampering` / `service`), `subcategory_jsonb`, `default_priority`, `pv_implication_default` (boolean default false), `field_action_implication_default` (boolean default false), `requires_pv_assessment` (boolean), `requires_field_action_assessment` (boolean), `created_by`, `updated_by`.
#### Triage workflow
- Triage per DEC-14-04: customer-quality reviewer reviews the received complaint, validates basic completeness, classifies via the taxonomy, assesses initial PV implication, assesses initial field-action implication, determines next state (`under_investigation`, `pending_response`, or `rejected_invalid`). Triage decision is e-signed via Controlled Approval Modal.
- SoD-14-01 enforced: intake user (creator) cannot be the triage reviewer. CMP-010 → MUST.
#### Investigation workflow
- Investigation entity: `complaint_investigations` per DEC-14-05 with `id`, `complaint_id`, `investigator_user_id`, `investigation_summary`, `root_cause_analysis_summary`, `disposition` (`isolated_event_no_action` / `process_capa_required` / `field_action_required` / `pv_only_no_quality_defect` / `not_attributable_to_product`), `deviation_id` (FK URS-16 nullable), `rca_id` (FK URS-17 nullable), `capa_id` (FK URS-18 nullable), `signed_at`, `signature_id`, `created_at`, `updated_at`.
- SoD-14-02 enforced: complaint creator and triage reviewer cannot be the investigator.
#### Adverse Event capture and PV workflow
- `adverse_events` table per DEC-14-06 with `id`, `complaint_id`, `event_description`, `event_severity` (`fatal` / `life_threatening` / `hospitalisation` / `congenital_anomaly` / `disability` / `other_serious` / `non_serious`), `event_outcome`, `onset_date`, `meddra_pt_code` (MedDRA Preferred Term, MUST), `causality_assessment` (`certain` / `probable` / `possible` / `unlikely` / `unrelated`), `expectedness` (`expected` / `unexpected` per registered label), `pv_assessor_user_id` (nullable), `pv_assessment_signed_at` (nullable), `pv_assessment_signature_id` (nullable), `reportability_decision_jsonb` (per-jurisdiction reportable boolean + due-date + report-id).
- PV reportability decision per DEC-14-07: PV reviewer signs jurisdictional reportability per FDA 21 CFR §314.80, EMA EudraVigilance ICH E2D, MHRA Yellow Card, Health Canada Vigilance, PMDA, CDSCO. Reportable events are escalated to URS-27 for FDA MedWatch / EudraVigilance / Yellow Card / regional submission.
- Per Annex 22 / DEC-14-18: NO LLM / generative AI in the reportability decision path. Static deterministic AI may suggest reportability based on jurisdictional rules (advisory only); human reviewer's signed decision is system of record.
#### Customer Response workflow
- `complaint_responses` per DEC-14-08 with `id`, `complaint_id`, `response_body`, `response_channel` (`letter` / `email` / `phone_followup` / `regulator_notification`), `drafter_user_id`, `drafted_at`, `approver_user_id` (nullable), `approver_signature_id` (nullable), `approved_at` (nullable), `issued_at` (nullable), `issued_by_user_id` (nullable), `external_copy_hash` (SHA-256 of issued external content).
- Response approval per DEC-14-09: response is drafted, then approved with Controlled Approval Modal e-signature by the named approver per the response approval matrix.
- SoD-14-04 enforced: response drafter cannot be the response approver.
#### Field Alert workflow
- `field_alerts` per DEC-14-10 with `id`, `tenant_id`, `complaint_id` (FK URS-14), `product_id`, `batch_id` (FK URS-23 nullable), `alert_classification` (e.g., `bacterial_contamination` / `chemical_change` / `physical_change` / `biological_change` / `microbiological_change` / `mix_up`), `awareness_date`, `proposed_action`, `regulator_target` (`fda_far` / `ema` / `mhra` / `health_canada` / `pmda` / `cdsco`), `regulatory_due_date` (auto-computed from awareness_date + jurisdictional rule), `approval_state` (`pending_approval` / `approved` / `submitted` / `closed`), `approver_user_id` (nullable), `approver_signature_id` (nullable), `submitted_at` (nullable), `submission_record_id` (FK URS-27 nullable).
- FDA Field Alert Report per 21 CFR §314.81: 3-working-day reporting for NDA / ANDA-holder significant batch problems.
- Authority gate per DEC-14-11: field-alert approval requires `field_alert_approval_authority` Authority Profile + e-signature. SoD-14-05 enforced: field-alert approver cannot be the complaint creator or investigator.
#### Recall workflow
- `recall_initiations` per DEC-14-12 with `id`, `tenant_id`, `complaint_id` (FK URS-14), `product_id`, `batch_ids_jsonb` (FK URS-23 list), `recall_classification` (`class_i` / `class_ii` / `class_iii`), `recall_initiation_reason`, `regulator_target_jsonb` (FDA / EMA / MHRA / Health Canada / PMDA / CDSCO list), `proposed_recovery_strategy`, `customer_communication_plan`, `pending_approval | approved | initiated | completed | cancelled`, `initiation_approver_signature_ids_jsonb` (multi-sign matrix — derived read snapshot only; authoritative multi-signature evidence is stored in the module signature-slot table), `founder_cosign_signature_id` (per DEC-14-21), `effectiveness_check_outcome` (`effective` / `partial` / `ineffective`), `closed_at` (nullable).
- Recall classification per FDA: Class I (serious adverse health / death likely), Class II (temporary / medically reversible adverse), Class III (not likely adverse).
- Authority gate per DEC-14-13: recall initiation requires multi-sign approval matrix (QA Head + RA Head + Manufacturing Head + Distribution Head) + executive authority co-sign per DEC-14-21. SoD-14-06 enforced: any single user cannot satisfy two slots.
- Recall execution: customer / distribution-channel notification per URS-30; recovery / quarantine / destruction tracked; effectiveness check signed.
- Per Annex 22 / DEC-14-18: NO generative AI in recall classification or initiation decision path.
#### Similarity / Signal / Trend
- Static deterministic similarity scoring on `complaint_embedding` vector per DEC-14-14: surfaces "similar complaints in the last N days" with similarity score; advisory only per ARCH-AI-001 AC-2; visibly labelled per AC-3; never autonomously writes to system of record per AC-4.
- Signal detection: aggregate trend dashboard surfaces sudden increase in complaints by product / batch / classification (statistical control-chart approach, deterministic — not AI-generated). Advisory only.
#### Closure with non-bypassable prerequisites
- Closure prerequisites per DEC-14-15: a complaint cannot transition `response_issued → closed` unless ALL of the following are true:
1. Investigation is complete and signed (if applicable per disposition).
2. PV reportability decision is signed (if applicable per AE classification).
3. Customer response is approved + issued + recorded with external-copy hash.
4. Field action (if any) is initiated and approver-signed.
5. Recall (if any) is initiated, approved, and executive-authority-co-signed.
6. Closure attestation is e-signed by the named closure authority.
-
- SoD-14-07 enforced: closure authority cannot be the original intake user.
#### Audit Trail
- Every Module 14 mutation calls `auditTrailService.log()` with full attribution.
- Lifecycle transitions log dual-write to `complaint_lifecycle_events` + URS-06 audit substrate.
#### Context model
- Per CMP-011: align `study_id` nullability across `complaint.schema.ts`, `types/complaint.ts`, `db/schema.ts`. Resolve to **nullable** for non-study complaints (e.g., post-marketed product complaints not attached to a clinical study).
- Per CMP-013: normalize `MODULE_CONTEXT_CONFIG['complaints']` to declare both `product_id` AND `study_id` filtering; remove the split between context-filter and route/service handling.
### 2.2 Out of scope
The following are NOT in Module 14 scope:
- **Document Control** — URS-12 owns documents; field-alert PDFs and recall communications are stored as URS-12 documents.
- **Deviations, RCA, CAPA workflows** — URS-16, URS-17, URS-18 own their own workflows; Module 14 references them via `deviation_id`, `rca_id`, `capa_id` foreign keys.
- **Regulatory submissions** — URS-27 owns submission lifecycle for FDA MedWatch, EudraVigilance, Yellow Card, etc. Module 14 raises the submission trigger.
- **Authentication, RBAC, scope** — URS-01 / URS-02 / URS-03.
- **E-signature substrate** — URS-04. Module 14 consumes the Controlled Approval Modal contract.
- **Authority Profile registry** — URS-05.
- **Audit substrate** — URS-06.
- **Generative / probabilistic AI in adverse-event reportability, field-alert, or recall decision paths** — prohibited per Annex 22 / DEC-14-18.
### 2.3 Closed launch decisions
The following decisions are **closed** for launch:
| ID | Decision | Disposition |
|---|---|---|
| DEC-14-01 | Complaint master registry shape and per-tenant scoping | Locked; with CMP-011 context-model requirement. |
| DEC-14-02 | Complaint lifecycle state machine | Locked: per §0.5. |
| DEC-14-03 | Complaint classification taxonomy at launch | Locked per §2.1; tenant-extensible via `complaint_classifications`. |
| DEC-14-04 | Triage workflow with SoD-14-01 | Locked + CMP-010. |
| DEC-14-05 | Investigation entity model | Locked. |
| DEC-14-06 | Adverse event entity model + MedDRA PT code | Locked; MedDRA terminology adopted. |
| DEC-14-07 | PV reportability decision per jurisdiction | Locked: FDA 21 CFR §314.80, EMA EudraVigilance ICH E2D, MHRA Yellow Card, Health Canada, PMDA, CDSCO. |
| DEC-14-08 | Customer response entity model with external-copy hash | Locked. |
| DEC-14-09 | Response approval matrix | Locked: drafter ≠ approver (SoD-14-04); per-classification approver list. |
| DEC-14-10 | Field alert entity model with **complaint_id linkage preserved** | Locked. |
| DEC-14-11 | Field alert approval authority | Locked: `field_alert_approval_authority` Authority Profile required. |
| DEC-14-12 | Recall initiation entity model with **complaint_id linkage preserved** | Locked. |
| DEC-14-13 | Recall approval matrix | Locked: QA Head + RA Head + Manufacturing Head + Distribution Head + executive authority co-sign per DEC-14-21. |
| DEC-14-14 | Similarity / signal advisory surface | Locked: static deterministic similarity on `complaint_embedding`; advisory only per ARCH-AI-001 AC-2. |
| DEC-14-15 | Closure 6-prerequisite check | Locked per §2.1; non-bypassable. |
| DEC-14-16 | Investigation linkage to URS-16 / 17 / 18 | Locked. |
| DEC-14-17 | Audit-trail coverage extended to lifecycle transitions, response approval, field/recall linkages | Locked. |
| DEC-14-18 | Annex 22 GenAI prohibition in adverse-event reportability, field-alert, and recall decision paths | Locked: NO LLM / generative AI in these surfaces. |
| DEC-14-19 | ARCH-AI-001 binding for advisory similarity / signal surfacing | Locked: AC-1..AC-7 binding. |
| DEC-14-20 | EU AI Act Art. 13 advisory transparency | Locked: visible advisory labelling on every advisory surface. |
| DEC-14-21 | executive authority co-sign on recall initiation | Locked: every Class I / II / III recall requires executive authority co-sign. |
| DEC-14-22 | Reopen requires executive authority co-sign + reason | Locked. |
| DEC-14-23 | Tenant offboarding cascade | Locked: open complaints transition to `archived_for_audit`; closed records preserved per retention class. |
| DEC-14-24 | Complaint linkage to URS-13 records when complaints precipitate platform changes | Locked: complaint may reference one or more URS-13 records via cross-module linkage. |
| DEC-14-25 | Complainant identity privacy | Locked: PII-tokenised per tenant privacy policy and GDPR Art. 6 / Art. 9 lawful basis; raw PII restricted to authorised PV / customer-quality roles. |
---
## 3. User Roles and Permissions
### 3.1 Architecture
Module 14 consumes the URS-01 authenticated identity, the URS-02 RBAC permission grants, the URS-03 active scope, the URS-04 workflow / e-signature substrate, and the URS-05 Authority Profile registry. Three-guard hierarchy — RoleGuard, PermissionGuard, AuthorityGuard.
### 3.2 Role definitions
| Role | Purpose | Module 14 ownership |
|---|---|---|
| `viewer` | Read-only access to complaints within scope | Read complaints; read investigations; read responses; read field alerts; read recalls |
| `complaint_intake` | Per-tenant intake authority | All `viewer` + create complaints from intake channels |
| `customer_quality_reviewer` | Triage authority | All `viewer` + triage complaints with classification + initial PV/field-action assessment + e-sign |
| `complaint_investigator` | Investigation authority | All `viewer` + create / update investigations + link deviation / RCA / CAPA + sign |
| `pv_assessor` | Pharmacovigilance assessment authority | All `viewer` + assess adverse events + sign reportability decision |
| `pv_lead` | Pharmacovigilance leadership | All `pv_assessor` + escalate to URS-27 submission + co-sign reportability for serious / unexpected events |
| `customer_quality_lead` | Customer-quality leadership | All `customer_quality_reviewer` + approve customer responses + co-sign closure |
| `field_alert_approver` | Field alert authority | All `viewer` + e-sign field alert approval |
| `recall_approver` | Recall matrix participation | All `viewer` + e-sign recall approval slot per matrix |
| `quality_lead` | Quality oversight | All `customer_quality_lead` + investigation oversight + closure attestation |
| `regulatory_affairs_lead` | Regulatory affairs oversight | All `viewer` + assess regulatory implications + co-sign field alert / recall regulator submission |
| `manufacturing_lead` | Manufacturing oversight | All `viewer` + investigate manufacturing causation + recall matrix slot |
| `distribution_lead` | Distribution oversight | All `viewer` + recall execution + recall matrix slot |
| `complaint_closure_authority` | Closure attestation authority | All `customer_quality_lead` + e-sign closure attestation |
| `admin` | Tenant-level administration | All `quality_lead` + manage tenant complaint configuration + manage classification taxonomy |
| `platform_admin` | Verixa platform administration | Tenant-scoped Module 14 actions are support / break-glass only (with reason, support-ticket reference, electronic signature, `PLATFORM_TENANT_ACCESS_USED` audit emit, SOC alert). Routine tenant complaints administration is the responsibility of tenant `admin` users. |
| `super_admin` | Verixa super-admin | All `platform_admin` + executive break-glass operations |
### 3.3 Authority Profiles consumed by Module 14
| Authority Profile | Description |
|---|---|
| `complaint_triage_authority` | E-signature authority for complaint triage decision |
| `complaint_investigation_signoff` | E-signature authority for investigation completion |
| `pv_reportability_decision` | E-signature authority for PV reportability decision |
| `pv_serious_event_cosign` | Co-sign authority for serious / unexpected AE reportability |
| `customer_response_approval` | E-signature authority for customer response approval |
| `field_alert_approval_authority` | E-signature authority for field alert approval |
| `recall_initiation_matrix_member` | Per-slot e-signature authority for recall approval matrix |
| `class_i_recall_executive_authority` | executive authority for recall initiation co-sign (DEC-14-21) |
| `complaint_closure_authority` | E-signature authority for complaint closure attestation |
| `complaint_reopen_executive_authority` | executive authority for complaint reopen co-sign (DEC-14-22) |
| `complainant_pii_access` | Authority to view raw complainant PII (raw email, phone) — restricted role |
### 3.4 Segregation-of-Duties rules
| SoD Rule | Description |
|---|---|
| SoD-14-01 | Complaint intake creator cannot be the triage reviewer. |
| SoD-14-02 | Complaint creator and triage reviewer cannot be the investigation investigator. |
| SoD-14-03 | PV assessor and PV co-signer (for serious events) cannot be the same user. |
| SoD-14-04 | Customer response drafter cannot be the response approver. |
| SoD-14-05 | Field-alert approver cannot be the complaint creator or the investigator. |
| SoD-14-06 | Recall approval matrix: no single user can satisfy two required slots. |
| SoD-14-07 | Closure attestation authority cannot be the complaint creator (intake user). |
| SoD-14-08 | Executive authority reopen co-signer cannot be the original closure authority. |
### 3.5 Worked examples
**Example 1: Particulate matter complaint with field alert and Class II recall.** A patient calls reporting visible black particles in their tablet. Intake (`complaint_intake`) creates `CMP-2026-001234`, classification `quality_defect / particulate_matter / drug_substance`, priority `expedited`. Triage by `customer_quality_reviewer` (different from intake, SoD-14-01) confirms valid complaint, flags both PV implication and field-action implication, signs triage. Investigation opened by `complaint_investigator` (SoD-14-02): reviewing batch records, the cause is traced to a manufacturing deviation already logged as `DEV-2026-0089` (URS-16). Investigation concludes `field_action_required`; investigation signed. Field alert opened: `field_alert_approver` e-signs after RA Lead co-sign; alert is submitted to FDA via URS-27 within 3 working days. Recall initiated as Class II: matrix slots e-signed by QA Head + RA Head + Manufacturing Head + Distribution Head; executive authority co-signs (DEC-14-21). Customer response drafted by customer-quality-team, approved by `customer_quality_lead` (different from drafter, SoD-14-04), issued via letter with external-copy hash recorded. Closure prerequisites checked: investigation complete ✓, PV not applicable ✓, response issued ✓, field action signed ✓, recall approved + executive-authority-cosigned ✓; `complaint_closure_authority` (different from intake, SoD-14-07) e-signs closure. `CMP-2026-001234` `closed`.
**Example 2: Adverse event with serious classification.** A prescriber reports a patient developed anaphylaxis after taking the product. Intake creates complaint with `pv_implication=true`. Triage routes to `under_investigation` and PV workflow. PV assessor (`pv_assessor`) captures adverse event with severity `life_threatening`, MedDRA PT `Anaphylactic shock`, causality `probable`, expectedness `unexpected per registered label`. PV reviewer signs reportability: FDA 21 CFR §314.80 — reportable as 15-day expedited; EMA EudraVigilance — reportable as ICH E2D 15-day; MHRA Yellow Card — reportable. PV lead (`pv_lead`) co-signs serious / unexpected event per SoD-14-03. URS-27 submission triggered for FDA MedWatch (within 15 days), EudraVigilance ICSR, MHRA Yellow Card. Per DEC-14-18: NO LLM / generative AI was used in the reportability decision; PV reviewer decision is system of record.
**Example 3: SoD enforcement — intake user attempts triage.** An intake user opens the triage interface for the complaint they just created. Service rejects with HTTP 403 + `COMPLAINT_SOD_VIOLATION_INTAKE_CANNOT_TRIAGE`. URS-06 audit substrate records the attempt. The platform offers re-assignment to another `customer_quality_reviewer`.
**Example 4: Closure blocked by missing field-action sign.** Closure attempted on a complaint where the investigation flagged field action but the field alert is still in `pending_approval` state. Closure rejected with HTTP 422 + `COMPLAINT_CLOSURE_BLOCKED_FIELD_ACTION_PENDING`. Closure remains blocked until the field alert is approver-signed.
**Example 5: Reopen requires executive authority co-sign (DEC-14-22).** A closed complaint is found, post-closure, to have additional reports indicating a broader pattern. QA proposes reopen. `closed → reopened` requires executive authority co-sign per DEC-14-22 + documented reason. SoD-14-08 enforced: executive authority co-signer cannot be the original closure authority. executive authority e-signs reopen attestation; complaint transitions back to `under_investigation` for re-evaluation.
**Example 6: Similarity advisory under ARCH-AI-001.** A new complaint is created. The static deterministic similarity service surfaces "3 similar complaints in the last 90 days for Product X / Lot Y" with visible "AI-suggested — requires human review" label (AC-3). The triage reviewer reviews the suggestion; decides to classify the new complaint as `efficacy / suspected_lack_of_efficacy` based on pattern. The similarity output and the human decision are both audited per ARCH-AI-001 AC-5. No autonomous write to the complaint record (AC-4). Per DEC-14-18: NO generative AI was used; only static deterministic vector similarity.
**Example 7: Annex 22 GenAI prohibition runtime block (DEC-14-18).** A user attempts to invoke "AI-suggest reportability" via an experimental UI surface. Runtime block returns HTTP 403 + `COMPLAINT_GENAI_PROHIBITED`. URS-06 audit substrate records the attempt. The platform's lint rule (Gate 8) prevents this surface from ever shipping.
### 3.6 Role-permission matrix (Module 14 administrative surface only)
| Permission | viewer | complaint_intake | customer_quality_reviewer | complaint_investigator | pv_assessor | customer_quality_lead | field_alert_approver | recall_approver | quality_lead | admin |
|---|---|---|---|---|---|---|---|---|---|---|
| `complaints:read` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| `complaints:create` | ✗ | ✓ | ✓ | ✓ | ✗ | ✓ | ✗ | ✗ | ✓ | ✓ |
| `complaints:triage` (with authority + SoD-14-01) | ✗ | ✗ | ✓ | ✓ | ✗ | ✓ | ✗ | ✗ | ✓ | ✓ |
| `complaints:investigate` (with authority + SoD-14-02) | ✗ | ✗ | ✗ | ✓ | ✗ | ✗ | ✗ | ✗ | ✓ | ✓ |
| `complaints:pv_assess` (with authority) | ✗ | ✗ | ✗ | ✗ | ✓ | ✗ | ✗ | ✗ | ✓ | ✓ |
| `complaints:pv_reportability_sign` (with authority + SoD-14-03) | ✗ | ✗ | ✗ | ✗ | ✓ | ✗ | ✗ | ✗ | ✓ | ✓ |
| `complaints:response_draft` | ✗ | ✗ | ✓ | ✗ | ✗ | ✓ | ✗ | ✗ | ✓ | ✓ |
| `complaints:response_approve` (with authority + SoD-14-04) | ✗ | ✗ | ✗ | ✗ | ✗ | ✓ | ✗ | ✗ | ✓ | ✓ |
| `complaints:response_issue` (with authority) | ✗ | ✗ | ✗ | ✗ | ✗ | ✓ | ✗ | ✗ | ✓ | ✓ |
| `complaints:field_alert_approve` (with authority + SoD-14-05) | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✓ | ✗ | ✓ | ✓ |
| `complaints:recall_approve_slot` (with authority + SoD-14-06) | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✓ | ✓ | ✓ |
| `complaints:recall_founder_cosign` (executive authority) | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ (executive authority only) |
| `complaints:close` (with authority + SoD-14-07) | ✗ | ✗ | ✗ | ✗ | ✗ | ✓ | ✗ | ✗ | ✓ | ✓ |
| `complaints:reopen_founder` (executive authority + SoD-14-08) | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ (executive authority only) |
| `complaints:reject_invalid` (with authority) | ✗ | ✗ | ✓ | ✗ | ✗ | ✓ | ✗ | ✗ | ✓ | ✓ |
| `complaints:read_audit` | ✗ | ✗ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| `complaints:complainant_pii_access` (restricted) | ✗ | ✓ | ✓ | ✗ | ✓ | ✓ | ✗ | ✗ | ✓ | ✓ |
---
## 4. End-to-End User Journeys
The 28 launch user journeys cover the full Complaint lifecycle: intake, triage, investigation, adverse-event capture and PV reportability, customer response, field alert, recall initiation and execution, similarity / signal advisory, closure, reject-invalid, reopen, and executive break-glass governance.
### J-01 — Intake creates a complaint from web form
A web form submission triggers complaint intake. `complaint_intake` user reviews the inbound details, attaches `product_id` (URS-10), enters `lot_number`, `symptom_description`, complainant identity (PII-tokenised), priority. Saves; platform assigns `complaint_number CMP-{YYYY}-{nnnnnn}` per CMP-014. State `received`. URS-06 records create.
### J-02 — Intake from regulator notification
FDA Inspector Notice triggers a complaint intake by `regulatory_affairs_lead`. Source `received_via=regulator`. Priority auto-set to `expedited`. URS-30 notifies QA + RA leads.
### J-03 — Triage with classification (SoD-14-01)
`customer_quality_reviewer` (different from intake user) opens triage. Validates basic completeness. Classifies via `complaint_classifications` taxonomy. Assesses initial PV implication (true/false). Assesses initial field-action implication (true/false). Selects next state (`under_investigation` / `pending_response` / `rejected_invalid`). E-signs triage decision via Controlled Approval Modal. State `received → triaged → next_state`.
### J-04 — Reject invalid complaint
Reviewer determines the complaint is duplicate / not related to a registered product / insufficient information after due diligence. Selects `rejected_invalid` with reason. E-signs rejection. State `triaged → rejected_invalid` (terminal). Complainant is notified (if contact known) via URS-30.
### J-05 — Open investigation (SoD-14-02)
`complaint_investigator` (different from creator/triage reviewer per SoD-14-02) opens investigation. Reviews batch records (URS-23), prior deviations (URS-16). Captures investigation summary. Optionally links to `deviation_id`, `rca_id`, `capa_id`. Captures disposition. E-signs investigation. State `triaged → under_investigation`.
### J-06 — Investigation links to existing deviation
Investigator finds the cause is already documented in `DEV-2026-0089` (URS-16). Investigation row created with `deviation_id=DEV-2026-0089`. Disposition `process_capa_required` (CAPA created in URS-18 referencing this complaint).
### J-07 — Investigation indicates field-action required
Investigator concludes `field_action_required`. State `under_investigation → field_action_pending`. URS-30 notifies field-alert team.
### J-08 — PV adverse-event capture
Complaint flagged as PV-implication during triage. `pv_assessor` opens adverse-event capture. Records event description, severity (`life_threatening` / `serious_other` / `non_serious`), MedDRA Preferred Term code, causality, expectedness, onset date.
### J-09 — PV reportability decision (DEC-14-07)
PV assessor evaluates per-jurisdiction reportability. Signs reportability decision via Controlled Approval Modal: e.g., FDA 15-day expedited (yes), EudraVigilance 15-day (yes), MHRA Yellow Card (yes). For serious / unexpected, `pv_lead` co-signs per SoD-14-03. URS-27 submission record created automatically.
### J-10 — Annex 22 GenAI prohibition in PV reportability path (DEC-14-18)
User attempts to invoke "AI-suggest reportability" experimental UI. Runtime block returns HTTP 403 + `COMPLAINT_GENAI_PROHIBITED`. Lint rule prevents this surface from shipping. Static deterministic AI MAY suggest reportability based on jurisdictional rules; only that is permitted.
### J-11 — Customer response drafted
`customer_quality_reviewer` or `customer_quality_lead` drafts the customer response: text body, channel (`letter` / `email`). Saves draft.
### J-12 — Customer response approved (SoD-14-04)
`customer_quality_lead` (different from drafter per SoD-14-04) approves the response via Controlled Approval Modal e-signature. Approval row recorded.
### J-13 — Customer response issued
`customer_quality_lead` or designated issuer e-signs issuance. Platform generates external letter / email content with watermark; SHA-256 hash recorded as `external_copy_hash`. URS-30 delivers to complainant. State `pending_response → response_issued`.
### J-14 — Field alert approval (SoD-14-05)
`field_alert_approver` (cannot be complaint creator or investigator per SoD-14-05) e-signs field alert approval via Controlled Approval Modal. Field alert is submitted to FDA URS-27 within 3 working days per 21 CFR §314.81.
### J-15 — Recall initiation Class I with executive authority co-sign (DEC-14-21)
QA leadership opens recall initiation: classification `class_i` (serious adverse health / death likely). Approval matrix slots e-signed: QA Head + RA Head + Manufacturing Head + Distribution Head + executive authority. SoD-14-06 enforced: no single user satisfies two slots. executive authority co-sign captured per DEC-14-21. State `recall pending_approval → approved`. URS-30 notifies regulators (FDA / EMA / MHRA / Health Canada / PMDA / CDSCO) per `regulator_target_jsonb`. URS-30 notifies distribution channels.
### J-16 — Recall execution and effectiveness
Recall in `initiated` state. Recovery, quarantine, destruction tracked. Effectiveness check planned. Verifier signs effectiveness check outcome (`effective` / `partial` / `ineffective`). State `initiated → completed`.
### J-17 — Closure with non-bypassable prerequisites (CMP-015)
`complaint_closure_authority` (different from creator per SoD-14-07) opens closure. Platform runs 6-prerequisite check: investigation complete ✓; PV reportability signed ✓; response issued ✓; field action initiated ✓; recall approved + executive-authority-cosigned ✓; closure attestation e-signed. State `response_issued → closed`.
### J-18 — Closure blocked by missing PV signoff
PV reportability is unsigned for an adverse-event complaint. Closure rejected with `COMPLAINT_CLOSURE_BLOCKED_PV_DECISION_PENDING`.
### J-19 — Closure blocked by missing field-action sign
Field alert is `pending_approval`. Closure rejected with `COMPLAINT_CLOSURE_BLOCKED_FIELD_ACTION_PENDING`.
### J-20 — Closure blocked by missing recall executive authority co-sign
Recall is matrix-approved but executive authority co-sign missing. Closure rejected with `COMPLAINT_CLOSURE_BLOCKED_RECALL_FOUNDER_COSIGN_PENDING`.
### J-21 — Reopen with executive authority co-sign (DEC-14-22)
Post-closure issue identified. QA proposes reopen. executive authority e-signs reopen via `complaint_reopen_executive_authority` Authority Profile. SoD-14-08 enforced: reopen authority ≠ original closure authority. State `closed → reopened → under_investigation`. URS-06 records reopen chain.
### J-22 — Similarity advisory (ARCH-AI-001 AC-2)
On new complaint creation, similarity service queries `complaint_embedding` for similar complaints in last 90 days. Returns top-N matches with similarity score. Advisory shown with "AI-suggested — requires human review" label (AC-3). Triage reviewer reviews and may include similarity in triage notes. The advisory is logged in `ai_requests` per AC-5. Per DEC-14-18: only static deterministic similarity (no GenAI).
### J-23 — Signal-detection trend dashboard
Customer-quality lead opens trend dashboard. Statistical control-chart approach surfaces sudden increase in complaints by product / batch / classification. Signal flagged for review. Advisory only; human investigation decision is system of record.
### J-24 — Cross-module linkage to URS-13 (complaint precipitates change)
A complaint reveals labelling ambiguity. Investigation concludes labelling change required. The labelling change is initiated via URS-13 record; the URS-13 record references this complaint as precipitating event.
### J-25 — Cross-module linkage to URS-27 regulatory submission
Recall approved triggers URS-27 submission record for FDA Recall Notification, EMA Rapid Alert, MHRA Drug Recall, Health Canada Recall.
### J-26 — Auditor reviews complaint evidence pack
Inspector requests evidence on a closed complaint. Platform exports complaint evidence pack: full complaint record + triage signature + investigation with linked deviation/RCA/CAPA + AE record + PV reportability decision + customer response with external-copy hash + field alert with regulatory submission record + recall approval matrix + executive authority co-sign + effectiveness check + closure attestation + URS-06 audit hash-chain proof. Pack is watermarked, e-signed by `quality_lead`.
### J-27 — Tenant offboarding cascade (DEC-14-23)
Tenant `offboarding`: open complaints transition to `archived_for_audit`; closed records preserved per retention class; new complaints blocked.
### J-28 — Complainant PII protection
A `viewer` attempts to view raw complainant email/phone. Platform redacts to PII-tokenised display. Only `complainant_pii_access` Authority Profile holders see raw PII. Per DEC-14-25 / GDPR Art. 6 / Art. 9 lawful basis.
---
## 5. Front-End Expected State
### 5.1 Routes
| Route | Purpose |
|---|---|
| `/complaints` | Complaint landing — list, filter by classification, lifecycle state, product, batch, date |
| `/complaints/new` | Create complaint from intake |
| `/complaints/:id` | Complaint detail (triage / investigation / AE / response / field alert / recall / closure tabs) |
| `/complaints/:id/triage` | Triage interface (classification + initial assessments + sign) |
| `/complaints/:id/investigations` | Investigation list and editor |
| `/complaints/:id/adverse-events` | AE capture + PV reportability decision |
| `/complaints/:id/responses` | Response draft + approval + issuance |
| `/complaints/:id/field-alerts` | Field alert workflow |
| `/complaints/:id/recalls` | Recall initiation + matrix approval + execution |
| `/complaints/:id/closure` | Closure attestation interface |
| `/complaints/:id/audit` | Per-complaint audit trail |
| `/complaints/me/assignments` | My open Module 14 assignments |
| `/complaints/dashboards/lifecycle-aging` | Lifecycle aging |
| `/complaints/dashboards/pv-reportability` | PV reportability queue |
| `/complaints/dashboards/field-actions` | Open field alerts and recalls |
| `/complaints/dashboards/signal-detection` | Trend / signal advisory dashboard |
| `/complaints/admin/classifications` | Classification taxonomy admin |
| `/complaints/admin/response-matrix` | Response approval matrix admin |
| `/complaints/admin/recall-matrix` | Recall approval matrix admin |
| `/complaints/executive/reopen` | Executive authority reopen workflow (executive authority only) |
| `/complaints/executive/recall-cosign` | Executive authority recall co-sign queue (executive authority only) |
### 5.2 Component requirements
- **ComplaintList / ComplaintCard** — display number, classification, lifecycle state, priority, product, batch, age, assignment.
- **ComplaintIntakeForm** — channel selector + complainant + product + batch + symptom + priority.
- **TriageEditor** — classification picker + PV/field-action toggles + e-sign SoD-14-01 enforced.
- **InvestigationEditor** — summary + RCA + disposition + linkage to deviation/RCA/CAPA.
- **AECaptureForm** — severity + MedDRA PT picker + causality + expectedness.
- **PVReportabilityDecisionModal** — per-jurisdiction reportability matrix + e-sign + (for serious) co-sign.
- **ResponseDraftEditor** — body + channel + SoD-14-04 enforced.
- **ResponseApprovalModal** — Controlled Approval Modal.
- **ResponseIssuanceModal** — issuance + watermark preview + external-copy hash recorded.
- **FieldAlertEditor** — alert classification + regulator target + due-date auto-calculated.
- **FieldAlertApprovalModal** — Controlled Approval Modal + SoD-14-05.
- **RecallInitiationEditor** — classification + reasons + recovery strategy + customer plan.
- **RecallApprovalMatrixViewer** — matrix slots + quorum + executive authority co-sign.
- **ClosurePrerequisiteChecklistViewer** — 6 prerequisites with live status.
- **SimilarityAdvisoryBanner** — visible "AI-suggested — requires human review" (ARCH-AI-001 AC-3) with override capability.
- **SignalTrendDashboard** — statistical control chart; deterministic; advisory.
- **AuditTrailViewer** — chronological per-complaint event view.
- **PIIRedactionWrapper** — redacts PII unless `complainant_pii_access` authorised.
### 5.3 Accessibility and internationalisation
- WCAG 2.1 AA across all components.
- Keyboard navigation on all interactive elements.
- Screen reader labelling on every action; AI advisory pills announced explicitly.
- Internationalisation: all strings in resource files; date/time per locale.
---
## 6. Back-End Expected State
### 6.1 Domain entities
| Entity | Purpose | Code module |
|---|---|---|
| `complaints` | Master complaint registry | `complaints` |
| `complaint_lifecycle_events` | Lifecycle transition audit | `complaints` |
| `complaint_classifications` | Classification taxonomy | `complaints` |
| `complaint_investigations` | Investigation records | `complaints` |
| `adverse_events` | AE records with PV reportability | `complaints` |
| `complaint_responses` | Customer response records | `complaints` |
| `field_alerts` | Field alert records (with `complaint_id` PRESERVED per CMP-006) | `complaints` |
| `recall_initiations` | Recall records (with `complaint_id` PRESERVED per CMP-007) | `complaints` |
| `recall_approval_matrix` | Per-recall approval slot rows | `complaints` |
| `recall_effectiveness_checks` | Recall effectiveness verification | `complaints` |
| `complaint_signal_alerts` | Signal-detection advisory records | `complaints` |
| `auth_audit_log` | Auth events (URS-06 substrate) | shared |
| `ai_requests` | Advisory AI request audit (URS-06 substrate) | shared |
### 6.1.1 Diagram 6.1-A — Module 14 entity-relationship overview
```mermaid
erDiagram
COMPLAINTS ||--o{ COMPLAINT_LIFECYCLE_EVENTS : emits
COMPLAINTS ||--o{ COMPLAINT_INVESTIGATIONS : has
COMPLAINTS ||--o{ ADVERSE_EVENTS : has
COMPLAINTS ||--o{ COMPLAINT_RESPONSES : has
COMPLAINTS ||--o{ FIELD_ALERTS : has
COMPLAINTS ||--o{ RECALL_INITIATIONS : has
RECALL_INITIATIONS ||--o{ RECALL_APPROVAL_MATRIX : has
RECALL_INITIATIONS ||--o{ RECALL_EFFECTIVENESS_CHECKS : has
COMPLAINT_CLASSIFICATIONS ||--o{ COMPLAINTS : classifies
TENANTS ||--o{ COMPLAINTS : owns
PRODUCTS ||--o{ COMPLAINTS : implicates
BATCH_RECORDS ||--o{ COMPLAINTS : implicates
STUDIES ||--o{ COMPLAINTS : optional_scopes
USERS ||--o{ COMPLAINTS : creates
USERS ||--o{ COMPLAINT_INVESTIGATIONS : investigates
USERS ||--o{ ADVERSE_EVENTS : assesses
USERS ||--o{ COMPLAINT_RESPONSES : drafts_approves_issues
USERS ||--o{ FIELD_ALERTS : approves
USERS ||--o{ RECALL_INITIATIONS : initiates
DEVIATIONS ||--o{ COMPLAINT_INVESTIGATIONS : linked_via_deviation_id
RCAS ||--o{ COMPLAINT_INVESTIGATIONS : linked_via_rca_id
CAPAS ||--o{ COMPLAINT_INVESTIGATIONS : linked_via_capa_id
REGULATORY_SUBMISSIONS ||--o{ ADVERSE_EVENTS : submits_via
REGULATORY_SUBMISSIONS ||--o{ FIELD_ALERTS : submits_via
REGULATORY_SUBMISSIONS ||--o{ RECALL_INITIATIONS : submits_via
COMPLAINTS ||--o{ COMPLAINT_SIGNAL_ALERTS : aggregated_into
COMPLAINTS ||--o{ AUTH_AUDIT_LOG : security_logged
COMPLAINTS ||--o{ AI_REQUESTS : advisory_for
```
Diagram 6.1-A — Module 14 entity-relationship. The target `complaints` code module is the expected owner of ~11 tables (extending the registry baseline with lifecycle events, recall matrix, recall effectiveness, signal alerts); ownership is target binding and remains subject to repository verification and validation evidence.
### 6.1.2 Diagram 6.1-B — Complaint lifecycle state machine (full)
```mermaid
stateDiagram-v2
[*] --> received : intake
received --> triaged : triage_signed (SoD-14-01)
triaged --> rejected_invalid : reject_signed (terminal)
triaged --> under_investigation : open_investigation (SoD-14-02)
triaged --> pending_response : no_investigation_path
under_investigation --> field_action_pending : disposition=field_action_required
under_investigation --> pending_response : disposition signed (no field action)
field_action_pending --> pending_response : field_action_initiated (alert/recall approver-signed)
pending_response --> response_issued : response_approved + issued (SoD-14-04)
response_issued --> closed : closure_signed (6 prereq + SoD-14-07)
closed --> reopened : executive authority co-sign (DEC-14-22, SoD-14-08)
reopened --> under_investigation : re-evaluation
rejected_invalid --> [*]
closed --> [*]
note right of field_action_pending
Field alert per CMP-006 (linkage)
Recall per CMP-007 (linkage)
executive authority co-sign DEC-14-21 for recall
end note
note right of pending_response
PV reportability signed (if AE)
SoD-14-03 for serious co-sign
end note
note right of closed
6 prerequisites:
1. investigation complete
2. PV decision signed (if AE)
3. response issued
4. field action signed
5. recall approved + executive authority
6. closure e-signed (SoD-14-07)
end note
```
Diagram 6.1-B — Complaint lifecycle state machine. Full transition set including field-action branch, reopen path, and the 6-prerequisite closure gate.
### 6.1.3 Diagram 6.1-C — Adverse Event PV reportability flow
```mermaid
flowchart TD
AE[Adverse event captured: severity + MedDRA + causality + expectedness] --> Assess[PV assessor evaluates]
Assess --> JurisCheck[Per-jurisdiction reportability rules deterministic]
JurisCheck --> Decision[PV reviewer signs reportability decision]
Decision --> Serious{Serious or unexpected?}
Serious -- yes --> CoSign[pv_lead co-signs per SoD-14-03]
Serious -- no --> SignOnly[Single sign sufficient]
CoSign --> Submit[URS-27 submission record created]
SignOnly --> Submit
Submit --> FDA[FDA MedWatch 15-day expedited if reportable]
Submit --> EMA[EMA EudraVigilance ICH E2D 15-day]
Submit --> MHRA[MHRA Yellow Card]
Submit --> HC[Health Canada Vigilance]
Submit --> PMDA[PMDA AE reporting]
Submit --> CDSCO[CDSCO]
Decision -.Annex 22 prohibition.-> NoGenAI[NO LLM in decision; static deterministic only DEC-14-18]
```
Diagram 6.1-C — PV reportability flow per CMP-004 + DEC-14-07. Per-jurisdiction deterministic rules; PV reviewer signs decision; serious / unexpected requires co-sign per SoD-14-03; URS-27 submission triggered. Under the internal Annex 22 Draft 2025 forward-looking AI governance control (not enacted predicate rule), generative AI is prohibited in the decision path; binding predicate-rule obligations remain those listed in §14.
### 6.1.4 Diagram 6.1-D — Recall approval matrix and execution
```mermaid
flowchart TD
Init[Recall initiated: class I/II/III + reasons] --> Matrix[Approval matrix per DEC-14-13]
Matrix --> QA[QA Head e-signs]
Matrix --> RA[RA Head e-signs]
Matrix --> MFG[Manufacturing Head e-signs]
Matrix --> DIST[Distribution Head e-signs]
Matrix --> ExecAuthority[executive authority co-signs DEC-14-21]
QA --> SoD{SoD-14-06 + matrix complete?}
RA --> SoD
MFG --> SoD
DIST --> SoD
ExecAuthority --> SoD
SoD -- not yet --> Wait[Wait for remaining slots]
Wait --> Matrix
SoD -- ok --> Approved[recall approved]
Approved --> RegNotify[URS-30 notify FDA EMA MHRA HC PMDA CDSCO]
Approved --> CustNotify[URS-30 notify customers / distribution channels]
Approved --> Execute[Recovery / quarantine / destruction]
Execute --> EffCheck[Effectiveness check signed]
EffCheck --> EffOutcome{Outcome}
EffOutcome -- effective --> Complete[recall completed]
EffOutcome -- partial --> Extend[Extend execution]
EffOutcome -- ineffective --> Escalate[Escalate to executive authority + RA]
```
Diagram 6.1-D — Recall approval matrix + execution per CMP-007 + DEC-14-13. Multi-slot approval with executive authority co-sign; SoD-14-06 enforced; regulator + customer notification; effectiveness verification.
### 6.2 Data model requirements
| Requirement | Statement |
|---|---|
| URS-14-DATA-001 | `complaints` table per DEC-14-01 with all listed fields per §2.1; nullability for `study_id` aligned across schema/type/persistence per CMP-011. |
| URS-14-DATA-002 | `complaint_lifecycle_events` append-only with `from_state`, `to_state`, `actor_user_id`, `at_timestamp`, `signature_id`, `reason`. |
| URS-14-DATA-003 | `complaint_classifications` per DEC-14-03 with extended taxonomy. |
| URS-14-DATA-004 | `complaint_investigations` per DEC-14-05 with `deviation_id`, `rca_id`, `capa_id` FKs. |
| URS-14-DATA-005 | `adverse_events` per DEC-14-06 with MedDRA PT code, causality, expectedness, reportability decision JSONB. |
| URS-14-DATA-006 | `complaint_responses` per DEC-14-08 with `external_copy_hash`. |
| URS-14-DATA-007 | `field_alerts` MUST persist `complaint_id` per CMP-006. |
| URS-14-DATA-008 | `recall_initiations` MUST persist `complaint_id` per CMP-007. |
| URS-14-DATA-009 | `recall_approval_matrix` per slot rows. |
| URS-14-DATA-010 | `recall_effectiveness_checks`. |
| URS-14-DATA-011 | `complaint_signal_alerts` for advisory signal records. |
| URS-14-DATA-012 | All Module 14 tables have RLS enabled per QS-6. |
| URS-14-DATA-013 | All mutations record to URS-06 audit substrate via `auditTrailService.log()` per QS-1. |
| URS-14-DATA-014 | `MODULE_CONTEXT_CONFIG['complaints']` declares both `product_id` AND `study_id` filtering per CMP-013. |
### 6.3 API requirements
| Endpoint | Method | Purpose | Priority |
|---|---|---|---|
| `/api/v1/complaints` | GET, POST | List, create | MUST |
| `/api/v1/complaints/:id` | GET, PATCH | Get, update | MUST |
| `/api/v1/complaints/:id/triage` | POST (with authority + SoD-14-01 + e-sign) | Triage decision | MUST |
| `/api/v1/complaints/:id/reject` | POST (with authority + e-sign) | Reject invalid | MUST |
| `/api/v1/complaints/:id/investigations` | GET, POST | List, create investigation | MUST |
| `/api/v1/complaints/:id/investigations/:invId` | PATCH (with authority + SoD-14-02 + e-sign) | Update + sign | MUST |
| `/api/v1/complaints/:id/adverse-events` | GET, POST | List, create AE | MUST |
| `/api/v1/complaints/:id/adverse-events/:aeId/pv-reportability` | POST (with authority + SoD-14-03 for serious + e-sign) | PV reportability decision | MUST |
| `/api/v1/complaints/:id/responses` | GET, POST | List, draft response | MUST |
| `/api/v1/complaints/:id/responses/:respId/approve` | POST (with authority + SoD-14-04 + e-sign) | Approve response | MUST |
| `/api/v1/complaints/:id/responses/:respId/issue` | POST (with authority + e-sign) | Issue response | MUST |
| `/api/v1/complaints/:id/field-alerts` | POST | Create field alert (preserves complaint_id per CMP-006) | MUST |
| `/api/v1/complaints/:id/field-alerts/:faId/approve` | POST (with authority + SoD-14-05 + e-sign) | Approve field alert | MUST |
| `/api/v1/complaints/:id/recalls` | POST | Initiate recall (preserves complaint_id per CMP-007) | MUST |
| `/api/v1/complaints/:id/recalls/:recId/approvals` | POST (with authority + SoD-14-06 + e-sign) | Approve recall slot | MUST |
| `/api/v1/complaints/:id/recalls/:recId/executive-cosign` | POST (executive authority + e-sign) | executive authority co-sign | MUST |
| `/api/v1/complaints/:id/recalls/:recId/effectiveness` | POST (with authority + e-sign) | Sign effectiveness check | MUST |
| `/api/v1/complaints/:id/close` | POST (with authority + SoD-14-07 + 6 prereq + e-sign) | Closure | MUST |
| `/api/v1/complaints/:id/reopen` | POST (executive authority + SoD-14-08 + reason) | Reopen | MUST |
| `/api/v1/complaints/:id/audit` | GET | Per-complaint audit trail | MUST |
| `/api/v1/complaints/:id/similarity` | GET | Static deterministic similar complaints | MUST |
| `/api/v1/complaints/signal-trends` | GET | Trend / signal advisory dashboard | MUST |
| `/api/v1/complaints/me/assignments` | GET | My open assignments | MUST |
| `/api/v1/complaints/admin/classifications` | GET, PUT | Classification taxonomy admin | MUST |
| `/api/v1/complaints/admin/response-matrix` | GET, PUT | Response approval matrix admin | MUST |
| `/api/v1/complaints/admin/recall-matrix` | GET, PUT | Recall approval matrix admin | MUST |
### 6.4 Workflow / lifecycle requirements
- URS-14-WF-001: Lifecycle state transitions per §6.4; unauthorised transitions return HTTP 422 + `COMPLAINT_INVALID_TRANSITION`.
- URS-14-WF-002: Triage enforces SoD-14-01 (intake user ≠ triage reviewer).
- URS-14-WF-003: Investigation enforces SoD-14-02.
- URS-14-WF-004: PV reportability serious / unexpected requires SoD-14-03 co-sign.
- URS-14-WF-005: Response approval enforces SoD-14-04.
- URS-14-WF-006: Field alert approval enforces SoD-14-05.
- URS-14-WF-007: Recall approval matrix enforces SoD-14-06 + executive authority co-sign per DEC-14-21.
- URS-14-WF-008: Closure enforces 6-prerequisite check + SoD-14-07.
- URS-14-WF-009: Reopen requires executive authority + SoD-14-08.
- URS-14-WF-010: Field alerts and recalls MUST persist `complaint_id` per CMP-006 / CMP-007.
### 6.5 Business rules
- BR-14-01: Server-authoritative complaint number `CMP-{YYYY}-{nnnnnn}` per CMP-014.
- BR-14-02: Tenant isolation enforced via TDAL + RLS.
- BR-14-03: Recall classifications are FDA Class I / II / III; classification cannot be changed after executive authority co-sign without reopen.
- BR-14-04: Field alert regulatory due-date auto-computed from awareness_date + jurisdictional rule (FDA = 3 working days for FAR per 21 CFR §314.81).
- BR-14-05: PV reportability per-jurisdiction rules deterministic; AI advisory permitted (DEC-14-19) but not autonomous (AC-4).
- BR-14-06: Annex 22 / DEC-14-18: NO LLM / generative AI in adverse-event reportability, field-alert issuance, or recall classification decision paths.
- BR-14-07: Tenant offboarding cascade per DEC-14-23.
- BR-14-08: Closed complaint reopened only via executive authority co-sign + reason per DEC-14-22.
- BR-14-09: Complainant PII restricted to `complainant_pii_access` Authority Profile holders per DEC-14-25.
- BR-14-10: Audit trail append-only per QS-1.
### 6.6 Audit trail requirements
- Every Module 14 mutation calls `auditTrailService.log()` per QS-1.
- Lifecycle transitions logged dual-write to `complaint_lifecycle_events` + URS-06.
- Triage, investigation, AE, PV reportability, response (draft/approve/issue), field alert (create/approve), recall (initiate/matrix/executive-cosign/effectiveness), closure, reopen — all logged.
- Auth-related events (SoD violations, authority denials) logged to `auth_audit_log`.
- Advisory AI requests (similarity, signal) logged to `ai_requests` per ARCH-AI-001 AC-5.
- Append-only per QS-1.
### 6.7 Architecture binding — Annex 22 GenAI prohibition + ARCH-AI-001 advisory governance
| Surface | AI use permitted | Governance |
|---|---|---|
| AE reportability decision | NONE — Annex 22 prohibition | Manual decision; deterministic jurisdictional rules |
| Field-alert issuance decision | NONE — Annex 22 prohibition | Manual decision; deterministic timeliness rules |
| Recall classification decision | NONE — Annex 22 prohibition | Manual classification by RA + executive authority |
| Closure decision | NONE — Annex 22 prohibition | Manual closure; deterministic 6-prereq check |
| Complaint similarity (advisory) | Static deterministic vector similarity only | ARCH-AI-001 AC-1..AC-7 |
| Signal-detection trend (advisory) | Static deterministic statistical control chart | ARCH-AI-001 AC-1..AC-7 |
| Triage classification suggestion (advisory) | Static deterministic pattern matching | ARCH-AI-001 AC-1..AC-7 |
---
## 7. Cross-Module Wiring and Change-Impact
### 7.1 Cross-module wiring
```mermaid
flowchart LR
M01[URS-01 Auth] --> M14[Module 14]
M02[URS-02 RBAC] --> M14
M03[URS-03 Active Scope] --> M14
M04[URS-04 Workflow / E-Sign] --> M14
M05[URS-05 Authority Profiles] --> M14
M06[URS-06 Audit Substrate] <-- M14
M10[URS-10 Product] --> M14
M11[URS-11 Supplier] --> M14
M12[URS-12 Documents] --> M14
M13[URS-13] --> M14
M16[URS-16 Deviations] <--> M14
M17[URS-17 RCA] <--> M14
M18[URS-18 CAPA] <--> M14
M21[URS-21 Findings] <-- M14
M22[URS-22 Inspection Mgmt] <-- M14
M23[URS-23 Batch Records] --> M14
M27[URS-27 Reg Intelligence] <-- M14
M30[URS-30 Notifications] <-- M14
ANNEX22[Annex 22] -.governs.-> M14
ARCHAI[ARCH-AI-001] -.governs.-> M14
```
Diagram 7.1-A — Module 14 cross-module wiring.
### 7.2 Change-Impact Matrix (CIM)
| Module 14 capability | Affects | Direction | URS-13 trigger if modified |
|---|---|---|---|
| Lifecycle state machine | All consuming modules | Outbound | Class 1 |
| Complaint classification taxonomy | URS-21, URS-22 | Outbound | Class 2 |
| AE severity / MedDRA PT enum | URS-27 | Outbound | Class 1 |
| PV reportability ruleset | URS-27 | Outbound | Class 1 |
| Recall classification (Class I/II/III) | URS-27 | Outbound | Class 1 |
| Recall approval matrix | URS-04, URS-05 | Outbound | Class 2 |
| executive authority co-sign requirement on recalls | URS-05 | Outbound | Class 1 |
| Closure prerequisite set | All consuming modules | Outbound | Class 1 |
### 7.3 Cross-module dependencies (consumed by Module 14)
- URS-01 — Auth.
- URS-02 — RBAC.
- URS-03 — Active scope.
- URS-04 — Workflow / e-sign.
- URS-05 — Authority Profiles.
- URS-06 — Audit substrate.
- URS-10 — Products.
- URS-11 — Suppliers.
- URS-12 — Documents.
- URS-13 — for complaints precipitating platform changes.
- URS-16 — Deviations (linked from investigations).
- URS-17 — RCA.
- URS-18 — CAPA.
- URS-23 — Batch records.
- URS-27 — Regulatory intelligence (PV / FAR / recall submissions).
- URS-30 — Notifications.
- EU GMP Annex 22 — GenAI prohibition.
- ARCH-AI-001 — Advisory AI binding.
---
## 8. AI / Automation / Human-in-the-Loop Controls
Per Annex 22 / DEC-14-18, generative / probabilistic AI is **PROHIBITED** in adverse-event reportability, field-alert issuance, recall classification, and closure decision paths. Static deterministic AI may be used in advisory roles only, governed by ARCH-AI-001 AC-1..AC-7.
| AI Surface | Permitted | Governance |
|---|---|---|
| AE reportability AI suggestion | NO (Annex 22) | Not built |
| Recall classification AI | NO (Annex 22) | Not built |
| Closure AI | NO (Annex 22) | Not built |
| Triage classification suggestion (deterministic) | YES — advisory | ARCH-AI-001 AC-1..AC-7 |
| Complaint similarity (deterministic vector) | YES — advisory | ARCH-AI-001 AC-1..AC-7 |
| Signal-detection trend (deterministic statistical) | YES — advisory | ARCH-AI-001 AC-1..AC-7 |
| MIRA copilot read-only retrieval over closed complaint records | YES — read-only | RAG per URS-12 |
All advisory AI output is visibly labelled per AC-3. All advisory output preserved in audit even when overridden per AC-6. No AI service is the sole path to act on a complaint.
---
## 9. Reports, Dashboards, and Exports
| Report / Dashboard | Purpose | Audience |
|---|---|---|
| Complaint inventory | All complaints by classification, lifecycle, product | QA, Customer Quality |
| Lifecycle aging | Time in each state | Customer Quality, QA |
| PV reportability queue | Open AEs awaiting reportability decision | PV team |
| Open field alerts | Pending field-alert approval / submission | RA, QA |
| Open recalls | Pending recall approval / execution / effectiveness | QA, RA, Manufacturing, Distribution, executive authority |
| Signal-detection trend dashboard (advisory) | Statistical trend by product / batch / classification | QA, PV |
| Closure-prerequisite blocked complaints | Complaints with closure blocked + reason | QA |
| Reopen audit register | Reopened complaints with executive authority attribution | QA, executive authority |
| Cross-tenant complaint indices (platform-admin support / break-glass only) | Aggregate Module 14 events | `platform_admin` (support / break-glass only with reason, support-ticket reference, electronic signature, `PLATFORM_TENANT_ACCESS_USED` audit emit, SOC alert) |
Exports:
- Complaint evidence pack (zipped: full complaint + investigation + AE + PV decision + response + field alert + recall + closure + URS-06 audit excerpt with hash-chain).
- Recall communication pack (regulator + customer letters with watermarks).
- Per-tenant retention archive.
---
## 10. Notifications and Queues
| Event | Recipients | Channel |
|---|---|---|
| Complaint received | QA + Customer Quality | URS-30 in-app |
| Triage assigned | Customer Quality reviewer | URS-30 in-app + email |
| Investigation opened | Investigator | URS-30 in-app |
| AE captured | PV team | URS-30 in-app |
| PV reportability signed (reportable) | PV lead + RA | URS-30 critical |
| Response approved + issued | Customer Quality lead + complainant | URS-30 in-app + email |
| Field alert approved | RA + URS-27 submission team | URS-30 in-app |
| Recall initiated (any class) | QA + RA + Manufacturing + Distribution + executive authority | URS-30 critical |
| Recall Class I | All stakeholders + executive office | URS-30 critical SMS + email |
| Recall effectiveness ineffective | QA + RA + executive authority | URS-30 critical |
| Closure attempted with prerequisite failure | Closure authority + QA | URS-30 in-app |
| Reopen executive-authority-cosigned | All stakeholders + executive office | URS-30 critical |
| Tenant offboarding cascade | All stakeholders | URS-30 in-app |
---
## 11. Error Handling and Negative Paths
### 11.1 Error envelope
`AppError` envelope per QS-9: `{ error, code, details? }`.
### 11.2 Error-code catalogue
| Code | HTTP | Meaning |
|---|---|---|
| `COMPLAINT_NOT_FOUND` | 404 | Complaint ID not in tenant scope |
| `COMPLAINT_INVALID_TRANSITION` | 422 | Lifecycle transition not allowed |
| `COMPLAINT_AUTHORITY_REQUIRED` | 403 | Authority Profile required |
| `COMPLAINT_SOD_VIOLATION_INTAKE_CANNOT_TRIAGE` | 403 | SoD-14-01 |
| `COMPLAINT_SOD_VIOLATION_INVESTIGATOR` | 403 | SoD-14-02 |
| `COMPLAINT_SOD_VIOLATION_PV_COSIGN` | 403 | SoD-14-03 |
| `COMPLAINT_SOD_VIOLATION_RESPONSE_APPROVAL` | 403 | SoD-14-04 |
| `COMPLAINT_SOD_VIOLATION_FIELD_ALERT_APPROVAL` | 403 | SoD-14-05 |
| `COMPLAINT_SOD_VIOLATION_RECALL_DOUBLE_SLOT` | 403 | SoD-14-06 |
| `COMPLAINT_SOD_VIOLATION_CLOSURE` | 403 | SoD-14-07 |
| `COMPLAINT_SOD_VIOLATION_REOPEN_EXECUTIVE_AUTHORITY` | 403 | SoD-14-08 |
| `COMPLAINT_CLOSURE_BLOCKED_INVESTIGATION_INCOMPLETE` | 422 | Closure prereq 1 |
| `COMPLAINT_CLOSURE_BLOCKED_PV_DECISION_PENDING` | 422 | Closure prereq 2 |
| `COMPLAINT_CLOSURE_BLOCKED_RESPONSE_NOT_ISSUED` | 422 | Closure prereq 3 |
| `COMPLAINT_CLOSURE_BLOCKED_FIELD_ACTION_PENDING` | 422 | Closure prereq 4 |
| `COMPLAINT_CLOSURE_BLOCKED_RECALL_FOUNDER_COSIGN_PENDING` | 422 | Closure prereq 5 |
| `COMPLAINT_FIELD_ALERT_LINKAGE_REQUIRED` | 422 | CMP-006 — field alert MUST persist complaint_id |
| `COMPLAINT_RECALL_LINKAGE_REQUIRED` | 422 | CMP-007 — recall MUST persist complaint_id |
| `COMPLAINT_REOPEN_EXECUTIVE_AUTHORITY_REQUIRED` | 403 | Reopen requires executive authority per DEC-14-22 |
| `COMPLAINT_RECALL_EXECUTIVE_AUTHORITY_REQUIRED` | 403 | Recall requires executive authority per DEC-14-21 |
| `COMPLAINT_GENAI_PROHIBITED` | 403 | GenAI not permitted per Annex 22 / DEC-14-18 |
| `COMPLAINT_PII_ACCESS_DENIED` | 403 | Raw PII restricted to authorised role |
| `VALIDATION_FAILED` | 400 | Zod validation |
| `SCOPE_MISMATCH` | 403 | Active scope mismatch |
### 11.3 Negative-path catalogue
- Intake user attempts triage → `COMPLAINT_SOD_VIOLATION_INTAKE_CANNOT_TRIAGE`.
- Closure with missing PV decision → `COMPLAINT_CLOSURE_BLOCKED_PV_DECISION_PENDING`.
- Closure with field alert pending → `COMPLAINT_CLOSURE_BLOCKED_FIELD_ACTION_PENDING`.
- Recall without executive authority → `COMPLAINT_RECALL_EXECUTIVE_AUTHORITY_REQUIRED`.
- Field alert insertion without `complaint_id` → `COMPLAINT_FIELD_ALERT_LINKAGE_REQUIRED`.
- GenAI invocation in critical decision path → `COMPLAINT_GENAI_PROHIBITED`.
- Viewer attempts raw PII → `COMPLAINT_PII_ACCESS_DENIED`.
---
## 12. Security, Privacy, and Tenant Isolation
### 12.1 Authentication dependency
URS-01 authenticated session required.
### 12.2 Authorisation pipeline
Three-guard hierarchy per QS-7. `requirePermission('complaints:approve')` + `withAuthority('field_alert_approval_authority')`.
### 12.3 Tenant isolation
TDAL on every DB op per QS-5; RLS on every Module 14 table per QS-6.
### 12.4 Encryption
At-rest encryption + TLS 1.2+. PII fields tokenised per privacy policy.
### 12.5 Logging hygiene
No raw PII / passwords in operational logs per QS-19.
### 12.6 Privacy and data residency
Module 14 records inherit tenant data residency. Complainant PII subject to GDPR Art. 6 / Art. 9 lawful basis; data subject access / erasure requests handled per URS-08.
### 12.7 Periodic access review
Per QS-7: per-tenant Authority Profile + classification taxonomy review every 6 months.
### 12.8 Periodic audit-trail review
Per QS-19: monthly Module 14 audit-trail sample by `quality_lead`; quarterly tenant-wide integrity check.
### 12.9 Security-operations alert thresholds
| Alert | Threshold |
|---|---|
| SoD violations | Any |
| GenAI prohibition violation | Any (always critical) |
| Recall executive authority co-sign | Any |
| Reopen executive authority | Any |
| Bulk export | >20 complaints in 1 hour |
| PII access surge | >50 PII accesses by one user in 1 hour |
### 12.10 Self-modification block
Module 14 services cannot modify own audit trail or configuration tables.
### 12.11 Secure export
Evidence-pack exports watermarked, audit-logged, TLS.
### 12.12 Cross-tenant confidentiality envelope
Tenant A cannot read tenant B complaints under any RBAC; only `platform_admin` support / break-glass cross-tenant operations (with reason, support-ticket reference, electronic signature, `PLATFORM_TENANT_ACCESS_USED` audit emit, SOC alert) are permitted.
---
## 13. Data Integrity and ALCOA+ Controls
| ALCOA+ Principle | Module 14 Implementation |
|---|---|
| Attributable | Every complaint, investigation, AE, response, field alert, recall, closure carries `created_by` / `signed_by` per QS-2. |
| Legible | Records human-readable; PII tokenised but original retrievable per authority. |
| Contemporaneous | Server-generated timestamps per QS-3. |
| Original | Original draft preserved on supersede; original AI advisory preserved per AC-6. |
| Accurate | Schema + Zod validation per QS-8; referential integrity per QS-14. |
| Complete | All required fields enforced; closure prerequisites non-bypassable. |
| Consistent | Context model normalized per CMP-011 / CMP-013. |
| Enduring | Records preserved per retention class; append-only audit per QS-1. |
| Available | Tenant-scoped retrieval; evidence pack export. |
| Traceable | Hash-chained URS-06 audit; per-complaint audit view; cross-module reference chain. |
---
## 14. Regulatory Mapping
### 14.1 Predicate-rule applicability matrix
| Authority | Predicate | Module 14 obligation |
|---|---|---|
| FDA | 21 CFR Part 11 §11.10(a/d/e) §11.50/11.70/11.100/11.200/11.300 | Validation + RBAC + audit + e-signature |
| FDA | 21 CFR §211.198 — Complaint Files | Complaint register, investigation, response |
| FDA | 21 CFR §314.80 — Postmarketing AE reporting | PV reportability, MedWatch submission |
| FDA | 21 CFR §314.81 — NDA / ANDA Field Alert Reports | Field alert workflow |
| FDA | 21 CFR Part 7 — Recalls | Recall workflow |
| FDA | FDA CSA Final Guidance (Sep 2025) | Risk-based testing |
| EMA / PIC/S | EU GMP Annex 11 §4/9/12/16 | Validation + audit + security + incident |
| EMA / PIC/S | EU GMP Chapter 8 — Complaints, Quality Defects, Recalls | Complaint + recall workflow |
| Internal architectural control (forward-looking; not enacted predicate rule) | EU GMP Annex 22 (Draft 2025) | GenAI prohibition per DEC-14-18 (treated as internal forward-looking control; jurisdiction-specific legal enforceability subject to future legal assessment) |
| EMA | EudraVigilance ICH E2D | PV ICSR submission |
| MHRA | Yellow Card | UK PV reporting |
| Health Canada | Vigilance Programme | Canada PV reporting |
| PMDA | Japan AE reporting | Japan PV reporting |
| India CDSCO (per applicable scope) | India Drugs and Cosmetics Act 1940 + Drugs Rules 1945 (including post-market complaint, field-alert, recall, and reportability routing) + Revised Schedule M (complaints chapter) + Schedule M-III (distribution recall expectations where in scope) + New Drugs and Clinical Trials Rules 2019 (where clinical AE / SAE reporting scope) + Medical Devices Rules 2017 (where device complaint / vigilance scope) + CDSCO PvPI / IPC adverse-event reporting; CDSCO field alert / recall routing — Applicable per India tenant operation and jurisdictional regulatory assessment | India PV reporting (PvPI / IPC), field alert routing, recall classification + execution; URS-27 submission linkage per India regulatory framework; external jurisdictional legal / RA confirmation required for clause / form applicability per India complaint / PV / recall scope |
| Internal architectural control (forward-looking; not enacted predicate rule) | EU AI Act Art. 13 — Transparency principles for advisory AI | Visible advisory labelling (treated as internal control aligned with transparency principles; jurisdiction-specific legal enforceability subject to future legal assessment) |
| MHRA | MHRA Data Integrity ALCOA+ | §13 |
| ICH | ICH Q10 — Pharmaceutical QMS | Complaint handling element |
| ICH | ICH E2D — Post-Approval Safety Data | PV case definition |
| ICH | MedDRA terminology | AE coding |
| GAMP | GAMP 5 Cat 5 | Validation per §17 |
| WHO | TRS 996 Annex 5 | Good data management |
---
## 15. URS Requirements Register
### 15.1 Front-end (FE)
| ID | Requirement | Priority |
|---|---|---|
| URS-14-FE-001 | Complaint landing route | MUST |
| URS-14-FE-002 | Create complaint route | MUST |
| URS-14-FE-003 | Complaint detail with tabs | MUST |
| URS-14-FE-004 | Triage editor with SoD-14-01 | MUST |
| URS-14-FE-005 | Investigation editor with linkage to URS-16/17/18 | MUST |
| URS-14-FE-006 | AE capture with MedDRA PT picker | MUST |
| URS-14-FE-007 | PV reportability decision modal with co-sign for serious | MUST |
| URS-14-FE-008 | Response draft + approval + issuance modals | MUST |
| URS-14-FE-009 | Field alert approval modal (SoD-14-05) | MUST |
| URS-14-FE-010 | Recall initiation + matrix viewer + executive authority co-sign | MUST |
| URS-14-FE-011 | Closure prerequisite checklist viewer | MUST |
| URS-14-FE-012 | Similarity advisory banner (ARCH-AI-001 AC-3) | MUST |
| URS-14-FE-013 | Signal trend dashboard | MUST |
| URS-14-FE-014 | Executive authority reopen modal | MUST |
| URS-14-FE-015 | Executive authority recall co-sign queue | MUST |
| URS-14-FE-016 | PII redaction wrapper | MUST |
| URS-14-FE-017 | WCAG 2.1 AA across all routes | MUST |
| URS-14-FE-018 | i18n / l10n | MUST |
| URS-14-FE-019 | ErrorBoundary + loading/error/empty states per QS-17 | MUST |
| URS-14-FE-020 | Per-complaint audit view | MUST |
| URS-14-FE-021 | Annex 22 GenAI prohibition surface (no AI offered in critical decision UI) | MUST (negative requirement) |
### 15.2 Back-end (BE)
| ID | Requirement | Priority |
|---|---|---|
| URS-14-BE-001 | `complaints` REST surface per §6.3 | MUST |
| URS-14-BE-002 | Lifecycle state machine (no generic patch on status) | MUST |
| URS-14-BE-003 | Triage route with SoD-14-01 + e-sign | MUST |
| URS-14-BE-004 | Investigation routes with SoD-14-02 | MUST |
| URS-14-BE-005 | AE PV reportability route with SoD-14-03 | MUST |
| URS-14-BE-006 | Response draft + approve + issue routes with SoD-14-04 | MUST |
| URS-14-BE-007 | Field alert with `complaint_id` linkage per CMP-006 | MUST |
| URS-14-BE-008 | Recall with `complaint_id` linkage per CMP-007 | MUST |
| URS-14-BE-009 | Recall approval matrix + executive authority co-sign | MUST |
| URS-14-BE-010 | Recall effectiveness check | MUST |
| URS-14-BE-011 | Closure 6-prereq + SoD-14-07 | MUST |
| URS-14-BE-012 | Reopen executive authority co-sign + SoD-14-08 | MUST |
| URS-14-BE-013 | Per-complaint audit trail route | MUST |
| URS-14-BE-014 | Similarity static deterministic route | MUST |
| URS-14-BE-015 | Signal trend route | MUST |
| URS-14-BE-016 | Context model normalization per CMP-011 / CMP-013 | MUST |
| URS-14-BE-017 | Audit-trail extension per CMP-012 | MUST |
| URS-14-BE-018 | Tenant offboarding cascade | MUST |
### 15.3 Workflow (WF)
| ID | Requirement | Priority |
|---|---|---|
| URS-14-WF-001..010 | Per §6.4 | MUST |
### 15.4 Data (DATA)
| ID | Requirement | Priority |
|---|---|---|
| URS-14-DATA-001..014 | Per §6.2 | MUST |
### 15.5 Security (SEC)
| ID | Requirement | Priority |
|---|---|---|
| URS-14-SEC-001 | Three-guard pipeline | MUST |
| URS-14-SEC-002 | TDAL per QS-5 | MUST |
| URS-14-SEC-003 | RLS per QS-6 | MUST |
| URS-14-SEC-004 | Cross-tenant envelope | MUST |
| URS-14-SEC-005 | PII redaction + restricted access | MUST |
| URS-14-SEC-006 | Watermarked evidence-pack export | MUST |
| URS-14-SEC-007 | Bulk export authority gate | MUST |
| URS-14-SEC-008 | Self-modification block | MUST |
| URS-14-SEC-009 | Periodic access review | MUST |
| URS-14-SEC-010 | GenAI prohibition runtime block | MUST |
### 15.6 Audit (AUD)
| ID | Requirement | Priority |
|---|---|---|
| URS-14-AUD-001 | Every mutation audited per QS-1 | MUST|
| URS-14-AUD-002 | Lifecycle dual-write to events + URS-06 | MUST |
| URS-14-AUD-003 | Triage / investigation / AE / response / field alert / recall / closure all audited | MUST |
| URS-14-AUD-004 | Auth events to `auth_audit_log` | MUST |
| URS-14-AUD-005 | Advisory AI requests to `ai_requests` per AC-5 | MUST |
| URS-14-AUD-006 | Append-only per QS-1 | MUST |
| URS-14-AUD-007 | Per-complaint audit view route | MUST |
### 15.7 AI / HITL (AI)
| ID | Requirement | Priority |
|---|---|---|
| URS-14-AI-001 | NO LLM/GenAI in AE reportability / field alert / recall / closure decision paths per Annex 22 | MUST (negative) |
| URS-14-AI-002 | Static deterministic similarity advisory per CMP-016 | MUST |
| URS-14-AI-003 | Static deterministic signal-detection trend advisory | MUST |
| URS-14-AI-004 | Visible "AI-suggested" labelling per ARCH-AI-001 AC-3 | MUST |
| URS-14-AI-005 | No autonomous write per AC-4 | MUST |
| URS-14-AI-006 | Override capability per AC-6 | MUST |
| URS-14-AI-007 | Full AI request audit per AC-5 | MUST |
| URS-14-AI-008 | EU AI Act Art. 13 transparency | MUST |
### 15.8 Integration (INT)
| ID | Requirement | Priority |
|---|---|---|
| URS-14-INT-001 | URS-01..06 substrate consumed | MUST |
| URS-14-INT-002 | URS-10 Product linkage | MUST |
| URS-14-INT-003 | URS-11 Supplier linkage | MUST |
| URS-14-INT-004 | URS-12 Document linkage (response letter PDF, recall communication) | MUST |
| URS-14-INT-005 | URS-13 linkage (complaint precipitates change) per DEC-14-24 | MUST |
| URS-14-INT-006 | URS-16 Deviation linkage from investigation | MUST |
| URS-14-INT-007 | URS-17 RCA linkage | MUST |
| URS-14-INT-008 | URS-18 CAPA linkage | MUST |
| URS-14-INT-009 | URS-23 Batch Records linkage | MUST |
| URS-14-INT-010 | URS-27 Regulatory submission (PV / FAR / recall) | MUST |
| URS-14-INT-011 | URS-30 Notifications wired per §10 | MUST |
| URS-14-INT-012 | Internal forward-looking AI governance evidence (EU GMP Annex 22 Draft 2025) | MUST |
| URS-14-INT-013 | ARCH-AI-001 binding | MUST |
### 15.9 Reporting (REP)
| ID | Requirement | Priority |
|---|---|---|
| URS-14-REP-001..009 | Per §9 | MUST |
### 15.10 Notifications (NOTIF)
| ID | Requirement | Priority |
|---|---|---|
| URS-14-NOTIF-001..013 | Per §10 | MUST |
### 15.11 Validation (VAL)
| ID | Requirement | Priority |
|---|---|---|
| URS-14-VAL-001 | URS approval | Pending Founder + signatories |
| URS-14-VAL-002 | Functional Specification | Pending |
| URS-14-VAL-003 | IQ / OQ / PQ executed | Pending |
| URS-14-VAL-004 | Traceability matrix | Pending |
| URS-14-VAL-005 | Risk-based testing per FDA CSA | Pending |
| URS-14-VAL-006 | RLS evidence | Pending |
| URS-14-VAL-007 | Audit trail integrity evidence | Pending |
| URS-14-VAL-008 | Migration evidence gate | Pending |
| URS-14-VAL-009 | Internal forward-looking AI governance evidence (EU GMP Annex 22 Draft 2025 GenAI prohibition control) | Pending |
| URS-14-VAL-010 | ARCH-AI-001 AC-1..AC-7 advisory AI evidence pack | Pending |
| URS-14-VAL-011 | Internal forward-looking AI governance evidence (EU AI Act Art. 13 transparency principles) | Pending |
| URS-14-VAL-012 | SoD-14-01..08 enforcement evidence | Pending |
| URS-14-VAL-013 | Closure prerequisite enforcement evidence | Pending |
| URS-14-VAL-014 | Field alert / recall complaint linkage evidence | Pending |
| URS-14-VAL-015 | PV reportability per-jurisdiction ruleset evidence | Pending |
| URS-14-VAL-016 | Recall executive authority co-sign procedural evidence | Pending |
---
## 16. Acceptance Criteria and Test Cases
### 16.1 Plain-language test cases
| TC | Plain-language test |
|---|---|
| TC-14-01 | Intake → triage → investigation → AE capture → PV reportability signed → response approved + issued → field alert approved → recall approved + executive authority cosigned → effectiveness effective → closure all signed → complaint closed. |
| TC-14-02 | Intake user attempts triage; rejected via SoD-14-01. |
| TC-14-03 | PV reviewer attempts to also serve as PV co-signer for serious AE; rejected via SoD-14-03. |
| TC-14-04 | Response drafter attempts to also approve; rejected via SoD-14-04. |
| TC-14-05 | Field alert created without `complaint_id`; rejected via `COMPLAINT_FIELD_ALERT_LINKAGE_REQUIRED` (CMP-006 enforcement). |
| TC-14-06 | Recall created without `complaint_id`; rejected via `COMPLAINT_RECALL_LINKAGE_REQUIRED` (CMP-007 enforcement). |
| TC-14-07 | Recall approval attempted without executive authority co-sign; rejected via `COMPLAINT_RECALL_EXECUTIVE_AUTHORITY_REQUIRED`. |
| TC-14-08 | Closure attempted with missing PV decision; rejected. |
| TC-14-09 | Closure attempted with field alert pending; rejected. |
| TC-14-10 | Reopen attempted by non-executive-authority; rejected. |
| TC-14-11 | GenAI invocation attempted in AE reportability path; runtime block + `COMPLAINT_GENAI_PROHIBITED` (DEC-14-18). |
| TC-14-12 | Static deterministic similarity returns top-N similar complaints with provenance; advisory banner shown; no autonomous write. |
| TC-14-13 | Viewer attempts raw PII; rejected via `COMPLAINT_PII_ACCESS_DENIED` (DEC-14-25). |
| TC-14-14 | Tenant offboarding cascade archives open complaints; closed records preserved. |
| TC-14-15 | Inspector evidence pack exported with watermark + audit hash-chain proof. |
### 16.2 Technical test cases
| TC | Test technique |
|---|---|
| TC-14-T01 | Unit test on service-layer SoD-14-01..08; assert HTTP 403 + correct error code. |
| TC-14-T02 | Integration test on field alert + recall persistence with `complaint_id` per CMP-006/007. |
| TC-14-T03 | Integration test on closure 6-prereq; assert each blocks correctly. |
| TC-14-T04 | Integration test on recall matrix + executive authority co-sign per DEC-14-13/21. |
| TC-14-T05 | Integration test on PV reportability per-jurisdiction deterministic ruleset. |
| TC-14-T06 | RLS test: tenant A user cannot read tenant B complaints. |
| TC-14-T07 | Audit test: every mutation produces URS-06 audit entry. |
| TC-14-T08 | E2E test (Playwright): full happy-path lifecycle. |
| TC-14-T09 | Performance test: list filter P95 latency ≤ 500ms with 100K complaints in tenant. |
| TC-14-T10 | Security test: bulk export >20 triggers authority gate. |
| TC-14-T11 | Tenant-isolation test: TDAL violation blocked. |
| TC-14-T12 | Annex 22 negative test: any GenAI in critical decision path blocked at runtime + lint. |
| TC-14-T13 | PII redaction test: PII tokenised in viewer view; raw PII visible only to authorised role. |
| TC-14-T14 | Context-model consistency test: `study_id` nullability matches across schema/type/persistence per CMP-011. |
### 16.3 Acceptance criteria
| AC | Statement |
|---|---|
| AC-14-01 | Complaint registry supports all launch classifications + lifecycle + numbering. |
| AC-14-02 | Triage SoD-14-01 enforced. |
| AC-14-03 | Investigation links deviation/RCA/CAPA per CMP-003. |
| AC-14-04 | PV reportability per-jurisdiction deterministic ruleset; serious co-sign per SoD-14-03. |
| AC-14-05 | Response approval SoD-14-04 enforced; external-copy hash recorded. |
| AC-14-06 | Field alert preserves `complaint_id` per CMP-006. |
| AC-14-07 | Recall preserves `complaint_id` per CMP-007. |
| AC-14-08 | Recall approval matrix + executive authority co-sign per DEC-14-13/21. |
| AC-14-09 | Closure 6-prereq non-bypassable per CMP-015. |
| AC-14-10 | Reopen executive authority + SoD-14-08 per DEC-14-22. |
| AC-14-11 | Annex 22 GenAI prohibition enforced runtime + lint per DEC-14-18. |
| AC-14-12 | ARCH-AI-001 AC-1..AC-7 satisfied for advisory surfaces. |
| AC-14-13 | All Module 14 tables RLS-enabled per QS-6. |
| AC-14-14 | Every mutation produces audit entry per QS-1. |
| AC-14-15 | PII restricted to authorised Authority Profile per DEC-14-25. |
```mermaid
sequenceDiagram
participant Intake
participant Triage
participant Inv as Investigator
participant PV as PV Reviewer
participant CQ as Customer Quality Lead
participant FA as Field Alert Approver
participant Rec as Recall Matrix
participant ExecAuthority
participant Close as Closure Authority
participant ESign as URS-04 E-Sign
participant Audit as URS-06
Intake->>Triage: create complaint
Triage->>ESign: triage e-sign (SoD-14-01)
ESign-->>Triage: signature
Triage->>Audit: log triage
Triage->>Inv: open investigation
Inv->>ESign: investigation e-sign (SoD-14-02)
ESign-->>Inv: signature
Inv->>Audit: log investigation
Inv->>PV: AE captured
PV->>ESign: reportability e-sign (SoD-14-03 if serious)
ESign-->>PV: signature
PV->>Audit: log PV decision
CQ->>ESign: response approve + issue (SoD-14-04)
ESign-->>CQ: signatures
CQ->>Audit: log response
FA->>ESign: field alert approve (SoD-14-05)
ESign-->>FA: signature
FA->>Audit: log field alert
Rec->>ESign: recall matrix slots e-sign (SoD-14-06)
Rec->>ExecAuthority: executive authority co-sign DEC-14-21
ExecAuthority->>ESign: executive authority e-sign
ESign-->>ExecAuthority: signature
Rec->>Audit: log recall
Close->>Close: 6-prereq check
Close->>ESign: closure e-sign (SoD-14-07)
ESign-->>Close: signature
Close->>Audit: log closure with prereq evidence
```
Diagram 16-A — End-to-end happy-path acceptance test sequence: full complaint lifecycle including investigation, AE PV, response, field alert, recall (with executive authority co-sign), closure (with 6-prereq + SoD-14-07).
### 16.4 Requirements-to-test traceability
| Requirement ID | Test Case ID | AC ID |
|---|---|---|
| URS-14-FE-001..021 | TC-14-T08, TC-14-T13 | AC-14-01..15 |
| URS-14-BE-001..018 | TC-14-T01..07, TC-14-T09..14 | AC-14-01..15 |
| URS-14-WF-001..010 | TC-14-T01..05 | AC-14-02..10 |
| URS-14-DATA-001..014 | TC-14-T06, TC-14-T14 | AC-14-13 |
| URS-14-SEC-001..010 | TC-14-T06, TC-14-T10..13 | AC-14-13, AC-14-15 |
| URS-14-AUD-001..007 | TC-14-T07 | AC-14-14 |
| URS-14-AI-001..008 | TC-14-T12 | AC-14-11..12 |
| URS-14-INT-001..013 | TC-14-T08 | AC-14-15 |
---
## 17. Validation and CSV/CSA Evidence Expectations
### 17.1 Supplier and service-provider qualification pack
- E-signature substrate provider qualification (URS-04).
- MedDRA terminology licence + version evidence.
- Hosting region qualification per tenant residency.
### 17.2 Inspection-ready evidence index
- URS approval pack (this document + signatories).
- Functional Specification per `complaints` code module.
- IQ / OQ / PQ scripts and execution evidence.
- Traceability matrix.
- Risk-based testing per FDA CSA.
- RLS evidence per QS-6.
- Audit trail integrity evidence.
- Migration evidence (URS-14-VAL-008).
- Internal forward-looking AI governance evidence (EU GMP Annex 22 Draft 2025 GenAI prohibition control: runtime block test, lint rule, design-review record).
- ARCH-AI-001 AC-1..AC-7 advisory AI evidence pack.
- Internal forward-looking AI governance evidence (EU AI Act Art. 13 transparency principles).
- SoD-14-01..08 enforcement evidence.
- Closure 6-prerequisite enforcement evidence.
- Field alert / recall complaint linkage evidence.
- PV reportability per-jurisdiction ruleset evidence.
- Recall executive authority co-sign procedural evidence (DEC-14-21).
- Reopen executive authority co-sign procedural evidence (DEC-14-22).
- PII redaction + restricted-access evidence (DEC-14-25 / GDPR).
---
## 18. Closed Decision and Dependency Register
### 18.1 Closed Launch Decisions Register
DEC-14-01..25 per §2.3 are all closed for launch. Each carries its rationale.
| ID | Disposition |
|---|---|
| DEC-14-01..02 | Locked;/CMP-008. |
| DEC-14-03 | Locked; + extended taxonomy. |
| DEC-14-04 | Locked; triage SoD-14-01/010. |
| DEC-14-05 | Locked;. |
| DEC-14-06 | Locked; with MedDRA adoption. |
| DEC-14-07 | Locked; per-jurisdiction PV reportability rules. |
| DEC-14-08..09 | Locked; + SoD-14-04. |
| DEC-14-10..11 | Locked; linkage preserved + field-alert authority. |
| DEC-14-12..13 | Locked; linkage preserved + recall matrix. |
| DEC-14-14 | Locked; advisory similarity. |
| DEC-14-15 | Locked; closure 6-prereq. |
| DEC-14-16..17 | Locked; / CMP-012. |
| DEC-14-18 | Locked; EU GMP Annex 22 critical-decision GenAI prohibition. |
| DEC-14-19..20 | Locked; ARCH-AI-001 advisory AI binding + EU AI Act Art. 13 transparency. |
| DEC-14-21..22 | Locked; executive authority co-sign requirements (recall + reopen). |
| DEC-14-23 | Locked; per URS-08 cascade. |
| DEC-14-24 | Locked; URS-13 linkage when complaint precipitates platform changes. |
| DEC-14-25 | Locked; complainant PII privacy per GDPR. |
### 18.2 Dependencies
| Dependency | Direction | Source |
|---|---|---|
| URS-01 authentication | Inbound | URS-01 module URS |
| URS-02 RBAC | Inbound | URS-02 module URS |
| URS-03 active scope | Inbound | URS-03 module URS |
| URS-04 workflow / e-signature | Inbound | URS-04 module URS |
| URS-05 Authority Profile | Inbound | URS-05 module URS |
| URS-06 audit substrate | Inbound | URS-06 module URS |
| URS-08 tenant lifecycle cascade | Inbound | URS-08 module URS |
| URS-10 Product | Inbound | URS-10 module URS |
| URS-11 Supplier | Inbound | URS-11 module URS |
| URS-12 Documents | Inbound | URS-12 module URS |
| URS-13 (when complaints precipitate platform changes) | Outbound | URS-13 module URS |
| URS-16 Deviations | Bidirectional | URS-16 module URS |
| URS-17 RCA | Bidirectional | URS-17 module URS |
| URS-18 CAPA | Bidirectional | URS-18 module URS |
| URS-21 Findings | Outbound | URS-21 module URS |
| URS-22 Inspection Mgmt | Outbound | URS-22 module URS |
| URS-23 Batch Records | Inbound | URS-23 module URS |
| URS-27 Regulatory Intelligence (PV / FAR / recall submissions) | Outbound | URS-27 module URS |
| URS-30 Notifications | Outbound | URS-30 module URS |
| EU GMP Annex 22 (Draft 2025) | Internal forward-looking architectural reference (not enacted predicate rule) | Internal forward-looking AI governance evidence (Annex 22 platform reference) |
| ARCH-AI-001 AI Optionality and Manual Continuity | Architectural binding | ARCH-AI-001 platform binding |
---
## 19. Completeness Checklist
| Item | Priority |
|---|---|
| Header + mapping + Code Modules Mapped + Architecture Bindings (Annex 22 + ARCH-AI-001) | ✓ |
| Plain-language primer + glossary + architectural picture | ✓ |
| Complaint lifecycle diagram | ✓ |
| Module Purpose | ✓ |
| Scope (in / out / closed launch decisions) | ✓ |
| User Roles + Authority Profiles + SoD-14-01..08 + worked examples + role-permission matrix | ✓ |
| 28 end-to-end user journeys | ✓ |
| Front-end expected state | ✓ |
| Back-end expected state (entities + ER + lifecycle + PV flow + recall matrix flow + data + API + workflow + business rules + audit) | ✓ |
| Annex 22 + ARCH-AI-001 architecture reference section | ✓ |
| Cross-module wiring + CIM + dependencies | ✓ |
| AI / Automation / HITL controls (with Annex 22 prohibition) | ✓ |
| Reports / dashboards / exports | ✓ |
| Notifications and queues | ✓ |
| Error envelope + error-code catalogue + negative paths | ✓ |
| Security, privacy, tenant isolation (with PII protection) | ✓ |
| ALCOA+ controls | ✓ |
| Regulatory mapping | ✓ |
| URS Requirements Register (FE / BE / WF / DATA / SEC / AUD / AI / INT / REP / NOTIF / VAL) | ✓ |
| Acceptance Criteria + Test Cases + traceability | ✓ |
| Validation evidence expectations | ✓ |
| Closed decisions + dependencies | ✓ |
| Module scoped strictly to Complaints | ✓ |
| Version 1.0 only | ✓ |
---
## 20. Final Module Output Quality Gate
**URS approval is separate from validation execution.** This document becomes "Approved Controlled URS — released for engineering implementation and validation planning" upon signature capture; it becomes "Released for validation execution" only after URS-14-VAL-008 (Migration Evidence Gate) and the §17 validation evidence pack are satisfied. **No Module 14 internal open questions remain.**
- **Specification ready for engineering review?** Yes — every requirement is fully specified within this URS..CMP-REQ-012 and §2 CMP-001..CMP-017 .
- **Specification ready for quality validation review?** Yes — IQ/OQ/PQ + RLS evidence + audit chain integrity + Annex 22 GenAI-prohibition evidence + ARCH-AI-001 AC-1..AC-7 advisory AI evidence + EU AI Act Art. 13 transparency + SoD enforcement evidence + closure prerequisite evidence + linkage preservation evidence + executive authority co-sign procedural evidence are itemised in §17.
- **Specification ready for compliance review?** Yes — ALCOA+, 21 CFR Part 11 §11.10(a/d/e/g) §11.50/11.70/11.100/11.200/11.300, 21 CFR §211.198, 21 CFR §314.80, 21 CFR §314.81, 21 CFR Part 7, EU GMP Annex 11 §4/9/12/16, EU GMP Chapter 8, EudraVigilance ICH E2D, MHRA Yellow Card, Health Canada Vigilance, PMDA, CDSCO, MHRA ALCOA+, ICH Q10, ICH E2D, MedDRA, GAMP 5 Cat 5, FDA CSA Final Guidance (Sep 2025), WHO TRS 996 Annex 5 — all mapped in §14. EU GMP Annex 22 (Draft 2025) and EU AI Act Art. 13 are treated as internal forward-looking architectural controls; jurisdiction-specific legal enforceability remains subject to a future jurisdiction-specific legal assessment.
- **Specification ready for inspector / client review?** Yes — 28 end-to-end journeys (§4), full requirements register (§15), evidence pack index (§17.2).
- **Specification ready for Founder approval?** Yes.
- **Blocking gaps?** None internal. Cross-module dependencies (§18.2) are owned by named companion modules.
- **Two-step release path:**
1. **Approved Controlled URS — released for engineering implementation and validation planning.** Reached upon signature capture.
2. **Released for validation execution.** Reached after URS-14-VAL-008 is satisfied and the §17 evidence pack is complete.
---
## Appendix A — Module 14 End-to-End Composite (Intake → Triage → Investigation → AE/PV → Response → Field Action → Recall → Closure)
```mermaid
flowchart TD
A([complaint_intake creates complaint]) --> B[RECEIVED]
B --> C[customer_quality_reviewer triages SoD-14-01]
C --> D{Triage outcome}
D -- valid quality defect --> E[UNDER_INVESTIGATION SoD-14-02]
D -- invalid --> F[REJECTED_INVALID terminal]
D -- info request only --> G[PENDING_RESPONSE direct]
E --> H[Investigation links to URS-16 deviation / URS-17 RCA / URS-18 CAPA]
H --> I{Disposition}
I -- field action required --> J[FIELD_ACTION_PENDING]
I -- no field action --> G
J --> K[Field alert with complaint_id PRESERVED CMP-006 + approver SoD-14-05]
J --> L[Recall with complaint_id PRESERVED CMP-007 + matrix SoD-14-06 + executive authority DEC-14-21]
K --> G
L --> G
E --> M[AE captured if PV implication]
M --> N[PV reportability per jurisdiction deterministic + SoD-14-03 for serious]
N -.Annex 22.-> NoGenAI[NO GenAI in decision per DEC-14-18]
N --> O[URS-27 submission FDA EMA MHRA HC PMDA CDSCO]
G --> P[Response drafted]
P --> Q[Response approved SoD-14-04]
Q --> R[Response issued + external_copy_hash]
R --> S[RESPONSE_ISSUED]
S --> T{Closure 6-prereq check}
T -- investigation incomplete --> U[Block: investigation incomplete]
T -- PV decision pending --> V[Block: PV pending]
T -- response not issued --> W[Block: response]
T -- field action pending --> X[Block: field action]
T -- recall executive authority cosign pending --> Y[Block: recall executive authority]
T -- all 6 prereq satisfied --> Z[complaint_closure_authority e-signs SoD-14-07]
Z --> AA[CLOSED]
AA --> AB{Lifecycle event}
AB -- post-closure issue --> AC[executive authority co-sign reopen DEC-14-22 SoD-14-08 → REOPENED → UNDER_INVESTIGATION]
AB -- normal --> AD[Terminal closed]
F --> AE[Terminal rejected]
R -.advisory.-> AF[Static deterministic similarity per CMP-016 ARCH-AI-001 AC-2]
S -.advisory.-> AG[Signal trend dashboard]
```
Diagram Appendix A — Module 14 End-to-End Composite. Single composite flow showing intake → triage → investigation with cross-module linkage → field action with linkage preserved (CMP-006 / CMP-007) → recall with executive authority co-sign (DEC-14-21) → AE / PV with deterministic reportability (internal Annex 22 control prohibition) → response with SoD-14-04 → closure with 6-prerequisite gate (CMP-015) → terminal states with reopen path requiring executive authority co-sign (DEC-14-22 + SoD-14-08). Under the internal Annex 22 Draft 2025 forward-looking AI governance control (not enacted predicate rule), generative AI is prohibited in critical decisions; ARCH-AI-001 governs advisory deterministic AI in similarity / signal / triage suggestion. Binding predicate-rule obligations remain those listed in §14.
— End of Module 14 User Requirements Specification —