From 3bd9c9a2c39f98c92b897a803d6d1d02483dafa3 Mon Sep 17 00:00:00 2001 From: chengma Date: Sun, 9 Aug 2026 18:23:33 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=BD=92=E6=A1=A3=E4=BB=BB=E5=8A=A1=20?= =?UTF-8?q?#59?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/task/59-统一日期同步与同步记录.md | 68 ++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 docs/task/59-统一日期同步与同步记录.md diff --git a/docs/task/59-统一日期同步与同步记录.md b/docs/task/59-统一日期同步与同步记录.md new file mode 100644 index 0000000..6914553 --- /dev/null +++ b/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` 统一顺运宝日期同步并记录历史