chengma/cmroubao
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Page: T-233
Pages
00-ai-start-here 01-vision 02-requirements 03-tech-stack 04-architecture 05-coding-rules 06-tasks 07-user-stories 08-interaction-checklist Design Home Integrations-shunyunbao-contract PPT T-001 T-002 T-003 T-004 T-101 T-102 T-103 T-104 T-201 T-202 T-203 T-204 T-205 T-206 T-207 T-208 T-209 T-210 T-211 T-212 T-213 T-214 T-215 T-216 T-217 T-218 T-219 T-220 T-221 T-222 T-223 T-224 T-225 T-226 T-227 T-228 T-229 T-230 T-231 T-232 T-233 T-234 T-235 T-236 T-237 T-238 T-239 T-240 T-241 T-242 T-243 T-244 T-245 T-246 T-247 T-248 T-249 T-250 T-251 T-252 T-253 T-254 T-255 T-256 T-257 T-258 T-259 T-260 T-261 T-262 T-263 T-264 T-265 T-266 T-267 T-268 T-269 T-270 T-271 T-272 T-273 T-274 T-275 T-276 T-277 T-278 T-279 T-280 T-281 Task-Template Tasks agent-context api clean-state-checklist current-state routes
Clone
1
T-233
ila edited this page 2026-08-07 16:36:47 +08:00
Unescape Escape
Table of Contents
This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

同步来源：docs/tasks/T-233.md · commit afc651f75a3a

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 进程开启同一开关。

验收要点

  • 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。