# 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` 同步记录弹窗改为局部刷新