2026-07-29 11:12:33 +08:00
|
|
|
|
---
|
|
|
|
|
|
id: T-233
|
|
|
|
|
|
title: 修复 ERP 预检错误映射并增加受控诊断日志
|
|
|
|
|
|
phase: 2
|
|
|
|
|
|
deps:
|
|
|
|
|
|
- T-232
|
2026-07-29 11:24:04 +08:00
|
|
|
|
status: DONE
|
2026-07-29 11:12:33 +08:00
|
|
|
|
created: 2026-07-29
|
|
|
|
|
|
context_ref: b316287
|
|
|
|
|
|
work_branch: null
|
|
|
|
|
|
write_paths:
|
|
|
|
|
|
- docs/tasks/T-233.md
|
|
|
|
|
|
- docs/current-state.md
|
|
|
|
|
|
- docs/api.md
|
2026-07-29 11:24:04 +08:00
|
|
|
|
- start-backend.bat
|
2026-07-29 11:12:33 +08:00
|
|
|
|
- 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 文本或密钥。启动时仅记录调试
|
2026-07-29 11:24:04 +08:00
|
|
|
|
已启用，不输出配置值；调试结束后将 `.env` 设回 `false`。根目录
|
|
|
|
|
|
`start-backend.bat --erp-debug` 可只对本次 API 进程开启同一开关。
|
2026-07-29 11:12:33 +08:00
|
|
|
|
|
|
|
|
|
|
## 验收要点
|
|
|
|
|
|
|
2026-07-29 11:24:04 +08:00
|
|
|
|
- [x] ERP 不可用可从 `/freight/import` 日志看到
|
2026-07-29 11:12:33 +08:00
|
|
|
|
`freight_import_preflight_failed code=ERP_UNAVAILABLE status=503`。
|
2026-07-29 11:24:04 +08:00
|
|
|
|
- [x] 开启 `CMROUBAO_ERP_DEBUG_LOG=true` 后，验证码、登录、用户校验及后续查询均有可关联
|
2026-07-29 11:12:33 +08:00
|
|
|
|
的脱敏请求/响应日志；默认关闭时没有这些日志。
|
2026-07-29 11:24:04 +08:00
|
|
|
|
- [x] 日志绝不含 ERP 凭证、验证码、Cookie、token、订单号、收件人、手机号、地址或原始
|
2026-07-29 11:12:33 +08:00
|
|
|
|
非 JSON/图片 body。
|
2026-07-29 11:24:04 +08:00
|
|
|
|
- [x] 配置、脱敏、ERP client 和 Web adapter 均有测试；标准 Go 验证和入口构建通过。
|
2026-07-29 11:12:33 +08:00
|
|
|
|
|
|
|
|
|
|
## 边界
|
|
|
|
|
|
|
|
|
|
|
|
- 不输出用户要求的完整原始 ERP 数据，因为其中可能含订单和个人信息；受控脱敏摘要足以诊断
|
|
|
|
|
|
当前登录/协议失败。
|
|
|
|
|
|
- 不改变 ERP 协议、OCR 调用、重试、同步 schema 或采购流程。
|
|
|
|
|
|
|
|
|
|
|
|
## 执行记录
|
|
|
|
|
|
|
|
|
|
|
|
- 2026-07-29：创建任务。现场终端提供 `freight_import_failed status=503`，确认稳定 code 在
|
|
|
|
|
|
Web adapter 丢失；本机没有可重放的真实 ERP 账户响应。
|
2026-07-29 11:24:04 +08:00
|
|
|
|
- 2026-07-29：修复 CreateFreightSync 复用所有预检错误映射，增加受控 ERP 诊断 logger、
|
|
|
|
|
|
JSON 递归脱敏和 4 KiB 限制，并提供 `start-backend.bat --erp-debug` 一次性开关。标准 Go
|
|
|
|
|
|
测试、race、vet 和三个入口构建均通过；未请求真实 ERP。
|
