# 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 `/_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 - customer, product, salesperson, organization, department, project, warehouse, status, and currency rankings or breakdowns - customer, product, and salesperson summaries - sales order counts, lists, trends, quantities, averages, and delivery-plan quantities The wiki remains the place for context: customer background, project history, sales notes, email-derived signals, and cross-linked narrative knowledge. ## Commands ```bash scripts/obsidian-wiki-ops.py kingdee sync --input ./kingdee-orders.json scripts/obsidian-wiki-ops.py kingdee config # Fill .runtime/kingdee.env, then test the login/refresh flow: scripts/obsidian-wiki-ops.py kingdee auth-test scripts/obsidian-wiki-ops.py kingdee sync \ --start-bizdate 2026-06-01 \ --end-bizdate 2026-06-30 \ --billstatus C scripts/obsidian-wiki-ops.py kingdee sync --start-modifytime "2026-07-01 00:00:00" scripts/obsidian-wiki-ops.py kingdee sync --incremental # wiki-query uses this schema/template catalog to answer business questions. scripts/obsidian-wiki-ops.py kingdee schema --json scripts/obsidian-wiki-ops.py kingdee template order_count --vault /path/to/vault --year 2026 --month 6 --json scripts/obsidian-wiki-ops.py kingdee template sales_amount --vault /path/to/vault --year 2026 --month 6 --json scripts/obsidian-wiki-ops.py kingdee template top_products --vault /path/to/vault --year 2026 --month 6 --limit 10 --json scripts/obsidian-wiki-ops.py kingdee template staff_summary --vault /path/to/vault --start-date 2026-06-30 --end-date 2026-07-07 --staff 徐丽 --staff-role-scope all --json # Guarded SQL is for gaps where no template fits. scripts/obsidian-wiki-ops.py kingdee sql "SELECT COUNT(*) AS order_count FROM orders" ``` When `--input` is omitted, sync reads `.runtime/kingdee.env`, gets or refreshes an access token, calls the official Kingdee sales order API, and stores the returned rows. If the file does not exist, `business sync kingdee` creates the template and asks you to fill it before retrying. For unattended sync, install the user-level systemd timer: ```bash scripts/obsidian-wiki-ops.py timer install --vault /path/to/vault scripts/obsidian-wiki-ops.py timer run-now --vault /path/to/vault scripts/obsidian-wiki-ops.py timer status ``` The timer defaults to daily `07:10` with a 15-minute randomized delay. It runs incremental Kingdee sync with a 48-hour lookback window. The config template includes: - Token defaults follow Kingdee's enhanced OpenAPI token authentication doc: `https://vip.kingdee.com/knowledge/specialDetail/226337046514476288?category=239331354741842688&id=489812471545485056&productLineId=29`. - `KINGDEE_SALORDER_API_URL`: defaults to the official `querySalOrder` endpoint. - `KINGDEE_TOKEN_URL`: defaults to the official enhanced-token endpoint `/kapi/oauth2/getToken`. - `KINGDEE_CLIENT_ID`, `KINGDEE_CLIENT_SECRET`, `KINGDEE_USERNAME`, `KINGDEE_ACCOUNT_ID`, `KINGDEE_LANGUAGE`: fixed fields used to build the official getToken request body. - `nonce` and `timestamp`: generated automatically for every token request; `timestamp` uses the official zero-time-zone format by default. - `KINGDEE_TOKEN_BODY_EXTRA_JSON`: optional fixed extra fields merged into the generated token request body. - `KINGDEE_TOKEN_BODY_JSON`: advanced override for nonstandard token request bodies. - `KINGDEE_TOKEN_HEADERS_JSON`: optional token request headers, such as app-specific headers. - `KINGDEE_TOKEN_FIELD`, `KINGDEE_TOKEN_EXPIRES_IN_FIELD`, `KINGDEE_TOKEN_EXPIRES_IN_UNIT`, `KINGDEE_REFRESH_TOKEN_FIELD`: dot paths and units used to read token response fields. The official `expires_in` unit is milliseconds. - `KINGDEE_REFRESH_URL` and `KINGDEE_REFRESH_BODY_JSON`: optional refresh request. Use `{refresh_token}` in the JSON body template. - `KINGDEE_ACGW_IDENTITY`: value sent as the required `x-acgw-identity` sales-order API header. - `KINGDEE_PAGE_SIZE`: default sales-order page size. `KINGDEE_LOGIN_URL`, `KINGDEE_LOGIN_BODY_JSON`, and `KINGDEE_LOGIN_HEADERS_JSON` are accepted as aliases for the token settings. `KINGDEE_ACCESS_TOKEN` can also be set for one-off manual testing. Fetched tokens are cached in `.runtime/kingdee-token.json`; both local files are ignored by git and should not be copied into `.env.example`. The API response can still be imported from a JSON file for replay or testing. JSON may be a list of order objects or an object containing `orders`, `rows`, `data`, `records`, or `items`. ## Database Default path: `/_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. It keeps the query-critical fields (`order_id`, `order_no`, `order_date`, customer, status, organization, department, operator, currency, total amount, net amount, tax amount, address, comment) plus `raw_json` for the full original order header. - `order_items`: normalized material detail lines. It keeps material number/name/model, quantity, unit, price, tax-inclusive price, net amount, tax-inclusive amount, tax amount, delivery date, project, warehouse, and `raw_json` for the full original line. - `order_deliveries`: normalized delivery-plan rows from `billentry[].orderdeliverentry[]`. It keeps planned demand date, planned delivery date, planned quantity, planned base quantity, unit, receive address/place, remark, transport lead time, and `raw_json` for the full original delivery-plan row. - `order_staff`: sales staff roles extracted from the order header. Roles are `primary_sales`, `sales_2`, `sales_3`, `sales_4`, and `followup`. - `sync_state`: saved Kingdee incremental cursor. - `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 and delivery-plan rows. `total_amount` is the statistic field used by monthly sales queries. For Kingdee sales orders it prefers `totalallamount` (价税合计) and falls back to other total fields only when the tax-inclusive total is absent. `total_net_amount`, `total_tax_amount`, and `total_all_amount` are stored separately so later reports can choose a different accounting basis without re-fetching historical payloads. ## Query Flow And Counting Basis `wiki-query` decides semantically whether a user question needs business facts. When it does, it loads `obsidian-wiki business schema --json`, chooses a template if one fits, and only then uses guarded SQL for gaps. Template families include: - Order totals: `order_count`, `sales_amount`, `customer_count`, `product_count`, `quantity_sum`, `avg_order_amount`. - Trends: `order_trend`, `sales_trend`, `quantity_trend`, grouped by day or month. - Rankings and breakdowns: customers, products, staff, organizations, departments, projects, warehouses, statuses, currencies. - Lists: orders, customer orders, product orders, staff orders. - Summaries: customer, product, and staff summaries. - Delivery plans: delivery-plan count, quantity, and list by planned date. Core counting basis: - Order count: `COUNT(DISTINCT order_no)` by `orders.order_date`. - Sales amount: `SUM(orders.total_amount)` by `orders.order_date`. - Ordered quantity: `SUM(order_items.quantity)` by `orders.order_date`. - Delivery-plan quantity: `SUM(order_deliveries.plan_qty)` by `order_deliveries.plan_date`. - Staff templates join `orders` to `order_staff`, defaulting to `primary_sales`. 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. Salesperson templates default to the main Kingdee salesperson (`operator_operatorname`). Use `--staff-role-scope all`, or wording such as "全部角色" or "含跟单", to include sales 2/3/4 and follow-up roles. If no template matches, `wiki-query` may generate guarded SQL and execute it through `business sql`. The SQL fallback is still restricted: - only one `SELECT` or `WITH ... SELECT` statement - only structured tables: `orders`, `order_items`, `order_deliveries`, `order_staff`, `customers`, `products`, `sync_runs` - no `raw_json` columns and no `raw_snapshots` - no write, schema, attach, pragma, or vacuum statements - default result limit is 100 rows, capped at 1000 ## Incremental Sync `scripts/obsidian-wiki-ops.py kingdee sync --incremental` uses Kingdee `start_modifytime`. - First run without a cursor: fetches the last 7 days. - Later runs: starts from the saved cursor minus 48 hours. - Explicit `--start-modifytime` or `--since` wins over the computed cursor. The 48-hour lookback intentionally re-fetches recent orders so late edits and boundary cases are updated rather than missed. Upserts keep the database deduplicated by `order_id`. ## Boundary With Wiki Ingest Do not create one markdown page per order or order line. That makes the wiki noisy and produces unreliable statistics. The database remains the fact source for exact numbers; the wiki remains the context source.