ADR-004：数据先存后处理，原件不可变

• 状态：Accepted
• 日期：2026-11-11
• 关联：docs/architecture/卓安Claw-数据存储与处理架构-v1.0.md、ADR-003

背景

卓安Claw 处理刑事案卷，单案约 1GB、单所约 1,000 案/年，案卷含 C 类敏感信息。Agent 需要 OCR、全文检索、实体抽取、摘要与引用；这些处理慢、会失败、会随模型/引擎升级而变化。如果先处理再存，只保留处理结果，会丢失原件、证据链和可追溯性；如果存完不处理，Agent 无法使用。

决策

1. 先存储、后处理：上传时同步写不可变原件（SHA-256 内容寻址）+ 最小清单 + 待处理任务；解析/OCR/抽取/索引全部异步。
2. 原始层是唯一事实源：原件永不原地修改；修订新增版本；删除走审批、墓碑、保留期。
3. 派生层可重建：文本、页码映射、实体、摘要、向量索引都按 blob_id + artifact_type + pipeline_version 版本化，可重跑、可对比、可回滚。
4. 业务事实先落、指标后算：线索/案件/节点/财务先写事实与事件，经营指标异步汇总。
5. AI 产物先草稿、律师确认后生效：Agent 不能直接改写业务事实。
6. C 类不出所：原件与全文留在本机/私有云；外部模型只接受必要片段，需脱敏、审批、审计；庭立方平台只拿元数据、状态、聚合指标和脱敏知识。

备选方案

A. 先处理再存（只存结果）

拒绝。原因：丢失原件与证据链；OCR/模型错误不可追溯；无法重跑；C 类全文可能先出所；处理失败导致上传失败。

B. 只存原件，使用时同步处理

拒绝。原因：每次打开都重复 OCR/解析，慢且贵；无法建索引；Agent 体验不可用；并发下资源不可控。

C. 先存原件 + 异步派生（采纳）

接受。代价是需要任务队列/worker、存储容量、哈希回填、状态展示与失败处理；换来可靠性、可审计、可重跑和数据主权。

后果

• 需要新增 zhuoan_doc_blob / zhuoan_doc_version / zhuoan_ingest_job / zhuoan_doc_artifact / zhuoan_doc_event；
• 上传接口从“同步处理”改为“202 + 状态轮询”；
• Agent 只能读 ready 的派生结果，引用必须带 blob_id + page；
• 需要单机 worker、幂等键、重试/死信、重新解析入口；
• 需要容量规划与备份策略；派生层可不备份，原件必须备份；
• 需要法务复核开源许可证（Paperless/Immich/MinIO 为 GPL/AGPL，MinerU 有附加条款）。

后续

1. V1 侧表 + 上传改造 + 单机 worker + FTS5；
2. 现有 document 哈希回填与映射；
3. C 类外部模型拦截与审计；
4. 平台数据边界与指标口径；
5. 私有云阶段再评估对象存储、pgvector、Temporal。