cmroubao/docs/tasks/T-232.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-232	记录 ERP 货运导入预检的安全诊断日志	2	T-231	DONE	2026-07-29	5ed27af	null	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 构建均通过。