本体工作台

1. 页面概览

1.1 是什么

「本体工作台」是 LightFoundry 数据集成与本体引擎的核心建模页面，对应前端源码 action/web/src/views/FoundryPage.vue，挂载于 Foundry 产品侧边栏（FoundryLayout）的第一个菜单项。页面的职责可以用一句话概括：用对象类型（Object Type）把企业数据"语义化"——把数据源中的基础表建模为本体对象，再在对象上叠加属性（Properties）、关系（Links）与动作（Actions）三层定义，最终形成一个可供语义检索、对象查询（OOL）、指标计算、Action 写路径统一消费的本体模型层。

本体（Ontology）层是 LightFoundry 对标 Palantir Foundry 本体系统的核心。它位于"数据集成"与"应用开发"之间：下层是数据集与数据源（基表、字段），上层是管道、指标、应用、工作流、语义检索等消费方。对象类型定义一旦合入（merged），就会落到真实的数据库表（主表），后续的语义检索、对象查询、Action 执行全部基于这套定义运行。因此本页是 Foundry 一切语义能力的"总入口"，也是建模者日常操作最频繁的页面。

页面实现的功能包括四大块：（1）对象类型列表与详情浏览——以表格展示全部对象类型及其状态、版本与三要素数量，点击行进入详情面板；（2）创建对象类型——通过一个含属性/链接/动作三组嵌套行的表单一次性创建完整对象定义；（3）对象定义详情编辑——在选中对象后通过「属性 / 关系 / 动作」三个 Tab 分别进行子定义的增删改，其中属性变更走"创建草稿 → 更新草稿 → 提交评审 → 合入"的版本状态机四连调用；（4）版本状态机操作——创建草稿、提交评审、合入、回滚四个版本级动作，以及合入/回滚前必现的影响分析弹窗。

页面的信息层级非常清晰：顶部是全局操作区（创建对象按钮与结果提示），中部是对象类型列表，底部（选中对象后出现）是详情面板。详情面板内又分为版本操作区（草稿/评审/合入/回滚）、Tab 切换区、以及对应 Tab 的子定义表格与新增表单。

1.2 核心价值

1.3 一句话总结

本体工作台是 LightFoundry 的"对象类型建模台"：以对象为纲、属性/链接/动作为目，用草稿-评审-合入-回滚的版本状态机保证每一次结构变更都安全、可审计、可回退。

2. 访问入口

2.1 路由与菜单

侧边栏激活高亮规则：isActive('/foundry') 使用精确匹配（route.path === '/foundry'），其余子页面按前缀匹配。因此只有正好访问 /foundry 时"本体工作台"才高亮，访问 /foundry/versions 等子页时高亮切到对应子菜单，不会让本体工作台常亮。

访问方式：登录 Foundry（/login 统一登录，token 存 localStorage 的 aip_token）后，点击任意 Foundry 页面侧边栏顶部的「本体工作台」，或直接访问 http://<host>:5173/foundry（开发态 Vite 端口 5173）。

2.2 认证与权限

2.3 端口与 API 前缀

注意与其它产品区分：AIP 前端 API 前缀为 /aip-api（18080）、Apollo 为 /apollo-api（18082）、Gotham 为 /gotham-api（18083）、Swift 为 /swift-api（18084）。本体工作台属于 Foundry，一律使用 /api/v1/... 前缀；若误用其它产品前缀会打到错误后端返回 404。

3. 界面布局

页面整体为单栏纵向布局（FoundryLayout 左侧边栏 + 右侧内容区），本页内容从上到下分为五块。文字框图如下：

┌─────────────────────────────────────────────────────────────┐
│ 页头（page-header）                                          │
│   [Foundry 本体工作台]                    [创建对象]/[收起表单] │
├─────────────────────────────────────────────────────────────┤
│ 操作结果提示（alert）— 加载/创建/保存/合入/回滚的反馈条        │
├─────────────────────────────────────────────────────────────┤
│ 创建对象类型表单（card，默认收起，点「创建对象」展开）          │
│   名称/显示名称/数据源ID/基础表/主键列/多列主键/实现接口/分类/描述 │
│   附加数据源 supplementary_sources（+附加行，≤3）               │
│   属性（+属性行）/ 链接（+链接行）/ 动作（+动作行）三子块       │
│   [创建对象] [取消]                                          │
├─────────────────────────────────────────────────────────────┤
│ 对象类型列表（card）                                          │
│   工具栏：关键字过滤 / 每页条数 ▾ / 第 N/M 页 / 上一页 下一页  │
│   表头：ID | 名称 | 显示名称 | 状态 | 版本 | 属性 | 链接 | 动作 │
│   行：点击选中（row-selected 高亮）                          │
├─────────────────────────────────────────────────────────────┤
│ 详情面板（card，选中对象后出现）                               │
│   标题行：显示名 + 状态徽标 + v版本号 + meta 信息               │
│   版本操作区：[创建草稿][提交评审][合入] [回滚到版本▾][回滚]     │
│   Tab 切换：[属性][关系][动作]（默认「属性」）                  │
│   ┌ 属性 Tab：新增属性表单(内联) + 属性表(编辑/删除)           │
│   ┌ 关系 Tab：新增链接表单(内联) + 链接表(删除)                │
│   ┌ 动作 Tab：新增动作表单(内联) + 动作表(删除)                │
└─────────────────────────────────────────────────────────────┘
   └─ 全局覆盖层：影响分析弹窗（modal-overlay + modal-card）

各板块职责：

• 页头：展示页面标题「Foundry 本体工作台」，右侧按钮在「创建对象」与「收起表单」两个文案间切换，控制创建表单的显隐。
• 操作结果提示（alert）：页面所有异步操作的成败反馈统一走这里。alert.message 非空时显示提示条，颜色由 alert.type 决定（alert-info/alert-success/alert-error 等），右上角有「关闭」链接按钮。成功提示绿色、失败提示红色、信息提示蓝色。
• 创建对象类型表单：默认收起。展开后是一个栅格布局（三列）的基础字段区 + 三个虚线框子块（属性/链接/动作）。每个子块都支持动态增删行，用于一次定义对象的完整结构。
• 对象类型列表：核心导航区。加载中显示「加载中...」；空数据显示「暂无对象类型，请点击"创建对象"添加。」；有数据时表格列出对象类型（前端分页，默认每页 20 条），工具栏提供关键字过滤、每页条数与上一页/下一页翻页，行可点击选中（高亮 row-selected）。
  诚实标注：GET /ontology/objects 没有服务端分页参数（仅 status 过滤，一次返回全量），因此本页的分页与关键字过滤均为纯前端实现（对已取回数据切片/内存过滤），目的是降低一次渲染大量行的开销，不是服务端分页（不减少网络传输量）。
• 详情面板：选中对象后出现。包含版本操作按钮组、Tab 切换、以及当前 Tab 的子定义表格与内联新增表单。
• 影响分析弹窗：合入/回滚触发的模态弹窗，覆盖全页（modal-overlay 半透明遮罩，点击遮罩空白处可关闭），<pre class="code-block"> 展示 JSON.stringify 后的影响分析报告。

4. 交互元素详解

4.1 页头区

4.2 操作结果提示条

4.3 创建对象类型表单（card）

创建对象 payload 组装要点（handleCreate）：对象级高级字段先组装——pk_columns_text 经 parsePkColumnsText 解析为数组、implements_interfaces 过滤空项、supplementary_sources 过滤全空行（table/join_on/data_source_id 皆为空的整行剔除，data_source_id 经 Number(...)||0 转数值），三者非空才写入 payload（空则不提交该字段，交由后端缺省）；属性行过滤掉 name 为空的行后映射为 {name, display_name, data_type, mapped_column: mapped_column || name, is_pii, is_primary_key, synonyms, description, constraints?, shared_property_id?}，其中 constraints 由 buildPropConstraints(data_type, enum_text, orig, unit, precision) 按 ValueType 联动组装（enum→constraints.enum；currency/percentage→constraints.unit；decimal→constraints.precision；无剩余键则不提交），shared_property_id 非空才写入；同义词/描述取 trim 后字符串。链接行过滤 name 为空后映射为 {name, target_object_type_id, cardinality, direction}；动作行过滤 name 为空后映射为 {name, edit_type, description: description || '', param_schema, validation_rules, write_back_config, idempotency_key_field, requires_approval}，其中三个 JSON 字段经 parseOptionalJSON 解析（空串 → null）。提交前先做两道本地校验：动作 JSON 合法性；属性 ValueType 联动约束（enum 需枚举值、currency/percentage 需 unit）。任一不满足时提示并直接 return（不发出请求）。

后端契约：CreateObjectTypeRequest 支持 pk_columns / supplementary_sources / implements_interfaces（service_impl.go:196-210，字段定义见 models.go:100-102），属性 PropertyInput 支持 constraints / shared_property_id（service_impl.go applyToModel）。implements_interfaces 由 validateImplementsInterfaces 校验（validate.go:105-129），currency/percentage 的 unit 由 validatePropertyTypeConstraints 校验（validate.go:374-403）；decimal 的 precision 后端未做强校验（前端按约定录入）。supplementary_sources 在 models.go:101/service_impl.go:205 为 JSON（[]byte）透传存储，Go 侧无结构体形状、无 ≤3 校验（其形状 [{"data_source_id":n,"table":"x","join_on":"..."}] 来自设计约定 wiki/design/design_foundry.md:203，非后端强约束）；存储路径见 repository.go:746。

4.4 对象类型列表（card）

列表数据来自 GET /ontology/objects，响应 data 为 ObjectTypeSummary 数组，每项结构为 {object_type: {...}, property_count, link_count, action_count}。

分页实现口径（重点）：该端点无 limit/offset/page 参数，一次返回全量。前端用 filteredObjects（关键字内存过滤）→ totalPages（ceil(过滤后长度 / 每页条数)）→ pagedObjects（slice 当前页）三层计算属性完成分页；keyword/pageSize 变化时 watch 回到第 1 页，totalPages 变小（如过滤后）时自动把越界页码回退。因此分页只减少 DOM 渲染量，不减少请求数据量；对象数量非常大时仍会全量拉取。

4.5 详情面板——标题与版本操作区

4.6 Tab 切换

Tab 通过 tabs 数组渲染，tab-btn.active 高亮为蓝色下划线式。

4.7 属性 Tab

4.8 关系 Tab

链接的创建/删除会生成新的 merged 版本（后端 AddLink/DeleteLink 返回 version），刷新后详情与版本列表同步更新。

4.9 动作 Tab

动作的新增与编辑共用同一个弹窗（.modal-card.action-modal），覆盖动作四大配置块（param_schema / validation_rules / write_back_config / idempotency_key_field / requires_approval）——只有 param_schema 时动作执行后无法回写源数据。

4.10 影响分析弹窗（modal）

弹窗在三种场景出现：合入前（先单独调 POST /ontology/objects/{id}/impact 弹「合并前影响分析」）、合入后（merge 返回的 impact 字段弹「合入结果（影响分析）」）、回滚后（rollback 返回的 impact 弹「回滚结果（影响分析）」）。

5. 后端关联

5.1 API 客户端

本页使用通用客户端 action/web/src/api/client.js（默认导出 apiClient）：

5.2 端点表（本体工作台实际调用）

5.3 响应结构（JSON 示例）

统一信封：成功 {"code": 0, "data": ...}；失败 {"code": "<错误码>", "error": "<详情>"}，HTTP 状态取错误码映射（见 5.5）。

GET /ontology/objects 响应示例

{
  "code": 0,
  "data": [
    {
      "object_type": {
        "id": 1,
        "name": "order",
        "rid": "object-type:order",
        "display_name": "订单",
        "description": "",
        "category": "core",
        "data_source_id": 1,
        "base_table": "orders",
        "pk_column": "id",
        "status": "merged",
        "version": 3,
        "created_by": "admin",
        "created_at": "2026-08-30T10:00:00Z",
        "updated_at": "2026-08-30T11:00:00Z"
      },
      "property_count": 5,
      "link_count": 2,
      "action_count": 3
    }
  ]
}

GET /ontology/objects/:id 响应示例（详情面板数据源）

{
  "code": 0,
  "data": {
    "object_type": { "id": 1, "name": "order", "display_name": "订单", "status": "merged", "version": 3, "data_source_id": 1, "base_table": "orders", "pk_column": "id" },
    "properties": [
      { "id": 10, "name": "order_id", "display_name": "订单号", "data_type": "integer", "mapped_column": "order_id", "is_pii": false, "is_primary_key": true, "ordinal": 1 },
      { "id": 11, "name": "amount", "display_name": "金额", "data_type": "currency", "mapped_column": "amount", "is_pii": false, "is_primary_key": false, "ordinal": 2 }
    ],
    "links": [
      { "id": 5, "name": "belongs_to_customer", "source_object_type_id": 1, "target_object_type_id": 2, "cardinality": "N:1", "direction": "directed" }
    ],
    "actions": [
      { "id": 8, "name": "update_status", "description": "更新订单状态", "edit_type": "modify", "param_schema": { "type": "object" } }
    ]
  }
}

POST /ontology/objects/:id/drafts 响应示例

{ "code": 0, "data": { "version_id": 42 } }

POST /ontology/drafts/:vid/merge 响应示例（含影响分析）

{
  "code": 0,
  "data": {
    "version_id": 42,
    "impact": {
      "object_type_id": 1,
      "object_type_name": "order",
      "impacts": [
        { "type": "link", "id": "5", "name": "belongs_to_customer", "detail": "link \"belongs_to_customer\" (1 → 2)target 引用" },
        { "type": "metric", "id": "3", "name": "gmv", "detail": "列 dimensions 内容引用对象 \"order\"" }
      ]
    }
  }
}

POST /ontology/objects/:id/rollback 响应示例

{
  "code": 0,
  "data": { "target_version": 2, "impact": { "object_type_id": 1, "object_type_name": "order", "impacts": [] } }
}

5.4 关联模块表

5.5 关键机制

（1）版本状态机 draft → review → merged（核心机制）

对象类型结构不允许直接修改线上定义，一切结构变更必须先进入版本状态机：

• CreateDraft：以最新 merged 快照为底创建 draft，版本号 = 最新 merged 版本 + 1，base_version = 最新 merged 版本。响应 {version_id}（版本记录 id，注意不是版本号）。
• UpdateDraft：仅 draft 状态可更新。用请求里的完整新定义覆盖草稿快照，并计算 change_diff（kind=object_type/property/link/action，op=add/modify/delete，含 before/after）。修改前后都会做 validate.go 校验；改名（name 是稳定标识唯一索引）不得与其它对象重复，否则报 DUPLICATE_ENTRY。
• SubmitReview：draft → review。同时记录 approval_policy：若快照中任意动作 requires_approval=true，则 min_approvals=1 且 self_approval=false（受保护资源需至少 1 人审批且不允许自批）；否则 min_approvals=0、允许自批。
• Approve / Reject（审批闭环）：仅 review 状态可审批。Approve 写一条 approve 审批记录（策略禁自批时若审批人即版本创建人返回 APPROVAL_DENIED）；Reject 写 reject 记录并把版本状态置回 draft（可修改后重新 review，状态机保持三态不变）。
• Merge：仅 review 可合入。前置两道闸门：①审批门禁（min_approvals>0 时 approve 数须达标，否则 APPROVAL_REQUIRED；禁自批时存在自批 approve 记录则 APPROVAL_DENIED）；②真冲突检测——draft 的 base_version 落后于 main 最新 merged 时，聚合 (base, latest] 区间所有 merged 版本的 diff 与草稿 diff 按 (kind, api_name) 求交，任一 op∈{modify,delete} 即冲突，返回 merge conflict on resource(s): ...（INVALID_VERSION_STATE）；无真冲突则"非冲突自动合并"（以 main 最新快照为底应用草稿 diff，双方变更均保留）。合入成功后以最新 merged 快照重建主表，返回影响分析报告。
• Rollback：目标必须是 merged 版本（否则 INVALID_VERSION_STATE）。从历史 merged 快照重建主表并新建 merged 版本（版本号递增），返回影响分析报告。回滚前检查历史快照 name 是否被其它对象占用（DUPLICATE_ENTRY）。

非法状态转移统一返回错误码 INVALID_VERSION_STATE（HTTP 409），例如 merged 再 merge、draft 未 review 直接 merge、rollback 目标非 merged 等。

（2）影响分析（impact.go）

AnalyzeImpact 扫描对象被引用的位置并返回分组清单 ImpactItem{type, id, name, detail}，type 取值 link|action|pipeline|lineage|metric|report|edit：

• ontology_links：source 或 target 指向该对象，detail 标注「source 引用 / target 引用」；
• ontology_actions：object_type_id 指向该对象；
• pipeline_definitions / data_lineage / foundry_metrics：先 HasTable 检查，表未建时输出占位项「(表未就绪)」并跳过；指标表的 dimensions/filters 等 JSON 列按内容包含对象名匹配；
• ontology_edits：存在进行中的编辑时输出「N 条进行中的编辑记录（ontology_edits）」。

（3）API 错误响应约定

成功 {code: 0, data}；失败 {code, error}，HTTP 状态由 ierr 映射。本页常见错误码：NOT_FOUND（404）、VALIDATION_ERROR（422）、DUPLICATE_ENTRY（409）、INVALID_VERSION_STATE（409）、APPROVAL_REQUIRED（409）、APPROVAL_DENIED（409）、DATA_SOURCE_NOT_FOUND（404）。

（4）ValueType 13 类冻结目录

属性类型下拉与后端 GET /ontology/value-types 一一对应：text/number/integer/decimal/currency/percentage/date/datetime/bool/enum/json/array<text>/array<number>。前端常量 web/src/constants/valueTypes.js 冻结取值与顺序（B7-1，禁增删改序），类型 label 带括号值（如「文本（text）」。

6. 核心流程详解

6.1 主流程一：创建对象类型

1. 点击页头「创建对象」，展开创建表单。
2. 填写基础字段：名称（api_name，必填）、显示名称、数据源 ID（必填，默认 1）、基础表、主键列、多列主键 pk_columns（复合主键时填，逗号分隔）、实现接口 implements_interfaces（多选，可选）、分类、描述；若对象需补充表，在「附加数据源 supplementary_sources」子块点「+ 附加行」逐行填数据源 ID / 补充表名 / 关联条件（设计约定 ≤3，留空不提交）。
3. 在「属性」子块填属性行（默认 1 行，可点「+ 属性行」追加）；属性行第一行含属性名/显示名/数据类型（13 类 ValueType 下拉）/映射列/PII/主键，第二行可填同义词与属性口径说明。空属性名行会在提交时被过滤。
4. 在「链接」子块点「+ 链接行」添加关系行：链接名、目标对象（从已有对象下拉选择，显示 name（#id））、基数（1:1/1:N/N:M）、方向（directed/bidirectional/undirected）。
5. 在「动作」子块点「+ 动作行」添加动作行：动作名、编辑类型（modify/create/delete/link）、param_schema JSON，还可填幂等键字段、勾选需审批，并在第二行填 validation_rules / write_back_config JSON。所有 JSON 字段必须是合法 JSON（空可留白），否则提交被前端拦截；复杂写回配置可在对象创建后到详情「动作」Tab 点「编辑」补齐。
6. 点「创建对象」提交（按钮变「提交中...」禁用）。前端组装完整 payload 调 POST /ontology/objects。
7. 成功提示「对象创建成功 id=N」，重置表单收起，刷新列表；新对象出现在列表（初始 status=merged，version=1）。失败提示「创建失败：<错误详情>」（如数据源不存在 DATA_SOURCE_NOT_FOUND、name 重复 DUPLICATE_ENTRY、字段校验失败 VALIDATION_ERROR）。

6.2 主流程二：选中对象并查看/编辑定义

1. 点击列表行选中对象 → selectObject 置 selectedId、清空回滚选择，并行加载详情（GET /ontology/objects/:id）与版本历史（GET /ontology/objects/:id/versions）。
2. 详情面板出现：标题行显示显示名/状态徽标/v版本号与 meta（name/数据源/表/主键）。
3. 默认停留在「属性」Tab：表格展示属性名（下含口径小字）/显示名/类型/映射列/同义词/PII/主键；可点「新增属性」展开内联表单（可填同义词、属性口径说明），或点行内「编辑」「删除」。
4. 切「关系」Tab 查看/新增/删除链接；切「动作」Tab 查看/新增/删除动作。

6.3 主流程三：版本状态机四连调用（属性变更快速合入）

属性 Tab 的「保存/删除」按钮是页面最典型的状态机操作，代码 commitPropertyChange(nextProperties) 按顺序发出 4 个请求：

1. 建草稿 POST /ontology/objects/{id}/drafts → 得 version_id（版本记录 id）。
2. 更新草稿 PUT /ontology/drafts/{version_id}，请求体为当前对象完整新定义（对象主字段 + 变更后的属性列表 + 原链接 + 原动作）。服务端校验合法后覆盖草稿快照并计算 change_diff。
3. 提交评审 POST /ontology/drafts/{version_id}/review → draft 变 review。
4. 合入 POST /ontology/drafts/{version_id}/merge → 过审批门禁与冲突检测后重建主表，生成新 merged 版本。

成功提示「属性保存成功（已生成新 merged 版本）」或「属性"xx"已删除」，随后 loadDetail + loadVersions 刷新。若其中任一步失败（如当前对象已存在进行中的 draft、校验失败、审批门禁拒绝、真冲突），整条链中断，弹「属性保存失败：<详情>」。

版本状态机语义表

6.4 主流程四：合入与影响分析

「合入」按钮是一个两段式操作：

1. 先取 latestByStatus('review') 找最新 review 版本；没有则提示「没有可合入的 review 版本（请先提交评审）」。
2. 有则先调 POST /ontology/objects/{id}/impact，弹出「合并前影响分析」模态窗（JSON 原文），让评审者确认下游影响。
3. 再调 POST /ontology/drafts/{review.id}/merge；成功后提示「版本 vX 已合入」，并弹出「合入结果（影响分析）」展示 merge 返回的 impact（合入后的最新影响扫描）。
4. 刷新详情与版本列表，状态徽标与版本号更新。

6.5 主流程五：回滚

1. 从「回滚到版本」下拉选择目标版本（仅列 merged 版本，显示 v{{version}}）。
2. 点「回滚」（未选版本时按钮禁用）。触发 confirm('确定回滚到 vX 吗？将重建主表并生成新版本。')。
3. 确认后调 POST /ontology/objects/{id}/rollback，body {target_version: X}。
4. 成功提示「回滚成功」并弹出「回滚结果（影响分析）」；刷新详情与版本列表。回滚会在版本历史上新增一个 merged 版本（版本号递增），而不是删除历史。

6.6 分支流程：审批门禁（requires_approval 动作）

当对象快照中存在 requires_approval=true 的动作时，SubmitReview 会生成 min_approvals=1、self_approval=false 的审批策略。此后「合入」前必须有人对 review 版本执行 Approve（后端路由 POST /ontology/objects/:id/versions/:vid/approve），否则 merge 返回 APPROVAL_REQUIRED。本页当前未内置审批操作入口（审批动作属于版本历史等其它页/接口），因此这类对象在本页「提交评审 → 合入」的链路会被审批门禁拦截，提示合入失败，需通过其它途径完成审批后再合入。这是本页的一个边界（见第 9 章）。

7. 权限与安全

8. 常见问题与排错

8.1 「合入前置版本状态依赖 latestByStatus」——提交评审/合入提示没有可操作的版本

现象：点了「提交评审」却提示「没有可评审的 draft 版本（请先创建草稿）」；或点了「合入」却提示「没有可合入的 review 版本（请先提交评审）」。

原因：前端用 latestByStatus(status) 取 versions 数组中第一个 status === 'draft'（或 'review'）的版本。若当前对象不存在对应状态的版本，或版本历史尚未刷新（比如刚创建草稿后版本列表是旧的），就会命中该分支。另外若草稿曾被驳回（reject 置回 draft），状态为 draft 也能重新走评审。

排查步骤：

1. 确认版本列表已刷新：选中对象时会调用 GET /ontology/objects/:id/versions，可打开浏览器 Network 检查该请求最近一次是否成功且包含目标状态版本。
2. 确认状态：draft 版本的 status 字段必须是 draft 才能评审；review 版本必须是 review 才能合入；merged 版本两者都不能再操作。
3. 若刚创建草稿，稍等 loadVersions 完成再点「提交评审」；或先重新选中对象行强制刷新详情与版本。

8.2 属性保存报「属性保存失败」且提示 INVALID_VERSION_STATE

现象：属性 Tab 新增/删除属性点「保存」后报错，错误详情含 INVALID_VERSION_STATE 或"only draft can be updated"。

原因：commitPropertyChange 四连调用的第一步是无条件 POST /ontology/objects/{id}/drafts 建草稿，但若对象当前已存在进行中的 draft 版本，服务端 CreateDraft 不会重复建草稿（或 UpdateDraft 因目标版本不是 draft 而拒绝），状态机不满足转移条件。属性快速合入要求当前对象处于"无进行中草稿"的干净状态。

排查步骤：

1. 查看版本列表确认是否存在 status=draft 的进行中版本（页面上详情面板没有直接的版本列表，可切到「版本历史」页 /foundry/versions 查看）。
2. 若有进行中的 draft：先把它完成（提交评审并合入），或先回滚/处理掉，再回来做属性保存。
3. 若确认无 draft 仍失败，检查响应 error 详情是否为其它错误（校验失败、审批门禁等）。

8.3 「合入」弹影响分析后被 APPROVAL_REQUIRED 拒绝

现象：点「合入」先弹出「合并前影响分析」，紧接着合入请求返回失败，提示 APPROVAL_REQUIRED：merge requires 1 approval(s), got 0。

原因：对象快照含 requires_approval=true 的动作，SubmitReview 时生成 min_approvals=1、self_approval=false 审批策略，而本页没有审批入口，approve 数不足导致合入被门禁拦截（这是设计行为）。

排查步骤：

1. 用任意 API 客户端调用 POST /ontology/objects/:id/versions/:vid/approve（vid 为 review 版本记录 id）完成一次审批（非版本创建人身份）。
2. 或先在「动作」Tab 把 requires_approval 动作调整为不需要审批的配置后重新走一遍草稿链路。
3. 若审批人为版本创建人且策略禁自批，会被 APPROVAL_DENIED 拒绝，需换一个用户审批。

8.4 创建对象报「数据源 ID 不存在」或 name 重复

现象：「创建对象」提交失败，提示 DATA_SOURCE_NOT_FOUND 或 DUPLICATE_ENTRY。

原因：data_source_id 必须指向已存在的数据源（Foundry 数据源管理页配置，如演示数据源 sales_data_warehouse）；name（api_name）是全局唯一稳定标识，与已有对象重名即冲突。

排查步骤：

1. 到「数据源」页确认数据源存在且 ID 正确（默认值 1 不一定有效）。
2. 换一个 name 或用「YAML 导入导出」页检查当前已有哪些对象名。
3. 若需改名，走「创建草稿 → 更新草稿（改名）→ 评审 → 合入」，注意草稿改名同样受唯一索引约束。

8.5 页面接口报 401 自动跳登录页

现象：操作任意按钮后浏览器跳转到 /login。

原因：aip_token 过期/被清，后端返回 401，client.js 响应拦截器清除 token 并重定向。

排查步骤：

1. 重新登录获取新 token。
2. 若频繁 401，检查系统时间（JWT 过期判定依赖时钟）、SECRET_KEY 是否稳定（SECRET_KEY 过弱/变化会导致 Token 立即过期）。
3. 检查是否误用其它产品前缀（如 /aip-api 打 18081），路径不匹配时可能 404 而非 401。

8.6 列表加载失败提示「加载对象列表失败」

现象：页面顶部 alert 红条显示「加载对象列表失败：<详情>」。

原因：GET /ontology/objects 请求失败（后端未启动、代理未分流、网络超时 30s）。

排查步骤：

1. 确认 Foundry 后端已启动且端口 18081 未被占用。
2. 确认 Vite 代理将 /api 分流到 18081。
3. 打开 Network 看具体状态码：404 多为代理分流问题；超时多为后端未响应；500 看后端日志。

9. 已知缺陷与边界

注：动作「新增/编辑」能力已于 2026-09-07 补齐（动作 Tab 弹窗支持 param_schema/validation_rules/write_back_config/idempotency_key_field/requires_approval，编辑走 PUT /ontology/actions/:id；创建对象动作行同步补齐）。动作删除为硬删、删除后名字可复用，补配置请在动作 Tab 点「编辑」——整库 YAML 导入对已存在同名对象按 skipped 跳过，属防误覆盖保护。

注：属性保存遇进行中 draft 时的冲突已于 2026-09-06 修复（存在 draft 则复用并覆盖更新、存在 review 则友好提示先合入/回滚，不再无条件新建草稿）。

注：影响分析弹窗只读问题已于 2026-09-06 修复（合入前先弹影响分析，需在弹窗底部点「确认」后才真正执行合入）。

注：deprecated 对象仍在列表展示的问题已于 2026-09-06 修复（对象列表过滤 status=deprecated，不再展示可点但无法正常操作的对象）。

注：对象类型列表的分页/搜索缺口已于 2026-09-13 补齐（前端分页 + 关键字过滤 + 每页条数/翻页/计数，默认每页 20）。边界：列表接口无服务端分页参数，仍为一次全量拉取，前端分页只降低渲染开销、不减少网络传输量（详见 4.4 与第 9 章）。

注：对象级高级字段与 ValueType 联动约束缺口已于 2026-09-13 补齐——创建表单新增「多列主键 pk_columns」「实现接口 implements_interfaces」（选项来自 GET /ontology/interfaces）、「附加数据源 supplementary_sources」（附加行：数据源 ID / 补充表名 / 关联条件）；创建属性行与属性 Tab 新增「共享属性引用 shared_property_id」（选项来自 GET /ontology/shared-properties）与按类型联动的「单位 unit」「小数位 precision」；详情 meta 行展示 pk_columns/implements_interfaces/附加数据源个数，属性表类型列展示约束摘要。边界：supplementary_sources 后端请求体已支持（service_impl.go:205）但为 JSON 透传存储，Go 侧不校验形状与 ≤3（形状取自设计约定 design_foundry.md:203）；precision 后端未做强校验。

后端文件

• 路由注册：action/products/foundry/server/server.go（protected 分组 /ontology/* 路由）
• HTTP handler：action/products/foundry/server/ontology_handlers.go
• 版本状态机：action/products/foundry/ontology/version.go
• 影响分析：action/products/foundry/ontology/impact.go
• 数据模型与输入结构：action/products/foundry/ontology/models.go、ontology/service_impl.go
• ValueType：action/products/foundry/ontology/valuetype.go、server/valuetype_handlers.go
• 统一错误码：action/platform/ierr/errors.go

项目文档

• V5 升级计划与批次规格：action/wiki/upgrade-v5/UPGRADE-PLAN.md（Batch 7 / B7-1）
• 实施故事：action/wiki/upgrade-v5/dev-story/stage-5.md（§2.1 ValueType 13 类冻结）、stage-6.md（收官）
• 变更记录：action/wiki/changelog/2026-08-30-6-v5-stage5.md、2026-08-30-7-v5-stage6.md
• 前端索引：action/wiki/frontend-intro-v5/markdown/index.md、html/index.html
• 版本/升级设计文档：action/wiki/ 下 Foundry 相关 design 文档（design_foundry 章节涉及版本状态机/审批/影响分析契约）

相邻页面链接

• versions.html — 版本历史：对象版本列表、回溯与回滚
• yaml.html — YAML 导入导出：对象声明式导入导出
• action-tester.html — Action 测试：Action 写路径参数与执行
• metrics.html — 指标管理：指标语义层定义与派生
• pipelines.html — 管道构建：数据处理管道
• datasets.html — 数据集：数据集管理/上传/版本/发布
• sync.html — 数据同步：同步目标、立即运行与任务轮询
• sql-workbench.html — SQL 工作台：NLQ 翻译、SQL 执行、RLS/CLS 回显
• data-sources.html — 数据源：连接与元数据导入
• lineage.html — 数据血缘：表/字段级血缘
• quality.html — 数据质量：质量画像与评分
• semantic-search.html — 语义检索：对象语义检索
• object-query.html — 对象查询：OOL 查询与导出
• audit.html — 审计管理：Foundry 审计日志
• dashboards.html — 可视化仪表盘：ECharts 图表与权限
• governance.html — 数据治理：治理规则与任务
• mlops.html — MLOps 模型：模型注册与推理
• apps.html — 应用构建：低代码应用组装
• workflows.html — 工作流：Foundry 工作流编排
• api-keys.html — API Key：Foundry API Key 与 scope
• notebook.html — Notebook 分析：markdown/sql/chart 单元格
• reports.html — 智能报表：报表定义/运行/派发
• fusion.html — 实体消解：Fusion 实体合并确认
• stream.html — 流事件规则：CDC 事件化与投递
• functions.html — 函数注册：OntologyFunction 表达式函数
• markings.html — 数据打标：密级打标、绑定与授权矩阵
• ontology-export.html — 本体导出：OWL/SHACL/TTL 导出
• marketplace.html — 商品市场：对象/指标等发布与安装
• coderepo.html — 代码仓库：SQL 宏仓库与宏解析