57 lines
2.5 KiB
Markdown
57 lines
2.5 KiB
Markdown
---
|
|
id: T-231
|
|
title: 显示 ERP 货运导入预检的稳定错误
|
|
phase: 2
|
|
deps:
|
|
- T-230
|
|
status: DONE
|
|
created: 2026-07-29
|
|
context_ref: f887bc4
|
|
work_branch: null
|
|
write_paths:
|
|
- docs/tasks/T-231.md
|
|
- docs/api.md
|
|
- docs/current-state.md
|
|
- backend-api/internal/transport/webui/**
|
|
- backend-api/internal/usecase/**
|
|
- backend-api/internal/transport/httpapi/**
|
|
---
|
|
|
|
## 问题 / 背景
|
|
|
|
T-230 已让货运导入在创建同步前建立 OCR/ERP 会话，但除 `OCR_SERVICE_INVALID` 外，ERP
|
|
凭证缺失、登录拒绝、外部不可用和协议异常都会被 SSR 页面压成“同步任务创建失败”。部署者
|
|
无法区分应检查本机 OCR、ERP 账号密码还是稍后重试，同时不应暴露 ERP 原始正文或凭证。
|
|
|
|
## 方案
|
|
|
|
1. 在 `FreightService` 预检层将来源错误保持为已有稳定码：`ERP_NOT_CONFIGURED`、
|
|
`ERP_LOGIN_REJECTED`、`ERP_RESPONSE_INVALID`、`ERP_UNAVAILABLE` 和
|
|
`OCR_SERVICE_INVALID`；不把登录拒绝折叠成不可用。
|
|
2. Web adapter 将上述 code 转为专用公开错误。`/freight/import` 保留单号、日期和幂等键，
|
|
对预检失败渲染可关闭弹窗，展示稳定 code 及修复建议；不创建同步记录。
|
|
3. JSON `POST /api/v1/freight-syncs` 保持同一 code、合适 HTTP 状态和匿名 message，供非 SSR
|
|
管理调用方判断。
|
|
4. 新增 source -> usecase -> Web/API 的错误映射测试，断言错误中不含 OCR 文字、ERP 响应、
|
|
Cookie、账号或密码。
|
|
|
|
## 验收要点
|
|
|
|
- [x] OCR 无效、ERP 未配置、登录拒绝、协议异常和暂时不可用均有稳定 code；登录拒绝不再显示
|
|
泛化“同步任务创建失败”。
|
|
- [x] 导入页弹窗保留表单，并在错误发生前不创建同步记录；JSON 返回相同 code。
|
|
- [x] 错误、HTML 和 JSON 均不含凭证、验证码、Cookie 或上游响应片段。
|
|
- [x] `go test ./...`、`go test -race ./...`、`go vet ./...` 和三个 Go 入口构建通过。
|
|
|
|
## 边界
|
|
|
|
- 不重试 OCR/ERP 登录、不改变 OCR 请求、ERP 协议、SQLite schema、任务/采购流程。
|
|
- 不执行真实 ERP 或 OCR 登录测试。
|
|
|
|
## 执行记录
|
|
|
|
- 2026-07-29：创建任务。现场检查确认 `.env` 四项均已设置且后端/OCR 均监听；原 SSR 错误
|
|
分支丢弃了 ERP 预检稳定码，尚不能从页面确认上游失败类别。
|
|
- 2026-07-29：将 ERP 登录拒绝归一化为来源错误，并向 SSR/JSON 映射五类匿名稳定预检错误；
|
|
完整 Go 验证命令和结果见实现提交。
|