本体建模

1. 页面概览

本体建模是 AIP 管理后台面向管理员的本体（Ontology）编辑页，路由为 /admin/ontology。它把「对象（对应数据表）→ 属性（对应列）→ 链接（对象间关系）」三层结构拆成三个 Tab 分别维护，并提供简单的本体图列表视图做总览，不依赖可视化图库。

本体数据是 NLQ 语义层的基础：查询命中本体时，以对象描述替代原始表结构注入提示词（本体定义优先于 RAG），维护好对象名、同义词、聚合类型可显著提升 NLQ 转 SQL 准确率。

一句话总结：本体建模把「表与列」抽象为「对象与属性」，再补充对象间链接，让 NLQ 链路优先使用语义定义生成 SQL。

2. 访问入口

2.1 路由与菜单

2.2 认证与权限

守卫校验 aip_is_admin='1'，否则跳 /chat；请求经 action/web/src/api/aipClient.js 附 aip_token（Bearer JWT），401 清 token 跳登录页。

2.3 端口与 API 前缀

AIP 后端 18080，前缀 /aip-api（实际 /aip-api/v1/...，Vite 代理重写为 /api/v1）。

3. 界面布局

+------------------------------+
| 本体建模  [刷新]  [alert 提示] |
| Tab：对象 | 链接 | 本体图     |
+------------------------------+
| 对象 Tab：对象列表（card）    |
|   工具栏：[新建对象]（共 N 个）|
|   表格：名称|显示名|基础表|同义词|数据源|操作
|   行操作：属性 | 编辑 | 删除
| 链接 Tab：对象链接（card）    |
|   工具栏：[新建链接]         |
|   表格：名称|源对象|基数|目标对象|连接条件|操作
| 本体图 Tab：对象节点+属性chips+链接关系
+------------------------------+

各板块职责：顶部 alert 统一反馈操作结果；「刷新」并行重拉对象/链接/属性，并在本体图 Tab 时重拉图数据；三个 Tab 分别管理对象、链接与本体图。

4. 交互元素

5. 后端关联

API 端点（读挂 protected 登录组、写挂 admin 管理组，均 /ontology 前缀）：

5.1 关键机制

• 统一响应 {code, message, data, trace_id}；前端 unwrap 兼容 {code,data} 与直接 {...} 结构，asList 归一化列表，后端未就绪时优雅提示不白屏。
• 对象主键兼容 id 与 object_type_id；同义词逗号分隔输入、提交转数组（后端为 JSON 数组）。
• 删除对象后刷新对象与链接并清空图缓存；属性/链接保存后清空图缓存，切到本体图 Tab 才重拉。
• 详情弹窗缺 properties 字段时，用全局属性列表按 object_type_id 过滤兜底。

后端实现位于 action/products/aip/ontology/handler.go（RegisterRoutes 双组注册）、service 与 model.OntologyObjectType/OntologyProperty/OntologyLinkType。

6. 权限与安全

• 认证：aip_token（JWT Bearer），401 自动清 token 跳 /login。
• 角色：页面要求管理员（父路由 requiresAdmin，本地 aip_is_admin 校验），非管理员访问被路由守卫拦到智能查询页。
• 写操作防护：所有写端点挂后端 admin 分组，非 admin Token 请求 403；前端删除对象/属性/链接均有 confirm 二次确认，保存类操作无额外确认。

7. 常见问题与排错

问题 1：列表显示「暂无对象（后端可能未就绪）」且顶部红色 alert

原因：后端未启动、token 过期（401）或 /aip-api 代理未指向 18080。
处理：看 DevTools Network 确认请求落在 /aip-api/v1/ontology/objects；确认 AIP 进程存活；重新登录换取新 token。

问题 2：新建对象提示「对象名称必填」但已填写

原因：名称要求英文标识（如 customer），空值或纯空格会被 trim 后判空。
处理：填写合法英文标识与基础表名（如 customers）。

问题 3：链接源对象与目标对象选成同一个，报「源对象与目标对象不能相同」

原因：页面禁止自环链接。
处理：更换目标对象；确需自环需后端支持（当前前端拦截）。

问题 4：本体图提示「本体图数据格式异常」

原因：/ontology/graph 返回结构不含 objects 或 links 数组。
处理：先确保对象与链接有数据再进本体图 Tab；检查后端 graph 服务返回结构。

8. 已知缺陷与边界

注：数据源 ID 手填无下拉（对象数据源为文本输入）已于 2026-09-06 修复（数据源下拉 + 手动输入兜底）。