From 15b1101941307b0b967c4321a7dd8b3db3997406 Mon Sep 17 00:00:00 2001
From: QiuSW <105186638@qq.com>
Date: Wed, 29 Jul 2026 14:18:18 +0800
Subject: [PATCH] docs(t238): plan ERP minute timestamp fix

---
 docs/current-state.md |  5 ++--
 docs/tasks/T-238.md   | 64 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 67 insertions(+), 2 deletions(-)
 create mode 100644 docs/tasks/T-238.md

diff --git a/docs/current-state.md b/docs/current-state.md
index 07f4b92..7874366 100644
--- a/docs/current-state.md
+++ b/docs/current-state.md
@@ -5,7 +5,7 @@
 ## 当前快照
 
 - 日期：2026-07-29
-- 阶段：T-237 已完成完整单号 55 秒同步导入
+- 阶段：T-238 已规划顺运宝详情分钟精度时间兼容，待实现
 - Git：当前分支为 `main`；T-001 至 T-004、T-101 至 T-104、T-201 至 T-219
   均按文档提交、实现提交的顺序纳入历史
 - 生产代码：`android-buyer/` 已接入 Roubao Android 源码
@@ -18,7 +18,8 @@
   同步记录、货运头和全部明细，canonical hash 控制 revision，Admin 已有 `/freight`、
   `/freight/import`、`/freight/{id}` 与对应 JSON API。T-237 已将完整单号改为 55 秒
   同步响应，成功后直接进入可见货运列表；超时/取消使用独立 cleanup context 写
-  `FAILED`，日期范围仍后台异步。HTTP `WriteTimeout` 为 70 秒。
+  `FAILED`，日期范围仍后台异步。HTTP `WriteTimeout` 为 70 秒。T-238 已定位真实详情
+  `created` 为分钟精度，而当前 parser 只接受带秒格式，待兼容后复测。
 - ERP Go 迁移：T-225 已用脱敏 fixture 固定 `internal/platform/shunyunbao` 的 header、
   单号/日期查询、分页、详情批量和字段 allowlist，并使货运用例依赖来源中立错误。T-226
   已增加受锁保护的 Go 内存 Cookie jar、验证码 ticket、登录和用户校验，以及 ADMIN 的
diff --git a/docs/tasks/T-238.md b/docs/tasks/T-238.md
new file mode 100644
index 0000000..6068874
--- /dev/null
+++ b/docs/tasks/T-238.md
@@ -0,0 +1,64 @@
+---
+id: T-238
+title: 兼容顺运宝详情分钟精度时间
+phase: 2
+deps:
+  - T-237
+status: PLANNED
+created: 2026-07-29
+context_ref: 8d5b88f
+work_branch: null
+write_paths:
+  - docs/tasks/T-238.md
+  - docs/api.md
+  - docs/current-state.md
+  - backend-api/internal/usecase/freight_service.go
+  - backend-api/internal/usecase/freight_service_test.go
+---
+
+## 问题 / 背景
+
+完整单号同步登录、列表和详情请求均成功后，Admin 返回
+`ERP_RESPONSE_INVALID / ERP 返回格式无法确认`。对照本机
+`query_stock_list_with_order_number.json` 和 `query_stock_detail_with_id.json` 的结构化
+字段检查确认：
+
+- 列表与详情 envelope 均为 `status=true`、`data.total=1`、`data.list` 一项。
+- 列表 stock id 与详情 id 一致且为正整数，详情有合法 `details[]`。
+- 列表 `created` 是 19 位 `yyyy-MM-dd HH:mm:ss`，详情 `created` 是 16 位
+  `yyyy-MM-dd HH:mm`。
+
+平台 normalizer 按既有合约优先选择详情 `created`；用例层 `parseERPTime` 只接受 RFC3339、
+带秒的空格格式和带秒的 `T` 格式，因此拒绝真实的分钟精度详情时间。同步将规范化错误稳定映射
+为 `ERP_RESPONSE_INVALID`。
+
+## 方案
+
+1. `parseERPTime` 增加已确认的 `2006-01-02 15:04`，并对称支持
+   `2006-01-02T15:04`；无时区值继续按 `Asia/Shanghai` 解释并转 UTC。
+2. 保持详情 `created` 优先级，不因格式差异静默改用列表时间，也不补造秒数以外的信息。
+3. 保留 RFC3339、两种带秒格式和空值行为；非法日期、额外字符及其他未知格式继续拒绝。
+4. 使用完全脱敏的构造数据覆盖详情分钟精度、`T` 分隔分钟精度、列表秒精度和非法值；不复制
+   或提交原始订单、收件人、电话、地址、商品内容及两份本机 JSON。
+
+## 验收要点
+
+- [ ] 详情 `yyyy-MM-dd HH:mm` 可规范化并按 Asia/Shanghai 得到正确 UTC 时间。
+- [ ] `yyyy-MM-ddTHH:mm` 同样可解析；既有 RFC3339 和带秒格式不回归。
+- [ ] 非法日期和未知格式仍返回错误，不放宽为模糊解析。
+- [ ] 完整单号同步不再因已确认的 16 位详情时间返回 `ERP_RESPONSE_INVALID`。
+- [ ] 两份真实响应 JSON 保持未跟踪，不进入 Git。
+- [ ] 标准 Go 测试、race、vet 和三个入口构建通过。
+
+## 边界
+
+- 不修改列表/详情 endpoint、ID 对齐、字段 allowlist、详情优先级、时区、数据库 schema 或
+  T-237 同步超时。
+- 不把时间解析改为猜测式 parser，不接受没有真实证据的日期格式。
+- 不在自动测试中访问真实 ERP。
+
+## 执行记录
+
+- 2026-07-29：创建任务。以只输出字段名、类型、长度和结构断言的方式检查两份本机响应；
+  排除 envelope、list、detail id、details、数量、SKU 回退和字段长度，定位为详情
+  `created` 分钟精度与用例层严格 layout 不一致。