# 来源治理与处理结果说明

治理设置、来源处理、当前分段和向量重算分别确认，不能用一个成功响应替代整个处理链。

## 治理设置

文件来源可以在处理完成前保存标签、到期和启用设置。省略字段保持原值；`tags: []` 清空标签，`expires_at: null` 清除到期时间。`tags: null` 按当前绑定视为未提供标签，不具有清空语义。

`enabled: false` 同时清除过期后强制启用；已过期且原来未实际启用的来源设置 `enabled: true` 时，会派生过期后强制启用。读取响应中的 `enabled`、`expired`、`force_enabled_after_expiry`、`effective_enabled`，不要只根据提交值推断最终状态。

Catalog 表来源只接受过期与启停字段，不能显式提交 tags/force-enabled 字段。已处理成功的文件来源实际改变治理启用状态时，才同步向量表中的禁用标志；未完成处理的来源保存设置不意味着索引可用。

## 来源处理视图

来源处理列表按候选来源汇总底层作业，每次最多选择 32 个来源。`total` 统计符合候选条件的来源，不是底层作业数，也不是完整历史；当前没有 page、offset 或 cursor 参数。

`job_id` 是来源汇总视图标识，不是可直接传给工作流查询的应用或运行 ID。顶层 `reconcile_required` 还可能提示历史来源关系需要补建；列表为空但提示为 true 时，应先检查来源关系，不要反复假设存在可重试作业。

普通协调会观察运行状态并推进满足条件的关联、结果或后续处理；显式重试另需指定来源及匹配的失败作业。RAG 作业可重试；Catalog 文件复制与本地文件载入按其类型重试；关联结构化导入任务的失败不通过本路径重启。

## 当前分段与条件写入

文档 GET 默认返回 20 个分段，最多 100 个；按 `segment_status.next_cursor` 继续。条件写入的 `etag` 代表整个当前分段集合，与本页窗口无关。它不覆盖来源治理字段或召回计数，不能用其变化证明向量已重新生成。

创建、修改、启停、删除及重嵌入返回完整分段快照；使用返回的 ETag 做后续条件写入。重嵌入可能在分段事实不变时返回相同 ETag。写入期间出现冲突时重读并确认意图，不自动覆盖。删除后仍须至少保留一个分段。

当前创建使用 chunk。doc/section 虽能通过前置层级类型检查，但没有完整持久化支持，不把它们当作可用创建方式。创建时的图片与页面图片身份由解析流程提供，不能通过请求另指定。

## 结果确认

`updated: true` 只说明协调调用已处理；即使没有候选也可能返回 true。处理成功要结合来源 `ingest_status`、关联信息与文档 `segment_status` 判断，不根据候选清单变空判断。

来源处理状态使用 pending/succeeded/failed 等来源枚举；存储准备的 ensure_status 使用 ready 等另一套值。存储准备就绪不等于来源处理成功，来源治理启用也不等于来源内容已解析或可检索。

本工作集保留未发布的重试字段扩展。
