From e5abbfd4b9f4b9021c8e207d2e9748e647264406 Mon Sep 17 00:00:00 2001 From: chengma Date: Sun, 9 Aug 2026 21:02:58 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=BD=92=E6=A1=A3=E4=BB=BB=E5=8A=A1=20?= =?UTF-8?q?#62?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/task/62-同步记录弹窗局部刷新.md | 69 ++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 docs/task/62-同步记录弹窗局部刷新.md diff --git a/docs/task/62-同步记录弹窗局部刷新.md b/docs/task/62-同步记录弹窗局部刷新.md new file mode 100644 index 0000000..ea49a31 --- /dev/null +++ b/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` 同步记录弹窗改为局部刷新