feat(invoicing): TAM-6900: inpatient bed fee

[tcaiger]

Changes

Implements the inpatient bed fee (TAM-6900). Stacked on #10141 (TAM-6901) → #10137 (TAM-6898) — review/merge those first (base is the 6901 branch). No DB migration — BED_FEE is a category string and Location-as-product reuses InvoiceProduct.sourceRecordId.

• New BED_FEE invoice category with each Location as a priceable product (InvoiceProduct.sourceLocationRecord); rate via price lists.
• Facility setting invoicing.bedFee.overnightChargeTime (default 02:00, facility-local).
• Pure computeBedFeeChargeInstants helper (facility-local night counting, unit-tested) + Invoice.recalculateBedFee — reconciles one bed-fee line per location (quantity = nights, attributed to the location at each overnight check; placeholder wards without a product are skipped; recompute sets quantity and won't resurrect a cashier-removed line).
• Night 1 charged on admission (encounter create); the nightly BedFeeCharger accrues later nights for all admitted patients. The recompute is idempotent and computes facility-local timing internally, so the job just runs hourly — no per-facility cron needed.

Verified: @tamanu/database + @tamanu/central-server build pass, lint clean, night-counting unit tests (5/5). Open items (see specs/invoicing/inpatient-encounter-fees-plan.md): the PRD worked-example looks off by a day — confirm the night-counting rule (an N-night stay bills N nights); discharge-day finalisation has a narrow edge for non-hour-aligned check times; integration tests (location attribution, batching) not yet run.

Auto-Deploy

• Deploy

Options

• Artillery load test
• Seed from closest snapshot
• Generate fake data
• More data (20Gi)
• No facility servers (central-only)
• No sync (facility tasks scaled to zero)
• AMD64 architecture (default is arm64)
• Skip mobile build
• Always build mobile
• Stay up for 8 hours
• Stay up for 24 hours
• Stay up (no TTL)
• Build images only (don't deploy)
• Pause this deploy

Tests

• Run E2E tests
• Run DAST scan

Review Hero

• Run Review Hero
• Auto-fix review suggestions Wait for Review Hero to finish, resolve any comments you disagree with or want to fix manually, then check this to auto-fix the rest.
• Auto-fix CI failures Check this to auto-fix lint errors, test failures, and other CI issues.
• Auto-merge upstream Check this to merge the base branch into this PR, with AI conflict resolution if needed.
• Save suppressions Check this to capture 👎 reactions on Review Hero comments as suppression rules in .github/review-hero/suppressions.yml. Also runs automatically at the end of any auto-fix run.

Remember to...

• ...write or update tests
• ...add UI screenshots and testing notes to the Linear issue
• ...add any manual upgrade steps to the Linear issue
• ...update the config reference, settings reference, or any relevant runbook(s)
• ...call out additions or changes to config files for the deployment team to take note of

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 3 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 9188a62. Configure here.}

[review-hero]

🦸 Review Hero Summary
15 agents reviewed this PR | 2 critical | 3 suggestions | 1 nitpick | Filtering: consensus 3 voters, 8 below threshold

Below consensus threshold (8 unique issues not confirmed by majority)

Location	Agent	Severity	Comment
packages/central-server/app/tasks/BedFeeCharger.js:43	Performance	suggestion	The Encounter.count on line 43 and the subsequent Encounter.findAll with offset pagination on line 60 hit the same table twice on every run. The count is only used to compute batchCount and l...
packages/central-server/app/tasks/BedFeeCharger.js:54	Bugs & Correctness	suggestion	Offset pagination over live endDate IS NULL data is not stable. An encounter discharged (endDate set) between batch iterations removes a row from the result set, shifting all subsequent rows by o...
packages/central-server/app/tasks/BedFeeCharger.js:60	Performance	suggestion	Offset-based pagination becomes increasingly expensive as the offset grows: the database must scan and discard all preceding rows to reach each batch. For 10 000 admitted patients with batchSize=10...
packages/database/src/models/Invoice/Invoice.ts:410	BES Requirements	nitpick	encounter.endDate || getCurrentDateTimeString() uses || instead of ??. The project prefers ?? over ||.
packages/database/src/models/Invoice/Invoice.ts:411	Bugs & Correctness	suggestion	(await settings.get('invoicing.bedFee.overnightChargeTime')) as string silences the type but doesn't add a runtime guard. If the setting is missing or the ReadSettings instance hasn't been seeded...
packages/database/src/models/Invoice/Invoice.ts:434	Performance	suggestion	Sequential item.destroy() calls inside a loop: each triggers an individual DELETE (plus audit trigger). Collect the ids of items to remove and issue a single `InvoiceItem.destroy({ where: { id: {...
packages/database/src/models/Invoice/Invoice.ts:480	BES Requirements	suggestion	item.destroy() on a paranoid model soft-deletes the record, placing it in the same state as a cashier-manually-removed line. Later, the existing?.deletedAt guard (line ~472) skips resurrection ...
packages/utils/src/invoice/bedFee.ts:47	Bugs & Correctness	suggestion	overnightChargeTime.split(':').map(Number) with default destructuring ([hour = 0, minute = 0]) silently falls back to midnight (00:00) if the time string is malformed (e.g. '2:00' without zer...

Nitpicks

File	Line	Agent	Comment
packages/utils/src/invoice/bedFee.ts	35	BES Requirements	facilityTimeZone || primaryTimeZone uses || where the project prefers ?? (see important-project-rules.md). facilityTimeZone is typed string | null | undefined, so ?? is correct here — it falls back only on null/undefined, not on an empty string. Same issue on line 55: `primaryTimeZone...

Local fix prompt (copy to your coding agent)

Fix these issues identified on the pull request. One commit per issue fixed.

---

packages/database/src/models/Invoice/Invoice.ts:392: recalculateBedFee performs multiple reads and writes (findAll, destroy, findOne, update/create) without a transaction. Concurrent runs — e.g. the hourly BedFeeCharger and an admission trigger firing simultaneously for the same encounter — can race, producing duplicate invoice items or leaving items in an inconsistent state. Wrap the entire body after the early-return guards in await this.sequelize.transaction(async () => { ... }) per the project's managed-transaction pattern (no need to pass the transaction object thanks to CLS).

---

packages/database/src/models/Invoice/Invoice.ts:468: orderDate: new Date() passes a JavaScript Date object to a column declared as a string (dateType). The project convention is to store datetimes as ISO 9075 strings via getCurrentDateTimeString() (already imported on line 27). Use orderDate: getCurrentDateTimeString() instead.

---

packages/utils/src/invoice/bedFee.ts:35: facilityTimeZone || primaryTimeZone uses || where the project prefers ?? (see important-project-rules.md). facilityTimeZone is typed string | null | undefined, so ?? is correct here — it falls back only on null/undefined, not on an empty string. Same issue on line 55: primaryTimeZone || displayTimeZone should be primaryTimeZone ?? displayTimeZone.

---

packages/database/src/models/Invoice/Invoice.ts:418: N+1 query pattern in the per-instant loop: locationIdAtInstant issues one EncounterHistory.findOne per charge instant (one per night). For a 90-day admission that's 90 separate DB queries just for location lookups, and this runs hourly for every admitted patient in the system. Fix: fetch all EncounterHistory rows for the encounter in a single query (WHERE encounterId = ? AND date <= endDateTime ORDER BY date ASC), then resolve each instant's location in-memory by binary-searching or walking the sorted result set.

---

packages/database/src/models/Invoice/Invoice.ts:441: N+1 query pattern: InvoiceProduct.findOne is called once per distinct location in nightsByLocation. For an encounter that moved through many locations this multiplies round-trips. Fix: replace with a single InvoiceProduct.findAll({ where: { category: BED_FEE, sourceRecordId: { [Op.in]: [...nightsByLocation.keys()] } } }) and build a Map keyed by sourceRecordId before the loop.

---

packages/database/src/models/Invoice/Invoice.ts:448: N+1 query pattern: InvoiceItem.findOne is issued once per location. Combined with the InvoiceProduct.findOne loop above, each location causes 2 sequential round-trips. Fix: batch-load all existing BED_FEE InvoiceItems for the invoice in a single query (the existingItems fetch on line 431 already does this but only for the destroy pass — reuse it, keyed by sourceRecordId, for the upsert pass too).