本体导出（OWL / SHACL / TTL / YAML / JSON）

1. 页面概览

1.1 是什么

本体导出（Ontology Export）是 LightFoundry 语义互操作能力（V5 Stage 5，B7-5）的前端出口，对应 OntologyExportPage.vue。它以「选择导出范围 → 切换格式 → 预览与下载」三步交互，把本体模型（对象类型、属性、链接、继承/接口）渲染为多种可交换语义格式：单个对象支持 OWL（Turtle）、TTL（Turtle）、SHACL、YAML、JSON 五种格式；整库导出支持 OWL（全部对象一图）与 TTL 两种格式。

导出是单向的（B7-5 明确不做 roundtrip 保证）：OWL/TTL 面向语义图互操作（对象→owl:Class、属性→owl:DatatypeProperty、链接→owl:ObjectProperty、接口→rdfs:subClassOf），SHACL 面向校验形状（sh:NodeShape + 各属性 sh:PropertyShape），YAML 面向声明式导入（与本体工作台「YAML 导入导出」页共用 ontology.ExportObject），JSON 面向程序消费（GetObjectType 详情原样输出）。

1.2 核心价值

1.3 一句话总结

本体导出页是把 Foundry 本体模型一键翻译为 OWL/SHACL/TTL/YAML/JSON 标准语义格式的互操作出口——范围任选、格式任切、先预览后下载。

2. 访问入口

2.1 路由与菜单

• 路由路径：/foundry/ontology-export，路由名 FoundryOntologyExport，meta.title 为「本体导出」，meta.requiresAuth: true（定义于 action/web/src/router/index.js 第 364-369 行，Foundry 子路由内）。
• 菜单入口：Foundry 侧边栏（action/web/src/views/FoundryLayout.vue 第 109 行）菜单项「本体导出」。
• 源码文件：action/web/src/views/OntologyExportPage.vue。

2.2 认证与权限

• 路由级 requiresAuth: true：未登录访问被路由守卫拦截到登录页。
• API 级认证：经 action/web/src/api/client.js 统一注入 aip_token（Authorization: Bearer <token>）；401 由响应拦截器清 token 并跳 /login。
• 权限要求：本页接口挂在 Foundry protected 鉴权组下（server.go 第 983 行 protected.GET("/ontology/objects/:id/export", ...)、第 1137-1138 行 /ontology/objects/:id/shacl 与 /ontology/export/owl），任何已登录用户（持有合法 aip_token）均可访问；不校验 admin 角色。
• 404 排错：若预览报 404，先确认 Foundry 后端（18081）已启动；再确认请求路径带上了正确的对象 id 与 format 参数；/ontology/export/owl 整库出口仅在新版 server 接线后存在（B7-5 新增路由）。

2.3 端口与 API 前缀

端口：18081（Foundry）。API 前缀：/api（baseURL /api/v1），本页接口路径如 GET /api/v1/ontology/objects/1/export?format=owl、GET /api/v1/ontology/objects/1/shacl、GET /api/v1/ontology/export/owl。

3. 界面布局

语义导出（OWL / SHACL / YAML / JSON）
└─ 提示条（alert，右上角「关闭」）
└─ 卡片「导出设置」
   ├─ 导出范围（radio）：单个对象 | 整库导出（全部对象一图）
   ├─ [单个对象] 选择对象类型（下拉：name（v version））+ 导出格式（下拉）
   ├─ [整库] 导出格式（下拉：OWL（Turtle，全部对象一图）| TTL（Turtle））
   └─ 按钮：导出预览 | 下载
└─ 卡片「导出内容」
   ├─ 标题：导出内容（整库 / OWL / TTL / SHACL / YAML / JSON）
   ├─ 内容区：pre.export-viewer（原样回显）
   └─ 空态：「请选择范围与格式后点击「导出预览」。」

各板块职责：

• 提示条：加载对象列表、导出成功/失败的统一反馈。
• 导出设置卡片：范围与格式的选择区；「导出预览」按钮在 canExport 不满足（单个对象且未选对象类型）时禁用；「下载」在内容为空时禁用。
• 导出内容卡片：预览结果的只读展示区，支持横向/纵向滚动（max-height: 520px; overflow: auto）。

4. 交互元素详解

4.1 导出范围与格式

对象范围格式选项：OWL（Turtle）、TTL（Turtle）、SHACL、YAML、JSON。整库范围格式选项：OWL（Turtle，全部对象一图）、TTL（Turtle）。

4.2 导出预览的请求分发

normalize(res) 的语义：后端对 TTL/YAML 以原始文本返回（c.Data 直接输出 body），对 JSON 以 {code:0,data} 包装；因此 typeof res.data === 'string' 时原样使用，否则 JSON 格式化。

4.3 下载命名规则

下载实现：new Blob([content], { type: 'text/plain;charset=utf-8' }) → URL.createObjectURL → 临时 <a download> 点击 → 移除节点并 revokeObjectURL。

5. 后端关联

5.1 API 客户端

本页使用 action/web/src/api/client.js（baseURL: '/api/v1'、timeout: 30000、aip_token Bearer 注入、401 跳登录），无自定义导出函数。

5.2 端点表

handleExportObject 后端 switch 逻辑：json→GetObjectType 输出；owl/ttl→export.ExportOWL；shacl→export.ExportSHACL；其它（含缺省）→ontology.ExportObject（YAML）。对象 id 解析失败（resolveObjectID）时返回错误。

5.3 响应结构

TTL/YAML 出口以原始文本返回（前端 normalize 直接取 res.data 字符串），例如 OWL 文档：

# LightFoundry Ontology — OWL/Turtle 导出（B7-5）
# 命名空间: http://zyinfo.local/foundry/ontology#
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix owl: <http://www.w3.org/2002/07/owl#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix foundry: <http://zyinfo.local/foundry/ontology#> .

foundry:customer a owl:Class ;
    rdfs:label "客户" ;
    rdfs:comment "客户主数据" ;
    foundry:baseTable "customers" ;
    foundry:pkColumn "id" .

JSON 出口为 {code:0,data:{...}} 包装，前端取 data.data 再格式化。

5.4 关联模块表

5.5 关键机制

• OWL 渲染映射：对象类型→owl:Class（含 rdfs:label、rdfs:comment、foundry:category/baseTable/pkColumn）；属性→owl:DatatypeProperty（DataType→XSD 映射，未知类型以 foundry:dataType 标注）；链接→owl:ObjectProperty（目标对象名按内部 id 解析）；接口（implements_interfaces）→rdfs:subClassOf。
• SHACL 渲染：对象→sh:NodeShape（sh:targetClass 指向 OWL 类 IRI）；属性→sh:PropertyShape（sh:datatype 来自 XSD 映射；sh:minCount/maxCount 由 IsPrimaryKey/constraints 推导；枚举→sh:in RDF 列表；正则→sh:pattern；长度→sh:minLength/maxLength 防御性扩展）。
• 整库一图：ExportOWLAll 先 ListObjectTypes 建目标名 map，再逐对象 GetObjectType 组 detail 列表统一渲染，链接目标名无需逐条查库。
• 单向导出：不做 roundtrip 保证；format=owl 与 format=ttl 共用同一渲染输出。

6. 核心流程详解

6.1 主流程：单对象导出

1. 页面加载时 onMounted(fetchObjects) 拉取 GET /ontology/objects，填充对象类型下拉。
2. 保持「单个对象」范围，选择对象类型（如 customer（v1）），选格式（如 OWL（Turtle））。
3. 点「导出预览」→ 请求 GET /ontology/objects/{id}/export?format=owl，normalize 后写入预览区，alert「导出成功」。
4. 点「下载」→ 生成 customer.ttl 下载。
5. 切换格式（TTL/SHACL/YAML/JSON）重复预览，观察不同语义视图。

6.2 分支流程：整库导出

1. 范围切到「整库导出（全部对象一图）」，对象选择区隐藏，格式仅剩 OWL/TTL。
2. 点「导出预览」→ GET /ontology/export/owl，所有对象类型渲染进同一 Turtle 图。
3. 下载文件名固定为 ontology-export.ttl。

6.3 状态与终态语义

导出为同步请求（timeout 30 秒），无轮询；busy 期间按钮禁用；失败 alert「导出失败：<error>」并保留旧内容（content 在请求前先清空）。下载按钮以 content.trim() 判空禁用，即「未预览不可下载」。

7. 权限与安全

• 认证：aip_token JWT；401 自动跳登录。
• 数据级安全：对象详情（JSON 导出）走 GetObjectType，与本体工作台同源同权；无对象级 RLS/CLS 过滤（本体定义本身非行/列数据）。
• 写操作防护：本页纯读操作，无写防护需求；导出不落库、不产生审计副作用。

8. 常见问题与排错

8.1 导出预览报 404

现象：点「导出预览」后 alert「导出失败：...404...」。原因：请求路径或参数不对（对象 id 无效），或后端路由未挂载（如整库出口 /ontology/export/owl 为 B7-5 新增，旧版本 server 没有）。排查步骤：1) 确认已选择对象类型（未选时按钮本身禁用）；2) 抓包确认 URL 为 /api/v1/ontology/objects/{id}/export?format=xxx；3) 在浏览器直接访问该 URL 验证；4) 确认后端为 v5 Stage 5+ 版本且 protected 组挂载了 983/1137-1138 行路由。

8.2 预览内容为空

现象：预览区空白或仍显示「请选择范围与格式后点击「导出预览」。」原因：请求成功但 res.data 为空字符串/空对象；或导出失败被静默吞掉（normalize 对字符串空值直接返回）。排查步骤：1) 检查 alert 是否有错误提示；2) 直接 curl 请求该出口看 body 是否为空；3) 若对象无属性/链接，OWL 仍应有类声明与前缀——确认对象真实存在。

8.3 下载文件名不带正确扩展名

现象：下载文件名为 object.ttl 或 .txt。原因：selectedObjectName() 未匹配到对象（列表为空或 id 不在列表），回退到 object；或格式不在映射表（兜底 .txt）。排查步骤：1) 确认对象下拉已加载且有数据；2) 确认所选格式为 owl/ttl/shacl/yaml/json 五者之一；3) 整库导出固定 ontology-export.ttl，属预期行为。

8.4 整库导出非常慢或超时

现象：对象数量多时预览超时（30 秒 timeout）。原因：ExportOWLAll 对每个对象逐次 GetObjectType（N 次查询），对象多时耗时线性增长。排查步骤：1) 少量对象先验证；2) 大库建议改用单对象导出分片；3) 后端可考虑在 ExportOWLAll 批量预取详情优化。

9. 已知缺陷与边界