# Finance workflow operations UI — 2026-09-08

Status: implemented; local engineering checks passed, PR/CI and merge SHA are the
authoritative integration receipt. Not deployed or business-execution accepted.
Base: `6de61408ad05f620606bc7385e3d1e2220f31f99`.

This document owns the interactive workflow UI contract. It supersedes the
handmade SVG / serpentine graph presentation, not the v7 execution or business
acceptance contracts referenced by README. No provider migration or deployment
is part of this change.

## Product and evidence contract

- React Flow canvas, ELK layered left-to-right routing, HeroUI controls and Dark
  theme. Business phases come from the catalog; grouping adds no dependency.
- Stage overview opens a focused stage. Search, attention and related-path modes,
  zoom, fit and reset are presentation-only. Status refresh must not relayout or
  move the viewport. Unknown tasks remain visible and are not successes.
- Default latest-observation view is explicitly NOT one coherent workflow run.
  Selected external-record mode shows that record on its own task; other tasks
  have no bound execution. A CRM table record is not whole-bundle success; shared
  extract/loader job success is diagnostic only.
- No billing-period or cross-provider batch is inferred from timestamps or IDs.
  The API currently has neither binding. Month filtering is labelled execution
  month (UTC), not billing month. Matrix columns are independent provider records,
  not shared batches. Pagination and errors expose partial history coverage.
- Inspector opens only after selection. It separates execution, collection and
  verification, shows inputs/outputs, original run ID, history and direct neighbors.
  Closing the inspector preserves graph context and restores focus.
- Retry preview names only the selected task, original record and scope; it shows
  downstream impact as a design relation, not automatic dispatch. No retry POST
  contract exists in Operations: confirmation stays disabled even if a stale or
  malformed catalog says can_run=true. No fabricated preflight pass. Users can
  inspect unmet conditions and original records without execution permission.
- Only Finance-scoped CRM tables already in the catalog are shown. No new tables,
  data source, identity, approval bypass or automatic rerun is introduced.

## Engineering acceptance

Required: model/layout tests (branching, cycles, missing endpoints, stable
geometry), UI tests (selection, history, filtering, stale/error races and no POST),
existing frontend regression suite/build and Go tests, browser dark-theme/layout
and keyboard checks with synthetic fixtures only. No live business mutations.

User acceptance targets (not substitutes for measured usability testing): locate
the current failure within 10 seconds; inspect its evidence within two clicks;
preserve readable text and run identity through view changes. Real finance-user
timing and production execution acceptance remain unverified.

### Local verification, 2026-09-08

- `go test ./...`: passed on the unchanged Go source baseline.
- `cd web && npm test`: 52 tests passed, including async history race protection,
  pagination retention, CRM partial/duplicate evidence and UTC month boundaries.
- `npm run build`: passed. The ELK lazy chunk is approximately 1.44 MB / 439 KB gzip;
  Vite reports its size warning. It is loaded only on the dependency page, not in
  the initial application bundle. No chunk warning threshold was weakened.
- `npm audit --audit-level=moderate`: zero reported vulnerabilities at verification.
- `npm run test:browser`: three real Chromium tests passed, with 12 nodes / 13
  edges, failure inspection, record selection, no-POST retry, geometry-preserving
  refresh, keyboard focus return and 390px viewport overflow checks. Chrome stable
  also passed the same suite. Fixtures contain no live service credentials.
- Browser screenshots were inspected locally; they are synthetic fixtures, not
  production data or a claim that actual Finance tasks completed.
- Added GitHub source CI for Go, frontend and isolated-browser regression tests.
  It does not deploy or load production credentials.

### Initial CI finding and supersession

The first PR run on `b346f4c2c5b3212c5d4df00e1ea0a16e7b2e1a58`
([run 34213806341](https://github.com/pingcap-inc/finance-portal/actions/runs/34213806341))
failed in an existing live BigQuery test, `TestFetchMarchRevenueOrderData`, because
the clean runner has no ADC credentials. That head's local Go pass did not prove
an isolated test suite. The test is now explicitly gated by the
`bigquery_integration` build tag and `FINANCE_PORTAL_BIGQUERY_READ_TEST=true`.
Default Go CI requires no warehouse identity; no production credential was added.
The subsequent PR head/check result supersedes this initial integration failure.
This changes test admission only, not Finance runtime business logic.

## Reproduce and library boundaries

Run `npm ci`, `npx playwright install chromium`, then `npm test`, `npm run build`
and `npm run test:browser` from `web/`. On Linux CI, install browser OS dependencies
with `npx playwright install --with-deps chromium`. An installed Chrome can be
used with `PLAYWRIGHT_CHANNEL=chrome npm run test:browser`.

React Flow 12.11.6 uses MIT; elkjs 0.12.0 declares EPL-2.0 OR GPL-3.0-or-later
(this integration uses the EPL-2.0 option). No paid Pro templates or copied
vendor implementation are included. Upstream sources and notices are available
from [React Flow](https://github.com/xyflow/xyflow) and
[elkjs](https://github.com/kieler/elkjs). The diagram renderer is not a scheduler:
enabling real retries still requires the server contracts listed above.