docs: 归档任务 #58

docs/task/58-顺运宝日期同步容量与完整性保护.md

@@ -0,0 +1,83 @@
+# 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)`