chengma/cmautobuy
2
0
Fork 0
Code Issues 89 Pull Requests Actions Packages Projects Releases Wiki Activity

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

New Issue
Closed
opened 2026-08-09 18:06:51 +08:00 by ila · 3 comments
ila commented 2026-08-09 18:06:51 +08:00
Owner
Copy Link
Copy Source

基本信息

  • 类型：需求
  • 父级大工单：#14
  • 所属 MVP / 版本：#15 Admin 四模块可用闭环
  • 阶段：顺运宝货运单与采购任务
  • 依赖：#53、#58
  • 状态：已完成

要解决什么

当前顺运宝页同时存在“同步”和“指定日期同步”两个入口：一个隐藏日期范围并自动增量，另一个打开弹窗填写日期。采购员需要先判断该点哪一个，且无法在同步前直接确认实际范围。

最近一次同步报告只保存在进程内存中，Admin 重启后丢失，也无法按操作账号追溯历史同步的范围、结果和失败原因。

做什么 / 不做什么

做

  • 删除独立的自动“同步”入口和“指定日期同步”弹窗，工具栏统一为“开始日期、结束日期、同步、同步记录”。
  • 主按钮名称统一为“同步”；日期按顺运宝 UTC+8、两端包含，服务端仍限制最多 31 天。
  • 通常默认最近 3 天（今天及前两天）；如果同步覆盖游标显示存在更早缺口，则优先预选可连续补齐的范围：
    • 31 天内可追上今天时，开始日扩展到游标日期；
    • 超过 31 天时，预选从游标日期开始的最早 31 天，并明确提示仍有后续区间，成功后下一次继续。
  • 成功同步与当前覆盖游标连续的范围时，将覆盖游标推进到该范围结束日期；历史补拉或跳过缺口的范围不推进。首次没有游标时，成功选择的范围建立后续覆盖基线。
  • 新增持久化同步记录：发起即写“同步中”，完成后写成功或失败、日期范围、操作账号、开始/完成时间、统计、失败原因和是否推进游标。
  • 增加“同步记录”次要按钮，弹窗分页展示记录；错误用文字说明，不只依赖颜色。
  • Admin 启动时把上次进程遗留的“同步中”记录标记为“已中断”。
  • 保持 #58 的逐日容量预检、10000 熔断、列表/明细完整性校验和失败不推进游标。

不做

  • 不改顺运宝请求协议、72 个 columns、每页 20 条和每批 100 个明细 ID。
  • 不增加定时同步、后台调度、实时百分比进度或记录删除功能。
  • 不改 Client 四接口、采购任务、人工规格匹配和真实下单开关。
  • 不记录 Cookie、密码、Token、验证码、收件人和原始业务响应。
  • 自动化测试不请求真实顺运宝接口。

已确认的实现方案

  1. 数据库新增 v8 迁移和 syb_sync_runs 表，只追加、不改 v1-v7；同步记录引用发起用户，状态限定为 running/succeeded/failed/interrupted，添加按开始时间倒序索引。
  2. repository 提供创建、完成、启动中断恢复、分页查询同步记录方法；所有 SQL 参数化。
  3. service 增加默认日期范围计算、连续覆盖游标推进规则和同步记录视图；SyncReport 增加是否推进游标字段。
  4. handler 从已认证的当前用户取得操作账号；拿到同步互斥标志后先创建记录，再启动后台同步，完成后持久化结果。记录写入失败则不启动同步。
  5. 页面把两个旧入口合成一个带可见标签的日期表单；服务端日期错误保留输入并在表单附近显示 role="alert"。
  6. 同步记录弹窗使用现有原生 JS 弹窗机制，服务端渲染记录表和分页；点击分页后仍自动打开弹窗。
  7. 更新数据模型、界面规范、顺运宝接口文档和迁移测试。

预计修改：

  • admin/repository/db.go
  • admin/repository/migrate_test.go
  • admin/repository/syb.go
  • admin/repository/syb_test.go
  • admin/model/model.go
  • admin/service/syb.go
  • admin/service/syb_test.go
  • admin/handler/web/others.go
  • admin/handler/web/others_test.go
  • admin/templates/syb/list.html
  • 必要的 admin/static/css/app.css
  • admin/main.go 及启动测试
  • docs/admin/03-data-model.md
  • docs/admin/05-ui-specification.md
  • docs/admin/08-顺运宝接口.md

验收标准

  • 页面只保留一个“同步”主按钮，按钮左侧直接显示有标签的开始/结束日期；“同步记录”为次要按钮。
  • 正常情况下默认 UTC+8 最近 3 天；存在未覆盖缺口时自动扩展或按最早 31 天分段，并显示可恢复的说明。
  • 日期错误保留输入、在日期表单附近明确显示；登录/OCR 降级后日期范围原样保留。
  • 每次同步持久化操作账号、范围、状态、开始/结束时间、统计、失败原因及游标推进结果。
  • 同步记录弹窗按时间倒序分页，空记录、同步中、成功、失败、已中断均有明确文本。
  • Admin 启动会把旧进程遗留的 running 记录改为 interrupted。
  • 连续覆盖范围成功后游标可分段推进；历史补拉、跳过缺口和任何失败都不推进。
  • #58 的 31 天限制、10000 总量熔断、逐日同步及列表/明细完整性保护全部保持。
  • v8 能从所有已发布 schema 状态升级，全新库、v7 库和重复迁移均通过；启动自检包含新表。
  • 不记录或展示 Cookie、密码、Token、验证码、收件人及原始响应。
  • Client 四接口契约测试保持通过。
  • go vet ./...、Go 1.23.0 go build ./... 和 go test ./... -count=1 通过。

验证方式

从 admin/ 执行：

gofmt -w model/model.go repository/db.go repository/migrate_test.go repository/syb.go repository/syb_test.go service/syb.go service/syb_test.go handler/web/others.go handler/web/others_test.go main.go
go vet ./...
$env:GOTOOLCHAIN="go1.23.0"
go build ./...
go test ./... -count=1
Remove-Item Env:GOTOOLCHAIN

不连接真实顺运宝接口；同步测试继续使用 httptest。

风险和回退

  • 数据库迁移：v8 只新增表和索引。回退旧程序时新表会保留但不被读取，不影响原表；重新升级仍可继续使用。
  • 覆盖游标：仅允许没有基线或范围与当前游标连续时推进，避免跳过未同步日期；失败保持原值。
  • 记录失败：如果无法创建同步记录，本次同步不启动，避免发生无法审计的外部读取和数据库写入。
  • 严格完整性失败仍可能保留本次已经 upsert 的部分数据，但记录标记失败且游标不推进，下次重试幂等覆盖。
## 基本信息 - 类型：需求 - 父级大工单：#14 - 所属 MVP / 版本：#15 Admin 四模块可用闭环 - 阶段：顺运宝货运单与采购任务 - 依赖：#53、#58 - 状态：已完成 ## 要解决什么 当前顺运宝页同时存在“同步”和“指定日期同步”两个入口：一个隐藏日期范围并自动增量，另一个打开弹窗填写日期。采购员需要先判断该点哪一个，且无法在同步前直接确认实际范围。 最近一次同步报告只保存在进程内存中，Admin 重启后丢失，也无法按操作账号追溯历史同步的范围、结果和失败原因。 ## 做什么 / 不做什么 ### 做 - 删除独立的自动“同步”入口和“指定日期同步”弹窗，工具栏统一为“开始日期、结束日期、同步、同步记录”。 - 主按钮名称统一为“同步”；日期按顺运宝 UTC+8、两端包含，服务端仍限制最多 31 天。 - 通常默认最近 3 天（今天及前两天）；如果同步覆盖游标显示存在更早缺口，则优先预选可连续补齐的范围： - 31 天内可追上今天时，开始日扩展到游标日期； - 超过 31 天时，预选从游标日期开始的最早 31 天，并明确提示仍有后续区间，成功后下一次继续。 - 成功同步与当前覆盖游标连续的范围时，将覆盖游标推进到该范围结束日期；历史补拉或跳过缺口的范围不推进。首次没有游标时，成功选择的范围建立后续覆盖基线。 - 新增持久化同步记录：发起即写“同步中”，完成后写成功或失败、日期范围、操作账号、开始/完成时间、统计、失败原因和是否推进游标。 - 增加“同步记录”次要按钮，弹窗分页展示记录；错误用文字说明，不只依赖颜色。 - Admin 启动时把上次进程遗留的“同步中”记录标记为“已中断”。 - 保持 #58 的逐日容量预检、10000 熔断、列表/明细完整性校验和失败不推进游标。 ### 不做 - 不改顺运宝请求协议、72 个 columns、每页 20 条和每批 100 个明细 ID。 - 不增加定时同步、后台调度、实时百分比进度或记录删除功能。 - 不改 Client 四接口、采购任务、人工规格匹配和真实下单开关。 - 不记录 Cookie、密码、Token、验证码、收件人和原始业务响应。 - 自动化测试不请求真实顺运宝接口。 ## 已确认的实现方案 1. 数据库新增 v8 迁移和 `syb_sync_runs` 表，只追加、不改 v1-v7；同步记录引用发起用户，状态限定为 `running/succeeded/failed/interrupted`，添加按开始时间倒序索引。 2. repository 提供创建、完成、启动中断恢复、分页查询同步记录方法；所有 SQL 参数化。 3. service 增加默认日期范围计算、连续覆盖游标推进规则和同步记录视图；`SyncReport` 增加是否推进游标字段。 4. handler 从已认证的当前用户取得操作账号；拿到同步互斥标志后先创建记录，再启动后台同步，完成后持久化结果。记录写入失败则不启动同步。 5. 页面把两个旧入口合成一个带可见标签的日期表单；服务端日期错误保留输入并在表单附近显示 `role="alert"`。 6. 同步记录弹窗使用现有原生 JS 弹窗机制，服务端渲染记录表和分页；点击分页后仍自动打开弹窗。 7. 更新数据模型、界面规范、顺运宝接口文档和迁移测试。 预计修改： - `admin/repository/db.go` - `admin/repository/migrate_test.go` - `admin/repository/syb.go` - `admin/repository/syb_test.go` - `admin/model/model.go` - `admin/service/syb.go` - `admin/service/syb_test.go` - `admin/handler/web/others.go` - `admin/handler/web/others_test.go` - `admin/templates/syb/list.html` - 必要的 `admin/static/css/app.css` - `admin/main.go` 及启动测试 - `docs/admin/03-data-model.md` - `docs/admin/05-ui-specification.md` - `docs/admin/08-顺运宝接口.md` ## 验收标准 - [x] 页面只保留一个“同步”主按钮，按钮左侧直接显示有标签的开始/结束日期；“同步记录”为次要按钮。 - [x] 正常情况下默认 UTC+8 最近 3 天；存在未覆盖缺口时自动扩展或按最早 31 天分段，并显示可恢复的说明。 - [x] 日期错误保留输入、在日期表单附近明确显示；登录/OCR 降级后日期范围原样保留。 - [x] 每次同步持久化操作账号、范围、状态、开始/结束时间、统计、失败原因及游标推进结果。 - [x] 同步记录弹窗按时间倒序分页，空记录、同步中、成功、失败、已中断均有明确文本。 - [x] Admin 启动会把旧进程遗留的 `running` 记录改为 `interrupted`。 - [x] 连续覆盖范围成功后游标可分段推进；历史补拉、跳过缺口和任何失败都不推进。 - [x] #58 的 31 天限制、10000 总量熔断、逐日同步及列表/明细完整性保护全部保持。 - [x] v8 能从所有已发布 schema 状态升级，全新库、v7 库和重复迁移均通过；启动自检包含新表。 - [x] 不记录或展示 Cookie、密码、Token、验证码、收件人及原始响应。 - [x] Client 四接口契约测试保持通过。 - [x] `go vet ./...`、Go 1.23.0 `go build ./...` 和 `go test ./... -count=1` 通过。 ## 验证方式 从 `admin/` 执行： ```powershell gofmt -w model/model.go repository/db.go repository/migrate_test.go repository/syb.go repository/syb_test.go service/syb.go service/syb_test.go handler/web/others.go handler/web/others_test.go main.go go vet ./... $env:GOTOOLCHAIN="go1.23.0" go build ./... go test ./... -count=1 Remove-Item Env:GOTOOLCHAIN ``` 不连接真实顺运宝接口；同步测试继续使用 `httptest`。 ## 风险和回退 - 数据库迁移：v8 只新增表和索引。回退旧程序时新表会保留但不被读取，不影响原表；重新升级仍可继续使用。 - 覆盖游标：仅允许没有基线或范围与当前游标连续时推进，避免跳过未同步日期；失败保持原值。 - 记录失败：如果无法创建同步记录，本次同步不启动，避免发生无法审计的外部读取和数据库写入。 - 严格完整性失败仍可能保留本次已经 upsert 的部分数据，但记录标记失败且游标不推进，下次重试幂等覆盖。
ila commented 2026-08-09 18:07:10 +08:00
Author
Owner
Copy Link
Copy Source

已开始实施。#59 已加入父级 #14 和 MVP #15。将保留工作区现有 Client 与脚本改动；数据库只追加 v8，自动化不连接真实顺运宝接口。

已开始实施。#59 已加入父级 #14 和 MVP #15。将保留工作区现有 Client 与脚本改动；数据库只追加 v8，自动化不连接真实顺运宝接口。
ila commented 2026-08-09 18:23:58 +08:00
Author
Owner
Copy Link
Copy Source

实施完成，等待用户验收

  • 实现提交：05a54b0（统一日期范围入口、安全默认范围与分段游标、v8 同步记录、历史弹窗、启动中断恢复）
  • 归档提交：3bd9c9a
  • 归档文档：docs/task/59-统一日期同步与同步记录.md

验证（admin/，Go 1.23.0）：

  • go build ./...：通过
  • go test ./... -count=1：通过
  • go vet ./...：通过
  • git diff --check：通过

安全复核：自动化仅使用 httptest，没有访问真实顺运宝；同步记录不保存 Cookie、密码、Token、验证码、收件信息或原始响应；为避免上游原始行进入失败记录，缺少 ID 的错误不再拼接 raw 数据。

未验证：未连接真实顺运宝账号执行同步，未做人工浏览器视觉验收。工单保持打开，待用户验收后再关闭，并同步 #14/#15 清单。

## 实施完成，等待用户验收 - 实现提交：`05a54b0`（统一日期范围入口、安全默认范围与分段游标、v8 同步记录、历史弹窗、启动中断恢复） - 归档提交：`3bd9c9a` - 归档文档：`docs/task/59-统一日期同步与同步记录.md` 验证（`admin/`，Go 1.23.0）： - `go build ./...`：通过 - `go test ./... -count=1`：通过 - `go vet ./...`：通过 - `git diff --check`：通过 安全复核：自动化仅使用 `httptest`，没有访问真实顺运宝；同步记录不保存 Cookie、密码、Token、验证码、收件信息或原始响应；为避免上游原始行进入失败记录，缺少 ID 的错误不再拼接 raw 数据。 未验证：未连接真实顺运宝账号执行同步，未做人工浏览器视觉验收。工单保持打开，待用户验收后再关闭，并同步 #14/#15 清单。
ila commented 2026-08-09 21:16:38 +08:00
Author
Owner
Copy Link
Copy Source

用户已于 2026-08-09 明确通过全部 Admin 待验收工单。本工单验收通过，现关闭，并同步父级 #15、#14 的任务清单。

用户已于 2026-08-09 明确通过全部 Admin 待验收工单。本工单验收通过，现关闭，并同步父级 #15、#14 的任务清单。
ila closed this issue 2026-08-09 21:16:41 +08:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
admin ila
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: chengma/cmautobuy#59