From 707694dec4db85a2293026c413fa2b2017f3ad7b Mon Sep 17 00:00:00 2001
From: ila <ila2002@qq.com>
Date: Fri, 7 Aug 2026 16:36:51 +0800
Subject: [PATCH] docs: import wiki at afc651f75a3a

---
 T-238.-.md | 72 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 72 insertions(+)
 create mode 100644 T-238.-.md

diff --git a/T-238.-.md b/T-238.-.md
new file mode 100644
index 0000000..76e751f
--- /dev/null
+++ b/T-238.-.md
@@ -0,0 +1,72 @@
+<!-- docs-wiki-sync:docs/tasks/T-238.md@afc651f75a3abc2676bb13aa8a80f6aa6a25a72e -->
+> 同步来源：[`docs/tasks/T-238.md`](/chengma/mroubao/src/commit/afc651f75a3abc2676bb13aa8a80f6aa6a25a72e/docs/tasks/T-238.md) · commit `afc651f75a3a`
+
+---
+id: T-238
+title: 兼容顺运宝详情分钟精度时间
+phase: 2
+deps:
+  - T-237
+status: DONE
+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
+  - backend-api/internal/transport/httpapi/admin_handlers_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。
+
+## 验收要点
+
+- [x] 详情 `yyyy-MM-dd HH:mm` 可规范化并按 Asia/Shanghai 得到正确 UTC 时间。
+- [x] `yyyy-MM-ddTHH:mm` 同样可解析；既有 RFC3339 和带秒格式不回归。
+- [x] 非法日期和未知格式仍返回错误，不放宽为模糊解析。
+- [x] 完整单号同步不再因已确认的 16 位详情时间返回 `ERP_RESPONSE_INVALID`。
+- [x] 两份真实响应 JSON 保持未跟踪，不进入 Git。
+- [x] 标准 Go 测试、race、vet 和三个入口构建通过。
+
+## 边界
+
+- 不修改列表/详情 endpoint、ID 对齐、字段 allowlist、详情优先级、时区、数据库 schema 或
+  T-237 同步超时。
+- 不把时间解析改为猜测式 parser，不接受没有真实证据的日期格式。
+- 不在自动测试中访问真实 ERP。
+
+## 执行记录
+
+- 2026-07-29：创建任务。以只输出字段名、类型、长度和结构断言的方式检查两份本机响应；
+  排除 envelope、list、detail id、details、数量、SKU 回退和字段长度，定位为详情
+  `created` 分钟精度与用例层严格 layout 不一致。
+- 2026-07-29：严格增加空格/`T` 分隔的分钟 precision layout，保持 Asia/Shanghai 和 UTC
+  规范化语义。脱敏单元测试覆盖分钟、秒、RFC3339 和未知格式，Admin/Gin/SQLite 完整单号
+  集成 fixture 改用分钟精度并返回 `201/SUCCEEDED`。标准 Go 测试、race、vet 及三个入口
+  构建均通过；两份真实响应 JSON 未暂存。