docs: 归档任务 #61

docs/task/61-顺运宝同步反馈与记录刷新.md

@@ -0,0 +1,66 @@
+# 61 Admin：优化顺运宝同步反馈与记录刷新交互
+
+- 类型：需求
+- 父级大工单：#14
+- 所属 MVP / 版本：#15 / MVP
+- 状态：已完成
+- 日期：2026-08-09
+- Gitea 工单：http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/61
+
+## 背景与目标
+
+顺运宝同步是后台长任务，操作员需要立即知道点击已经生效，并避免重复发起。
+同步记录弹窗此前没有刷新入口，只能手工刷新整个 SYB 页面；弹窗底部的页码和
+翻页组件也需要收敛为统一的右侧操作区。
+
+## 最终方案
+
+- 同步表单有效提交后，原生 JavaScript 立即把按钮变成禁用的“同步中…”，并设置
+  `aria-busy`；页面重新渲染时，当前进程仍在同步也保持相同状态。
+- 服务端同步互斥继续作为最终保护。旧页面或多窗口重复请求时，统一提示“同步
+  正在进行，请耐心等待，请勿重复点击”。成功启动只在状态条反馈，不增加需要
+  手工关闭的确认弹窗。
+- 同步记录弹窗增加“刷新记录”按钮。点击后按钮显示“刷新中…”并禁用，再通过
+  普通 GET 重新加载；URL 保留当前历史页码、订单号、日期范围和 `history=1`，
+  因此返回后弹窗自动重开。
+- 刷新、当前页、翻页和关闭控件统一放在弹窗底部右侧，窄宽度时允许换行。
+- 不自动轮询，不增加新 API，不改变同步业务和数据库。
+- 实现与建单方案一致。根据 `ui-ux-pro-max` 的长任务反馈规则，加载状态在点击后
+  立即出现，成功反馈不阻塞操作，重复操作仍由服务端保护。
+
+## 改了哪些
+
+- `admin/handler/web/others.go`：传递当前同步状态、统一重复提交提示、生成记录刷新
+  URL。
+- `admin/templates/syb/list.html`：增加同步按钮运行态、记录刷新按钮并调整底部顺序。
+- `admin/static/js/app.js`：增加同步提交和记录刷新的即时加载反馈。
+- `admin/static/css/app.css`：记录弹窗底部右对齐并支持换行。
+- `admin/handler/web/others_test.go`、`admin/main_test.go`：覆盖刷新 URL、运行态按钮和
+  页面提示。
+- `docs/admin/05-ui-specification.md`：固化长任务反馈和同步记录刷新规则。
+
+## 验收结果
+
+| 验收标准 | 结果 |
+|---|---|
+| 有效提交后同步按钮立即显示“同步中…”并禁用 | 通过 |
+| 页面检测到同步任务时渲染禁用的“同步中…”按钮 | 通过 |
+| 服务端重复请求提示统一且互斥保护保留 | 通过 |
+| 成功启动不增加需要手工关闭的确认弹窗 | 通过 |
+| 记录刷新按钮有“刷新中…”状态并防重复点击 | 通过 |
+| 刷新保持弹窗、当前历史页码和筛选条件 | 通过 |
+| 弹窗底部操作统一右对齐并允许窄屏换行 | 通过 |
+| 未增加轮询、接口、数据库或同步业务变更 | 通过 |
+
+## 测试
+
+- 执行的命令：在 `admin/` 目录执行
+  `$env:GOTOOLCHAIN="go1.23.0"; go build ./...; go test ./... -count=1; go vet ./...; Remove-Item Env:GOTOOLCHAIN`
+- 结果：构建通过；全部 Go 测试通过；`go vet`、`git diff --check` 和
+  `node --check static/js/app.js` 通过。
+- **没验证到的部分**：未使用真实顺运宝运行长任务；未在人工浏览器中确认按钮
+  视觉状态和不同窗口宽度下的实际对齐效果。
+
+## 相关提交
+
+- `3fd863d` 优化顺运宝同步反馈与记录刷新