docs: 接口文档 v1.2 同步响应字段精简

- §4.1 POST /scans 同步响应示例: 精简为 7 顶层字段
- §4.2 GET /scans/{id} pending 状态示例: 去掉 verdict/score
- §5 数据模型重写:
  - §5.1 响应字段: 精简为 6 个（task_id/action/reason/status/file/meta）
  - §5.2 action 取值: 去掉 pass_with_flag（合并进 pass）
  - §5.3 file 结构: 精简为 5 字段，砍 real_ext/declared_ext
  - §5.4 meta 结构: 精简为 2 字段（scan_duration_ms/scanned_at）
  - §5.5 新增内部判定字段章节: verdict/score/findings/triggered/open_risk/extracted 标注为内部使用不对外暴露
- §6 检测规则清单: 更新说明（findings 不对外暴露）
- 文档版本号: v1.1 → v1.2

docs/接口文档.md

@@ -2,7 +2,7 @@
 
 | 项目 | 内容 |
 |---|---|
-| 文档版本 | v1.1（2026-10-27 对齐当前代码实现） |
+| 文档版本 | v1.2（2026-10-29 响应字段精简，只暴露调用方必需字段） |
 | 接口版本 | `/api/v1` |
 | 适用系统 | 光闸内外网文件摆渡系统 |
 | 保密级别 | **内部交付文档**，请勿公开传播 |
@@ -286,51 +286,25 @@ signature = HMAC-SHA256(response_key, payload)  → 小写十六进制
 ```json
 {
   "task_id": "3f8a9c2e1b7d4e6f8a0b2c4d6e8f0a1b",
-  "verdict": "malicious",
-  "score": 85.0,
   "action": "reject",
   "reason": "检测到 VBA 宏 + DDEAUTO 自动执行",
   "status": "completed",
   "file": {
+    "filename": "起诉状.docx",
     "sha256": "a1b2c3...",
     "md5": "d4e5f6...",
     "size": 284915,
-    "real_type": "Microsoft Word 2007+",
+    "real_type": "Microsoft Word 2007+"
-    "real_ext": ".docx",
-    "declared_ext": ".docx",
-    "filename": "起诉状.docx"
   },
-  "findings": [
-    {
-      "engine": "document",
-      "layer": "L2",
-      "severity": "critical",
-      "rule": "DDEAutoExecution",
-      "detail": "检测到 DDE/DDEAUTO 字段：DDEAUTO c:\\windows\\system32\\cmd.exe",
-      "extracted_path": "word/settings.xml",
-      "weight": 65.0,
-      "meta": {}
-    }
-  ],
-  "extracted": [
-    { "path": "word/vbaProject.bin", "filename": "vbaProject.bin", "size": 10240, "depth": 1, "sha256": "" }
-  ],
-  "triggered": [
-    { "type": "rule_override", "rule": "DDEAutoExecution", "action": "reject", "engine": "document" }
-  ],
   "meta": {
     "scan_duration_ms": 1840,
-    "engines": ["structure", "clamav", "document", "keywords", "yara", "binary"],
+    "scanned_at": "2026-10-27T08:30:00Z"
-    "engine_errors": [],
-    "clamav": { "version": "ClamAV 1.5.4", "signature_date": "2026-10-27" },
-    "policy_version": "2026.10.1",
-    "policy_sha256": "…",
-    "scanned_objects": 3,
-    "scanned_at": "2026-10-27T08:30:00+00:00"
   }
 }
 ```
 
+> **设计原则**：接口只暴露调用方必须知道的字段，内部权重、严重度、引擎层、策略链等实现细节不对外返回。调用方拿到 `action` 即可直接决策，无需二次分析。
+
 **响应 200（异步受理）**
 
 ```json
@@ -350,11 +324,11 @@ if result["status"] != "completed":
 
 action = result["action"]
 if action == "reject":
-    reject_transfer(reason=result["reason"])      # 拒绝并向用户展示 reason
+    reject_transfer(reason=result["reason"])      # 拦截，向用户展示 reason
 elif action == "manual_review":
-    route_to_human_review(result["task_id"])       # 转人工
+    route_to_human_review(result["task_id"])       # 暂不放行，转人工
 else:
-    allow_transfer()                                # pass / pass_with_flag
+    allow_transfer()                                # pass，正常放行
 ```
 
 ---
@@ -373,9 +347,7 @@ else:
 {
   "task_id": "…",
   "status": "running",
-  "verdict": "pending",
   "action": "pending",
-  "score": 0.0,
   "reason": ""
 }
 ```
@@ -506,93 +478,78 @@ else:
 
 ## 5. 数据模型
 
-### 5.1 结论字段
+### 5.1 响应字段
 
 | 字段 | 类型 | 说明 |
 |---|---|---|
-| `task_id` | string | 任务标识，全局唯一 |
+| `task_id` | string | 任务标识，全局唯一，用于后续查询与审计追溯 |
-| `verdict` | enum | 总体判定，见 §5.2 |
+| `action` | enum | **调用方决策依据**，见 §5.2 |
-| `score` | float | 风险评分，0~100 |
-| `action` | enum | 处置建议，见 §5.3 |
 | `reason` | string | 人可读的判定理由，可直接展示给用户 |
 | `status` | enum | `pending` / `running` / `completed` / `failed` |
+| `file` | object | 文件追溯信息，见 §5.3 |
+| `meta` | object | 基础元信息，见 §5.4 |
 
-### 5.2 verdict 取值
+### 5.2 action 取值（调用方唯一决策依据）
+
+| 值 | 含义 | 调用方动作 |
+|---|---|---|
+| `pass` | 未发现风险或仅极轻微信号 | 正常放行 |
+| `manual_review` | 可疑，需人工判断 | **暂不放行**，转入人工复核流程 |
+| `reject` | 判定不可放行 | 拒绝传输，向用户展示 `reason` |
+| `pending` | 异步尚未完成 | 等待轮询 |
+
+> **`action` 是调用方唯一需要判断的字段**，不需要关心内部权重、严重度、触发了几条规则。
+
+### 5.3 file 结构
+
+| 字段 | 说明 |
+|---|---|
+| `filename` | 原始文件名 |
+| `sha256` | 文件哈希，用于去重与追溯举证 |
+| `md5` | 文件哈希，兼容场景使用 |
+| `size` | 字节数 |
+| `real_type` | 内容判定的真实类型描述（如 `JPEG image data`） |
+
+> 不对外暴露 `real_ext` / `declared_ext`（内部判定使用）。
+
+### 5.4 meta 结构
+
+| 字段 | 说明 |
+|---|---|
+| `scan_duration_ms` | 本次检测耗时（毫秒） |
+| `scanned_at` | 检测时间（UTC） |
+
+> 不对外暴露 `engines` / `engine_errors` / `clamav` 版本 / `policy_version` / `policy_sha256` / `scanned_objects` 等内部实现细节。这些信息保留在服务端控制台与审计日志中，运维人员按需查询。
+
+---
+
+### 5.5 内部判定字段（不对外暴露）
+
+以下字段存在于服务端内部（控制台、审计日志、DB 记录），不通过 API 返回。调用方无需关心。
+
+**verdict（内部总体判定）**
 
 | 值 | 含义 |
 |---|---|
 | `clean` | 未发现风险 |
-| `suspicious` | 存在可疑信号，需要关注或人工判断 |
+| `suspicious` | 存在可疑信号 |
 | `malicious` | 判定为恶意 |
-| `error` | 检测过程异常（如引擎不可用），结论不可信 |
+| `error` | 检测过程异常 |
 | `pending` | 尚未完成 |
 
-### 5.3 action 取值
+**score（内部权重和，0~100）** — 调用方不做二次分析，不对外暴露。
 
-| 值 | 含义 | 建议调用方动作 |
+**findings（内部命中信号列表）** — 每条含 engine / layer / severity / rule / detail / weight / meta 等字段，供安全团队审计与问题追溯。不对外暴露。
-|---|---|---|
-| `pass` | 未发现问题 | 正常放行 |
-| `pass_with_flag` | 存在低风险信号 | 放行，但建议记录标记 |
-| `manual_review` | 需人工判断 | **暂不放行**，转入人工复核流程 |
-| `reject` | 判定不可放行 | 拒绝传输，向用户展示 `reason` |
-| `pending` | 尚未裁决 | 等待异步结果 |
 
-> **`action` 与 `verdict` 解耦使用。** 业务逻辑请依据 `action`，`verdict` 供人查看与统计。
+**triggered（内部策略链触发记录）** — rule_override / zero_tolerance 等，不对外暴露。
 
-### 5.4 findings 结构
+**open_risk / extracted（内部辅助分析与解包过程）** — 不对外暴露。
-
-| 字段 | 类型 | 说明 |
-|---|---|---|
-| `engine` | string | 引擎名：`structure` / `extractor` / `clamav` / `document` / `yara` / `binary` |
-| `layer` | string | 检测层：`L0` / `L1` / `L2` / `L2B` / `L3` |
-| `severity` | enum | `info` / `low` / `medium` / `high` / `critical` |
-| `rule` | string | 规则标识 |
-| `detail` | string | 命中详情 |
-| `extracted_path` | string | 信号来自哪个内部路径（顶层文件为空） |
-| `weight` | float | 该信号的风险权重 |
-| `meta` | object | 引擎附加信息 |
-
-### 5.5 严重度与权重对照
-
-| 严重度 | 典型含义 | 权重区间 |
-|---|---|---|
-| `critical` | 确凿的恶意行为，自动执行、外联、路径穿越 | 50 ~ 90 |
-| `high` | 高度可疑，宏调用、危险 API、高熵加壳 | 30 ~ 80 |
-| `medium` | 可疑但存在合理场景，外部链接、可疑导入 | 15 ~ 45 |
-| `low` | 轻微信号，仅编码字符串、无签名 | 5 ~ 20 |
-| `info` | 信息性提示 | 0 |
-
-### 5.6 file 结构
-
-| 字段 | 说明 |
-|---|---|
-| `sha256` / `md5` | 文件哈希，用于去重与追溯 |
-| `size` | 字节数 |
-| `real_type` | 内容判定的真实类型描述 |
-| `real_ext` | 真实扩展名（由内容推导） |
-| `declared_ext` | 文件名声明的扩展名 |
-| `filename` | 原始文件名 |
-
-### 5.7 meta 结构
-
-| 字段 | 说明 |
-|---|---|
-| `scan_duration_ms` | 检测耗时（毫秒） |
-| `engines` | 参与的引擎列表 |
-| `engine_errors` | 不可用的引擎列表，非空说明结论可能不完整 |
-| `clamav` | ClamAV 版本与签名库编号 |
-| `policy_version` | 判定所依据的策略版本 |
-| `policy_sha256` | 策略文件哈希 |
-| `scanned_objects` | 实际检测的对象数（含递归解包出的子文件） |
-| `scanned_at` | 检测时间（UTC） |
-
-> **`meta.clamav` 与 `meta.policy_version` 建议留存**，用于检测结果的有效性举证。
 
 ---
 
 ## 6. 检测规则清单
 
-以下规则命中时会出现在 `findings` 中。**规则清单公开用于解释结论，不含检测规则的具体实现内容。**
+以下规则命中时会在服务端审计日志中留下记录，调用方通过 `reason` 字段获得人可读的结论说明。**规则清单公开用于解释结论，不含检测规则的具体实现内容。**
 
 ### 6.1 L0 结构层