brandize_bi/AGENTS.md

# AGENTS.md

Guidance for agents working in this repository (Brandize · BI Dashboard).

## What this project is

A **flat, server-free browser dashboard** for the Brandize BI webhook. It renders
gross revenue (Brutto inkl. USt) per departure country plus a VAT summary, with KPI
cards, bar charts and detail tables. There is **no build step, no framework, no
package manager** — just static files opened directly in a browser.

Supporting tools: a bash dev-server launcher (`start`) and a Python CLI (`send`) that
uploads CSV rows to an n8n webhook. SQL scripts (`sql/`) define the upstream queries
that feed the webhook (Odoo 17 / PostgreSQL).

## Layout

| Path | Purpose |
| --- | --- |
| `index.html` | Dashboard markup: sidebar nav, shared filter bar, one `<main class="view">` per report, auth overlay |
| `styles.css` | All styling (CSS custom properties in `:root`, BEM-ish class names) |
| `app.js` | Everything: data loading, parsing, rendering, CSV export, auth, navigation |
| `README.md` | User-facing docs (German/English mixed). Update it when behavior changes |
| `start` | Bash: installs `live-server` if missing and serves the folder on :8080 |
| `send` | Python CLI: batches CSV rows to the `.../webhook/VAT` n8n webhook |
| `sql/*.sql` | Upstream Odoo/PostgreSQL queries (see below) |
| `data/` | Git-ignored. Empty in the repo; holds local CSV payloads for `send` |

## Running / validating

There is **no test suite and no linter**. Validation is manual:

- Open `index.html` directly (double-click) — the intended primary usage, works over `file://`.
- Or run `./start` and browse `http://localhost:8080` for live reload.
- `./send data/<file>.csv` requires Python 3 + `requests` and network access to the webhook.

Because `fetch` hits a remote webhook protected by HTTP Basic Auth, you generally
**cannot fully exercise the UI without valid credentials and network access**. Don't
claim validation passed unless you actually loaded the page and saw it work; otherwise
state clearly what you could not run.

## Architecture notes (`app.js`)

Single file, loaded as a plain `<script>` (not a module), `"use strict"` at the top.
No bundler — keep everything in global scope as the file already does.

- **Config constants** at the top: `API_URL`, `MONTHS` (German abbreviations), `PALETTE`.
- **`els`** — a single object caching all `getElementById`/`querySelector` lookups.
  Add new DOM handles here rather than querying inline.
- **State**: `currentView`, `lastData` (`{ abgangsland, vat }`), `auth`.
- **Sections** are delimited by `/* ---------- Name ---------- */` banners: Auth,
  Period selector, Formatting, Data, Rendering (per report), CSV export, Navigation, Init.
- **Views**: the `VIEWS` map defines title/subtitle per view id. `showView(name)`
  toggles `.hidden` on the `<main class="view">` elements and re-renders. A new report
  needs: markup section in `index.html`, an entry in `VIEWS`, a render function, and a
  `viewEls()` branch.
- **Data flow**: `load()` → `POST API_URL` with `{ query, month }` → `extractArray(payload, key)`
  → `normalizeAbgangsland` / `normalizeVat` → `renderActiveView()`. `load()` queries
  **only** the active dashboard's dataset; it is triggered from `showView()` (when a
  dashboard is displayed) and from the refresh/period controls — never prefetched.

### Webhook / data contract

- The webhook is called with **POST** and a JSON body `{ "query": <key>, "month": "YYYY-MMM" }`
  (quarter dashboards send `{ "query": <key>, "quarter": "YYYY-QN" }` instead).
  `query` selects the dataset. The datasets are large, so **exactly one dataset is
  requested per call**, for the dashboard currently shown (no prefetching).
- Query keys: `"Summe je Abgangsland"` (Umsatz je Abgangsland), `"VAT Summary"`,
  `"ODOO Rechnungen pro Monat"`, `"Alle Rechnungen pro Monat"`, `"Quartal Schweiz"`,
  `"FIFO Lager Bewertung"` and `"Produkt Materialkosten"`. Each view's `query` lives in
  the `VIEWS` map, which maps the active dashboard to its `normalize` function;
  `quarter: true` marks the dashboards that use a quarter period. The FIFO and
  Produkt-Materialkosten responses are `[{ id, query, row_count, data: [...] }]`
  (unwrapped in `normalizeFifo` / `normalizeMaterialkosten`). In *Produkt Materialkosten*,
  `remaining_qty` is the remaining quantity of that cost bracket (the last cost bracket, not FIFO),
  not the product total.
- `extractArray` accepts the dataset either as a bare array or wrapped under the
  query key (case-insensitive). If the shape changes upstream, adjust the normalizers.
- The webhook returns **German-formatted strings**, e.g. `"90.717,93 €"` and
  `"1.234"`. Parsing (`parseEuro`, `parseQuantity`) strips symbols and swaps
  `.`/`,` — do **not** use `parseFloat` directly on the raw values.
- `month` uses `YYYY-MMM` (e.g. `2026-SEP`), matching `%(month)s` in `sql/*.sql`;
  `quarter` uses `YYYY-QN` (e.g. `2026-Q3`), matching `%(quarter)s` in `sql/Quartal_Schweiz.sql`.

### Auth

HTTP Basic. The first request goes out without credentials; a `401` triggers the
login overlay. Credentials live in `sessionStorage` (best-effort — unavailable on
`file://`, where they stay in memory only) and are sent as `Authorization: Basic ...`.

## SQL scripts (`sql/`)

Odoo 17 / PostgreSQL against table `brandize_datacenter_amazon_vat_transaction`.
Each file has a header block documenting the model, parameters and invocation.

- Parameter is named `%(month)s` for psycopg2; in `psql` use `:'month'` instead
  (documented in the headers — respect this distinction).
- Money is formatted **in SQL** to German notation via
  `translate(to_char(...), ',.', '.,') || ' €'` so the frontend receives display-ready
  strings. Keep formatting consistent if you add columns.
- `Delete_Activity_Period.sql` is destructive — note the "ACHTUNG" warning and the
  transaction-bracket guidance. Be cautious editing it.

## Conventions

- **Language**: UI text is **German**, code identifiers and comments are English
  (comments occasionally German). Keep new user-facing strings German.
- **Number/date formatting**: always `de-DE` via `toLocaleString` in JS and German
  `to_char` formatting in SQL. Dates as `YYYY-MMM` with the `MONTHS` abbreviations.
- **JS style**: `"use strict"`, double quotes, semicolons, 2-space indent, `const`/`let`
  (no `var`), named `function` declarations, `camelCase`. Nullish-safe (`??`, optional
  guards). DOM built imperatively with `document.createElement` (charts are hand-rolled
  bars/lists, no chart library).
- **CSS**: use the existing `:root` custom properties for colors/spacing/radius; reuse
  existing class patterns rather than inventing new naming.
- **CSV export**: semicolon-delimited, UTF-8 **with BOM** (for Excel umlauts), CRLF line
  endings, includes a `Gesamt` total row, filename `*_YYYY-MMM.csv`. Follow this pattern
  for any new exportable view.
- Keep changes minimal and consistent with the existing file structure — this is a small,
  intentionally dependency-free static app. Prefer no new dependencies.

## Gotchas

- `data/` is git-ignored; never commit contents from it. `send` expects CSVs with a
  header row (`csv.DictReader`) and posts JSON arrays in batches of 50.
- The `send` script targets a **different** webhook (`/webhook/VAT`) than the dashboard
  (`/webhook/bi-dashboard`). Don't conflate them.
- `fetch` from `file://` sends `Origin: null`; the webhook reflects origins to allow CORS.
  Changing how requests are made can break the "just open the file" workflow.
- README documents behavior (navigation, auth, CSV, filter). If you change any of these,
  update `README.md` in the same change.
- The invoice dashboards (*ODOO Rechnungen pro Monat*, *Alle Rechnungen pro Monat*
  and *Quartal Schweiz*) are pivot experiments: they load jQuery, jQuery UI and
  PivotTable.js from CDNs (so they need internet), reuse `normalizeRechnungen`, and
  render via `renderRechnungenPivot` (no detail table). Layouts come from
  `PIVOT_PRESETS` (keyed per view; the Vorlage dropdown) / the pivotUI panel; the
  renderer is fixed to *Table*. The pivot container is recreated on each render so
  a preset actually applies.