Contract Management

Overview

Contract Management handles the creation, tracking, and termination of employment contracts. Contracts are created automatically when an applicant reaches the offer stage in the recruitment pipeline.

The module uses Eloquent Observers that react to model events — automatically creating probation records when a contract stage changes and dispatching notifications when probation progresses.

---

Flow

Applicant reaches 'offer' stage
    ↓
StageOrchestrator::createContract(applicant)
    ↓
Contract created (status: draft)
    ├── Employee record created
    ├── Teacher record created (if applicable)
    ├── User account created
    └── Default role assigned
    ↓
HR reviews → Activate Contract → stage_id changes
    ↓
ContractObserver::updated() fires
    ↓
If stage meta has contract_type = 'probation'
    → Probation record auto-created
    ↓
ProbationObserver::created() fires
    → SendPromotedToProbationNotification dispatched
    ↓
Probation stage changes
    ↓
ProbationObserver::updated() fires
    → SendAcquisitionStageChangedNotification dispatched
    ↓
Probation ends → Contract confirmed or terminated

---

Observer Flows

ContractObserver — Auto-Create Probation

The ContractObserver listens for updated events on the Contract model. When the stage_id changes to a stage configured with contract_type: probation, it automatically creates a Probation record.

Explanation:

1. The observer checks if stage_id has actually changed (isDirty). If not, nothing happens.
2. The new stage is loaded and its meta.contract_type is checked — only stages configured as probation trigger creation.
3. A duplicate check prevents creating multiple probation records for the same contract.
4. The probation duration is calculated from meta.duration_days (defaults to 3 months).
5. The entire operation runs inside a database transaction for consistency.

ProbationObserver — Notifications

The ProbationObserver dispatches notification jobs when probation records are created or updated.

Explanation:

1. On create — dispatches SendPromotedToProbationNotification to inform the employee that they've been promoted to probation.
2. On stage change — detects the stage_id change, resolves both the old and new stage names, and dispatches SendAcquisitionStageChangedNotification with the transition details.

---

Contract States

DRAFT → ACTIVE → EXPIRED
  │         │
  │         ├── TERMINATED
  │         └── RENEWED
  │
  └── CANCELLED

---

Database

Key Tables

Table	Description
contracts	Employment contracts — applicant_id, employee_id, type, start_date, end_date, status, stage_id
probations	Probation periods — contract_id, stage_id, employee_id, start_date, end_date, duration_months, status
contract_settings	Contract type configurations — templates, terms
probation_settings	Probation period rules — duration, review intervals

Relationships

applicant → contract (hasOne)
contract → probations (hasMany)
contract → employee (belongsTo)
contract → contract_settings (belongsTo)
probation → stage (belongsTo)

---

Key Files

File	Purpose
app/Observers/ContractManagement/ContractObserver.php	Auto-create Probation when contract stage changes to probation type
app/Observers/ContractManagement/ProbationObserver.php	Dispatch notifications on probation creation and stage changes
app/Services/Platform/Pipeline/StageOrchestrator.php	Auto-create contract from applicant pipeline
app/Models/ContractManagement/Contract/Contract.php	Contract model with stage_id and probation relation
app/Models/ContractManagement/Probation/Probation.php	Probation tracking with stage progression
app/Models/ContractManagement/ContractSetting/ContractSetting.php	Contract type configurations
app/Jobs/Recruitment/SendPromotedToProbationNotification.php	Job: notify employee promoted to probation
app/Jobs/Recruitment/SendAcquisitionStageChangedNotification.php	Job: notify stage change during probation
app/Filament/Resources/Contracts/	Contract CRUD admin panel