RAG/docs/03-implementation-plan.md

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

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

## 1. 仓库结构规范

```text
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 依赖方向

```text
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 关键接口

```python
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 结构

```text
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. 阶段计划

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

### 阶段 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 示例

```text
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](00-overall-design.md) |
| 知识库构建 | 解析、OCR、表格、切分、版本与入库测试 |
| 检索生成实现 | 两阶段检索、Prompt、SSE 和引用 |
| 实验与评测 | 验证集、指标、消融、置信区间和成本 |
| 系统实现 | 前后端页面、API、Docker 和安全 |
| 总结与展望 | 失败案例、图件限制、多模态和扩展路径 |

## 10. 进度判断

进度报告必须区分：

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

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