YAML 导入导出（YAML Import / Export）

1. 页面概览

1.1 是什么

「YAML 导入导出」页面是 LightFoundry 本体工作台中负责对象类型声明式导入导出的页面。Foundry 的对象类型定义（对象名、属性、链接、动作、回写配置等）可以序列化为一份 YAML 文档（对外稳定契约格式），通过本页面一键导出成文本、或从文本导入并批量重建对象类型。

页面源码位于 action/web/src/views/YAMLPage.vue，共约 170 行，是三个页面中结构最简单的一个：上半部是「选择对象类型 + 导出 YAML」按钮，中部是 YAML 文本编辑区（textarea），下部是导入结果统计卡片。

顶部注释块对功能的概括非常精炼：选择对象 → 导出定义（GET export?format=yaml）到 textarea；textarea 输入 YAML → 导入（POST /ontology/objects/import），显示 created/skipped/errors。值得注意的是导出接口返回的是原始 YAML 文本，而非 {code:0} 包装的 JSON；而导入接口的请求体是原始 YAML 文本、Content-Type 为 application/yaml。这两个"不走常规 JSON 包装"的契约是本页面最容易踩坑的地方（详见第 8 章排错）。

1.2 核心价值

1.3 一句话总结

2. 访问入口

2.1 路由与菜单

访问方式：登录后从 Foundry 左侧菜单点击「YAML 导入导出」，或直接访问 /foundry/yaml。

2.2 认证与权限

• 路由 meta.requiresAuth: true；API 认证使用 aip_token（localStorage），由 client.js 请求拦截器自动附加 Authorization: Bearer <aip_token>。
• 页面不区分角色，但导出与导入都属于本体定义级读写：导出只读无副作用；导入是创建型写操作，会把 YAML 中声明的对象类型实际写入本体库。在多用户环境中建议先导出到文本备份、人工 review 后再导入。
• 401 时客户端拦截器清理 aip_token/aip_username 并跳转 /login。

2.3 端口与 API 前缀

• Foundry 后端端口：18081；Vite 开发服务器把 /api 前缀代理到该后端。
• API 基础前缀：/api/v1（client.js 的 baseURL）。
• 本页请求落在 /api/v1/ontology/...，属于 Foundry 本体域。

3. 界面布局

本页为三张纵向卡片流：

┌─────────────────────────────────────────────────────┐
│  YAML 导入导出                                       │
│  ┌─────────────────────────────────────────────────┐ │
│  │ [alert 提示条（出现时展示，右上角"关闭"）]          │ │
│  └─────────────────────────────────────────────────┘ │
│  ┌─────────────────────────────────────────────────┐ │
│  │ 选择对象类型  [下拉框]  [导出 YAML]               │ │
│  └─────────────────────────────────────────────────┘ │
│  ┌─────────────────────────────────────────────────┐ │
│  │ 本体定义（YAML）                                  │ │
│  │ ┌─────────────────────────────────────────────┐ │ │
│  │ │ textarea（等宽字体，min-height 320px）        │ │ │
│  │ └─────────────────────────────────────────────┘ │ │
│  │ [导入 YAML]  [清空]                              │ │
│  └─────────────────────────────────────────────────┘ │
│  ┌─ 导入结果（importResult 存在时展示）──────────────┐ │
│  │  总数 N  已创建 N  跳过 N  错误 N                 │ │
│  │  对象 | 错误（错误表格，可选）                    │ │
│  └─────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘

4. 交互元素详解

4.1 选择对象类型下拉框

4.2 导出 YAML 按钮

4.3 本体定义（YAML）编辑器

4.4 导入 YAML 按钮

4.5 清空按钮

4.6 导入结果卡片

5. 后端关联

5.1 API 客户端

5.2 端点表

5.3 响应结构

导入成功响应（POST /ontology/objects/import）：

{
  "code": 0,
  "data": {
    "total": 3,
    "created": 2,
    "skipped": 1,
    "errors": [
      { "object": "order", "error": "链接 \"xx\" 目标对象 \"yy\" 未创建" }
    ]
  }
}

导出成功响应（format=yaml）为原始 YAML 文本，形如：

apiVersion: zy-foundry/ontology/v1
objectTypes:
  - name: customer
    displayName: 客户
    description: 客户档案
    category: sales
    dataSourceId: 1
    baseTable: customers
    pkColumn: customer_id
    properties:
      - name: customer_id
        displayName: 客户ID
        dataType: number
        mappedColumn: customer_id
        isPrimaryKey: true
        ordinal: 1
    links: []
    actions:
      - name: update_customer_credit
        objectType: customer
        requiresApproval: false

5.4 关联模块表

5.5 关键机制

YAML 文档契约

根结构 apiVersion（固定 zy-foundry/ontology/v1）+ objectTypes 数组。导入时若 apiVersion 不匹配返回"不支持的 apiVersion"错误。对象间引用一律用 name（不直接带内部自增 id），导出时链接的 source/target、动作的 objectType 都翻译为对象 name，保证文档可移植。

两遍扫描导入

第一遍校验所有对象定义（name 必填、属性/链接/动作合法性、共享属性是否存在等），第二遍逐个创建；单个对象失败不整体回滚，仅把该对象计入 skipped 并把错误追加到 result.Errors。重复对象名同样按 skipped 处理。

导入限流

handleImportObjects 用 http.MaxBytesReader 限制请求体为 maxBodyBytes（1MB），超限直接拒绝，防止超大 YAML 打满内存。

属性/动作字段映射

属性 YAML 中 sharedProperty 引用共享属性定义（ontology_shared_properties）的 api_name，导入时按 api_name 解析为 shared_property_id 并从共享定义复制默认值；动作 YAML 中 paramSchema、validationRules、writeBackConfig 均为 JSON 对象，requiresApproval/idempotencyKeyField 为普通字段。

6. 核心流程详解

6.1 主流程：导出对象定义

1. 页面挂载执行 fetchObjects()，请求 GET /ontology/objects 填充「选择对象类型」下拉。
2. 选择一个对象（selectedId 非空），「导出 YAML」按钮由禁用变为可用。
3. 点击「导出 YAML」→ handleExport()：
   • busy=true，请求 GET /ontology/objects/:id/export?format=yaml；
   • 成功：yamlText 填入返回的 YAML 文本，alert「导出成功」，busy=false；
   • 失败：alert「导出失败：<错误信息>」，busy=false。

6.2 主流程：导入 YAML

1. 在编辑器粘贴或编写 YAML 文本（也可先导出再修改）。
2. 点击「导入 YAML」→ handleImport()：
   • busy=true，importResult=null（清掉上次结果）；
   • POST /ontology/objects/import，body 为 yamlText 原始文本，headers: {'Content-Type': 'application/yaml'}；
   • 成功：importResult = data.data，alert「导入完成」，随后 fetchObjects() 刷新对象下拉；
   • 失败：alert「导入失败：<错误信息>」。
3. 下方「导入结果」卡片展示统计；有错误时渲染错误明细表格。

6.3 分支：部分失败语义

当 YAML 声明多个对象时，后端两遍扫描保证：created + skipped = total，skipped 中每个对象对应一条 errors 条目（对象级错误，不整体回滚）。已创建的对象照常生效，用户可修正错误对象后再次导入同一份文档（已存在的对象按 skipped 处理，不会重复创建——这也是 created/skipped 拆分的意义）。

6.4 状态流转

7. 权限与安全

• 认证：aip_token Bearer 认证；/ontology/... 全部挂载在 protected 路由组。
• 数据级安全：导出仅返回本体定义（不含业务数据），无行级敏感数据外泄风险；但对象定义中可能含 isPII 标记、synonyms 等元信息，导出文档对外分发时需注意脱敏与权限控制。
• 写操作防护：导入是创建型操作，前端以「导入 YAML」按钮置灰（文本为空时禁用）+ busy 忙碌锁防护重复提交；后端以 1MB body 上限、两遍扫描校验、对象级失败隔离兜底，部分失败不影响已创建对象。
• 审计：导入的每个对象通过 CreateObjectType 落库，版本快照机制自动生成版本记录，可回溯谁在何时创建了什么对象。

8. 常见问题与排错

9. 已知缺陷与边界