cmroubao/docs/tasks/T-231.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-231	显示 ERP 货运导入预检的稳定错误	2	T-230	TODO	2026-07-29	f887bc4	null	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、账号或密码。

验收要点

• OCR 无效、ERP 未配置、登录拒绝、协议异常和暂时不可用均有稳定 code；登录拒绝不再显示 泛化“同步任务创建失败”。
• 导入页弹窗保留表单，并在错误发生前不创建同步记录；JSON 返回相同 code。
• 错误、HTML 和 JSON 均不含凭证、验证码、Cookie 或上游响应片段。
• go test ./...、go test -race ./...、go vet ./... 和三个 Go 入口构建通过。

边界

• 不重试 OCR/ERP 登录、不改变 OCR 请求、ERP 协议、SQLite schema、任务/采购流程。
• 不执行真实 ERP 或 OCR 登录测试。

执行记录

• 2026-07-29：创建任务。现场检查确认 .env 四项均已设置且后端/OCR 均监听；原 SSR 错误 分支丢弃了 ERP 预检稳定码，尚不能从页面确认上游失败类别。