4.2 KiB
4.2 KiB
58 Admin：增强顺运宝日期同步容量与完整性保护
- 类型：缺陷
- 父级大工单：#14
- 所属 MVP / 版本：#15 Admin 四模块可用闭环
- 状态：已完成
- 日期：2026-08-09
- Gitea 工单：#58
背景与目标
顺运宝按货运单创建日期查询时，短日期范围的数据量也可能超过原默认上限
500。原同步流程还没有核对分页结果和批量明细是否完整，存在响应短缺后仍推进
同步游标、造成静默漏单的风险。
本任务在不改变 HAR 已验证查询协议的前提下，提高正常同步容量，并确保只有列表
和明细都完整时才推进 last_synced_at。
最终方案
- 保持
t_stock.created、UTC+8、闭区间、72 个columns、每页 20 条和明细 每批最多 100 个 ID 的协议不变。 - 将日期范围拆为逐日计划，先查询所有日期的
listTotal并计算全范围总量； 超过max_matches时不调用列表或明细接口，也不写数据库和游标。 - 默认
max_matches从500提高为10000；人工指定范围限制为最多 31 天， 自动增量不受人工天数限制。 - 每一页核对
list.data.total与当日预检总数，分页结束后核对唯一货运单 ID 数量；总数漂移、缺页和重复 ID 均明确失败。 - 每批明细要求返回 ID 与请求 ID 一一对应，并要求每张货运单至少包含一个商品 明细；缺失、重复、意外 ID 或空明细均明确失败。
- 任一日期失败时保留已写入的幂等数据，但不推进游标；所有日期成功后才沿用原 游标规则。实施结果与建单方案一致。
改了哪些
admin/service/syb.go：增加 31 天校验、逐日预检与同步、默认容量和列表/明细 完整性保护。admin/service/syb_test.go：增加 501 张同步、跨日汇总、容量预检、列表异常、 明细异常和游标保护测试。admin/syb/client.go：解析并返回list.data.total，拒绝缺失或非法值。admin/syb/client_test.go：更新列表契约测试并覆盖非法total。admin/config.example.yaml：将示例上限改为10000并说明适用范围。admin/templates/syb/list.html：在日期范围弹窗中持续提示最多 31 天。docs/admin/05-ui-specification.md、docs/admin/08-顺运宝接口.md：同步界面、 分页、容量与完整性规则。- 本机忽略提交的
admin/config.yaml：只把非凭据字段max_matches改为10000，未读取、输出或提交凭据。
验收结果
| 验收标准 | 结果 |
|---|---|
| HAR 创建日期查询结构、72 个 columns 和每页 20 条保持一致 | 通过 |
| 指定日期闭区间最多 31 天，32 天被明确拒绝 | 通过 |
| 多日范围逐日预检和拉取，报告汇总全范围 | 通过 |
| 默认上限 10000；全范围超限前不拉列表、明细，不写数据库或游标 | 通过 |
| 501 张货运单可按 20 条分页并正常同步 | 通过 |
list.data.total 非法、漂移或唯一 ID 不足时失败且不推进游标 |
通过 |
| 明细缺失、重复、意外 ID 或空明细时失败 | 通过 |
| 全部日期成功才推进游标，历史局部补拉仍不推进 | 通过 |
重试继续 upsert，人工 shopee_sku_id 不被覆盖 |
通过 |
| 未提交 HAR、Cookie、Token、个人信息或业务明细 | 通过 |
测试
- 执行的命令：
go vet ./... - 结果：通过。
- 执行的命令：
$env:GOTOOLCHAIN="go1.23.0"; go build ./...; go test ./... -count=1; Remove-Item Env:GOTOOLCHAIN - 结果：构建通过；Admin 全部 Go 测试通过。
- 执行的命令：本地 PowerShell 只读解析
raw_data/query_shunyunbaoerp_between_createdate.har的目标请求结构。 - 结果：
listTotal与list均为创建日期范围查询、72 个columns、type=3、op=0、optType=0、length=20；未输出请求头和响应正文。 - 没验证到的部分：未请求真实顺运宝接口，未用真实账号执行浏览器人工验收； 真实接口在同步期间是否会出现总数漂移或空明细，只能在后续实际运行中观察。
遗留问题（选填）
无。
相关提交
4b5cd13fix: 增强顺运宝同步完整性保护 (#58)