版本历史（Version History）

1. 页面概览

1.1 是什么

「版本历史」页面是 LightFoundry 本体工作台（Foundry）中负责对象类型版本管理的页面。Foundry 的本体对象（如 customer、order、product）并不是"改一次就立刻生效"的扁平定义，而是遵循一条 draft（草稿）→ review（评审中）→ merged（已合入） 的版本状态机演进。每次正式修改都会生成一个新的版本记录，页面以垂直时间线的形式展示某个对象类型的全部历史版本，并在每个版本旁按状态渲染对应的操作按钮。

本页面的源码位于 action/web/src/views/VersionHistoryPage.vue，共约 380 行，属于典型的"单页 + 列表 + 弹窗"结构：顶部一个「选择对象类型」下拉框，选中后下方渲染该对象的版本时间线；时间线每条目按版本状态（draft / review / merged）显示不同的可用操作；所有需要展示的后端分析结果（合并前影响分析、合并后影响、回滚影响）统一在「影响分析弹窗」中呈现。

页面顶部注释块概括了三件事：选择对象 → 版本时间线；对 draft 执行 review（提交评审）、对 review 版本合入前调用 /impact 接口做影响分析；对历史 merged 版本执行 rollback（回滚）。这决定了本页面是 Foundry 版本治理的"操作台"：它不负责创建/编辑对象定义（那是「本体工作台」与草稿编辑入口的事），而是负责推动版本状态流转、审批把关、合入与回滚。

1.2 核心价值

1.3 一句话总结

2. 访问入口

2.1 路由与菜单

访问方式：登录后在 Foundry 左侧菜单点击「版本历史」，或直接访问 /foundry/versions。路由注册于 Foundry 布局的子路由下，因此必须先进入 /foundry 布局，URL 才能被正确匹配；直接访问完整路径同样有效。

2.2 认证与权限

• 路由 meta.requiresAuth: true，未登录访问会被路由守卫拦截跳转登录页。
• API 认证使用 aip_token（localStorage），由 action/web/src/api/client.js 请求拦截器自动附加 Authorization: Bearer <aip_token>。
• 页面本身不区分角色，但每个后端操作（评审/合入/审批/回滚）都会以当前登录用户身份写入版本记录的 created_by 或审批记录的 approver_id，属于审计级权限而非功能级权限；审批环节另有自批拦截与票数门禁（见第 7 章）。
• 若 token 过期或失效，客户端拦截器会清理 aip_token/aip_username 并跳转 /login；遇到"页面白屏/跳登录"时可先检查浏览器 localStorage 中 aip_token 是否存在。

2.3 端口与 API 前缀

• Foundry 后端端口：18081；前端开发服务器（Vite）通过 /api 前缀把请求代理到该后端。
• API 基础前缀：/api/v1（见 action/web/src/api/client.js 中 baseURL: '/api/v1'）。
• 本页所有请求都落在 /api/v1/ontology/... 下，属于 Foundry 本体域。

3. 界面布局

本页布局为纵向卡片流，文字框图如下：

┌─────────────────────────────────────────────────────┐
│  版本历史                                             │
│  ┌─────────────────────────────────────────────────┐ │
│  │ [alert 提示条（出现时展示，右上角"关闭"）]          │ │
│  └─────────────────────────────────────────────────┘ │
│  ┌─────────────────────────────────────────────────┐ │
│  │ 选择对象类型  [下拉框：对象名（v版本 · 状态）]      │ │
│  └─────────────────────────────────────────────────┘ │
│  ┌─ 状态卡片（三选一）───────────────────────────────┐ │
│  │ A. 加载中...（loading=true）                     │ │
│  │ B. 该对象暂无版本记录。（versions 为空）           │ │
│  │ C. 版本时间线（timeline）                        │ │
│  │    ● v3 [merged] base v2 · user · 2026-08-30    │ │
│  │      [回滚到此版本]                              │ │
│  │    ● v2 [review]  base v1 · user · 2026-08-30   │ │
│  │      [合入] [通过] [驳回]                         │ │
│  │    ● v1 [draft]   base - · system · 2026-08-30  │ │
│  │      [提交评审]                                  │ │
│  └─────────────────────────────────────────────────┘ │
│  ┌─ 影响分析弹窗（impactModal.visible 时全屏蒙层）───┐ │
│  │  标题 + 关闭  │  <pre> 影响分析 JSON </pre>      │ │
│  └─────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘

4. 交互元素详解

4.1 选择对象类型下拉框

下拉选项数据来自 GET /ontology/objects，取响应的 data.data 数组，每个元素含 object_type 对象（含 id、name、version、status）。

4.2 提交评审（draft 专属）

4.3 合入（review 专属）

4.4 通过 / 驳回（review 且带审批策略时显示）

4.5 回滚到此版本（merged 专属）

4.6 影响分析弹窗与 Alert 提示条

5. 后端关联

5.1 API 客户端

5.2 端点表

注：:id 支持数字内部 id，也支持 api_name / rid（object-type:<name> 前缀会被剥离后按 name 查询），见服务端 resolveObjectID。

5.3 响应结构

所有成功响应统一封装为 {code: 0, data: ...}（okData）；失败响应为 {code, error, ...}。

版本历史列表（GET /ontology/objects/:id/versions）的 data 为数组，元素为：

{
  "id": 7,
  "version": 3,
  "status": "merged",
  "base_version": 2,
  "created_by": "admin",
  "created_at": "2026-08-30T10:00:00Z",
  "approval_policy": { "min_approvals": 1, "self_approval": false }
}

影响分析报告（POST /ontology/objects/:id/impact、merge、rollback 的 data.impact）结构：

{
  "object_type_id": 2,
  "object_type_name": "order",
  "impacts": [
    { "type": "link", "id": "5", "name": "customer_orders", "detail": "link \"customer_orders\" (1 → 2)source 引用" },
    { "type": "action", "id": "9", "name": "update_order_status", "detail": "action \"update_order_status\" belongs to object type" },
    { "type": "edit", "id": "2", "name": "order", "detail": "1 条进行中的编辑记录（ontology_edits）" }
  ]
}

影响项 type 取值：link / action / pipeline / lineage / metric / report / edit；detail 中会出现"source 引用"、"target 引用"、"表未就绪"等后缀说明。

5.4 关联模块表

5.5 关键机制

版本状态机（draft → review → merged）

聚合真冲突判定

merge 时聚合 (base_version, latest] 区间所有 merged 版本的 change_diff，与草稿 diff 按 (kind, api_name) 求交，op ∈ {modify, delete} 即冲突；落后但无真冲突时允许"非冲突自动合并"（不再"落后即拒绝"）。

审批门禁

approve 数 ≥ min_approvals 才允许 merge（不足返回 APPROVAL_REQUIRED）；self_approval=false 时禁止版本创建人给自己批准（返回 APPROVAL_DENIED）。

回滚语义

target_version 必须为正整数且目标版本为 merged；回滚重建主表并生成一个新版本，返回影响分析报告，便于回滚后评估影响面。

6. 核心流程详解

6.1 主流程：查看版本时间线

1. 页面挂载时执行 fetchObjects()，请求 GET /ontology/objects，把返回的对象类型列表填充进下拉框。
2. 用户在「选择对象类型」下拉中选择一个对象，触发 handleSelectObject()：
   • loading=true，渲染"加载中..."卡片；
   • 请求 GET /ontology/objects/:id/versions；
   • 成功把 data.data 写入 versions，loading=false，渲染时间线；失败 alert「加载版本失败：<错误信息>」。切换对象时页码复位为第 1 页。
   • 版本数组为一次全量返回（后端无 limit/offset、无 total），时间线之上按 pageSize（10/20/50，默认 20）做渲染层分页：pagedVersions = versions.slice((page-1)*pageSize, page*pageSize)，合入/回滚刷新后页码自动钳制回合法范围。
3. 若该对象没有任何版本记录，显示"该对象暂无版本记录。"。

时间线每条目渲染：版本号 v{n}（加粗）、状态徽标 status-badge（按状态着色）、元信息 base v{base_version || '-'} · {created_by || 'system'} · {formatTime(created_at)}。formatTime 把 ISO 时间串的 T 替换为空格并截取前 19 位。

6.2 分支流程：评审与合入

• 提交评审：draft 版本点击「提交评审」→ POST /ontology/drafts/:vid/review → 成功 alert「版本 v{n} 已提交评审」→ refreshVersions() 重新拉取列表 → 该版本变为 review 状态；若带审批策略，时间线上出现「通过」「驳回」。
• 审批通过：「通过」→ prompt 意见 → confirm → POST /ontology/objects/:id/versions/:vid/approve（body {comment}）→ alert「版本 v{n} 已通过审批」→ 刷新；状态仍为 review。
• 审批驳回：「驳回」→ prompt 意见 → confirm → POST .../reject → alert「版本 v{n} 已驳回，退回草稿」→ 刷新；状态退回 draft。
• 合入：「合入」→ 先 POST /ontology/objects/:id/impact 弹出「合并前影响分析（对象引用清单）」→ 再 POST /ontology/drafts/:vid/merge → 成功弹出「合入结果（影响分析）」并 alert「版本 v{n} 已合入」→ 刷新。合入失败（如审批票数不足 409）alert「合入失败：<错误信息>」。

6.3 分支流程：回滚

1. merged 版本点击「回滚到此版本」→ confirm「确定回滚到 v{n} 吗？将重建主表并生成新版本。」
2. POST /ontology/objects/:id/rollback，body {target_version: v.version}。
3. 成功 alert「回滚成功」并弹出「回滚结果（影响分析）」；随后刷新版本列表，可在时间线顶部看到新生成的 merged 版本。

6.4 状态机终态语义

7. 权限与安全

• 认证：全部请求依赖 aip_token Bearer 认证；后端在 protected 路由组挂载 /ontology/...。
• 身份注入：后端 currentUserID / currentUsername 从 gin 上下文取当前登录用户，注入到版本记录的 created_by、审批记录的 approver_id、merge/rollback 的 requestedBy；上下文缺失时 user_id 回退为 "anonymous"。
• 审批安全（P0-5）：
  • 自批拦截：approval_policy.self_approval=false 时版本创建人不能给自己的版本批准；
  • 票数门禁：min_approvals 不足时 merge 被 APPROVAL_REQUIRED 拒绝；
  • 状态机守卫：所有非法状态转移（draft 直接 merge、merged 再 merge、回滚非 merged 目标等）返回 INVALID_VERSION_STATE（HTTP 409），不产生副作用。
• 写操作防护：评审/合入/审批/回滚均为 POST（非幂等语义），前端以 busy 置灰 + confirm 二次确认防护；回滚前强制确认文案提示"将重建主表"。
• 审计：每次状态流转以当前用户身份落库（版本记录的 created_by、审批记录 decision/approver），形成可追溯链。

8. 常见问题与排错

9. 已知缺陷与边界

注：影响分析弹窗互相覆盖问题已于 2026-09-06 修复（合入改为先弹影响分析、经用户确认后才真正执行 merge；合入结果以只读弹窗在确认后另屏展示，不再与确认弹窗互相覆盖）。