From 2d8ad971677d78b2d1f16cfe2c4e1da00faf72d2 Mon Sep 17 00:00:00 2001
From: QiuSW <105186638@qq.com>
Date: Wed, 29 Jul 2026 10:52:48 +0800
Subject: [PATCH] docs(t231): plan freight preflight errors

---
 docs/current-state.md |  5 ++--
 docs/tasks/T-231.md   | 54 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 57 insertions(+), 2 deletions(-)
 create mode 100644 docs/tasks/T-231.md

diff --git a/docs/current-state.md b/docs/current-state.md
index 3b0bcec..5fdb5de 100644
--- a/docs/current-state.md
+++ b/docs/current-state.md
@@ -5,7 +5,7 @@
 ## 当前快照
 
 - 日期：2026-07-29
-- 阶段：T-230 已接入本机 OCR ERP 自动登录并移除人工 `/erp` 连接模块
+- 阶段：T-231 待显示 ERP/OCR 导入预检的稳定错误码与修复提示
 - Git：当前分支为 `main`；T-001 至 T-004、T-101 至 T-104、T-201 至 T-219
   均按文档提交、实现提交的顺序纳入历史
 - 生产代码：`android-buyer/` 已接入 Roubao Android 源码
@@ -203,7 +203,8 @@
 - 已完成：另含 T-220 至 T-230 ERP 契约、货运存储、采购需求生成、日期增量同步、Go
   直连协议、OCR 会话预检、直连 `FreightSource`、旧 Connector 清理和受控本地凭证加载。
 - 进行中：无。
-- 下一步：确认开放 API、OCR/ERP 数据使用权限，并以受控单号执行一次不记录订单内容的 smoke。
+- 下一步：T-231 先显示 ERP/OCR 导入预检稳定错误；随后确认开放 API、OCR/ERP 数据使用权限，
+  并以受控单号执行一次不记录订单内容的 smoke。
 
 ## 当前可运行内容
 
diff --git a/docs/tasks/T-231.md b/docs/tasks/T-231.md
new file mode 100644
index 0000000..67b61da
--- /dev/null
+++ b/docs/tasks/T-231.md
@@ -0,0 +1,54 @@
+---
+id: T-231
+title: 显示 ERP 货运导入预检的稳定错误
+phase: 2
+deps:
+  - T-230
+status: TODO
+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、账号或密码。
+
+## 验收要点
+
+- [ ] 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 预检稳定码，尚不能从页面确认上游失败类别。