# ERP 表单知识图谱 (multi-granularity KG + RAG)

把 xlyweberp 低代码平台的 **1748 张业务表单** 结构化成多粒度知识图谱，打包成
LangChain4j 的 GraphRAG 语料。所有视图直接建在平台自带的配置表上（配置表本身就是一张潜在 KG，
这里只是把边**物化**出来）。

## 数据库连接

本地 `~/.my.cnf` 默认指向不存在的库 `xlyweberp_saas_ai`，**必须** 带 `--no-defaults`：

```sh
mysql --no-defaults -h127.0.0.1 -P33307 -uroot -plocal xlyweberp_saas
```

## 三个粒度

| 层  | 关注               | 视图                                    | 规模 | 消费方式 |
|-----|--------------------|-----------------------------------------|------|----------|
| L1  | 业务域（路由）     | `viw_kg_domain`                          | 11 域 | ⇒ 常驻 system prompt |
| L2 ⭐| 单据流转（最有用） | `viw_kg_edge_flow` / `viw_kg_form_neighbors` | 411 边 | ⇒ tool 按需查 |
| L3  | 实体字段 ER（NL2SQL）| `viw_kg_edge_ref` + `viw_kg_field_dict` | 1597 FK / 38k 术语 | ⇒ tool 按需查 |

**消费分层（agentic RAG）：** L1 体量小且永远相关 → 直接进 system prompt 做路由地图；
L2/L3 大且稀疏 → 做成 agent tools（`DynamicExeDbService.findSql` 薄封装）按需索引，
L3 工具必须"按词查询"而非整表 dump。L1 的 11 个域对齐 `ai_agent` 的 8 个业务智能体
（+基础资料/设备/其他→ERP代理人），可直接驱动场景路由。

## 视图/脚本一览（按依赖顺序）

0. **`viw_kg_domain`** — L1 业务域地图（11 行）：域→域流转上卷 + 锚点单据 + 对应智能体，渲染进 system prompt。
1. **`viw_ai_useful_forms`** — 1748 张有用业务表单目录（此前已建）。节点主键 `sFormId`，菜单 `sModuleId`。
2. **`viw_kg_edge_flow`** — 单据流转边：源菜单 --生成--> 目标菜单。
   目标由 `gdsconfigformslave` 上 `BtnCopyTo.<Action>` 行的 **`sActiveId`** 解析（照搬存储过程
   `Sp_Ai_AddCommonAfterNew`；`.ActXxx` 只是标签）。411 边 / 51 自环 / 404 端点命中目录。
   完整覆盖 报价→订单→送货→对账→发票→收款 与 采购申请→订单→入库→对账→发票→付款。
3. **`viw_kg_form`** — 表单节点富化（业务域 / 数据源 / 上下游单据数 / AI工具挂载）。1748 行。
4. **`viw_kg_edge_ref`** — 外键/引用边：源表.字段 --引用--> 目标表.主键。
   解析 `gdsconfigformslave.sRelation`（逗号分隔多跳 `字段&关联表&主键&显示字段`）的第一跳。
   1597 边；目标多为 `ele*`/`sis*` 主数据字典。`bTgtMaster` 标记引用主数据。
5. **`viw_kg_form_card`** — 每表单一段可向量化的结构化卡片文本 `sCard`（合并节点+上下游+字段中文名）。
6. **`viw_kg_field_dict`** — 中文名→字段→表 术语字典（38342 条），带外键 join 提示，供 NL2SQL 接地。
7. **`viw_kg_form_neighbors`** — 每表单的 1-hop 子图（上/下游单据 + 引用实体表），GraphRAG 的「图扩展」步物化。
8. **`export_form_cards.sh`** — 导出 1748 张卡片为 JSONL（供灌向量库）。生成文件 gitignore，按需重跑。

## 一键重建

```sh
# 注意：zsh 不对未加引号的变量做分词，用数组
DB=(mysql --no-defaults -h127.0.0.1 -P33307 -uroot -plocal xlyweberp_saas)
for v in viw_ai_useful_forms viw_kg_edge_flow viw_kg_form viw_kg_edge_ref \
         viw_kg_form_card viw_kg_field_dict viw_kg_form_neighbors viw_kg_domain; do
  "${DB[@]}" < "$v.sql"   # viw_kg_domain 依赖 viw_kg_form + viw_kg_edge_flow，放最后
done
./export_form_cards.sh form_cards.jsonl   # → 1748 行 JSONL
```

> 依赖顺序：edge_flow → form → (edge_ref) → form_card / field_dict。edge_ref 独立于 form。

## GraphRAG 用法（L2/L3 扩展）

1. 向量召回：把用户问题 embed，在 Milvus 里对 `form_cards.jsonl` 的 `text` 找 top-k 表单卡片。
2. 图扩展：对召回的表单，沿 `viw_kg_edge_flow`（上下游单据）+ `viw_kg_edge_ref`（关联主数据表）
   拉一跳邻居，拼成子图上下文。
3. 术语接地：用 `viw_kg_field_dict` 把问题里的中文词映射到真实列 + join 目标，喂给 NL2SQL。
4. 取数：命中表单后统一走 `POST /business/getBusinessDataByFormcustomId/{sFormId}?sModelsId={sModuleId}`。

## 校验基线

以 `ai_tool`（62 张 form-backed 工具，`sSrcFormId`=菜单id）为 ground truth 校验召回。