# Finance-Flux — parity with the legacy portal + decommission

The external **PingCAP Financial Flux** portal (`pingcap-flux-portal.vercel.app`,
Next.js on Vercel) has been replicated into the Helix `finance_flux` domain
(PRs 1–7, 2026-06-26/27). This is the parity record and the retirement plan.

## Feature parity

| Legacy portal | Helix `finance_flux` |
|---|---|
| Summary: 5 KPI cards (value / Δ / Δ%) | `GET /summary` → KPI cards, auto-computed from the statement totals (`kpi_def.source_line_key`), **finance-overridable** per period. Frontend: equal-height cards with good/bad tone. |
| Summary: variance-flag counts (\|Δ\|>$10K, \|Δ%\|>20%, both) | `compute_flag_summary` over all BS+PL lines; thresholds finance-configurable (global + per-line override). |
| Summary: Key Highlights (editable cards) | `finance_flux_insight_cards` (card_type=highlight) + CRUD endpoints. *(authoring widget = follow-up; backend complete)* |
| Summary: balance check | Total Assets vs Total L&E both come straight from the report (which balances by construction). |
| Balance Sheet / P&L Flux: per-line prior/current/Δ/Δ%/flag | `GET /statement?statement=BS|PL` — per-line, MoM **and YoY**. Frontend `StatementTab` table with ⚐/⚑ flags. |
| BS/PL: JE / Commentary (editable, autosaved) | `finance_flux_commentary` + `POST /commentary`; inline-editable in the table. Survives re-import (separate table). |
| BS/PL: Recon Link | same row; inline-editable. |
| BS/PL: "AI Analysis" (a hard-coded string template) | **Real upgrade** — `POST /ai/generate` calls 百炼 (`BailianLLMClient`) with the line's actual variance; "Use as Commentary" adopts it. Deterministic fallback when no LLM key (≈ the old template, but only as a fallback). |
| Period selector (MoM, only one period had data) | Real accounting periods imported from NetSuite; MoM **+ YoY**; only closed periods. |
| Upload Data (4 source types) | **Removed by design** — figures come from NetSuite's own consolidated report export (the report already does consolidation/elimination/CTA, which can't be reproduced externally — see PLATFORM PR2 note). Finance uploads the report export via `POST /import`; full auto-delivery is a mailbox away. |
| Insights: Top BS / P&L variance rankings | `GET /insights` → top movers by \|Δ\| (auto-computed). |
| Insights: editable insight cards + Recommended Follow-ups | `finance_flux_insight_cards` (insight) + `finance_flux_followups` + CRUD. *(authoring widget = follow-up; backend complete)* |
| Config (was external / hard-coded) | `GET/PUT /config` + line/KPI/account-map editors — **all finance-self-service** (`can_operate_finance`, not admin). |
| Persistence (`/api/comments` → TiDB, **broken**) | Single Helix TiDB, standard envelope, audited, idempotent. |
| — (new) | MCP read tools so AI clients can query the flux too. |

## Numerical correctness
The imported figures ARE NetSuite's consolidated report numbers, verified to
the cent against the live May-2026 consolidated Balance Sheet (Cash
$32,228,212.53 — matching the legacy portal exactly; Total Assets $187.35M,
balances with Total L&E). Helix never recomputes consolidation.

## Decommissioning the legacy portal
The Vercel site is **outside Helix infrastructure** — it is not deleted by this
work (and Helix has no credentials to do so). Retirement is a finance/ops step:

1. Confirm finance is using `/admin/finance-flux` for the current close.
2. Stop the Vercel deployment (finance/ops own the `pingcap-flux-portal`
   project) and remove its TiDB credentials.

Until the mailbox for auto-delivery is provided, finance self-service uploads
the NetSuite report export each period; the tool is fully usable today.

## Follow-ups (backend complete, UI pending)
- Inline authoring widgets for highlight/insight cards + follow-up rows
  (CRUD endpoints exist; the read views render them).
- Scheduled report → email → Helix intake for hands-off delivery (needs a
  mailbox).