Phased Treatment Planning & Procedures

The Treatment Planning & Procedures bounded context structures complex dental therapies into sequential, clinically sound treatment phases. It guarantees that disease control precedes definitive restorative or surgical interventions and enforces chairside tablet informed consent before any plan is approved.

The 5 Clinical Treatment Phases

Treatment plans are divided into five ordered phases:

flowchart LR
    P1["1. URGENT<br/>(Pain and Trauma)"] --> P2["2. DISEASE CONTROL<br/>(Caries and Perio)"]
    P2 --> P3["3. RESTORATIVE<br/>(Crowns and Fillings)"]
    P2 --> P4["4. SURGICAL<br/>(Implants and Surgery)"]
    P3 --> P5["5. MAINTENANCE<br/>(Recall and Hygiene)"]
    P4 --> P5

use Obelaw\Ium\Dental\Enums\TreatmentPhase;

enum TreatmentPhase: string
{
    case URGENT = 'urgent';                     // Phase 1: Relief of acute pain, swelling, trauma
    case DISEASE_CONTROL = 'disease_control';   // Phase 2: Caries excavation, endodontics, perio debridement
    case RESTORATIVE = 'restorative';           // Phase 3: Permanent restorations, crowns, bridges
    case SURGICAL = 'surgical';                 // Phase 4: Implant placement, ridge augmentation, extractions
    case MAINTENANCE = 'maintenance';           // Phase 5: Periodontal recall, recare, prophylaxis
}

Phase Dependency Invariants

To avoid placing permanent restorations in an infected or unstable oral environment:

• RESTORATIVE and SURGICAL phases depend on the completion of the DISEASE_CONTROL phase.
• MAINTENANCE depends on the completion of active restorative and surgical therapy.
• In-progress phase transitions evaluate preceding phase status (TreatmentPhaseStatus::COMPLETED).

Treatment Plan Lifecycle

use Obelaw\Ium\Dental\Enums\TreatmentPlanStatus;

enum TreatmentPlanStatus: string
{
    case DRAFT = 'draft';             // Clinician assembling procedures and fee estimates
    case PROPOSED = 'proposed';       // Presented to the patient with insurance estimates
    case APPROVED = 'approved';       // Patient signed chairside tablet informed consent
    case IN_PROGRESS = 'in_progress'; // Active clinical appointments underway
    case COMPLETED = 'completed';     // All phases and planned procedures finished
    case DECLINED = 'declined';       // Patient refused proposed clinical plan
}

Mandatory Informed Consent Signature Invariant

A treatment plan cannot be approved without capturing a verified chairside digital signature. Calling approve() validates the signature blob:

use Obelaw\Ium\Dental\Data\SignConsentDto;
use Obelaw\Ium\Dental\ValueObjects\InformedConsentSignature;
use Obelaw\Ium\Dental\Exceptions\TreatmentPlanApprovalException;

// If signature blob is empty, throws TreatmentPlanApprovalException

When approved, the service atomically:

1. Validates the signature payload.
2. Records an immutable ConsentRecord with ConsentType::TREATMENT.
3. Sets plan->status to TreatmentPlanStatus::APPROVED.
4. Activates Phase 1 (status = TreatmentPhaseStatus::APPROVED).
5. Dispatches TreatmentPlanApproved.

Planned Procedures & ADA/CDT Codes

Procedures link tooth numbers, ADA/CDT dental procedure codes, and estimated fees:

use Obelaw\Ium\Dental\ValueObjects\AdacdtCode;
use Obelaw\Ium\Dental\Enums\ProcedureStatus;

// ADA/CDT codes follow the DXXXX format
$code = AdacdtCode::from('D2740'); // Porcelain/Ceramic Crown

enum ProcedureStatus: string
{
    case SCHEDULED = 'scheduled';
    case IN_PROGRESS = 'in_progress';
    case COMPLETED = 'completed';
    case CANCELLED = 'cancelled';
}

Fluent Service Operations

1. Creating a Treatment Plan

When a plan is created, all five sequential phases are initialized automatically:

use Obelaw\Ium\Dental\Data\CreateTreatmentPlanDto;

$plan = ium()->dental()->treatmentPlans()->create(CreateTreatmentPlanDto::from([
    'patient_id' => $patient->id,
    'title' => 'Comprehensive Maxillary Rehabilitation',
    'notes' => 'Patient presents with deep recurrent caries on tooth 14 and fractured tooth 19.',
    'actor_id' => 'DR-MARTINEZ',
]));

2. Adding Procedures to a Phase

use Obelaw\Ium\Dental\Data\AddPlanProcedureDto;
use Obelaw\Ium\Dental\ValueObjects\ToothNumber;
use Obelaw\Ium\Dental\ValueObjects\AdacdtCode;
use Obelaw\Ium\Dental\Enums\TreatmentPhase;

// Locate the Restorative phase
$restorativePhase = $plan->phases()
    ->where('phase_type', TreatmentPhase::RESTORATIVE)
    ->first();

$procedure = ium()->dental()->treatmentPlans()->addProcedure(AddPlanProcedureDto::from([
    'plan_id' => $plan->id,
    'phase_id' => $restorativePhase->id,
    'tooth_number' => ToothNumber::fromUniversal(14),
    'cdt_code' => AdacdtCode::from('D2740'), // Crown - Porcelain/Ceramic Substrate
    'estimated_fee_minor' => 115000,         // $1,150.00
    'notes' => 'Full contour zirconia crown on tooth 14.',
    'actor_id' => 'DR-MARTINEZ',
]));

3. Capturing Chairside Consent & Approving the Plan

use Obelaw\Ium\Dental\Data\SignConsentDto;
use Obelaw\Ium\Dental\ValueObjects\InformedConsentSignature;

$approvedPlan = ium()->dental()->treatmentPlans()->approve(
    planId: $plan->id,
    consent: SignConsentDto::from([
        'signature' => new InformedConsentSignature(
            signatureBlob: 'data:image/svg+xml;base64,PHN2ZyB4bWxucz0...',
            ipAddress: '192.168.1.150',
            device: 'Apple iPad Pro 11 (Operatory 1 Chairside)',
            signedAt: new DateTimeImmutable(),
        ),
        'actorId' => 'DR-MARTINEZ',
    ])
);

4. Executing & Completing Procedures

When the clinician finishes the chairside treatment, the procedure is completed, dispatching ProcedureCompleted to trigger ledger invoicing:

$completedProcedure = ium()->dental()->treatmentPlans()->completeProcedure(
    procedureId: $procedure->id
);

echo $completedProcedure->status->value; // 'completed'

Alternatively, invoke ProcedureService directly:

ium()->dental()->procedures()->complete($procedure->id);

Emitted Domain Events