docs: annotate payment, host operations and shared components

app/components/HostList.vue

@@ -1,4 +1,10 @@
 <script>
+/**
+ * 服务器列表的共享业务组件，供云服务器、独立服务器及动态后台菜单复用。
+ * modules/menuId 决定数据范围，title/tabs/tabParams 决定列表展示与筛选映射；
+ * 页面自身负责列表、按模块补充状态/流量、备注、批量电源操作及批量续费。
+ * 恢复后的短变量名仍与渲染树对应，修改时重点保持身份代次、分页快照及模块接口契约。
+ */
 import "~/assets/styles/PaymentDialog.BNFKQF1U.css";
 import "~/assets/styles/OsIcon.CAi4Iz2S.css";
 import "~/assets/styles/HostList.B3U15sJm.css";
@@ -72,6 +78,7 @@ import { n as renewal_quote_n } from "~/lib/renewal-quote.js";
 import { r as renewal_quote_r } from "~/lib/renewal-quote.js";
 import { t as renewal_quote_t } from "~/lib/renewal-quote.js";
 var T = new WeakMap();
+// 列表筛选快照按 auth 实例和菜单/模块分别保存；切换 token 时清空，避免串用账号状态。
 function We(e, t) {
   let n = T.get(e);
   if (!n) {
@@ -114,6 +121,7 @@ function We(e, t) {
   };
 }
 function Ge(e, t) {
+  // 机电状态查询器：每轮重建请求队列，最多三个并发，并用身份/版本/请求号拒绝过期响应。
   let n = ref({}),
     r = 0,
     i = !1,
@@ -132,6 +140,7 @@ function Ge(e, t) {
     (r++, (d = []), l.clear(), (n.value = {}));
   }
   function m(e) {
+    // 实例必须仍在当前列表且为 Active，才能将异步返回的电源状态写回。
     return (
       !i &&
       e.version === r &&
@@ -217,6 +226,7 @@ function Ge(e, t) {
     g();
   }
   function _(e) {
+    // 电源操作成功后优先刷新对应实例，并先显示 operating，不能假定指令已执行完成。
     if (i || t.loading.value || t.error.value) return;
     let a = new Set(e);
     d = d.filter((e) => !a.has(e.id));
@@ -294,12 +304,14 @@ for (let e of [
     actions: D,
   };
 function Ke(e) {
+  // 不同模块支持的批量动作不同；列表中的 re 前缀模块仍使用对应接口能力映射。
   return O[e] || O[`re${e}`];
 }
 function qe(e) {
   return typeof e == `string` ? O[e] : void 0;
 }
 function Je(e, t) {
+  // 每个请求 ID 必须恰好得到一项明确结果；缺失、重复或非 200 响应一律不能算成功。
   let n = Array.isArray(e) ? e : [];
   return t.map((e) => {
     let t = n.filter((t) => t && typeof t == `object` && Number(t.id) === e),
@@ -512,6 +524,7 @@ var Ye = {
           tabParams: {},
         },
         setup(c) {
+          // 共享列表适配器负责分页和缓存，本组件补充菜单字段配置及实例业务操作。
           let m = c,
             b = useApi(),
             w = useAuth(),
@@ -522,6 +535,7 @@ var Ye = {
             D = ref(null),
             O = 0;
           async function rn(e) {
+            // 异步返回的动态列只属于当前请求与当前账号，不能覆盖切换后的菜单字段。
             let t = ++O,
               n = w.token,
               r = await E(e);
@@ -554,6 +568,7 @@ var Ye = {
             );
           }
           function on(e, t) {
+            // 动态自定义列仅展示标量；密码字段始终遮盖，不因表格刷新而暴露原值。
             let n = e.self_defined_field?.[t.id];
             return n == null || n === ``
               ? `—`
@@ -675,6 +690,7 @@ var Ye = {
             wn = Cn.statusOf,
             Tn = T?.scrollY ?? null;
           function En() {
+            // 离开详情前保存筛选、分页及滚动位置；快照仅存在当前账号的内存中。
             Oe.save({
               tab: A.value,
               keywords: j.value,
@@ -742,6 +758,7 @@ var Ye = {
               },
             ));
           function Dn() {
+            // 业务操作后的强刷新同时失效列表、状态和流量补充数据，防止混合新旧快照。
             return (
               Cn.reset(),
               E.invalidate(!0),
@@ -800,6 +817,7 @@ var Ye = {
             );
           }
           async function Rn(e, t = !1) {
+            // 快快云流量单独取数：同一实例合并在途请求，以刷新版本阻止旧数据回写。
             if (
               e.module !== `kky_ecs` ||
               e.status === `Unpaid` ||
@@ -882,6 +900,8 @@ var Ye = {
               : n;
           }
           async function Bn(e) {
+            // 按实例真实模块补齐系统与流量信息；列表缺少 module 时先查询 host/view。
+            // 不同财务模块的配置结构并不相同，不能把此处接口路径直接统一成一种格式。
             let t = R;
             if (!(Fn.value[e.id]?.version === t || In.has(e.id))) {
               In.set(e.id, t);
@@ -962,6 +982,7 @@ var Ye = {
             }
           }
           async function Vn(e) {
+            // 附加数据按三路工作队列加载；翻页或卸载推进代次，不再继续启动旧队列任务。
             let t = ++Ln;
             if (dn.value) return;
             async function n(n) {
@@ -1009,6 +1030,7 @@ var Ye = {
             W.value || ((U.value = null), (G.value = ``));
           }
           async function qn() {
+            // 单条备注保存绑定提交时身份，成功后刷新列表，避免仅本地乐观更新留下旧缓存。
             let e = U.value;
             if (!e || W.value) return;
             let t = Wn.value,
@@ -1130,6 +1152,7 @@ var Ye = {
             Q.value || (er.value = null);
           }
           async function sr() {
+            // 批量备注要求成功/失败/总数与所选 ID 严格对齐，结果不完整时回读列表而不报全成功。
             let e = er.value;
             if (!e || Q.value || X || e.token !== w.token || e.epoch !== Y)
               return;
@@ -1225,6 +1248,8 @@ var Ye = {
             (cr(), vn(e));
           }
           async function hr() {
+            // 批量电源操作先逐台核对真实管理模块，再按接口分组提交，保留失败实例供重试。
+            // 请求过程绑定 token 与操作代次；“指令下发”不等于已开关机，完成后另刷电源状态。
             let e = J.value;
             if (
               !e ||
@@ -1333,6 +1358,7 @@ var Ye = {
             _r.value.filter((e) => e.renew_forbidden !== 1),
           );
           async function Dr() {
+            // 批量续费先取可用周期和报价，所选实例改变、弹窗关闭或卸载后放弃旧报价。
             if (xr.value || Tr) return;
             let e = ++wr,
               t = K.value.map((e) => e.id),
@@ -1385,6 +1411,7 @@ var Ye = {
             ),
             Ar = ref(null);
           async function jr() {
+            // 只提交允许续费的实例、周期及非空优惠码；未支付订单交给 PaymentDialog 接续处理。
             if (Er.value.length) {
               ((xr.value = !0), (Sr.value = ``), (Cr.value = ``));
               try {
@@ -1435,6 +1462,7 @@ var Ye = {
               e && Ar.value && (Pr.value = Ar.value.id);
             }),
             (e, r) => {
+              // 渲染区域依次包含筛选表格、备注/批量操作弹窗、续费报价及共用支付面板。
               let a = ListSegments,
                 s = inputtext,
                 u = button,