场外前端：单据核对区显示不出字段 —— 邮件详情的单据只是摘要，须与识别接口按 task_id 合并

## 现象 "单据核对与运营动作"里的单据信息全是 `--`： ``` 20260914-001-A01 subscription · -- · -- 申请日期 -- 申购金额 / 赎回份额 -- / -- 机构 -- 基金代码 -- ``` 而 OCR 识别字段里这些值都**有**（基金代码 15911 / 申请日期 2026-09-11 / 申购金额 5000.00 / 机构星澜财富服务中心）。所以不是"没保存"，是**渲染时取错了数据源**。 ## 根因：同一个单据，两个接口给的不是同一份字段 | 接口 | `attachments[].documents[]` 的字段 | |---|---| | `GET /mails/{id}`（`_mail_detail`） | **只有摘要 4 个键**：`task_id` / `document_type` / `status` / `operator_decision` | | `GET /mails/{id}/recognition-fields`（`_recognition_payload`） | **全部标准化字段**：`fund_code` / `fund_name` / `application_no` / `application_date` / `agency` / `subscription_amount_yuan` … | `renderDocuments()` 渲染单据 kv 用的是 `state.documents`，而 `loadMail()` 只从 **邮件详情**那一份构建它 ⇒ 标准化字段根本不在对象里，只能显示 `--`。前端其实**已经有** `syncDocumentsFromRecognition()` 想做这件事，但 `loadMail()` 里是「先 `syncDocumentsFromRecognition(...)`、紧接着又用邮件详情重建 `state.documents`」 —— 合并结果被后一行覆盖掉了（这也是保存识别字段后那次同步没生效的原因）。 ## 修法 1. `loadMail()`：构建完 `state.documents`（邮件侧摘要）之后**再调用一次** `syncDocumentsFromRecognition(state.recognition)`，把识别侧的标准字段合并进来； 2. `syncDocumentsFromRecognition()` 由"整段替换"改为**逐条按 `task_id` 合并**： - 两侧都有 → 识别侧字段优先，摘要里独有的键（`status` / `operator_decision`）保留； - 只有摘要侧 → 原样保留（不因为识别接口没提到就丢单据）； - 只有识别侧 → 也补进来（例如刚生成、摘要还没刷新）； - 识别接口无 attachments（请求失败等）→ 早退，**不清空**已有单据。 ## 验证 `node --check offsite.js` 通过；并用 Node **从源文件抽出该函数**（不另抄一份逻辑）灌入线上两个接口的真实载荷形态，6+4+3+1 项断言全部通过： - 摘要 + 识别侧全字段 → `fund_code=15911` / `application_date=2026-09-11` / `agency=星澜财富服务中心` / `subscription_amount_yuan=5000.0000`，且 `status=planned`、`operator_decision=未处理` 未被覆盖，`attachment_id` 已补上； - 识别接口返回空 → 邮件侧摘要仍在； - 邮件侧独有单据保留、识别侧独有单据出现。前端相关测试：`tests/unit/api/test_portal_frontend.py` → 45 passed, 1 failed （仍是组员在改的投顾页，与本次无关）；`pytest tests/unit/api -k "offsite or operations"` → 1 passed。 ## 说明：为什么没改后端也可以让 `_mail_detail` 直接带上标准化字段，但那会改动已被文档化的接口载荷形状；而前端本来就有合并函数、意图明确（`save-ocr` 路径早就在调用它），因此按"恢复原有意图 + 按 task_id 正确合并"来修，零接口契约风险。
2026-09-14 22:23:49 +08:00
parent ae7a89f33d
commit 5b97475950
1 changed files with 43 additions and 13 deletions
@@ -373,26 +373,53 @@ if (requireOperator()) {
    renderMetrics(); renderStatusTabs(); renderMailList(); renderDetail(); renderDocuments(); renderNotice(); renderStatistics();
  }

+  /**
+   * 把识别接口返回的**单据标准字段**合并进 `state.documents`。
+   *
+   * 为什么必须合并：邮件详情的 `attachments[].documents[]` 只是一个**摘要**
+   * （`task_id` / `document_type` / `status` / `operator_decision`），
+   * 基金代码、申请日期、申购金额、机构这些字段**只在识别接口的返回里**
+   * （`_mail_detail` vs `_recognition_payload`）。只用摘要渲染，
+   * "单据核对与运营动作"里的单据信息就全是 `--`。
+   *
+   * 合并口径（**逐条按 task_id 匹配**，不是整段替换）：
+   *   - 两侧都有 → 识别侧字段优先，摘要里独有的键（status/operator_decision）保留；
+   *   - 只有摘要侧 → 原样保留（不能因为识别接口没提到就丢掉单据）；
+   *   - 只有识别侧 → 也要出现（例如刚生成、邮件摘要还没刷新）。
+   */
  function syncDocumentsFromRecognition(payload) {
    const attachments = Array.isArray(payload?.attachments) ? payload.attachments : [];
    if (!attachments.length || !state.mail) return;
-    const documentsByAttachment = new Map(
-      attachments.map((attachment) => [
-        attachment.attachment_id,
-        (attachment.documents || []).map((document) => ({
+    const recognitionDocuments = new Map();
+    attachments.forEach((attachment) => {
+      (attachment.documents || []).forEach((document) => {
+        if (!document?.task_id) return;
+        recognitionDocuments.set(document.task_id, {
          ...document,
          attachment_id: attachment.attachment_id,
-        })),
-      ]),
-    );
+        });
+      });
+    });
+    if (!recognitionDocuments.size) return;
    state.mail = {
      ...state.mail,
-      attachments: (state.mail.attachments || []).map((attachment) => ({
-        ...attachment,
-        documents: documentsByAttachment.get(attachment.attachment_id)
-          || attachment.documents
-          || [],
-      })),
+      attachments: (state.mail.attachments || []).map((attachment) => {
+        const summaries = attachment.documents || [];
+        const merged = summaries.map((document) => {
+          const recognized = recognitionDocuments.get(document.task_id);
+          return recognized ? { ...document, ...recognized } : document;
+        });
+        const known = new Set(summaries.map((document) => document.task_id));
+        return {
+          ...attachment,
+          documents: merged.concat(
+            [...recognitionDocuments.values()].filter(
+              (document) => document.attachment_id === attachment.attachment_id
+                && !known.has(document.task_id),
+            ),
+          ),
+        };
+      }),
    };
    state.mailDetails[state.mail.mail_id] = state.mail;
    state.documents = state.mail.attachments.flatMap((attachment) => (
@@ -411,6 +438,9 @@ if (requireOperator()) {
    state.recognition = recognitionResponse.data || {};
    state.ocrDrafts = Object.fromEntries((state.recognition.attachments || []).map((item) => [item.attachment_id, { ...(item.effective_fields || item.extracted_fields || {}) }]));
    state.documents = (state.mail.attachments || []).flatMap((attachment) => (attachment.documents || []).map((document) => ({ ...document, attachment_id: document.attachment_id || attachment.attachment_id })));
+    // 邮件详情给的单据只是摘要，标准化字段在识别接口那一份里 ⇒ 这里必须再合并一次。
+    // 缺了这一步，"单据核对与运营动作"的单据信息（申请日期/申购金额/机构/基金代码）全是 `--`。
+    syncDocumentsFromRecognition(state.recognition);
    const taskIds = [...new Set(state.documents.map((item) => item.task_id).filter(Boolean))];
    const results = await Promise.all(taskIds.map(async (taskId) => {
      const [nlResult, ruleResult] = await Promise.allSettled([