feat: add document versioning and list API

2026-04-29 11:48:50 +08:00
parent f3b83c9979
commit b45d61fa97
14 changed files with 1693 additions and 92 deletions
@@ -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`
+
+展开其历史版本。