docs: 归档任务 #62

docs/task/62-同步记录弹窗局部刷新.md

@@ -0,0 +1,69 @@
+# 62 Admin：同步记录弹窗改为局部刷新
+
+- 类型：缺陷
+- 父级大工单：#14
+- 所属 MVP / 版本：#15 / MVP
+- 状态：已完成
+- 日期：2026-08-09
+- Gitea 工单：http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/62
+
+## 背景与目标
+
+#61 的“刷新记录”通过重新加载 `/syb` 整页实现。虽然不会请求顺运宝，但会同时
+重渲染主货运单列表，不符合“刷新按钮只更新同步记录列表，F5 才刷新整个页面”的
+操作语义。本任务把刷新和弹窗分页改为局部加载，保留主页面操作上下文。
+
+## 最终方案
+
+- 新增受网页登录保护的只读路由 `/syb/sync-history`，只调用现有同步记录查询并
+  返回 HTML 片段，不读取顺运宝配置、不调用顺运宝、不写数据库。
+- 把同步记录表格、总数和底部操作抽到 `syb/history_partial` 模板，完整页面和
+  局部路由共用，避免两份结构漂移。
+- “刷新同步记录”和弹窗内翻页通过原生 `fetch` 获取片段，只替换
+  `data-syb-history-slot` 内部；主表 DOM、滚动、勾选、筛选和弹窗外壳保持不变。
+- 请求期间显示加载状态并阻止重复请求；失败时保留旧记录，通过 `role="alert"`
+  显示错误和重试指引；成功后焦点回到刷新按钮且不滚动页面。
+- 片段响应和 `fetch` 均使用 `no-store`，防止刷新取得缓存结果。登录过期导致重定向
+  时跳转登录页。
+- 无 JavaScript 时，分页链接降级为原来的 `/syb?history=1...` 整页路径。
+- 实现与建单方案一致。`ui-ux-pro-max` 促使本任务保留旧内容处理失败、提供可访问
+  错误和加载反馈，并维持焦点与页面上下文。
+
+## 改了哪些
+
+- `admin/handler/web/web.go`：注册同步记录片段路由。
+- `admin/handler/web/others.go`：渲染只读片段并生成局部、降级两套分页 URL。
+- `admin/templates/syb/history_partial.html`：新增同步记录共用片段。
+- `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`：明确同步记录局部刷新与 F5 的职责。
+
+## 验收结果
+
+| 验收标准 | 结果 |
+|---|---|
+| 刷新按钮只请求本地同步记录片段，不请求 SYB 整页和顺运宝 | 通过 |
+| 只替换弹窗内部，主表 DOM、滚动、勾选和筛选不受代码路径影响 | 通过 |
+| 弹窗翻页使用同一局部加载机制 | 通过 |
+| 加载状态可见并阻止重复请求 | 通过 |
+| 失败保留旧记录并提供可访问错误和重试提示 | 通过 |
+| 弹窗保持打开，成功或失败后焦点回到刷新按钮且不滚动 | 通过 |
+| 无 JavaScript 时分页链接可降级到完整 SYB 页面 | 通过 |
+| F5 和同步按钮原有职责不变 | 通过 |
+| 未修改数据库、同步业务和 Client 接口 | 通过 |
+
+## 测试
+
+- 执行的命令：在 `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` 通过。
+- **没验证到的部分**：未在人工浏览器中实际观察主表滚动、勾选和焦点保持；未使用
+  真实顺运宝账号（本功能按设计也不会发起顺运宝请求）。
+
+## 相关提交
+
+- `d8a2424` 同步记录弹窗改为局部刷新