实体解析

1. 页面概览

实体解析页（/gotham/resolution）解决多源数据的实体消解与合并（TAD-03）：选择实体类型与参与数据源创建解析作业，后台比对生成匹配对、实体簇，支持确定性/规则/模糊/AI 四层打分；作业运行后以退避轮询（1.5s 起、每次 ×1.5、封顶 10s，总上限 5 分钟，超限可「继续轮询」）直至终态。另含「人工审核」标签页，对低置信度匹配对并排对比后「确认合并/拒绝」。一句话总结：本页把各数据源的重复实体自动消解合并，并以人工兜底保证图质量。

2. 访问入口

2.1 路由与菜单

path /gotham/resolution、name GothamResolution、title Gotham 实体解析，挂在父路由 /gotham（GothamLayout）下，侧边栏菜单项「实体解析」。源码 action/web/src/views/GothamResolutionPage.vue。

2.2 认证与权限

子路由 meta requiresAuth: true；请求经 gothamClient.js 附带 aip_token，401 用 gotham_refresh_token 换新。

2.3 端口与 API 前缀

Gotham 后端 18083，前缀 /gotham-api（baseURL /gotham-api/v1，Vite 代理重写为 /api/v1）。

3. 界面布局

Gotham 实体解析作业                    [刷新]
[标签页：作业管理 | 人工审核]
创建解析作业：名称 * / 实体类型 *(datalist person|org|ship|incident|asset)
             / 描述 / AI 层 enable_ai 勾选 / 参与数据源 source_ids 勾选
             [创建并运行]
解析作业列表（ID/名称/实体类型/状态/候选实体/匹配对/自动合并/创建时间/操作）
作业详情面板：基础信息行 + 统计卡（候选实体/匹配对/自动合并/待审核/已拒绝/AI 裁决/实体簇）
实体簇列表（ID/代表实体/状态/相似度/成员 entity_ids）
匹配对列表（状态过滤下拉：全部/auto_merged/review/rejected/ai_reviewed）
[人工审核页] 待审核匹配对卡片：实体 A/B 并排属性 + 匹配依据 + 审核理由
             [确认合并][拒绝]

• 作业管理页：创建表单 + 作业列表 + 展开的详情面板（统计卡/实体簇/匹配对）。
• 人工审核页：逐条卡片展示匹配对两侧实体属性（来自融合实体表），供人工裁决。

4. 交互元素

5. 后端关联

端点表（源码 action/products/gotham/server/server.go，处理器 handlers_ingestion.go 与 resolution 域）：

• 作业生命周期：pending → running → completed/failed/partially_completed。以退避轮询查询 GET /resolution/jobs/:id：延迟 1.5s 起、每次 ×1.5、封顶 10s，总上限 5 分钟，命中终态停止并刷新详情与列表；到上限暂停并露出「继续轮询」按钮（对齐 FusionPage.vue 既有实现），组件卸载时清理定时器。
• 四层匹配：匹配对带 layer（deterministic/rule/fuzzy/ai）；enable_ai 开启时 fuzzy 层灰区由 LLM 裁决，状态 ai_reviewed；人工待审对状态 review。
• 人工合并：确认合并把实体 B 吸收进代表实体并写图（confirm 返回 {confirmed:true,pair_id}）；拒绝仅记录决策；审核理由随请求提交，留审计线索。
• 详情数据：stats/clusters/pairs 用 Promise.allSettled 并行加载；实体属性经 GET /ingestion/entities 分页拉取（limit+offset，每页 500、最多 10 页 = 5000 条；覆盖审核对引用实体即提前结束）构建 entityMap 供并排展示，命中页数上限时提示「更靠后实体属性可能未加载」。

6. 权限与安全

• 页面全部接口受 JWT 保护，无公开端点。
• 创建/运行/审核均为写操作，前端二次确认（confirm 弹窗）后才发出请求。
• 确认合并/拒绝经 ABAC PEP 写门（resolution.review + execute:write），deny 策略命中返回 403。
• 合并结果写入图数据库，属于结构性变更；审核理由落库便于追溯。

7. 常见问题与排错

1. 作业轮询达 5 分钟上限仍未完成：提示「轮询已达 5 分钟上限，作业可能仍在运行」，状态行出现「继续轮询」按钮；原因是候选实体量大或 LLM 裁决慢（退避轮询：1.5s 起、×1.5、封顶 10s）；处理：点「继续轮询」续一轮（重置 5 分钟窗口），或点「刷新」/查看作业列表，终态后开详情。
2. 人工审核页为空：「待审核匹配对」无数据；原因是没有 review 状态的匹配对（作业未运行或全部处理完）；处理：先在「作业管理」运行解析作业；低置信度对会自动进入 review。
3. 审核卡片提示「实体信息未加载」：实体 A/B 属性区显示 id=xxx 未加载；原因是该实体不在 /ingestion/entities 已分页拉取范围（最多 10 页 × 500 = 5000 条）内，或已被合并删除；处理：确认数据源已运行、实体已入表；标题显示「已加载融合实体 N 条」，若提示「分页拉取已达上限」则属页数上限，可缩小数据源范围或按后端能力提高前端页数上限。
4. 创建作业后无「参与数据源」可选：source_ids 区提示先创建并运行数据源；原因是 /ingestion/sources 为空或全部未运行；处理：到「Gotham 多源接入」页创建数据源并运行，生成融合实体后再回本页。

8. 已知缺陷与边界

注：审核「拆分」入口已于 2026-09-06 修复（补齐拆分按钮，提交 entity_id/reason 调后端 split 接口）。