diff --git a/docs/页面缓存-操作后自动刷新数据设计方案.md b/docs/页面缓存-操作后自动刷新数据设计方案.md new file mode 100644 index 00000000..7d282ffb --- /dev/null +++ b/docs/页面缓存-操作后自动刷新数据设计方案.md @@ -0,0 +1,621 @@ +# 页面缓存下「操作成功后自动刷新列表」设计方案 + +> 状态:设计稿(仅分析,未改代码) +> 适用范围:所有启用了「页面缓存 / Tab 缓存」的列表页,以 `order/orderManagement` 为落地样例 +> 更新日期:2026-09-05 + +> 审计修订(2026-09-05):按「修改平台后刷新 / 切到 waveOrder 零副作用 / 缓存保持正常」做了代码级复核,修正了“嵌套 keep-alive 会把路由级 `activated` 透传给子页签”的误述(不成立),并补充「脏标记懒刷新」为推荐主方案。修订点见 §2.1.3、§6 方案 A/B、§8、§9、§10。 + +> 审计修订2(2026-09-05,操作影响范围):按「在待处理订单执行『修改平台』后仅本页刷新、待审核订单等其它页签不受影响」复核——各订单页签按状态互斥、行不重叠(各自查 `orderPendingOrder/orderReviewOrder/orderExpectionOrder/...` 的 list),修改平台只改本列表字段值、不改成员资格,**现状本地 `params.loadData()` 即满足需求,无需跨页 dirty/广播**。此前粗 scope `order.list.changed` 会让不含这些行的页签在切回时被无意义刷新,已废弃,改为「默认局部刷新 + 仅类型②操作对受影响目标桶打细粒度脏」。新增 §3.1 分类,修订 §2.4、§6、§7、§8、§9、§10。 + +--- + +## 1. 背景与目标 + +### 1.1 需求描述 + +项目已启用两级页面缓存(路由级 keep-alive + 页面内部 Tab 级 keep-alive)。缓存带来「切走再切回不重新挂载、列表数据不刷新」的副作用。 + +期望行为:**页面内/跨页面执行了会改动列表数据的某个功能后,自动调用与「刷新按钮」相同的刷新接口拉取最新数据**,无需用户手动点刷新。 + +典型例子:`order/orderManagement` 中执行「建单」「修改平台」等操作后,列表 / 角标应自动保持最新。 + +### 1.2 术语约定 + +| 术语 | 含义 | +|---|---| +| 路由级缓存 | `AppMain` 里 `` 对整页路由组件的缓存(`orderManagement` 整页) | +| Tab 级缓存 | `orderManagement/index.vue` 内部 `` 对 8 个子页签(待审核/待处理/…)的缓存 | +| `loadData()` | 每个列表子页「唯一的取数函数」,与表格右上角「刷新按钮」(`UpperTable` 的 `@refresh`)是同一个函数 | +| 全局宿主 | 挂在 Layout 层、不在任何 keep-alive 内的常驻组件(如建单弹窗 `CreateOrderSessionHost`) | + +### 1.3 目标与非目标 + +**目标** + +1. 明确「页面缓存 + 列表自动刷新」的完整触发链路与责任划分。 +2. 沉淀一套可复用的通用机制(而非每个页面各写一套),兼容本项目已有写法。 +3. 以 `orderManagement` 为例给出落地映射与验收点。 + +**非目标** + +- 不改动缓存策略本身(缓存开关/容量由实验性设置控制)。 +- 不做通用全局 event-bus 引入(避免引入第三方依赖与全局耦合)。 +- 本文只出方案,不落地代码。 + +--- + +## 2. 现状分析(基于代码梳理) + +### 2.1 两级缓存结构 + +#### 2.1.1 路由级缓存 + +`src/layout/component/AppMain.vue`: + +```html + + + +``` + +- `cachedViews` 来自 `stores/modules/tagsView.ts`(按路由 `name` 加入/删除)。 +- `wrapRouteComponent` 把路由组件包装成 `name = 路由 name`,使 include 真正生效。 +- `pageCacheEnabled / pageCacheMax`(默认开、`max=8`,LRU)来自 `stores/modules/experimental.ts`。 + +结论:`order/orderManagement` 整个页签容器在路由切换时**不会卸载重建**,切回时走的是 `activated` 而非 `mounted`。 + +#### 2.1.2 页面内 Tab 级缓存 + +`src/views/order/orderManagement/index.vue`(同样模式还有 `stock/stockManagement/index.vue` 等): + +```html + + + +``` + +- 8 个子页签组件:`reviewOrder / pendingOrder / exceptionOrder / outboundOrder / entrustWarehouse / deliveryOrder / deliveryException / archiveOrder`。 +- `tabCacheEnabled` 默认开、`tabCacheMax` 默认 2(LRU),仍来自 `experimental` store。 +- 页签切换走本地状态(`handleTabChange`),不写回 URL,避免触发 AppMain 整页重建(详见 `index.vue` 注释「方案B」)。 + +结论:切走再切回某子页签,组件不卸载,**不会自动拉取**。超过 2 个页签时最久未用的会被 LRU 淘汰(触发卸载,下次进入重新 `mounted` 拉取)。 + +#### 2.1.3 关键结论 + +两级缓存导致两类“不刷新”: + +- ① 路由级:从其它菜单/页面回到 `orderManagement` → 不刷新。 +- ② Tab 级:在 `orderManagement` 内部切回已缓存子页签 → 不刷新。 + +##### ⚠️ 重要事实:嵌套 keep-alive 的 `activated` 只作用在“直接子级” + +- Vue 的 keep-alive 只对其**直接子组件**触发 `activated/deactivated`。当外层(`AppMain` 路由级)keep-alive 激活/停用 `orderManagement/index.vue` 时,只是把整棵子树移入/移出 DOM,**不会**把 `activated` 透传给容器内部的 Tab 级 keep-alive 子组件(`reviewOrder/pendingOrder/…`)。 +- 因此: + - 子页签自己的 `onActivated` **只能**覆盖“在容器内部切回某缓存 Tab”(Tab 级); + - “从其它菜单/页面切回 `orderManagement`”需要**容器(`index.vue`)级的 `onActivated`** 自行向当前激活页签转发刷新,不能指望子页签收到路由级激活(见方案 A-2)。 +- 对应地,`waveOrder` 等其它缓存路由同理:给它们加 `onActivated` 只会在“切回 waveOrder 本页”时触发,不会在切走或停留在其它页面时触发任何动作。 + +### 2.2 列表唯一的刷新入口:`loadData()` + +各子页签结构高度一致(以 `pendingOrder.vue` 为例): + +```ts +async function loadData() { + if (loading.value) return // ① loading 去重(天然幂等,防并发重复请求) + loading.value = true + const queryParams = { pagination, where: buildExportWhere(), sort } // ② 沿用当前筛选/分页 + try { + const res = await orderPendingOrder.list(queryParams) + // ③ 解析后写 list / pagination.total + } finally { + loading.value = false + queryTime.value = Date.now() - start + } +} +``` + +模板中: + +```html + +``` + +- 「刷新按钮」= `UpperTable` 内部刷新图标 → emit `refresh` → `loadData`。 +- `loadData` 具备:loading 去重、沿用当前筛选与页码、耗时统计。**“自动刷新”应复用它,语义 = 模拟点了一次刷新按钮**。 + +### 2.3 已有「操作 → 刷新」机制盘点 + +#### 2.3.1 同页操作:成功后原地 `loadData()` + +集中实现于 `src/views/order/orderManagement/utils/toolbar-actions.ts`(工厂函数注入 `loadData` 作为 `params.loadData` / `reload`): + +| 功能 | 入口 | 成功后行为 | +|---|---|---| +| 修改平台 / 修改快递 | `submitUpdateOrderMeta` | 关闭弹窗 → `clearSelection()` → `await params.loadData()` | +| 通用批量动作(改留言/加急/锁单…) | `executeApiAction(... reload: params.loadData)` | 成功 → `reload()` | +| 储位分配 | `submitStorageAllocate`(含异步轮询) | 轮询结束 → `params.loadData()` | +| 批量复制 / 手动运单 / 地址修改 / 同步订单号 / 异常处理等 | 各 `submit*` | 成功后 `await loadData()` | + +另外打印链路(`pendingOrder.vue`): + +```ts +useOrderBatchPrint({ ..., onPrintSuccess: () => loadData() }) +useSubWaybillPrint({ ..., onPrintSuccess: () => loadData() }) +``` + +**共同特征:只刷新“当前这个页签实例自己”。** 若同一条数据在另一个缓存页签里也在展示,那个页签不会自动更新。 + +#### 2.3.2 全局宿主 + 跨页签刷新:`useCreateOrderSession`(建单场景) + +这是项目里**唯一已实现“跨缓存实例自动刷新”的参考实现**,值得重点解剖: + +- 全局宿主:`src/layout/component/CreateOrderSessionHost.vue` 挂在 `layout/index.vue` 的 `main-box` 里,位于 `` 旁,**不在任何 keep-alive 内**,生命周期与 Layout 相同。 +- 模块级单例 composable:`src/views/order/orderManagement/composables/useCreateOrderSession.ts` 在**模块顶层**持有状态: + +```ts +const successCallbacks = shallowRef(new Set<() => void | Promise>()) + +export function useCreateOrderSession() { + function registerCreateOrderSuccess(cb) { successCallbacks.value.add(cb) } + function unregisterCreateOrderSuccess(cb) { successCallbacks.value.delete(cb) } + async function notifyCreateOrderSuccess() { + const tasks = Array.from(successCallbacks.value).map((cb) => cb()) + await Promise.allSettled(tasks) + } + // ... +} +``` + +- 订阅方(各列表页签):`reviewOrder.vue`、`pendingOrder.vue`、`exceptionOrder.vue` 均 + +```ts +onMounted(() => { registerCreateOrderSuccess(loadData); loadData(); ... }) +onUnmounted(() => { unregisterCreateOrderSuccess(loadData) }) +``` + +- 触发方(建单弹窗 `CreatePendingOrderDialog.vue`,批量建单成功后): + +```ts +if (result.success_count > 0) { + emit('success') + void notifyCreateOrderSuccess() // → 所有“存活且已订阅”的页签各自 loadData() +} +``` + +**要点提炼(这套机制能正确适配缓存的原因)** + +1. 注册/注销挂在 `onMounted/onUnmounted` 而非 `onActivated/onDeactivated`。 + - keep-alive 缓存中,隐藏页签仍是“已 mounted 未销毁”状态 → 回调保留; + - LRU 淘汰销毁才 `onUnmounted` → 回调注销,**不会产生对已销毁页签的幽灵刷新**。 +2. 触发方与页面解耦(建单弹窗活在 Layout 全局宿主,与缓存页不在同一棵组件树),因此必须用模块级(跨组件)通信,而不是组件 props/事件。 +3. 事件回调即 `loadData`,天然幂等(loading 去重)+ 沿用筛选条件。 + +#### 2.3.3 `onActivated` 刷新的既有先例(storage/entry) + +`src/views/storage/entry/component/DirectInboundLogs.vue`、`EntryBindingRelations.vue` 已有: + +```ts +onActivated(() => { if (props.id) void loadLogs() }) +``` + +说明「keep-alive 实例被再次激活时重新取数」在本项目已被使用过,可作为通用化依据。 + +### 2.4 现状能力矩阵(orderManagement 子页签) + +| 操作 | 是否刷新当前页 | 是否刷新其它缓存页签 | 是否刷新全局宿主/角标 | +|---|---|---|---| +| 建单(批量/识别) | ✅(bus 通知) | ✅(bus 通知,所有已订阅存活页签) | 角标仅在切 tab / 挂载时刷新,建单后不刷 | +| 修改平台 / 修改快递 | ✅ 原地 loadData | ❌ | ❌ | +| 其余 toolbar 动作 | ✅ 原地 loadData | ❌ | ❌ | +| 打印成功 | ✅ | ❌ | ❌ | +| 切回缓存页签 / 切回本菜单 | ❌(无 onActivated) | — | — | + +> 缺口即文档第 3 节要解决的问题。注意:矩阵中「刷新其它缓存页签 ❌」对**类型①本页局部操作(如修改平台/快递)是期望行为**,不是缺口——订单各页签按状态互斥、行不重叠,其它页签不含这些行,跨页刷新既无意义又会打扰用户(见 §3.1)。 + +--- + +## 3. 问题拆解 + +在页面缓存前提下,“执行功能后自动刷新”包含四个相互独立的子问题,需分别对待: + +| 编号 | 子问题 | 场景示例 | 本质 | +|---|---|---|---| +| P0 | 缓存页**重新被激活**时不刷新 | 在其它菜单处理了订单 → 切回 `orderManagement`;或在本页 8 个页签间来回切换 | 组件没走 `mounted`,走了 `activated`;当前无 `onActivated` 刷新 | +| P1 | 某页签内操作只刷新自己,其它缓存页签不同步 | (仅当同一记录可能同时出现在两个页签时)A 页操作后切到 B 页仍是旧值 | 前提是两页列表**数据重叠**;待审核/待处理等按状态互斥的页签不存在此问题 → 先按 §3.1 判定是否为真的需要跨页的类型②操作 | +| P2 | **Layout 层全局宿主**(非缓存树内)执行操作,页面需要感知 | 全局悬浮「建单」在任意页签创建订单 | 组件树隔离,只能用跨组件通信(模块级单例) | +| P3 | **异步长任务**(打印/批量异步批处理/轮询)结束后才落库 | 打印成功、储位分配轮询结束 | 刷新时机在“任务终态”而非“提交成功” | +| P4 | 操作导致**数量变化**,顶部**角标**不同步 | 建单后待处理数 +N | 角标由容器 `index.vue` 管理,与子页签不在同层 | + +### 3.1 操作对列表的影响范围分类(决定要不要跨页刷新) + +> 审计补充(2026-09-05):不是所有操作都需要“跨页签同步”。先按“影响范围”分类,**默认只做本页局部刷新**;只有会影响“其它页签数据集成员资格 / 计数”的操作才打脏。订单各页签按状态互斥:待审核(`orderReviewOrder.list`)、待处理(`orderPendingOrder.list`)、待处理异常(`orderExpectionOrder.list`)、待出库(`orderOutboundOrder.list`)、配送(`orderDeliveryOrder.list`)各查各桶,同一订单只落在一个状态桶。 + +| 类型 | 特征 | 示例 | 建议 | +|---|---|---|---| +| ① 本页局部 | 只改当前列表行的字段值,不改成员资格 | 修改平台/快递(仅 `order.pendingOrder.updateOrderPlatform/Express`,改待处理订单平台字段值)、改留言、改地址/备注 | **只 `params.loadData()`(现状已满足),不打脏、不广播**;其它状态互斥页签不含这些行,无需且不应被刷新 | +| ② 成员迁移/新增 | 让数据“进入/离开/新建于”其它页签,或改变其角标计数 | 建单(新单落入待处理桶)、异常转待处理(`orderExpectionOrder.resolveException`,从异常桶移入待处理桶)、审核通过(审核桶→待处理桶)、库内拦截确定(状态迁移) | 只对“实际受影响的目标桶”打细粒度脏(如 `order.pending.list.changed`),对应页签激活时懒刷新 | +| ③ 不可枚举的外部变更 | 数据可能在别处被改动,来源无法枚举 | 其它端/其它菜单改数据 | 激活兜底(A-1/A-2 + 脏标记) | + +> 判定规则:若两个列表**按状态互斥**(同一条记录不可能同时出现在两页),则“改字段值”类操作(类型①)不需要跨页刷新——本页已最新,另一页根本不含该行;此时给另一页打脏反而会在用户切回时触发一次无意义刷新,**违反“其它页面不受影响”**。 + +--- + +## 4. 设计目标与约束 + +1. **“自动刷新”语义必须等于“点一次刷新按钮”**:复用 `loadData`,沿用当前筛选/分页,不跳页、不重置条件。 +2. **幂等与防抖**:同一时刻只允许一次在途请求(`loadData` 已有 loading 守卫;跨实例并发时需合并/节流)。 +3. **生命周期一致**:订阅生命周期跟随组件真实存活(`mounted`/`unmounted`),避免幽灵刷新与内存泄漏。 +4. **事件作用域化**:只刷新“关心该事件”的页面;不得因一次小操作让所有缓存页全部重拉(成本控制)。 +5. **不引入全局事件总线依赖**:沿用项目现有的“模块级单例 composable”轻量风格。 +6. **不改变缓存开关语义**:缓存关时(`pageCacheEnabled=false` / `tabCacheEnabled=false`)页面走 `mounted` 全量重建,本机制自动退化为“每次进入都拉取”,不应出现重复拉取或负作用。 + +### 4.1 影响面承诺:其余页面缓存“照旧” + +审计复核(2026-09-05):本方案对**未接入页面是零侵入**的,实施时必须守住以下约束: + +1. 新增的 `useRefreshBus` / 脏标记是**模块级惰性单例**:不订阅就不产生任何行为;不碰 `experimental` store 的缓存开关/容量,不改 `AppMain` keep-alive 的 include/key/config。 +2. 只在目标页面(如 `orderManagement` 各页签/容器)加 `onActivated`,属页面局部改动;`stockManagement`、`waveOrder` 等其它缓存容器与其子页签**不加任何钩子**,其缓存、激活、LRU 行为均不变。 +3. 不存在“对所有缓存页统一刷新”的代码路径:`activated` 与订阅都**按页声明**;同一 scope(如 `order.list.changed`)只有真正关心该数据域的页面才订阅。 +4. 缓存关闭分支(`tabCacheEnabled=false` / `pageCacheEnabled=false`)下这些钩子自然不触发,行为回到“每次进入全量拉取”,与改造前一致。 +5. 不加 `:key`、不改造 keep-alive 标签、不改路由 meta/`noCache`——避免任何破坏缓存实例复用/淘汰逻辑的改动。 + +--- + +## 5. 设计方案总览 + +把「操作后刷新」拆成两条互相补充的链路: + +``` +触发源(三选一) + ├─ 生命周期触发:缓存页再次被激活(activated) + ├─ 同页操作触发:本页签内弹窗/按钮提交成功 + └─ 跨页/全局操作触发:Layout 全局宿主、其它缓存页签、异步任务终态 + ↓ 通过「模块级事件(作用域化)」 +统一入口:pageRefresher.refresh(scope) + ↓ 命中「已订阅该 scope 的存活列表页」 +各自 loadData()(沿用当前筛选/分页,loading 幂等) +``` + +链路图: + +```mermaid +flowchart LR + A[功能执行成功] -->|同页操作| B[本页签 loadData] + A -->|全局宿主/其它页签/异步终态| C[触发 pageRefresher.emit scope] + C --> D{各缓存页签是否订阅该 scope} + D -->|是且存活| E[该页签 loadData] + D -->|否| F[忽略] + G[缓存页再次激活 activated] --> E +``` + +### 5.1 统一刷新抽象(约定层,先行的“软约定”) + +不急着造框架,先立规则,让各页面 `loadData` 满足: + +- **签名**:`refresh: () => Promise` +- **幂等**:函数体首行 `if (loading.value) return` +- **语义**:沿用当前 `pagination + buildWhere() + sort`(与刷新按钮一致) +- **可选**:返回 `Promise`,便于 `Promise.allSettled` 聚合与调用方 await + +> 现状子页签的 `loadData` 基本已满足,无需大改。 + +--- + +## 6. 分层方案 + +### 方案 A(P0 首选落地):两级「激活即刷新」(注意嵌套 keep-alive 语义) + +> ⚠️ 审计修订(2026-09-05):原稿“Tab 级与路由级都由 keep-alive 触发同一 activated、一套代码覆盖两种切回”——**不成立**。嵌套 keep-alive 不透传路由级 `activated`(见 §2.1.3),因此 `onActivated` 要分两级挂。 + +#### A-1 Tab 级(子页签自己挂,覆盖“容器内切回缓存 Tab”) + +```ts +// 在子页签(pendingOrder/reviewOrder/…)setup 内 +onMounted(() => { registerCreateOrderSuccess(refresh); refresh() }) +onActivated(() => { void maybeRefresh() }) // 新增:Tab 级再次被激活时刷新(脏标记见方案 B,无脏则不拉) +onUnmounted(() => { unregisterCreateOrderSuccess(refresh) }) +``` + +- 首次进入:`mounted` 先触发 `refresh()`(同步置 `loading=true` 后 await),keep-alive 直接子组件紧随的 `activated` 再次调用会被 loading 守卫拦下 → **不会双拉**。 +- 之后在容器内反复切 Tab:走 `activated` → 拉最新。 + +#### A-2 路由级(容器 `index.vue` 挂,覆盖“从其它菜单/页面切回本页”) + +只有 `AppMain` 路由级 keep-alive 的**直接子组件**(即 `orderManagement/index.vue`)才会收到路由级 `activated`: + +```ts +// orderManagement/index.vue +onActivated(() => { + // 转发给“当前激活页签”刷新;建议配合脏标记(无脏则不拉),避免每次返回都请求 + refreshActiveTab() +}) +``` + +容器拿到“激活页签刷新句柄”的方式(任选其一): + +1. 子页签把 `refresh` 注册进模块级“页签刷新注册表”(`Map`,`mounted` 注册 / `unmounted` 注销),容器遍历注册表刷新当前激活页签(其余缓存 Tab 等用户切到时由 A-1 自行刷新); +2. 或给 `` 加 ref + 子页签 `defineExpose({ refresh })`,容器直接调用。 + +**成本与取舍** + +- 优点:实现成本低、无需事件定义,天然覆盖“任何把数据改旧的外部路径”。 +- 缺点:纯“每次激活都拉”会产生冗余请求,且无法区分“本次激活是否真有数据变化”。 +- 优化:配合脏标记(懒刷新,见 §6)→ 无脏不拉,副作用最小;这也是满足“切其它页面零打扰 + 缓存正常”的推荐做法。 + +**适用**:P0 两种“切回”都希望看到最新数据的列表页/页签。 + +--- + +### 方案 B(P1/P2/P3 通用化):模块级「作用域事件」总线(轻量、无依赖) + +把 `useCreateOrderSession` 的“回调注册”机制**抽取成通用小工具**(仍走模块级单例 + Set,不引入 mitt)。 + +#### 6.1 新增通用 composable(建议路径 `src/composables/useRefreshBus.ts`) + +```ts +// 模块级单例状态(与 useCreateOrderSession 同风格) +type RefreshHandler = () => void | Promise + +const scopedListeners = new Map>() + +function ensureScope(scope: string) { + if (!scopedListeners.has(scope)) scopedListeners.set(scope, new Set()) + return scopedListeners.get(scope)! +} + +export function useRefreshBus() { + /** 列表页挂载时订阅:只关心该 scope 的刷新事件 */ + function registerRefresh(scope: string, handler: RefreshHandler) { + ensureScope(scope).add(handler) + return () => unregisterRefresh(scope, handler) + } + function unregisterRefresh(scope: string, handler: RefreshHandler) { + scopedListeners.get(scope)?.delete(handler) + } + /** 操作成功后广播:通知所有订阅了该 scope 的存活列表页刷新 */ + async function notifyRefresh(scope: string) { + const handlers = scopedListeners.get(scope) + if (!handlers?.size) return + await Promise.allSettled(Array.from(handlers).map((h) => h())) + } + return { registerRefresh, unregisterRefresh, notifyRefresh } +} +``` + +#### 6.1.1 推荐增强:脏标记(懒刷新变体) + +> 审计修订(2026-09-05):为同时满足“操作后能拿到最新”与“切到无关页面零打扰 / 不产生冗余请求”,推荐用 **markDirty → 激活时懒刷新** 代替“每次激活都拉 / 每次操作都广播”。 + +##### 简单版(boolean,仅单个订阅者 / 不关心互相覆盖时可接受) + +```ts +const dirtyScopes = new Set() +function markDirty(scope: string) { dirtyScopes.add(scope) } +function isScopeDirty(scope: string) { return dirtyScopes.has(scope) } +function consumeDirty(scope: string) { return dirtyScopes.delete(scope) } +``` + +> ⚠️ boolean 版缺陷(审计发现):多个缓存页签订阅**同一 scope** 时,“谁激活谁 consume”会清掉脏标记,导致**后激活的页签漏刷**。例:在 `pendingOrder` 修改平台后切到 `reviewOrder`(refresh + consume),但 `exceptionOrder` 里也有同单数据、从未刷过——脏标记已被消费,切到它时不刷新、显示旧数据。 + +##### 推荐版(epoch 水位,多订阅者各自独立判断,审计建议采用) + +```ts +// 全局(模块级):scope -> 单调递增的变更序号 +const dirtyEpoch = new Map() +let epochSeq = 0 + +function markDirty(scope: string) { + epochSeq += 1 + dirtyEpoch.set(scope, epochSeq) +} +function getDirtyEpoch(scope: string) { return dirtyEpoch.get(scope) ?? 0 } +``` + +- 操作方:`markDirty('order.list.changed')`——只递增序号,不做任何通知; +- 订阅方(每个缓存页/页签各自持有 `lastSeenEpoch = ref(0)`),在 `activated` 时: + +```ts +onActivated(() => { + const cur = getDirtyEpoch('order.list.changed') // 无脏返回 0 + if (cur > lastSeenEpoch.value) { // 本页上次刷新之后确实发生过变更 + lastSeenEpoch.value = cur // 先追平水位再拉,防重复 + void refresh() + } +}) +``` + +- 各订阅者独立比较自己的 `lastSeen` 与全局 `epoch`:A 刷新不影响 B 的判断,**无漏刷、无错刷**; +- 页面被 LRU 淘汰后重建(`mounted`)→ `lastSeen=0` + 全量拉取,天然正确; +- “本页自己刚执行操作并已原地刷新”:操作方本页在 `refresh()` 后把自己的 `lastSeen` 同步到当前 epoch,之后切走再切回不会重复拉。 + +两种广播语义任选(或组合): + +| 语义 | 触发 | 效果 | 取舍 | +|---|---|---|---| +| **eager(主动广播)** | 操作成功即 `notifyRefresh(scope)` | 所有存活订阅页**立即**刷新 | 反应最快;会让订阅页**并发重拉**(订单列表是大请求);切其它页时若页面正处理中也会被打扰 | +| **lazy(脏标记 + 激活时刷新)** | 操作成功只 `markDirty(scope)`(epoch 递增);各页在**被激活**(切回)时 `epoch > lastSeen` → `refresh()` → 水位追平 | 只有用户“实际去看”的页才拉,且每页各自判断、无漏刷 | 无冗余请求、副作用最小;缺点是被激活页看到的不是操作当刻、而是切回当刻的最新(通常可接受) | + +> 推荐:默认 lazy(符合“切到 waveOrder 不被触发”的诉求);仅当产品明确要求“操作当下其它页必须立即同步”时才对该 scope 用 eager。 + +**作用域(scope)设计建议**: + +- 按“业务数据域”命名,例如 `stock.list.changed`、`wave.list.changed`。 +- **订单管理各页签按状态互斥、行不重叠 → 不要用粗 scope `order.list.changed`**(改平台后会给不含这些行的待审核页签也打脏,切回时被无意义刷新)。改用“目标数据集”粒度,如 `order.pending.list.changed` / `order.review.list.changed` / `order.exception.list.changed`,只被对应桶的页签订阅;操作方标记“它实际改变的桶”。 +- 可再加仓库维度 `order.pending.list.changed:{warehouseId?}`(可选,默认全局)以便同仓库才刷新。 +- 订阅方决定是否关心;广播方不需要知道“谁在听”。 + +#### 6.2 列表页侧(订阅方)统一写法 + +```ts +const refreshBus = useRefreshBus() +onMounted(() => { + const off = refreshBus.registerRefresh('order.list.changed', refresh) // scope 由页面自己声明关心 + // 与既有 useOrderListPageCleanup 等叠加 + refresh() +}) +onUnmounted(() => { off() }) // 或直接 unregisterRefresh +``` + +> 生命周期挂 `mounted/unmounted`(与 `useCreateOrderSession` 一致):缓存的隐藏页签依然订阅并能被动刷新;被 LRU 淘汰后自动注销。 + +#### 6.3 操作侧(广播方)统一写法 + +- 同页弹窗操作成功后,除保留“原地 `loadData`”外,若该改动**会影响其它页签/其它页面**,按所选语义追加: + +```ts +await params.loadData() // 当前页签先刷新(现状已如此,必留) +// 懒刷新(推荐):只打脏标记,其它缓存页在切回时自己刷 +markDirty('order.list.changed') +// 或 eager(不推荐默认):让其它存活列表页立即同步 +// notifyRefresh('order.list.changed') +``` + +- 全局宿主(Layout 层)操作,如建单弹窗:把 `void notifyCreateOrderSuccess()` 等价替换为 `void markDirty('order.list.changed')`(若沿用建单即时多页签刷新体验,可保留一次 `notifyRefresh('order.list.changed')`);可选新增子 scope(`order.list.changed.pending`)缩小影响面。 + +**副作用隔离规则(满足“切到其它页面不触发其它操作”)** + +- 订阅方 = “数据真的会变”的页面自己决定是否订阅某 scope;广播方不需要知道谁在听。 +- **只让相关页面订阅**:`order.list.changed` 只应被订单列表类页面(如订单管理各页签)订阅;`order/waveOrder` 的波次/拣货/回落单面板展示的是波次与拣货任务数据,**不受“修改平台”影响,一律不订阅**(现状亦未订阅,保持即可)。 +- `activated` 只在“回到被缓存的本页/页签”时触发:停留在 `waveOrder`、或切去 `waveOrder` 的那一刻,订单页不会触发任何刷新动作。 +- lazy 语义下,即便 scope 已脏,只要用户不去那个页面,就不会产生请求。 + +**成本与取舍** + +- 优点:精确、可控;可承载“异步任务终态再广播”的场景(P3);可扩展携带数据(例如 `{ orderIds }`,订阅方决定是否需要局部更新)。 +- 缺点:需要人工维护 scope 与订阅点;广播范围过宽会引发多列表并发请求。 + +#### 6.4 关键场景映射 + +| 场景 | 触发时机 | 建议 | +|---|---|---| +| P1 修改平台/快递(类型①:本页局部值变更) | `submitUpdateOrderMeta` 成功后 | **只原地 `loadData`**(现状即可,不打脏/不广播);其它状态互斥页签不含这些行、不受影响 | +| P2 建单/状态迁移(类型②:改变其它页签成员资格/计数) | 建单成功 / `resolveException` / 审核通过等 | 按“实际受影响的目标桶”打细粒度 dirty(如 `order.pending.list.changed`),对应页签激活时懒刷新 | +| P3 打印成功 | 打印 composable `onPrintSuccess` | 原地 `loadData` +(如影响它桶)`markDirty` | +| P3 异步批处理/储位分配轮询终态 | 轮询 `success` | 原地 `loadData`(必要时 `markDirty`) | + +--- + +### 方案 C(规模化沉淀,可选后续):统一列表 Composable + +若页面数量多、希望“开箱即得”,可再包一层列表组合式封装,把 A+B 收敛: + +```ts +// useCachedListPage(options) +// options: { scope?: string[]; loader: () => Promise; registerExtra?: (refresh)=>(()=>void) } +// 内部自动: +// onMounted: refresh() + 订阅各 scope + 返回卸载 +// onActivated: refresh()(方案A) +// 幂等 refresh(loading 守卫) +``` + +价值:新页面一行接入缓存感知的刷新;旧页面可渐进迁移。 +代价:侵入现有页面结构较大,建议二期再做,先以方案 A + B 的“软约定”落地。 + +--- + +## 7. 决策矩阵 + +| 场景 | 建议方案 | 理由 | +|---|---|---| +| 回到本菜单/切回缓存 Tab 要最新 | 方案 A 两级激活 + 脏标记 lazy | 路由级返回需容器转发(嵌套 keep-alive 不透传 `activated`);lazy 避免无关切换也拉一次 | +| 操作只改本列表值(类型①,如修改平台) | 无需新机制(现状本地 `loadData` 已够) | 各页签按状态互斥;其它页不含该行,跨页刷新会违背“其它页面不受影响” | +| 操作会改变其它页签数据集/计数(类型②,如建单/状态迁移) | B lazy(细粒度 scope `markDirty` + 激活时刷新) | 只对实际受影响的目标桶打脏,避免并发重拉 | +| 全局宿主(Layout 层)操作 | B lazy(全局宿主不属于缓存树,只能跨组件通信) | 与 `useCreateOrderSession` 一致 | +| 切到无关页面(如 waveOrder)不被触发 | 订阅方按数据域隔离 scope + lazy | waveOrder 不订阅 `order.list.changed`;激活只在返回本页发生 | +| 异步长任务终态 | B lazy(终态回调里 `markDirty`)+ 原地刷新 | 刷新时机在终态;eager 仅当要求操作当下立即同步 | +| 角标/数量 | 容器层订阅同 scope(`loadBadgeCounts` 进回调) | 角标在 `index.vue`,非子页签 | +| 数据变更来源不可枚举的页面 | A 即可 | 不必造事件 | + +--- + +## 8. 落地示例(order/orderManagement) + +### 8.1 建单(现状已实现,保留并可作为“标准范式”) + +- 已具备:模块级 `useCreateOrderSession` + `mounted/unmounted` 订阅 + `notifyCreateOrderSuccess`。 +- 建议演进: + 1. 将回调注册语义泛化为 `registerRefresh('order.list.changed', refresh)`(内部仍走同一模块级单例,兼容旧接口或渐进替换)。 + 2. 建单成功后补一次 `loadBadgeCounts()` 通知(解决 P4:待处理/待审核角标数量)。 + +### 8.2 修改平台 / 修改快递(类型①:本页局部,默认不跨页) + +- 现状:`submitUpdateOrderMeta` 成功后已 `params.loadData()` → **只有当前页签(如待处理订单)触发刷新,待审核订单等其它页签不受影响**——正是需求行为,**无需任何改动**。 +- 原因:待审核/待处理/异常/待出库等页签是**按订单状态互斥**的列表(各自查 `orderReviewOrder.list` / `orderPendingOrder.list` / `orderExpectionOrder.list`…),同一订单只落在一个状态桶;修改平台只改本桶内行的字段值、不改变成员资格 → 其它页签不含这些行,跨页刷新既无意义又打扰用户。 +- 结论:此类操作**不打脏、不广播**,保持“只刷新本页”。若将来确认确有“同单跨页展示”的桶重叠,再按重叠桶打细粒度 dirty。 + +### 8.3 其余 toolbar 动作(executeApiAction 等) + +- 已在 `reload` 后集中处理当前页;**不要在 `executeApiAction` 末尾统一打脏**——多数批量动作是类型①(本页字段值),统一打脏会波及其它互斥页签。 +- 逐项按 §3.1 分类:类型①保持本地刷新(现状即可);只有类型②(会改变其它页签成员资格/计数,如异常转待处理、库内拦截确定等状态迁移)才对受影响的目标桶打细粒度 dirty。 + +### 8.4 `onActivated` 刷新(两级挂载,配合脏标记) + +- Tab 级(A-1):对 8 个列表页签补充 `onActivated(() => maybeRefresh())`(脏才刷),与现有 `onMounted` 注册并存,loading 幂等防双拉。 +- 路由级(A-2):`index.vue` 补充 `onActivated(() => refreshActiveTab())`(向当前激活页签转发),覆盖“从 waveOrder 等其它页面切回本页”。**仅靠子页签的 `onActivated` 覆盖不了路由级返回**。 + +### 8.5 角标(P4) + +- `index.vue` 的 `loadBadgeCounts()` 除现有「挂载/切 Tab」外,订阅 `order.list.changed` 广播,在建单/异常处理等导致数量变化的操作后同步刷新角标(带已有 `badgeLoading` 去重)。 + +--- + +## 9. 关键细节与坑(务必遵守) + +1. **双拉问题**:首次进入时 `mounted + activated` 都会触发;靠 `loadData` 的 `if (loading.value) return` 去重即可,不要在 `onActivated` 里额外做“跳过首次”标记(切回场景仍需刷新)。若担心竞态(极快返回后 activated 再拉一次),可记录 `lastActivatedAt`,同一 tick 内去重(可选优化)。 +2. **刷新语义 = 刷新按钮**:自动刷新必须沿用当前筛选/分页;若改成“重置到第一页”会与用户当前查看上下文冲突。 +3. **订阅生命周期绑 `mounted/unmounted`**,不要绑 `activated/deactivated`:否则隐藏缓存页会漏刷新、且语义混乱。 +4. **作用域按“目标数据集”粒度,不要跨状态桶**:订单各页签按状态互斥,不要用 `order.list.changed` 这种跨桶 scope——一次打脏会让所有订阅订单页签在切回时被刷(大请求且大多无变化)。用 `order.pending.list.changed` / `order.review.list.changed` 等,只被对应桶订阅。 +5. **LRU 淘汰**:`tabCacheMax=2` 时,隐藏且久未使用的页签会被销毁(走 `onUnmounted` 自动注销),不会幽灵刷新;这是机制能自洽的关键,注销代码务必补全。 +6. **异步任务**:不要在“提交成功”就刷新,要在任务轮询到终态(success/failed)时刷新;现有 `submitStorageAllocate`、`useTaskProgress` 轮询结构可复用。 +7. **打印/导出等非列表动作**:仅 `onPrintSuccess` 需要刷新;导出进度类动作不得误触发广播。 +8. **重复广播**:同页操作成功后“原地 loadData + 广播”时,广播回调会命中自己 → 被 loading 守卫拦截,不会二次请求;确保 `loadData` 幂等即可放心广播。 +9. **角标刷新频控**:角标接口频率敏感,广播回调里合并/节流(复用 `badgeLoading` 去重)。 +10. **缓存关闭时**:`pageCacheEnabled=false / tabCacheEnabled=false` 时组件每次进入都 `mounted`,自动刷新天然发生;`onActivated` 不会重复触发(无 keep-alive 时不触发 activated),广播仍安全(`unmounted` 即注销)。 +11. **嵌套 keep-alive 不透传 activated**:路由级返回时子页签不会自动收到激活;必须由容器(`index.vue`)的 `onActivated` 显式转发,否则只加 Tab 级 `onActivated` 时“从 waveOrder 切回本页”不会刷新。 +12. **scope 隔离是“切其它页面零打扰”的前提**:只让真正相关页面订阅;如 waveOrder 的波次/拣货面板与 `order.list.changed` 无关,一律不订阅,修改平台广播/脏标记就不会波及它们。 +13. **同一 scope 多订阅者时不要用“全局 boolean 脏标记 + consume”**:会互相覆盖导致后激活页签漏刷;改用 epoch 水位,每订阅者记录自己的 `lastSeen` 各自判断。 +14. **默认局部刷新,跨页同步是例外而非默认**:修改平台等“只改本列表值”的操作不要打脏/广播——其它状态互斥页签不含这些行,切回时触发刷新反而违背“其它页面不受影响”;只有会改变其它页签成员资格/计数的类型②操作(建单、状态迁移)才对受影响目标桶打脏。 + +--- + +## 10. 分阶段实施建议 + +| 阶段 | 内容 | 覆盖问题 | 风险 | +|---|---|---|---| +| 一期(推荐先做,改动小) | ① 子页签补 `onActivated`(Tab 级,A-1);② `index.vue` 补 `onActivated` 转发当前激活页签(路由级,A-2);③ 结合脏标记 lazy 防冗余 | P0 | 低 | +| 一期 | 类型①操作(修改平台/快递等)保持现状“仅本页刷新”,不改代码;仅类型②(建单/状态迁移)对受影响目标桶打细粒度 dirty | P1 | 低 | +| 二期 | 抽取通用 `useRefreshBus`(方案 B),把建单 bus 迁移/兼容到通用层 | P2/P3 | 中(需回归建单链路) | +| 二期 | 角标订阅广播(P4) | P4 | 低 | +| 三期(可选) | 沉淀 `useCachedListPage`(方案 C),新页面开箱即用 | 规模化 | 高(侵入式,谨慎) | + +--- + +## 11. 验收清单(order/orderManagement 样例) + +- [ ] 在「待审核/待处理/异常」页签建单成功 → 列表自动刷新且保留筛选条件,无重复请求(Network 中同参数仅一次在途)。 +- [ ] 打开待审核 + 待处理两页签,在待处理「修改平台」成功后:**仅待处理页签刷新**;待审核页签不刷新、无任何新请求、数据不受影响。 +- [ ] 状态互斥验证:修改平台/快递不改成员资格,其它状态桶列表不含该行;对确需跨桶的操作(建单/异常转待处理等)按 §3.1 判定后仅对目标桶懒刷新。 +- [ ] 切走菜单再切回 `orderManagement`、或页签间来回切换 → 列表刷新为最新(路由级返回由容器 A-2 转发,Tab 内切换由子页签 A-1 覆盖)。 +- [ ] 停留/切到 `order/waveOrder` 期间:不产生任何由“修改平台/建单”触发的订单或波次列表请求;waveOrder 不被 `order.list.changed` 波及。 +- [ ] 建单/异常处理等导致数量变化的操作后,顶部页签角标同步刷新。 +- [ ] 打开 ≥3 个页签触发 LRU 淘汰后,被淘汰页签重建时数据正确且无残留回调/幽灵请求。 +- [ ] 关闭「页面缓存/Tab 缓存」实验性开关后功能正常,无重复拉取。 +- [ ] 刷新中快速切页签、快速重复点按钮:无并发重复请求、无 loading 卡死。 + +--- + +## 附:相关代码位置速查 + +| 位置 | 说明 | +|---|---| +| `src/layout/component/AppMain.vue` | 路由级 keep-alive + 组件包装 | +| `src/layout/index.vue` / `src/layout/component/CreateOrderSessionHost.vue` | 全局宿主(建单弹窗/悬浮)挂载点 | +| `src/views/order/orderManagement/index.vue` | 容器:Tab 级 keep-alive + 角标刷新 | +| `src/views/order/orderManagement/composables/useCreateOrderSession.ts` | 现有模块级回调总线(范式) | +| `src/views/order/orderManagement/{reviewOrder,pendingOrder,exceptionOrder}.vue` | 列表页:mounted 订阅 + loadData | +| `src/views/order/orderManagement/utils/toolbar-actions.ts` | 各操作成功后原地 loadData 的集中实现 | +| `src/views/order/orderManagement/component/CreatePendingOrderDialog.vue` | 建单成功 → notify 的触发点 | +| `src/components/UpperTable/index.vue` | 刷新按钮(emit refresh) | +| `src/stores/modules/experimental.ts` | 缓存开关/容量设置(tab 默认 max2、页面默认 max8) | +| `src/views/storage/entry/component/DirectInboundLogs.vue` | `onActivated` 刷新的既有先例 | diff --git a/src/api/order.wave/orderwave.ts b/src/api/order.wave/orderwave.ts index cda4d68b..71e9e48b 100644 --- a/src/api/order.wave/orderwave.ts +++ b/src/api/order.wave/orderwave.ts @@ -59,6 +59,8 @@ export type WavePickTaskListItem = { claim_operator?: string current_cart_id?: number | string current_cart_code_snapshot?: string + /** 拣货车名(如 "拣货车40",order.wave.wavePickTaskList 返回) */ + cart_name?: string device_id?: string start_at?: string start_time?: string diff --git a/src/views/Externalwarehouse/shipperSigning/index.vue b/src/views/Externalwarehouse/shipperSigning/index.vue index 20c96c9c..44bcb558 100644 --- a/src/views/Externalwarehouse/shipperSigning/index.vue +++ b/src/views/Externalwarehouse/shipperSigning/index.vue @@ -140,7 +140,7 @@ import { ref, reactive, onMounted } from 'vue' import { ElMessage } from 'element-plus' import { Search, Refresh } from '@element-plus/icons-vue' -import { storeWarehouseWarehouseList } from '@/api/storeWarehouse.warehouse/storeWarehouse' +import { storeWarehouseWarehouseList } from '@/api/storewarehouse.warehouse/storeWarehouse' import ScanBox from '@/components/ScanBox/index.vue' import UpperTable from '@/components/UpperTable/index.vue' diff --git a/src/views/express/returnReceived/index.vue b/src/views/express/returnReceived/index.vue index 8e77ae74..55aac05c 100644 --- a/src/views/express/returnReceived/index.vue +++ b/src/views/express/returnReceived/index.vue @@ -76,9 +76,9 @@ @sort-change="handleSortChange" > + diff --git a/src/views/express/waybill/config/components/DetailPanel.vue b/src/views/express/waybill/config/components/DetailPanel.vue index eb992d25..336a7826 100644 --- a/src/views/express/waybill/config/components/DetailPanel.vue +++ b/src/views/express/waybill/config/components/DetailPanel.vue @@ -21,9 +21,9 @@ >