Notes List

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

This feature provides a centralized Notes List experience where users can filter, review, sort, and open session notes (RBT/BCBA) from one table, with built-in pagination and status indicators. Operationally, it also includes bulk export of selected notes (permission-based) and a payroll summary panel tied to the selected date range, so teams can validate documented services and compensation context in the same workflow.

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

• Users with view_notes: can access the Notes section from main navigation and patient actions (note list entries).
• Users with manage_notes (or SUPERADMIN role): can select rows via checkboxes and use bulk-selection controls.
• Users with export_notes: can export selected notes as a single PDF.
• Users with create_note_bcba: can choose note type (rbt or bcba) in filters.
• Users without create_note_bcba: note type is forced to rbt and the note type selector is disabled.
• Users with view_employees: can use Provider filter input.
• Any authenticated user in this route: payroll panel loads using authenticated user id as provider context in payroll request.

Required permissions used by this feature path:

• view_notes: entry/access visibility from UI navigation and patient actions.
• manage_notes: enables row selection and select all.
• export_notes: enables bulk export action.
• create_note_bcba: enables BCBA note type filtering.
• view_employees: enables Provider filter control.

3. Business Rules & Enforcements

• Rule 1: Default date range is auto-enforced when missing (date_start/date_end), using previous Sunday to last Saturday window.
• Rule 2: Filter state is synchronized with query params; incoming query params are normalized (patient_id, insurance_id, location_id parsed to number; empty/all/null cleaned).
• Rule 3: Filtering always triggers reload; duplicate identical filter payloads are skipped to avoid redundant requests.
• Rule 4: Sorting state is persisted in filter (sort, direction) and reused if new filter submissions do not override it.
• Rule 5: Date changes in search component are debounced (300ms) before search emit.
• Rule 6: Payroll section is only ready when both dates exist; otherwise payroll list is hidden/empty and guidance message is shown.
• Rule 7: If payroll date range is invalid (start > end), error modal is shown and date values are cleared in child filter component.
• Rule 8: Bulk note selection is only available with manage_notes; selection is cleared on filter changes.
• Rule 9: Bulk export requires both export_notes and at least one selected note; otherwise user gets info/error feedback.
• Rule 10: Bulk export sends payload as { id, type }[] and downloads a generated PDF blob.
• Rule 11: Table supports page-based navigation and dynamic visible-page window (up to 3-page sliding window with ellipsis).
• Rule 12: Notes table shows No data available when no records returned; payroll table has its own no-data handling.

4. UI Placement

• Main sidebar: Notes menu item (permission-gated by view_notes).
• Patient actions path:

1. Medical > Patients list > Patient actions
2. RBT Note list or Analist Note list
3. Navigates into Notes List with prefilled query params (patient_id, note_type).

• Primary route: /notes-list.

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

Scenario A: Review notes for a date range

1. Open Notes from sidebar (or enter from patient actions).
2. Set From and To dates (or keep auto-default range).
3. Optionally filter by Note type, Provider, and Client.
4. Review records in table; click DOS to open note detail.
5. Use sort headers and pagination to navigate results.

Scenario B: Export selected notes in bulk

1. Ensure user has manage_notes and export_notes.
2. Select individual notes or use header checkbox to select current visible rows.
3. Click Export selected.
4. System calls bulk export endpoint and downloads a PDF file.

Scenario C: Check payroll summary for selected period

1. Select valid From and To dates.
2. Observe Payroll section under notes table.
3. Review total hours and total pay by provider row.
4. If no payroll data, table shows No data available.

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

• Q: What happens if no date range is provided in URL?

• A: The component auto-sets default weekly range and updates URL query params.

• Q: What if user does not have manage_notes?

• A: Selection checkboxes and selection controls are not available; bulk selection flow is blocked.

• Q: What if user has manage_notes but not export_notes?

• A: User may select notes, but export action is not shown/enabled for them.

• Q: What happens when no note is selected and export is attempted?

• A: System prompts user to select at least one note before export.

• Q: What if payroll start date is later than end date?

• A: Error dialog appears; payroll is reset and date fields are cleared in search filter component.

• Q: What if there are no notes returned?

• A: Notes table displays No data available.

• Q: What if user lacks BCBA creation permission?

• A: Note type filter is forced to rbt and selector is disabled.