数据治理

1. 页面概览

1.1 是什么

数据治理页面（路由 /foundry/governance）是 LightFoundry 承载"元数据治理三件套"的操作台：术语表、数据分类、保留策略。它把散落在各处的治理动作集中到一个三 Tab 页面：Tab1 管理业务术语并对接本体属性（对象类型 → 属性级联下拉，把术语与具体字段绑定）；Tab2 管理数据分类标签（敏感等级 0~3）并把标签打到本体属性上，同时提供属性治理汇总查询（一个属性关联了哪些术语、被打了哪些标签）；Tab3 管理保留策略（按目标类型 + 目标 ID 配置保留天数与到期动作，并可启用/停用）。

页面对应的设计文档是 TAD-12 数据治理，后端实现分布在 action/products/foundry/governance 包与 action/products/foundry/server/governance_handlers.go。与同一产品下的 MarkingPage（密级打标，第二道列级闸门）不同，本页治理的对象是术语字典与分类标签，目标是让业务字段"说人话、有分级、可回收"。

1.2 核心价值

1.3 一句话总结

数据治理页把"术语字典、分类打标、保留策略"三大治理动作收进一个三 Tab 页面，让字段级治理从"记录"走向"可关联、可分级、可回收"。

2. 访问入口

2.1 路由与菜单

侧边栏菜单注册项为 { path: '/foundry/governance', label: '数据治理' }。页面头部标题「数据治理」旁展示副标题「术语表 / 数据分类 / 保留策略」。

2.2 认证与权限

• meta requiresAuth: true，未登录由路由守卫拦到登录页；
• 请求经 action/web/src/api/client.js：baseURL /api/v1、超时 30s、Authorization: Bearer <aip_token>、401 清除 Token 并跳 /login；
• 后端治理路由全部挂在 protected 组（见 server.go 1080-1104 行）；
• 页面无独立角色门槛，鉴权依赖平台 Token；治理数据（术语/分类/策略）为全局共享，未做按行 RLS 过滤。

2.3 端口与 API 前缀

Foundry 后端端口 18081，API 前缀 /api（请求路径带 /v1，如 /api/v1/governance/glossary）。开发环境 Vite 代理转发。

3. 界面布局

+---------------------------------------------------------------------+
| 数据治理                    术语表 / 数据分类 / 保留策略                |
+---------------------------------------------------------------------+
| [操作结果提示 alert（可关闭）]                                         |
+---------------------------------------------------------------------+
| Tab 栏：[术语表] [数据分类] [保留策略]                                 |
+---------------------------------------------------------------------+
| Tab1 术语表：                                                         |
|   card「术语表」：[+ 新建术语|收起表单]                                 |
|     创建表单：术语名称*/缩写/分类/状态(draft|approved|deprecated)       |
|               定义/同义词(逗号分隔)/负责人OwnerID + [创建术语][取消]     |
|     术语表格：ID|名称|缩写|分类|状态|负责人|关联属性|操作                 |
|       行内展开：关联本体属性（对象类型→属性级联 + 关联）                 |
|                  已关联属性表（对象类型|属性|数据类型|取消关联）          |
+---------------------------------------------------------------------+
| Tab2 数据分类：                                                       |
|   card「分类标签管理」：[+ 新建分类|收起表单]                            |
|     创建表单：分类名称*/敏感等级level*(0公开|1内部|2机密|3绝密)          |
|               颜色/描述 + [创建分类][取消]                              |
|     分类表格：ID|名称|等级|颜色|描述|操作(删除)                          |
|   card「属性打标签 / 属性治理查询」：                                    |
|     对象类型→属性→分类标签 三下拉 + [打标签][查询治理]                   |
|     结果：属性「object.property」（data_type）                          |
|       左：关联术语（名称|缩写|状态）  右：分类标签（分类|等级|打标人|移除）|
+---------------------------------------------------------------------+
| Tab3 保留策略：                                                       |
|   card「保留策略」：[+ 新建策略|收起表单]                                |
|     创建表单：策略名称*/目标类型target_type*(datasource|pipeline_output  |
|                |query_cache|audit_log) 目标ID(0=全部)/保留天数*/动作*    |
|               (delete|archive|anonymize) + [创建后即启用]              |
|               + [创建策略][取消]                                       |
|     策略表格：ID|名称|目标类型|目标ID|保留天数|动作|状态|操作(停用/启用,删除) |
+---------------------------------------------------------------------+

各板块职责：

• Tab 栏：三个 Tab 按钮（术语表/数据分类/保留策略），activeTab 驱动分区渲染，切换不重置其他 Tab 的数据。
• Tab1 术语表：新建术语表单 + 术语列表；每行可展开"关联属性"面板（对象类型 → 属性级联下拉），查看/取消已关联属性。术语删除会级联移除属性关联。
• Tab2 数据分类：分类标签管理（创建/删除）+ 属性打标签与治理查询；分类删除会级联移除属性上的标签。
• Tab3 保留策略：创建策略表单 + 策略列表（启用/停用/删除）。

4. 交互元素详解

4.1 Tab 栏

4.2 Tab1 术语表 —— 创建表单

4.3 Tab1 术语表 —— 列表与关联面板

4.4 Tab2 数据分类 —— 分类标签管理

4.5 Tab2 数据分类 —— 属性打标签与治理查询

4.6 Tab3 保留策略 —— 创建表单

4.7 Tab3 保留策略 —— 策略列表

5. 后端关联

5.1 API 客户端

页面使用 action/web/src/api/client.js 默认导出 apiClient：baseURL /api/v1、timeout 30000、JSON 头、Authorization: Bearer <aip_token>、401 清 Token 跳登录。治理请求全部走该实例，路径写 /governance/...、/ontology/...。

5.2 端点表

5.3 响应结构

统一成功包裹 {"code": 0, "data": ...}；错误 {"code", "error"}。

术语列表响应 data（数组元素）：

{
  "id": 1,
  "name": "客户生命周期价值",
  "abbreviation": "CLV",
  "definition": "客户在生命周期内贡献的价值",
  "category": "customer",
  "synonyms": ["LTV", "客户终身价值"],
  "owner_id": "alice",
  "status": "approved"
}

术语关联属性响应 data（数组元素）：

{
  "id": 21,
  "object_name": "customer",
  "object_type_id": 3,
  "property_name": "clv",
  "property_display": "客户生命周期价值",
  "data_type": "number"
}

属性治理汇总（GET /governance/properties/:objId/:propId）响应 data：

{
  "object_name": "customer",
  "property_name": "clv",
  "data_type": "number",
  "terms": [{ "term_id": 1, "name": "客户生命周期价值", "abbreviation": "CLV", "status": "approved" }],
  "classifications": [
    { "id": 31, "classification_name": "财务敏感", "level": 2, "applied_by": "alice", "applied_at": "..." }
  ]
}

保留策略列表响应 data（数组元素）：

{
  "id": 1,
  "name": "审计日志保留 90 天",
  "target_type": "audit_log",
  "target_id": 0,
  "retention_days": 90,
  "action": "delete",
  "is_enabled": true
}

5.4 关联模块表

5.5 关键机制

• 级联下拉 + 属性缓存：术语关联面板与打标签面板共用对象类型/属性级联逻辑；fetchProps 带 objPropsCache（objID → 属性数组）缓存，同一对象重复选中不重复请求。
• 同义词解析：前端把同义词输入按 , 与 ， 拆分过滤空串后提交为数组；后端 synonyms 为 JSON 数组，读取时 synonymsArray 兼容数组/JSON 字符串两种形态。
• 分类等级语义：level 0~3 对应公开/内部/机密/绝密，前端 levelText 映射展示；分类标签可被"移除"（按关联记录 id 删除，不删除分类定义）。
• 保留策略动作：action 取值 delete/archive/anonymize，分别对应到期删除、归档、匿名化；target_id=0 表示作用于该类型全部目标。
• 启用/停用语义：前端切换用 PUT /governance/retention-policies/:id 携带完整策略字段、仅翻转 is_enabled；状态由 status-enabled/status-disabled 徽章展示。
• 级联删除：删除术语级联移除术语-属性关联；删除分类级联移除属性上的标签；前端均以 confirm 二次确认提示级联影响。

6. 核心流程详解

6.1 页面加载

onMounted 并行拉取四类数据：fetchTerms（GET /governance/glossary）、fetchClasses（GET /governance/classifications）、fetchPolicies（GET /governance/retention-policies）、fetchObjectTypes（GET /ontology/objects）。各自失败独立 alert，互不影响。

6.2 术语治理主流程

1. 点「+ 新建术语」展开表单，填写名称（必填）、缩写、分类、状态、定义、同义词、负责人。
2. 点「创建术语」→ POST /governance/glossary → 成功提示并重置表单、刷新列表。
3. 术语行「编辑」→ startEditTerm(t) 回填表单（同义词数组渲染为逗号文本）并置 editingTermId，表单头部提示「正在编辑术语 id=...」；点「保存修改」→ PUT /governance/glossary/:id。后端 UpdateGlossaryTerm 为全字段语义：name 必填、重名冲突校验，abbreviation/definition/category/synonyms/owner_id 整体覆盖，status 非空才更新；故前端提交携带全部表单字段。
4. 在术语行点「关联属性」展开面板：先选对象类型（触发加载属性），再选属性，点「关联」→ POST /governance/glossary/:id/link → 成功提示并刷新已关联列表。
5. 已关联属性可点「取消关联」→ DELETE /governance/glossary-links/:linkId。
6. 术语可「删除」（级联移除关联），确认框明示级联影响。点「取消」退出编辑态并清空表单。

6.3 数据分类与打标主流程

1. 点「+ 新建分类」展开表单，填名称（必填）、等级、颜色、描述 → 「创建分类」→ POST /governance/classifications。
2. 分类行「编辑」→ startEditClass(c) 回填表单并置 editingClassId，表单头部提示「正在编辑分类 id=...」；「保存修改」→ PUT /governance/classifications/:id。后端 UpdateClassification 为全字段语义：name 必填、level 取值 0-3、重名校验，description/color 整体覆盖；前端提交前做同样校验。
3. 在"属性打标签 / 属性治理查询"区：选对象类型 → 选属性 → 选分类标签 → 「打标签」→ POST /governance/properties/:objId/:propId/classify → 成功提示并自动执行治理查询。
4. 「查询治理」→ GET /governance/properties/:objId/:propId → 汇总区展示关联术语（左）与分类标签（右）。
5. 标签行「移除」→ DELETE /governance/property-classifications/:pcId → 重新查询刷新。
6. 分类可「删除」（级联移除属性上的标签）。点「取消」退出编辑态并清空表单。

6.4 保留策略主流程

1. 点「+ 新建策略」展开表单，填名称（必填）、目标类型、目标 ID（0=全部）、保留天数（必填，>0 校验）、动作、是否勾选"创建后即启用"。
2. 「创建策略」→ 前端校验"保留天数必须大于 0" → POST /governance/retention-policies → 成功提示并重置表单、刷新列表。
3. 策略行「编辑」→ startEditPolicy(p) 回填全部字段（含 is_enabled）并置 editingPolicyId，表单头部提示「正在编辑策略 id=...」，勾选框文案变为「启用该策略」；「保存修改」→ PUT /governance/retention-policies/:id。后端 UpdateRetentionPolicy 要求 name 必填、target_type/action 取值合法、retention_days>0，is_enabled 为 *bool（显式传值即覆盖）；前端提交前做同样校验。
4. 列表行点「停用/启用」→ PUT /governance/retention-policies/:id（翻转 is_enabled）→ 提示"策略"xx"已停用/启用"。
5. 列表行点「删除」→ confirm → DELETE /governance/retention-policies/:id。点「取消」退出编辑态并清空表单。

6.5 状态与终态语义

• 术语状态：draft（草稿）→ approved（已批准）→ deprecated（已废弃），创建/编辑时可选，本页不做独立状态流转操作。
• 编辑语义（全字段覆盖）：术语/分类的更新为全字段替换——未在表单呈现的字段会被后端按整体覆盖语义处理，故编辑表单回填全部可编辑字段后再提交，不依赖"未传保持不变"；保留策略的 is_enabled 例外，为 *bool 显式传值才覆盖。
• 策略启停：is_enabled 布尔量即终态；停用后策略不再生效（后端策略执行器按启用态过滤），启停可反复切换。
• 打标签幂等性：同一属性重复打同一分类会被后端去重或报唯一冲突，前端在打标后自动刷新汇总。
• 数据一致性：删除术语/分类均级联清理关联，避免悬挂引用；前端 confirm 文案明示级联行为。

7. 权限与安全

• 认证：aip_token Bearer，401 跳登录；路由 requiresAuth。
• 数据级安全：治理数据（术语/分类/策略）全局共享，无按行 RLS；但关联对象/属性来自 GET /ontology/objects，属性下拉数据源受本体可见性约束。
• 敏感信息分级：分类标签的 level（0~3）即敏感分级信号，后续可被 CLS/打标（Marking）体系引用，为列级访问控制提供治理依据——本页是"贴标签"的入口，强制执行在查询链路的第二道闸门。
• 写操作防护：删除术语、删除分类、取消关联、移除标签、删除策略均有 window.confirm 二次确认；创建/打标等写操作在 busy 期间禁用按钮防重复提交。
• 级联副作用明示：删除提示文案明确"关联属性将一并移除""属性上的标签将一并移除"，避免误删。

8. 常见问题与排错

问题 1：关联属性面板的对象类型/属性下拉为空

• 现象：展开「关联属性」后，对象类型下拉无选项，或选了对象类型后属性下拉为空。
• 原因：对象类型来自 GET /ontology/objects，属性来自 GET /ontology/objects/:id；请求失败或对象无属性都会导致空。
• 排查步骤：
• 1. 看 Network 中 GET /ontology/objects 是否成功（401/404/500 各有对应处理）；
• 2. 选中对象类型后看 GET /ontology/objects/:id 是否返回 properties 数组；
• 3. 若属性为空但对象确有属性，确认选择的对象类型 id 与后端返回一致（fetchObjectTypes 做了 x.object_type || x 归一化）。

问题 2：创建术语/分类/策略提示失败

• 现象：提交后红色 alert"xx 创建失败：..."。
• 原因：多为必填校验或唯一约束冲突（术语 name 有 uniqueIndex；分类名重复、等级越界；策略保留天数 <=0 等）。
• 排查步骤：
• 1. 阅读 alert 中的后端 error 详情（如"术语名称已存在"）；
• 2. 术语创建校验：名称必填；同义词按 ,/， 拆分后过滤空串，无需手填分隔符；
• 3. 策略创建校验：保留天数 > 0（前端已拦"保留天数必须大于 0"）；目标类型/动作取值须在枚举内（datasource/pipeline_output/query_cache/audit_log；delete/archive/anonymize）。

问题 3：打标签后治理汇总里看不到标签

• 现象：「打标签」提示成功，但「查询治理」结果里分类标签区为空。
• 原因：打标成功后前端自动 handleQueryGovernance，但若查询失败或 property_id 被重置会导致看不到。
• 排查步骤：
• 1. 确认打标请求 POST /governance/properties/:objId/:propId/classify 响应成功（200/201）；
• 2. 手动再点「查询治理」，确认 GET /governance/properties/:objId/:propId 响应 data.classifications 非空；
• 3. 若打标失败，查看后端是否因 applied_by 解析（currentUsername 兜底 currentUserID）或唯一约束报错。

问题 4：策略启停不生效

• 现象：点「停用」后提示成功，但列表状态没变或策略仍在执行。
• 原因：PUT /governance/retention-policies/:id 要求携带完整字段（name/target_type/target_id/retention_days/action/is_enabled）；若前端传参缺失会被后端校验拒绝；或启停只是元数据切换，调度器按自身节奏读取。
• 排查步骤：
• 1. 查看 Network 中 PUT 请求体是否含全部策略字段且 is_enabled 已翻转；
• 2. 查看返回错误详情并修正参数；
• 3. 若状态已切换但执行未停，属后端调度器读取时机问题，非本页问题，查看保留策略执行器配置。

问题 5：删除术语/分类后出现"孤儿"引用

• 现象：删除术语/分类后，某属性仍显示已删除项的引用。
• 原因：删除接口后端应级联清理关联，但若删除发生在关联面板未刷新时，前端缓存（linkedProps/objPropsCache）可能残留。
• 排查步骤：
• 1. 删除后确认请求 DELETE /governance/glossary/:id 或 DELETE /governance/classifications/:id 成功；
• 2. 前端已 delete linkedProps.value[t.id] 清理缓存，确认当前页未残留旧行；
• 3. 若跨页面看到残留，属其他页面缓存，刷新页面后重新查询验证。

9. 已知缺陷与边界

注：关联面板缓存不过期问题已于 2026-09-06 修复（objPropsCache 属性缓存带 30s TTL，过期自动失效并重新拉取，无需整页刷新）。