实体消解（Fusion 实体合并确认）

1. 页面概览

1.1 是什么

「实体消解」页面（页面内标题为 Fusion · 实体消解）是 LightFoundry 提供的重复实体识别与合并确认工作台，V5 Stage 3（B3-3）交付。页面副标题给出了它的完整技术定位：「重复实体识别：规则分桶 + 加权打分 + LLM 复核 + 传递闭包聚类，survivorship 选主写回。」

在企业数据中，同一个真实世界实体（客户、商品、员工……）经常以多条「长相不同」的记录散落在不同来源（CRM、ERP、POS 等）：电话号码相同但姓名写法不同、公司名带不带「有限公司」、地址缩写不一致等。实体消解要回答的核心问题是：这些记录是不是同一个人/同一家公司？如果是，以哪一条为准（选主），并把合并结果写回到本体中去。

页面对标 OpenFoundry 的 fusion-service 的确定性规则部分与 Gotham resolution 的三段式流水线（collectCandidates → scorePair 规则+AI → union-find 聚类），但在 Foundry 内单机闭环实现，不跨服务依赖。整条链路在页面上表现为：项目配置（对象 + key_fields 分桶 + 加权字段 + 阈值 + LLM 复核 + survivorship 选主 + 输出模式）→ 异步运行（轮询 runs）→ 匹配结果表（按簇聚合 + 确认/拒绝人工闭环）。

1.2 核心价值

1.3 一句话总结

2. 访问入口

2.1 路由与菜单

• 路由：/foundry/fusion
• 路由名称：FoundryFusion
• 路由 meta：title: 实体消解，requiresAuth: true，挂在父路由 /foundry（FoundryLayout）下
• 菜单位置：Foundry 左侧边栏「实体消解」（FoundryLayout 菜单项，V5 Stage 3 接线时加入）
• 前端源码：action/web/src/views/FusionPage.vue
• API 客户端：action/web/src/api/fusionApi.js

2.2 认证与权限

• 页面路由挂 requiresAuth: true，未登录访问会被全局路由守卫重定向到 /login（并携带 redirect 参数，登录后回跳）。
• 页面所有数据请求走 fusionApi 实例：请求拦截器自动从 localStorage.getItem('aip_token') 取令牌并以 Authorization: Bearer <token> 附带；响应拦截器遇到 401 时清理 aip_token 与 aip_username，并把页面跳转到 /login。
• 后端所有 /fusion/* 端点挂 protected 语义（authMiddleware 校验 JWT），未带有效令牌一律 401。
• 若登录页反复出现但令牌仍被清空，多半是后端返回 401（令牌过期或 SECRET_KEY 变更），重新登录即可。

2.3 端口与 API 前缀

• Foundry 后端端口：18081（Vite 开发服务器将 /api 前缀代理到该端口）。
• API 前缀：/api/v1（fusionApi 的 baseURL）。
• 完整请求示例：GET /api/v1/fusion/projects、POST /api/v1/fusion/projects/:id/run。

3. 界面布局

页面为「左窄右宽」两栏布局（.fusion-layout，grid 240px + 1fr）：

┌──────────────────────────────────────────────────────────────┐
│ Fusion · 实体消解（页头 + 描述）                                │
│ [alert 操作结果提示条（可关闭）]                                 │
├──────────────┬───────────────────────────────────────────────┤
│ 消解项目（左）│ [未选项目时：从左侧选择或新建一个消解项目开始。]      │
│ [输入框: 新项目名称] [新建]                                     │
│ ┌ 项目1 ┐     │ ① 项目配置（保存按钮）                            │
│ │ 名称   │    │    form-grid：对象类型/key_fields/source_field/  │
│ │ 类型·启用│   │    阈值/LLM 复核线/输出模式/输出数据集/选主策略/    │
│ └───────┘     │    字段来源覆盖 + 打分字段表（+ 添加字段）         │
│ 删除          │ ② 运行（运行消解 / 自动轮询 / 最近一次摘要）        │
│               │ ③ 运行历史（时间/状态/簇/合并/错误）               │
│               │ ④ 匹配结果（状态筛选 + 刷新 / 簇/成员/来源/得分/   │
│               │    依据/状态/操作：确认|拒绝）                     │
└──────────────┴───────────────────────────────────────────────┘

各板块职责：

• 消解项目（左栏卡片）：新建、选择、删除消解项目；当前项目高亮。每个项目一行显示 name、object_type · 启用/停用，右侧是「删除」链接按钮。
• 项目配置（右侧第 1 张卡片）：对象的全部消解规则都在这里编辑，含对象类型、分桶字段、来源字段、候选阈值、LLM 复核线、LLM 开关、输出模式、输出数据集、选主策略、字段来源覆盖，以及一张「打分字段」子表。「保存」按钮把配置提交到后端。
• 运行（右侧第 2 张卡片）：「运行消解」触发一次异步 run；「运行后自动轮询」勾选后前端以退避策略轮询 runs 直到终态（1.5s 起、每次 ×1.5、封顶 10s，总上限 5 分钟），超时后露出「继续轮询」按钮可一键续轮询至终态，无需用户去别处手动刷新；卡片底部展示最近一次运行摘要。
• 运行历史：展示 run 的时间、状态徽标、簇数、合并数与错误信息；一次取满后端 limit 上限（50 条），列表按「加载更多」客户端分批渲染以控制单屏行数。
• 匹配结果：按状态筛选（全部/候选/已合并/已拒绝）查看匹配记录，每条记录展示簇 key、成员对象、来源、得分、匹配依据（rule/llm），候选状态的行提供「确认」「拒绝」按钮。

4. 交互元素详解

4.1 左栏：项目列表

4.2 项目配置表单

4.3 打分字段子表

4.4 运行与结果

5. 后端关联

5.1 API 客户端

• 文件：action/web/src/api/fusionApi.js
• baseURL：/api/v1；超时 60000ms（runProject 单独 120000ms）；Content-Type: application/json
• 请求拦截器：自动附带 Authorization: Bearer <aip_token>
• 响应拦截器：401 时清除 aip_token / aip_username 并跳转 /login
• 导出函数：listProjects / createProject / getProject / updateProject / deleteProject / runProject / listRuns / listMatches / confirmMatch / rejectMatch

5.2 端点表

5.3 响应结构

统一响应体 {code: 0, data: ...}（错误时 {code, error}）：

{ "code": 0, "data": { "projects": [ { "id": "...", "name": "...", "object_type": "customer",
  "rule_config": {...}, "survivorship": {...}, "output_mode": "in_place_edit",
  "output_dataset_id": "", "enabled": 1 } ], "total": 1 } }

匹配记录（matches 数组元素）：

{ "id": "...", "project_id": "...", "cluster_key": "9f8b...", "member_object_id": "customer/123",
  "member_pk": "123", "source_ref": "erp", "score": 0.923, "matched_by": "llm",
  "status": "candidate", "created_at": "2026-08-30T..." }

运行记录（runs 数组元素）：

{ "id": "...", "project_id": "...", "status": "success", "clusters": 5, "merged": 12,
  "error": "", "created_at": "...", "finished_at": "..." }

5.4 关联模块表

5.5 关键机制

• 异步任务化：RunProject 经平台任务系统 mgr.Submit 提交，立即返回 MergeRun（status=running）；前端轮询 runs 接口直到 status != "running"。
• 轮询语义：前端 pollUntilDone 采用退避轮询——初始 1500ms、每次乘 1.5、封顶 10000ms，总 deadline 300000ms（5 分钟）；loadRuns 取列表首条作为 lastRun，返回 runs[0].status !== 'running' 作为「完成」信号。到 deadline 仍未终态时置 pollTimedOut 并露出「继续轮询」按钮（pollUntilDone 可重复调用），不再要求用户手动点「刷新」。
• 运行历史获取：listRuns 默认 limit=50（后端 ListRuns 对 limit<=0 || limit>50 一律回落 20，故 50 为可取上限）；前端一次取满后按每批 10 条「加载更多」渲染。
• 状态机：run 状态 running → success | failed；match 状态 candidate → merged | rejected（rejected 不再参与后续 run）；matched_by 为 rule | llm | manual。
• 簇语义：同一 cluster_key 的成员构成一个传递闭包簇（疑似同一实体）；score 为簇内成员对平均相似度；确认/拒绝以簇为单位（调用成员 id 的 confirm/reject 作用于整簇）。
• 写回方式：in_place_edit 经注入 EditWriter 编辑态改 winner 属性值；materialize 经 DatasetWriter 写输出数据集。

6. 核心流程详解

6.1 主流程：配置 → 运行 → 审核 → 写回

1. 新建项目：左栏输入名称点「新建」，前端用默认模板创建（object_type=customer，key_fields=['city']，name/phone 各 0.5，match_threshold=0.8，llm_confirm_score=0.85，llm_enabled=false，survivorship source_priority，output_mode in_place_edit），创建成功后自动打开并填入表单。
2. 编辑配置：在项目配置卡修改对象类型、分桶字段、打分字段（属性/权重/比较器/必比/字段阈值）、候选阈值、LLM 复核线与开关、输出模式与数据集、选主策略与字段来源覆盖，点「保存」提交 PUT /fusion/projects/:id。
3. 运行消解：点「运行消解」，前端提交 POST /fusion/projects/:id/run；若勾选「运行后自动轮询」，则 1.5 秒轮询 runs 直到终态（最长 120 秒），完成后自动加载匹配结果并提示「消解运行完成」。
4. 人工审核：在匹配结果表筛选「候选」，逐簇查看成员对象、来源、得分与依据（rule/llm），对确认无误的簇点「确认」、对有误的簇点「拒绝」。确认/拒绝后列表自动刷新，该簇移出候选。
5. 结果写回：确认合并的簇在运行写回语义生效——in_place_edit 将 winner 属性值写回本体编辑态；materialize 写入输出数据集。拒绝簇保留 rejected 状态，后续 run 不再产出。

6.2 分支流程：运行失败

运行失败时 run 记录 status=failed 并携带 error；前端「最近一次」摘要与运行历史表均以红色展示 error。排查顺序：检查对象类型与 key_fields 是否真实存在 → 确认数据源/本体对象可查询 → 确认打分字段名与本体属性 api_name 一致 → 查看 runs 列表错误列的具体报错。

6.3 状态机与终态语义

• run：running（已提交、任务执行中）→ success（聚类完成、候选已生成）或 failed（规则/取数异常，error 说明原因）。
• match：candidate（本次 run 产出，待人工审核）→ merged（人工确认，整簇合并）或 rejected（人工拒绝；rejected 不参与后续 run）。
• 确认/拒绝调用成功后状态即刻更新；若对同一簇重复调用，后端按当前状态给出响应（已终态的簇操作列显示「—」）。

7. 权限与安全

• 认证：全部端点经 authMiddleware（JWT，aip_token），未授权返回 401，前端自动跳登录。
• 数据级安全：项目按用户维度管理（currentUserID 注入），后端写回经 EditWriter/DatasetWriter 接口注入，不越过本体权限口径。
• 写操作防护：删除项目与删除运行记录均为级联操作，前端用 window.confirm 二次确认；人工确认/拒绝动作直接影响本体数据，操作前应核对簇成员与来源。
• LLM 复核安全：llm_enabled 时仅对达到 llm_confirm_score 的候选批量复核；LLM 未注入时后端自动降级为纯规则，不影响主链路。

8. 常见问题与排错

9. 已知缺陷与边界