70 lines
3.3 KiB
Markdown
70 lines
3.3 KiB
Markdown
---
|
|
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 未暂存。
|