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:

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:

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:

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