docs: reorganize backend project documentation

docs/接口/文档上传与列表接口分析.md

@@ -1,6 +1,8 @@
 # 文档上传与列表 — 接口分析 & 接入方案
 
 > 所有信息已逐文件验证。源代码位置均已标注。
+>
+> 说明：这份文档已经吸收旧的 `新系统版_documents_list接口.md` 与 `文档上传与评查接口.md`，后续以本文件作为文档上传、列表、详情、更新、删除、评查触发与状态查询的统一说明。
 
 ---
 
@@ -23,7 +25,7 @@ URL:    POST /api/upload
 | `typeCode` | str | typeId/typeCode 二选一 | None | 文档类型编码，如 `contract.construction` |
 | `region` | str | 否 | `"default"` | 地区标识 |
 | `fileRole` | str | 否 | `"primary"` | 文件角色：primary/attachment/template |
-| `createdBy` | int | 否 | None | 上传用户 ID |
+| `createdBy` | int | 否 | None | 前端可传，但后端当前以 JWT 中的 `user_id` 为准 |
 | `autoRun` | bool | 否 | `false` | 是否上传后自动触发评查 |
 | `speed` | str | 否 | `"normal"` | urgent / normal |
 
@@ -124,17 +126,119 @@ URL:    GET /api/documents/list
 
 ---
 
-### 1.3 缺失的后端接口
+### 1.3 文档详情 / 更新 / 删除（现已实现）
+
+#### GET /api/documents/{id}
+
+- 用途：获取单个文档详情
+- 返回：`Result[DocumentDetailVO]`
+- 关键字段：
+  - 继承列表接口的版本链、文件、run、统计字段
+  - 新增 `documentNumber`、`remark`、`isTestDocument`、`auditStatus`、`pageCount`
+- 历史版本：`historyVersions` 返回同一 `version_group_key` 下除当前文档外的其它未删除版本
+
+#### PUT /api/documents/{id}
+
+- 用途：更新文档元数据
+- 请求体：`DocumentUpdateDTO`
+
+```json
+{
+  "documentNumber": "粤烟合同〔2026〕001号",
+  "remark": "地市管理员修订备注",
+  "isTestDocument": false,
+  "auditStatus": 1
+}
+```
+
+- 字段说明：
+  - `documentNumber`：若 `leaudit_documents.document_number` 列存在则写入
+  - `remark`：若 `leaudit_documents.remark` 列存在则写入
+  - `isTestDocument`：若 `leaudit_documents.is_test_document` 列存在则写入
+  - `auditStatus`：若 `leaudit_documents.audit_status` 列存在则写入；若当前环境未加该列，则接口忽略该字段但不报错
+
+#### DELETE /api/documents/{id}
+
+- 用途：软删除文档
+- 行为：
+  - `leaudit_documents.deleted_at = now()`
+  - 当前文档的 active file 置为 `is_active = false`
+  - 若删除的是当前最新版本，则自动把同版本链中剩余的最高版本提升为 `is_latest_version = true`
+
+#### 数据隔离规则（已在后端强制执行）
+
+| 角色 | 范围 |
+|------|------|
+| `super_admin` / `provincial_admin` | 全量文档 |
+| `admin` | **仅本地市 `region = user.area`** |
+| `common` | **仅自己上传的文档 `created_by = current_user_id`** |
+
+额外约束：
+- `admin` 若在列表接口传入其他地市 `region`，后端直接返回空结果
+- `common` 若试图访问、修改、删除他人文档，后端返回“文档不存在或无权访问”
+
+#### 尚未完成
 
 | 操作 | 当前 | 需要 |
 |------|------|------|
-| 删除文档 | ❌ | `DELETE /api/documents/{id}` — 软删除 |
-| 编辑元数据 | ❌ | `PUT /api/documents/{id}` — 更新备注、测试标记等 |
-| 文档详情 | ❌ | `GET /api/documents/{id}` — 单文档查询 |
 | 附件追加 | ❌ | `POST /api/documents/{id}/attachments` — fileRole=attachment |
 
 ---
 
+### 1.4 自动评查 / 手动评查 / 状态结果查询
+
+#### POST /api/upload
+
+- 上传成功且 `autoRun=true` 时，后端会直接调用 `AuditService.Run()` 创建 run
+- 队列档位当前只保留：
+  - `urgent`
+  - `normal`
+
+#### POST /api/audit/run
+
+- 用途：对已存在文档手动触发评查
+- 典型参数：
+  - `documentId`
+  - `speed=normal|urgent`
+- 当前收口：
+  - 若同一文档已有活动 run，后端优先复用，不重复创建
+
+#### GET /api/audit/run/{runId}
+
+- 用途：查询评查任务状态
+- 关键状态：
+  - `queued`
+  - `running`
+  - `completed`
+  - `failed`
+- 关键阶段：
+  - `dispatch`
+  - `prepare`
+  - `ocr / extraction / evaluation / rescue / persist`
+
+#### GET /api/audit/result/{runId}
+
+- 用途：查询评查结果
+- 返回来源：
+  - `leaudit_rule_results`
+  - `leaudit_field_results`
+  - `leaudit_run_metrics`
+  - `leaudit_run_errors`
+
+#### 当前评查链路口径
+
+1. 上传文档
+2. 建立 `leaudit_documents / leaudit_document_files`
+3. 创建 `leaudit_audit_runs`
+4. 按 `speed` 投递 `leaudit.urgent` 或 `leaudit.normal`
+5. worker 按 `runId` 查库
+6. bridge 下载文档与规则 YAML 到本地临时文件
+7. `NativeRunner` 构建原生 `AuditCtx`
+8. `AuditService.audit(ctx)` 执行
+9. `StorageAdapter` 结果写回 `leaudit_*`
+
+---
+
 ## 二、前端调用现状（已验证）
 
 ### 2.1 上传 — `uploadDocumentToServer()`