cmroubao/docs/tasks/T-233.md

id, title, phase, deps, status, created, context_ref, work_branch, write_paths

id	title	phase	deps	status	created	context_ref	work_branch	write_paths
T-233	修复 ERP 预检错误映射并增加受控诊断日志	2	T-232	DONE	2026-07-29	b316287	null	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 进程开启同一开关。

验收要点

• ERP 不可用可从 /freight/import 日志看到 freight_import_preflight_failed code=ERP_UNAVAILABLE status=503。
• 开启 CMROUBAO_ERP_DEBUG_LOG=true 后，验证码、登录、用户校验及后续查询均有可关联 的脱敏请求/响应日志；默认关闭时没有这些日志。
• 日志绝不含 ERP 凭证、验证码、Cookie、token、订单号、收件人、手机号、地址或原始 非 JSON/图片 body。
• 配置、脱敏、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。