# 文档处理链路数据库设计

## 1. Purpose

本文档定义当前文档处理主链路的 PostgreSQL 数据库设计，覆盖上传、解析、索引、状态查询、重试、删除这条核心链路，以及围绕该链路的常用运维与审计需求。

本文档的目标不是替代 [document-core-processing-flow.md](/abs/path/C:/Users/A200477427/Developers/AIRegulation/AIRegulation-DocAnalysis/docs/architecture/document-core-processing-flow.md:1) 的流程说明，而是补齐关系型存储的 authority，使后续从 JSON 元数据切换到 PostgreSQL 时有清晰、稳定、可实施的数据库设计基线。

## 1.1 Scope And Design Target

本文档只覆盖以下范围：

- 文档主记录
- 文档处理运行记录
- 文档状态历史
- 解析产物引用
- 当前最新结构化解析快照

本文档不覆盖以下范围：

- Agent 会话
- 反馈和人工审核
- 合规分析任务
- Milvus collection schema 的详细实现

设计原则采用 `Compat First`：

- 保持与当前 `DocumentRepository` / `ParseArtifactStore` 主流程兼容
- 新增关系表以补足运维与审计能力
- 不为了理想化模型而反推大规模接口重写

## 2. Storage Responsibilities

当前系统采用三类存储，各自职责必须清晰分离：

| 存储 | 保存内容 | 是否业务主记录 | 说明 |
| --- | --- | --- | --- |
| MinIO | 原始文件、`layouts.json`、`structure_nodes.json`、`semantic_blocks.json`、`vector_chunks.json` | 否 | 负责大对象与产物归档，不承担关系查询 |
| Milvus | chunk 级向量和检索辅助字段 | 否 | 负责向量检索，不承担文档生命周期管理 |
| PostgreSQL | 文档元数据、处理状态、结构化快照、处理历史、artifact 引用 | 是 | 负责文档管理、运维可观测性和关系查询 |

约束说明：

- PostgreSQL 不保存 embedding 向量。
- PostgreSQL 不新增 `vector_chunks` 内容表。
- Milvus 可以保存 `doc_id`、`doc_name`、`regulation_type`、`version` 等检索辅助字段，但不是业务真相源。
- 文档下载、删除、重试仍以 PostgreSQL 中的文档主记录为入口。

## 3. Design Overview

### 3.1 Entity Responsibilities

数据库采用“当前态主记录 + 当前快照 + 历史过程”的分层模型：

- `documents`
  - 当前文档主记录
  - 保存供管理、下载、重试、删除直接使用的元数据和当前状态
- `document_processing_runs`
  - 每次上传或重试对应一次处理运行
  - 保存运行级统计、阶段时间点和失败信息
- `document_status_history`
  - 追加式状态事件流
  - 保存每次状态变更的上下文
- `document_artifacts`
  - 保存 MinIO artifact 的引用信息
  - 不保存 artifact 内容本体
- `structure_nodes`
  - 当前最新解析快照中的目录结构
- `semantic_blocks`
  - 当前最新解析快照中的语义块结构

### 3.2 Current Snapshot Vs Historical Records

本设计显式区分两类数据：

- 当前快照
  - `documents`
  - `structure_nodes`
  - `semantic_blocks`
- 历史过程
  - `document_processing_runs`
  - `document_status_history`
  - `document_artifacts`

其中：

- `structure_nodes` 和 `semantic_blocks` 只保存“最新一次成功解析后”的当前快照
- 历史版本回溯依赖 `document_processing_runs`、`document_artifacts` 和 MinIO 中对应 run 的 artifact 文件

## 4. Table Design

### 4.1 `documents`

用途：

- 作为文档生命周期的主记录表
- 为下载、删除、重试、管理列表、状态查询提供当前态真相

字段设计：

```sql
CREATE TABLE IF NOT EXISTS documents (
    doc_id              VARCHAR(128) PRIMARY KEY,
    doc_name            VARCHAR(512)  NOT NULL DEFAULT '',
    file_name           VARCHAR(512)  NOT NULL DEFAULT '',
    object_name         VARCHAR(1024) NOT NULL DEFAULT '',
    content_type        VARCHAR(128)  NOT NULL DEFAULT '',
    size_bytes          BIGINT        NOT NULL DEFAULT 0,
    status              VARCHAR(32)   NOT NULL DEFAULT 'pending',
    regulation_type     VARCHAR(128)  NOT NULL DEFAULT '',
    version             VARCHAR(64)   NOT NULL DEFAULT '',
    summary             TEXT          NOT NULL DEFAULT '',
    summary_latency_ms  INTEGER       NOT NULL DEFAULT 0,
    chunk_count         INTEGER       NOT NULL DEFAULT 0,
    parser_name         VARCHAR(128)  NOT NULL DEFAULT '',
    index_name          VARCHAR(128)  NOT NULL DEFAULT '',
    error_message       TEXT          NOT NULL DEFAULT '',
    metadata            JSONB         NOT NULL DEFAULT '{}'::jsonb,
    created_at          TIMESTAMPTZ   NOT NULL DEFAULT NOW(),
    updated_at          TIMESTAMPTZ   NOT NULL DEFAULT NOW(),
    CONSTRAINT chk_documents_status
        CHECK (status IN ('pending', 'stored', 'parsed', 'indexed', 'failed'))
);

CREATE INDEX IF NOT EXISTS idx_documents_status_updated_at
    ON documents(status, updated_at DESC);

CREATE INDEX IF NOT EXISTS idx_documents_regulation_version
    ON documents(regulation_type, version);

CREATE INDEX IF NOT EXISTS idx_documents_updated_at
    ON documents(updated_at DESC);
```

字段说明：

- `object_name`
  - 原始上传文件在 MinIO 中的对象路径
  - 当前实现依赖该字段完成下载、重试和删除，v1 不拆分为独立文件表
- `status`
  - 当前文档处理状态
  - 仅表示当前态，不承担历史审计职责
- `metadata`
  - 保存轻量、变动频率较高、暂不值得列式建模的附加信息
  - 典型内容包括 `parse_task_id`、`processing_stage`、`artifact_keys`、统计计数等

### 4.2 `document_processing_runs`

用途：

- 记录一次上传或一次重试的完整处理运行
- 用于解释“这份文档本次处理为什么成功或失败”

字段设计：

```sql
CREATE TABLE IF NOT EXISTS document_processing_runs (
    run_id                 BIGSERIAL PRIMARY KEY,
    doc_id                 VARCHAR(128) NOT NULL,
    trigger_type           VARCHAR(16)  NOT NULL,
    run_status             VARCHAR(16)  NOT NULL,
    parser_backend         VARCHAR(64)  NOT NULL DEFAULT '',
    chunk_backend          VARCHAR(64)  NOT NULL DEFAULT '',
    embedding_model        VARCHAR(128) NOT NULL DEFAULT '',
    index_name             VARCHAR(128) NOT NULL DEFAULT '',
    started_at             TIMESTAMPTZ  NOT NULL DEFAULT NOW(),
    stored_at              TIMESTAMPTZ,
    parsed_at              TIMESTAMPTZ,
    indexed_at             TIMESTAMPTZ,
    finished_at            TIMESTAMPTZ,
    layout_count           INTEGER      NOT NULL DEFAULT 0,
    structure_node_count   INTEGER      NOT NULL DEFAULT 0,
    semantic_block_count   INTEGER      NOT NULL DEFAULT 0,
    vector_chunk_count     INTEGER      NOT NULL DEFAULT 0,
    chunk_count            INTEGER      NOT NULL DEFAULT 0,
    failure_stage          VARCHAR(32)  NOT NULL DEFAULT '',
    error_message          TEXT         NOT NULL DEFAULT '',
    metadata               JSONB        NOT NULL DEFAULT '{}'::jsonb,
    CONSTRAINT fk_runs_document
        FOREIGN KEY (doc_id) REFERENCES documents(doc_id) ON DELETE CASCADE,
    CONSTRAINT chk_runs_trigger_type
        CHECK (trigger_type IN ('upload', 'retry')),
    CONSTRAINT chk_runs_status
        CHECK (run_status IN ('running', 'succeeded', 'failed'))
);

CREATE INDEX IF NOT EXISTS idx_runs_doc_started_at
    ON document_processing_runs(doc_id, started_at DESC);

CREATE INDEX IF NOT EXISTS idx_runs_status_started_at
    ON document_processing_runs(run_status, started_at DESC);
```

字段说明：

- `trigger_type`
  - 标识该次处理由首次上传还是 retry 触发
- `run_status`
  - 只表示该次运行的最终结果
- `failure_stage`
  - 建议取值与应用层关键阶段一致，例如 `store`、`parse`、`artifact_persist`、`embed`、`index`
- `metadata`
  - 保存运行级附加上下文，例如配置快照、后端实现名、provider 返回信息摘要

### 4.3 `document_status_history`

用途：

- 保存状态变化事件流
- 用于排障、审计和运行轨迹分析

字段设计：

```sql
CREATE TABLE IF NOT EXISTS document_status_history (
    event_id         BIGSERIAL PRIMARY KEY,
    doc_id           VARCHAR(128) NOT NULL,
    run_id           BIGINT,
    from_status      VARCHAR(32)  NOT NULL DEFAULT '',
    to_status        VARCHAR(32)  NOT NULL,
    stage            VARCHAR(32)  NOT NULL DEFAULT '',
    message          TEXT         NOT NULL DEFAULT '',
    metadata         JSONB        NOT NULL DEFAULT '{}'::jsonb,
    occurred_at      TIMESTAMPTZ  NOT NULL DEFAULT NOW(),
    CONSTRAINT fk_status_document
        FOREIGN KEY (doc_id) REFERENCES documents(doc_id) ON DELETE CASCADE,
    CONSTRAINT fk_status_run
        FOREIGN KEY (run_id) REFERENCES document_processing_runs(run_id) ON DELETE CASCADE,
    CONSTRAINT chk_status_history_to_status
        CHECK (to_status IN ('pending', 'stored', 'parsed', 'indexed', 'failed'))
);

CREATE INDEX IF NOT EXISTS idx_status_history_doc_occurred_at
    ON document_status_history(doc_id, occurred_at DESC);

CREATE INDEX IF NOT EXISTS idx_status_history_run_occurred_at
    ON document_status_history(run_id, occurred_at DESC);
```

字段说明：

- `from_status` 可以为空字符串
  - 用于首个事件，例如文档创建时进入 `pending`
- `stage`
  - 用于记录状态推进对应的业务阶段
- `message`
  - 用于记录面向排障的人类可读说明

### 4.4 `document_artifacts`

用途：

- 保存解析产物在 MinIO 中的位置与基本属性
- 支持后续定位某次 run 的 artifacts，而不扫描对象存储

字段设计：

```sql
CREATE TABLE IF NOT EXISTS document_artifacts (
    artifact_id       BIGSERIAL PRIMARY KEY,
    doc_id            VARCHAR(128)  NOT NULL,
    run_id            BIGINT,
    artifact_type     VARCHAR(32)   NOT NULL,
    object_name       VARCHAR(1024) NOT NULL,
    content_type      VARCHAR(128)  NOT NULL DEFAULT 'application/json',
    byte_size         BIGINT        NOT NULL DEFAULT 0,
    checksum          VARCHAR(128)  NOT NULL DEFAULT '',
    metadata          JSONB         NOT NULL DEFAULT '{}'::jsonb,
    created_at        TIMESTAMPTZ   NOT NULL DEFAULT NOW(),
    CONSTRAINT fk_artifacts_document
        FOREIGN KEY (doc_id) REFERENCES documents(doc_id) ON DELETE CASCADE,
    CONSTRAINT fk_artifacts_run
        FOREIGN KEY (run_id) REFERENCES document_processing_runs(run_id) ON DELETE CASCADE,
    CONSTRAINT chk_artifact_type
        CHECK (artifact_type IN ('layouts', 'structure_nodes', 'semantic_blocks', 'vector_chunks'))
);

CREATE INDEX IF NOT EXISTS idx_artifacts_doc_created_at
    ON document_artifacts(doc_id, created_at DESC);

CREATE INDEX IF NOT EXISTS idx_artifacts_run_type
    ON document_artifacts(run_id, artifact_type);

CREATE UNIQUE INDEX IF NOT EXISTS uq_artifacts_run_type_object
    ON document_artifacts(run_id, artifact_type, object_name);
```

字段说明：

- 该表只记录 artifact 引用，不记录原始文件
- 原始文件仍由 `documents.object_name` 表达，这是为了保持当前下载和重试逻辑兼容

### 4.5 `structure_nodes`

用途：

- 保存当前最新解析快照中的标题层级结构
- 供目录树查询、结构化浏览、调试和审计使用

字段设计：

```sql
CREATE TABLE IF NOT EXISTS structure_nodes (
    id             BIGSERIAL PRIMARY KEY,
    doc_id         VARCHAR(128) NOT NULL,
    unique_id      VARCHAR(128),
    page           INTEGER      NOT NULL DEFAULT 0,
    idx            INTEGER      NOT NULL DEFAULT 0,
    level          INTEGER      NOT NULL DEFAULT 0,
    title          TEXT         NOT NULL DEFAULT '',
    type           VARCHAR(64),
    sub_type       VARCHAR(64),
    created_at     TIMESTAMPTZ  NOT NULL DEFAULT NOW(),
    CONSTRAINT fk_structure_nodes_document
        FOREIGN KEY (doc_id) REFERENCES documents(doc_id) ON DELETE CASCADE
);

CREATE INDEX IF NOT EXISTS idx_structure_nodes_doc_idx
    ON structure_nodes(doc_id, idx);

CREATE INDEX IF NOT EXISTS idx_structure_nodes_doc_level
    ON structure_nodes(doc_id, level);
```

设计约束：

- 该表表示当前快照，不做多版本建模
- 新一轮成功解析会覆盖同一 `doc_id` 的旧快照

### 4.6 `semantic_blocks`

用途：

- 保存当前最新解析快照中的语义块
- 供结构回溯、调试和后续关系型查询使用

字段设计：

```sql
CREATE TABLE IF NOT EXISTS semantic_blocks (
    id              BIGSERIAL PRIMARY KEY,
    doc_id          VARCHAR(128) NOT NULL,
    semantic_id     VARCHAR(128) NOT NULL,
    block_type      VARCHAR(64)  NOT NULL DEFAULT '',
    page_start      INTEGER      NOT NULL DEFAULT 0,
    page_end        INTEGER      NOT NULL DEFAULT 0,
    section_path    JSONB        NOT NULL DEFAULT '[]'::jsonb,
    section_level   INTEGER      NOT NULL DEFAULT 0,
    section_title   VARCHAR(512) NOT NULL DEFAULT '',
    source_ids      JSONB        NOT NULL DEFAULT '[]'::jsonb,
    text            TEXT         NOT NULL DEFAULT '',
    created_at      TIMESTAMPTZ  NOT NULL DEFAULT NOW(),
    CONSTRAINT fk_semantic_blocks_document
        FOREIGN KEY (doc_id) REFERENCES documents(doc_id) ON DELETE CASCADE,
    CONSTRAINT uq_semantic_blocks_doc_semantic
        UNIQUE (doc_id, semantic_id)
);

CREATE INDEX IF NOT EXISTS idx_semantic_blocks_doc_id
    ON semantic_blocks(doc_id);

CREATE INDEX IF NOT EXISTS idx_semantic_blocks_doc_section_title
    ON semantic_blocks(doc_id, section_title);

CREATE INDEX IF NOT EXISTS idx_semantic_blocks_doc_block_type
    ON semantic_blocks(doc_id, block_type);
```

设计约束：

- 该表表示当前快照，不保存历史版本
- 历史回溯应通过 run 对应的 artifact 文件完成

## 5. Relationship Model

实体关系如下：

```mermaid
erDiagram
    documents ||--o{ document_processing_runs : has
    documents ||--o{ document_status_history : has
    documents ||--o{ document_artifacts : has
    documents ||--o{ structure_nodes : has
    documents ||--o{ semantic_blocks : has
    document_processing_runs ||--o{ document_status_history : emits
    document_processing_runs ||--o{ document_artifacts : produces
```

关系语义：

- `documents` 是聚合根
- `document_processing_runs` 记录一次完整处理尝试
- `document_status_history` 记录状态推进轨迹
- `document_artifacts` 记录 MinIO 中可回放的结构化产物
- `structure_nodes` / `semantic_blocks` 代表“当前版本”的关系型快照

## 6. Flow-To-Table Mapping

### 6.1 Upload

上传开始时：

1. 创建 `documents`
2. 创建一条 `document_processing_runs`
3. 写入一条 `document_status_history`，`to_status='pending'`

### 6.2 Store Original File

原始文件写入 MinIO 成功后：

1. 更新 `documents.status='stored'`
2. 更新当前 run 的 `stored_at`
3. 追加 `document_status_history`

### 6.3 Parse And Persist Artifacts

解析成功后：

1. 更新当前 run 的 `parsed_at`
2. 更新 run 的 `layout_count`、`structure_node_count`、`semantic_block_count`、`vector_chunk_count`
3. 更新 `documents.status='parsed'`
4. 刷新 `structure_nodes`
5. 刷新 `semantic_blocks`
6. 为 `layouts`、`structure_nodes`、`semantic_blocks`、`vector_chunks` 写入 `document_artifacts`
7. 追加 `document_status_history`

### 6.4 Embed And Index

向量化和入库成功后：

1. 更新当前 run 的 `indexed_at`、`finished_at`
2. 更新当前 run 的 `run_status='succeeded'`
3. 更新 `documents.status='indexed'`
4. 更新 `documents.chunk_count`、`index_name`
5. 追加 `document_status_history`

### 6.5 Failure

任一阶段失败时：

1. 更新当前 run 的 `run_status='failed'`
2. 记录 `failure_stage` 和 `error_message`
3. 更新 `finished_at`
4. 更新 `documents.status='failed'`
5. 更新 `documents.error_message`
6. 追加 `document_status_history`

### 6.6 Retry

重试时：

1. 保留现有 `documents.doc_id`
2. 新建一条 `document_processing_runs`
3. 为本次重试重新写入状态历史
4. 本次重试成功后覆盖 `structure_nodes` / `semantic_blocks` 当前快照
5. 历史 run 和 artifact 记录继续保留

### 6.7 Delete

删除文档时：

1. 应用层先删除 MinIO 原始文件和 artifacts
2. 应用层删除 Milvus 中按 `doc_id` 关联的向量
3. 最后删除 `documents`
4. 依赖外键 `ON DELETE CASCADE` 清理 run、status history、artifacts、structure nodes、semantic blocks

## 7. Alignment With Current Backend

### 7.1 Compatible Parts

当前代码已天然兼容以下设计：

- `documents`
- `structure_nodes`
- `semantic_blocks`
- 当前快照覆盖式更新
- `doc_id` 作为跨 MinIO / Milvus / PostgreSQL 的统一关联键

### 7.2 Required Future Additions

若后续正式切到 PostgreSQL 默认元数据后端，应新增以下内部 store 或 repository：

- `DocumentProcessingRunStore`
- `DocumentStatusEventStore`
- `DocumentArtifactStore`

这些新增能力属于内部增强，不要求修改现有 HTTP API。

### 7.3 Migration Guidance

从当前 JSON 元数据切换到 PostgreSQL 时，建议按以下顺序进行：

1. 迁移 `documents.json` 中已有文档主记录到 `documents`
2. 将 `DOCUMENT_REPOSITORY_BACKEND` 切换为 `postgres`
3. 为新上传或重试的文档开始写入 run / status history / artifact records
4. 历史文档若缺少 run 级数据，可允许为空，不阻塞切换

## 8. Non-Goals

以下能力不在本设计 v1 范围内：

- 将 Milvus 替换为 PostgreSQL 向量能力
- 在 PostgreSQL 中保存向量字段
- 为 `vector_chunks` 建独立关系表
- 为 `structure_nodes` / `semantic_blocks` 建历史版本仓库
- 将原始文件抽象成独立 `document_files` 表

这些能力可能在后续重构时被讨论，但不应影响当前主链路切换和现有应用层兼容性。