dify/knowledge-fs/docs/figma-backend-traceability-matrix.md

Figma 产品功能 → 后端实现可追踪矩阵

1. 范围与判定规则

本矩阵以 Figma New RAG 的产品功能拓扑为需求输入，追踪：

Figma 产品功能 → 后端需求 → 当前实现/代码证据 → 缺口 → 修复/验证 → 状态

本仓库是 纯后端服务。所有“修复”仅包含后端 schema、repository、route、worker、鉴权、索引、检索编排、测试与文档；不在本仓库开发页面、组件、样式、前端 API client 或 BFF。Figma 中纯视觉、交互展示状态若不需要跨请求保存、权限判断或后台任务，不会被错误转换成后端任务。

审查基线：2026-07-15，分支 codex/figma-backend-alignment。状态以包含本矩阵的提交为准；每次实现变更必须同步更新稳定 ID 和测试证据。

状态定义：

• 已完成：已有可运行代码和对应测试证据，当前产品契约在该行范围内闭环。
• 部分完成：已有可复用能力，但尚未满足该行完整产品契约。
• 本批修复中：当前迭代已有代码变更，但尚未完成全量验证、提交或运行时闭环。
• 未实现：没有可供产品调用的完整后端能力。
• 后续迭代：已明确需求和验收条件，但不属于当前批次。

优先级定义：P0 为安全、数据隔离或核心检索语义错误；P1 为主流程缺失或配置不生效；P2 为运营、可观测性或体验增强。

2. 三种检索模式的产品契约与当前结论

这里的 Summary 指 PageIndex/DocumentOutline 节点生成的摘要，不是必须另建一套独立的 synthetic SummaryTree 索引。除非产品后来明确增加第二套 SummaryTree，否则不应把实验性 createSummaryTreeRetrievalPath 接入生产来冒充 PageIndex。

auto 是公开的模式路由选择器，不是第四条检索执行管线。只有请求显式传入 mode=auto 时，后端才会使用知识空间 frozen published profile 的 reasoningModel，经 plugin-daemon 选择下表三条管线之一；省略 mode 直接使用 defaultMode。路由不再根据 CJK/混合语言、查询长度、词数或“分析/解释/研究/证据”等关键词做硬编码判断；模型调用 失败或输出无效时安全降级到同一 published profile 的 defaultMode。

模式	产品契约	当前结论	主要缺口
Fast	普通混合召回（dense + FTS）→ 候选去重/融合 → 一次最终 rerank → Top K/Threshold	查询边界固定一次 published head/profile tuple；dense/FTS 只读该 publication 的 ready member，分别归一化原始分数后按 nodeId 等权融合；启用 rerank 时最终分数与排序只使用 reranker score，关闭时使用 [0,1] normalized final score；进入检索前统一校验 space member/API Access，并把服务端 candidate grants 用于 SQL 与应用层 ACL；缺 verified embedding、已启用的 reranker、权限快照或 published snapshot 均 fail closed；TiDB FTS 使用 indexed postings，不做字符串全表扫描	当前产品契约已闭环
Research	Evidence V3：多查询 dense + FTS + deterministic Outline + 可选单次 Graph → weighted RRF → profile rerank → 证据集充分性判断	直接问题跳过 planner；复杂问题最多 1 次 planner + 3 个批量 embedding rewrite；不按文档调用 LLM。所有候选绑定同一 publication/profile/ACL，RRF 后每轮只调用一次知识库 reranker，最终 [0,1] 分数用于 threshold/Top K；durable 最多补检一次	当前产品契约已闭环；V2 仅保留 checkpoint replay
Deep	普通混合召回 + Graph 扩展 → 合并全部候选 → 一次统一 rerank → Top K/Threshold	固定同一 published head/profile tuple，先执行 dense/FTS normalized score fusion，再按同一 publication 的 Graph member/entity/relation/source-node/ACL 闭包扩展和二次召回；启用 rerank 时最后只执行一次统一 rerank、threshold 与 Top K，关闭时按 normalized final score 排序；Graph capability 缺失只让 Deep fail closed，不影响 Fast/Research	当前产品契约已闭环

3. Creation

ID	优先级	Figma 产品功能	后端需求	当前实现/证据	缺口	修复/验证	状态	迭代
CRE-001	P1	创建知识空间：名称、描述	tenant-scoped 创建、slug 唯一、基础信息可读写	Create schema 的 slug 已可选；knowledge-space-creation.ts 从名称生成受限 ASCII slug，纯非拉丁名称使用稳定 SHA-256 后缀，重名按有界确定性序列重试；显式 slug 仍保持严格冲突语义，数据库唯一性按 tenant 隔离	当前后端契约已闭环；Figma 调用方无需生成或展示 slug	knowledge-space-creation.test.ts 与 gateway/repository 测试覆盖中文名称、冲突重试、显式冲突、重试耗尽和租户隔离	已完成	I3
CRE-002	P2	创建知识空间：图标	持久化 icon identity/asset reference，并在 Space DTO 返回	KnowledgeSpaceSchema、create/update schema 与 memory/database repository 已支持 nullable iconRef；0023 添加 icon_ref，0034 将 CHECK 与 Dify Emoji Mart identity（例如 grinning、slightly_smiling_face、+1）对齐，并继续兼容 builtin: 前缀	当前只接受有界内置 emoji identity，不接受任意 URL/object key；产品若以后要求自定义上传需另建受控 asset lifecycle	create/update/clear、CAS、非法 URL/大小写、PostgreSQL/TiDB migration/schema tests 通过	已完成	I6
CRE-003	P1	创建时选择 Embedding 模型	保存用户选择的 plugin/provider/model；在首次需要向量时根据真实模型响应派生 vectorSpaceId/dimension，不得写死 1536	空知识空间创建只把 selection 写入带 digest/revision/state 的 manifest.pendingModelConfiguration，不调用 plugin-daemon，也不预先伪造 dimension/profile/vectorSpaceId；首个文档的 durable async compilation 在 lease 内执行 tenant-scoped catalog/credential/real-invocation preflight，从 embedding 实际响应生成不可变 profile、dimension/metric 和 vectorSpaceId，并以单一事务安装完整 embedding/retrieval tuple、active heads 与 pending clear，再将 exact profile refs 绑定到 attempt；已发布空间的模型变更仍通过 full-vector-space durable migration 重建、评估并联合切换 profile/publication，失败保留旧 tuple	当前已同时满足空空间创建不阻塞、空间级动态维度、首次 tuple 无 partial 可见窗口和发布后安全迁移；最终 PostgreSQL/TiDB 向量列无 1536 运行时约束	create zero-daemon、首文档 capability/原子 tuple activation/fault rollback/replay、7/384/768/1024/3072/4096 维、跨空间模型/凭据隔离、migration lease/retry/evaluation/head conflict/rollback 与 PG/TiDB 回归	已完成	I3/I7
CRE-004	P0	创建时建立默认权限/Owner	Space、manifest/pending configuration、owner membership、access policy、API access default 与 activity 必须在一个可靠事务内创建；profile head 延迟到首文档验证后激活	生产 create 不等待 plugin-daemon；knowledge-space-provisioning-repository.ts 以单个数据库事务写入 Space、Manifest/pending config、Owner、only_me policy、API Access off 和 activity，初始不建 profile/head。idempotency key 派生确定性 ID；v3 lost-ACK replay 会精确重验 pending digest/revision/selection 与权限语义，并保留对旧 v2 完整 aggregate 的严格重放兼容；旧空间只能由带签名 deployment-admin scope 的 initialize-only bootstrap 恢复	当前原子创建、零 daemon 创建、幂等重放和旧空间迁移安全契约已闭环；Space durable deletion 另见 SET-010	PostgreSQL/TiDB 原子回滚、pending v3/legacy v2 replay、generated slug suffix、逐类缺行/篡改、owner/viewer/last-owner/跨租户与重复 bootstrap 回归	已完成	I1/I3/I7
CRE-005	P1	创建后接入 Upload/Crawl/Online docs	创建 Space 后可用独立 Source/Document API 继续导入；操作要幂等并返回可追踪任务	创建完成后可独立调用 Document 单/批上传以及 Source crawl preview、Online docs/Drive import；长流程使用 durable workflow/compilation run、Idempotency-Key、状态查询、cancel/retry，不依赖统一页面 wizard 或单个 HTTP 连接	当前后端-only 产品契约已闭环；Source/Document 是两个独立 API 域，不在本仓库合并为前端创建向导	Source workflow、逐文件 upload admission、durable attempt/outbox、重启/重试/幂等和状态路由测试通过	已完成	I4/I5
CRE-006	P1	创建时设置默认检索策略	可选保存版本化 default mode、reasoning、rerank、Top K、Threshold；空空间不应因模型网络校验阻塞创建	create 只持久化 pending selections；首文档 compilation 再验证 embedding/reasoning/rerank 并冻结 exact tuple。三种模式都要求 verified embedding + rerank；Research V3 另使用 frozen reasoning 做 bounded plan/judge，并按计划选择 published Graph；profile-less legacy 空间不猜测部署默认	当前版本化默认策略、惰性验证和三模式隔离契约已闭环	create/update pending、首文档 activation、V3 model/Graph routing、两空间凭据隔离、legacy fail-closed	已完成	I3/I7/I9

4. Settings

ID	优先级	Figma 产品功能	后端需求	当前实现/证据	缺口	修复/验证	状态	迭代
SET-001	P1	Basic info：名称、描述	tenant-scoped GET/PATCH，支持并发保护	PATCH 必须提交 expectedRevision；数据库事务按 active space/deletion lock → fresh durable admin permission fence → revision CAS 更新名称、描述、slug/icon，并写 activity；撤权、删除、并发 revision 或 slug 冲突均不会落盘	当前并发与最终权限重验契约已闭环	memory/PG/TiDB repository、handler/gateway 测试覆盖 CAS 409、撤权、API key/API Access、删除竞态和 tenant slug 隔离	已完成	I3
SET-002	P0	Permissions：Only me / All members / Partial members	access policy、member CRUD、owner/editor/viewer role、space authorization guard	0013 建立 tenant+space scoped member/policy/partial-member 表；CRUD 全部 CAS 并保护 policy owner/last owner；统一 middleware 覆盖所有 /knowledge-spaces/:id/**，资源 ID 路由（trace/job/research/snapshot/bulk）解析所属 space 后再授权；列表在 SQL LIMIT 前做 membership/visibility 过滤	当前 Figma 三种可见性和角色契约已闭环	knowledge-space-access-control.test.ts、gateway-space-authorization.test.ts、repository PG/TiDB SQL 测试覆盖跨用户、viewer mutation、partial members 和 fail-closed legacy space	已完成	I1
SET-003	P0	API access 开关	持久化开关/revision；关闭后拒绝 Service API、MCP、Agent 新请求；key 只保存 hash	0013 持久化 versioned API Access、SHA-256-only API keys 与 durable permission snapshots；JWT caller kind 只能来自签名 claim，API key 从存储记录反查 tenant/space/member；关闭开关或撤销 key 后下一请求立即失败；MCP 构造器强制注入 authorization，API key 禁止 tenant-wide routes	当前空间级 API Access 与 key lifecycle 已闭环；OAuth/provider connection 属 SRC-004	handler/auth/MCP/gateway 测试覆盖 off、revoke、expiry、跨 space、hash/token 不回显及 tenant-wide route 拒绝	已完成	I1
SET-004	P1	Embedding model	空间级 selection/profile/vectorSpaceId/dimension/revision，ingestion/query 同源	尚无 active profile/head 的未发布空空间在设置保存时只 CAS 更新 pending selection/digest/revision，返回 202 且不调 daemon；首文档 durable compilation 从 tenant-scoped plugin-daemon 实际响应观察 dimension/metric，派生 vectorSpaceId 并激活 profile/head。空间 factory 不携带部署 secret；已发布空间变更走 durable full-vector-space candidate rebuild/evaluation，并与 successor publication 联合 CAS 激活	当前动态维度、vector-space、凭据隔离、空空间非阻塞设置与发布后原子迁移契约已闭环	zero-daemon pending update、首文档 capability/activation、不同空间/模型/维度、same-provider credential isolation、stale pending CAS、published migration retry/rollback/head drift 回归	已完成	I3/I7
SET-005	P1	System reasoning model	空间级 plugin/provider/model selection，query 与 ingestion 时解析	首文档激活后，最终回答、Auto、Research V3 planner/judge、Outline/Summary enhancer 与 Graph extraction 均从同一 frozen space profile 解析。Research 不再逐候选打分；direct query跳过 planner，Graph只在 plan要求时进入 original recall leg	当前 reasoning 惰性验证、凭据隔离和 V3 bounded-call 契约已闭环	planner skip/bound、judge identity、frozen ingestion/answer/Auto、Graph single-leg	已完成	I3/I7/I9
SET-006	P1	Rerank Model 开关与模型	空间级 enabled + plugin/provider/model，三模式在完整候选集后调用	首文档 preflight 并冻结 capability；Fast/Deep 每次检索一次，Research V3 每个 evidence round 一次（最多 initial+supplement 两次），V2 replay不额外调用；disabled/缺能力 fail closed	当前 rerank 惰性验证、凭据隔离与三模式 score 契约已闭环	activation/migration、dynamic factory、V3 per-round single-call、threshold	已完成	R0/I3/I7/I9
SET-007	P1	Retrieval depth：Fast/Research/Deep/Auto	保存 defaultMode，并允许受控 request override；Auto只选三条管线之一	Fast=hybrid+rerank；Research=Evidence V3 multi-recall+RRF+rerank+judge；Deep=hybrid+Graph+rerank。省略 mode 直接用 default，显式 concrete zero-route-call，显式 Auto 用 frozen reasoningModel	当前模式配置、Auto 与 V3 runtime消费闭环	default/explicit/Auto、V3 calls/Graph/rerank、legacy checkpoint	已完成	I3/I8/I9
SET-008	P1	Top K	持久化空间级 Top K；按模式作用于正确候选阶段	topK 限制1..100；Fast/Deep/Research V3 都在最终 rerank+threshold 后应用，内部 multi-leg/RRF 保留更宽候选；V2 replay保留历史顺序	当前产品 Top K 闭环	三模式顺序、V3 candidate width、100边界	已完成	R1/I9
SET-009	P1	Score Threshold	版本化 enabled/value/stage；基于可比较分数过滤	Fresh Fast/Deep/Research 都以 profile reranker [0,1] score 在 final Top K 前过滤；V2 replay以 versioned semantic score兼容。必配 rerank缺失在工作开始前拒绝	当前配置和执行契约闭环	保存/override、provider非法score、V3/V2顺序	已完成	R1/I9
SET-010	P1	Danger zone：删除知识库	owner/admin challenge、CAS 标记 deleting、durable delete job、派生数据/对象/缓存/trace 清理	durable-deletion-service.ts 要求 interactive owner、完整名称 challenge、expected revision 与 idempotency key；durable-deletion-repository.ts 原子写入 deleting 状态、job/tombstone/outbox/item，worker 按 requested→quiescing→deleting_objects→deleting_derived_data→deleting_primary_data→completed checkpoint 恢复；database-durable-deletion-target-capabilities.ts 排空 retrieval/compile/research/sync/lease，清理对象、Secret、cache、trace/evidence/index/path/primary rows 并在完成事务内反向证明无残留	当前行 Space durable deletion 契约已闭环；生产开放仍必须按 0017 writer-fence rollout 执行	repository/runtime/handler/capability 故障注入覆盖 lease loss、retry、dirty-primary reconciliation、晚到 worker/publication；PG/TiDB 真实迁移与对象写入锁序通过	已完成	I2
SET-011	P1	模型配置保存/校验状态	设置页必须区分 setup-required、pending-validation、validation-failed、ready，并在已有可用配置更新失败时继续使用旧 active profile	Provisioning 只持久化 pending config，不执行候选校验；首个文档的 durable compilation attempt 在验证前后用 pending digest/revision 与 profile-head CAS 防止旧结果激活，非可重试失败写入 allow-listed validation-failed。GET /knowledge-spaces/{id}/status 从 immutable heads 与 pending config 派生四态；active heads 始终优先于失败候选，任何模式进入 ready 都要求 retrieval 与 embedding 两个 active head；legacy Research-only retrieval head 显示 setup-required；响应不回显候选 model selection、provider 原始错误或凭据	当前配置 readiness、安全诊断、stale-result fence 与首文档激活链已闭环	control-plane diagnostics 覆盖空配置、pending、validation-failed、legacy Research-only active + replacement failed 与候选身份不回显；coordinator/repository 回归覆盖动态维度、重复 worker 收敛、stale pending CAS 与 exact attempt binding	已完成	I7

5. Overview

ID	优先级	Figma 产品功能	后端需求	当前实现/证据	缺口	修复/验证	状态	迭代
OVR-001	P2	Overview 统计卡片	24h/7d/30d query count、answer rate、knowledge count、linked apps、freshness 聚合	query.requested 在生成 admission 前持久化；服务端 UUID queryRunId 与客户端 correlation header 分离。成功 AnswerTrace 以最终 query.generate summary 为权威终态，可恢复的中间 stage error 不会误判；数据库统计以成功 trace 为主并兼容旧 query.completed。knowledge-space-overview-database-repository.ts 在 tenant/space/grant scope 内聚合 24h/7d/30d distinct query/answer、active logical documents、connection 与 source freshness	当前统计与 durable query terminal 契约已闭环	时间窗、request-before-completion、fallback success、exactly-one done、cancel/lease/trace failure、重复 completion、空数据、ACL 与异常聚合 clamp 回归通过	已完成	I6
OVR-002	P2	Needs Attention	由可追溯规则生成问题、严重度、资源和 action	已实现 stale source、failed document、low-quality query、permission/model readiness 规则及 persisted attention state；/overview/attention 支持 list 与 CAS dismiss/resolve。failed-query signal 在 LIMIT 前按 tenant、exact requester、完整 provenance 与当前 grants 过滤	当前 Needs Attention 契约已闭环	transition 由 handler 签发 fresh snapshot，DB 在 active/deletion lock 后事务内重验 member/policy/API Access/snapshot/scopes；revoke、API-off、active-delete 与跨 requester 负向测试通过	已完成	I6
OVR-003	P2	Recent Activity	保存 actor/action/resource/result/timestamp，可分页筛选	knowledge_space_activity_events 为 append-only、确定性幂等事件；query activity key 纳入 tenant+space+server queryRunId，SSE 只在 exactly-one done 且 durable success trace 提交后暴露成功。AnswerTrace read model 可在 trace commit 与 activity projection 之间崩溃后合成唯一 completed/failed 终态，并抑制重复显式 terminal；cancel/failed 使用同一终态 gate。document、source workflow、settings/profile 与 permission 写路径也已接入	当前活动流、终态恢复和跨租户幂等契约已闭环	tenant/space/grant 过滤先于分页；客户端伪造/重复 x-trace-id、post-commit disconnect、success-commit failure、cancel/lease 竞态、跨 scope idempotency reuse、敏感 details 清理与 route 脱敏测试通过	已完成	I6
OVR-004	P2	Knowledge health/status	返回 ingestion、index、source sync、query availability 的综合状态	/overview/health 已返回 ingestion、index、profile publication、query availability、source freshness、worker readiness 六组件及稳定 health code；探针读取 active document、published head/profile binding、source 与 stale worker 状态	当前产品 health 契约已闭环	bounded SQL、空数据、degraded/unavailable 映射与公共 DTO 测试见 Overview repository/handler tests	已完成	I6

6. Source / Crawl / Online docs

ID	优先级	Figma 产品功能	后端需求	当前实现/证据	缺口	修复/验证	状态	迭代
SRC-001	P1	Source 列表、创建、编辑、删除	tenant + space scoped CRUD、cursor、CAS、状态	CRUD/cursor/CAS、space role/API Access 与 candidate grants 已闭环；删除改走 durable job，cascade 会清理文档对象、索引与派生数据，keep 会生成不含 Source identity 的 immutable successor publication、CAS 切 head，并清除 retained Document/Asset 的 source reference；credential lifecycle ref 会进入可重试清理清单，Source tombstone 阻止晚到 materializer/sync 重写	当前行 Source CRUD 与 durable delete/keep 契约已闭环；provider/OAuth/sync 产品能力分别追踪 SRC-003～SRC-010	Source authorization/cursor、keep/cascade publication、credential/object inventory、stale-write scrub 与故障恢复测试；对象 put 在 Source deletion 前持有空间写入门禁	已完成	I1/I2
SRC-002	P0	Connection 凭据安全	公共 DTO/日志不返回 secret；数据库只存 credentialRef；支持 rotate/revoke	0014 为 Source 增 opaque credential_ref、source_secret_lifecycle_refs 与 durable backfill；AES-256-GCM SecretStore 用 tenant/space/source/ref AAD；create/rotate 先持久化 staged ref、再写精确对象地址，随后把 Source CAS、active/retired lifecycle 原子提交；revoke 同样原子解绑并 retire；backfill 的 candidate/job、activate/refresh/abandon 均有数据库事务和 lease fence；删除 tombstone 周期复扫可清理过期 worker 的晚到写入，损坏或旧密钥密文也可按 hashed ref 删除；connector 只拿短生命周期 hydrated clone，公共 DTO 不返回 ref/secret	当前 SecretStore、dual-read/backfill、新写入、retired-object 与 Space/Source durable deletion 清理契约均已闭环	lifecycle reserve-before-put、错误 fingerprint、commit ACK 丢失、late write scrub、损坏密文删除、backfill crash/retry/lease、资源删除、PG/TiDB rolling-upgrade closure、API redaction 与未知 connector error 脱敏测试	已完成	I1/I2
SRC-003	P1	Provider catalog / capability	列出 provider、配置 schema、connection status、支持的 source 类型	GET /source-providers 返回稳定 provider id、display name、auth kinds、source capabilities、配置字段 schema 与 configured availability；connection API 单独返回每个连接的 lifecycle status	当前发现契约已闭环；available 是部署静态 registry 声明，不冒充 plugin 的实时健康探针	source-provider-catalog.test.ts 与 product route tests 覆盖 schema、重复/非法 descriptor、capability mismatch 和 unavailable provider	已完成	I4
SRC-004	P1	OAuth connection	start/callback、PKCE/state、refresh/revoke，Source 仅引用 connectionId	一等 Source Connection repository/routes 已实现 create/list/get、OAuth start/callback、refresh/revoke；state 仅存 hash，PKCE verifier 与 tokens 存 SecretStore ref，callback 绑定 tenant/subject/channel/API key，redirect URI 执行 allowlist/HTTPS 校验；最终 DB mutation 重验 fresh permission	当前 connection/OAuth lifecycle 契约已闭环；Source 业务数据只引用 connection identity，不保存 OAuth 明文	PKCE/state expiry/replay、redirect allowlist、exchange/refresh crash recovery、rotate/revoke、撤权/API key 和 secret cleanup 测试通过	已完成	I4
SRC-005	P1	Website Crawl 预览、选页、导入	durable preview job；分页发现页面；progress/cancel/retry；提交 page IDs 后 materialize	crawl-preview durable workflow 按 queued/crawling/preview_ready/importing/completed 状态推进；发现页持久化并用 cursor 分页返回且不含完整 body，selection 以 page IDs 和 Idempotency-Key 提交，run 支持 get/list/cancel/retry 与 lease/checkpoint 恢复	当前流程通过轮询 run/pages API报告进度，未提供 SSE；这不影响 Figma 产品所需的可恢复预览与选择导入契约	repository/runtime/route 测试覆盖重启、失租、选择幂等、分页、零结果、取消/重试与 staging object 清理	已完成	I4
SRC-006	P1	Online docs 浏览与选择导入	分页列 workspace/page，选择 page IDs 后异步 materialize	/pages 已接受 bounded limit 与 opaque cursor 并返回 nextCursor；选择项经 /workflow-imports 创建 durable online-document import run，HTTP 不再等待 materialization，历史/状态/cancel/retry 可查询	当前 Online docs 浏览与异步导入契约已闭环	cursor round-trip、200 项上限、幂等 import、provider failure/retry、远端变更和权限/deletion fence 测试通过	已完成	I4
SRC-007	P1	Online Drive 浏览与导入	browse 必须透传 continuation token；选择文件后异步下载/materialize	connector/input/output 与 /files DTO 已透传 opaque continuationToken、bucket/prefix/maxKeys；选择文件通过 durable online-drive import run 下载、校验 hash并发布逻辑 revision	当前 Online Drive continuation 与异步导入契约已闭环	token round-trip、truncated multi-page、重复页幂等、下载失败/retry、provider identity 与权限/deletion fence 测试通过	已完成	I4
SRC-008	P1	Sync policy / 手动与周期同步	first-class policy、durable sync runs、进度/error/cursor/retry；单个和 bulk control	source_sync_policies、workflow run/outbox、lease/row-version/checkpoint、history/control API 已落地；manual/interval/custom/provider policy 创建受限 run，多 worker claim、stale recovery、cancel/retry 和 terminal aggregation 持久化	当前 sync policy 与 durable execution 契约已闭环	0021 migration、repository/runtime/scheduler tests 覆盖重复调度、lease loss、crash resume、API revoke、deletion、cancel/retry 和 outbox replay	已完成	I4
SRC-009	P1	远端更新/删除与版本	providerItemId + contentHash/etag 识别逻辑对象；candidate revision ready 后切 active；tombstone policy	Source materializer 通过 sourceId + providerItemId 定位 Logical Document，以 contentHash/etag 判断 unchanged 或创建 immutable candidate revision；candidate 与 compilation publication 在同一最终事务联合激活，失败保留旧 active。绑定 attempt 后失败的 candidate 以 durable deletion tombstone/outbox 清理，但仅允许 failed + never-active + exact run/item/hash ownership + 唯一 asset 引用；事务内再次锁定 asset/source/logical revision 验证，active/superseded/activated/历史引用永不清理；远端缺失按 retain/tombstone policy	当前远端版本、失败候选 GC 与删除策略契约已闭环	update/no-change、provider identity digest、失败重启幂等、lost-ACK、并发 activation/rollback/额外版本引用、joint CAS、remote retain/tombstone、撤权/删除竞态测试通过	已完成	I4/I5
SRC-010	P2	Bulk Sync / Disable / Remove	bounded bulk job，返回 eligible/skipped/failed，支持进度	POST /knowledge-spaces/{id}/sources/bulk 支持最多 200 个 source 的 sync/disable/remove；父 run 与独立 child/deletion jobs 持久化，bulk-items cursor 返回 eligible/running/skipped/failed/completed，完整 idempotency fingerprint 防止 key 碰撞	当前 bulk control 契约已闭环	部分失败、入队后 Source 删除、child retry、remove polling、权限 scope、幂等 replay/collision 与 terminal progress 测试通过	已完成	I4

7. Documents / Tasks

ID	优先级	Figma 产品功能	后端需求	当前实现/证据	缺口	修复/验证	状态	迭代
DOC-001	P1	Document 列表与详情	space scoped 分页、状态、source、active revision、timestamps	0022 引入 logical_documents 与 immutable document_revisions；/logical-documents list/get 返回 source/provider identity、status、rowVersion、activeRevision 及 active revision 的 asset/hash/MIME/time，cursor 在 tenant/space/ACL 过滤后分页	当前一等 Logical Document 读取契约已闭环；旧 asset routes 继续作为兼容的物理内容视图	schema/migration、memory/PG/TiDB repository、route ACL/cursor 和 public DTO 测试通过	已完成	I5
DOC-002	P1	单文件/批量上传	写对象前校验 MIME/size/count/quota；每文件独立 accepted/excluded/reason	默认单文件 15 MB、批次 50 MB/20 文件，hard ceiling 50 MB/25 文件；扩展名与 MIME allowlist、storage/manifest quota 在对象写前校验；bulk admission 对每个文件返回 accepted/excluded/reason，运行时单文件失败不会回滚同批合法文件	当前逐文件 admission 契约已闭环	upload utils/gateway tests 覆盖格式、大小/数量/总量/quota、部分失败、revision target CAS、对象补偿和删除竞态	已完成	I5
DOC-003	P1	Document revisions / history / rollback	逻辑文档、不可变 revision、activeRevision CAS、历史和 rollback	新上传或 Source update 以 documentId 或 sourceId+providerItemId 追加 immutable candidate revision；history cursor 可查；rollback 不复活旧 mutable 行，而是从 superseded revision 创建新 candidate并启动 compilation；最终 publication 事务联合 CAS logical active revision 和索引 head。Source-bound compilation 失败时，exact owned、never-active revision/asset 由 durable GC 回收；任何 active/superseded/activated 或被其他 revision 引用的资产都保留	当前 revision/history/rollback、联合发布与失败候选生命周期契约已闭环	duplicate/provider identity、CAS conflict、rollback、candidate failure/restart/lost-ACK/concurrent activation、publication head conflict、权限撤销与 PG/TiDB migration/repository tests 通过	已完成	I5
DOC-004	P1	Processing Tasks	durable task 列表/详情/progress/retry/cancel，按 space/document 分页	/processing-tasks 支持 space/document scoped cursor list、get、SSE event stream、cancel/retry；底层复用 durable compilation attempt/outbox、lease/fence/checkpoint，公开 DTO 隐藏 worker token 与权限 provenance	当前任务产品契约已闭环	task repository/handler/SSE tests 覆盖进度、分页、subject/channel binding、cancel/retry、失租、重启恢复和删除 fence	已完成	I5
DOC-005	P0	Candidate index publication	所有组件在 candidate generation 构建；评估通过后单一 head CAS；失败保留旧 head	空空间的首个 durable compilation attempt 允许先不带 profile refs 入队；worker 取得 lease 后先校验 pending model config，以单事务激活完整 profile tuple 并清 pending，再用 fenced bindInitialProfiles 恰好一次绑定当前 active id/revision/digest/vector-space，然后才进入 parser/index worker。普通 attempt 继续在创建时冻结 base publication/member/profile 与 durable permission provenance；candidate 隔离构建 projection/Outline/multimodal/path/Graph，闭包与 candidate-only evaluation 通过后在最终锁内事务联合 CAS profile binding、publication head 与产品 candidate	当前首文档惰性 profile 冻结、无 partial tuple、发布原子性、最终权限和 profile/logical 联合切换契约已闭环；缺失或部分 provenance 一律 fail closed	initial no-ref attempt/atomic tuple rollback+replay/fenced bind/restart、revoke/API key expiry/partial member、profile/head drift、lease loss、partial receipt、evaluation failure 与拒绝路径零副作用回归	已完成	I0-3C/I3/I5/I7
DOC-006	P1	Chunks 查看、搜索、启停	分页 chunk API、parent-child、token count、enable/disable 与 revision 一致	revision-scoped chunks API 支持 cursor、query、get，返回 ordinal、parent、tokenCount、metadata；state change 不直接改 published node，而是在 fresh candidate-admission 后创建 compilation attempt和 candidate override，只有 publication 成功才激活	当前 Chunk 读取、搜索和候选启停契约已闭环	chunk repository/handler/runtime tests 覆盖 revision scope、search、parent、revoke/delete admission、candidate failure与 publication activation	已完成	I5
DOC-007	P1	Metadata 编辑	systemMetadata 与 userMetadata 分离，user PATCH 带 expected revision	logical revision 内部 systemMetadata 保存 provenance，公共 Document DTO 只暴露 userMetadata；PATCH 要求 expectedRowVersion，拒绝 __knowledgeFs* 等保留 namespace；数据库事务在 active/deletion lock 后重验 fresh durable permission、当前 asset permission scope和 CAS	当前 metadata namespace、脱敏与并发写契约已闭环	handler/repository tests 覆盖 reserved key、嵌套 pollution、CAS、撤权、current scope变化、删除竞态与零副作用	已完成	I5
DOC-008	P1	Document Settings / reindex	保存索引行为；变更创建 candidate，不直接污染 active revision	document settings 使用 immutable revision/head，PATCH 带 expected head revision；chunk size/overlap、PageIndex/Graph/language 作为 exact compilation attempt override 创建 reindex candidate；最终 publication 成功才激活 settings，失败/撤权/删除保持旧 settings/head	当前 settings/reindex 候选发布契约已闭环	settings repository/coordinator/reconciler/publication tests 覆盖 CAS、幂等、失败回滚、权限 admission、head drift 和 active-only resolver	已完成	I5/I0-3C
DOC-009	P1	Document 删除	durable lifecycle，先阻止新发布，再清派生引用和对象，支持 retry	Document DELETE 与 bulk DELETE 只创建 durable job 并返回 202；请求事务预存 raw object item、标记 asset deleting 并安装 tombstone，worker 先从 published head 排除目标，再按持久化 inventory 清 object/multimodal/staging/cache/trace/evidence/outline/graph/projection/path，最终在 fenced transaction 删除 primary row并执行 DB + object prefix 反向证明；失败 item/job 可 retry，不再同步误报 204	当前行 Document durable deletion 契约已闭环；逻辑 Document/Revision 产品模型另追踪 DOC-001～DOC-008	handler/repository/runtime/capability、bulk、publication CAS、late put compensation、orphan/residue probe 与 lease-loss 测试	已完成	I2
DOC-010	P0	Published document visibility	查询只能读取当前 published snapshot 的成员，不读 building/failed/stale generation	query 开始时一次解析 immutable head snapshot；Fast dense/FTS、Research PageIndex/leaf、Deep Graph/entity/relation/source-node 均校验 exact publication member + generation + document asset；building/candidate/stale/跨 publication 行不可见，空或不一致 snapshot fail closed；legacy bootstrap/backfill 有 durable lease/ledger	当前行可见性契约已闭环	PostgreSQL 16 + TiDB 8.5 真实迁移/查询探针与负向测试持续保留	已完成	I0-3B3

8. Retrieval Test 与线上检索

ID	优先级	Figma 产品功能	后端需求	当前实现/证据	缺口	修复/验证	状态	迭代
RET-001	P1	选择 Fast/Research/Deep 发起检索	API 接受 mode，并返回可追踪 plan/metrics/evidence	除线上 /queries 外，POST /knowledge-spaces/{id}/retrieval-tests 已提供 bounded、无答案生成的正式检索测试；mode 可覆盖空间 default，执行同一 published runtime snapshot、权限 grants、retriever 与 execution lease，并返回证据、plan、metrics、stages	当前 Retrieval Test 产品契约已闭环	route/executor tests 覆盖三模式、默认/override、无 answer 调用、ACL、删除 admission、lease loss 和 fail-closed capability	已完成	I3/I6
RET-002	P0	Fast：普通混合召回	并行 dense + FTS，任一路失败按显式策略降级	createBasicHybridRetriever 并行执行 dense/FTS，固定 publication id、vectorSpaceId、permission scope；缺 verified embedding 时 Fast/Deep 在任何 leg 前 fail closed；TiDB FTS 用 hash postings lookup index，PG 用 GIN tsvector；单 leg 失败策略与 metrics 有测试	当前普通混合召回与模型 preflight 契约已闭环	hybrid-retrieval.test.ts、capability tests 与真实 PG/TiDB probe 保留两 leg、member/ACL、动态 vector-space 和索引路径回归	已完成	R1/I3
RET-003	P0	Fast：候选合并	dense/FTS 按 node 去重，保留来源/projection，各路原始分数归一化后融合并送 rerank	fuseRetrievalCandidates 先在每个 non-empty leg 内按 nodeId 去重和 min-max 归一化，再按可用 leg 等权累加；单 leg 自动使用完整权重并保留 planner 的 pre-rerank candidate width	当前行契约已闭环；后续只需继续保留候选宽度回归	retrieval-fusion.test.ts、hybrid-retrieval.test.ts 与 retriever-options.test.ts 覆盖双路、单路、重复 projection、稳定排序和完整候选池	已完成	R0
RET-004	P0	Fast：最终 Rerank	所有普通混合候选合并后仅调用一次 reranker，再截取 final Top K	planner 为 Fast 生成非零 rerank candidate limit；最外层 wrapper 在全部普通候选融合后只调用一次；dynamic factory 不依赖部署默认，profile enabled + capability unavailable 时 fail closed；关闭时 zero-call；阈值在 final Top K 前执行	当前行契约已闭环；后续只需保留调用次数、模型身份和失败策略回归	retriever-options.test.ts、final-rerank-retrieval.test.ts 覆盖动态 factory、缺能力、关闭与 legacy 路径	已完成	R0
RET-005	P0	Research：PageIndex Summary/Outline 构建	ingestion 为每个文档生成可导航 outline 和节点 summary，并与 publication generation 绑定	compilation pipeline 构建 generation-scoped DocumentOutline；按空间 reasoning model 运行 summary enhancer；page-index-build-repository.ts 将 ready manifest、flattened nodes 和 exact terms 与 outline generation 原子写入；reasoning 变化会创建 full Summary/Outline rebuild migration，完整 build 才允许 publication	当前构建、模型变更重建与发布契约已闭环	builder/enhancer/build repository、profile migration、publication readiness 与失败保留旧 PageIndex 测试通过	已完成	R1/I3
RET-006	P0	Research：Evidence V3 多路召回	在 Space 的 published corpus 上融合 dense、FTS、Outline 与必要的 Graph，不能按文档/树层级放大模型调用	createResearchEvidenceRetrieval 对直接查询零 planner-call，对复杂查询一次结构化计划并批量 embedding 最多 3 个 rewrite；每个 recall leg 复用 frozen publication/profile/ACL。createResearchOutlineEvidenceRetrieval 以 Value 命中和 exact section postings 确定性打开范围；fuseRankedHybridRetrievalLists 用 weighted RRF 合并，不把跨模型 raw score 直接相加	当前 V3 主路径与 V2 checkpoint compatibility 均已闭环	planner bound、batch vector、RRF、outline range、ACL/snapshot、fresh V3 不调用 legacy tree scorer回归	已完成	I9
RET-007	P0	Research：Graph 按需单次运行	只有关系/多跳计划启用 Graph，rewrite 与补检不能重复遍历	researchGraphEnabled 只在 original query leg 为 true；subquery/supplement 均为 false；Graph 使用同一 published member/entity/relation/source-node/ACL 闭包。直接问题与无 Graph 计划为 zero-call	当前按需 Graph 契约已闭环	direct/relationship、single-leg、missing capability degradation、publication/ACL 回归	已完成	I9
RET-008	P0	Research：统一最终 Rerank	RRF 合并后使用知识库必配 rerank，不能由规划 LLM逐条打分	V3 在每个 evidence round 对完整 merged candidate window 调用 profile-scoped reranker 一次，threshold 后再取 Top K；generic outer rerank 跳过 Research，避免二次打分。V2 checkpoint replay 保留历史 PageIndex score domain	当前 V3 score 契约已闭环	profile factory identity、每轮 single-call、threshold/order、V2 zero-extra-rerank 回归	已完成	I9
RET-009	P0	Deep：普通混合召回	Deep 必须先得到 dense + FTS 融合候选，不能只查 Graph	Deep 先执行同一 published snapshot 的 dense/FTS normalized score fusion，再进入 Graph；published-deep-retrieval.test.ts 断言 base 两 leg 发生在 Graph seed/traverse 之前；Graph capability 缺失在任何 base leg 前抛稳定错误，仅影响 Deep	当前行契约已闭环	保留 Deep stage-order 与 Graph-off fail-closed 回归	已完成	R1
RET-010	P0	Deep：Graph 扩展	从 base 命中实体做 permission-scoped traversal，再检索/合并 graph candidates	PublishedGraphIndexRepository 按固定 publication 的 entity/relation member、generation、source node、ready projection member 与 document asset 做闭包；traversal 与二次 dense/FTS 使用同一 snapshot/permission scope，并有 timeout/fanout/maxNodes 上限	当前行 published Graph 契约已闭环	跨 publication/asset/generation/ACL/source-node 缺失负向测试与真实 PG probe	已完成	I0-3B3
RET-011	P0	Deep：统一最终 Rerank	base hybrid 与 Graph 扩展候选先合并，再只做一次 rerank	published-deep-retrieval.test.ts 完整证明 published dense+FTS → published Graph traverse → graph dense+FTS → ordinary/graph merge → 最外层一次 rerank；reranker 同时收到普通和 graph-only node，threshold/Top K 在其后	当前行 stage-order 契约已闭环	保留动态 provider identity/failure 的 I3 增强测试	已完成	R1
RET-012	P1	三模式 Top K	三种模式都在最终可比较分数阶段消费空间配置	空间 profile.topK 是最终 evidence 上限；Fast/Deep 在统一 rerank 后截取，Research V3 先保留 bounded multi-leg/RRF window，再在 profile rerank + threshold 后截取；各 leg 不被 final Top K 过早截断	当前行契约已闭环	三模式 Top K、100 边界、V3 multi-list candidate width 回归	已完成	R1/I9
RET-013	P1	三模式 Score Threshold	在定义的可比较 stage 过滤最终 evidence；过滤后生成器不可绕过	Fast/Deep/Research V3 都只接受 profile reranker 的 [0,1] score 并在 Top K 前过滤；V2 replay 单独保留 versioned semantic LLM score。过滤后的 evidence 是 answer generator 唯一输入并写 metrics	当前行契约已闭环	provider 非法 score、V3 threshold/order、V2 compatibility、三模式 evidence 回归	已完成	R1/I9
RET-014	P1	三模式 Reasoning model	最终回答、Auto、Research V3 planner/judge及 ingestion Summary/Outline/Graph 使用 space profile	生产不装配 deployment fallback；V3 planner/judge校验 frozen model identity与strict structured output，模型调用总数不随候选/文档增加；durable Graph构建仍读attempt frozen profile	当前 reasoning identity、凭据隔离和 bounded V3 calls闭环	first-document preflight、两空间隔离、planner/judge schema/model、Auto/answer/ingestion	已完成	I3/I7/I8/I9
RET-015	P0	三模式 Embedding model/vector-space	query 与 ingestion 使用同一 active space vectorSpaceId、实际 dimension；不写死 1536	compilation attempt 冻结 embedding/retrieval profile id、revision、digest 与 vectorSpaceId；发布锁内重验并把 exact tuple 写入 publication binding；query/retrieval-test 只解析该 frozen binding，空间 factory 不携带 deployment credential，embedding 输出长度与 profile dimension 严格校验；生产没有 fallback selection；模型变化走 full-vector-space rebuild/evaluation/联合 CAS，ANN gap 使用 exact fallback	当前 profile/head/vector-space、tenant credential 和原子一致性契约已闭环；运行时没有固定 1536 或全局 embedding fallback	7/384/768/1024/3072/4096 dynamic dimension、same-provider credential isolation、profile fence/binding、legacy backfill、migration failure/rollback、query mismatch 与 PG/TiDB publication tests 通过	已完成	I0-3C/I3
RET-016	P1	三模式 Rerank model	Fast/Deep/Research V3 均使用 space rerank model，每轮一次	published profile/capability snapshot 冻结 plugin/provider/model；生产仅注入 per-space factory。Fast/Deep 在各自完整候选集合后调用一次；Research V3 在 RRF 后调用一次，若发生唯一 supplement 则对 combined set 再调用一次；disabled/缺能力 fail closed，V2 replay不额外 rerank	当前三模式 rerank、凭据隔离和调用次数契约已闭环	dynamic provider identity/failure、Fast/Deep single-call、V3 per-round single-call、V2 compatibility、threshold/order	已完成	R0/I3/I9
RET-017	P0	Candidate ACL	dense/FTS SQL 先过滤，应用层再次过滤；Graph/Outline 也不得扩大权限	authorization guard 从 member/policy/API revisions 生成 immutable canonical candidate grants，明确丢弃 bearer scopes；Query、MCP、Agent、Research 只能使用该服务端快照；dense/FTS、PageIndex、Graph 均在 SQL closure 和应用层执行 required-scope subset 过滤；Document、Source、KnowledgeFS、direct published Graph 与 semantic operator 的公开入口也做 asset/node/path/entity 闭包，隐藏游标不回显，semantic 全局写只有在 bounded corpus 全部可见时才执行	当前 candidate ACL 契约已闭环	forged-scope、三模式 forbidden candidate、direct read/mutation、隐藏游标、shared semantic entity/community 与 scan-budget fail-closed 回归	已完成	I1
RET-018	P0	Space membership / API access 过滤	进入检索前校验 tenant + member role + API access，不能只靠 candidate ACL	Query/Research/MCP/Agent 和 trace/job/snapshot/bulk/compilation resource reads 共用 guard；interactive 校验 visibility/role，service_api/api_key/mcp/agent 还要求 API Access enabled；API key 每请求重查 revoke/expiry/member/policy；Research、AnswerTrace、Workspace、bulk 与 public compilation job 额外绑定 exact subject、access channel、snapshot revision 和 API key id	当前空间进入检索与派生结果的四层边界已闭环	outsider、viewer、跨成员、interactive↔API key、不同 key、API off/revoke/expiry 与 trace/job/snapshot 间接资源负向测试	已完成	I1
RET-019	P0	Async Research 权限与执行	job 只持久化服务端签发的权限快照与 frozen published runtime；worker 在执行时重验撤销/版本	admission 冻结同一 publication/retrieval/embedding tuple 和 concrete mode；worker 以 DB claim/lease/fence 执行。V3 持久化 planned、initial、supplemental、complete 边界，重试不重复已完成 planner/recall/rerank/judge；串行 mutation lane 同步推进 rowVersion，避免并发模型记账造成 lease 丢失。V2 checkpoint 只走 compatibility retriever	当前 durable权限、Auto冻结、V3恢复与V2兼容闭环	concurrent accounting、stage resume、retry/restart/revoke/delete、HTTP/MCP/Agent E2E 与 PG/TiDB replay	已完成	I1/R1/I3/I8/I9
RET-020	P0	Published snapshot 过滤	三模式只读取当前 published head 的 member IDs；head/member/实体不一致必须 fail closed	query-handlers.ts 在查询边界解析一次 frozen publication id/fingerprint/head revision 及 profile binding；strict repository 禁止缺 snapshot/tenant/permission scope；Fast projection、Research PageIndex、Deep Graph 均验证 exact member/generation/asset，publication 必须是 published 或查询开始后 superseded；legacy bootstrap/PageIndex/profile backfill 使用 durable CAS/lease	当前 published content + profile snapshot 契约已闭环	real PG/TiDB probe 覆盖 candidate/building/stale/cross-publication、空 member、profile mismatch 与 legacy binding	已完成	I0-3B3/I3
RET-021	P0	Production query fail closed	未配置 production retriever/query generator/profile 时返回 unavailable，不能退回 local scan 或部署默认模型	默认不创建 local node generator；无正式 query generator 返回 503；allowLocalQueryFallback、Research legacy runtime fallback、static embedding/rerank 只允许显式非生产测试/开发；生产 query/answer/retriever 装配只接受 frozen space profile factories，profile-less space fail closed/setup-required	当前 production fail-closed、无全局模型降级契约已闭环	unavailable、profile missing、静态 provider、global fallback source assertion、显式开发 opt-in 与 production config rejection 测试通过	已完成	R0/I6
RET-022	P1	Retrieval Test 可解释性	返回实际 mode、profile revision、各 leg 候选数、融合/Graph/PageIndex/rerank/threshold 与安全的过滤指标	dedicated endpoint 返回 resolved mode、完整 active retrieval/embedding profile、published publication id/fingerprint/head/projection revision、projection IDs、stage executed/skipped、dense/FTS/fusion/Graph/PageIndex/rerank/threshold/permission/projection metrics，以及 verified/disabled/not-required capability 状态	当前 bounded 可解释性契约已闭环；能力不满足时返回 503 而非伪造 degraded success；为避免 ACL oracle，不返回完整 member inventory、不可见 corpus 总量或 SQL 层隐藏候选总数	schema/executor/handler snapshot tests 覆盖三模式 stage、profile/publication provenance、capability fail-closed、secret/content allow-list 和 ACL filtering	已完成	I3/I6
RET-023	P1	Auto 智能选择检索模式	Auto 通过空间级 reasoning model 选择 Fast/Research/Deep，失败可追踪且不能退回语言/长度/关键词启发式	Query、Research plan/create 与 MCP 边界在授权后解析显式 Auto；调用 frozen published reasoningModel 的 tenant-scoped plugin-daemon provider，要求严格结构化 concrete mode。省略 mode 直接取 defaultMode，显式 concrete mode zero-call；timeout/provider/invalid/model mismatch 降级到 frozen defaultMode。lower retrieval stack 只接受 concrete mode，旧 CJK/混合语言/词数/关键词 heuristic 已删除。AnswerTrace 持久化 query.route 的 requested/resolved/resolver/model/prompt/duration/degraded/safe error provenance；Research create 将一次决策与 frozen tuple 持久化，retry/restart 不重判	当前 Auto 作为路由选择器的产品契约已闭环；它不是第四条执行管线	explicit zero-call、omitted default zero-call、LLM Fast/Research/Deep、invalid/timeout/provider/model mismatch fallback、caller abort、unauthorized zero-call、trace 脱敏、Research durable zero-reclassification 回归	已完成	I8

9. Quality / Evidence

ID	优先级	Figma 产品功能	后端需求	当前实现/证据	缺口	修复/验证	状态	迭代
QLT-001	P1	Evidence history	按 space 分页、搜索、时间筛选 trace；查看 passage/citation/各阶段 score	/quality/traces 已支持 cursor、query、from/to、mode、status；SQL 在 LIMIT 前绑定 tenant、exact subject 与当前 candidate grants，summary 返回 retrieval/rerank/final score、stage 与非密钥 profile/publication/vector-space provenance；详细 evidence 继续复用 subject-owned trace API	当前 history 契约已闭环	PostgreSQL/TiDB ACL-before-LIMIT、跨 subject、profile/score mapping 与 DTO allow-list 测试通过	已完成	I6
QLT-002	P2	Missing evidence dismiss	保存 actor、reason、status，支持 audit	/quality/traces/{traceId}/missing/{itemKey} 已实现 active/dismissed CAS，持久化 actor/reason/revision，并提供 history route	当前 dismiss/audit 契约已闭环	写入事务锁定 active space、fresh permission fence 与 exact trace visibility；revision/deletion/revoke 负向测试通过	已完成	I6
QLT-003	P1	Golden questions	CRUD、annotations、expected evidence、分页	Golden question CRUD/annotation 继续可用；Quality replay 会冻结 question/expected evidence，failed-query promotion 的 golden create 也在事务内重验 fresh durable write permission	当前 golden question 与 replay 关联闭环	guarded create 撤权前拒绝写入，公开 replay 仅返回 allow-list provenance/result	已完成	I1/I6
QLT-004	P1	Production bad cases	从 AnswerTrace 捕获 bad case，保存原因/tags/evidence	已建立 quality_bad_cases 与 quality_resource_history，支持 open/replaying/fixed/dismissed、CAS、replayRun 关联和审计 history；创建绑定 exact subject-owned visible trace	当前 bad-case lifecycle 契约已闭环	fresh permission、deletion、candidate ACL、cross-space replay link、revision 与历史唯一性测试通过	已完成	I1/I6
QLT-005	P1	Failed queries / triage / clusters	自动记录低置信度，分页、metrics、cluster、annotate/promote/dismiss	capture 已持久化 tenant/requester/channel/snapshot revision/required scope/revision；list/get/metrics/cluster/triage/annotate 全部 exact requester scoped，ACL 在 LIMIT/GROUP BY 前；旧 provenance-free 行 fail closed；Overview 与 trends 复用同一边界	当前 failed-query 产品与安全契约已闭环	撤权/删除 mutation、partial grant、跨 subject、pagination/aggregation oracle、promotion side-effect permission 与 PG/TiDB SQL 测试通过	已完成	I6
QLT-006	P1	Replay	durable queued/running/passed/failed/canceled；保存输入 profile revision、trace diff、evidence 变化	0024 建立 replay run/items/outbox、lease/checkpoint/retry/cancel 与 frozen published/profile/model/vector-space snapshot；worker 通过真实 RetrievalTestExecutor 分别执行 Fast、Research、Deep，并保存 evidence diff、metrics 与 trace	当前 durable replay 契约已闭环	create/cancel/retry 均为 active-space/deletion lock + fresh durable write fence；撤权、lease loss、restart/idempotency、terminal aggregation、三模式执行与 secret redaction 测试通过	已完成	I6
QLT-007	P2	Quality trends / baseline comparison	outcome trend、top unanswered、版本基线、模式/模型切片	/quality/trends 已按时间窗返回 current/baseline pass rate、failed queries、bad-case state、top unanswered，以及 mode/model/profile revision slices	当前 trends/baseline 契约已闭环	tenant、exact subject、candidate grants、from/to 与 bounded top limit 均下推 SQL；窗口与聚合测试通过	已完成	I6

10. 后端实施结果与验证轨迹

本节只追踪后端检索、索引与发布一致性，不包含任何前端实现。当前已经落地：

1. RET-002～RET-004：Fast 严格执行 published dense + indexed FTS → per-leg normalized score merge → 可选的一次 rerank → threshold → Top K；启用 rerank 时 public score 等于 reranker score，关闭时等于 [0,1] normalized final score；缺关键 capability/snapshot/permission 时 fail closed。
2. RET-005～RET-008：Research V3 对 direct query 零 planner-call、complex query 单 planner-call；执行 published dense/FTS、deterministic Outline 与按需单次 Graph recall，以 weighted RRF 合并后由 profile reranker 产生最终 score，再做一次 evidence-set judge；不按文档或树层级调用 LLM。
3. RET-009～RET-011：Deep 严格执行 published dense+FTS → published Graph expansion/second recall → merge → 一次统一 rerank；Graph capability 缺失只让 Deep fail closed。
4. RET-012/RET-013：Top K 与 mode-final [0,1] threshold 在三种模式的正确最终阶段执行，过滤后的 evidence 不会被 answer generator 绕过。
5. DOC-005/DOC-010/RET-020：query-start immutable publication snapshot、candidate generation、完整 member receipt、candidate-only evaluation 与 head CAS 已接线；building/failed/stale/cross-publication 行不可见。
6. legacy 空间 publication bootstrap 与 PageIndex upgrade backfill 使用 durable ledger、lease token、fence、retry/supersede；Research readiness 不会阻断无关 Fast 模式。
7. TiDB FTS 改为 (space, term_hash, projection) indexed postings；新 projection 与 posting 同事务写入，legacy 数据由 per-space durable cursor/lease/fence worker 有界回填；Fast/Deep/Research V3 在完成前返回稳定 503；不再使用 INSTR/LIKE 扫描。
8. PostgreSQL 的最终 schema 是 typmod-free vector，TiDB 使用动态 VECTOR，均保留用户模型实际维度。已发布历史 0001 为保持 migration checksum 不变仍含 vector(1536)，但 0002 会在正式读写前立即删除旧 HNSW 并转换为 typmod-free vector；运行时没有 1536 约束。
9. Publication 最终事务同时做 member receipt 正向和 generation node→FTS/dense/TiDB posting 反向闭包校验；legacy zero-document complete、PageIndex lease expiry、TiDB member mutation rollback/replay 均 fail closed。
10. TiDB 0012 对历史 TEXT key、generated column、匿名跨-generation unique index、CHECK/FK 漂移做无损前向修复；重复、孤儿或过长数据会阻止迁移，不会被删除或静默合并。
11. 0013 建立 tenant/space scoped member、visibility policy、API Access、hash-only API key 与 durable permission snapshot；所有 nested Space route 及 trace/job/research/snapshot/bulk 间接资源路由统一执行 membership/role/API Access guard，检索只接受服务端签发的 candidate grants。
12. 0014 将 Source 凭据切换为 opaque credentialRef + AES-256-GCM SecretStore；每个外部 secret 写入都先有 durable lifecycle reservation，Source/ref 的激活、轮换、撤销和 legacy backfill 使用原子事务及 lease fence；retired/deleted tombstone 会持续复扫晚到写入，connector 原始异常不会进入 HTTP、metadata 或 scheduler state。
13. 0015 将 Research job/outbox/partial result/progress 持久化；job 状态、outbox 与 progress 事件原子写入，worker 使用数据库 claim/lease/fence 并在 claim 与每个 next 前重验权限 revision；撤权、关闭 API Access、lease 丢失或重启时均 fail closed，公开响应不暴露 worker/lease/fence/ACL provenance。
14. 0016 为 public compilation job 持久化 exact requester 与 durable permission snapshot provenance；bulk/compilation get/cancel/retry 重验 subject、channel、snapshot revision、API key id/revoke/expiry 和当前 candidate asset closure。Document、Source、KnowledgeFS、direct Graph、semantic operator 的公开读写同样执行服务端 candidate closure，隐藏项不会通过 cursor、job 或 operator diagnostics 旁路泄漏。
15. 0017 将 Space/Source/Document 删除改为 durable state machine：请求先写 lifecycle/tombstone/job/item/outbox，worker 以 lease/fence/checkpoint 可恢复推进，并在完成事务内证明数据库、对象、cache、trace、evidence 与 publication 无残留。
16. 所有生产对象写入均持有空间级 deletion admission；PostgreSQL 使用 FOR SHARE，TiDB 8.5 使用真实 FOR UPDATE，并在 identity lock 后通过 current locking read 检查 active deletion，关闭 RR 旧快照绕过。旧 compilation/research/sync/backfill/retrieval worker 同样受 tombstone、mutation lease 与 publication CAS 阻断。
17. 0018～0020 建立 immutable embedding/retrieval profiles、profile/publication binding、migration run/outbox/lease 和 legacy manifest backfill；当前新建/未激活空空间先持久化 pending model config 且零 daemon，首文档 durable compilation 再执行 catalog + active invocation preflight，将实际 embedding dimension/metric/vector-space 写入能力快照/profile 并绑定 attempt；已发布变更仍走 candidate migration，profile-less legacy 空间 fail closed。
18. 0021 建立 Source provider/connection/OAuth、crawl/import/sync/bulk durable workflow 控制面；PKCE/token 只存 SecretStore ref，provider cursor/Drive continuation token 透传，Source update 经 Logical Document candidate 与 publication 联合激活。
19. 0022 建立 Logical Document/Revision、processing task、chunk state candidate、metadata namespace 和 versioned settings/reindex；Document/Source candidate 写入与最终 publication 均重验 durable permission、deletion 与 candidate grants。
20. 0023 提供 Space icon、Overview stats/attention/activity/health；所有聚合在 SQL LIMIT/GROUP BY 前执行 tenant、space、subject 与 candidate-grant 过滤。
21. 0024 提供 Evidence history、bad case、failed query、Golden promotion、durable Quality replay/trends；创建/变更/replay 使用 fresh permission 与 deletion fence，worker 冻结 published profile/model/vector-space tuple。
22. Dedicated Retrieval Test 使用与线上查询相同的 snapshot/profile/grants/retriever，明确验证 Fast hybrid+rerank、Research Evidence V3 dense/FTS/Outline/(optional Graph)+RRF+rerank、Deep hybrid+Graph+rerank，并返回 bounded stage provenance而不泄漏隐藏 ACL 总量。
23. 显式 Auto 在 Query/Research/MCP 请求边界通过空间 frozen published reasoning model 选择 Fast/Research/Deep；省略 mode 直接使用 defaultMode。旧 CJK/混合语言、长度、词数与关键词 heuristic 已从 planner 删除，LLM 失败安全降级到 frozen default，并在 query.route 记录 脱敏 provenance；durable Research 只判断一次并持久化 concrete mode。

I1/I2 历史批次验证证据（保留用于审计实施轨迹）：

• API：1892 passed / 3 skipped；API app：153 passed；Database：43 passed；Adapters：116 passed / 1 skipped；Core：49 passed；Embeddings：26 passed；workspace pnpm test（20/20 tasks）、pnpm typecheck（20/20 tasks）与 Swagger 测试均通过。
• PostgreSQL 16 + pgvector 与 TiDB 8.5 均从空库顺序执行 0001 → 0017 成功；整份 0017 replay 与 migration artifact drift check 均成功。manifest 最终只保留 tenant + space 复合 FK；历史跨租户错配会阻断迁移。两种数据库的 writer-first、delete-commit-first、delete-rollback-first 锁序均通过真实并发验收。
• PostgreSQL 实探针覆盖 Fast/Research/Deep 的 publication/member/generation/ACL 负向；TiDB 实探针覆盖 old-TEXT 升级、durable FTS discovery/lease/cursor/final closure、publication member rollback/idempotent replay、lookup index、CHECK 与跨空间复合 FK。
• workspace typecheck、migration artifact check、Biome 与 git diff --check 通过。

上述测试数字只对应当时的 I1/I2 历史快照，不代表最终提交的测试总数。I3～I8 已按第 17～23 项完成；包含本矩阵的最终提交以 figma-backend-iteration-plan.md 最新执行记录、migration artifact check、全 workspace test/typecheck 和定向 PG/TiDB 验证为权威证据。

11. 迭代完成顺序

顺序	覆盖 ID	目标	退出条件
R1（已完成，V2 compatibility）	RET-005、RET-006、RET-012、RET-013、RET-020	published semantic Value Search、LLM PageIndex tree score 与 bounded final evidence	保留用于 retained V2 checkpoint replay；fresh online path 由 I9 取代
I0-3B3/3C（已完成）	DOC-005、DOC-010、RET-010、RET-020	published head/member read cutover、candidate-only evaluation 和原子发布	building/failed/stale generation 三模式不可见；head/member 不一致 fail closed；profile/head 联合迁移随后由 I3 完成
I1（已完成）	CRE-004、SET-002、SET-003、SRC-001/002、RET-017～RET-019、QLT-003	Space ACL、member role、API access、SecretStore、服务端权限快照、durable Research 权限重验	tenant + membership + API access + candidate ACL 四层负向 E2E、凭据泄漏/晚写清理回归、PG/TiDB clean migration 与 rolling-upgrade closure 均通过
I2（已完成）	SET-010、SRC-001、DOC-009	Space/Source/Document durable deletion	任意阶段故障可重试；DB/Object/cache/trace/evidence 无残留；旧 worker 不能重发索引；PG/TiDB 锁序与迁移 replay 已验证
I3（已完成）	CRE-001/003/006、SET-001/004～009、RET-001/014～016/022	RetrievalProfile 完整迁移、模型 catalog/preflight、profile/head 联合快照、动态维度 ANN、embedding 原子迁移	所有 active 空间级模型与检索设置由 frozen published profile 消费；已发布 profile 更新可审计并发安全；profile/head/vector-space 与 publication 一致；任意 dimension 不写死 1536
I4（已完成）	SRC-003～SRC-010	Provider/Connection、OAuth、crawl preview、durable sync、版本与 bulk control	crawl/sync 重启可恢复，列表有 cursor，credentials 只存 ref，远端版本经 Logical Revision 联合发布
I5（已完成）	DOC-001～DOC-008	Logical Document/Revision、逐文件 admission、Tasks/Chunks/Metadata	active revision CAS、历史/rollback、chunk/metadata/settings candidate API、任务 E2E与最终权限零副作用测试完成
I6（已完成）	CRE-002、OVR-001～OVR-004、QLT-001～QLT-007	Overview、Evidence history、Quality replay/trends、审计	bounded tenant/space/requester/grant scoped API、durable permission/deletion fences、replay worker 与迁移/回归测试均已落地
I7（已完成）	CRE-003/004/006、SET-004～006/011、DOC-005、RET-014/015	空空间 pending model config、零 daemon create/settings、首文档惰性 profile 激活	create不因daemon阻塞；首文档以 leased attempt验证并原子激活 profile；dimension/vector-space来自实际响应；已发布变更走migration；Research V3消费相同frozen tuple
I8（已完成）	SET-007、RET-008/014/019/023	Auto LLM 路由、可追踪失败降级与 durable Research 决策冻结	只有显式 Auto 调用 frozen space reasoningModel/plugin-daemon；省略 mode 与显式 concrete mode zero-call；无语言/长度/关键词 heuristic；失败回落 frozen default；Query trace 可审计且 Research retry/restart 不重判
I9（已完成）	SET-005～009、RET-006～008/012～016/019/022	Research Evidence Retrieval V3	fresh Research无per-document/tree LLM；direct最多1次judge，complex最多planner+judge；dense/FTS/Outline/optional single Graph经RRF和profile rerank；最多1次supplement；四阶段checkpoint恢复与V2 compatibility回归通过

12. 状态维护约定

• 每个修复 PR/commit 必须在测试通过后更新对应稳定 ID 的“当前实现/证据”“状态”和“迭代”，不得复制出新编号。
• 已完成 必须至少包含实现文件和测试文件证据；只有 schema、接口或 mock 不算完成。
• 任何模式实现变更都必须同步更新 RET-002～RET-016 的调用次数/顺序测试。
• 任何 publication 变更都必须同步更新 DOC-005、DOC-010、RET-010、RET-015、RET-020。
• 任何权限变更都必须同步更新 CRE-004、SET-002/003、RET-017～RET-019，以及 Source/Document/Quality 的负向测试。
• 本矩阵不产生前端任务；仓库外调用方只依赖这里定义并验证过的后端契约。