docs: 归档任务 #59

docs/task/59-统一日期同步与同步记录.md

@@ -0,0 +1,68 @@
+# 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` 统一顺运宝日期同步并记录历史