Admin：增强顺运宝日期同步容量与完整性保护 #58

New Issue

2026-08-09T17:06:18+08:00

ila commented

2026-08-09 17:06:18 +08:00

基本信息

类型：缺陷
父级大工单：#14
所属 MVP / 版本：#15 Admin 四模块可用闭环
阶段：顺运宝货运单与采购任务
状态：已完成
依赖：#53 指定日期同步

要解决什么

根据本地 HAR（仅作脱敏结构分析，不提交抓包内容）核对，现有日期查询协议正确，但真实的短日期范围总量已经明显超过当前默认 max_matches=500。接口筛选粒度只有日期，单日数据也可能超过 500，“缩小日期范围”不一定可执行。

同时，现有同步存在两个可能静默漏单的完整性缺口：

listTotal 返回总数后，分页结束没有核对唯一货运单 ID 数是否等于总数；短页、空页、重复页或并发位移可能少拉数据，流程仍会推进游标。
明细批量接口没有核对返回货运单 ID 是否完整覆盖请求 ID；缺失、重复、意外 ID 或空明细会被当成成功，流程仍可能推进游标。

复现：

选择一个总量超过 500 的短日期范围。
当前实现会在第一页前直接失败；如果只提高配置，则需发起大量 offset 分页，但没有分页和明细覆盖校验。
假服务端让某一列表页少返回一条，或让明细批次少返回一个 ID。
当前实现仍可能完成并更新 last_synced_at。

做什么 / 不做什么

做：保持 t_stock.created、UTC+8、两端包含和每页 20 条的 HAR 已验证协议。
做：把一次日期范围拆成逐日同步段，降低跨多日 offset 分页受新增数据影响的范围。
做：人工指定日期最多 31 天，避免误选超长范围；自动增量不受 31 天人工输入限制。
做：把默认总量熔断上限从 500 提高到 10000；仍允许通过 max_matches 配置调整。
做：执行前逐日查询 listTotal 并汇总；总量超过熔断上限时不拉列表、不写数据、不推进游标。
做：解析并校验每次 list 响应内的 total；每天分页结束后唯一 ID 数必须等于预检总数。
做：每批明细响应必须与请求 ID 一一对应；缺失、重复、意外 ID 或零商品明细均明确失败。
做：任一日期段或完整性检查失败时不推进 last_synced_at；已写入内容保留，重试依靠 upsert。
做：同步报告按整个范围累计货运单和商品明细数量。
不做：不改日期查询字段、72 个 columns、20 条分页和 100 ID 明细批次。
不做：不改数据库结构、Client API、人工规格匹配或真实下单开关。
不做：不请求真实顺运宝接口；自动化使用 httptest，HAR 只本地读取。
不做：本工单不建设持久化断点续传和详细百分比进度。

怎么做

在 service/syb.go 增加日期范围按天展开和人工范围 31 天校验。
同步开始时对每一天调用 ListTotal，得到日分段计划和全范围总数；总数超过 max_matches 时在任何列表/明细写入前失败。
默认 max_matches 改为 10000，并同步 config.example.yaml 与接口文档。现有本地 config.yaml 的非凭据配置需要同步为 10000，但不得读取、输出或提交其中凭据。
修改 syb.Client.ListPage 返回 data.total，要求格式合法；Service 每页核对 total 不漂移，并在当日分页结束核对唯一 ID 总数。
明细批次建立请求 ID 集合，要求返回集合完全一致且每张货运单至少一个商品明细；任何不完整响应立即失败。
保持“所有日分段成功后才推进游标”；历史局部补拉仍不推进。
增加分段、跨度、总量熔断、列表短页/重复/total 漂移、明细缺失/重复/意外/空明细及游标回归测试。
使用本地 HAR 做只读结构比对，确认请求 payload 仍保持一致；不连接真实服务。

预计修改：

admin/service/syb.go
admin/service/syb_test.go
admin/syb/client.go
admin/syb/client_test.go
admin/config.example.yaml
docs/admin/05-ui-specification.md
docs/admin/08-顺运宝接口.md
必要的现有回归测试

不修改数据库结构和 Client API。

验收标准

当前 HAR 所示的创建日期请求字段、72 个 columns、20 条分页参数保持不变。
指定日期最多 31 天；32 天及以上由服务端拒绝并给出明确提示。
多日范围按单日顺序预检和拉取，报告仍汇总整个范围。
默认 max_matches 为 10000；全范围总量超限时列表和明细接口均不调用，数据库和游标不变。
单日数量超过旧上限 500、但全范围不超过新上限时可以正常分页同步。
list.data.total 缺失、格式错误、与预检不一致或分页过程中漂移时同步失败且不推进游标。
短页、空页、重复 ID 导致最终唯一 ID 数不足时同步失败且不推进游标。
明细缺失请求 ID、重复 ID、返回意外 ID或零商品明细时同步失败且不推进游标。
全部日期段完整成功后才按原规则推进游标；局部历史补拉仍不推进。
已写入数据重试时继续 upsert，不覆盖人工 shopee_sku_id。
不记录或提交 HAR 中的 Cookie、Token、个人信息和业务明细。
go vet ./...、go test ./... 及 Go 1.23.0 构建和无缓存测试通过。

怎么验证

从 admin/ 执行：

gofmt -w service/syb.go service/syb_test.go syb/client.go syb/client_test.go
go vet ./...
go test ./... -count=1
$env:GOTOOLCHAIN="go1.23.0"
go build ./...
go test ./... -count=1
Remove-Item Env:GOTOOLCHAIN

本地 HAR 只读结构比对：

请求路径和 payload 字段不变；
72 个 columns 逐项一致；
不输出 headers、Cookie、Token、收件人或完整响应。

风险和回退

风险：严格完整性校验可能暴露顺运宝接口偶发的短页或空明细，使同步从“表面成功”变成明确失败；这是为了防止静默漏单。
风险：上限提高后请求次数增加；用 31 天人工跨度、10000 总量熔断、逐日拆分、30 秒单请求超时和单实例同步互斥共同限制。
风险：真实接口是否偶发返回空明细尚未验证；如发生，先保留不推进游标的安全行为，再依据脱敏证据评估重试策略。
回退：回退本任务提交并恢复示例配置即可；无数据库迁移。

## 基本信息 - 类型：缺陷 - 父级大工单：#14 - 所属 MVP / 版本：#15 Admin 四模块可用闭环 - 阶段：顺运宝货运单与采购任务 - 状态：已完成 - 依赖：#53 指定日期同步 ## 要解决什么根据本地 HAR（仅作脱敏结构分析，不提交抓包内容）核对，现有日期查询协议正确，但真实的短日期范围总量已经明显超过当前默认 `max_matches=500`。接口筛选粒度只有日期，单日数据也可能超过 500，“缩小日期范围”不一定可执行。同时，现有同步存在两个可能静默漏单的完整性缺口： 1. `listTotal` 返回总数后，分页结束没有核对唯一货运单 ID 数是否等于总数；短页、空页、重复页或并发位移可能少拉数据，流程仍会推进游标。 2. 明细批量接口没有核对返回货运单 ID 是否完整覆盖请求 ID；缺失、重复、意外 ID 或空明细会被当成成功，流程仍可能推进游标。复现： 1. 选择一个总量超过 500 的短日期范围。 2. 当前实现会在第一页前直接失败；如果只提高配置，则需发起大量 offset 分页，但没有分页和明细覆盖校验。 3. 假服务端让某一列表页少返回一条，或让明细批次少返回一个 ID。 4. 当前实现仍可能完成并更新 `last_synced_at`。 ## 做什么 / 不做什么 - 做：保持 `t_stock.created`、UTC+8、两端包含和每页 20 条的 HAR 已验证协议。 - 做：把一次日期范围拆成逐日同步段，降低跨多日 offset 分页受新增数据影响的范围。 - 做：人工指定日期最多 31 天，避免误选超长范围；自动增量不受 31 天人工输入限制。 - 做：把默认总量熔断上限从 500 提高到 10000；仍允许通过 `max_matches` 配置调整。 - 做：执行前逐日查询 `listTotal` 并汇总；总量超过熔断上限时不拉列表、不写数据、不推进游标。 - 做：解析并校验每次 `list` 响应内的 `total`；每天分页结束后唯一 ID 数必须等于预检总数。 - 做：每批明细响应必须与请求 ID 一一对应；缺失、重复、意外 ID 或零商品明细均明确失败。 - 做：任一日期段或完整性检查失败时不推进 `last_synced_at`；已写入内容保留，重试依靠 upsert。 - 做：同步报告按整个范围累计货运单和商品明细数量。 - 不做：不改日期查询字段、72 个 columns、20 条分页和 100 ID 明细批次。 - 不做：不改数据库结构、Client API、人工规格匹配或真实下单开关。 - 不做：不请求真实顺运宝接口；自动化使用 `httptest`，HAR 只本地读取。 - 不做：本工单不建设持久化断点续传和详细百分比进度。 ## 怎么做 1. 在 `service/syb.go` 增加日期范围按天展开和人工范围 31 天校验。 2. 同步开始时对每一天调用 `ListTotal`，得到日分段计划和全范围总数；总数超过 `max_matches` 时在任何列表/明细写入前失败。 3. 默认 `max_matches` 改为 10000，并同步 `config.example.yaml` 与接口文档。现有本地 `config.yaml` 的非凭据配置需要同步为 10000，但不得读取、输出或提交其中凭据。 4. 修改 `syb.Client.ListPage` 返回 `data.total`，要求格式合法；Service 每页核对 total 不漂移，并在当日分页结束核对唯一 ID 总数。 5. 明细批次建立请求 ID 集合，要求返回集合完全一致且每张货运单至少一个商品明细；任何不完整响应立即失败。 6. 保持“所有日分段成功后才推进游标”；历史局部补拉仍不推进。 7. 增加分段、跨度、总量熔断、列表短页/重复/total 漂移、明细缺失/重复/意外/空明细及游标回归测试。 8. 使用本地 HAR 做只读结构比对，确认请求 payload 仍保持一致；不连接真实服务。预计修改： - `admin/service/syb.go` - `admin/service/syb_test.go` - `admin/syb/client.go` - `admin/syb/client_test.go` - `admin/config.example.yaml` - `docs/admin/05-ui-specification.md` - `docs/admin/08-顺运宝接口.md` - 必要的现有回归测试不修改数据库结构和 Client API。 ## 验收标准 - [x] 当前 HAR 所示的创建日期请求字段、72 个 columns、20 条分页参数保持不变。 - [x] 指定日期最多 31 天；32 天及以上由服务端拒绝并给出明确提示。 - [x] 多日范围按单日顺序预检和拉取，报告仍汇总整个范围。 - [x] 默认 `max_matches` 为 10000；全范围总量超限时列表和明细接口均不调用，数据库和游标不变。 - [x] 单日数量超过旧上限 500、但全范围不超过新上限时可以正常分页同步。 - [x] `list.data.total` 缺失、格式错误、与预检不一致或分页过程中漂移时同步失败且不推进游标。 - [x] 短页、空页、重复 ID 导致最终唯一 ID 数不足时同步失败且不推进游标。 - [x] 明细缺失请求 ID、重复 ID、返回意外 ID或零商品明细时同步失败且不推进游标。 - [x] 全部日期段完整成功后才按原规则推进游标；局部历史补拉仍不推进。 - [x] 已写入数据重试时继续 upsert，不覆盖人工 `shopee_sku_id`。 - [x] 不记录或提交 HAR 中的 Cookie、Token、个人信息和业务明细。 - [x] `go vet ./...`、`go test ./...` 及 Go 1.23.0 构建和无缓存测试通过。 ## 怎么验证从 `admin/` 执行： ```powershell gofmt -w service/syb.go service/syb_test.go syb/client.go syb/client_test.go go vet ./... go test ./... -count=1 $env:GOTOOLCHAIN="go1.23.0" go build ./... go test ./... -count=1 Remove-Item Env:GOTOOLCHAIN ``` 本地 HAR 只读结构比对： - 请求路径和 payload 字段不变； - 72 个 columns 逐项一致； - 不输出 headers、Cookie、Token、收件人或完整响应。 ## 风险和回退 - 风险：严格完整性校验可能暴露顺运宝接口偶发的短页或空明细，使同步从“表面成功”变成明确失败；这是为了防止静默漏单。 - 风险：上限提高后请求次数增加；用 31 天人工跨度、10000 总量熔断、逐日拆分、30 秒单请求超时和单实例同步互斥共同限制。 - 风险：真实接口是否偶发返回空明细尚未验证；如发生，先保留不推进游标的安全行为，再依据脱敏证据评估重试策略。 - 回退：回退本任务提交并恢复示例配置即可；无数据库迁移。

ila referenced this issue

2026-08-09 17:06:33 +08:00

[Epic] Admin 采集采购管理端 #14

ila referenced this issue

2026-08-09 17:06:34 +08:00

[MVP] Admin 四模块可用闭环 #15

ila commented

2026-08-09 17:06:35 +08:00

已开始实施。#58 已同步到父级 #14 和 MVP #15。HAR 仅在本地做脱敏结构比对，不读取或回写 headers、Cookie、Token、收件人和完整响应；现有 Client 与脚本改动保持不动。

ila commented

2026-08-09 17:19:28 +08:00

实施完成，待用户验收

已按确认方案完成，工单保持开启。

实现结果

日期范围逐日预检和拉取；人工指定范围最多 31 天，自动增量不受人工天数限制。
默认 max_matches 为 10000；超限时不会调用列表/明细接口，也不写数据库或游标。
分页核对 list.data.total 与唯一货运单 ID 数；明细批次核对请求/响应 ID 一一对应且非空。
任一日期、列表或明细不完整时停止且不推进 last_synced_at；全部成功后沿用原游标规则。
日期弹窗增加“每次最多选择 31 天”的持续提示。
本机忽略提交的 admin/config.yaml 只调整了非凭据字段 max_matches: 10000，未读取、输出或提交凭据。

验证结果

go vet ./...：通过。
Go 1.23.0：go build ./...、go test ./... -count=1：全部通过。
新增覆盖 501 张正常同步、跨日汇总、全范围容量预检、列表 total 漂移/重复 ID、明细缺失/重复/意外 ID/空明细及失败不推进游标。
本地 HAR 只读结构核对通过：创建日期查询、72 个 columns、type=3、op=0、optType=0、每页 20 条保持一致；未输出或提交请求头、Cookie、Token、个人信息和业务明细。
未验证：没有请求真实顺运宝接口，也未使用真实账号做浏览器人工验收。

提交与归档

实现提交：4b5cd13 fix: 增强顺运宝同步完整性保护 (#58)
归档提交：ea7932d docs: 归档任务 #58
归档文档：docs/task/58-顺运宝日期同步容量与完整性保护.md

## 实施完成，待用户验收已按确认方案完成，工单保持开启。 ### 实现结果 - 日期范围逐日预检和拉取；人工指定范围最多 31 天，自动增量不受人工天数限制。 - 默认 `max_matches` 为 10000；超限时不会调用列表/明细接口，也不写数据库或游标。 - 分页核对 `list.data.total` 与唯一货运单 ID 数；明细批次核对请求/响应 ID 一一对应且非空。 - 任一日期、列表或明细不完整时停止且不推进 `last_synced_at`；全部成功后沿用原游标规则。 - 日期弹窗增加“每次最多选择 31 天”的持续提示。 - 本机忽略提交的 `admin/config.yaml` 只调整了非凭据字段 `max_matches: 10000`，未读取、输出或提交凭据。 ### 验证结果 - `go vet ./...`：通过。 - Go 1.23.0：`go build ./...`、`go test ./... -count=1`：全部通过。 - 新增覆盖 501 张正常同步、跨日汇总、全范围容量预检、列表 total 漂移/重复 ID、明细缺失/重复/意外 ID/空明细及失败不推进游标。 - 本地 HAR 只读结构核对通过：创建日期查询、72 个 columns、`type=3`、`op=0`、`optType=0`、每页 20 条保持一致；未输出或提交请求头、Cookie、Token、个人信息和业务明细。 - 未验证：没有请求真实顺运宝接口，也未使用真实账号做浏览器人工验收。 ### 提交与归档 - 实现提交：`4b5cd13` `fix: 增强顺运宝同步完整性保护 (#58)` - 归档提交：`ea7932d` `docs: 归档任务 #58` - 归档文档：`docs/task/58-顺运宝日期同步容量与完整性保护.md`

ila referenced this issue

2026-08-09 18:06:51 +08:00

Admin：统一日期范围同步并增加同步记录 #59

ila referenced this issue

2026-08-09 18:58:03 +08:00

Admin：修复顺运宝分页总数误判导致同步停止 #60

ila commented

2026-08-09 21:16:32 +08:00