Clients Out Of Projection Report

1. What does this feature do? (High-Level Overview)

This report lists clients whose weekly objective values are outside the expected projection range for a selected recent window. It gives clinical and operations teams a fast way to identify potential intervention follow-up needs.

2. Who is this for? (Roles & Permissions)

• Users with view_projection_report: Can access and use the report.
• By default role mapping, this includes Manager and BCBA role sets.

Required permission:

• view_projection_report

3. Business Rules & Enforcements

• Rule 1: The report window is limited to 1 to 4 weeks (weeks parameter). Values outside this range are rejected.
• Rule 2: The request must be scoped to the active location context (X-Location-ID); a mismatched location_id is rejected.
• Rule 3: Only in-progress objectives with numeric start_point and target, and without end_date, are evaluated.
• Rule 4: Only maladaptive and replacement categories are evaluated.
• Rule 5: Out-of-projection condition is actual weekly value < expected min or > expected max.
• Rule 6: Weekly formula summary used by the backend:
  • First compute daily expected ranges for Monday-Friday using the projection policy.
  • Maladaptive weekly expected range: sum of daily values.
  • Replacement weekly expected range: average of daily values.
  • Compare stored weekly report value against computed [min, max].
• Rule 7: Returned rows include patient, objective, plan, category, week range, expected range, and actual value.

4. UI Placement

1. Reports > Access > Clinical > Clients Out of Projection.
2. Route: /reports/client-projection.
3. API source: GET /api/patients/out-of-projection.

5. How-To Guide (Step-by-Step)

Scenario A: Review the latest out-of-projection clients

1. Open Reports and navigate to Clients Out of Projection.
2. Keep Last as 1 week to review the most recent complete week.
3. Review each row’s expected range and actual value.
4. Open the client from the patient link for follow-up.

Scenario B: Expand clinical monitoring window

1. Change Last from 1 week to 2, 3, or 4 weeks.
2. Use search by name to focus on a client.
3. Sort rows (for example by patient or actual value) to prioritize review.
4. Use findings in supervision or care planning workflows.

6. What happens if…? (Edge Cases / FAQ)

• Q: What if the selected weeks value is outside 1-4?

• A: The API returns a validation error and does not generate results.

• Q: What if the location in query does not match the current location header?

• A: The API rejects the request to enforce location isolation.

• Q: Why might a client with active treatment not appear?

• A: They are included only when at least one weekly value is outside computed range and objective data is valid for projection calculation.