diff --git a/docs/current-state.md b/docs/current-state.md index 0afdaf2..28805f4 100644 --- a/docs/current-state.md +++ b/docs/current-state.md @@ -5,7 +5,7 @@ ## 当前快照 - 日期:2026-07-29 -- 阶段:T-231 已显示 ERP/OCR 导入预检的稳定错误码与修复提示 +- 阶段:T-232 计划补充 ERP/OCR 导入预检的安全诊断日志 - Git:当前分支为 `main`;T-001 至 T-004、T-101 至 T-104、T-201 至 T-219 均按文档提交、实现提交的顺序纳入历史 - 生产代码:`android-buyer/` 已接入 Roubao Android 源码 @@ -204,7 +204,8 @@ - 已完成:另含 T-220 至 T-231 ERP 契约、货运存储、采购需求生成、日期增量同步、Go 直连协议、OCR 会话预检、稳定预检错误、直连 `FreightSource`、旧 Connector 清理和受控本地 凭证加载。 -- 进行中:无。 +- 进行中:T-232 将把货运导入的稳定预检 code 和 HTTP 状态写入 API 终端;不记录 + 单号、凭证、Cookie、验证码、OCR 文本或 ERP 原文。 - 下一步:确认开放 API、OCR/ERP 数据使用权限,并以受控单号执行一次不记录订单内容的 smoke。 ## 当前可运行内容 diff --git a/docs/tasks/T-232.md b/docs/tasks/T-232.md new file mode 100644 index 0000000..e9bd4cf --- /dev/null +++ b/docs/tasks/T-232.md @@ -0,0 +1,50 @@ +--- +id: T-232 +title: 记录 ERP 货运导入预检的安全诊断日志 +phase: 2 +deps: + - T-231 +status: PLANNED +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 终端写入任何诊断事件。