BIP Weekly Baseline Auto-Conversion

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

This feature automatically converts eligible BIP maladaptive plans from hourly baseline mode to weekly baseline mode after scheduled weekly report generation. It keeps plan targets aligned with the latest weekly results without requiring a manual baseline reset.

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

• System scheduler: Runs the conversion automatically as part of the scheduled weekly reports pipeline.
• Technical operations / developers: Can trigger the same flow manually through the weekly report command for validation or support tasks.
• Clinical and operations stakeholders: Consume the updated baseline and objective targets in BIP data, but do not execute this process from a dedicated UI screen.

There is no feature-specific frontend permission gate in this flow; execution is controlled by backend job dispatch path.

3. Business Rules & Enforcements

• Rule 1: The conversion runs only from the scheduled weekly report command flow (reports:generate-weekly) after weekly reports are processed.
• Rule 2: Batch/manual fanout dispatch (QueueWeeklyReportBatchJob) does not run this conversion path.
• Rule 3: The patient must be active.
• Rule 4: The BIP must have service_start_date set.
• Rule 5: At least one full Sunday-to-Saturday week must have elapsed since service start.
• Rule 6: Only maladaptive plans with baseline_timeframe = per_hour are considered.
• Rule 7: If any objective in a target plan is mastered, that plan is skipped.
• Rule 8: If no weekly report exists for the plan up to the generated week end, that plan is skipped.
• Rule 9: When updated, the plan baseline is set from the latest eligible weekly report:
  • baseline_level = weekly_reports.value
  • baseline_date = weekly_reports.week_end
  • baseline_timeframe = per_week
  • timeframe = per_week
• Rule 10: STO targets are recalculated as a chained weekly progression from baseline to 0, using rounded values and carrying each previous target as the next start point.
• Rule 11: If an LTO exists, it is reset to start_point = 0 and target = 0.
• Rule 12: The system logs structured completion and skip reasons for traceability.

4. UI Placement

This feature has no dedicated frontend page or button. It is a backend automation tied to weekly report processing.

Operational entry point when needed:

1. Backend console command: php artisan reports:generate-weekly.
2. Optional parameters for testing/support: --date, --patient_id, and --force.

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

Scenario A: Automatic weekly conversion in production

1. The scheduler runs reports:generate-weekly on the configured weekly schedule.
2. A weekly report job is queued per qualifying patient.
3. Each job generates weekly reports for the selected week.
4. The post-processing conversion evaluates BIP eligibility and target plans.
5. Eligible per-hour maladaptive plans are converted to weekly baseline and objective chain values are recalculated.
6. Results and skip reasons are recorded in automaster weekly logs.

Scenario B: Manual validation for a single patient

1. Run php artisan reports:generate-weekly --date=YYYY-MM-DD --patient_id=<id>.
2. Process queued jobs with php artisan queue:work --once (or run the worker normally).
3. Review plan fields and objectives in BIP data:
   • baseline and timeframe should be per_week when eligible.
   • STO start/target values should reflect chained weekly targets.
4. Check storage/logs/automaster/week_<start>__<end>.log for conversion summary and skip reasons.

Scenario C: Understanding non-update outcomes

1. If no conversion occurs, inspect the post-processing summary for reason codes.
2. Common reasons include:
   • missing_service_start_date
   • first_full_week_not_elapsed
   • inactive_client
   • plan_has_mastered_objective
   • plan_missing_weekly_report
3. Correct data conditions and re-run through reports:generate-weekly if needed.

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

• Q: What if the plan baseline date is filled but BIP service start date is empty?

  • A: The conversion is skipped. Eligibility uses service_start_date on the BIP, not plan baseline date.

• Q: What if the patient has per-week maladaptive plans already?

  • A: Those plans are ignored. Only plans with baseline_timeframe = per_hour are targeted.

• Q: What if the command is run for all patients and a specific patient is not picked up?

  • A: The all-patients mode only queues patients with qualifying notes for that week. Use --patient_id to force a single-patient run for validation.