docs(t233): plan ERP diagnostics

docs/current-state.md

@@ -5,7 +5,7 @@
 ## 当前快照
 
 - 日期：2026-07-29
-- 阶段：T-232 已记录 ERP/OCR 导入预检的安全诊断日志
+- 阶段：T-233 计划修复 ERP 预检错误映射并增加受控诊断日志
 - Git：当前分支为 `main`；T-001 至 T-004、T-101 至 T-104、T-201 至 T-219
   均按文档提交、实现提交的顺序纳入历史
 - 生产代码：`android-buyer/` 已接入 Roubao Android 源码
@@ -204,9 +204,10 @@
 - 已完成：另含 T-220 至 T-231 ERP 契约、货运存储、采购需求生成、日期增量同步、Go
   直连协议、OCR 会话预检、稳定预检错误、直连 `FreightSource`、旧 Connector 清理和受控本地
   凭证加载。
-- 进行中：无。
-- 下一步：重启 API 后以受控单号导入一次，读取终端的货运预检稳定 code；再确认开放 API、
-  OCR/ERP 数据使用权限并完成不记录订单内容的 smoke。
+- 进行中：T-233 修复将 ERP 预检错误降级为通用 `503` 的 Web adapter 映射，并增加默认关闭的
+  ERP 脱敏诊断日志。
+- 下一步：启用受控诊断日志后以受控单号导入一次，读取 ERP 请求/响应摘要和货运预检 code；
+  再确认开放 API、OCR/ERP 数据使用权限并完成不记录订单内容的 smoke。
 
 ## 当前可运行内容
 

docs/tasks/T-233.md

@@ -0,0 +1,61 @@
+---
+id: T-233
+title: 修复 ERP 预检错误映射并增加受控诊断日志
+phase: 2
+deps:
+  - T-232
+status: PLANNED
+created: 2026-07-29
+context_ref: b316287
+work_branch: null
+write_paths:
+  - docs/tasks/T-233.md
+  - docs/current-state.md
+  - docs/api.md
+  - 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`。
+
+## 验收要点
+
+- [ ] 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 账户响应。