1

T-238

ila edited this page 2026-08-07 16:36:51 +08:00

Table of Contents

• 问题 / 背景
• 方案
• 验收要点
• 边界
• 执行记录

同步来源：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。

验收要点

• 详情 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 不一致。
• 2026-07-29：严格增加空格/T 分隔的分钟 precision layout，保持 Asia/Shanghai 和 UTC 规范化语义。脱敏单元测试覆盖分钟、秒、RFC3339 和未知格式，Admin/Gin/SQLite 完整单号 集成 fixture 改用分钟精度并返回 201/SUCCEEDED。标准 Go 测试、race、vet 及三个入口 构建均通过；两份真实响应 JSON 未暂存。