Logs Report Charges Calculation

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

This feature calculates and recalculates note charges inside Logs Report so billing totals stay aligned with current note data and insurance service setup. It reduces manual corrections by applying a consistent formula and service-matching logic.

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

• Users with manage_notes access (for example, Billing/Admin roles): Can review calculated values and trigger Recalculate charges for individual rows.
• Location-scoped users: Can recalculate only notes available in their active location context.

3. Business Rules & Enforcements

• Rule 1: Charges are calculated with this formula:
  • total_units = units derived from total session minutes using 15-minute units and 8-minute rounding.
  • unit_price = matched insurance service unit price.
  • total_charges = total_units × unit_price (rounded to 2 decimals).
• Rule 2: Unit calculation rule is fixed:
  • 1 unit per 15 minutes.
  • Remaining minutes >= 8 round up to the next unit.
• Rule 3: Unit price matching requires a valid combination of insurance, location, CPT code, provider type, and modifiers.
• Rule 4: Provider type is resolved from taxonomy mapping (BCBA, BCaBA, RBT taxonomies supported).
• Rule 5: If insurance is configured to use supervisor as provider and the rendering provider is RBT, supervisor taxonomy is used to resolve pricing.
• Rule 6: Modifiers are matched exactly against configured insurance service modifiers (none handling included when no modifiers are set).
• Rule 7: If no compatible insurance service is found, charges remain unresolved in UI as MISSING SERVICE.
• Rule 8: Recalculation is blocked for billed notes (Cannot recalculate charges for billed notes).
• Rule 9: The Recalculate charges button runs a forced backend recalculation and updates row values (total_units, unit_price, total_charges, charges_calculated_at) plus report totals.
• Rule 10: Normal note saves also auto-sync charges when charge-relevant fields change (time fields, provider/rendering provider/supervisor, modifiers, CPT, insurance, location).

4. UI Placement

1. Reports > Billing Collections > Logs Report (/reports/logs): Main table with charge columns.
2. Per-row Charges column: Displays charge value and the Recalculate charges action button.
3. Per-row Unit Price / Charges tooltips: Shows Calculated at timestamp when available.
4. Logs Report footer: Displays aggregated totals (Total units, Total hours, Total charges) based on current filters.

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

Scenario A: Recalculate charges for one note

1. Open Reports > Billing Collections > Logs Report.
2. Find the target note row and review current Unit Price / Charges values.
3. Click the recalculate icon in the Charges column.
4. Confirm Recalculate in the dialog.
5. Wait for success feedback and verify updated values and timestamp.

Scenario B: Resolve a MISSING SERVICE charge result

1. In Logs Report, identify a row showing MISSING SERVICE.
2. Verify insurance service configuration for that location/CPT/provider type/modifier combination.
3. Verify provider (or supervisor, if applicable) has valid taxonomy.
4. Return to Logs Report and click Recalculate charges.
5. Confirm that unit_price and total_charges now populate.

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

• Q: What happens if the note is already billed?
  A: Recalculation is rejected by the API and the note keeps existing billed values.
• Q: What happens if modifiers are changed but no service matches?
  A: The note returns unresolved pricing (MISSING SERVICE) until a valid insurance service match exists.
• Q: What happens to report totals after recalculation?
  A: Totals are refreshed from the backend totals endpoint using current filters.