RAG/docs/03-implementation-plan.md

实施计划、代码规范与验收标准

项目	内容
计划周期	10–14 周（含 300 题正式标注与盲测）
开发方式	小步可验证、每阶段提交并推送
主分支	main
质量门禁	格式、lint、类型、测试、密钥扫描、文档同步

1. 仓库结构规范

RAG/
├── README.md
├── SECURITY.md
├── CONTRIBUTING.md
├── AGENTS.md
├── Makefile
├── compose.yaml                 # 实现阶段创建
├── .env.example                # 只能有占位符
├── .githooks/
├── .gitea/workflows/
├── backend/
│   ├── Dockerfile
│   ├── pyproject.toml
│   ├── alembic.ini
│   ├── migrations/
│   ├── app/
│   │   ├── main.py
│   │   ├── api/v1/
│   │   ├── core/
│   │   ├── domain/
│   │   ├── ports/
│   │   ├── services/
│   │   ├── adapters/
│   │   │   ├── bailian/
│   │   │   └── parsers/
│   │   ├── persistence/
│   │   ├── workers/
│   │   ├── tools/
│   │   │   ├── provider_smoke.py
│   │   │   ├── seed_demo.py
│   │   │   ├── verify_index.py
│   │   │   └── run_evaluation.py
│   │   └── prompts/
│   └── tests/
│       ├── unit/
│       ├── integration/
│       └── contract/
├── frontend/
│   ├── Dockerfile
│   ├── nginx.conf
│   ├── package.json
│   ├── src/
│   │   ├── api/
│   │   ├── components/
│   │   ├── features/
│   │   ├── hooks/
│   │   ├── pages/
│   │   ├── routes/
│   │   ├── styles/
│   │   └── types/
│   └── tests/
│       ├── unit/
│       └── e2e/
├── docs/
│   ├── 00-overall-design.md
│   ├── 01-data-and-evaluation.md
│   ├── 02-deployment-and-security.md
│   ├── 03-implementation-plan.md
│   └── adr/
├── data/
│   └── README.md
├── ops/
│   └── postgres/init/            # 数据库扩展与分权角色初始化
└── scripts/
    ├── check-secrets.sh
    └── check_markdown_links.py

空目录只作为当前结构承诺；开始实现某模块时删除对应 .gitkeep 并增加真实代码和测试。

2. 后端代码边界

2.1 依赖方向

api / workers
    -> services
        -> domain
        -> ports (protocols)
adapters / persistence
    -> implement ports

规则：

• domain/ 不 import FastAPI、SQLAlchemy、OpenAI SDK 或具体解析库；
• ports/ 定义外部模型、解析、存储和仓储协议；
• services/ 编排用例，通过接口调用外部能力；
• adapters/ 封装百炼、PDF/OCR、文件存储；
• persistence/ 负责 ORM、仓储和事务；
• api/ 只处理鉴权、DTO、状态码和调用用例；
• workers/ 只领取任务、调用用例和更新租约；
• Prompt 文件独立版本化并计算哈希，不散落在控制器字符串中。

2.2 关键接口

class EmbeddingProvider(Protocol):
    async def embed_documents(self, texts: list[str]) -> list[list[float]]: ...
    async def embed_query(self, text: str) -> list[float]: ...

class Reranker(Protocol):
    async def rerank(self, query: str, documents: list[str], top_n: int) -> list[RankedItem]: ...

class Generator(Protocol):
    async def stream_answer(self, request: GroundedAnswerRequest) -> AsyncIterator[GenerationEvent]: ...

class DocumentParser(Protocol):
    def parse(self, source: StoredDocument) -> ParsedDocument: ...

适配器契约要保留 request ID、usage 和耗时，但领域层不依赖供应商响应对象。

2.3 Python 质量

• Ruff 统一格式和 lint；
• mypy 或 pyright 做严格类型检查；
• pytest + coverage；
• 时间使用带时区 UTC，展示层转 Asia/Shanghai；
• UUID 作为外部资源 ID；
• 金额和精确数值不用二进制浮点做业务比较；
• 异常转成稳定错误码，不把内部堆栈返回前端；
• 所有外部调用显式 timeout、并发上限和取消传播。

3. 前端代码边界

3.1 Feature 结构

features/chat/
  api.ts
  types.ts
  hooks.ts
  components/
  pages/
  tests/

documents、retrieval、evaluation 使用同样结构。通用按钮、来源卡片基础组件放 components/，业务组合留在各 feature。禁止把所有请求、状态和页面堆在单个 App.tsx。

3.2 TypeScript 质量

• TypeScript strict；
• ESLint + Prettier；
• API 类型从后端 OpenAPI 生成或由共享 schema 校验；
• TanStack Query 管理服务端状态，局部 UI 状态才用组件状态；
• Vitest/Testing Library 做单元与组件测试；
• Playwright 做上传、问答、引用和失败重试 E2E；
• SSE 重连、取消和错误状态必须测试；
• Markdown 渲染必须清理 HTML。

4. 阶段计划

每个阶段都必须形成“功能 + 测试 + 文档 + 提交 + 推送”的闭环。

截至 2026-07-13，核心 synthetic 上传→解析→审核→向量化→检索链已在 Docker 中连续两次 通过，当前门禁记录为 296 项后端测试和 53 项前端测试。以下阶段描述仍是最终 Definition of Done，不因部分能力提前落地而降低验收标准；实时完成度和剩余项以 04-project-todo.md 为准。

阶段 0：仓库、安全和设计基线

交付：

• 规范目录、README、贡献和安全规则；
• .gitignore、Secret 扫描钩子和 Gitea 工作流；
• 总体、数据评测、部署安全、实施计划和 ADR；
• 初始化远端仓库并推送。

验收：

• make verify-design 通过；当前阶段只验证文档、相对链接、diff 和密钥，尚不声称存在应用 lint/类型/测试结果；
• 工作树没有真实 Key、真实工作空间地址或受限数据；
• 所有 Markdown 链接和目录入口可定位；
• 第一笔提交推送到 main；Gitea Actions 仅在远端 runner 首次成功后才可称为已验证。

阶段 1：模型与数据库 PoC（1–2 天）

交付：

• 轮换后 Secret 注入；
• 最小后端 Python 包、backend/Dockerfile 和依赖锁定；
• 最小 Compose db + migrate + provider-smoke，以及数据库角色初始化脚本；
• 确定文档族 split 规则、盲测保管人/受控凭据和“盲测用于调参即退役”规则；
• Embedding/Rerank/Chat 三个独立适配器；
• provider_smoke.py；
• pgvector 1024 维表与迁移；
• 20 条虚构文本的写入/检索/重排测试。

验收：

• docker compose up db migrate 可在空 volume 上建立扩展、分权角色和表；
• docker compose run --rm provider-smoke 可独立执行三模型探测；
• docker compose run --rm seed-demo 可完成 20 条虚构数据写入、检索和重排；
• Key 不出现在日志、异常、镜像历史和 Git；
• Embedding 返回 1024 维，批次下标正确；
• Rerank URL 与响应下标正确；
• Chat 关闭思考可流式返回；
• 重复运行 seed 不增加数据。

建议提交意图：Prove the selected model chain before building product workflows。

阶段 2：扩展为完整工程骨架（3–4 天）

交付：

• 在阶段 1 的最小后端/数据库 Compose 上增加 FastAPI、React、Nginx 和 worker；
• /health/live、/health/ready；
• 数据库任务租约；
• Worker maintenance loop、advisory-lock reaper 与 fencing 恢复测试；
• OpenAPI 客户端生成；
• 一键 Compose。

验收：

• 空白机器按文档启动；
• migration 只执行一次且失败会阻止 API；
• 只有 Web 端口暴露；
• Docker 重启数据保留；
• 强杀任务 Worker 后，有剩余次数的任务可恢复、耗尽任务进入 FAILED、旧租约不能提交；
• API/前端 lint、类型和测试通过。

阶段 3：数字文档入库（1 周）

交付：

• PDF/DOCX/TXT/Markdown 上传；
• 权利元数据门禁；
• 冻结 corpus manifest 与文档族 60/20/20 划分，正式盲测标签继续由保管人隔离；
• 数字 PDF 页码/章节解析；
• 结构化切分；
• 批量向量化、检查点和版本激活；
• 文档状态 UI。

验收：

• 重复文件/任务幂等；
• 中途终止后恢复；
• 100% searchable 切片可追溯当前文档版本和页码；
• 预期切片数等于非空向量数；
• 删除后立即不能检索。

阶段 4：检索与重排（1 周）

交付：

• pgvector 精确和 HNSW 检索；
• 权限/知识库元数据过滤；
• qwen3-rerank；
• 邻接补全、去重和上下文预算；
• 检索实验室。

验收：

• 100 组语义三元组门槛达标或有错误报告；
• 初召回、重排结果和耗时可解释；
• ANN Recall@10 与精确基线对比；
• 未授权文档在候选生成阶段被排除。

阶段 5：生成、引用和问答 UI（1 周）

交付：

• deepseek-v4-flash SSE；
• 证据 Prompt；
• 引用编号验证；
• 会话、来源卡片、页码定位、反馈；
• 无答案与模型失败降级。

验收：

• 用户取消会终止下游请求；
• 模型自造引用被拦截；
• 证据不足题可以拒答；
• LLM 失败仍能显示检索结果；
• Prompt Injection 回归样例不改变系统行为。

阶段 6：OCR、表格与数据质量（1–2 周）

交付：

• 扫描页检测和可选 OCR profile；
• OCR 置信度复核队列；
• 表格 JSON/Markdown/语义行；
• 数值、单位、地质术语校验；
• 图件挑战集边界提示。

验收：

• 金标准页 CER、术语和数值指标可计算；
• 跨页表/合并单元格有失败而非静默错位；
• OCR 原文和修订文本都保留；
• 图件问题不会被当作已可靠支持。

阶段 7：验证集与消融实验（3–4 周）

交付：

• 至少 300 题（构建/开发/盲测各 100）的源证据锚点及 run-specific qrels；500 题仅在人力充分时扩展；
• 双人审核和一致性统计；
• union pooling、未判定候选补标、Hit/CompleteHit/MRR/nDCG、忠实度、引用和拒答指标；
• 维度、切片、Rerank、上下文等消融；
• 运行配置、预测、指标和错误分类。

验收：

• 测试集哈希冻结；
• Gold 问答未进入知识库；
• 正式盲测只用于最终结论；一旦结果用于调参，该集合立即退役为开发集并更换新的未见盲测集；
• 所有论文图表可由脚本重建；
• 指标带分层结果和置信区间。

阶段 8：安全、备份、性能和论文（1 周）

交付：

• RBAC、上传限制、限流、审计；
• 数据库/文件备份与恢复演练；
• p50/p95、并发、费用报告；
• 演示脚本、失败案例、局限性；
• 最终部署和答辩文档。

验收：

• 恢复到空白环境并通过固定 20 题冒烟；
• Secret 扫描和镜像检查通过；
• 端到端 p95 和错误率有实测；
• 论文不夸大图件、预测和专业结论能力。

5. 测试矩阵

层级	内容
单元	规范化、切分、哈希、下标映射、分数排序、引用校验、任务状态机
集成	PostgreSQL/pgvector、迁移、任务租约、文件卷、备份恢复
契约	百炼 Embedding/Rerank/Chat 请求响应、错误码、超时和限流
端到端	上传 -> READY -> 检索 -> 重排 -> SSE -> 引用 -> 反馈
安全	Secret、越权检索、路径穿越、恶意文件、XSS、Prompt Injection
数据质量	OCR CER、表格数值、页码追溯、重复和版本冲突
性能	入库吞吐、查询 p50/p95、ANN Recall、并发和成本
评测	检索、生成、引用、拒答、分层和消融

外部百炼契约测试分为：默认 CI 使用 fake server，不花费 Token；受控的手动/定时环境使用真实 Key。真实调用测试不得在外部贡献者 PR 自动执行。

6. Definition of Done

任何功能阶段标记完成前必须满足：

1. 范围内功能工作，失败路径可见。
2. 新行为有回归测试。
3. Ruff/类型/pytest、ESLint/TypeScript/Vitest 等适用门禁通过。
4. make verify 密钥和 diff 检查通过。
5. 迁移可向前应用，必要时有回滚/恢复说明。
6. API、配置和数据格式文档已更新。
7. 不新增未说明的依赖、服务或权限。
8. 运行证据和剩余风险写入阶段记录。
9. 使用 Lore 提交信息提交。
10. 推送远端并确认提交可见。

7. 提交和推送协议

7.1 频率

• 每个阶段至少一个可独立回滚的提交；
• 大阶段按数据库、后端、前端、测试拆成少量有意义提交；
• 不为每个微小文件保存制造无意义提交；
• 在“验证通过的过程点”提交，而不是未测试半成品；
• 当前阶段结束后立即推送；后续每个阶段同样执行。

7.2 Lore 示例

Establish a safe and reproducible foundation for the RAG project

The repository begins with the architecture, data governance, evaluation,
and secret-handling contracts required before model calls or corpus ingestion.

Constraint: Real provider credentials and restricted geological data must never enter Git
Rejected: Add runnable placeholder services | would imply unverified implementation
Confidence: high
Scope-risk: narrow
Directive: Run make verify before every commit and update ADRs for architecture changes
Tested: Documentation checks, secret scan, git diff validation
Not-tested: Application runtime has not been implemented in the design stage

7.3 推送失败

网络或远端认证失败时：

• 本地提交仍保留，记录失败原因；
• 不把 Token 写进 remote URL；
• 使用系统 Git Credential Manager/SSH agent；
• 恢复连接后只推送已验证提交；
• 不用关闭 TLS 验证或把凭证明文写入脚本绕过问题。

8. 最终答辩演示脚本

1. 展示仓库 Secret 防护和无密钥配置。
2. docker compose up -d --build 启动并展示健康状态。
3. 上传一份合法数字报告，展示页码解析、分块和向量数量。
4. 用同一问题展示 Top 50 初召回、重排 Top 10 和最终上下文 Top 8 的变化。
5. 展示带页码来源的流式答案。
6. 提问一个语料无答案问题，展示拒答。
7. 展示一个旧/新资料冲突问题，分别引用。
8. 展示表格数值问题及单位来源。
9. 打开评测面板，比较无 RAG、无 Rerank、完整 RAG。
10. 展示错误分类、局限性和恢复演练证据。

9. 论文结构映射

论文章节	工程证据
绪论	课题背景、目标、国内外工作和边界
相关技术	RAG、Embedding、Rerank、LLM、pgvector
需求与总体设计	00-overall-design.md
知识库构建	解析、OCR、表格、切分、版本与入库测试
检索生成实现	两阶段检索、Prompt、SSE 和引用
实验与评测	验证集、指标、消融、置信区间和成本
系统实现	前后端页面、API、Docker 和安全
总结与展望	失败案例、图件限制、多模态和扩展路径

10. 进度判断

进度报告必须区分：

• 当前提交/阶段完成度；
• 整个系统完成度；
• 已验证能力；
• 仅完成设计、尚未验证的能力；
• 剩余风险和预计时间。

不能因设计文档完整就声称系统已经实现，也不能因页面可演示就声称评测和安全已经完成。