feat(business): add schema-driven query templates

Expose a business schema catalog and explicit template runner for Kingdee sales-order facts. Update wiki-query guidance so the LLM routes operational questions through templates first and guarded SQL only when needed. Refresh user docs and ops aliases, and add coverage for schema metadata, template execution, and CLI JSON output.

Validation: python3 -m unittest discover -v; python3 -m compileall obsidian_wiki tests scripts; git diff --check
This commit is contained in:
Codex
2026-07-06 22:27:49 +00:00
parent b85c26e0ba
commit d3f3151218
8 changed files with 1327 additions and 39 deletions
+227
View File
@@ -8,9 +8,11 @@ from pathlib import Path
from unittest.mock import patch
from obsidian_wiki.business_facts import (
business_schema,
business_db_path_for_vault,
compute_incremental_start_modifytime,
execute_business_sql,
execute_business_template,
query_business_question,
sync_kingdee_orders,
)
@@ -461,6 +463,231 @@ class BusinessFactsTests(unittest.TestCase):
self.assertEqual(fallback["template"], "sql_fallback")
self.assertEqual(fallback["rows"], [{"order_no": "SO-001", "customer_name": "Customer A"}])
def test_business_schema_describes_templates_fields_and_sql_guardrails(self):
schema = business_schema()
template_names = {template["name"] for template in schema["templates"]}
templates = {template["name"]: template for template in schema["templates"]}
self.assertTrue(
{
"order_count",
"sales_amount",
"customer_count",
"product_count",
"quantity_sum",
"avg_order_amount",
"order_trend",
"sales_trend",
"quantity_trend",
"top_customers",
"top_products",
"top_staff",
"top_orgs",
"top_departments",
"top_projects",
"top_warehouses",
"breakdown_by_customer",
"breakdown_by_product",
"breakdown_by_staff",
"breakdown_by_org",
"breakdown_by_department",
"breakdown_by_status",
"breakdown_by_currency",
"order_list",
"customer_order_list",
"product_order_list",
"staff_order_list",
"customer_summary",
"product_summary",
"staff_summary",
"delivery_plan_count",
"delivery_plan_quantity",
"delivery_plan_list",
"order_status_breakdown",
"billstatus_breakdown",
"close_status_breakdown",
}.issubset(template_names)
)
table_names = {table["name"] for table in schema["tables"]}
self.assertIn("orders", table_names)
self.assertIn("order_items", table_names)
self.assertIn("order_staff", table_names)
self.assertIn("order_deliveries", table_names)
self.assertIn("COUNT(DISTINCT order_no)", schema["metric_guidance"]["order_count"])
self.assertEqual(templates["customer_count"]["required_parameters"], [])
self.assertEqual(templates["product_count"]["required_parameters"], [])
self.assertEqual(templates["customer_summary"]["required_parameters"], ["customer"])
self.assertEqual(templates["product_summary"]["required_parameters"], ["product"])
self.assertEqual(templates["staff_summary"]["required_parameters"], ["staff"])
self.assertIn("raw_json", schema["sql_guardrails"]["forbidden_columns"])
self.assertIn("raw_snapshots", schema["sql_guardrails"]["forbidden_tables"])
def test_execute_business_templates_cover_core_totals_rankings_lists_and_delivery_plans(self):
sync_kingdee_orders(
self.vault,
[
{
"id": "1001",
"billno": "SO-001",
"bizdate": "2026-06-03",
"customer_number": "C01",
"customer_name": "Customer A",
"totalallamount": "100.00",
"settlecurrency_number": "CNY",
"billstatus": "C",
"orderstatus": "D",
"closestatus": "A",
"org_name": "Org A",
"dept_name": "Dept A",
"operator_operatorname": "徐丽",
"billentry": [
{
"id": "L1",
"material_masterid_number": "P01",
"material_masterid_name": "Part 1",
"qty": "2",
"amountandtax": "60",
"project_name": "Project A",
"warehouse_name": "Warehouse A",
"orderdeliverentry": [
{
"id": "D1",
"d_plandate": "2026-06-10",
"d_plandeliverydate": "2026-06-08",
"d_planqty": "2",
}
],
},
{
"id": "L2",
"material_masterid_number": "P02",
"material_masterid_name": "Part 2",
"qty": "1",
"amountandtax": "40",
"project_name": "Project B",
"warehouse_name": "Warehouse B",
},
],
},
{
"id": "1002",
"billno": "SO-002",
"bizdate": "2026-06-04",
"customer_number": "C02",
"customer_name": "Customer B",
"totalallamount": "300.00",
"settlecurrency_number": "CNY",
"billstatus": "B",
"orderstatus": "C",
"closestatus": "A",
"org_name": "Org B",
"dept_name": "Dept B",
"operator_operatorname": "王五",
"h5a3_basedatafield2_operatorname": "徐丽",
"billentry": [
{
"id": "L1",
"material_masterid_number": "P01",
"material_masterid_name": "Part 1",
"qty": "3",
"amountandtax": "300",
"project_name": "Project A",
"warehouse_name": "Warehouse A",
"orderdeliverentry": [
{
"id": "D2",
"d_plandate": "2026-06-11",
"d_planqty": "3",
}
],
}
],
},
],
synced_at="2026-07-06T09:00:00Z",
)
count = execute_business_template(self.db_path, "order_count", start_date="2026-06-01", end_date="2026-07-01")
sales = execute_business_template(self.db_path, "sales_amount", year=2026, month=6)
customers = execute_business_template(self.db_path, "customer_count", year=2026, month=6)
products = execute_business_template(self.db_path, "product_count", year=2026, month=6)
quantity = execute_business_template(self.db_path, "quantity_sum", year=2026, month=6)
average = execute_business_template(self.db_path, "avg_order_amount", year=2026, month=6)
top_products = execute_business_template(self.db_path, "top_products", year=2026, month=6, limit=1)
staff = execute_business_template(
self.db_path,
"staff_summary",
year=2026,
month=6,
staff="徐丽",
staff_role_scope="all",
)
delivery_qty = execute_business_template(self.db_path, "delivery_plan_quantity", year=2026, month=6)
status = execute_business_template(self.db_path, "billstatus_breakdown", year=2026, month=6)
self.assertEqual(count["data"]["order_count"], 2)
self.assertEqual(sales["data"]["sales_amount"], 400.0)
self.assertEqual(customers["data"]["customer_count"], 2)
self.assertEqual(products["data"]["product_count"], 2)
self.assertEqual(quantity["data"]["quantity_sum"], 6.0)
self.assertEqual(average["data"]["avg_order_amount"], 200.0)
self.assertEqual(top_products["rows"][0]["product_id"], "P01")
self.assertEqual(top_products["rows"][0]["quantity"], 5.0)
self.assertEqual(staff["data"]["order_count"], 2)
self.assertEqual(staff["data"]["sales_amount"], 400.0)
self.assertEqual(delivery_qty["data"]["delivery_plan_quantity"], 5.0)
self.assertEqual(
[(row["status"], row["order_count"]) for row in status["rows"]],
[("B", 1), ("C", 1)],
)
def test_execute_business_template_rejects_unknown_or_missing_parameters(self):
with self.assertRaisesRegex(RuntimeError, "unknown business template"):
execute_business_template(self.db_path, "not_a_template", year=2026, month=6)
with self.assertRaisesRegex(RuntimeError, "requires"):
execute_business_template(self.db_path, "staff_summary", year=2026, month=6)
def test_cli_business_schema_and_template_print_json(self):
sync_kingdee_orders(
self.vault,
[
{
"id": "1001",
"billno": "SO-001",
"bizdate": "2026-06-03",
"customer_name": "Customer A",
"totalallamount": "100.00",
}
],
synced_at="2026-07-06T09:00:00Z",
)
from obsidian_wiki.cli import main
schema_output = StringIO()
with redirect_stdout(schema_output):
schema_code = main(["business", "schema", "--json"])
template_output = StringIO()
with redirect_stdout(template_output):
template_code = main(
[
"business",
"template",
"order_count",
"--vault",
str(self.vault),
"--year",
"2026",
"--month",
"6",
"--json",
]
)
self.assertEqual(schema_code, 0)
self.assertEqual(template_code, 0)
self.assertIn("order_count", {template["name"] for template in json.loads(schema_output.getvalue())["templates"]})
self.assertEqual(json.loads(template_output.getvalue())["data"]["order_count"], 1)
def test_incremental_start_modifytime_uses_cursor_with_lookback_or_initial_days(self):
initial = compute_incremental_start_modifytime(
self.db_path,