Odoo-Modules/fusion_accounting_reports/CLAUDE.md

# fusion_accounting_reports — Cursor / Claude Context

## Purpose

AI-augmented financial reports — a Fusion-native replacement for Odoo
Enterprise's `account_reports` module. Phase 2 of the fusion_accounting
roadmap.

CORE scope:
- Income Statement (P&L)
- Balance Sheet
- Trial Balance
- General Ledger (with drill-down)

AI augmentation:
- Anomaly detection (variance vs prior period)
- AI commentary (LLM-generated narrative)

## Architecture

Hybrid: the engine (`fusion.report.engine`, AbstractModel) is the SINGLE
read surface for reports. Per-report definitions are stored as `fusion.report`
records with JSON `line_specs` so non-developers can tweak the layouts.

Public engine API (5 methods):
- `compute_pnl(period, *, comparison='none', company_id=None)`
- `compute_balance_sheet(date_to, *, comparison='none', company_id=None)`
- `compute_trial_balance(period, *, company_id=None)`
- `compute_gl(period, *, account_ids=None, company_id=None)`
- `drill_down(*, account_id, period, company_id=None)`

Pure-Python services in `services/` (no Odoo imports — independently
unit-testable):
- `date_periods` — `Period` dataclass + comparison-period math
- `account_hierarchy` — chart-of-accounts tree walk
- `totaling` — debit/credit/balance roll-ups
- `currency_conversion` — multi-currency conversion via `res.currency.rate`
- `line_resolver` — JSON `line_specs` → rendered rows
- `drill_down_resolver` — line → underlying journal items
- `anomaly_detection` — variance vs prior period (z-score + abs/pct gates)
- `commentary_generator` — LLM narrative with templated fallback
- `commentary_prompt` — provider-agnostic system + user prompt

Persisted models in `models/`:
- `fusion.report` — definition with JSON `line_specs`
- `fusion.report.commentary` — LLM-output cache (one per period+mode)
- `fusion.report.anomaly` — flagged variances
- `fusion.account.balance.mv` — pre-aggregated materialized view
- `fusion.report.engine` — AbstractModel (the API)
- `fusion.reports.cron` — cron handlers (commentary refresh, MV refresh)
- `fusion.xlsx.export.wizard` — TransientModel (XLSX export)
- `fusion.period.picker.wizard` — TransientModel (UX entry-point)
- `fusion.migration.wizard` (inherits) — adds `_reports_bootstrap_step`

Controller: `controllers/reports_controller.py` exposes 8 JSON-RPC endpoints
under `/fusion/reports/*`. All read paths route through the engine.

OWL frontend: `static/src/`
- `scss/` — variables, base styles, dark-mode overrides
- `services/reports_service.js` — central reactive state + RPC wrappers
- `views/report_viewer/` — top-level OWL view + view-registry adapter
- `components/report_table/` — generic financial-table renderer
- `components/drill_down_dialog/` — modal for journal-item listing
- `components/period_filter/` — date-range + comparison picker
- `components/ai_commentary_panel/` — LLM commentary surface
- `components/anomaly_strip/` — variance summary banner
- `tours/reports_tours.js` — 5 OWL tour smoke tests

## Coexistence

When `account_reports` is installed, the Reports menu hides via
`fusion_accounting_core.group_fusion_show_when_enterprise_absent`
(a computed group). The engine + AI tools (commentary, anomaly detection)
remain available for the chat regardless.

## Conventions

- **V19 deprecations to avoid:** `_sql_constraints` (use `models.Constraint`),
  `@api.depends('id')` (raises `NotImplementedError`), `@route(type='json')`
  (use `type='jsonrpc'`), `numbercall` field on `ir.cron` (removed),
  `groups_id` on `res.users` (use `all_group_ids` for searching),
  `users` field on `res.groups` (use `user_ids`), `groups_id` on
  `ir.ui.menu` (use `group_ids`).

- **Engine signature:** Public methods are keyword-only after the leading
  positional `period` / `date_to`. Always pass `company_id=...` explicitly.

- **`fusion.report` lookup:** `_get_report` falls back from per-company
  override to global (`company_id=False`) — order is `company_id desc nulls
  last`.

- **Materialized view refresh:** `fusion.account.balance.mv` rebuilds via a
  dedicated autocommit cursor (REFRESH CONCURRENTLY can't run inside Odoo's
  regular transaction). Triggered by cron + on demand from the engine when
  data is older than the configured TTL.

- **JSON `line_specs`:** Strings prefixed `account:`, `prefix:`, `formula:`
  or `header` — `line_resolver.py` resolves each spec to a row. Header rows
  have no compute payload and are silently skipped by downstream totals.

- **Commentary cache:** Keyed on `(report_id, company_id, period_from,
  period_to, comparison_mode)` with a unique constraint. Re-runs use the
  cache unless `force_refresh=True`.

## Test counts (Phase 2 ship)

- 130 logical tests, 0 failed, 0 errors
- Includes:
  - 6 benchmarks (tagged `benchmark`)
  - 1 LLM compat smoke (tagged `local_llm`, skips when no LLM)
  - 5 OWL tours (tagged `tour`, skips without `websocket-client`)
  - Property-based, integration, controller, materialized-view, coexistence,
    migration round-trip, PDF/XLSX export

## Performance baseline

| Operation | Median | P95 | Budget |
|---|---|---|---|
| `engine.compute_pnl` | 3ms | 8ms | <2000ms |
| `engine.compute_balance_sheet` | 15ms | 20ms | <2000ms |
| `engine.compute_trial_balance` | 3ms | 8ms | <1000ms |
| `engine.compute_gl` | 25ms | 81ms | <3000ms |
| `engine.drill_down` | 2ms | 10ms | <500ms |
| `controller.run` (HTTP round-trip) | 9ms | 46ms | <2500ms |

All metrics within 1x of budget at Phase 2 ship. Numbers from
`tests/test_performance_benchmarks.py` against the dev VM
(`westin-v19`, ~1 fiscal year of data).

## Known concerns / Phase 2.5 backlog

- Trial balance period-only sum doesn't auto-close to retained earnings
  (drift visible in `test_trial_balance_total_near_zero`, currently skipped)
- Balance sheet `TOTAL LIABILITIES + EQUITY` math limited (no
  subtotal-of-subtotals expansion in `formula:` specs)
- GL `line_specs` need `prefix:` empty-string handling for
  "all accounts" semantics
- Header rows (no compute payload) silently skipped by `line_resolver` —
  fine for layout, but a `header_only=True` flag would be clearer
- `expense` prefix overlaps with subtypes (`expense_direct_cost`,
  `expense_depreciation`) — current line_specs need explicit ordering or a
  longer-prefix-wins rule
- `wkhtmltopdf` may need configuration for PDF export on first install
- `ReportsAdapter.run_report` vs `run_fusion_report` naming (legacy clash
  with Enterprise wrapper)
- Tour tests skip when `websocket-client` is absent — install it in CI to
  exercise the OWL surface end-to-end