feat: add document versioning and list API

docs/leaudit/SYSTEM_OVERVIEW.md

@@ -4,6 +4,10 @@
 
 ## 一、目标架构
 
+补充文档：
+
+- 并发与重试参数：`docs/leaudit/并发与重试参数说明.md`
+
 ```
 ┌─ API ───────────────────────────────────────────────────────────┐
 │  AuditController (/audit)          RuleController (/rule-sets)   │
@@ -166,11 +170,11 @@ finalize_run()               ← 唯一写 result_status / finished_at / rescue_
 POST /upload (multipart/form-data)
   file
   typeId / typeCode
-  bizDocumentId?
   region=default
   fileRole=primary
   createdBy?
   autoRun=false
+  speed=normal|urgent
 ```
 
 执行链：
@@ -178,7 +182,7 @@ POST /upload (multipart/form-data)
 ```text
 Upload
   -> DocumentServiceImpl.Upload()
-  -> upsert leaudit_documents
+  -> create leaudit_documents
   -> 旧 active 文件失效
   -> 上传原始文件到 OSS:
      bdocs/{region}/{type_code}/{document_id}/v{n}/{file_role}.{ext}
@@ -186,6 +190,14 @@ Upload
   -> autoRun=true 时直接调用 AuditServiceImpl.Run()
 ```
 
+说明：
+
+- `leaudit_documents` 现阶段是平台内部文档主表，不再依赖旧系统 `documents.id`
+- 每次前端上传都会新建一条 `leaudit_documents`
+- `speed`
+  - `normal` -> `leaudit.normal`
+  - `urgent` -> `leaudit.urgent`
+
 ## 四点六、最新补充：结果查询视图
 
 当前 `GetRunStatus()` / `GetResult()` 已不再只返回 run 主表摘要。
@@ -204,6 +216,14 @@ Upload
   - `leaudit_run_metrics`
   - `leaudit_artifacts`
 
+建议联调方式：
+
+- 上传后从 `run.runId` 轮询 `GET /audit/run/{runId}`
+- 完成后调用 `GET /audit/result/{runId}`
+- worker 日志里会明确打印：
+  - 已投递到哪个队列
+  - worker 实际消费的是 `urgent` 还是 `normal`
+
 ## 四点七、关键关系图：DocumentType -> Binding -> RuleSet -> RuleVersion
 
 这一段是当前规则执行链里最关键的一层路由关系。

docs/leaudit/document_schema_design.md

@@ -52,7 +52,7 @@ LeAudit 有一套自己的 SQLAlchemy ORM 表（`storage/models/`）。**leaudit
 
 | # | 表名 | 用途 | 状态 |
 |---|------|------|------|
-| 1 | `leaudit_documents` | LeAudit 域文档镜像，关联业务文档 | ✅ 已创建 |
+| 1 | `leaudit_documents` | LeAudit 平台内部文档主表 | ✅ 已创建 |
 | 2 | `leaudit_document_files` | 文档文件版本管理 | ✅ 已创建 |
 | 3 | `leaudit_audit_runs` | 每次处理执行的主索引记录 | ✅ 已创建 |
 | 4 | `leaudit_artifacts` | OCR/normalize/manifest/markdown/图片等文件产物索引 | ✅ 已创建 |
@@ -79,12 +79,12 @@ LeAudit 有一套自己的 SQLAlchemy ORM 表（`storage/models/`）。**leaudit
 
 ### 4.1 `leaudit_documents`
 
-LeAudit 域文档镜像表。通过 `biz_document_id` 关联老系统 `documents.id`。
+LeAudit 平台内部文档主表。当前不再依赖旧系统文档表。
 
 | 字段 | 类型 | 说明 |
 | --- | --- | --- |
 | `id` | bigint PK | 主键，自增 |
-| `biz_document_id` | bigint UNIQUE | 关联老业务 `documents.id` |
+| `biz_document_id` | bigint UNIQUE | 内部追踪号，沿用旧字段名以兼容历史库 |
 | `type_id` | bigint | 文档类型 ID → `leaudit_document_types.id` |
 | `processing_status` | varchar(64) | waiting / running / completed / failed |
 | `current_run_id` | bigint | 最新有效 `leaudit_audit_runs.id` |
@@ -179,7 +179,7 @@ LeAudit 域文档镜像表。通过 `biz_document_id` 关联老系统 `documents
 ```text
 leaudit_entry_modules
   └── leaudit_document_types
-        ├── leaudit_documents ── biz_document_id → 老系统 documents
+        ├── leaudit_documents
         │     ├── leaudit_document_files
         │     └── leaudit_audit_runs
         │           ├── leaudit_artifacts (N)
@@ -214,6 +214,7 @@ artifacts/{region}/{run_id}/{artifact_type}/{detail}.{ext}
 ## 9. 最终结论
 
 - 所有表 `leaudit_*` 前缀，与老系统完全隔离
+- `leaudit_documents` 现阶段是平台内部文档主表，不再要求外部 `documents.id`
 - `leaudit_audit_runs` 是每次处理的唯一追踪单位
 - `leaudit_artifacts` 统一管理所有文件产物，数据库只存索引
 - `leaudit_rule_results` 粒度到逐条规则，结构与 LeAudit `RuleResult` 对齐

docs/接口/README.md

@@ -0,0 +1,21 @@
+# 接口文档目录
+
+这个目录专门放当前 `leaudit-platform` 已落地接口的使用说明，重点记录：
+
+- 接口用途
+- 参数说明
+- 业务逻辑
+- 请求示例
+- 返回示例
+
+当前已整理：
+
+- `文档上传与评查接口.md`
+- `文档列表接口设计分析.md`
+
+建议阅读顺序：
+
+1. 先看 `文档上传与评查接口.md`
+2. 再看 `文档列表接口设计分析.md`
+3. 再结合 `docs/规则编辑/worker并发执行改造方案.md`
+4. 如果要理解底层数据结构，再看 `docs/leaudit/document_schema_design.md`

docs/接口/文档上传与评查接口.md

@@ -0,0 +1,692 @@
+# 文档上传与评查接口
+
+这份文档描述当前已经落地的文档上传、文档列表、自动评查、手动评查、状态查询、结果查询接口。
+
+当前接口围绕以下业务语义设计：
+
+- 每次前端上传都会形成一个平台内部文档实例
+- 同名文档会尝试归入同一个版本组
+- 同名且内容相同：
+  - 不新建版本
+  - `duplicateUpload=true`
+  - 如果 `autoRun=true`，仍然可以重新走一次评查流程
+- 同名但内容变化：
+  - 新建版本
+  - 形成 `v2 / v3 / ...`
+- 评查任务走 worker 异步执行
+- 队列只有两档：
+  - `urgent`
+  - `normal`
+
+---
+
+## 1. 上传接口
+
+### 路径
+
+```http
+POST /upload
+```
+
+### Content-Type
+
+```http
+multipart/form-data
+```
+
+### 用途
+
+- 上传文档
+- 创建或命中文档版本
+- 建立 `leaudit_documents / leaudit_document_files`
+- 可选自动触发评查
+
+### 请求参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|---|---|---:|---|
+| `file` | file | 是 | 上传文件 |
+| `typeId` | int | 否 | 文档类型 ID，和 `typeCode` 二选一至少传一个 |
+| `typeCode` | string | 否 | 文档类型编码，例如 `contract.sale` |
+| `region` | string | 否 | 区域，默认 `default` |
+| `fileRole` | string | 否 | 文件角色，默认 `primary` |
+| `createdBy` | int | 否 | 上传用户 ID |
+| `autoRun` | bool | 否 | 是否上传后自动触发评查，默认 `false` |
+| `speed` | string | 否 | 执行速度档位：`normal` / `urgent`，默认 `normal` |
+
+### 版本匹配逻辑
+
+上传时会先做版本候选匹配：
+
+1. 归一化文件名，得到 `normalized_name`
+2. 按以下条件查找最新版本候选：
+   - `type_id` 相同
+   - `region` 相同
+   - `normalized_name` 相同
+   - `is_latest_version = true`
+   - 主文件 `file_role = 'primary'`
+3. 比较最新版本主文件的 `sha256`
+
+结果分三种：
+
+- 找不到候选
+  - 新建版本组
+  - 当前版本为 `v1`
+- 找到候选且 `sha256` 相同
+  - 视为重复上传
+  - 不新建版本
+  - `duplicateUpload=true`
+- 找到候选但 `sha256` 不同
+  - 新建版本
+  - 当前版本为 `v2 / v3 / ...`
+  - 旧版本 `is_latest_version=false`
+  - 新版本 `is_latest_version=true`
+
+### 队列路由逻辑
+
+- `speed=urgent` -> 投递 `leaudit.urgent`
+- `speed=normal` -> 投递 `leaudit.normal`
+
+### 请求示例：普通上传，不自动评查
+
+```bash
+curl -X POST 'http://127.0.0.1:8096/api/upload' \
+  -F 'file=@/path/to/合同.docx' \
+  -F 'typeCode=contract.sale' \
+  -F 'region=default' \
+  -F 'fileRole=primary' \
+  -F 'autoRun=false' \
+  -F 'speed=normal'
+```
+
+### 返回示例：首次上传，命中 `v1`
+
+```json
+{
+  "code": 200,
+  "message": "ok",
+  "data": {
+    "documentId": 11,
+    "internalDocumentNo": 1777426812904262854,
+    "versionGroupKey": "4e02e455aa504cb9b75a254727f1bb4c",
+    "versionNo": 1,
+    "previousVersionId": null,
+    "rootVersionId": 11,
+    "duplicateUpload": false,
+    "fileId": 12,
+    "typeId": 9,
+    "typeCode": "contract.sale",
+    "region": "default",
+    "fileName": "版本归档验证合同.docx",
+    "ossUrl": "bdocs/default/contract.sale/2026/04/11/v1/primary__版本归档验证合同.docx",
+    "speed": "normal",
+    "processingStatus": "waiting",
+    "autoRunTriggered": false,
+    "run": null
+  }
+}
+```
+
+### 返回示例：重复上传，不升版
+
+```json
+{
+  "code": 200,
+  "message": "ok",
+  "data": {
+    "documentId": 11,
+    "internalDocumentNo": 1777426812904262854,
+    "versionGroupKey": "4e02e455aa504cb9b75a254727f1bb4c",
+    "versionNo": 1,
+    "previousVersionId": null,
+    "rootVersionId": 11,
+    "duplicateUpload": true,
+    "fileId": 12,
+    "typeId": 9,
+    "typeCode": "contract.sale",
+    "region": "default",
+    "fileName": "版本归档验证合同.docx",
+    "ossUrl": "bdocs/default/contract.sale/2026/04/11/v1/primary__版本归档验证合同.docx",
+    "speed": "normal",
+    "processingStatus": "waiting",
+    "autoRunTriggered": false,
+    "run": null
+  }
+}
+```
+
+### 返回示例：同名但内容变化，自动形成 `v2`
+
+```json
+{
+  "code": 200,
+  "message": "ok",
+  "data": {
+    "documentId": 12,
+    "internalDocumentNo": 1777426813574315361,
+    "versionGroupKey": "4e02e455aa504cb9b75a254727f1bb4c",
+    "versionNo": 2,
+    "previousVersionId": 11,
+    "rootVersionId": 11,
+    "duplicateUpload": false,
+    "fileId": 13,
+    "typeId": 9,
+    "typeCode": "contract.sale",
+    "region": "default",
+    "fileName": "版本归档验证合同.docx",
+    "ossUrl": "bdocs/default/contract.sale/2026/04/12/v2/primary__版本归档验证合同.docx",
+    "speed": "normal",
+    "processingStatus": "waiting",
+    "autoRunTriggered": false,
+    "run": null
+  }
+}
+```
+
+### 返回示例：重复上传但自动重新评查
+
+```json
+{
+  "code": 200,
+  "message": "ok",
+  "data": {
+    "documentId": 13,
+    "internalDocumentNo": 1777427235286905027,
+    "versionGroupKey": "4e02e455aa504cb9b75a254727f1bb4c",
+    "versionNo": 3,
+    "previousVersionId": 12,
+    "rootVersionId": 11,
+    "duplicateUpload": true,
+    "fileId": 14,
+    "typeId": 9,
+    "typeCode": "contract.sale",
+    "region": "default",
+    "fileName": "版本归档验证合同.docx",
+    "ossUrl": "bdocs/default/contract.sale/2026/04/13/v3/primary__版本归档验证合同.docx",
+    "speed": "normal",
+    "processingStatus": "queued",
+    "autoRunTriggered": true,
+    "run": {
+      "runId": 13,
+      "documentId": 13,
+      "runNo": 2,
+      "documentFileId": 14,
+      "status": "queued",
+      "phase": "dispatch",
+      "resultStatus": null,
+      "ruleSetId": 29,
+      "ruleVersionId": 9,
+      "ruleTypeId": "contract.sale",
+      "rescueApplied": false,
+      "totalScore": null,
+      "passedCount": null,
+      "failedCount": null,
+      "skippedCount": null,
+      "startedAt": null,
+      "finishedAt": null
+    }
+  }
+}
+```
+
+---
+
+## 2. 文档列表接口
+
+### 路径
+
+```http
+GET /documents/list
+```
+
+### 用途
+
+- 返回文档主列表
+- 只返回每个版本组的最新版本
+- 每条记录附带历史版本摘要，前端可以直接做“展开历史版本”
+
+### 查询参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|---|---|---:|---|
+| `page` | int | 否 | 页码，从 `1` 开始，默认 `1` |
+| `pageSize` | int | 否 | 每页数量，默认 `20`，最大 `100` |
+| `keyword` | string | 否 | 文件名 / 归一化名称模糊搜索 |
+| `typeCode` | string | 否 | 文档类型编码，例如 `contract.sale` |
+| `region` | string | 否 | 区域过滤 |
+| `processingStatus` | string | 否 | 文档处理状态过滤 |
+| `resultStatus` | string | 否 | 最新 run 的结果状态过滤 |
+
+### 查询逻辑
+
+- 主查询只看 `leaudit_documents.is_latest_version = true`
+- 只关联主文件：
+  - `leaudit_document_files.is_active = true`
+  - `leaudit_document_files.file_role = 'primary'`
+- 当前评查状态来自 `leaudit_audit_runs`
+- 历史版本按 `version_group_key` 再查一次并挂到 `historyVersions`
+
+### 请求示例
+
+```bash
+curl 'http://127.0.0.1:8096/api/documents/list?page=1&pageSize=5'
+```
+
+### 带筛选请求示例
+
+```bash
+curl 'http://127.0.0.1:8096/api/documents/list?page=1&pageSize=2&keyword=版本归档&typeCode=contract.sale&region=default'
+```
+
+### 返回示例
+
+```json
+{
+  "code": 200,
+  "message": "ok",
+  "data": {
+    "total": 1,
+    "page": 1,
+    "pageSize": 2,
+    "totalPages": 1,
+    "documents": [
+      {
+        "documentId": 13,
+        "internalDocumentNo": 1777427235286905027,
+        "versionGroupKey": "4e02e455aa504cb9b75a254727f1bb4c",
+        "versionNo": 3,
+        "rootVersionId": 11,
+        "previousVersionId": 12,
+        "typeId": 9,
+        "typeCode": "contract.sale",
+        "region": "default",
+        "normalizedName": "版本归档验证合同",
+        "fileId": 14,
+        "fileName": "版本归档验证合同.docx",
+        "fileExt": "docx",
+        "mimeType": "application/octet-stream",
+        "fileSize": 587279,
+        "ossUrl": "bdocs/default/contract.sale/2026/04/13/v3/primary__版本归档验证合同.docx",
+        "processingStatus": "completed",
+        "currentRunId": 13,
+        "runStatus": "completed",
+        "resultStatus": "review",
+        "totalScore": 92.0,
+        "passedCount": 25,
+        "failedCount": 3,
+        "skippedCount": 0,
+        "updatedAt": "2026-04-29T01:50:05.241397+00:00",
+        "hasHistory": true,
+        "totalVersions": 3,
+        "historyVersions": [
+          {
+            "documentId": 12,
+            "fileId": 13,
+            "versionNo": 2,
+            "fileName": "版本归档验证合同.docx",
+            "fileExt": "docx",
+            "processingStatus": "waiting",
+            "runStatus": null,
+            "resultStatus": null,
+            "updatedAt": "2026-04-29T01:47:15.250697+00:00"
+          },
+          {
+            "documentId": 11,
+            "fileId": 12,
+            "versionNo": 1,
+            "fileName": "版本归档验证合同.docx",
+            "fileExt": "docx",
+            "processingStatus": "waiting",
+            "runStatus": null,
+            "resultStatus": null,
+            "updatedAt": "2026-04-29T01:40:13.538839+00:00"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### 返回字段说明
+
+| 字段 | 说明 |
+|---|---|
+| `documents[]` | 主列表，仅最新版本 |
+| `versionGroupKey` | 同一版本链的归档组键 |
+| `versionNo` | 当前版本号 |
+| `rootVersionId` | 版本链根文档 ID |
+| `previousVersionId` | 上一版本文档 ID |
+| `hasHistory` | 是否存在历史版本 |
+| `totalVersions` | 该版本组的总版本数 |
+| `historyVersions[]` | 历史版本摘要，按 `versionNo DESC` 排序 |
+
+---
+
+## 3. 手动触发评查
+
+### 路径
+
+```http
+POST /audit/run
+```
+
+### 用途
+
+- 对指定 `documentId` 手动触发一次新的评查 run
+- 不改变文档版本
+- 只新增 `leaudit_audit_runs`
+
+### 请求体
+
+```json
+{
+  "documentId": 13,
+  "ruleType": null,
+  "force": false,
+  "speed": "normal"
+}
+```
+
+### 参数说明
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---:|---|
+| `documentId` | int | 是 | 文档 ID |
+| `ruleType` | string/null | 否 | 指定规则类型编码 |
+| `force` | bool | 否 | 是否强制重跑 |
+| `speed` | string | 否 | `normal` / `urgent` |
+
+### 请求示例
+
+```bash
+curl -X POST 'http://127.0.0.1:8096/api/audit/run' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "documentId": 13,
+    "force": false,
+    "speed": "urgent"
+  }'
+```
+
+### 返回示例
+
+```json
+{
+  "code": 200,
+  "message": "ok",
+  "data": {
+    "runId": 15,
+    "documentId": 13,
+    "runNo": 3,
+    "documentFileId": 14,
+    "status": "queued",
+    "phase": "dispatch",
+    "resultStatus": null,
+    "ruleSetId": 29,
+    "ruleVersionId": 9,
+    "ruleTypeId": "contract.sale",
+    "rescueApplied": false,
+    "totalScore": null,
+    "passedCount": null,
+    "failedCount": null,
+    "skippedCount": null,
+    "startedAt": null,
+    "finishedAt": null
+  }
+}
+```
+
+---
+
+## 4. 查询运行状态
+
+### 路径
+
+```http
+GET /audit/run/{runId}
+```
+
+### 用途
+
+- 查询 run 当前状态
+- 适合前端轮询
+
+### 状态说明
+
+常见状态：
+
+- `queued`
+- `running`
+- `completed`
+- `failed`
+
+常见阶段：
+
+- `dispatch`
+- `prepare`
+- `ocr`
+- `extract`
+- `evaluate`
+- `rescue`
+- `persist`
+- `executed`
+
+### 请求示例
+
+```bash
+curl 'http://127.0.0.1:8096/api/audit/run/11'
+```
+
+### 返回示例
+
+```json
+{
+  "code": 200,
+  "message": "ok",
+  "data": {
+    "runId": 11,
+    "documentId": 10,
+    "runNo": 1,
+    "documentFileId": 11,
+    "status": "completed",
+    "phase": "executed",
+    "resultStatus": "review",
+    "ruleSetId": 29,
+    "ruleVersionId": 9,
+    "ruleTypeId": "contract.sale",
+    "rescueApplied": true,
+    "totalScore": 89.0,
+    "passedCount": 24,
+    "failedCount": 4,
+    "skippedCount": 0,
+    "startedAt": "2026-04-28T19:01:01.766352+08:00",
+    "finishedAt": "2026-04-28T19:03:11.044894+08:00"
+  }
+}
+```
+
+---
+
+## 5. 查询评查结果
+
+### 路径
+
+```http
+GET /audit/result/{runId}
+```
+
+### 用途
+
+- 查询本次 run 的完整结果
+- 包括：
+  - 规则结果
+  - 抽取字段
+  - 运行错误
+  - rescue 结果
+  - metrics
+  - artifacts
+
+### 请求示例
+
+```bash
+curl 'http://127.0.0.1:8096/api/audit/result/11'
+```
+
+### 返回结构说明
+
+顶层字段：
+
+| 字段 | 说明 |
+|---|---|
+| `runId` | 运行 ID |
+| `documentId` | 文档 ID |
+| `documentFileId` | 本次锁定的文件 ID |
+| `status` | 运行状态 |
+| `totalScore` | 总分 |
+| `passedCount` | 通过数 |
+| `failedCount` | 失败数 |
+| `skippedCount` | 跳过数 |
+| `phase` | 当前阶段 |
+| `resultStatus` | 总体结果 |
+| `rescueApplied` | 是否执行 rescue |
+| `ruleSetId` | 规则集 ID |
+| `ruleVersionId` | 规则版本 ID |
+| `startedAt` / `finishedAt` | 起止时间 |
+| `rules` | 规则结果列表 |
+| `fields` | 抽取字段列表 |
+| `errors` | 错误列表 |
+| `rescueOutcomes` | 补救结果列表 |
+| `metrics` | 阶段指标 |
+| `artifacts` | 产物列表 |
+
+### 返回示例（节选）
+
+```json
+{
+  "code": 200,
+  "message": "ok",
+  "data": {
+    "runId": 11,
+    "documentId": 10,
+    "documentFileId": 11,
+    "status": "completed",
+    "totalScore": 89.0,
+    "passedCount": 24,
+    "failedCount": 4,
+    "skippedCount": 0,
+    "phase": "executed",
+    "resultStatus": "review",
+    "rescueApplied": true,
+    "ruleSetId": 29,
+    "ruleVersionId": 9,
+    "startedAt": "2026-04-28T19:01:01.766352+08:00",
+    "finishedAt": "2026-04-28T19:03:11.044894+08:00",
+    "rules": [
+      {
+        "ruleId": "MM-SALE-012",
+        "ruleName": "甲方信用代码校验",
+        "passed": false,
+        "status": "executed",
+        "risk": "medium",
+        "score": 3.0,
+        "failMessage": "甲方统一社会信用代码校验位错误"
+      }
+    ],
+    "fields": [
+      {
+        "fieldName": "合同名称",
+        "valueText": "智慧法务平台建设采购项目合同",
+        "confidence": 0.9991
+      }
+    ],
+    "rescueOutcomes": [
+      {
+        "ruleId": "MM-SALE-012",
+        "status": "final_fail",
+        "finalStatus": "review",
+        "requiresHumanReview": true,
+        "failureReason": "Agent (4 iter, requires_human): token_budget_exhausted"
+      }
+    ],
+    "metrics": {
+      "ocrSeconds": 79.06,
+      "extractSeconds": 11.87,
+      "evaluateSeconds": 9.9,
+      "totalSeconds": 100.83,
+      "pageCount": 2,
+      "fieldCount": 35,
+      "ruleCount": 28,
+      "rescueRuleCount": 5,
+      "artifactCount": 8
+    },
+    "artifacts": [
+      {
+        "artifactType": "ocr_json",
+        "fileName": "ocr_result.json",
+        "fileExt": "json",
+        "mimeType": "application/json"
+      }
+    ]
+  }
+}
+```
+
+---
+
+## 6. worker 日志怎么看
+
+worker 关键日志已经做了可读化，重点看这两类：
+
+### 投递日志
+
+```text
+run_id=13 已投递到 worker 队列: queue=leaudit.normal, speed=normal, task_id=...
+```
+
+### 执行日志
+
+```text
+run_id=13 worker开始执行: queue=leaudit.normal, speed=normal, filename=版本归档验证合同.docx
+```
+
+结合状态查询接口可以快速判断：
+
+- 是否已经成功投递
+- 是否已被 worker 消费
+- 跑的是 `urgent` 还是 `normal`
+
+---
+
+## 7. 前端建议接法
+
+### 文档上传页
+
+1. 调 `POST /upload`
+2. 读取返回：
+   - `documentId`
+   - `versionGroupKey`
+   - `versionNo`
+   - `duplicateUpload`
+   - `run`
+
+### 自动评查场景
+
+如果 `autoRun=true` 且返回里 `run != null`：
+
+1. 取 `run.runId`
+2. 轮询 `GET /audit/run/{runId}`
+3. `status=completed/failed` 后停止轮询
+4. 再调 `GET /audit/result/{runId}`
+
+### 列表页
+
+列表页建议默认只展示：
+
+- `is_latest_version = true` 的 document
+
+点击某条后，再按：
+
+- `versionGroupKey`
+
+展开其历史版本。

docs/接口/新系统版_documents_list接口.md

@@ -0,0 +1,307 @@
+# 新系统版 `documents/list` 接口
+
+这份文档专门说明当前 `leaudit-platform` 里已经落地的“新系统版文档列表接口”。
+
+目标很明确：
+
+- 前端文档列表只看“最新版本”
+- 同名文档的历史版本直接归到同一个版本链
+- 列表接口直接返回历史版本摘要，前端不用自己再拼版本关系
+
+---
+
+## 1. 接口路径
+
+```http
+GET /api/documents/list
+```
+
+---
+
+## 2. 当前接口语义
+
+这个接口不是“把所有上传记录平铺出来”。
+
+它的语义是：
+
+- 每个 `version_group_key` 只返回一条“最新版本文档”
+- 这条最新版本文档下面附带 `historyVersions`
+- `historyVersions` 里放的是同组下更老的版本摘要
+
+也就是说，前端主列表看到的是：
+
+- 当前版本
+- 是否有历史版本
+- 一共有多少版本
+- 历史版本有哪些
+
+---
+
+## 3. 请求参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|---|---|---:|---|
+| `page` | int | 否 | 页码，从 `1` 开始，默认 `1` |
+| `pageSize` | int | 否 | 每页数量，默认 `20`，最大 `100` |
+| `keyword` | string | 否 | 按文件名或归一化名称模糊搜索 |
+| `typeCode` | string | 否 | 文档类型编码，例如 `contract.sale` |
+| `region` | string | 否 | 区域 |
+| `processingStatus` | string | 否 | 文档处理状态 |
+| `resultStatus` | string | 否 | 最新 run 的结果状态 |
+
+请求示例：
+
+```bash
+curl 'http://127.0.0.1:8096/api/documents/list?page=1&pageSize=5'
+```
+
+带筛选示例：
+
+```bash
+curl 'http://127.0.0.1:8096/api/documents/list?page=1&pageSize=2&keyword=版本归档&typeCode=contract.sale&region=default'
+```
+
+---
+
+## 4. 返回结构
+
+返回模型是分页结构：
+
+```json
+{
+  "code": 200,
+  "message": "ok",
+  "data": {
+    "total": 1,
+    "page": 1,
+    "pageSize": 20,
+    "totalPages": 1,
+    "documents": []
+  }
+}
+```
+
+其中 `documents[]` 的单条结构核心字段如下：
+
+| 字段 | 说明 |
+|---|---|
+| `documentId` | 当前最新版本文档 ID |
+| `internalDocumentNo` | 平台内部追踪号 |
+| `versionGroupKey` | 版本归档组键 |
+| `versionNo` | 当前版本号 |
+| `rootVersionId` | 版本链根文档 ID |
+| `previousVersionId` | 上一版本文档 ID |
+| `typeId` | 文档类型 ID |
+| `typeCode` | 文档类型编码 |
+| `region` | 区域 |
+| `normalizedName` | 归一化后的名称 |
+| `fileId` | 当前主文件 ID |
+| `fileName` | 文件名 |
+| `fileExt` | 文件扩展名 |
+| `mimeType` | MIME 类型 |
+| `fileSize` | 文件大小 |
+| `ossUrl` | 对象存储路径 |
+| `processingStatus` | 文档处理状态 |
+| `currentRunId` | 当前 run ID |
+| `runStatus` | 当前 run 状态 |
+| `resultStatus` | 当前 run 结果状态 |
+| `totalScore` | 总分 |
+| `passedCount` | 通过数 |
+| `failedCount` | 失败数 |
+| `skippedCount` | 跳过数 |
+| `updatedAt` | 更新时间 |
+| `hasHistory` | 是否有历史版本 |
+| `totalVersions` | 总版本数 |
+| `historyVersions` | 历史版本摘要列表 |
+
+`historyVersions[]` 结构：
+
+| 字段 | 说明 |
+|---|---|
+| `documentId` | 历史版本文档 ID |
+| `fileId` | 历史版本文件 ID |
+| `versionNo` | 历史版本号 |
+| `fileName` | 文件名 |
+| `fileExt` | 文件扩展名 |
+| `processingStatus` | 处理状态 |
+| `runStatus` | 运行状态 |
+| `resultStatus` | 结果状态 |
+| `updatedAt` | 更新时间 |
+
+---
+
+## 5. SQL 逻辑
+
+### 5.1 主列表计数 SQL
+
+```sql
+SELECT COUNT(*)
+FROM leaudit_documents d
+JOIN leaudit_document_files f
+  ON f.document_id = d.id
+LEFT JOIN leaudit_document_types dt
+  ON dt.id = d.type_id
+LEFT JOIN leaudit_audit_runs ar
+  ON ar.id = d.current_run_id
+WHERE d.is_latest_version = true
+  AND d.deleted_at IS NULL
+  AND f.is_active = true
+  AND f.file_role = 'primary'
+  -- 可选过滤：
+  -- AND (f.file_name ILIKE :keyword OR d.normalized_name ILIKE :keyword)
+  -- AND dt.code = :type_code
+  -- AND d.region = :region
+  -- AND d.processing_status = :processing_status
+  -- AND ar.result_status = :result_status
+```
+
+### 5.2 主列表分页 SQL
+
+```sql
+SELECT
+    d.id AS document_id,
+    d.biz_document_id AS internal_document_no,
+    d.version_group_key,
+    d.version_no,
+    d.root_version_id,
+    d.previous_version_id,
+    d.type_id,
+    dt.code AS type_code,
+    d.region,
+    d.normalized_name,
+    d.processing_status,
+    d.current_run_id,
+    d.updated_at,
+    f.id AS file_id,
+    f.file_name,
+    f.file_ext,
+    f.mime_type,
+    f.file_size,
+    f.oss_url,
+    ar.status AS run_status,
+    ar.result_status,
+    ar.total_score,
+    ar.passed_count,
+    ar.failed_count,
+    ar.skipped_count,
+    vc.total_versions,
+    COALESCE(vc.total_versions, 1) > 1 AS has_history
+FROM leaudit_documents d
+JOIN leaudit_document_files f
+  ON f.document_id = d.id
+LEFT JOIN leaudit_document_types dt
+  ON dt.id = d.type_id
+LEFT JOIN leaudit_audit_runs ar
+  ON ar.id = d.current_run_id
+LEFT JOIN (
+    SELECT version_group_key, COUNT(*) AS total_versions
+    FROM leaudit_documents
+    WHERE deleted_at IS NULL
+    GROUP BY version_group_key
+) vc
+  ON vc.version_group_key = d.version_group_key
+WHERE d.is_latest_version = true
+  AND d.deleted_at IS NULL
+  AND f.is_active = true
+  AND f.file_role = 'primary'
+ORDER BY d.updated_at DESC, d.id DESC
+LIMIT :limit OFFSET :offset
+```
+
+### 5.3 历史版本摘要 SQL
+
+```sql
+SELECT
+    d.version_group_key,
+    d.id AS document_id,
+    d.version_no,
+    d.processing_status,
+    d.updated_at,
+    f.id AS file_id,
+    f.file_name,
+    f.file_ext,
+    ar.status AS run_status,
+    ar.result_status
+FROM leaudit_documents d
+JOIN leaudit_document_files f
+  ON f.document_id = d.id
+ AND f.is_active = true
+ AND f.file_role = 'primary'
+LEFT JOIN leaudit_audit_runs ar
+  ON ar.id = d.current_run_id
+WHERE d.version_group_key = ANY(:group_keys)
+  AND d.is_latest_version = false
+  AND d.deleted_at IS NULL
+ORDER BY d.version_group_key, d.version_no DESC, d.id DESC
+```
+
+---
+
+## 6. 为什么新系统要这么做
+
+因为现在我们已经不是老系统那种“文档记录 + 旁路版本信息”的模式了。
+
+当前新系统已经有真正的版本链字段：
+
+- `version_group_key`
+- `version_no`
+- `previous_version_id`
+- `root_version_id`
+- `is_latest_version`
+- `normalized_name`
+
+所以列表天然应该是：
+
+- 主列表 = 最新版本
+- 展开项 = 历史版本
+
+而不是把所有版本平铺在一个列表里。
+
+---
+
+## 7. 当前代码落点
+
+实现代码在这些文件：
+
+- 路由：`fastapi_modules/fastapi_leaudit/controllers/documentController.py`
+- 服务接口：`fastapi_modules/fastapi_leaudit/services/documentService.py`
+- VO：`fastapi_modules/fastapi_leaudit/domian/vo/documentVo.py`
+- 具体实现：`fastapi_modules/fastapi_leaudit/services/impl/documentServiceImpl.py`
+
+---
+
+## 8. 当前验证结果
+
+已经实际验证通过：
+
+```bash
+curl 'http://127.0.0.1:8096/api/documents/list?page=1&pageSize=5'
+```
+
+以及：
+
+```bash
+curl 'http://127.0.0.1:8096/api/documents/list?page=1&pageSize=2&keyword=版本归档&typeCode=contract.sale&region=default'
+```
+
+验证结论：
+
+- 接口正常返回
+- 主列表只返回最新版本
+- `historyVersions` 能正确带出历史版本摘要
+- 已验证版本组 `4e02e455aa504cb9b75a254727f1bb4c`
+  - `documentId=13` 是当前最新 `v3`
+  - `documentId=12` 是 `v2`
+  - `documentId=11` 是 `v1`
+
+---
+
+## 9. 下一步建议
+
+如果后面前端需要更完整的“版本展开页”，再补一个：
+
+```http
+GET /api/documents/{documentId}/versions
+```
+
+但当前列表页场景下，`/documents/list` 已经够用了。