---
id: T-233
title: 修复 ERP 预检错误映射并增加受控诊断日志
phase: 2
deps:
  - T-232
status: DONE
created: 2026-07-29
context_ref: b316287
work_branch: null
write_paths:
  - docs/tasks/T-233.md
  - docs/current-state.md
  - docs/api.md
  - start-backend.bat
  - backend-api/.env.example
  - backend-api/cmd/api/**
  - backend-api/internal/config/**
  - backend-api/internal/platform/shunyunbao/**
  - backend-api/internal/transport/webui/**
---

## 问题 / 背景

现场导入仍返回 `503`，终端只显示 `freight_import_failed status=503`。T-232 的日志表明
`UsecaseAdapter.CreateFreightSync` 仅专门映射 OCR 错误，其他 ERP 预检错误会在
`mapUsecaseError` 中降级为通用 `ErrUnavailable`，稳定 code 丢失。与此同时，当前 ERP
client 不记录请求路径、HTTP 状态或响应摘要，无法区分 TLS/网络、验证码 endpoint、登录
响应或用户校验响应失败。

## 方案

1. `CreateFreightSync` 对全部已有 ERP/OCR 预检 error 调用同一 `mapFreightPreflightError`，
   保持 `ERP_UNAVAILABLE` 等稳定 code 到 SSR 日志和页面。
2. 增加仅 API 进程使用的 `CMROUBAO_ERP_DEBUG_LOG`（默认 `false`，只接受 true/false）；
   开启后输出 ERP 请求 method/path、响应 status/content type/字节数及受限响应摘要。
3. 响应摘要仅对 JSON 输出经过递归字段脱敏且最长 4 KiB 的内容；密码、用户名、验证码、
   token、Cookie、收件人、电话、地址和订单标识均替换为 `[REDACTED]`。图片、非 JSON 和
   传输失败只输出类型、长度、状态或固定类别，不输出原始内容或 Go error。
4. 不记录请求 body、完整 URL query、header、Cookie、OCR 文本或密钥。启动时仅记录调试
   已启用，不输出配置值；调试结束后将 `.env` 设回 `false`。根目录
   `start-backend.bat --erp-debug` 可只对本次 API 进程开启同一开关。

## 验收要点

- [x] ERP 不可用可从 `/freight/import` 日志看到
  `freight_import_preflight_failed code=ERP_UNAVAILABLE status=503`。
- [x] 开启 `CMROUBAO_ERP_DEBUG_LOG=true` 后，验证码、登录、用户校验及后续查询均有可关联
  的脱敏请求/响应日志；默认关闭时没有这些日志。
- [x] 日志绝不含 ERP 凭证、验证码、Cookie、token、订单号、收件人、手机号、地址或原始
  非 JSON/图片 body。
- [x] 配置、脱敏、ERP client 和 Web adapter 均有测试；标准 Go 验证和入口构建通过。

## 边界

- 不输出用户要求的完整原始 ERP 数据，因为其中可能含订单和个人信息；受控脱敏摘要足以诊断
  当前登录/协议失败。
- 不改变 ERP 协议、OCR 调用、重试、同步 schema 或采购流程。

## 执行记录

- 2026-07-29：创建任务。现场终端提供 `freight_import_failed status=503`，确认稳定 code 在
  Web adapter 丢失；本机没有可重放的真实 ERP 账户响应。
- 2026-07-29：修复 CreateFreightSync 复用所有预检错误映射，增加受控 ERP 诊断 logger、
  JSON 递归脱敏和 4 KiB 限制，并提供 `start-backend.bat --erp-debug` 一次性开关。标准 Go
  测试、race、vet 和三个入口构建均通过；未请求真实 ERP。