PSA/ee/docs/plans/2026-04-12-unapproved-time-blocks-recurring-invoices/SCRATCHPAD.md

Scratchpad — Unapproved Time Blocks Recurring Invoices

• Plan slug: unapproved-time-blocks-recurring-invoices
• Created: 2026-04-12

What This Is

Working notes for making recurring invoice approval blockers explicit in Automatic Invoices and enforcing the same rule server-side during generation.

Decisions

• (2026-04-12) A recurring invoice window is blocked in full when it contains at least one uninvoiced billable time entry for that window whose approval_status !== 'APPROVED'.
• (2026-04-12) Blocked windows belong in a dedicated Needs Approval section above Ready to Invoice.
• (2026-04-12) The blocked row should show X unapproved entries, not blocked hours, because count is more actionable for approvers.
• (2026-04-12) Mixed-charge windows are blocked entirely; no partial invoice should be created for fixed or other non-time charges while related billable time is still unapproved.
• (2026-04-12) The generation path must re-check approval blockers immediately before invoice creation so stale UI state cannot bypass the rule.

Discoveries / Constraints

• (2026-04-12) Reviewed billing-engine selection queries indicate contract-hourly and unresolved/non-contract time selection already filter time_entries.approval_status = 'APPROVED'. Relevant file: packages/billing/src/lib/billing/billingEngine.ts.
• (2026-04-12) rolloverUnapprovedTime(...) explicitly targets DRAFT, SUBMITTED, and CHANGES_REQUESTED entries after recurring invoice generation, which reinforces that unapproved time is conceptually expected to stay out of billed time selection. Relevant files: packages/billing/src/lib/billing/billingEngine.ts, packages/billing/src/actions/invoiceGeneration.ts.
• (2026-04-12) AutomaticInvoices.tsx already understands grouped recurring candidates and generic blocked states (canGenerate / blockedReason), so approval blockers can likely fit the existing grouped row model rather than requiring a brand new page architecture.
• (2026-04-12) packages/billing/src/actions/billingAndTax.ts appears to be the primary recurring due-work shaping path and likely the right place to compute approval-blocker metadata for the UI.
• (2026-04-12) packages/types/src/interfaces/recurringTiming.interfaces.ts already carries grouped due-work row and candidate metadata and likely needs approval-blocker count/reason fields.
• (2026-04-12) During review, no obvious source-linkage population path for invoice_time_entries / invoice_usage_records was found in the inspected invoice creation path. That looks adjacent to, but not required for, this blocker-focused change and should stay out of scope unless implementation depends on it.

Commands / Runbooks

• (2026-04-12) Scaffolded this plan with:
  • python3 /Users/roberisaacs/.codex/skills/alga-plan/scripts/scaffold_plan.py "Unapproved Time Blocks Recurring Invoices" --slug unapproved-time-blocks-recurring-invoices
• (2026-04-12) Validate the plan with:
  • python3 /Users/roberisaacs/.codex/skills/alga-plan/scripts/validate_plan.py ee/docs/plans/2026-04-12-unapproved-time-blocks-recurring-invoices
• (2026-04-12) Design doc written to:
  • docs/plans/2026-04-12-unapproved-time-blocks-recurring-invoices-design.md

Links / References

• Design doc: docs/plans/2026-04-12-unapproved-time-blocks-recurring-invoices-design.md
• Automatic invoices UI: packages/billing/src/components/billing-dashboard/AutomaticInvoices.tsx
• Recurring due-work shaping: packages/billing/src/actions/billingAndTax.ts
• Recurring generation: packages/billing/src/actions/invoiceGeneration.ts
• Recurring billing runs: packages/billing/src/actions/recurringBillingRunActions.ts
• Billing engine selection logic: packages/billing/src/lib/billing/billingEngine.ts
• Due-work interfaces: packages/types/src/interfaces/recurringTiming.interfaces.ts
• Related grouped automatic-invoices plan: ee/docs/plans/2026-03-20-grouped-automatic-invoices-selection/

Open Questions

• What is the exact target screen for Review Approvals, and can we deep-link/filter by client and invoice window in the first pass?

Implementation Log (2026-04-12)

• Added shared recurring approval-blocker detection helper:
  • packages/billing/src/actions/recurringApprovalBlockers.ts
  • Centralizes blocker count logic for contract-hourly windows and unresolved/non-contract time selections.
  • Mirrors contract-hourly billing semantics more closely by including client/work-item scoping, configured service matching, and uniquely assignable unassigned time.
  • Treats approval_status IS NULL as non-approved, excludes invoiced=true, and returns counts by recurring execution identity key.
• Applied blocker metadata during due-work shaping:
  • packages/billing/src/actions/billingAndTax.ts
  • getAvailableRecurringDueWork(...) now computes and applies approval-blocker counts before pagination.
  • Candidates and members now carry blocker metadata and approval-specific blocked reason text.
• Extended recurring due-work interfaces for blocker metadata:
  • packages/types/src/interfaces/recurringTiming.interfaces.ts
  • Added approvalBlockedEntryCount on rows/candidates and hasApprovalBlockers on candidates.
• Added server-side recurring generation guard:
  • packages/billing/src/actions/invoiceGeneration.ts
  • Re-resolves selector-input windows to matching recurring rows, re-checks approval blockers immediately before invoice creation, and throws Blocked until approval: X unapproved entries. when blocked.
  • Fixed pre-check query regression by joining recurring_service_periods -> contract_lines -> contracts and filtering by contracts.owner_client_id.
• Ensured grouped recurring runs continue when one target is blocked:
  • packages/billing/src/actions/recurringBillingRunActions.ts
  • Preserves per-target failure handling while continuing unrelated eligible targets.
  • Adjusted helper invocations to avoid passing explicit undefined bridge args.
• Added Automatic Invoices Needs Approval UX:
  • packages/billing/src/components/billing-dashboard/AutomaticInvoices.tsx
  • New Needs Approval section above Ready to Invoice.
  • Blocked groups moved out of ready table.
  • Needs Approval rows show client, service period, invoice window, X unapproved entries, and Review Approvals link to /msp/time-sheet-approvals with query params.
  • Ready selection/preview/generate semantics remain for clean windows.

Test Coverage Added / Updated

• Integration (DB-backed):
  • server/src/test/integration/billingInvoiceTiming.integration.test.ts
  • Added/updated:
    • T001/T004 approval-blocked contract-hourly window with uninvoiced non-approved time.
    • Added parity coverage for uniquely assignable unassigned time on the final included service-period day and for approval_status = NULL behaving as non-approved.
    • T002 unrelated non-approved time outside window does not block.
    • T003/T008/T017 mixed-charge window blocked in full; direct generation rejects.
    • T009/T011 stale-ready server rejection and approval-cleared transition back to ready.
  • Added helper options in createApprovedTimeEntryForContractLine(...) for nullable approvalStatus, nullable contractLineId, and invoiced.
• UI unit:
  • server/src/test/unit/billing/automaticInvoices.recurringDueWork.ui.test.tsx
  • Added Needs Approval rendering/assertions (section order, row content, review link, non-selectable/non-generatable behavior).
  • Added explicit T007 coverage marker for preserving ready-list grouped behavior.
• Server generation unit:
  • server/src/test/unit/billing/invoiceGeneration.selectorInputGenerate.test.ts
  • Added T008/T009 guard test validating pre-generation blocker rejection.
• Recurring run unit:
  • server/src/test/unit/billing/recurringBillingRunActions.test.ts
  • Added T010 coverage ensuring blocked target failure does not stop unrelated eligible target.
• Docs/copy unit:
  • server/src/test/unit/docs/unapprovedTimeBlocksRecurringInvoices.copy.test.ts
  • Added T012 assertions for runbook + in-product copy.

Validation Commands Run

• pnpm -s vitest run src/test/unit/billing/automaticInvoices.recurringDueWork.ui.test.tsx --coverage.enabled=false
• pnpm -s vitest run src/test/unit/billing/invoiceGeneration.selectorInputGenerate.test.ts --coverage.enabled=false
• pnpm -s vitest run src/test/unit/billing/recurringBillingRunActions.test.ts src/test/unit/docs/unapprovedTimeBlocksRecurringInvoices.copy.test.ts --coverage.enabled=false
• pnpm -s vitest run src/test/integration/billingInvoiceTiming.integration.test.ts -t "T001/T004|parity: recurring due-work blocks uniquely assignable unassigned hourly time|T002: recurring due-work does not block|T003/T008/T017|T009/T011" --coverage.enabled=false

Gotchas / Notes

• Running the full billingInvoiceTiming.integration.test.ts suite currently includes pre-existing failures unrelated to this approval-blocker scope; validation for this change set uses targeted DB-backed cases tied to plan IDs.
• One unit fixture (invoiceGeneration.selectorInputGenerate) required explicit recurring-service-period row fields (owner_client_id, matching invoice window) so the new pre-generation blocker query can resolve rows in the mocked environment.