mail-yubao/docx/异常场景与系统韧性设计.md

# 异常场景与系统韧性设计（邮件自动预报系统专用）

> 本章为 `docx/需求规格-邮件自动预报-v0.2.md` 第 14 章正文；与 §5–§8 状态机、CC 接口、数据模型、运营 SOP 一一对应。  
> 常量约定：`IMPORT_LOCK_TTL=120s`；`IMPORTING_TIMEOUT=180s`；`PARSING_STALE=10min`；`COMPENSATION_MAX_RETRY=3`；`IMAP_CONNECT_TIMEOUT=30s`；`IMAP_READ_TIMEOUT=60s`；`CC_HTTP_TIMEOUT=60s`；`CC_REPLAY_ON_410=1`；`SHIPMENT_ROW_SOFT_LIMIT=1000`；`SHIPMENT_ROW_HARD_LIMIT=5000`。
；**`IMAP_LOOKBACK_DAYS=3`**。  
> **2026-07-23 回写**：拉取=近 N 天已读+未读；**一期无 audit_log**；详见 `docx/现行口径-修订说明-v1.md`。

---

## 1. 输入层异常处理

### 1.1 邮件缺失主题
- **异常描述**：IMAP 入库的 Message `subject` 为空或仅空白。
- **系统行为**：`mail_message.subject` 存 `"(无主题)"`；类型判定仅用正文+附件名；照常进入 `PARSING`。
- **是否允许降级**：是（继续解析）。
- **是否触发告警**：`warn` 日志 `mail.subject_missing`；不计监控告警。
- **用户看到的结果**：列表主题显示「(无主题)」；详情正常。

### 1.2 邮件缺失正文
- **异常描述**：纯附件邮件或正文 HTML/纯文本均为空。
- **系统行为**：正文摘要空串；类型与柜头字段仅从附件/主题提取；无附件则 `REJECTED_VALIDATION`，`last_error=NO_BODY_NO_ATTACHMENT`。
- **是否允许降级**：有附件则继续；无附件则阻断导入路径。
- **是否触发告警**：无附件 → `error` + 指标 `mail.reject_validation`。
- **用户看到的结果**：状态「校验拒绝」；提示「无正文且无附件，无法解析」；可下载原始快照。

### 1.3 邮件无附件
- **异常描述**：类型可能为 NEW/TRANSFER，但无 xlsx/csv/zip。
- **系统行为**：若主题/正文能抽出柜号则写入 `parse_result.container_header`，`shipments=[]`；`mail_type` 仍按 §4 判定；因有效行=0，即使 NEW 也不进 `PENDING_CONFIRM`，停留 `REJECTED_VALIDATION` 或 `PARSED`（非 NEW）+ `last_error=NO_SHIPMENT_ROWS`。
- **是否允许降级**：是（仅展示，不可导入）。
- **是否触发告警**：`warn` `parse.no_attachment`。
- **用户看到的结果**：详情提示「缺少卡派/装箱清单附件」；确认导入入口不可用。

### 1.4 附件格式非 xlsx/csv，且 zip 内无有效文件
- **异常描述**：仅有 pdf/图片/docx，或 zip 解压后无 xlsx/csv/xls。
- **系统行为**：附件仍写入 `mail_attachment`；解析器标记 `template_id=null`；状态 `PARSE_FAILED`，`last_error=NO_SUPPORTED_SPREADSHEET`。
- **是否允许降级**：附件可下载；不调用 SaveContainer。
- **是否触发告警**：`error` `parse.unsupported_attachment`。
- **用户看到的结果**：「不支持的附件格式」+「重新解析」按钮；运营按 SOP 走客户端预报。

### 1.5 附件关键列缺失（仓库ID / 渠道 / 件数）
- **异常描述**：卡派资料表头缺少映射到 `F_FBACode`/`F_Transporter`/`F_CTNS` 的列。
- **系统行为**：整表无法建有效行 → `PARSE_FAILED`，`lineage.missing_columns=[...]`；若仅部分行缺值见 1.7。
- **是否允许降级**：否（不可进 `PENDING_CONFIRM`）。
- **是否触发告警**：`error` `parse.missing_columns`。
- **用户看到的结果**：展示缺失列名列表；可重新解析。

### 1.6 柜号格式非法（非 ISO 6346）
- **异常描述**：抽出柜号未通过校验位（且未关闭 ISO 校验配置）。
- **系统行为**：`container_header.F_ContainerNo` 保留原值并标 `container_no_valid=false`；状态 `REJECTED_VALIDATION`；禁止确认导入。
- **是否允许降级**：Admin 可在详情手工改柜号后触发「重新校验」；不自动猜正确柜号。
- **是否触发告警**：`warn` `parse.invalid_container_no`。
- **用户看到的结果**：「柜号未通过 ISO 校验：{no}」；编辑柜号后可再校验。

### 1.7 货件行半空（件数=0、仓库ID 空等）
- **异常描述**：单行缺少 `F_FBACode` 或 `F_Transporter` 或 `F_CTNS`≤0/空。
- **系统行为**：该行 `row_status=INVALID`，写入 `shipments[]`；不阻断其他 VALID 行；默认不勾选。
- **是否允许降级**：是（柜级部分行导入，§5.7）。
- **是否触发告警**：INVALID 行占比 >30% → `warn` `parse.high_invalid_ratio`。
- **用户看到的结果**：灰显行 + tooltip 列缺失原因；底栏「已选 n / 有效 m」。

### 1.8 超大附件（>20MB）
- **异常描述**：单附件 `size > 20MB`。
- **系统行为**：不落盘完整文件（或落盘后立即拒绝解析）；`mail_attachment` 记 size + `rejected=1`；邮件 `REJECTED_VALIDATION`，`last_error=ATTACHMENT_TOO_LARGE`；仍按 §6.2 标 `\Seen`。
- **是否允许降级**：否。
- **是否触发告警**：`error` `mail.attachment_too_large`。
- **用户看到的结果**：「附件超过 20MB，请客户拆分后重发」；快照仅保留邮件头+正文。

### 1.9 渠道映射词不匹配
- **异常描述**：渠道列值不在 §5.6 黄金表。
- **系统行为**：`F_Transporter`=原文截断 30 字符；行标 `CHANNEL_UNMAPPED`；**仍可为 VALID**（若三必填齐全）；确认页该行黄标警告。
- **是否允许降级**：是（不阻断提交）；CC 若 400 再走补偿。
- **是否触发告警**：`warn` `map.channel_unmapped`（带原词）。
- **用户看到的结果**：警告「渠道未映射：{raw}，将原样提交 CC」；可手工改下拉为标准枚举。

### 1.10 体积/重量含非数字
- **异常描述**：`总体积`/`毛重` 含单位文字或非法字符。
- **系统行为**：剥离常见单位（m³/cbm/kg）后 `parseFloat`；失败则该字段 `null`，行仍 VALID（体积重量非必填）；`lineage` 记 `FIELD_PARSE_FALLBACK`。
- **是否允许降级**：是。
- **是否触发告警**：仅 `debug`/`info`。
- **用户看到的结果**：对应单元格空；可手工补填。

### 1.11 地址/日期格式错误
- **异常描述**：送仓日期无法解析，或地址超长。
- **系统行为**：日期统一按 `Asia/Shanghai` 解析；失败则 `F_Expected_DeliveryDateB/E=null`；地址截断至 500 字符并 `warn`。
- **是否允许降级**：是。
- **是否触发告警**：日期失败 `warn` `parse.bad_date`。
- **用户看到的结果**：日期空或截断提示；确认页可改。

---

## 2. 用户行为与并发控制

### 2.1 确认页重复点击提交
- **异常描述**：用户连点「确认导入」。
- **系统行为**：前端按钮立即 `disabled` + loading；请求带 `Idempotency-Key=mail_id:container_no:shipments_hash`；后端对 `mail_message` 执行 `UPDATE ... SET status='IMPORTING' WHERE id=? AND status='PENDING_CONFIRM'`，影响行=0 则返回 `409 ALREADY_IMPORTING`。
- **是否允许降级**：第二次请求直接返回当前状态，不二次调 CC。
- **是否触发告警**：`info` `import.duplicate_click`。
- **用户看到的结果**：首次进入「导入中」；再次点击 Toast「正在导入，请勿重复提交」。

### 2.2 快速连续提交（并发）
- **异常描述**：两次请求几乎同时到达。
- **系统行为**：DB 行锁/条件更新串行化；仅赢家进入 CC 调用；输家 409。
- **是否允许降级**：否（严格单飞）。
- **是否触发告警**：`warn` 若 1 分钟内同 mail 409>3 → `import.contention`。
- **用户看到的结果**：同 2.1。

### 2.3 页面刷新导致状态丢失或重复请求
- **异常描述**：提交后刷新，前端本地 state 清空。
- **系统行为**：一切以 DB `status` 为准；刷新后拉取详情，若 `IMPORTING/SUCCESS/FAILED` 展示对应 UI；不自动重放未完成请求（除非用户点重试）。
- **是否允许降级**：是（只读恢复）。
- **是否触发告警**：否。
- **用户看到的结果**：看到真实状态角标；IMPORTING 显示进度/等待。

### 2.4 浏览器回退/前进
- **异常描述**：确认页回退到详情再前进。
- **系统行为**：确认页 `beforeunload` 不拦截只读浏览；若 status 已非 `PENDING_CONFIRM`，确认页挂载时重定向详情并禁用提交。
- **是否允许降级**：是。
- **是否触发告警**：否。
- **用户看到的结果**：「当前状态不可导入：{status}」。

### 2.5 多标签页同时操作同一邮件
- **异常描述**：两标签同时改字段或提交。
- **系统行为**：提交用乐观锁 `mail_message.updated_at` 或 `version` 字段；冲突返回 `409 VERSION_CONFLICT`；改类型接口同锁。
- **是否允许降级**：后写失败，需刷新。
- **是否触发告警**：`warn` `mail.version_conflict`。
- **用户看到的结果**：「数据已被其他页面更新，请刷新后重试」。

### 2.6 Admin 改类型误操作
- **异常描述**：误将 LABEL 改为 NEW 并准备导入。
- **系统行为**：改类型二次确认弹窗展示旧→新 + 证据分；写入 `audit_log`；支持「改回」若尚未 `IMPORTING`；已 SUCCESS 禁止改类型。
- **是否允许降级**：人工改回。
- **是否触发告警**：每次改类型 `info` 审计；1 小时同用户改类型>10 → `warn`。
- **用户看到的结果**：弹窗确认；一期无审计页。

---

## 3. 网络与通信容错

### 3.1 IMAP 连接断开/超时
- **异常描述**：connect>30s 或 read>60s，或 TLS 中断。
- **系统行为**：本次轮询 abort；释放 `GET_LOCK('imap_poll')`；下个 `POLL_INTERVAL` 重试；已 `FETCHED` 的邮件不受影响。
- **是否允许降级**：retry（无限轮询，指数退避上限 5min 仅当连续失败≥5）。
- **是否触发告警**：连续失败≥3 → `error` 监控 `imap.poll_fail`；列表顶栏红条「邮件同步异常」。
- **用户看到的结果**：已有邮件仍可操作；新邮件暂不出现。

### 3.2 前端调 CC 超时/断开
- **异常描述**：Web→自有 API 或自有 API→CC 超过 `CC_HTTP_TIMEOUT`。
- **系统行为**：若请求已发出且本地未收到响应：柜状态先标 `FAILED` 或入 `import_compensation`（`reason=TIMEOUT_UNKNOWN`）；**禁止立即自动重放 SaveContainer**（防双写）；需 `GetContainerList` 确认柜是否已存在后再决定重试或标 SUCCESS。
- **是否允许降级**：补偿队列 + 人工确认重试。
- **是否触发告警**：`error` `cc.timeout`。
- **用户看到的结果**：「导入结果不确定，已加入待核查队列」；日志页显示「超时待核对」。

### 3.3 请求已发送但响应丢失（部分成功不确定）
- **异常描述**：CC 可能已建柜，客户端读超时。
- **系统行为**：同 3.2；核对流程：用柜号查 `GetContainerList`；命中近 10 分钟新建 → 回写 `external_id` 并 `SUCCESS`；未命中 → 允许补偿重试。
- **是否允许降级**：核查后自动收敛。
- **是否触发告警**：`error` `cc.ambiguous_success`。
- **用户看到的结果**：状态「待核查」直到收敛。

### 3.4 弱网重试导致重复请求
- **异常描述**：浏览器/代理自动重试 POST。
- **系统行为**：依赖 `Idempotency-Key` + 条件更新 `PENDING_CONFIRM→IMPORTING`；CC 侧再经 §5.8 冲突检测。
- **是否允许降级**：幂等吞掉重复。
- **是否触发告警**：`info`。
- **用户看到的结果**：单次成功结果。

### 3.5 CDN/静态资源加载失败
- **异常描述**：JS/CSS chunk 404。
- **系统行为**：Next error boundary 展示「资源加载失败，请强刷」；不影响已运行的 worker/IMAP。
- **是否允许降级**：用户手动刷新。
- **是否触发告警**：前端上报 `warn` `ui.chunk_fail`（若有）。
- **用户看到的结果**：整页错误壳，非静默白屏。

---

## 4. 后端 API（CarrierCentral）容错策略

### 4.1 customerLogin 返回 410 或 5xx
- **异常描述**：登录失败或 token 接口异常。
- **系统行为**：清 `cc_token_cache` + 进程内存 token；5xx 退避重试登录最多 2 次；仍失败则导入整体 `FAILED`，`last_error=CC_LOGIN_FAILED`。
- **是否允许降级**：否（无法调用业务 API）。
- **是否触发告警**：`error` `cc.login_fail`。
- **用户看到的结果**：§5.10「登录失效/CC 异常」文案；运营检查 `CC_USERNAME`。

### 4.2 SaveContainer 业务调用中途 410
- **异常描述**：token 过期发生在 SaveContainer。
- **系统行为**：重登 1 次并**重放同一 Idempotency 载荷 1 次**（`CC_REPLAY_ON_410=1`）；仍 410 → FAILED。
- **是否允许降级**：单次重放。
- **是否触发告警**：重放成功 `info`；失败 `error`。
- **用户看到的结果**：成功则无感；失败见 §5.10。

### 4.3 SaveContainer 返回 400（含柜号已存在）
- **异常描述**：CC 业务校验失败。
- **系统行为**：该柜 `container_import.status=FAILED`；`last_error=info`；**不自动重试**（业务错误）；邮件多柜则其他柜继续 → 可能 `PARTIAL_SUCCESS`。
- **是否允许降级**：人工改数据后重新确认（若邮件回到可编辑：从 FAILED 允许「重新打开确认」仅当无任何 SUCCESS 柜；已有 SUCCESS 柜则仅补偿失败柜）。
- **是否触发告警**：`warn` `cc.save_400`。
- **用户看到的结果**：「业务校验失败：{info}」。

### 4.4 GetContainerList 超时或数据不全
- **异常描述**：冲突检测调用失败。
- **系统行为**：**默认阻断导入**（`CONFLICT_CHECK_FAILED`），不盲调 SaveContainer；运营可 Admin 强制跳过冲突检测（需 `ENABLE_FORCE_IMPORT=true`）。
- **是否允许降级**：仅 Admin 强制。
- **是否触发告警**：`error` `cc.list_timeout`。
- **用户看到的结果**：「无法校验柜号是否已存在，请稍后重试」。

### 4.5 响应结构变化（字段新增/删除）
- **异常描述**：`data` 非预期类型或缺柜 id。
- **系统行为**：`code=200` 但无法解析 `external_id` → 走 3.2 不确定流程（列表核对）；解析层用宽松 schema（忽略未知字段）。
- **是否允许降级**：核对收敛。
- **是否触发告警**：`error` `cc.schema_drift`。
- **用户看到的结果**：「返回异常，已待核查」。

### 4.6 相同 loginMark「重复提交」语义
- **异常描述**：CC 侧会话与多次 SaveContainer。
- **系统行为**：本系统不轮换 loginMark（进程级固定）；重复保护完全靠本库幂等 + 冲突检测，不依赖 CC 对 loginMark 去重。
- **是否允许降级**：本库幂等。
- **是否触发告警**：否。
- **用户看到的结果**：无重复柜（冲突则阻断）。

---

## 5. 邮件解析与附件处理容错（重点）

### 5.1 IMAP 拉取成功但无法解析原始内容
- **异常描述**：损坏 MIME / 编码异常。
- **系统行为**：原始字节仍写入 `snapshot_path`；`PARSE_FAILED`，`last_error=MIME_PARSE_ERROR`；已 `\Seen`。
- **是否允许降级**：人工下载快照；「重新解析」可重试。
- **是否触发告警**：`error` `parse.mime_error`。
- **用户看到的结果**：解析失败页 + 下载原始邮件。

### 5.2 zip 解压失败或嵌套多层
- **异常描述**：损坏 zip，或有效 xlsx 在二层目录。
- **系统行为**：仅解压**一层**；失败 → `PARSE_FAILED` `ZIP_EXTRACT_FAILED`；一层内递归目录找 xlsx/csv；超过一层嵌套 zip **不进入**，记 `warn` `zip.nested_ignored`。
- **是否允许降级**：否（需客户重发扁平附件）。
- **是否触发告警**：失败 `error`；嵌套忽略 `warn`。
- **用户看到的结果**：对应错误文案。

### 5.3 多 sheet 找不到「卡派」
- **异常描述**：无名称含「卡派」的 sheet。
- **系统行为**：回退第一 sheet；若第一 sheet 表头映射失败再 `PARSE_FAILED`。
- **是否允许降级**：fallback 第一 sheet。
- **是否触发告警**：`info` `parse.sheet_fallback`。
- **用户看到的结果**：详情显示「使用 Sheet：{name}」。

### 5.4 表头别名匹配失败
- **异常描述**：列名与映射表无一命中必填语义。
- **系统行为**：同 1.5 → `PARSE_FAILED` + `missing_columns`。
- **是否允许降级**：否。
- **是否触发告警**：`error`。
- **用户看到的结果**：缺失列列表。

### 5.5 货件行数过大（>1000 / >5000）
- **异常描述**：解析行数超过软/硬限制。
- **系统行为**：`>SHIPMENT_ROW_HARD_LIMIT(5000)` → `REJECTED_VALIDATION` 不落全量 JSON；`>SOFT(1000)` 且 ≤HARD → 落库，确认页强制虚拟滚动，默认**不**全选，需用户筛选后勾选，底栏警告。
- **是否允许降级**：软限制降级；硬限制拒绝。
- **是否触发告警**：软 `warn`；硬 `error` `parse.row_limit`。
- **用户看到的结果**：硬限「行数过多请拆分」；软限「行数较多，请筛选后勾选导入」。

### 5.6 柜号提取错误
- **异常描述**：正文柜号与附件柜号不一致，或正则误匹配。
- **系统行为**：附件柜号优先（§ 结构化优先）；冲突写入 `lineage` `CONTAINER_NO_CONFLICT`；确认页大红警告，**默认阻断提交**直至人工选定柜号（下拉：附件值/正文值/手输）。
- **是否允许降级**：人工选定。
- **是否触发告警**：`warn` `parse.container_conflict`。
- **用户看到的结果**：必须选择柜号后才能确认。

### 5.7 类型判定信号冲突
- **异常描述**：多类型得分接近或同分。
- **系统行为**：严格按 §4.2 同分优先级执行；`type_evidence` 完整落库；UI 展示各类型得分。
- **是否允许降级**：Admin 改类型。
- **是否触发告警**：得分差≤5 → `info` `type.close_call`。
- **用户看到的结果**：证据面板；非 NEW 导入按钮禁用原因含「当前类型=…」。

### 5.8 重新解析
- **异常描述**：用户/系统对 `PARSE_FAILED`/`REJECTED_VALIDATION`/`PARSED` 点重新解析。
- **系统行为**：仅当 status∉{IMPORTING,SUCCESS,PARTIAL_SUCCESS}；置 `PARSING`；覆盖 `parse_result`；写审计。
- **是否允许降级**：是。
- **是否触发告警**：`info`。
- **用户看到的结果**：解析中 → 新结果。

---

## 6. 状态机与生命周期保护

### 6.1 落库成功但标 `\Seen` 失败
- **异常描述**：DB 已有 `FETCHED`，IMAP STORE 失败。
- **系统行为**：邮件保持可解析；下次 lookback 再次命中 UID → 幂等键命中则**跳过新建**，仅重试 `\Seen`；不重复解析除非强制。
- **是否允许降级**：retry Seen。
- **是否触发告警**：连续 Seen 失败 `warn` `imap.seen_fail`。
- **用户看到的结果**：列表仍一条；无重复卡片。

### 6.2 进程崩溃卡在 `PARSING`
- **异常描述**：worker 死于解析中。
- **系统行为**：定时任务（每 1min）：`status=PARSING AND updated_at < now-PARSING_STALE` → 目标重置为 `FETCHED` 再入队；现行可先置 `PARSE_FAILED` 后「重新解析」（待收敛）。一期不写 audit_log。
- **是否允许降级**：自动恢复。
- **是否触发告警**：`error` `state.stale_parsing`。
- **用户看到的结果**：短暂后恢复为已解析或失败态。

### 6.3 `IMPORTING` 超时未更新
- **异常描述**：超过 `IMPORTING_TIMEOUT=180s`。
- **系统行为**：回收任务将状态改为 `FAILED` 或 `TIMEOUT_UNKNOWN` 入补偿；触发 3.2 核对；禁止无限 IMPORTING。
- **是否允许降级**：补偿+核对。
- **是否触发告警**：`error` `state.importing_timeout`。
- **用户看到的结果**：「导入超时，请至日志核查/重试」。

### 6.4 解析与 Admin 改类型并发
- **异常描述**：PARSING 中同时改类型。
- **系统行为**：改类型 API 拒绝非终态解析中：`409 MAIL_BUSY`；解析结束后以解析器写的 `mail_type` 为准，Admin 需再改。
- **是否允许降级**：否。
- **是否触发告警**：`info`。
- **用户看到的结果**：「邮件正在解析，请稍后再改类型」。

### 6.5 补偿队列丢记录或超最大重试
- **异常描述**：`retry_count >= COMPENSATION_MAX_RETRY(3)` 或行被误删。
- **系统行为**：超限标 `COMPENSATION_EXHAUSTED`，停止自动重试；监控告警；运营手工重试重置 `retry_count`（Admin）。
- **是否允许降级**：人工介入。
- **是否触发告警**：`error` `compensation.exhausted`。
- **用户看到的结果**：日志「重试已耗尽，请联系值班」；SOP §12。

### 6.6 非法状态迁移
- **异常描述**：客户端伪造 status 回写。
- **系统行为**：所有迁移仅服务端按 §6.3 表执行；无通用 status PATCH。
- **是否允许降级**：否。
- **是否触发告警**：`warn` `state.illegal_transition`。
- **用户看到的结果**：400。

---

## 7. 缓存一致性与幂等设计

### 7.1 DB token 过期但内存仍有效
- **异常描述**：`cc_token_cache.expire_at` 已过，进程内存未清。
- **系统行为**：每次用 token 前比较 DB `expire_at`；以 **DB 为权威**；过期强制重登；内存跟随失效。
- **是否允许降级**：重登。
- **是否触发告警**：`info` `cc.token_refresh`。
- **用户看到的结果**：无感或一次短暂延迟。

### 7.2 多实例 token 刷新未同步
- **异常描述**：实例 A 重登写入 DB，实例 B 仍持旧 token。
- **系统行为**：B 收到 410 → 读 DB 最新 token；若仍 410 → 抢锁重登（`GET_LOCK('cc_login')`）写 DB。
- **是否允许降级**：410 重放路径。
- **是否触发告警**：`warn` 频繁 410 `cc.token_churn`。
- **用户看到的结果**：同 §5.10。

### 7.3 raw_hash 碰撞
- **异常描述**：不同邮件 hash 相同（极低概率）。
- **系统行为**：幂等顺序：Message-ID → folder+uid → raw_hash；hash 命中时若 Message-ID 不同则**不合并**，改用 folder+uid 新建并 `error` `idempotency.hash_collision`。
- **是否允许降级**：分叉新建。
- **是否触发告警**：`error`（必告警）。
- **用户看到的结果**：两条独立邮件记录。

### 7.4 同一 Message-ID 被多次处理
- **异常描述**：重复投递/重复拉取。
- **系统行为**：`UNIQUE(message_id)` 插入失败 → 吞掉；若需更新 `\Seen` 则只做 IMAP。
- **是否允许降级**：幂等跳过。
- **是否触发告警**：`info` `idempotency.msgid_dup`。
- **用户看到的结果**：仍一条。

---

## 8. 并发一致性与锁策略

### 8.1 多 worker 锁竞争失败
- **异常描述**：`GET_LOCK('imap_poll', 0)` 返回 0。
- **系统行为**：本轮直接退出，等待下轮；不报错为故障。
- **是否允许降级**：是（正常互斥）。
- **是否触发告警**：连续 30 轮拿不到锁且无其他实例心跳 → `error` `imap.lock_stuck`（锁持有方崩溃未释放极罕见，MySQL 连接断即释放）。
- **用户看到的结果**：无。

### 8.2 同一柜号多封邮件同时确认
- **异常描述**：两封 PENDING 邮件含同柜，两运营同时提交。
- **系统行为**：提交事务内：`SELECT ... FOR UPDATE` 锁 `container_import` 占位行 `UNIQUE(container_no) WHERE status IN ('IMPORTING','SUCCESS')` 或等价唯一活跃索引；第二人冲突检测失败阻断；第一人 CC 成功后第二人必拦。
- **是否允许降级**：后提交失败。
- **是否触发告警**：`warn` `conflict.cross_mail_container`。
- **用户看到的结果**：「柜号已被邮件#{id}占用/已存在」。

### 8.3 多 Admin 同时改类型并提交
- **异常描述**：改类型+导入竞态。
- **系统行为**：`version` 乐观锁；导入前再次校验 `mail_type=NEW_CONTAINER`；类型已变则 409。
- **是否允许降级**：刷新重来。
- **是否触发告警**：`warn`。
- **用户看到的结果**：版本冲突提示。

### 8.4 补偿队列同一柜重复重试
- **异常描述**：调度器重复投递补偿任务。
- **系统行为**：补偿执行前锁 `container_import`；已 SUCCESS 跳过；`IMPORTING` 跳过；用 `retry_token` 幂等。
- **是否允许降级**：跳过。
- **是否触发告警**：`info`。
- **用户看到的结果**：单次结果。

---

## 9. 数据计算安全

### 9.1 CHANNEL_UNMAPPED 未阻断
- **异常描述**：未知渠道仍提交（见 1.9）。
- **系统行为**：确认页强制展示警告计数；提交 API 若存在 UNMAPPED 且未传 `ack_unmapped_channels=true` → 400 要求确认。
- **是否允许降级**：用户显式确认后放行。
- **是否触发告警**：`warn`。
- **用户看到的结果**：二次确认「存在未映射渠道，仍要提交？」。

### 9.2 浮点精度（体积/重量）
- **异常描述**：Excel 浮点噪声。
- **系统行为**：CBM/Weight 存 DECIMAL(18,4)；展示与提交前 `round(value,4)`；不在服务端做单位换算乘法链。
- **是否允许降级**：四舍五入。
- **是否触发告警**：否。
- **用户看到的结果**：最多 4 位小数。

### 9.3 日期时区错误
- **异常描述**：解析为 UTC 导致差一天。
- **系统行为**：所有业务日期按 `Asia/Shanghai` 日历日；写入 CC 格式 `YYYY-MM-DD`；`received_at` 存 UTC 瞬时并 UI 转上海。
- **是否允许降级**：固定时区。
- **是否触发告警**：跨日边界单测覆盖；运行时否。
- **用户看到的结果**：与邮件 ETA 日历日一致。

### 9.4 F_ShippingLineId 匹配失败
- **异常描述**：船名无法匹配。
- **系统行为**：留空；确认页可选船司；**不阻断**提交（字段非 SaveContainer 必填）。
- **是否允许降级**：是。
- **是否触发告警**：`info`。
- **用户看到的结果**：「未匹配船司，可手动选择」。

### 9.5 勾选总数与提交数不一致
- **异常描述**：前端展示 n，实际 payload m。
- **系统行为**：服务端以请求体 `shipment_ids[]` 为准再查 `parse_result`；过滤非 VALID/非本 mail；响应回传 `accepted_count`；与前端 n 不符则 UI 以服务端为准刷新。
- **是否允许降级**：服务端权威。
- **是否触发告警**：不一致 `warn` `import.count_mismatch`。
- **用户看到的结果**：Toast「实际提交 {accepted_count} 行」。

---

## 10. 权限与安全控制

### 10.1 未登录访问 API
- **异常描述**：无 session 调 `/api/mails`、`/api/import`。
- **系统行为**：统一 401；不返回业务数据。
- **是否允许降级**：否。
- **是否触发告警**：暴力 401 计数 `security.unauthorized`。
- **用户看到的结果**：跳转登录。

### 10.2 越权查看（一期单租户）
- **异常描述**：伪造 mail_id 扫库。
- **系统行为**：一期单租户：登录即可访问全部邮件；禁止未登录；二期按 `sender_customer_map`/客户隔离时校验 `customer_code`。
- **是否允许降级**：一期 N/A。
- **是否触发告警**：否（一期）。
- **用户看到的结果**：正常列表（仅登录用户）。

### 10.3 Admin 改类型未授权
- **异常描述**：`ENABLE_TYPE_OVERRIDE=false` 但前端暴露按钮；或普通用户调 API。
- **系统行为**：**服务端**校验 `role=admin AND ENABLE_TYPE_OVERRIDE`；失败 403；前端按同条件隐藏（不可作唯一防线）。
- **是否允许降级**：否。
- **是否触发告警**：`warn` `security.type_override_denied`。
- **用户看到的结果**：无按钮或 403。

### 10.4 伪造 loginMark / CC token
- **异常描述**：客户端上传假 token 想直打 CC。
- **系统行为**：浏览器**永不**持有 CC token；仅服务端 Adapter 使用；用户会话与 CC 凭证隔离。
- **是否允许降级**：否。
- **是否触发告警**：出现客户端传 cc_token 字段 → `error` `security.cc_token_probe`。
- **用户看到的结果**：忽略非法字段。

### 10.5 批量刷导入接口
- **异常描述**：脚本对多邮件狂打确认。
- **系统行为**：用户级限流：确认导入 **10 次/分钟**；同 mail 条件更新防重；超限 429。
- **是否允许降级**：限流。
- **是否触发告警**：`warn` `security.rate_limit_import`。
- **用户看到的结果**：「操作过于频繁」。

### 10.6 审计（一期不做）
- **现行口径**：不建 `audit_log`、无 Admin 审计页；关键操作依赖应用日志与 `/logs`。
- **系统行为**：原写审计点可空实现，不阻断主流程。
- **是否允许降级**：是（已降级为不做）。
- **用户看到的结果**：无审计查询入口。


## 11. 监控指标与告警阈值（落地用）

| 指标 | 级别 | 阈值 |
|---|---|---|
| `imap.poll_fail` 连续 | error | ≥3 轮 |
| `cc.login_fail` | error | ≥1/5min |
| `cc.ambiguous_success` | error | ≥1 |
| `state.stale_parsing` | error | ≥1 |
| `state.importing_timeout` | error | ≥1 |
| `compensation.exhausted` | error | ≥1 |
| `idempotency.hash_collision` | error | ≥1 |
| `parse.high_invalid_ratio` | warn | 单邮件 INVALID>30% |
| `import.contention` | warn | 同 mail 409>3/min |
| `security.rate_limit_import` | warn | 触发即记 |

一期告警出口：应用日志 + 管理页顶栏；企微后置。

---

## 12. QA 异常用例索引（按本章）

| 编号 | 对应用例要点 |
|---|---|
| A-1.x | 无主题/无正文/无附件/坏格式/缺列/坏柜号/半空行/20MB+/未映射渠道/坏数字日期 |
| A-2.x | 双击提交、双标签 version、刷新恢复、回退、误改类型 |
| A-3.x | IMAP 断网、CC 超时、模糊成功核对 |
| A-4.x | login 5xx、Save 400、List 超时阻断、410 重放 |
| A-5.x | 坏 MIME、坏 zip、sheet 回退、1001 行软限、柜号冲突、重新解析 |
| A-6.x | Seen 失败去重、卡 PARSING 回收、IMPORTING 超时 |
| A-7.x | token DB 权威、Message-ID 重复 |
| A-8.x | 双 worker 锁、双邮件同柜 |
| A-9.x | unmapped 需 ack、时区、accepted_count |
| A-10.x | 401/403 改类型、429 限流、无 CC token 出前端 |

### 12.1 自动化覆盖（2026-08-12）

跑法：`pnpm test`（单测/集成）+ `pnpm test:e2e tests/e2e/resilience-auth.spec.ts`（需本机可起 web）。

| 编号 | 覆盖 | 自动化入口 | 真人/联调仍需 |
|---|---|---|---|
| A-1.1 空主题 | ✅ | `resilience-scenarios` + `resilience-metrics` | UI 列表展示「(无主题)」 |
| A-1.2/1.3 无正文无附件 / NEW 无清单 | ✅ | `resolveNoSpreadsheetOutcome` | 详情文案 |
| A-1.4 非表格附件 | ✅ | 同上 | 重新解析按钮 |
| A-1.5 缺列 | ✅ | packing-list | — |
| A-1.6 坏柜号 ISO | ✅ | iso6346 + scenarios | Admin 改柜号再校验 |
| A-1.7 半空行 INVALID | ✅ | packing-list scenarios | 确认页灰显 |
| A-1.8 >20MB | ⚠️ 规则在 pipeline | 未造 20MB fixture | 真附件拒收 + `\Seen` |
| A-1.9 未映射渠道 | ✅ | channel-map + packing-list | 确认页黄标 + ack |
| A-1.10 体积重量单位 | ✅ | packing-list | — |
| A-1.11 日期/地址截断 | ✅ | dates + packing-list | — |
| A-2.1/2.2 连点/并发 | ✅ 门禁+409 码 | forecast-gate + ConfirmImportError | 真双击/双请求打 DB CAS |
| A-2.3 刷新恢复 | ⚠️ | 无独立 E2E | 导入中刷新看 DB 状态 |
| A-2.4 回退确认页 | ⚠️ | 无独立 E2E | 浏览器前进后退 |
| A-2.5 version 冲突 | ✅ 错误码 | ConfirmImportError | 双标签真打 |
| A-2.6 误改类型 | ⚠️ API 有 MAIL_BUSY | type/route | Admin 二次确认弹窗 |
| A-3.1 IMAP 超时退避 | ✅ 阈值/退避公式 | runtime-status | 真断网轮询 |
| A-3.2/3.3 模糊成功窗口 | ✅ 10min 窗口 | compensation.isRecentlyCreated | live GetContainerList |
| A-3.4 弱网重试 | ⚠️ 依赖幂等键 | import CAS | 代理重放 POST |
| A-3.5 chunk 404 | ❌ | 无 | 强刷 error boundary |
| A-4.1 login token 解析 | ✅ extractLoginToken | auth.ts | live 5xx/410 |
| A-4.2 Save 410 重放 1 次 | ⚠️ http.ts 有 retried410 | 无单测打真实 410 | live token 过期 |
| A-4.3 Save 400 | ⚠️ mock 冲突 | cc-save + force-import | live 业务 400 文案 |
| A-4.4 List 超时阻断 | ⚠️ 代码默认阻断 | force-import | live timeout |
| A-4.5 schema drift | ✅ token/id 宽松解析 | extractLoginToken | 缺 F_Id → TIMEOUT_UNKNOWN |
| A-5.1 坏 MIME | ⚠️ pipeline MIME_PARSE_ERROR | 无坏 eml fixture | 重新解析+下载快照 |
| A-5.2 zip 一层/嵌套/穿越 | ✅ | zip-extract | — |
| A-5.3 sheet 回退 | ✅ | packing-list sheetFallback | — |
| A-5.4 表头失败 | ✅ 同 1.5 | — | — |
| A-5.5 软/硬行数 | ✅ hardLimit/softLimit | packing-list | 确认页虚拟滚动 UI |
| A-5.6 柜号冲突 | ⚠️ 规则有 | pipeline lineage | 确认页必须选定柜号 |
| A-5.7 类型 close call | ⚠️ classify 有样例 | classify.test | 证据面板 |
| A-5.8 重新解析门禁 | ✅ 状态机 | state-machine | 点按钮 |
| A-6.1 Seen 失败去重 | ❌ 需 IMAP | — | lookback 重试 Seen |
| A-6.2 卡 PARSING 回收 | ✅ 允许 PARSING→FETCHED | state-machine | worker reaper 真跑 |
| A-6.3 IMPORTING 超时 | ✅ 允许 IMPORTING→FAILED | state-machine | reaper + 补偿行 |
| A-6.4 解析中改类型 | ⚠️ API MAIL_BUSY | type/route | 并发点改类型 |
| A-6.5 补偿耗尽 | ⚠️ 代码有 EXHAUSTED | compensation | Admin 手工重置 |
| A-6.6 非法迁移 | ✅ | state-machine | — |
| A-7.1/7.2 token DB 权威 | ⚠️ 实现有 | 无多实例测 | 双 web 410 |
| A-7.3 hash 碰撞分叉 | ✅ | hash + resilience-metrics | — |
| A-7.4 Message-ID 重复/截断 | ✅ truncate 191 | snapshot | UNIQUE 插入失败 |
| A-8.1 双 worker 锁 | ❌ 需双进程+MySQL | db-lock | 双 worker lock_busy |
| A-8.2 双邮件同柜 | ⚠️ conflict mock | cc-save | 两运营同时确认 |
| A-8.3 改类型+导入竞态 | ⚠️ version | ConfirmImportError | — |
| A-8.4 补偿重复投递 | ⚠️ retry_token | compensation | worker 双 tick |
| A-9.1 unmapped ack | ✅ 错误码 + warning | ConfirmImportError | 确认页二次确认 |
| A-9.2 round4 | ✅ | dates | — |
| A-9.3 时区 | ✅ | hash-dates | — |
| A-9.4 船司匹配失败不阻断 | ⚠️ extract-header | extract-header.test | 确认页手选 |
| A-9.5 accepted_count/hash | ✅ shipments_hash | hash | Toast |
| A-10.1 未登录 401 | ✅ E2E | resilience-auth.spec | — |
| A-10.2 单租户 | N/A 一期 | — | — |
| A-10.3 改类型 403 | ⚠️ requireAdmin + ENABLE_TYPE_OVERRIDE | type/route | ops 调 API |
| A-10.4 前端无 CC token | ⚠️ 架构约束 | 无扫 bundle | Network 面板 |
| A-10.5 导入/登录限流 | ✅ 单测 + E2E 登录 429 | rate-limit + e2e | 多副本无效 |
| A-10.6 审计一期不做 | N/A | — | — |

**图例**：✅ 自动化已断言 · ⚠️ 代码有路径、缺完整 fixture/联调 · ❌ 尚未自动化（需 IMAP/双进程/真人 UI）