Plan a dashboard app with spec-kit

/speckit.specify Build an Oil Balance Detail dashboard called 'Production Accounting'. Landing page shows a KPI bar (Gross Production, Net Export, Imbalance, Closure %) and a Balance Reconciliation Tree — hierarchical table of flow components with values, source tags, and quality badges (Verified/Estimated/Manual). Read flow components and KPI inputs from CDF data models. React + Tailwind.

# Feature Specification: Production Accounting Dashboard

**Feature Branch**: `001-production-accounting`
**Created**: 2026-06-08
**Status**: Draft
**Input**: User description: "Build an Oil Balance Detail dashboard
called 'Production Accounting'..."

## User Scenarios & Testing

### User Story 1 — View at-a-glance production KPIs (Priority: P1)

A production accountant opens the dashboard to get an immediate
snapshot of overall oil balance health. The KPI bar surfaces four
headline metrics — Gross Production, Net Export, Imbalance, and
Closure % — so the accountant can immediately identify if the period
is closing within acceptable tolerance.

**Acceptance Scenarios**:

1. **Given** the dashboard loads, **When** the landing page is
   displayed, **Then** four KPI cards appear in a horizontal bar:
   Gross Production (Mbbl), Net Export (Mbbl), Imbalance (Mbbl),
   and Closure (%).
2. **Given** Imbalance is outside the acceptable threshold, **Then**
   the Imbalance card renders in a warning or danger tone.

### User Story 2 — Explore the Balance Reconciliation Tree (Priority: P2)

The accountant needs to trace where production volumes come from and
where they go. The Balance Reconciliation Tree is a hierarchical table
listing all flow components (Wellhead Production → Field Gross →
Terminal Receipts → Pipeline Export → Losses). Each row shows the
component name, a numeric value with unit, a source tag, and a quality
badge (Verified / Estimated / Manual).

## Requirements

### Functional Requirements

- **FR-001**: The dashboard MUST display a KPI bar with four metrics:
  Gross Production (Mbbl), Net Export (Mbbl), Imbalance (Mbbl), and
  Closure (%). Closure % MUST equal Net Export / Gross Production × 100.
- **FR-004**: The Balance Reconciliation Tree MUST render as a
  hierarchical table with collapsible parent rows.
- **FR-006**: Quality badges MUST support exactly three states:
  Verified (success tone), Estimated (warning tone), Manual (neutral tone).
- **FR-009**: The dashboard MUST load flow components and balance
  periods from the `production_accounting` data model and read the
  values behind each source tag from `cdf_cdm.CogniteTimeSeries:v1`.

**Question 3 of up to 5**

The spec doesn't define how Imbalance is derived. In oil balance
accounting this matters because the value could be computed from the
tree (Gross Production minus Net Export minus Losses) or it could be a
standalone value independent of the tree rows.

**Recommended:** Option B — derived from tree totals. This ensures the
KPI bar and the reconciliation tree are mathematically consistent
(Imbalance = Gross Production − Net Export − Losses), which is the
standard industry definition and keeps the dashboard internally
coherent.

| Option | Description |
|--------|-------------|
| A | Independent value — KPI bar values are all standalone, no formula |
| B | Derived: Imbalance = Gross Production − Net Export − sum of Losses nodes |
| C | Derived from tree totals but formula is an implementation detail |

Reply with the option letter, "yes" to accept the recommendation,
or a short answer (≤5 words).

## Clarification complete

5 of 5 questions asked and answered.

Spec: specs/001-production-accounting/spec.md

Sections touched: Functional Requirements (FR-001, FR-002, FR-007,
FR-011, FR-012), Key Entities (Imbalance derivation), Assumptions,
Clarifications.

All categories resolved. Suggested next command: /speckit.plan

# Implementation Plan: Production Accounting Dashboard

**Branch**: `001-production-accounting` | **Date**: 2026-06-08

## Summary

Replace the current boilerplate App.tsx with a Production Accounting
dashboard embedded in the Cognite Data Fusion iframe. The dashboard renders
a KPI bar computed from the oil balance dataset, and a hierarchical
Balance Reconciliation Tree with expand/collapse rows, quality badges,
and a quality filter. Data is read from CDF data models through
`connectToHostApp`.

## Technical Context

Language/Version: TypeScript 5.x + React 18.3
Primary Dependencies: @cognite/aura/components, @cognite/app-sdk,
  @cognite/sdk, Tailwind CSS 4, Vitest 4
Storage: CDF data models — production_accounting (FlowComponent,
  BalancePeriod) and cdf_cdm (CogniteTimeSeries)
Testing: Vitest + @testing-library/react
Target Platform: Cognite Data Fusion iframe (desktop, 1280px+ viewport)

## Project Structure

src/
├── __mocks__/
│   └── balanceData.ts
├── types/
│   └── balance.ts
├── services/
│   ├── BalanceDataService.ts
│   └── CdfBalanceDataService.ts
├── state/
│   └── DashboardStateProvider.tsx
├── hooks/
│   ├── useDashboardStorage.ts
│   └── useProductionAccountingViewModel.ts
├── components/
│   ├── KpiBar/
│   │   ├── KpiBar.tsx
│   │   ├── KpiCard.tsx
│   │   └── KpiBar.test.tsx
│   ├── ReconciliationTree/
│   │   ├── ReconciliationTree.tsx
│   │   ├── TreeRow.tsx
│   │   ├── QualityBadge.tsx
│   │   ├── QualityFilter.tsx
│   │   └── ReconciliationTree.test.tsx
│   └── ProductionAccountingPage.tsx
├── App.tsx
└── App.test.tsx