alldigital/PSA
2
0
Fork 0
Code Issues Pull Requests Actions 15 Packages Projects Releases Wiki Activity
PSA/ee/docs/plans/2026-01-05-contract-purchase-order-support/SCRATCHPAD.md
Hermes 284313f908
Some checks are pending
Bidi Control Character Guard / bidi-control-guard (push) Waiting to run
Details
Circular Dependency Check / Check for new circular dependencies (push) Waiting to run
Details
Citus Migration Smoke / Combined migrations on single-node Citus (push) Waiting to run
Details
E2E Fresh Install Tests / fresh-install-e2e (push) Waiting to run
Details
ext-v2 guardrails / Run ext-v2 guard and ESLint (push) Waiting to run
Details
Integration Tests / Check for relevant changes (push) Waiting to run
Details
Integration Tests / ${{ (github.event_name == 'schedule' || github.event.inputs.suite == 'full') && 'Full integration suite' || 'Tier-1 integration subset' }} (push) Blocked by required conditions
Details
Mobile checks / Mobile lint + typecheck (push) Waiting to run
Details
Mobile checks / Mobile unit tests (push) Waiting to run
Details
Mobile checks / Mobile dependency audit (report) (push) Waiting to run
Details
Mobile checks / Mobile reproducibility checks (push) Waiting to run
Details
Secrets guard (env backups) / Ensure no tracked env backup files (push) Waiting to run
Details
Temporal Readiness / fast-readiness (push) Waiting to run
Details
Temporal Readiness / docker-parity (push) Waiting to run
Details
TypeScript Type Check / Nx affected typecheck (push) Waiting to run
Details
Unit Tests / Skipped-test budget (push) Waiting to run
Details
Unit Tests / Nx affected unit tests (push) Waiting to run
Details
Unit Tests / Server unit coverage (informational) (push) Waiting to run
Details
Validate Tenant Management Schema / Check for relevant changes (push) Waiting to run
Details
Validate Tenant Management Schema / Validate Tenant Management Schema (push) Blocked by required conditions
Details
EE Workflows Build Guard / ee-workflows-build-guard (push) Waiting to run
Details
Initial import of AlgaPSA codebase from PSA server 
Excluded: .git, node_modules, secrets/, compose.env, assemblyscript tgz

Source: /opt/alga-psa on psa.joliet.tech
2026-06-22 16:12:17 -05:00

2.3 KiB
Raw Blame History

Scratchpad — Contract Purchase Order Support

Context / Decisions (2026-01-05)

  • One PO per invoice (single-assignment invoice scope; does not require a single active contract per client).
  • Invoice stores PO number as a snapshot at creation time.
  • PO number appears in:
    • invoice metadata in-app
    • default invoice PDF header (when present)
    • accounting export/sync reference surfaces (QBO + Xero)
  • PO amount (po_amount) is advisory “authorized total spend”.
    • Warn, do not block.
    • Consume only for finalized invoices; unconsume when no longer finalized.
  • Overages: warn and allow override.
  • Batch invoicing: if any invoices in the batch could exceed a PO limit, prompt upfront with allow vs skip; don’t prompt if there’s no possibility of overage.
  • Scope includes everything billed on the invoice (contract + non-contract charges); PO context is invoice-level.

Relevant Code Pointers

  • Contract assignment PO fields: client_contracts.po_required, client_contracts.po_number, client_contracts.po_amount
  • Billing engine attaches client_contract_id to charges: server/src/lib/billing/billingEngine.ts
  • Invoice generation entry point: server/src/lib/actions/invoiceGeneration.ts
  • Invoice persistence: server/src/lib/services/invoiceService.ts
  • Accounting exports:
    • QBO API: server/src/lib/adapters/accounting/quickBooksOnlineAdapter.ts
    • QBO CSV: server/src/lib/adapters/accounting/quickBooksCSVAdapter.ts
    • Xero API: server/src/lib/adapters/accounting/xeroAdapter.ts
    • Xero CSV: server/src/lib/adapters/accounting/xeroCsvAdapter.ts

Known Gaps / Notes

  • Current PO-required validation in generateInvoice references legacy client_plan_bundles; needs alignment to client_contracts.
  • Invoice table does not currently have an invoice-level PO field; requires migration.
  • Xero adapter currently uses reference to carry invoice number; we likely need a combined format (invoice + PO) without breaking matching.
  • Finalization mapping in UI/actions:
    • finalizeInvoiceWithKnex sets invoices.status = 'sent' and sets finalized_at.
    • unfinalizeInvoice clears finalized_at and forces status = 'draft' when status is not already draft.
    • FinalizedTab treats invoices as “finalized” when finalized_at is set OR status !== 'draft'.