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

- 类型：缺陷
- 父级大工单：#14
- 所属 MVP / 版本：#15 Admin 四模块可用闭环
- 状态：已完成
- 日期：2026-08-09
- Gitea 工单：http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/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`；未输出请求头和响应正文。
- **没验证到的部分**：未请求真实顺运宝接口，未用真实账号执行浏览器人工验收；
  真实接口在同步期间是否会出现总数漂移或空明细，只能在后续实际运行中观察。

## 遗留问题（选填）

无。

## 相关提交

- `4b5cd13` `fix: 增强顺运宝同步完整性保护 (#58)`