Skip to content

Finance Integration Bridge Plan: Operations to Payables

1. Objective

Establish a fully automated, user-verifiable bridge between the Operations Domain (Procurement/Work Orders) and the Finance Domain (Accounts Payable/Bills).

Target State:

  1. Staff creates a Purchase Order (PO) for a Work Order.
  2. Staff fulfills the PO (work complete).
  3. System automatically generates a Draft Bill in Finance.
  4. Staff/Admin verifies the Bill in the Finance Dashboard.

2. Current State Analysis

2.1 Existing E2E Coverage

  • File: apps/platform/e2e/operations-integration.spec.ts
  • Current Flow: Resident Request -> Staff Dispatch -> Work Order Item Created.
  • Gap: The test stops before creating a Purchase Order.

2.2 Bridge Logic Status

  • Verification: scripts/seed-ops-bridge.ts confirms the Service Layer logic works.
  • Mechanism: OperationsService.procurement.updatePurchaseOrder(..., 'fulfilled') triggers PayablesService.createBill.
  • Status: Backend Verified, but Frontend Disconnected.

2.3 UI & Actions Status

  • Procurement UI: /admin/operations/procurement exists.
  • Procurement Actions: apps/platform/src/actions/procurement.ts contains STUBS.
  • Payables UI: /admin/finance/payables exists.
  • Payables Actions: apps/platform/src/actions/payables.ts contains STUBS.

3. Schema Alignment

  • Bill Schema: Confirmed in packages/modules/finance/src/payables/schema.ts.
  • Field purchaseOrderId is present and correctly linked.
  • Status flow: draft -> approved (Ledger Post) -> paid.

4. Implementation Plan

Step 1: Hydrate Server Actions (The "Wiring")

Replace the stubs in apps/platform/src/actions with real Service calls.

  • procurement.ts: Import operationsService from @sd/com-operations.
  • Implement createPurchaseOrderAction.
  • Implement updatePurchaseOrderAction (Critical for "Fulfillment" trigger).
  • payables.ts: Import payablesService from @sd/mod-finance.
  • Implement getPendingBillsAction.
  • Implement approveBillAction.

Step 2: UI Enhancements

  • Procurement Page:
  • Ensure PurchaseOrderForm submits to the real action.
  • Add a "Fulfill" Action/Button in the PO List (or a Detail View) to trigger the transition to fulfilled.
  • Payables Page:
  • Ensure the Bill List correctly fetches draft bills via getPendingBillsAction.

Step 3: E2E Test Expansion

Update apps/platform/e2e/operations-integration.spec.ts:

  1. Create PO: Staff creates a PO for the Work Order Item.
  2. Fulfill PO: Staff marks PO as fulfilled.
  3. Verify Bridge: Staff navigates to Finance > Payables and asserts the Bill exists.

5. Execution Order

  1. Hydrate Actions (Low Risk, High Value).
  2. Update UI (Enable manual verification).
  3. Write E2E (Lock in stability).