1

T-232

ila edited this page 2026-08-07 16:36:47 +08:00

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-232.md · commit afc651f75a3a

---

id: T-232 title: 记录 ERP 货运导入预检的安全诊断日志 phase: 2 deps:

• T-231 status: DONE created: 2026-07-29 context_ref: 5ed27af work_branch: null write_paths:
• docs/tasks/T-232.md
• docs/current-state.md
• backend-api/cmd/api/**
• backend-api/internal/transport/webui/**

---

问题 / 背景

T-231 已将 ERP/OCR 导入预检失败映射成 Admin 页面和 JSON API 的稳定错误码，但 SSR handler 未把该错误码写入 API 进程日志。现场遇到 503 时，部署者无法从启动终端确认是 OCR 服务、ERP 连通性还是协议错误；直接记录底层 error 又可能泄露 ERP 响应、Cookie、 账号、密码或验证码。

方案

1. 为 Admin Web handler 注入可选事件记录器；API 入口把它连接到标准日志。
2. 仅在 /freight/import 的稳定预检失败分支记录固定事件名、稳定错误码和最终 HTTP 状态，例如 freight_import_preflight_failed code=ERP_UNAVAILABLE status=503。
3. 未归类的创建失败只记录固定事件名和状态，不拼接原始 error、单号、幂等键、请求头、 OCR 文本或 ERP 响应。
4. 以 handler 测试固定日志内容，验证可定位稳定失败类别且不包含伪造的敏感上游文字。

验收要点

• /freight/import 的五类稳定预检错误在 API 终端均有可搜索的 code 和 HTTP 状态。
• 页面和 JSON 响应继续只返回匿名公开提示，日志不包含单号、凭证、Cookie、验证码、 OCR 文本或 ERP 原始正文。
• 历史 NewHandler 调用保持兼容；日志记录器缺省为安全 no-op。
• go test ./...、go test -race ./...、go vet ./... 和三个 Go 入口构建通过。

边界

• 不修改 ERP/OCR 请求、重试、错误映射、数据库 schema 或采购任务流程。
• 不执行真实 ERP/OCR 请求；运行时日志由部署者在重启后的受控单号导入中观察。

执行记录

• 2026-07-29：创建任务。现场检查时本机 8080 无监听进程，无法回放先前 503；确认 T-231 的 SSR 分支会渲染稳定 code，但未向 API 终端写入任何诊断事件。
• 2026-07-29：API 入口向 Web handler 注入标准日志；五类稳定预检错误记录固定事件、code 和 status，未知失败也只记录固定事件/status。go test ./...、go test -race ./...、 go vet ./... 及 api/migrate/authctl 构建均通过。