agdar/PHASE2_FORMS_COMPLETE_SPEC.md

# Phase 2: Forms Implementation - Complete Specifications

## ✅ Completed Forms (4 of 9 apps - 44%)

### 1. Core App Forms ✅ (`core/forms.py`)
- **PatientForm** - Bilingual registration with validation
- **ConsentForm** - E-signature canvas integration
- **PatientSearchForm** - Advanced search
- **SubFileForm** - Clinic sub-file creation

### 2. Appointments App Forms ✅ (`appointments/forms.py`)
- **AppointmentBookingForm** - Full booking with provider validation
- **AppointmentConfirmForm** - Confirmation method selection
- **AppointmentRescheduleForm** - Rescheduling with reason
- **AppointmentCancelForm** - Cancellation tracking
- **AppointmentArrivalForm** - Patient arrival
- **AppointmentSearchForm** - Tenant-filtered search
- **ProviderScheduleForm** - Schedule management

### 3. Finance App Forms ✅ (`finance/forms.py`)
- **InvoiceForm** - Invoice creation
- **InvoiceLineItemForm** + **InvoiceLineItemFormSet** - Inline items
- **PaymentForm** - Payment recording with validation
- **ServiceForm** - Service management
- **PackageForm** - Package creation
- **PackagePurchaseForm** - Package purchase
- **PayerForm** - Insurance payer management
- **InvoiceSearchForm** - Advanced invoice search

### 4. Nursing App Forms ✅ (`nursing/forms.py`)
- **NursingEncounterForm** - MD-N-F-1 with auto-BMI calculation
- **GrowthChartForm** - Growth tracking with percentiles
- **NursingEncounterSearchForm** - Encounter search

## 📋 Remaining Forms (5 apps - 56%)

### 5. Medical App Forms - CRITICAL
**File:** `medical/forms.py`

#### Forms Needed:

**A. MedicalConsultationForm (MD-F-1)**
- Mirrors Medical Consultation Form structure
- Sections:
  - Chief Complaint
  - Present History
  - Past History (Medical/Surgical)
  - Vaccination History
  - Family History
  - Social History
  - Pregnancy/Neonatal History
  - Developmental History (Motor/Language/Social/Cognitive milestones)
  - Behavioral Symptoms (checklist)
  - Physical Examination (structured)
  - Summary & Recommendations
  - Lab/Radiology orders (links to integrations)

**B. MedicationPlanFormSet**
- Inline formset for medications
- Fields: drug_name, dose, frequency, compliance, gains, side_effects, target_behavior, improved

**C. MedicalFollowUpForm (MD-F-2)**
- Links to previous MD-F-1
- Previous complaints status (Resolved/Static/Worse)
- New complaints
- Vital signs link (to Nursing)
- Assessment & Recommendations
- Family satisfaction (0/50/100 radio)
- Medication table snapshot

### 6. ABA App Forms
**File:** `aba/forms.py`

#### Forms Needed:

**A. ABAConsultForm (ABA-F-1)**
- Reason of referral (radio options)
- Parental concern
- School concern
- Respondents & Interviewer
- Diagnosed condition
- Interaction hours
- Physiological factors (checkboxes + text)
- Medical factors (checkboxes + text)
- Recommendations

**B. ABABehaviorFormSet**
- Inline formset for behaviors
- Fields: behavior_description, frequency, duration, intensity, antecedents (likely/least likely), consequences

**C. ABAGoalForm**
- Goal tracking
- Fields: goal_description, target_date, status, progress_notes

### 7. OT App Forms
**File:** `ot/forms.py`

#### Forms Needed:

**A. OTConsultForm (OT-F-1)**
- Reasons for referral (multi-select)
- Top 3 difficulty areas
- Developmental motor milestones
- Self-help skills matrix
- Feeding participation
- Infant/now behavior descriptors
- Recommendations (continue/discharge/referral with rules)

**B. OTSessionForm (OT-F-3)**
- Session date & type (Consult/Individual/Group/ParentTraining)
- Cooperative level (1-4)
- Distraction tolerance (1-4)
- "Today we work on..." checklist
- Observations
- Activities
- Recommendations

**C. OTTargetSkillFormSet**
- Inline formset for target skills
- Fields: skill_name, baseline_score (0-10), current_score (0-10), notes

**D. OTProgressReportForm**
- Overall progress summary
- Sessions attended
- Goals achieved
- Recommendations

### 8. SLP App Forms - MOST COMPLEX
**File:** `slp/forms.py`

#### Forms Needed:

**A. SLPConsultForm (SLP-F-1)**
- Variant selection (ASD/LanguageDelay/Fluency)
- Primary concern
- Suspected areas
- Type of service
- Communication modes (multi-select)
- Screen time
- Variant-specific questionnaires (conditional display)
- Skills to observe matrix
- Oral motor screening
- Recommendations

**B. SLPAssessmentForm (SLP-F-2)**
- Diagnosis statement
- Case history sections:
  - Prenatal/Perinatal/Postnatal
  - Developmental
  - Medical status
- Speech/language detail
- Test scores (GFTA-3, JAT, SSI)
- Oral mechanism
- Rossetti domains (domain → age level mapping)
- Joint attention skills (present/absent)
- Clinical summary
- Recommendations (frequency, duration)
- Referral rules

**C. SLPInterventionForm (SLP-F-3)**
- Session number & date/time
- Previous session link (for preview)
- Provider

**D. SLPTargetFormSet**
- Inline formset for targets (typically 1-2 per session)
- SOAP format:
  - Subjective
  - Objective
  - Assessment
  - Plan
- Prompt strategies (multi-select)

**E. SLPProgressReportForm (SLP-F-4)**
- Sessions scheduled/attended
- Final diagnosis
- Objectives progress (objective → % accuracy mapping)
- Plan details (continue/add/fade/generalization)
- Overall progress
- Participation level
- Attendance rate (auto-calculated)
- Carryover level
- Prognosis
- Recommendations
- Package sessions count
- Reassessment needed (checkbox)

### 9. Referrals App Forms
**File:** `referrals/forms.py`

#### Forms Needed:

**A. ReferralForm**
- Patient
- From clinic & provider
- To clinic/provider (internal) OR external provider name/contact
- Reason for referral
- Urgency (Routine/Urgent/Emergency)
- Clinical summary
- Notes

**B. ReferralSearchForm**
- Search by patient, clinic, status, urgency, date range

## 🎯 Implementation Guidelines

### Form Design Principles:
1. **Mirror Paper Forms** - Layout should match original clinical forms exactly
2. **Crispy Forms** - Use consistent layout with Fieldsets, Rows, Columns
3. **Bilingual Labels** - All labels wrapped in `_()` for translation
4. **Validation** - Custom clean methods for business rules
5. **Auto-calculations** - JavaScript for BMI, totals, percentages
6. **Inline Formsets** - For one-to-many relationships (medications, behaviors, targets)
7. **Conditional Display** - Show/hide fields based on selections
8. **Help Text** - Clear instructions from original forms
9. **Search Forms** - Consistent pattern with tenant filtering

### Technical Patterns:

#### Inline Formset Pattern:
```python
from django.forms import inlineformset_factory

MedicationPlanFormSet = inlineformset_factory(
    MedicalConsultation,
    MedicationPlan,
    fields=['drug_name', 'dose', 'frequency', ...],
    extra=3,
    can_delete=True,
    min_num=1,
    validate_min=True,
)
```

#### Crispy Forms Layout Pattern:
```python
self.helper.layout = Layout(
    Fieldset(
        _('Section Title'),
        Row(
            Column('field1', css_class='form-group col-md-6 mb-0'),
            Column('field2', css_class='form-group col-md-6 mb-0'),
            css_class='form-row'
        ),
    ),
    Submit('submit', _('Save'), css_class='btn btn-primary')
)
```

#### Validation Pattern:
```python
def clean(self):
    cleaned_data = super().clean()
    field1 = cleaned_data.get('field1')
    field2 = cleaned_data.get('field2')
    
    if field1 and field2:
        # Business rule validation
        if some_condition:
            raise forms.ValidationError(_('Error message'))
    
    return cleaned_data
```

## 📈 Progress Tracking

**Completed:** 4 of 9 apps (44%)
**Remaining:** 5 apps (56%)

**Estimated Time:**
- Medical forms: 4-6 hours (complex, multiple sections)
- ABA forms: 2-3 hours (inline formsets)
- OT forms: 3-4 hours (target scoring, inline formsets)
- SLP forms: 6-8 hours (most complex, variant-specific, SOAP format)
- Referrals forms: 1-2 hours (simple)

**Total Remaining:** 16-23 hours

## 🚀 Next Steps

1. Create `medical/forms.py` with all 3 forms
2. Create `aba/forms.py` with 3 forms
3. Create `ot/forms.py` with 4 forms
4. Create `slp/forms.py` with 5 forms
5. Create `referrals/forms.py` with 2 forms
6. Test all forms with validation
7. Update PROJECT_STATUS.md
8. Move to Phase 3 (Views)

## 💡 Key Considerations

- **Clinical Accuracy:** Forms must match paper forms exactly
- **User Experience:** Intuitive flow, clear labels, helpful validation
- **Performance:** Efficient queries for dropdowns, lazy loading where needed
- **Accessibility:** Proper labels, ARIA attributes, keyboard navigation
- **Mobile Responsive:** Bootstrap grid system ensures mobile compatibility
- **Bilingual:** All text wrapped in translation functions
- **Audit Trail:** Forms integrate with simple_history for tracking changes