[Oluwaferanmi18]

Closes #73
Closes #74

What this is

A clean recovery of the Phase 5 implementation for #73 (item-level partial fulfillment) and #74 (facility location + distance-sorted selection), rebuilt on top of current main (8712c70).

Disclosure: #154 is the original PR for these two issues and remains open and untouched — this work is submitted as a separate PR rather than force-pushing that contributor's branch. #154 is referenced here purely for context: its description, review notes and history are the source material this branch recovers. Nothing here closes, edits or replaces #154.

Why a new branch was needed

By its head 57ce53c, #154's five successive merges with main had resolved conflicts toward main's side and silently deleted the branch's own work, while the tests, migration SQL and validation schemas referencing that work survived:

Dropped	In merge
model FulfillmentItem + FulfillmentRecord.items	e613309
/pharmacy-orders/fulfillments* routes + controllers	57ce53c (the PR head)
distance query in facilities/repositories (near/radiusKm)	bf30314

CI's latest run on #154 (run 544) therefore failed at npm run typecheck — TS2300 duplicate pharmacyOrdersRouter/facilitiesRouter in src/app.ts, prisma.fulfillmentItem missing, near not accepted — with unit tests, integration tests and build all skipped.

This branch redoes the merge once, cleanly, from ac86f2a (the last commit that still contained every piece, including the Prisma 7 fixes) against main, resolving each conflict as the union of both sides rather than either side wholesale.

Two collisions that only running the suite exposed

1. Duplicate migration DDL. The Phase 5 migration and main's later migrations both added PrescriptionItem.prescriptionId and FulfillmentRecord.facilityId with their indexes/FKs, so prisma migrate deploy failed with 42701 in all 33 integration files. The Phase 5 migration now creates only what it owns: the two partially_fulfilled enum values, the facility location columns + index, and the FulfillmentItem table.
2. ADR 0012's one-record-per-order UNIQUE vs. split routing. [Phase 5] Partial fulfillment: item-level dispensing for multi-item prescriptions #73 requires routing an order's remaining items to a second facility as a new record, which that UNIQUE forbids (the split scenario returned 409 where the issue requires a 201). Uniqueness moved down one level to (order FK, facilityId) — the guarantee the ADR was actually buying — and the order relation becomes one-to-many (fulfillments[]). Recorded as a dated amendment in docs/adr/0012, ARCHITECTURE.md §4.7 and ARCHITECTURE_ESSENTIALS.md, plus migration 20261026000000_fulfillment_record_per_order_facility.

Consequence reviewers should check: record.facilityId is now the facility the patient routed to, which for a split order is not the order's own facility_profile_id.

GET /facilities/eligible contract decision

The endpoint doubles as main's public price-comparison query, so it keeps main's contract: unauthenticated, { facilities: [...] } envelope. #74's capabilityType/detail/near/radiusKm/limit params and address/distanceKm fields are added inside it. A query with neither type nor capabilityType is a 400 (fail closed — no unqualified directory), radiusKm without near is 400, and the patient's point is never stored, logged or echoed back. #74's test was updated to assert this shared contract.

Test results (backend/, exact CI steps)

• npm run audit:prod — PASS
• npm run i18n:check — PASS
• npm run typecheck — PASS (the step that fails on feat(pharmacy-orders, facilities): item-level partial fulfillment + distance-sorted facility selection #154)
• npm run test — PASS, 270/270 (31 files)
• npm run test:integration — PASS, 435/435 (33 files, each on a fresh embedded Postgres, so migrate deploy is genuinely exercised)
• npm run build — PASS
• git diff --check origin/main...ci-fix — clean

New coverage (11 tests): split routing across two facilities with status derivation at each step, concurrent double-dispense race (exactly one 200, one 409), one-shot item claims, hard-rule-5 cross-facility 403s, expired-order non-resurrection, lab-order single-item flow, distance ordering against a haversine reference, unlocated-facility placement, query-contract validation, and the perf measurement below.

Issue #74 DoD (perf): 3005 facilities, near + radiusKm=60, 25 runs → p50 6.8 ms, p95 7.9 ms, max 8.5 ms (test ceiling 500 ms).

Docs (per AGENTS.md)

ARCHITECTURE.md §4.5/§4.6/§4.7/§5.3/§5.4/§6.1, ARCHITECTURE_ESSENTIALS.md data map, ROADMAP.md Phase 5 status + two checked items, docs/adr/0012 amendment, docs/api/README.md endpoint tables, and changelog.d/73-74-partial-fulfillment-facility-distance.md (a new file, not an append to ROADMAP.md, per changelog.d/README.md).

[afeezorobsco-cyber]

Sweep: malware scan clean, CI green.

[github-actions]

@Oluwaferanmi18 This PR now has merge conflicts with main, most likely because #251 (feat(platform): feature flags for staged rollouts (DB-backed, per environment and per user cohort)) was just merged, so it can't be merged until it's rebased:

git fetch upstream            # upstream = https://github.com/DocForum/docforum-core.git
git rebase upstream/main
# resolve the conflicts, re-run the tests, then:
git push --force-with-lease

The usual culprits are shared docs like ROADMAP.md and ARCHITECTURE*.md. If the conflict is in the ROADMAP.md changelog, move your entry into a new file under changelog.d/ (see changelog.d/README.md) rather than resolving it in place, so it can't conflict again. CI re-runs when you push, and the needs-rebase label is removed automatically once the conflicts are resolved.

_{Automated message. It won't repeat unless the PR conflicts again after your next push.}

[afeezorobsco-cyber]

@Oluwaferanmi18 After updating this branch with main, CI fails at npm run prisma:generate:

Error code: P1012
error: Type "FulfillmentItem" is neither a built-in type, nor refers to another model, composite type, or enum.

prisma/schema.prisma references FulfillmentItem but no longer defines the model. It was probably dropped while resolving the merge. Please restore the model FulfillmentItem { ... } block (and its migration), run npx prisma validate && npm run typecheck in backend/, and push.

[afeezorobsco-cyber]

@Oluwaferanmi18 Still the same prisma:generate failure as in my earlier comment, and now I have the exact location:

error: Type "FulfillmentItem" is neither a built-in type, nor refers to another model, composite type, or enum.
  -->  prisma/schema.prisma:1001
1001 |   items        FulfillmentItem[]

The relation field on line 1001 survived the merge, but the model FulfillmentItem { ... } block it points to didn't. Please re-add that model (and its migration), run npx prisma validate && npm run typecheck in backend/, and push.

[github-actions]

@Oluwaferanmi18 This PR now has merge conflicts with main, most likely because #162 (feat(api): idempotency and optimistic concurrency (#48, #49)) was just merged, so it can't be merged until it's rebased:

git fetch upstream            # upstream = https://github.com/DocForum/docforum-core.git
git rebase upstream/main
# resolve the conflicts, re-run the tests, then:
git push --force-with-lease

The usual culprits are shared docs like ROADMAP.md and ARCHITECTURE*.md. If the conflict is in the ROADMAP.md changelog, move your entry into a new file under changelog.d/ (see changelog.d/README.md) rather than resolving it in place, so it can't conflict again. CI re-runs when you push, and the needs-rebase label is removed automatically once the conflicts are resolved.

_{Automated message. It won't repeat unless the PR conflicts again after your next push.}