Service Recommendations

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

This tab defines and documents the clinical service recommendation package of the BIP so teams can translate assessment and intervention findings into billable service guidance (CPT, units, frequency, location, comments, and review period), improving care continuity and administrative clarity for treatment planning and authorization discussions.

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

• Superadmin/Admin/Owner/Manager (or any role granted manage_bips): Primary users of the tabbed BIP flow; can add, edit, and remove service recommendations, comments, and period.
• RBT/Analyst without manage_bips: Usually redirected to full BIP read-only flow (/bip/show/patient/:id) instead of tabbed editing flow.
• Users without BIP access permissions (view_bips/manage_bips): Cannot access BIP actions from normal client workflows.

Required permissions used by this feature path:

• manage_bips: Required to remain in editable tabbed BIP route.
• view_bips: Used in non-tabbed BIP viewing entry points.

3. Business Rules & Enforcements

• Rule 1: This tab is defined as recommendations with title Service Recommendations in the BIP tab catalog.
• Rule 2: If no BIP exists yet, normal tab interaction is blocked globally and users must first create a BIP.
• Rule 3: Recommendation list items support add/edit/remove, where each item captures CPT, service description, units, per-week breakdown, and location.
• Rule 4: Deleting a recommendation requires explicit user confirmation.
• Rule 5: Tab completion state is true when at least one recommendation exists (bip.recommendations.length > 0).
• Rule 6: Tab warning/error state is true if any recommendation is incomplete (missing CPT or missing description).
• Rule 7: Comment and recommendation period changes emit dedicated events (saveComment, savePeriod) that trigger immediate save in parent container.
• Rule 8: General field edits also emit bipUpdated, which follows parent debounced autosave behavior.

4. UI Placement

• Medical > clients list > client actions > BIP View / Update.
• Inside BIP tabbed view: tab Service Recommendations (tab id recommendations).
• Route family used for tabbed BIP: /bip/tabbed/:patient_id and /:id route variant under BIP module.

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

Scenario A: Add service recommendations

1. Go to Medical and open the clients list.
2. Open client actions and click BIP View / Update.
3. Open tab Service Recommendations.
4. Click Add Recommendation.
5. Complete CPT, Description, Units, Per Week, and Location.
6. Repeat for additional recommended services.

Scenario B: Update comments and recommendation period

1. In Service Recommendations, edit the Comments field.
2. Select period in the Period dropdown (3 or 6 months).
3. System triggers save for each change and shows saving feedback.

Scenario C: Remove an existing recommendation

1. Locate the recommendation row.
2. Click the delete icon.
3. Confirm the warning dialog.
4. Recommendation is removed and BIP is updated.

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

• Q: What if a recommendation row is missing CPT or Description?

• A: The tab enters warning/error state in tab validation until the row is completed.

• Q: What if there are no recommendations yet?

• A: The tab shows an informational empty-state message and allows adding a new recommendation.

• Q: What period options are available?

• A: Current UI supports 3-month and 6-month recommendation periods.