> ## Documentation Index > Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt > Use this file to discover all available pages before exploring further. # Encounter-Level Cost Accounting — Integration > Version: 1.0 Last Updated: 2026-05-11 Status: ✅ Complete Spec: PM-35 Encounter-Level Cost Accounting Constitution Reference: Section 1.2 (Core Independence), S… **Version:** 1.0 **Last Updated:** 2026-05-11 **Status:** ✅ Complete **Spec:** [PM-35 Encounter-Level Cost Accounting](../../../specs/pm/specs/PM-35-encounter-level-cost-accounting.md) **Constitution Reference:** Section 1.2 (Core Independence), Section 1.3 (Integration Patterns) *** ## Overview PM-35 adds encounter-level cost accounting to the Practice Management core: cost category configuration, rate management, automatic cost calculation on encounter completion, and margin reporting. It integrates with PM-07 (charge snapshot for margin), PM-25 (VBP cost benchmarking), and FA-35 (cost allocation) via an event contract. *** ## Integration Points (from spec) | Dependency | Pattern | Purpose | Status | | ---------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **PM-07** | Data (same core) | `pm_charges.charge_amount` snapshot for margin calculation; `pm_encounters` for encounter duration and service\_date | ✅ Implemented | | **PM-25** | Data (same core) | PM-25 reads `pm_encounter_costs` for cost benchmarking and PMPM/TCOC calculations | ✅ Implemented | | **FA-35** | Event (`encounter_cost_calculated`) | FA consumes event for program/department cost allocation (downstream consumer) | 📝 Schema documented in `EVENT_CONTRACTS.md` (≈L6126); awaiting FA-35 consumer confirmation (C-9) | | **PF-30** | Platform Layer | Permission seeding — `pm.cost_accounting.view`, `pm.cost_accounting.manage` | ✅ Complete — `view`: org\_admin, platform\_admin, staff, finance\_admin, finance\_staff. `manage`: org\_admin, platform\_admin, finance\_admin. (Spec's "Billing Manager / Financial Analyst" mapped to `finance_staff` / `finance_admin` since no such system roles exist; seeded 2026-05-11.) | | **HR** | None (future) | Provider hourly rates currently entered manually; HR integration deferred to future spec | ⏸ Deferred | *** ## Data Source Tables (PM-35) | Table | Key Columns | Used By | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | | `pm_cost_categories` | organization\_id, name, category\_type, is\_active | Rate lookup; UI configuration | | `pm_cost_rates` | organization\_id, cost\_category\_id, site\_id, provider\_id, rate\_amount, rate\_unit, effective\_from, effective\_to | Edge function rate lookup; UI rate management | | `pm_encounter_costs` | organization\_id, encounter\_id, patient\_id, provider\_id, site\_id, service\_date, total\_cost, cost\_breakdown, charge\_amount, margin, status | PM-25 VBP queries; cost reports; FA event payload source | *** ## Event Contract: `encounter_cost_calculated` **Publisher:** PM (edge function `pm-calculate-encounter-cost`, triggered on `encounter_completed`) **Subscriber:** FA-35 (cost allocation / program cost reporting) **Status:** 📝 Payload schema documented in [EVENT\_CONTRACTS.md](./EVENT_CONTRACTS.md) (`encounter_cost_calculated` entry). Outstanding: FA-35 consumer confirmation of `cost_breakdown` field shape (see `PENDING_CONTRACTS.md`). **Draft payload:** ```jsonc theme={null} { "event": "encounter_cost_calculated", "version": "1.0", "payload": { "organization_id": "uuid", "encounter_id": "uuid", // → pm_encounters.id "cost_record_id": "uuid", // → pm_encounter_costs.id "total_cost": "numeric", // e.g. 125.50 "cost_breakdown": { // JSONB with per-category detail "provider_time": { "rate_unit": "per_hour", "rate_amount": 75.00, "quantity": 1.5, "line_cost": 112.50 }, "facility_overhead": { "rate_unit": "flat", "rate_amount": 13.00, "quantity": 1, "line_cost": 13.00 } }, "service_date": "date", // ISO date "site_id": "uuid", // optional "provider_id": "uuid" // optional (no FK, opaque UUID per C-6) } } ``` > **Schema pending:** Finalize in `EVENT_CONTRACTS.md` entry during Phase 2 task generation. FA-35 team must confirm consumption fields before publishing. *** ## Trigger Mechanism Auto-cost-calculation is driven by an **edge function** (`supabase/functions/pm-calculate-encounter-cost/index.ts`) triggered by the `encounter_completed` event: 1. Validates `auto_calculate_encounter_cost = true` in `pm_module_settings` 2. Looks up effective cost rates for `service_date`, `site_id`, and `provider_id` 3. Calculates `cost_breakdown` and `total_cost` per rate\_unit rules (spec § Rate Calculation Rules C-8) 4. Snapshots `charge_amount` from `pm_charges` for the encounter (C-2) 5. Inserts `pm_encounter_costs` with `status = 'calculated'` 6. Publishes `encounter_cost_calculated` event for FA > **Dependency (Plan A-3):** Confirm `encounter_completed` event is already published by PM-03/PM-07 before Phase 2 implementation begins. *** ## Platform Layer Usage | Layer | Usage | | ------------------------ | --------------------------------------------------------------------------------------------- | | `@/platform/scheduling` | Encounter context (encounter duration, provider, site) via `useEncounterContext(encounterId)` | | `@/platform/types` | `EncounterContext`, `ChargeContext` shared types | | `@/platform/permissions` | `useHasPermission('pm.cost_accounting.view')` and `pm.cost_accounting.manage` | *** ## Open Items | Item | Details | Blocked On | | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | | FA-35 consumer confirmation | FA-35 to confirm `cost_breakdown` JSONB shape required for cost-allocation entries | FA-35 spec update (C-9) | | ~~`service_line` column strategy~~ | ✅ Resolved (C-11) — denormalized `service_line TEXT` on `pm_encounter_costs`, mapped from `pm_encounters.encounter_type` at calculation time | — | | ~~`per_unit` quantity source~~ | ✅ Resolved (C-12) — auto-calc defaults quantity = 1; `cost_breakdown.quantity_source = "auto_default"` | — | | `encounter_completed` event publisher | Confirm PM-03/PM-07 publishes this event (Plan A-3) | PM-03 / PM-07 spec review | *** ## References * **PM-35 Spec:** `specs/pm/specs/PM-35-encounter-level-cost-accounting.md` * **PM-35 Plan:** `specs/pm/plans/PM-35-encounter-level-cost-accounting-PLAN.md` * **PM-25 VBP Integration:** `docs/architecture/integrations/PM-25-VBP-APM-INTEGRATION.md` * **EVENT\_CONTRACTS.md:** `docs/architecture/integrations/EVENT_CONTRACTS.md` (encounter\_cost\_calculated — pending) * **PENDING\_CONTRACTS.md:** `docs/architecture/integrations/PENDING_CONTRACTS.md`