From 6a8d17e37618d7f742789fba50d68ed4c42e3da4 Mon Sep 17 00:00:00 2001
From: ila <ila2002@qq.com>
Date: Fri, 7 Aug 2026 16:36:47 +0800
Subject: [PATCH] docs: import wiki at afc651f75a3a

---
 T-232.-.md | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)
 create mode 100644 T-232.-.md

diff --git a/T-232.-.md b/T-232.-.md
new file mode 100644
index 0000000..aa1054c
--- /dev/null
+++ b/T-232.-.md
@@ -0,0 +1,56 @@
+<!-- docs-wiki-sync:docs/tasks/T-232.md@afc651f75a3abc2676bb13aa8a80f6aa6a25a72e -->
+> 同步来源：[`docs/tasks/T-232.md`](/chengma/mroubao/src/commit/afc651f75a3abc2676bb13aa8a80f6aa6a25a72e/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 测试固定日志内容，验证可定位稳定失败类别且不包含伪造的敏感上游文字。
+
+## 验收要点
+
+- [x] `/freight/import` 的五类稳定预检错误在 API 终端均有可搜索的 code 和 HTTP 状态。
+- [x] 页面和 JSON 响应继续只返回匿名公开提示，日志不包含单号、凭证、Cookie、验证码、
+  OCR 文本或 ERP 原始正文。
+- [x] 历史 `NewHandler` 调用保持兼容；日志记录器缺省为安全 no-op。
+- [x] `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 构建均通过。