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

- 类型：需求
- 父级大工单：#14
- 所属 MVP / 版本：#15 / MVP
- 状态：已完成
- 日期：2026-08-09
- Gitea 工单：http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/59

## 背景与目标

顺运宝数据页原来同时提供自动增量“同步”和“指定日期同步”，采购员需要先判断
应该使用哪个入口，也无法在 Admin 重启后查看以前的执行结果。本任务把日期范围
直接放到主工具条，只保留一个同步入口，并增加可持久化、可分页查看的同步记录。

## 最终方案

- 工具条显示开始日期、结束日期、主操作“同步”和次操作“同步记录”。日期按
  UTC+8 解释，闭区间最多 31 天。
- 通常默认最近 3 天；覆盖游标较早时从游标当天连续补齐，长缺口先选择最早
  31 天。成功启动后清除 URL 中的旧日期，使下一次刷新按新游标显示下一段。
- 首次成功同步以所选结束日建立覆盖游标；已有游标时，只有衔接当前覆盖范围并
  向后延伸才推进。历史补拉和跳过缺口的范围不推进。
- 数据库迁移 v8 新增 `syb_sync_runs`。后台同步开始前写入 `running`，结束后写入
  `succeeded` 或 `failed`；Admin 启动时把遗留的 `running` 改为 `interrupted`。
- 同步记录弹窗按开始时间倒序分页，显示状态、日期范围、操作账号、时间、统计、
  覆盖游标结果和失败原因。记录不保存凭据、验证码、收件信息或原始响应。
- 实现与建单方案一致；额外清除了成功启动后的旧日期查询参数，避免长缺口分段时
  重复提交刚完成的上一段。

## 改了哪些

- `admin/repository/db.go`、`admin/model/model.go`、`admin/repository/syb.go`：增加 v8
  迁移、同步记录模型及读写接口。
- `admin/service/syb.go`：计算安全默认范围、控制覆盖游标推进、创建和展示同步记录。
- `admin/handler/web/others.go`、`admin/main.go`：接入操作账号、后台执行记录、历史
  分页和启动中断恢复。
- `admin/templates/syb/list.html`、`admin/static/css/app.css`：统一同步工具条和同步记录
  弹窗。
- `admin/syb/client.go`：错误信息不再拼入顺运宝原始行，避免个人信息进入记录。
- `admin/**/*_test.go`：补充迁移、游标、记录、分页、跳转和页面烟测。
- `admin/config.example.yaml`、`docs/admin/03-data-model.md`、
  `docs/admin/05-ui-specification.md`、`docs/admin/08-顺运宝接口.md`：同步配置注释和
  Admin 基线文档。

## 验收结果

| 验收标准 | 结果 |
|---|---|
| 页面只保留一个同步入口，日期范围在按钮左侧且通常默认最近 3 天 | 通过 |
| 缺口可按最多 31 天连续分段，跳过缺口或历史补拉不错误推进游标 | 通过 |
| 同步开始前建立记录，成功、失败和重启中断状态可持久化 | 通过 |
| 同步记录弹窗可分页查看操作账号、范围、时间、统计、游标和错误 | 通过 |
| 登录、OCR 降级和日期校验过程保留已选日期 | 通过 |
| 同步记录不写入凭据、验证码、收件信息和原始响应 | 通过 |
| v1 至 v7 数据库均可升级到 v8，重复迁移和 schema 自检通过 | 通过 |

## 测试

- 执行的命令：在 `admin/` 目录执行
  `$env:GOTOOLCHAIN="go1.23.0"; go build ./...; go test ./... -count=1; go vet ./...; Remove-Item Env:GOTOOLCHAIN`
- 结果：构建通过；全部 Go 测试通过；`go vet` 通过；`git diff --check` 通过。
- **没验证到的部分**：未连接真实顺运宝账号执行同步，未在人工浏览器中做视觉验收；
  自动化测试使用本地 `httptest` 假服务端，未发送真实业务请求。

## 相关提交

- `05a54b0` 统一顺运宝日期同步并记录历史