1. 页面概览
本体建模是 AIP 管理后台面向管理员的本体（Ontology）编辑页，路由为 /admin/ontology。它把「对象（对应数据表）→ 属性（对应列）→ 链接（对象间关系）」三层结构拆成三个 Tab 分别维护，并提供简单的本体图列表视图做总览，不依赖可视化图库。
本体数据是 NLQ 语义层的基础：查询命中本体时，以对象描述替代原始表结构注入提示词（本体定义优先于 RAG），维护好对象名、同义词、聚合类型可显著提升 NLQ 转 SQL 准确率。
一句话总结：本体建模把「表与列」抽象为「对象与属性」，再补充对象间链接，让 NLQ 链路优先使用语义定义生成 SQL。
2. 访问入口
2.1 路由与菜单
| 项目 | 值 |
|---|---|
| 路由 path | /admin/ontology |
| 路由 name | AdminOntology |
| 路由 title | 本体建模 |
| requiresAuth | true（父级 /admin 另有 requiresAdmin） |
| 菜单位置 | AdminLayout 侧边栏菜单项「本体建模」 |
| 前端源码 | action/web/src/views/OntologyPage.vue |
| 路由注册 | action/web/src/router/index.js |
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. 交互元素
| 控件 | 位置 | 含义与作用 |
|---|---|---|
| 刷新 | 页头 | 并行加载对象/链接/属性（当前为本体图 Tab 时重拉图），加载中按钮禁用并显示「加载中...」 |
| 新建对象 / 行内编辑、删除 | 对象列表 | 弹窗：名称*、基础表* 必填，显示名、数据源 ID、同义词（逗号分隔）、描述可选；删除先弹级联清单确认弹窗（列出将一并删除的属性数与链接数及名称），确认后才执行 |
| 行内「属性」 | 对象列表 | 打开对象详情弹窗，展示该对象属性列表（对象名/基础表/属性数 meta 信息），可新增/编辑/删除属性 |
| 属性弹窗「维度属性」「度量属性」 | 属性表单 | Switch 开关标记维度/度量；聚合类型下拉 SUM/AVG/COUNT/MAX/MIN；名称*、列名* 必填；数据类型（data_type）无表单项，由后端按度量/维度自动推断（度量→number，其余→text），保存后随属性列表回显 |
| 新建链接 / 行内编辑、删除 | 链接列表 | 源对象/目标对象下拉选择（不可相同），基数下拉 1:1/1:N/N:1/N:M，连接条件如 a.customer_id = b.customer_id |
| 本体图 Tab | 图视图 | 只读：对象节点显示显示名/基础表/属性 chips（含聚合类型），下方列出链接关系 |
5. 后端关联
API 端点（读挂 protected 登录组、写挂 admin 管理组，均 /ontology 前缀）：
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /ontology/objects | 对象列表（data.objects） |
| GET | /ontology/objects/:id | 对象详情（属性在 data.properties，缺省时回退全局过滤） |
| POST / PUT / DELETE | /ontology/objects[/:id] | 新建 / 编辑 / 删除对象 |
| GET / POST / PUT / DELETE | /ontology/properties[/:id] | 属性列表与增删改 |
| GET / POST / PUT / DELETE | /ontology/links[/:id] | 链接列表与增删改 |
| GET | /ontology/graph | 本体全量图（data 含 objects/links） |
5.1 关键机制
- 统一响应
{code, message, data, trace_id}；前端unwrap兼容{code,data}与直接{...}结构，asList归一化列表，后端未就绪时优雅提示不白屏。 - 对象主键兼容
id与object_type_id；同义词逗号分隔输入、提交转数组（后端为 JSON 数组）。 - 删除对象后刷新对象与链接并清空图缓存；属性/链接保存后清空图缓存，切到本体图 Tab 才重拉。
- 详情弹窗缺
properties字段时，用全局属性列表按object_type_id过滤兜底。 - 删除对象级联范围（后端
service.goDeleteObjectType）：① 该对象全部属性（object_type_id = id）② 两端任一端为该对象的链接（source_object_type_id = id OR target_object_type_id = id）③ 对象本身。删除确认弹窗即按此范围即时组装清单——属性用GET /ontology/properties?object_type_id=<id>服务端过滤、链接用GET /ontology/links前端按两端过滤；后端对象详情接口不返回属性/链接，本体后端也无「动作」实体，故不列出动作项（不编造后端不返回的字段）。
后端实现位于 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. 已知缺陷与边界
| 项 | 说明 |
|---|---|
| 图视图是列表 | 本体图用 HTML 列表展示，无节点拖拽/缩放，仅作总览 |
| 属性聚合默认 SUM | 新建属性聚合类型默认 SUM，保存时为空则不上传该字段 |
| 删除对象级联 | 已补级联清单确认弹窗：列出将一并删除的属性/链接数量与名称，确认后才执行；清单即时从既有列表接口组装，不含后端无返回的字段（如「动作」） |
| 详情回退过滤 | 详情接口缺 properties 时回退全局属性过滤，可能与详情接口结果有差异 |
注：数据源 ID 手填无下拉（对象数据源为文本输入）已于 2026-09-06 修复（数据源下拉 + 手动输入兜底）。