elevenlabs-webhook-nodejs 1.0.0

package/docs/architecture/20-TREATMENTS-AND-PLANS.md

@@ -0,0 +1,774 @@
+# Treatments & Treatment Plans
+
+> Service catalog and multi-visit treatment plans -- clinic-defined treatments with pricing and recall, patient-specific plans with ordered items linked to appointments.
+> Last updated: 2026-03-29
+
+---
+
+## Table of Contents
+
+1. [Overview](#1-overview)
+2. [Treatment Model (Service Catalog)](#2-treatment-model-service-catalog)
+3. [Treatment Plan Model](#3-treatment-plan-model)
+4. [Treatment Plan Item Model](#4-treatment-plan-item-model)
+5. [Treatment Plan Workflow](#5-treatment-plan-workflow)
+6. [AI Integration](#6-ai-integration)
+7. [API Endpoints](#7-api-endpoints)
+8. [Permissions](#8-permissions)
+9. [Recall Automation (P1 -- Design Reference)](#9-recall-automation-p1----design-reference)
+10. [NestJS Module Structure](#10-nestjs-module-structure)
+
+---
+
+## 1. Overview
+
+Two core concepts support clinical workflow:
+
+- **Treatment** (service catalog) -- What the clinic offers. Each clinic defines its treatments with name, category, duration, price, and recall period. This is the menu of services the clinic sells. Treatments are reusable across patients.
+- **Treatment Plan** -- A multi-visit plan for a specific patient. Contains ordered items, each linked to a treatment from the catalog and optionally to an appointment. This is the doctor's prescription of what needs to happen for this patient, in what order.
+
+### Concrete Example
+
+A dental clinic's treatment catalog:
+
+| Treatment | Category | Duration | Price | Recall |
+|-----------|----------|----------|-------|--------|
+| Root Canal | Endodonti | 60 min | 3,000 TRY | -- |
+| Crown Prep | Protez | 45 min | 2,000 TRY | -- |
+| Crown Fit | Protez | 30 min | 1,500 TRY | -- |
+| Dental Cleaning | Genel | 30 min | 500 TRY | 180 days |
+| Teeth Whitening | Estetik | 60 min | 1,500 TRY | 365 days |
+
+A treatment plan for patient Ayse -- **"Tooth 14 Restoration"**:
+
+| # | Item | Treatment | Status | Appointment |
+|---|------|-----------|--------|-------------|
+| 1 | Root canal, tooth 14 | Root Canal | completed | 2026-03-15 10:00 |
+| 2 | Crown preparation, tooth 14 | Crown Prep | scheduled | 2026-04-05 14:00 |
+| 3 | Crown fitting, tooth 14 | Crown Fit | planned | -- |
+
+The three items reference treatments from the catalog. Item 1 is done, item 2 has an appointment booked, item 3 is still unscheduled. When all items are completed, the plan status moves to `completed`.
+
+---
+
+## 2. Treatment Model (Service Catalog)
+
+### Prisma Schema
+
+```prisma
+model Treatment {
+  treatment_id               String   @id @default(uuid())
+  treatment_tenant_id        String
+  treatment_clinic_id        String?  // null = available at all clinics in tenant
+  treatment_name             String
+  treatment_category         String   @default("")  // "Implant", "Ortodonti", "Estetik", "Genel"
+  treatment_description      String   @default("")
+  treatment_duration_minutes Int      @default(30)
+  treatment_price            Decimal?
+  treatment_currency         String   @default("TRY")
+  treatment_is_active        Boolean  @default(true)
+  treatment_sort_order       Int      @default(0)
+  treatment_recall_days      Int?     // null = no recall. e.g., 180 for biannual cleaning
+  treatment_created_at       DateTime @default(now())
+  treatment_updated_at       DateTime @updatedAt
+
+  tenant       Tenant              @relation(fields: [treatment_tenant_id], references: [tenant_id], onDelete: Cascade)
+  clinic       Clinic?             @relation(fields: [treatment_clinic_id], references: [clinic_id], onDelete: SetNull)
+  planItems    TreatmentPlanItem[]
+  appointments Appointment[]
+
+  @@index([treatment_tenant_id, treatment_is_active])
+  @@index([treatment_tenant_id, treatment_category])
+  @@index([treatment_clinic_id])
+  @@map("treatments")
+}
+```
+
+### Columns
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `treatment_id` | UUID | Yes | `uuid()` | Primary key |
+| `treatment_tenant_id` | UUID | Yes | -- | FK to `tenants`. Tenant isolation |
+| `treatment_clinic_id` | UUID | No | `null` | FK to `clinics`. Null = tenant-level treatment available at all clinics. Non-null = only available at that specific clinic |
+| `treatment_name` | String | Yes | -- | Display name. E.g., "Root Canal", "Diş Beyazlatma", "Botox (1 Bölge)" |
+| `treatment_category` | String | Yes | `""` | Free-form category string. E.g., "Implant", "Ortodonti", "Estetik", "Genel", "Cerrahi" |
+| `treatment_description` | String | Yes | `""` | Optional longer description. Shown in treatment detail view and optionally provided to AI |
+| `treatment_duration_minutes` | Int | Yes | `30` | Default appointment duration in minutes. Used when booking an appointment for this treatment |
+| `treatment_price` | Decimal | No | `null` | Price in `treatment_currency`. Null = "price on consultation" or varies. Decimal, not float, for currency safety |
+| `treatment_currency` | String | Yes | `"TRY"` | ISO 4217 currency code. Turkish clinics default to TRY |
+| `treatment_is_active` | Boolean | Yes | `true` | Soft delete flag. Inactive treatments are hidden from the catalog but preserved for historical plan items |
+| `treatment_sort_order` | Int | Yes | `0` | Display order within the catalog. Lower values appear first |
+| `treatment_recall_days` | Int | No | `null` | Number of days after completion to schedule a recall reminder. Null = no recall. E.g., 180 for biannual cleaning, 365 for annual checkup |
+| `treatment_created_at` | DateTime | Yes | `now()` | Record creation timestamp |
+| `treatment_updated_at` | DateTime | Yes | auto | Automatically updated on every write |
+
+### Indexes
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `treatment_id` | PK lookup |
+| `idx_treatments_tenant_active` | `(treatment_tenant_id, treatment_is_active)` | List active treatments for a tenant (the default catalog query) |
+| `idx_treatments_tenant_category` | `(treatment_tenant_id, treatment_category)` | Filter by category within tenant |
+| `idx_treatments_clinic` | `treatment_clinic_id` | List treatments scoped to a specific clinic |
+
+### Relations
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| belongs_to | tenants | `treatment_tenant_id` | Parent tenant (cascade delete) |
+| belongs_to | clinics | `treatment_clinic_id` | Owning clinic, nullable (set null on clinic delete) |
+| has_many | treatment_plan_items | -- | Plan items that reference this treatment |
+| has_many | appointments | -- | Appointments for this treatment type |
+
+### Key Design Decisions
+
+**`treatment_clinic_id` null = tenant-level treatment.** A multi-clinic tenant (e.g., a dental chain with 3 branches) defines most treatments at the tenant level so all clinics share the same catalog. Clinic-specific treatments (e.g., a branch with a specialized laser machine) are scoped with a non-null `treatment_clinic_id`. Single-clinic tenants never set this -- everything is tenant-level, and the default clinic is used implicitly.
+
+**`treatment_recall_days` enables recall automation.** When a treatment plan item linked to a treatment with `recall_days` set is marked completed, a BullMQ delayed job can be scheduled to trigger a recall reminder (WhatsApp message, outbound call, or SMS). This is the foundation for recall campaigns -- see Section 9.
+
+**Price is optional and Decimal.** Many clinics do not list prices publicly ("muayene sonrası fiyatlandırma" -- pricing after examination). Others have fixed prices. Using `Decimal` instead of `Float` prevents floating-point arithmetic errors in currency calculations. A treatment with `null` price means "consult for pricing."
+
+**Category is a free-form string, not an enum.** Turkish dental clinics use categories like "Endodonti", "Protez", "Ortodonti", "Cerrahi", "Estetik". Aesthetic clinics use "Botox", "Dolgu", "Lazer", "Saç Ekimi". Enforcing an enum would either be too restrictive or require constant updates. Free-form strings let each clinic define their own taxonomy. The `GET /treatments/categories` endpoint provides autocomplete suggestions from existing data.
+
+**Soft delete via `treatment_is_active`.** Deleting a treatment would orphan historical plan items. Instead, "deleting" a treatment sets `treatment_is_active = false`. The treatment disappears from the catalog but remains in the database so existing plan items retain their `treatment_id` reference.
+
+---
+
+## 3. Treatment Plan Model
+
+### Prisma Schema
+
+```prisma
+model TreatmentPlan {
+  plan_id          String               @id @default(uuid())
+  plan_tenant_id   String
+  plan_clinic_id   String?
+  plan_patient_id  String
+  plan_doctor_id   String?              // FK to users (doctor who created/manages the plan)
+  plan_name        String               // "Tooth 14 Restoration", "Full Smile Makeover"
+  plan_status      TreatmentPlanStatus  @default(active)
+  plan_notes       String               @default("")
+  plan_created_at  DateTime             @default(now())
+  plan_updated_at  DateTime             @updatedAt
+
+  tenant    Tenant              @relation(fields: [plan_tenant_id], references: [tenant_id], onDelete: Cascade)
+  clinic    Clinic?             @relation(fields: [plan_clinic_id], references: [clinic_id], onDelete: SetNull)
+  patient   Patient             @relation(fields: [plan_patient_id], references: [patient_id], onDelete: Cascade)
+  doctor    User?               @relation("PlanDoctor", fields: [plan_doctor_id], references: [user_id], onDelete: SetNull)
+  items     TreatmentPlanItem[]
+  photoSets PatientPhotoSet[]   // Before/after photos linked to plan (see doc 21)
+
+  @@index([plan_patient_id, plan_status])
+  @@index([plan_tenant_id, plan_status])
+  @@index([plan_doctor_id])
+  @@index([plan_clinic_id])
+  @@map("treatment_plans")
+}
+
+enum TreatmentPlanStatus {
+  active
+  completed
+  cancelled
+}
+```
+
+### Columns
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `plan_id` | UUID | Yes | `uuid()` | Primary key |
+| `plan_tenant_id` | UUID | Yes | -- | FK to `tenants`. Tenant isolation |
+| `plan_clinic_id` | UUID | No | `null` | FK to `clinics`. Which clinic manages this plan. Null for single-clinic tenants |
+| `plan_patient_id` | UUID | Yes | -- | FK to `patients`. The patient this plan is for |
+| `plan_doctor_id` | UUID | No | `null` | FK to `users`. The doctor who created or manages this plan. Null if created by receptionist or unassigned |
+| `plan_name` | String | Yes | -- | Free-form plan name. E.g., "Diş 14 Restorasyonu", "Full Smile Makeover", "Alt Çene İmplant" |
+| `plan_status` | TreatmentPlanStatus | Yes | `active` | Plan lifecycle state: `active` (in progress), `completed` (all items done), `cancelled` (abandoned) |
+| `plan_notes` | String | Yes | `""` | Free-form notes about the plan. Doctor's observations, special instructions |
+| `plan_created_at` | DateTime | Yes | `now()` | Record creation timestamp |
+| `plan_updated_at` | DateTime | Yes | auto | Automatically updated on every write |
+
+### Indexes
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `plan_id` | PK lookup |
+| `idx_plans_patient_status` | `(plan_patient_id, plan_status)` | List active plans for a patient (the primary query on patient detail page) |
+| `idx_plans_tenant_status` | `(plan_tenant_id, plan_status)` | List all active plans across a tenant (dashboard/reporting) |
+| `idx_plans_doctor` | `plan_doctor_id` | List plans managed by a specific doctor |
+| `idx_plans_clinic` | `plan_clinic_id` | List plans at a specific clinic |
+
+### Relations
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| belongs_to | tenants | `plan_tenant_id` | Parent tenant (cascade delete) |
+| belongs_to | clinics | `plan_clinic_id` | Managing clinic, nullable (set null on clinic delete) |
+| belongs_to | patients | `plan_patient_id` | Parent patient (cascade delete -- deleting a patient removes their plans) |
+| belongs_to | users | `plan_doctor_id` | Responsible doctor, nullable (set null on user delete) |
+| has_many | treatment_plan_items | -- | Ordered items in this plan |
+| has_many | patient_photo_sets | -- | Before/after photo sets linked to this plan (see doc 21) |
+
+### Key Design Decisions
+
+**Plan belongs to a patient and optionally a doctor.** Every plan must have a patient. The doctor is optional because a receptionist might create the plan and assign a doctor later, or a solo practitioner might not bother assigning themselves.
+
+**Status is simple: three states.** `active` means the plan is in progress (some items planned, some completed). `completed` means all items are done. `cancelled` means the plan was abandoned (patient didn't return, changed their mind, etc.). No `draft` or `pending_approval` states -- Turkish clinics don't typically have approval workflows for treatment plans. The doctor creates it and it's immediately active.
+
+**No financial fields on the plan.** Total cost, payments, and invoicing are deferred per product decision. The plan is a clinical document, not an invoice. Financial tracking will be handled separately when the billing module extends to patient-level charges. For now, treatment prices live on the Treatment model, and plan items inherit the treatment name.
+
+**`plan_name` is free-form.** Doctors write whatever describes the plan: "Diş 14 Restorasyonu", "Tam Ağız Rehabilitasyonu", "Botox + Dudak Dolgusu". No templates, no structured naming. Clinics across specialties (dental, aesthetic, dermatology) use completely different naming conventions.
+
+**Cascade delete from patient.** If a patient record is deleted, all their treatment plans and plan items are removed. This is consistent with `PatientPhotoSet` cascade behavior (doc 21).
+
+---
+
+## 4. Treatment Plan Item Model
+
+### Prisma Schema
+
+```prisma
+model TreatmentPlanItem {
+  item_id              String                   @id @default(uuid())
+  item_plan_id         String
+  item_treatment_id    String?                  // FK to treatments (null if custom/one-off)
+  item_appointment_id  String?                  // FK to appointments (linked after booking)
+  item_name            String                   // Denormalized treatment name (survives treatment deletion)
+  item_tooth_number    String?                  // Dental: "14", "21-23", "UL6"
+  item_status          TreatmentPlanItemStatus  @default(planned)
+  item_notes           String                   @default("")
+  item_sort_order      Int                      @default(0)
+  item_completed_at    DateTime?
+  item_created_at      DateTime                 @default(now())
+  item_updated_at      DateTime                 @updatedAt
+
+  plan        TreatmentPlan @relation(fields: [item_plan_id], references: [plan_id], onDelete: Cascade)
+  treatment   Treatment?    @relation(fields: [item_treatment_id], references: [treatment_id], onDelete: SetNull)
+  appointment Appointment?  @relation(fields: [item_appointment_id], references: [appt_id], onDelete: SetNull)
+
+  @@index([item_plan_id, item_sort_order])
+  @@index([item_appointment_id])
+  @@map("treatment_plan_items")
+}
+
+enum TreatmentPlanItemStatus {
+  planned       // Not yet scheduled
+  scheduled     // Appointment linked
+  in_progress   // Currently being performed
+  completed     // Done
+  cancelled     // Cancelled
+}
+```
+
+### Columns
+
+| Column | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `item_id` | UUID | Yes | `uuid()` | Primary key |
+| `item_plan_id` | UUID | Yes | -- | FK to `treatment_plans`. The plan this item belongs to |
+| `item_treatment_id` | UUID | No | `null` | FK to `treatments`. The catalog treatment this item represents. Null for custom/one-off items not in the catalog |
+| `item_appointment_id` | UUID | No | `null` | FK to `appointments`. Linked when an appointment is booked for this item. Null until scheduled |
+| `item_name` | String | Yes | -- | Display name for this item. Copied from `treatment_name` on creation, but stored separately (denormalized). E.g., "Root Canal", "Botox (1 Bölge)" |
+| `item_tooth_number` | String | No | `null` | Dental-specific: tooth number(s) this item applies to. E.g., "14", "21-23" (range), "UL6" (Palmer notation). Non-dental specialties leave this null |
+| `item_status` | TreatmentPlanItemStatus | Yes | `planned` | Item lifecycle state. See status transitions below |
+| `item_notes` | String | Yes | `""` | Per-item notes. E.g., "Patient requested sedation", "Use ceramic crown" |
+| `item_sort_order` | Int | Yes | `0` | Display order within the plan. Lower values appear first. Determines the intended sequence of treatment |
+| `item_completed_at` | DateTime | No | `null` | Timestamp when the item was marked completed. Null for non-completed items. Used for recall scheduling |
+| `item_created_at` | DateTime | Yes | `now()` | Record creation timestamp |
+| `item_updated_at` | DateTime | Yes | auto | Automatically updated on every write |
+
+### Indexes
+
+| Index | Columns | Purpose |
+|-------|---------|---------|
+| Primary | `item_id` | PK lookup |
+| `idx_items_plan_order` | `(item_plan_id, item_sort_order)` | List items in order within a plan (the primary query) |
+| `idx_items_appointment` | `item_appointment_id` | Reverse lookup: which plan item is this appointment for? |
+
+### Relations
+
+| Direction | Target | FK Column | Description |
+|-----------|--------|-----------|-------------|
+| belongs_to | treatment_plans | `item_plan_id` | Parent plan (cascade delete -- deleting a plan removes all items) |
+| belongs_to | treatments | `item_treatment_id` | Catalog treatment reference, nullable (set null on treatment delete) |
+| belongs_to | appointments | `item_appointment_id` | Linked appointment, nullable (set null on appointment delete) |
+
+### Status Transitions
+
+```
+planned -----> scheduled -----> in_progress -----> completed
+   |               |                |
+   +-------+-------+--------+------+
+           |                 |
+           v                 v
+       cancelled         cancelled
+```
+
+- **planned** -- Item exists in the plan but no appointment is linked. This is the initial state.
+- **scheduled** -- An appointment has been booked for this item (`item_appointment_id` is set). Transition triggered by linking an appointment.
+- **in_progress** -- The treatment is currently being performed. Typically set by the doctor during the appointment. Optional -- small clinics may skip this and go directly from scheduled to completed.
+- **completed** -- The treatment is done. `item_completed_at` is set. If the linked treatment has `treatment_recall_days`, a recall job is scheduled.
+- **cancelled** -- The item was cancelled. Can happen from any state. E.g., doctor decided this step is unnecessary, or patient declined.
+
+### Key Design Decisions
+
+**`item_treatment_id` is nullable for custom/one-off items.** A doctor might add an item to a plan that doesn't exist in the catalog: "Emergency extraction due to complication" or "Follow-up check (complimentary)". The item still has a name and participates in the plan workflow, it just doesn't reference a catalog treatment.
+
+**`item_name` is denormalized.** When a plan item is created from a catalog treatment, `item_name` is copied from `treatment_name`. If the treatment is later renamed ("Root Canal" -> "Root Canal Therapy") or soft-deleted, the plan item still shows the original name. This is critical for medical records -- what was planned must be preserved as-is.
+
+**`item_tooth_number` is dental-specific but lives on the generic model.** Dental clinics are the primary user base, and tooth numbers are essential for their workflow. Other specialties (aesthetic, dermatology) simply leave this field null. Adding a separate dental extension table for a single nullable string field would be overengineering.
+
+**`item_appointment_id` enables bidirectional tracking.** From the plan: "which items have appointments and which are still unscheduled?" From the appointment: "which plan item is this appointment for?" The `idx_items_appointment` index supports the reverse lookup. When an appointment is deleted (e.g., cancelled), the item's appointment link is set null via `onDelete: SetNull`, and the item status should be reverted to `planned` by the service layer.
+
+**Cascade delete on plan.** Deleting a treatment plan removes all its items. This is intentional -- a plan and its items are a single logical unit. Items have no independent existence outside their plan.
+
+---
+
+## 5. Treatment Plan Workflow
+
+### 5.1 Full Lifecycle
+
+```
+Doctor examines patient
+  |
+  v
+Doctor creates treatment plan with name and items from catalog
+  |  POST /patients/:patientId/treatment-plans
+  |  Body: { name, notes, items: [{ treatment_id, tooth_number, notes }] }
+  |
+  v
+Plan created with status = active, items with status = planned
+  |
+  v
+Receptionist books appointments for items
+  |  PUT /treatment-plans/:id/items/:itemId
+  |  Body: { appointment_id: "..." }
+  |  Item status -> scheduled
+  |
+  v
+Patient attends appointment
+  |  Doctor marks item as in_progress (optional)
+  |  PUT /treatment-plans/:id/items/:itemId
+  |  Body: { status: "in_progress" }
+  |
+  v
+Treatment completed
+  |  PUT /treatment-plans/:id/items/:itemId
+  |  Body: { status: "completed" }
+  |  Item status -> completed, item_completed_at = now()
+  |  If treatment.recall_days set -> schedule recall job
+  |
+  v
+Repeat for remaining items
+  |
+  v
+All items completed or cancelled
+  |  Service checks: are all items in terminal state (completed/cancelled)?
+  |  If yes -> plan status automatically set to completed
+  |
+  v
+Plan completed
+```
+
+### 5.2 Sequence Diagram: Plan Creation
+
+```
+Doctor (Frontend)           API                    TreatmentPlansService        DB
+     |                       |                            |                      |
+     |  Create plan          |                            |                      |
+     |  POST /patients/      |                            |                      |
+     |  :patientId/          |                            |                      |
+     |  treatment-plans      |                            |                      |
+     |  {name, items[]}      |                            |                      |
+     |---------------------->|                            |                      |
+     |                       |  createPlan(dto)           |                      |
+     |                       |--------------------------->|                      |
+     |                       |                            |                      |
+     |                       |                            |  Validate patient    |
+     |                       |                            |  belongs to tenant   |
+     |                       |                            |--------------------->|
+     |                       |                            |                      |
+     |                       |                            |  Validate each       |
+     |                       |                            |  treatment_id exists |
+     |                       |                            |  and is active       |
+     |                       |                            |--------------------->|
+     |                       |                            |                      |
+     |                       |                            |  Transaction:        |
+     |                       |                            |  1. Create plan      |
+     |                       |                            |  2. Create items     |
+     |                       |                            |     (copy name from  |
+     |                       |                            |      treatment)      |
+     |                       |                            |--------------------->|
+     |                       |                            |  plan + items        |
+     |                       |                            |<---------------------|
+     |                       |                            |                      |
+     |                       |  plan with items           |                      |
+     |                       |<---------------------------|                      |
+     |  201 Created          |                            |                      |
+     |<----------------------|                            |                      |
+```
+
+### 5.3 Sequence Diagram: Item Completion
+
+```
+Doctor (Frontend)           API                    TreatmentPlansService        DB             BullMQ
+     |                       |                            |                      |                |
+     |  Complete item        |                            |                      |                |
+     |  PUT /treatment-plans |                            |                      |                |
+     |  /:id/items/:itemId   |                            |                      |                |
+     |  {status: "completed"}|                            |                      |                |
+     |---------------------->|                            |                      |                |
+     |                       |  updateItem(itemId, dto)   |                      |                |
+     |                       |--------------------------->|                      |                |
+     |                       |                            |                      |                |
+     |                       |                            |  Update item:        |
+     |                       |                            |  status = completed  |
+     |                       |                            |  completed_at = now  |
+     |                       |                            |--------------------->|
+     |                       |                            |                      |                |
+     |                       |                            |  Load treatment      |
+     |                       |                            |  (check recall_days) |
+     |                       |                            |--------------------->|
+     |                       |                            |                      |                |
+     |                       |                            |  recall_days = 180   |                |
+     |                       |                            |                      |                |
+     |                       |                            |  Schedule recall job ----------------->|
+     |                       |                            |  delay = 180 days    |                |
+     |                       |                            |                      |                |
+     |                       |                            |  Check: all items    |                |
+     |                       |                            |  in terminal state?  |                |
+     |                       |                            |--------------------->|
+     |                       |                            |  yes (all done)      |                |
+     |                       |                            |<---------------------|                |
+     |                       |                            |                      |                |
+     |                       |                            |  Update plan:        |                |
+     |                       |                            |  status = completed  |                |
+     |                       |                            |--------------------->|
+     |                       |                            |                      |                |
+     |                       |  updated item + plan       |                      |                |
+     |                       |<---------------------------|                      |                |
+     |  200 OK               |                            |                      |                |
+     |<----------------------|                            |                      |                |
+```
+
+### 5.4 Automatic Plan Completion
+
+The service layer checks for automatic plan completion on every item status update:
+
+```typescript
+async updateItemStatus(itemId: string, newStatus: TreatmentPlanItemStatus): Promise<void> {
+  // ... update the item ...
+
+  // Check if all items are in a terminal state
+  const allItems = await this.prisma.treatmentPlanItem.findMany({
+    where: { item_plan_id: item.item_plan_id },
+  });
+
+  const allTerminal = allItems.every(
+    i => i.item_status === 'completed' || i.item_status === 'cancelled'
+  );
+
+  if (allTerminal) {
+    await this.prisma.treatmentPlan.update({
+      where: { plan_id: item.item_plan_id },
+      data: { plan_status: 'completed' },
+    });
+  }
+}
+```
+
+This runs inside the same database transaction as the item update. No separate background job needed -- the check is a simple array scan over a small number of items (typical plans have 2-10 items).
+
+---
+
+## 6. AI Integration
+
+Treatment plans interact with the AI agent at several points. These integrations build on the existing client tools system (doc 10).
+
+### 6.1 Appointment Booking with Plan Item Link
+
+When the AI books an appointment via the `reserve_slot` tool, it can optionally link the appointment to a treatment plan item. This enables the system to automatically update the item status from `planned` to `scheduled`.
+
+```
+AI calls reserve_slot({
+  patient_name: "Ayse Yilmaz",
+  iso_start: "2026-04-05T14:00:00+03:00",
+  iso_end: "2026-04-05T14:45:00+03:00",
+  treatment_plan_item_id: "item-uuid-here"    // Optional new parameter
+})
+```
+
+When `treatment_plan_item_id` is provided in the `reserve_slot` call:
+
+1. The appointment is created as normal (Google Calendar event + DB record).
+2. The plan item's `item_appointment_id` is set to the new appointment ID.
+3. The plan item's `item_status` is updated from `planned` to `scheduled`.
+
+This is a backward-compatible extension -- existing `reserve_slot` calls without `treatment_plan_item_id` continue to work unchanged.
+
+### 6.2 Doctor-Specific Availability
+
+When a treatment plan has a `plan_doctor_id`, the `check_availability` tool should consider that doctor's working hours. The AI context includes the doctor's user ID, and the availability calculation filters by the doctor's schedule in addition to the clinic's calendar.
+
+This does not change the `check_availability` tool interface -- the doctor filter is applied server-side based on the tool context (which patient, which plan, which doctor).
+
+### 6.3 Patient History Context
+
+The `check_patient_history` tool returns an enriched patient context that now includes treatment plans:
+
+```typescript
+// Added to PatientContext returned by check_patient_history
+{
+  // ... existing fields (name, phone, sessions, notes, tags) ...
+  treatment_plans: [
+    {
+      name: "Tooth 14 Restoration",
+      status: "active",
+      doctor: "Dr. Mehmet Kaya",
+      items: [
+        { name: "Root Canal", status: "completed", tooth: "14" },
+        { name: "Crown Prep", status: "scheduled", appointment: "2026-04-05 14:00" },
+        { name: "Crown Fit", status: "planned" }
+      ]
+    }
+  ]
+}
+```
+
+This gives the AI full awareness of the patient's treatment journey. The AI can say: "I see you have a crown preparation appointment next week for tooth 14. Would you like to schedule the crown fitting after that?"
+
+### 6.4 Future: Next-Item Slot Suggestion
+
+When a patient contacts the clinic and has an active plan with `planned` items, the AI could proactively suggest booking the next unscheduled item:
+
+```
+AI: "Merhaba Ayse Hanım! Diş 14 restorasyon planınızda kron takma işlemi henüz 
+     planlanmamış. Bu işlem için bir randevu ayarlamak ister misiniz?"
+```
+
+This is a future enhancement, not part of the initial implementation. It requires the AI prompt to include treatment plan context via `dynamic_variables` or `contextual_update`.
+
+---
+
+## 7. API Endpoints
+
+### 7.1 Treatments (Service Catalog)
+
+All treatment endpoints are tenant-scoped. Clinic filtering is optional -- if `clinicId` query parameter is provided, results include both tenant-level treatments (null `treatment_clinic_id`) and treatments scoped to that clinic.
+
+| Method | Path | Permission | Description |
+|--------|------|------------|-------------|
+| GET | `/treatments` | `treatments:read` | List treatments. Query params: `clinicId`, `category`, `active` (default true), `search`, `page`, `limit`. Returns tenant-level + clinic-specific treatments |
+| POST | `/treatments` | `treatments:manage` | Create a treatment. Body: `{ name, category, description, duration_minutes, price, currency, clinic_id, recall_days, sort_order }` |
+| GET | `/treatments/:id` | `treatments:read` | Treatment detail with usage stats (how many plan items reference this treatment) |
+| PUT | `/treatments/:id` | `treatments:manage` | Update treatment fields. Updating `name` does not change existing plan item names (denormalized) |
+| DELETE | `/treatments/:id` | `treatments:manage` | Soft-delete: sets `treatment_is_active = false`. Returns 409 Conflict if treatment has active (non-completed, non-cancelled) plan items -- require user confirmation |
+| GET | `/treatments/categories` | `treatments:read` | List unique category strings across the tenant's treatments. For autocomplete in the "category" field. Returns `string[]` |
+
+### 7.2 Treatment Plans
+
+Plan endpoints are nested under patients for creation and listing, but accessed directly by ID for updates. All endpoints enforce tenant isolation and clinic access via guards.
+
+| Method | Path | Permission | Description |
+|--------|------|------------|-------------|
+| GET | `/patients/:patientId/treatment-plans` | `patients:read` | List plans for a patient. Query params: `status` (active/completed/cancelled), `page`, `limit`. Returns plans with items included |
+| POST | `/patients/:patientId/treatment-plans` | `treatment_plans:manage` | Create plan with items in a single request. Body: `{ name, clinic_id, doctor_id, notes, items: [{ treatment_id, name, tooth_number, notes, sort_order }] }`. Items with `treatment_id` auto-populate `item_name` from the catalog |
+| GET | `/treatment-plans/:id` | `patients:read` | Plan detail with all items, linked treatments, linked appointments, and doctor info |
+| PUT | `/treatment-plans/:id` | `treatment_plans:manage` | Update plan fields: `name`, `notes`, `status`, `doctor_id`. Manually setting `status = completed` is allowed (doctor override) |
+| DELETE | `/treatment-plans/:id` | `treatment_plans:manage` | Delete plan and all items. Returns 409 Conflict if any items have `status = completed` -- completed work should not be silently deleted |
+| POST | `/treatment-plans/:id/items` | `treatment_plans:manage` | Add a new item to an existing plan. Body: `{ treatment_id, name, tooth_number, notes, sort_order }` |
+| PUT | `/treatment-plans/:id/items/:itemId` | `treatment_plans:manage` | Update item: `status`, `notes`, `appointment_id`, `tooth_number`, `sort_order`. Status changes trigger side effects (recall scheduling, auto-plan-completion) |
+| DELETE | `/treatment-plans/:id/items/:itemId` | `treatment_plans:manage` | Remove item from plan. Returns 409 if item `status = completed` |
+
+### 7.3 Response Formats
+
+**Plan list response** (GET `/patients/:patientId/treatment-plans`):
+
+```typescript
+{
+  data: [
+    {
+      plan_id: "uuid",
+      plan_name: "Tooth 14 Restoration",
+      plan_status: "active",
+      plan_notes: "",
+      plan_created_at: "2026-03-15T10:00:00Z",
+      doctor: { user_id: "uuid", user_full_name: "Dr. Mehmet Kaya" } | null,
+      items: [
+        {
+          item_id: "uuid",
+          item_name: "Root Canal",
+          item_status: "completed",
+          item_tooth_number: "14",
+          item_completed_at: "2026-03-15T11:00:00Z",
+          item_sort_order: 0,
+          treatment: { treatment_id: "uuid", treatment_name: "Root Canal", treatment_price: 3000 } | null,
+          appointment: { appt_id: "uuid", appt_start_time: "2026-03-15T10:00:00Z" } | null,
+        },
+        // ...
+      ],
+      _counts: { total: 3, completed: 1, scheduled: 1, planned: 1, cancelled: 0 }
+    }
+  ],
+  meta: { total: 1, page: 1, limit: 20 }
+}
+```
+
+The `_counts` field provides item status breakdown without requiring the frontend to count items client-side.
+
+---
+
+## 8. Permissions
+
+### New Permission Strings
+
+```
+treatments:read           - View treatment catalog
+treatments:manage         - Create, update, soft-delete treatments
+treatment_plans:manage    - Create, update, delete treatment plans and items
+```
+
+Treatment plan reading is covered by `patients:read` -- if you can view a patient, you can view their treatment plans. This is the same pattern used for patient photos (doc 21).
+
+### Role Mapping
+
+| Role | `treatments:read` | `treatments:manage` | `patients:read` | `treatment_plans:manage` |
+|------|-------------------|---------------------|-----------------|--------------------------|
+| owner | Yes | Yes | Yes | Yes |
+| admin | Yes | Yes | Yes | Yes |
+| doctor | Yes | No | Yes | Yes |
+| receptionist | Yes | No | Yes | No |
+
+**Rationale:**
+
+- **owner/admin** -- Full access to everything. They manage the clinic's service catalog and can create/edit treatment plans.
+- **doctor** -- Can read the treatment catalog but cannot modify it (catalog management is an admin task). Can create and manage treatment plans (this is core clinical work -- doctors prescribe treatment plans).
+- **receptionist** -- Can read the catalog (needed to know treatment durations when booking appointments) and view treatment plans (needed to understand what appointments to book). Cannot create or modify plans -- that is the doctor's responsibility.
+
+---
+
+## 9. Recall Automation (P1 -- Design Reference)
+
+This section describes how `treatment_recall_days` will be used for automated patient recall. This is P1 (not part of initial implementation) but the data model is designed to support it.
+
+### How It Works
+
+When a treatment plan item is marked `completed`, the service checks if the linked treatment has `treatment_recall_days` set. If it does, a BullMQ delayed job is scheduled:
+
+```
+Item completed (status -> completed, completed_at = now())
+  |
+  v
+Load treatment: treatment.recall_days = 180
+  |
+  v
+Schedule BullMQ delayed job:
+  Queue: treatment:recall
+  Delay: 180 days (15,552,000,000 ms)
+  JobId: "recall:{itemId}" (prevents duplicates)
+  Data: {
+    tenantId, clinicId, patientId, planId, itemId,
+    treatmentId, treatmentName, recallDays: 180
+  }
+  |
+  v
+... 180 days later ...
+  |
+  v
+Job fires:
+  1. Check patient still exists and has not had this treatment repeated
+  2. Create a WhatsApp reminder message or outbound call
+  3. Optionally create a new outbound campaign entry for batch recall
+```
+
+### Integration with Outbound Campaigns
+
+Recall jobs can feed into the existing outbound campaigns system (doc 09). Instead of sending individual reminders, the system can batch recall-eligible patients into an outbound campaign:
+
+```
+Daily BullMQ cron job: treatment:recall-batch (09:00 Istanbul time)
+  |
+  v
+Query: treatment_plan_items WHERE
+  item_status = 'completed'
+  AND item_completed_at + treatment.recall_days <= now()
+  AND no existing recall campaign entry for this item
+  |
+  v
+Group by tenant + clinic + treatment
+  |
+  v
+For each group: create outbound campaign entries
+  or send individual WhatsApp reminders (based on tenant config)
+```
+
+### Example Recall Scenarios
+
+| Treatment | Recall Days | Trigger |
+|-----------|-------------|---------|
+| Dental Cleaning | 180 | "Merhaba, son diş temizliğinizin üzerinden 6 ay geçti. Yeni bir randevu almak ister misiniz?" |
+| Annual Checkup | 365 | "Yıllık kontrol zamanınız geldi. Size uygun bir randevu ayarlayalım mı?" |
+| Botox | 120 | "Botox uygulamanızın tazeleme zamanı yaklaşıyor. Randevu için bize ulaşabilirsiniz." |
+| Teeth Whitening | 365 | "Diş beyazlatma işleminizin üzerinden 1 yıl geçti. Yenileme seansı düşünür müsünüz?" |
+
+---
+
+## 10. NestJS Module Structure
+
+Treatments and treatment plans live in a single `TreatmentsModule`. They are tightly coupled -- plan items reference treatments, and the plan workflow depends on treatment properties (duration, recall days). Splitting them into two modules would create circular dependencies without meaningful separation of concerns.
+
+```
+src/treatments/
+  treatments.module.ts              # Imports PrismaModule, BullModule (for recall queue)
+  treatments.controller.ts          # /treatments/* endpoints (catalog CRUD)
+  treatments.service.ts             # Treatment catalog CRUD, category listing, soft-delete
+  treatment-plans.controller.ts     # /treatment-plans/* and /patients/:id/treatment-plans
+  treatment-plans.service.ts        # Plan + item CRUD, status management, auto-completion, recall scheduling
+  dto/
+    create-treatment.dto.ts         # name, category, duration, price, clinic_id, recall_days
+    update-treatment.dto.ts         # PartialType of create
+    create-treatment-plan.dto.ts    # name, patient_id, doctor_id, clinic_id, notes, items[]
+    update-treatment-plan.dto.ts    # name, notes, status, doctor_id
+    create-plan-item.dto.ts         # treatment_id, name, tooth_number, notes, sort_order
+    update-plan-item.dto.ts         # status, notes, appointment_id, tooth_number, sort_order
+```
+
+### Module Registration
+
+```typescript
+// src/treatments/treatments.module.ts
+
+@Module({
+  imports: [
+    PrismaModule,
+    BullModule.registerQueue({ name: 'treatment:recall' }),
+  ],
+  controllers: [
+    TreatmentsController,
+    TreatmentPlansController,
+  ],
+  providers: [
+    TreatmentsService,
+    TreatmentPlansService,
+  ],
+  exports: [
+    TreatmentsService,
+    TreatmentPlansService,  // Exported for AI tools module to query plans
+  ],
+})
+export class TreatmentsModule {}
+```
+
+### Service Dependencies
+
+```
+TreatmentsService
+  <- PrismaService (CRUD)
+
+TreatmentPlansService
+  <- PrismaService (CRUD)
+  <- TreatmentsService (validate treatment_id, get recall_days)
+  <- BullMQ Queue 'treatment:recall' (schedule recall jobs)
+```
+
+The `TreatmentPlansService` is exported so the `ToolsModule` can query treatment plans when building patient context for `check_patient_history` and when linking appointments in `reserve_slot`.