Finance Screens Implementation Plan (SVG → Framework‑M Workspaces)

This document turns the current SVG screen set (screens/business-m/finance/*.svg) into an execution plan to reach real, working Finance workspaces in libs/finance/frontend that:

• keep the Framework‑M look & feel (Tamagui + @framework-m/* components)
• treat SVGs as information architecture + required fields/columns/views/actions (a skeleton), not a CSS target
• improve framework customizability so developers can achieve these layouts via config/overrides

Current State (what exists today)

• Catalog mapping: libs/finance/frontend/src/customization/screenCatalog.ts
  • Every SVG is mapped to a screenId, route, and doctype.
• Blueprints: libs/finance/frontend/src/customization/blueprints.ts
  • Every workspace screen has a FinanceScreenBlueprint (route, doctype, sections, grid columns, summaries, actions).
• Runtime registry + init: libs/finance/frontend/src/customization/{registry,initialize}.ts
  • Blueprints are registered at startup.
• Workspace renderer: libs/finance/frontend/src/pages/FinanceWorkspacePage.tsx
  • Uses useDocTypeMeta(doctype) + renders reusable components:
    • FinanceHeaderContext
    • FinanceSectionedForm
    • FinanceGridPanel
    • FinanceSummaryPanel
    • FinanceActionBar
• Gap: most UI is still “scaffolding”. The workspace renders, but it does not yet match SVG intent:
  • forms aren’t truly grouped/ordered by sections
  • grids aren’t scoped to the current document/context
  • actions are placeholders
  • layout is not a multi-pane workspace (sticky header/action bar, right-side summary, etc.)

Goal

Create a real, configurable workspace framework once (Phase A), then realize each SVG’s structure by configuration + small screen-specific handlers (Phase B/C).

Non-goals:

• pixel-perfect SVG parity
• copying SVG CSS into the app

Phase A (Platform/Foundation) — implement once, unlock all screens

A1. Workspace shell layout (Framework‑M-first, configurable)

• Outcome: A consistent Finance workspace layout:
  • sticky header
  • main column (form + grids)
  • right summary/context column
  • sticky bottom action bar
• Implementation
  • Implement layout using Framework‑M/Tamagui primitives (@framework-m/ui stacks, cards, etc.) and minimal inline layout styling
  • Add layout “slots” (header / content / summary / actions) and make them overrideable per screen if needed

A2. Real sectioned form rendering (developer-extensible)

• Outcome: FinanceFormSectionBlueprint[] actually controls:
  • which fields appear
  • the order they appear
  • per-section collapse
• Implementation
  • Extend the form layer so sections map to actual renderable blocks:
    • FinanceFormSectionBlueprint → FinanceFormSection component
    • each section renders with Framework‑M form components (or AutoForm with schema filtering if that’s the framework-supported path)
  • Add extensibility:
    • section-level overrides (custom section renderer per section.id)
    • per-field overrides (custom widget per doctype + field)

A3. Grid scoping / filters (config-driven)

• Outcome: all grids represent “rows related to this workspace context”, not global lists.
• Implementation
  • Extend FinanceGridBlueprint to allow optional filters that can be derived from:
    • current doc id
    • doctype fields (party/company/date)
  • Keep the grid rendering in Framework‑M table components (Desk/AutoTable or the recommended framework API), but add a finance-level “scoping adapter” layer:
    • blueprint describes intent
    • runtime turns intent into query params/filters supported by the framework components

A4. Action handler framework (extensible, not hardcoded in pages)

• Outcome: blueprint actions can call real effects:
  • submit/cancel transitions
  • recompute client-side summaries
  • call custom endpoints (e-invoice, statutory match, bank matching)
• Implementation
  • Create a handleFinanceAction({ blueprint, actionId, formData, schema, mutations }) module
  • Screen-specific action maps live in one place (per screen id)
  • FinanceActionBar stays purely presentational
  • Add an extension surface:
    • allow modules/adapters to register additional action handlers (per screen/action id)

A5. DocType config glue (config → framework overrides)

• Outcome: blueprint config drives list/form views outside workspaces too.
• Implementation
  • Either:
    • wire registerConfig(...) into Desk overrides (if the public API exists), or
    • implement finance-owned list/form wrappers that read the config registry and render a config-driven list/form.

Phase B (Priority Screens) — make SVGs “real”

Purchase Invoice (purchase-invoice)

• implement scoped InvoiceItem grid (items for current invoice)
• implement adapter status UX using Framework‑M components (chips/badges/banners), driven by blueprint state
• wire actions: verify GST, statutory match, recompute totals

Sales Invoice (sales-invoice)

• add e-invoice banner + fields (ack/qr) if present
• scoped InvoiceItem grid + export/print actions
• wire “generate e-invoice” action to backend endpoint

Payment Entry (payment-entry)

• replace grid resource with open-items projection (invoices/payables)
• implement settlement allocation UI and TDS validation actions

Phase C (Secondary/Tertiary Screens)

• Advanced Journal, GL View: report-grade filters + sorting + export/compare
• Bank Reconciliation: multi-panel matching + queue + exceptions
• Claims, Fixed Assets, EMD, Imprest: scoped child grids + workflow actions
• Stock Reconciliation: WMS integration panel + valuation handoff actions
• Digital Service Book: add sidebar entry + registry-style filtering
• Dashboard: replace hard-coded KPIs with backend-fed data + drilldowns

Deliverables & Quality Gates

• Contract tests: libs/finance/tests/integration/test_finance_workspace_contracts.py must stay green.
• No regressions: generic metadata list/form routes still work.
• Extensibility: new screens should be addable by updating:
  • screenCatalog.ts
  • blueprints.ts
  • optional handlers/overrides