# Business Facts

Business facts are structured operational data used for exact counts, sums, and rankings. They complement the markdown wiki; they do not replace it.

## Purpose

Use `<vault>/_meta/business-facts.sqlite` for questions where markdown is the wrong source of truth:

- how many sales orders were received in a month
- monthly sales amount
- top customers for a month
- customer order trend for a fixed period

The wiki remains the place for context: customer background, project history, sales notes, email-derived signals, and later human-readable summaries.

## Commands

```bash
obsidian-wiki business sync kingdee --input ./kingdee-orders.json
obsidian-wiki business sync kingdee --since 2026-07-01T00:00:00Z
obsidian-wiki business query "2026年6月接了多少单"
obsidian-wiki business query "2026-06 sales amount"
obsidian-wiki business query "2026-06 top customer"
```

When `--input` is omitted, sync reads `KINGDEE_API_URL` and optional `KINGDEE_API_TOKEN`. The API response must be JSON and can be either a list of order objects or an object containing `orders`, `data`, `records`, or `items`.

## Database

Default path: `<vault>/_meta/business-facts.sqlite`.

Tables:

- `sync_runs`: one row per Kingdee sync attempt, including status, cursor, record counts, and error text.
- `raw_snapshots`: content-hashed raw JSON payloads for audit and replay.
- `orders`: one normalized row per sales order.
- `order_items`: normalized detail lines for product/quantity/line amount analysis.
- `customers`: customer lookup data observed from orders.
- `products`: product lookup data observed from order lines.

Order upsert key: `order_id`, falling back to `order_no` when no explicit ID is present. Re-syncing the same order updates the existing row and replaces that order's detail lines.

## Counting Basis

V1 statistics use fixed templates, not free-form SQL generated by an LLM.

- Monthly order count: `COUNT(DISTINCT order_no)` by `order_date`.
- Monthly sales amount: `SUM(total_amount)` by `order_date`.
- Monthly top customers: group by customer name or ID and rank by sales amount.
- Customer trend: group matching customer orders by order month.

Every answer includes the statistic, counting basis, data source, and last successful sync time. If the last successful sync is before the query date, the answer warns that newer data may be missing.

## Boundary With Wiki Ingest

Do not create one markdown page per order or order line. That makes the wiki noisy and produces unreliable statistics.

If business summaries are added later, generate compact daily or monthly summary sources from this database and pass those summaries through `wiki-ingest`. The database remains the fact source for exact numbers.