docs: annotate all shared frontend modules in Chinese

app/lib/useListPage.js

@@ -1,3 +1,7 @@
+/**
+ * 列表页面共用加载器：分页、同请求去重、身份隔离、缓存首屏与刷新失败保留旧结果。
+ * 缓存来自统一 auth 模块；旧查询/旧账号/已卸载组件的响应不能覆盖当前列表。
+ */
 import { onMounted } from "vue";
 import { watch } from "vue";
 import { onScopeDispose } from "vue";
@@ -8,6 +12,7 @@ import { useApi } from "~/lib/auth.js";
 import { writeApiCache } from "~/lib/auth.js";
 import { readApiCache } from "~/lib/auth.js";
 import { clearApiCache } from "~/lib/auth.js";
+/** u 为接口路径，d 可提供查询参数、外部 loader、行键和缓存命名空间等现有列表选项。 */
 function u(u, d = {}) {
   let f = useApi(),
     p =
@@ -26,6 +31,7 @@ function u(u, d = {}) {
     w = !0,
     T = !1,
     E = null;
+  // 身份变更或查询构造失败时统一作废在途序号，清理可见数据，防止跨账号残留。
   function D() {
     (S++,
       (h.value = []),
@@ -50,6 +56,7 @@ function u(u, d = {}) {
     onScopeDispose(() => {
       ((T = !0), S++, (E = null));
     }));
+  // 优先使用业务行键，否则使用 id；没有稳定键的行不做对象复用。
   function O(e) {
     if (d.rowKey) return d.rowKey(e);
     if (
@@ -60,6 +67,7 @@ function u(u, d = {}) {
     )
       return e.id;
   }
+  /** 构造查询快照、读取一次初始缓存，再发真实请求刷新；同参数同身份共享 Promise。 */
   function k() {
     if (T) return Promise.resolve();
     let e,
@@ -103,6 +111,7 @@ function u(u, d = {}) {
       try {
         let r = d.loader ? await d.loader(e) : await f.get(u, e);
         if (!o()) return;
+        // 复用同 id 的行对象以保留 UI 引用，但删除新响应已不存在的字段，避免旧值残留。
         let i = new Map(
           h.value.flatMap((e) => {
             let t = O(e);
@@ -133,6 +142,7 @@ function u(u, d = {}) {
               A,
             ));
       } catch (e) {
+        // 只有同一查询已拥有结果时才可保留旧列表；新筛选失败不能继续展示上一查询。
         if (!o()) return;
         ((v.value = e instanceof Error ? e.message : `加载失败`),
           (!m || !l) && ((h.value = []), (g.value = 0), (y.value = !1)));
@@ -151,6 +161,7 @@ function u(u, d = {}) {
       j
     );
   }
+  // PrimeVue 页码从 0 开始，后端接口从 1 开始；切筛选的 reload 则回到第一页。
   function A(e) {
     ((b.value = e.page + 1), (x.value = e.rows), k());
   }