docs: add archive operator library plan and TDD implementation roadmap (!4) · Merge requests · public_collaboration / Platform Core Public

Merged yujiwen requested to merge feature/daft-native-operators into master Jul 07, 2026

Summary

在 backend/foundation 落地 Archive Operator Library（设计 11/12 号里程碑 M0–M7），建立 contracts（C0–C4）+ Daft-native operators + YAML 驱动 pipeline 的完整基线；支持 Pipeline A（Excel 文本质检） 与 Pipeline B（manifest → OCR → 标题） 端到端运行，并完成测试模块化、算子命名 SSOT 与文档对齐。

规模：34 commits · 174 files · +12,148 / −249 lines

背景与目标

将档案 AI 流水线从「散落脚本」收敛为 可配置、可组合、可测试 的算子库
以 canonical 列名 / projections 为 DataFrame SSOT，以 YAML + run_pipeline 为编排入口
覆盖教学链路（Pipeline A）与图像 OCR 链路（Pipeline B），为后续接入真实 OCR/LLM 预留 provider 边界

主要变更

1. Contracts（C0–C4）

层级	内容
C0–C2	`ontology/`、`projections/columns/`、`projections/*_flat.py` — 列名与扁平投影 SSOT
C3	`contracts/runtime/` + `runtime/bridge.py` — 运行时实体与 UUID 边界校验
C4	`operators/*/specs.py` canonical defaults；`test_deprecated_terms` 禁止泛化文件名/旧列名漂移

2. Pipeline 编排（M0 + 硬化）

config_loader / executor.run_pipeline / graph.compose_plan_with_outputs
Sources：inline、excel、json、filesystem_manifest（含 mapping.py 列映射与 doc_id 别名）
Sinks：memory、parquet
Checkpoint M5.4：{step_op}.staging → 原子 promote + manifest.json；checkpoint 后 lazy root 重切
Public API：稳定 from pipeline import ...；config fail-closed；merge_issues 可组合默认

3. 算子（15 个 registry steps，M1–M7）

域	算子	里程碑
tabular	`dedupe_by_key`、`validate_required_fields`	M1
quality	`llm_typo_check`、`merge_issues`	M2
text	`zh_t2s`	既有
archive	`assign_document_ids`、`normalize_archive_no`、`normalize_org_name`	M4 / M7
document	`pages_from_manifest`	M4
image / ocr / extract	`preprocess`、`recognize_text`、`title`	M5
sensitive / classify	`rule_scan`、`retention_period`	M7

Pipeline B 关键语义：page_table_route — 有 page_table 时 M5 步骤路由到 side table；REPLACES_SIDE_TABLES 避免 concat 污染。

4. 命名 SSOT 重构（PR-R1–R3）

旧	新（canonical）
`ids.py`	`assign_document_ids.py`
`dedupe.py`	`dedupe_by_key.py`
`validate.py`	`validate_required_fields.py`
`ocr.recognize`	`ocr.recognize_text`（`ocr.recognize` 为 deprecated 别名，`DeprecationWarning`）

tests/operators/test_registry_naming.py 强制 module / step 命名一致
RecognizeTextSpec = OcrRecognizeSpec 类型别名（OcrRecognizeSpec 为 M5.2 遗留名）

5. 测试布局模块化（PR-1–3）

tests/
├── contracts/     # 投影、bridge、deprecated terms
├── sources/       # excel/json/mapping/filesystem_manifest
├── operators/     # 按 domain 分组
├── pipeline/      # config、e2e、checkpoint、compose
├── sinks/
└── providers/

6. 文档与工具

新增/更新：docs/design/11_*、12_*、13_contracts_ontology.md、docs/OPERATORS.md
.cursor/skills/platform-foundation-dev/ — foundation 开发 skill + sub-agent 工作流
设计 08/11/12 与 golden YAML 已对齐 ocr.recognize_text 及重命名模块路径

权威配置与验收

Pipeline	权威 YAML	说明
A	`eval/golden/cases/pipeline_a_excel_text_quality.yaml`	Excel → dedupe → validate → zh_t2s → typo → merge
B	`eval/golden/cases/pipeline_b_image_ocr.yaml`	manifest → assign_ids → pages → preprocess → ocr.recognize_text → title

破坏性 / 迁移说明

ocr.recognize → ocr.recognize_text：旧 YAML 仍可用但会 DeprecationWarning；checkpoint 目录名随 op 字符串（ocr.recognize/ vs ocr.recognize_text/），无自动 rename
模块重命名：直接 import 旧路径 dedupe.py / recognize.py 等会失败，请改用 registry suffix 对应文件名
OCR 输出契约：page_table 仅写 ocr_text、layout_locator_*、ocr_confidence；provider/cache_hit 为 provider DTO 内部元数据，非 DataFrame 列

Test plan

cd backend/foundation

# 单元测试（254）
uv run pytest tests/ -q

# Golden eval（9）
uv run pytest eval/golden -m eval -q

# 命名/废弃项契约
uv run pytest tests/contracts/test_deprecated_terms.py -q
uv run pytest tests/operators/test_registry_naming.py -q

# Lint
uv run ruff check .

手动冒烟（README 快速开始）：

Pipeline A：load_pipeline_config('eval/golden/cases/pipeline_a_excel_text_quality.yaml') → run_pipeline
Pipeline B：同上 pipeline_b_image_ocr.yaml，确认 page_table 行数与 extracted_title

不在本 MR 范围

真实 PaddleOCR / 生产 LLM 接入（mock provider + # TODO(production)）
backend/app/ 主应用与 Celery/Ray 集成
设计 10 号 Excel 文档中部分历史 dedupe.py 路径（tabular 域已迁移，10 号未全量 sweep）

建议 Review 重点

pipeline/registry.py — 15 steps 注册与 deprecated alias 行为
pipeline/graph.py + operators/core/page_table_route.py — Pipeline B side table 路由
pipeline/checkpoints/parquet.py — staging 原子写与 resume 预留
contracts/runtime/bridge.py — C3 UUID 校验边界
eval/golden/cases/pipeline_*.yaml — 权威配置是否与文档一致

Target branch: master
Source branch: feature/daft-native-operators