BIP Profile View and Update

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

This feature provides the parent BIP experience in two connected flows: a full-profile extended read-only view for complete clinical review and a tabbed workflow for structured editing. Clinically, it keeps the treatment narrative, goals, risk/safety, recommendations, school statements, consent, and supporting data in one longitudinal plan while enforcing role-based edit access.

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

• Superadmin/Admin/Owner/Manager (or any role granted manage_bips): Can open BIP, edit BIP fields, save updates, and access edit actions.
• RBT/Analyst (or any role granted view_bips only): Can open and review BIP content in read-only mode; cannot save or edit.
• Users without view_bips: Cannot access BIP view actions from the client action menu.

Required permissions used by the feature:

• view_bips: Allows opening BIP in view mode.
• manage_bips: Allows editing/saving BIP and edit-related actions.

3. Business Rules & Enforcements

• Rule 1: If no client context is resolved, the page shows an empty/no-info state instead of rendering BIP sections.
• Rule 2: If the client has no saved BIP yet, the system builds a default BIP payload so the profile can still be displayed and completed.
• Rule 3: Save/update is blocked when the user does not have manage_bips; a permission denied message is shown.
• Rule 4: Save/update is blocked if in-memory BIP data is missing (bip or old_bip is null) to avoid unsafe writes.
• Rule 5: During save, consent signature image fields are reset before persistence, and then the BIP plus linked plan categories are synchronized.
• Rule 6: Weekly report fetch errors do not block the screen; graph data falls back to empty so the feature remains usable.
• Rule 7: Access path is role-sensitive: users with manage_bips enter tabbed edit flow, while users without that permission are redirected to read-only full BIP view.
• Rule 8: Feature-flagged tabs (insurance-statements-fields) only appear when enabled (for example, Individual Rationale, School Services, Functional Impairment).
• Rule 9: Report Date defines the reference date used for report generation and for selecting weekly-report data displayed in chart-backed sections.
• Rule 10: Month Range defines how many months of weekly-report history are fetched relative to the selected report date.
• Rule 11: If Report Date is missing or invalid, the system defaults to current date; if report retrieval fails, the UI still renders with empty chart datasets.
• Rule 12: View Full BIP from the tabbed workflow opens the extended read-only profile version of the same plan and carries Report Date + Month Range as query parameters to keep report context aligned.
• Rule 13: Update Current Progress provides a bulk update flow by selected categories and date range from the tabbed header actions.
• Rule 14: Export PDF is available from header actions (with export permission) to generate a report-style document using current BIP content and chart/report context.

4. UI Placement

• Medical > client list > client actions > BIP View / Update (for manage_bips) or BIP View (for view_bips).
• Route family:
  • Full profile view: /bip/profile/:patient_id and /bip/show/patient/:id.
  • Tabbed edit flow: /bip/:id and /bip/tabbed/:patient_id.
• Main screens:
  • BIP Profile (comprehensive read/review + PDF/report context).
  • BIP Tabbed (section-by-section editing, autosave, and tab validation indicators).
• Header action in BIP Tabbed: View Full BIP (opens extended read-only profile view).

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

Scenario A: Review a client BIP

1. Go to Medical and open the clients list.
2. Open a client action menu.
3. Click BIP View or BIP View / Update.
4. Review sections such as background, maladaptive goals, replacement goals, interventions, risk, and consent.
5. If needed, use PDF-related actions in the page header to generate/export with chart captures.

Scenario B: Update and save a BIP (users with manage_bips)

1. Open client action menu and click BIP View / Update.
2. System opens the tabbed BIP workflow for structured editing.
3. Update target tabs (Case History, Interventions, Recommendations, Safety, Consent, and others as enabled).
4. Changes are persisted through tab update flow/autosave and synchronized by parent BIP save logic.
5. Return to full profile when you need complete report-style review.

Scenario C: Refresh chart-backed data

1. Open BIP profile for the client.
2. Trigger refresh (where available) after recent data updates.
3. The page re-fetches BIP and weekly report data for chart sections.

Scenario D: Use Report Date and Month Range

1. Open BIP profile header filters.
2. Set Report Date to the clinical cut-off date you want to evaluate.
3. Set Month Range (for example, 3, 6, or 12) to control historical depth.
4. Review updated chart-backed sections and generated report context based on that window.

Scenario E: Open extended read-only version from tabbed workflow

1. Open BIP View / Update and work in tabbed mode.
2. In header actions, click View Full BIP.
3. System navigates to the extended profile version (read-only) of the same BIP.
4. Confirm that Report Date/Month Range context is preserved in the opened full view.

Scenario F: Run Update Current Progress (quick flow)

1. In tabbed BIP header actions, click Update Current Progress.
2. Select date range and categories.
3. Confirm update to apply bulk progress refresh on selected plan groups.

Scenario G: Export PDF (quick flow)

1. In BIP header actions, click Export PDF.
2. Select/export sections as required in the PDF flow.
3. Generate the document using current BIP data and report/chart context.

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

• Q: What if a client has no BIP yet?

• A: The app generates a default BIP structure so staff can view and start completing it without a hard failure.

• Q: What if a user can open the BIP but cannot edit it?

• A: This is expected for view_bips users. They stay in read-only flow; save/edit actions require manage_bips.

• Q: What if weekly reports fail to load for graphs?

• A: The page still renders. Graph datasets are treated as empty, and users can continue reviewing or editing text sections.

• Q: What is the practical difference between Report Date and Month Range?

• A: Report Date sets the anchor date for the report, while Month Range controls how far back weekly-report data is pulled from that anchor.

• Q: What is View Full BIP and when should it be used?

• A: It opens the extended, report-style, read-only version of the same plan. Use it when you need comprehensive clinical review and PDF/report context after or during tabbed editing.