Establish a safe foundation before implementing the geology RAG system

The project begins with architecture, data governance, reproducible evaluation, deployment boundaries, and secret-handling contracts so later code has measurable acceptance criteria.

Constraint: Real provider credentials, workspace identities, and restricted geological data must never enter Git

Rejected: Add placeholder runnable services in the design commit | would imply unverified implementation readiness

Confidence: high

Scope-risk: narrow

Reversibility: clean

Directive: Run make verify before every commit and update ADRs when architecture boundaries change

Tested: Secret scan, Markdown links, YAML parse, shell syntax, and staged diff validation

Not-tested: Application runtime is intentionally deferred to the implementation stage

docs/adr/0001-use-pgvector.md

@@ -0,0 +1,25 @@
+# ADR-0001：第一版使用 PostgreSQL + pgvector
+
+- Status: accepted
+- Date: 2026-07-11
+
+## Context
+
+系统目标是毕业设计规模的地质文档 RAG，并要求 Docker 最简单启动、数据和实验可复现。预计正式语料约 1 万至 30 万切片，默认向量维度为 1024。
+
+## Decision
+
+第一版使用 PostgreSQL + pgvector，同时存储业务元数据和向量。使用 Cosine 距离并从首个 schema 版本建立 HNSW；评测事务通过禁用索引扫描获得同过滤条件的 exact 基线。应用与数据库之外不增加 Qdrant、Milvus、Redis 等基础服务，后台任务使用 PostgreSQL 持久化任务表。
+
+## Consequences
+
+- Docker 长期运行组件减少，备份与事务边界更清晰。
+- 1024 维位于 pgvector HNSW `vector` 类型 2000 维限制内。
+- 带权限过滤的 ANN 必须使用冗余过滤列、普通索引和 pgvector 0.8.x iterative scan，并与 exact filtered Top K 比较召回。
+- 维度变化需要新表、列或索引，不允许把不同维度混写。
+- 当切片达到百万级、过滤复杂度或查询吞吐明显超过单机 PostgreSQL 能力时，重新评估 Qdrant；Milvus 只在明确需要分布式大规模检索时评估。
+
+## Rejected
+
+- Qdrant：RAG 能力很好，但第一版会引入第二套持久化系统和双写一致性问题。
+- Milvus：组件和运维成本超过当前规模需求。

docs/adr/0002-separate-bailian-protocols.md

@@ -0,0 +1,18 @@
+# ADR-0002：分离百炼协议适配器
+
+- Status: accepted
+- Date: 2026-07-11
+
+## Context
+
+百炼 Chat/Embedding 使用 `/compatible-mode/v1`，而 `qwen3-rerank` 使用独立的 `/compatible-api/v1/reranks`。把它们封装成一个通用 OpenAI 客户端容易误拼路径，并掩盖不同错误和限流语义。
+
+## Decision
+
+后端建立独立的 `EmbeddingProvider`、`Reranker`、`Generator` 接口。OpenAI 兼容客户端承担 Chat 与基础 Embedding；独立 HTTP 客户端承担 Rerank。实验需要 `text_type=query/document` 时，由原生 Embedding 适配器承担。
+
+## Consequences
+
+- 三类端点和错误处理可以独立做契约测试。
+- Anthropic 兼容地址不进入本项目运行配置。
+- 模型凭证仍只在服务端配置层读取，任何适配器都不得记录鉴权请求头。

docs/adr/0003-text-first-scope.md

@@ -0,0 +1,17 @@
+# ADR-0003：第一版采用文本优先范围
+
+- Status: accepted
+- Date: 2026-07-11
+
+## Context
+
+选定的向量和重排模型是纯文本模型。地质资料中的图件、剖面和图例包含空间关系，仅靠 OCR 不能可靠恢复这些关系。
+
+## Decision
+
+第一版支持数字文本、扫描 OCR、表格结构化文本、图题和人工复核的图件摘要。依赖整幅图几何关系的问题单列为挑战集，不计入纯文本主指标。
+
+## Consequences
+
+- 系统不宣称完成矿体建模、图件空间推理、储量计算或找矿概率预测。
+- 后续引入多模态模型时必须新增 ADR、数据格式与独立评测集。

docs/adr/README.md

@@ -0,0 +1,9 @@
+# Architecture Decision Records
+
+ADR 用于记录会长期影响系统的技术决策。状态使用 `proposed`、`accepted`、`superseded` 或 `rejected`。
+
+当前记录：
+
+- [0001-use-pgvector.md](0001-use-pgvector.md)：选择 PostgreSQL + pgvector 作为第一版向量存储。
+- [0002-separate-bailian-protocols.md](0002-separate-bailian-protocols.md)：分离百炼 Chat/Embedding 与 Rerank 协议适配器。
+- [0003-text-first-scope.md](0003-text-first-scope.md)：第一版采用文本优先边界，不宣称地质图空间理解。