From deb7c3b3cd14c435459c61f52e3073cc8026d24d Mon Sep 17 00:00:00 2001
From: CieanYau <ltd@crash.work>
Date: Fri, 6 Nov 2026 00:43:00 +0800
Subject: [PATCH] docs: align shared-module comments with actual edge cases

---
 app/lib/auth.js                      | 7 ++++---
 app/lib/backend-menu.js              | 4 ++--
 app/lib/cart-edit.js                 | 2 +-
 app/lib/cloud-instance-management.js | 2 +-
 app/lib/complete-list.js             | 2 +-
 app/lib/content-route.js             | 2 +-
 app/lib/dict.js                      | 2 +-
 app/lib/instance-data.js             | 2 +-
 app/lib/instance-status.js           | 2 +-
 app/lib/product-fields.js            | 2 +-
 app/lib/server-page.js               | 6 +++---
 app/lib/storage-capacity.js          | 2 +-
 app/lib/useCaptcha.js                | 2 +-
 app/lib/useListPage.js               | 2 +-
 14 files changed, 20 insertions(+), 19 deletions(-)

diff --git a/app/lib/auth.js b/app/lib/auth.js
index ae48b73..381ff0b 100644
--- a/app/lib/auth.js
+++ b/app/lib/auth.js
@@ -1,7 +1,8 @@
 /**
  * 控制台统一请求与登录会话入口。
  * 页面通过 useApi 访问 /console/v1，通过 useAuth 共享登录状态；本模块只在客户端使用。
- * 后端业务成功必须同时满足 HTTP 成功和响应信封 status === 200，不能仅检查 HTTP 状态。
+ * 默认 JSON 请求须同时满足 HTTP 成功和信封 status === 200；显式兼容项可接受无 status 的 data 数组。
+ * 文件下载使用独立响应规则，不能把默认 JSON 信封要求直接套用于文件内容。
  */
 import CryptoJS from "crypto-js";
 import { defineStore } from "pinia";
@@ -71,7 +72,7 @@ function _e() {
 function ve() {
   return ge;
 }
-/** 按身份/命名空间、接口及参数生成稳定键；对象键排序避免同义参数重复缓存。 */
+/** 按接口、命名空间与参数生成稳定键；对象键排序，身份隔离由缓存读写单独处理。 */
 function ye(e, t, n = ``) {
   return JSON.stringify([e, n, t], (e, t) =>
     t && typeof t == `object` && !Array.isArray(t)
@@ -685,7 +686,7 @@ const useAuth = defineStore("auth", () => {
   let sessionVersion = 0;
   let legacySession = null;
 
-  // 仅在登录或服务端核验成功后调用；先清理上一会话的缓存与未完成旧平台登录。
+  // 接收登录、旧入口核验或跨标签同步的凭证；先清理旧缓存和未完成的旧平台登录。
   function loginWithJwt(jwt) {
     if (!ut(jwt))
       throw Error("登录响应无效，请重新登录；若持续失败，请联系客服。");
diff --git a/app/lib/backend-menu.js b/app/lib/backend-menu.js
index 0349f18..820f26a 100644
--- a/app/lib/backend-menu.js
+++ b/app/lib/backend-menu.js
@@ -41,7 +41,7 @@ function e(e) {
   }
   return r(e);
 }
-/** 路径长度和匹配 query 数量决定激活优先级，避免父菜单与更具体子菜单同时高亮。 */
+/** 路径长度和匹配 query 数量决定激活优先级，在传入候选项中优先匹配更具体的菜单。 */
 function t(e, t, n = []) {
   let r =
     t.path === `/products/cvm`
@@ -278,7 +278,7 @@ function d(e) {
   }
 }
 /**
- * 规范化后端菜单树：最多三层、每层最多 100 项，文本最多 100 字。
+ * 规范化后端菜单树：深度最多三层，每组同级菜单最多 100 项，标签截取前 100 个字符。
  * 无法适配的菜单保留禁用原因而非猜测跳转；二次提醒 second_reminder 作为确认标记保留。
  */
 function f(e, t = ``, a = 0) {
diff --git a/app/lib/cart-edit.js b/app/lib/cart-edit.js
index 770133f..fc3eba0 100644
--- a/app/lib/cart-edit.js
+++ b/app/lib/cart-edit.js
@@ -76,7 +76,7 @@ async function l(e) {
   });
 }
 /**
- * 返回编辑保存函数：n 为 API 客户端，r 包含 position/item，u 回调检查报价是否仍有效。
+ * n 为 API 客户端，r 包含 position/item；返回函数的第二参 u 检查报价是否仍有效。
  * 保存前重取购物车并比较原始项，提交 expected_item 供后端进一步检测并发变更。
  */
 function u(n, r) {
diff --git a/app/lib/cloud-instance-management.js b/app/lib/cloud-instance-management.js
index 362e97b..465baa9 100644
--- a/app/lib/cloud-instance-management.js
+++ b/app/lib/cloud-instance-management.js
@@ -1,6 +1,6 @@
 /** 云实例管理表单的协议校验：防御报价、订单、NAT、VPC 和磁盘规格。 */
 var e = (e) => e === `mf_cloud` || e === `remf_cloud`;
-// 空对象表示没有防御选项；非空配置必须给出合法的 defence 列表及当前防御值。
+// 空对象表示没有防御选项；非空配置须有合法 defence 列表，当前防御值可缺省，非空时须合法。
 function t(e) {
   let t = () => {
     throw Error(`防御配置无效，请重试`);
diff --git a/app/lib/complete-list.js b/app/lib/complete-list.js
index 4b96e4f..bb36c25 100644
--- a/app/lib/complete-list.js
+++ b/app/lib/complete-list.js
@@ -1,6 +1,6 @@
 /**
  * 拉取完整关联列表：e(page, limit) 返回 {list, count?}，t 判断调用上下文是否仍有效。
- * 按正整数 id 去重；总数缺失时以不足一页结束，无新增项时拒绝，避免无限分页。
+ * 按正整数 id 去重；总数缺失时以不足一页结束，尚未满足结束条件却无新增项时拒绝。
  */
 async function e(e, t = () => !0) {
   let n = [],
diff --git a/app/lib/content-route.js b/app/lib/content-route.js
index c5dda64..841aee2 100644
--- a/app/lib/content-route.js
+++ b/app/lib/content-route.js
@@ -8,7 +8,7 @@ function e(e) {
 function t(e) {
   return e === `help` || e === `news` || e === `notices` ? e : null;
 }
-// 通过后端启用的插件记录确定类型；未知/停用插件不生成内容路由。
+// 通过插件记录确定类型；兼容缺省 status，明确停用或未知类型的插件不生成内容路由。
 function n(t, n) {
   let r = e(t);
   return r
diff --git a/app/lib/dict.js b/app/lib/dict.js
index ff99d2b..29c22ed 100644
--- a/app/lib/dict.js
+++ b/app/lib/dict.js
@@ -80,7 +80,7 @@ var t = {
 function a(e) {
   return i[e] ?? e;
 }
-// 订单优先展示脱敏后的商品名列表，缺失时回落到订单名称/描述。
+// 订单优先展示移除内部 -L 后缀的商品名列表，缺失时回落到订单名称/描述。
 function o(t) {
   let n = t.product_names;
   if (Array.isArray(n)) {
diff --git a/app/lib/instance-data.js b/app/lib/instance-data.js
index 8458b55..702d1dc 100644
--- a/app/lib/instance-data.js
+++ b/app/lib/instance-data.js
@@ -1,4 +1,4 @@
-/** 多供应商实例数据展示适配；缺失/无效数值用 null 表示，避免误显示为有效的 0。 */
+/** 多供应商实例数据展示适配；基础数值以 null 区分缺值与 0，具体输出再按展示协议归一。 */
 function e(e) {
   if (e == null || e === ``) return null;
   let t = Number(e);
diff --git a/app/lib/instance-status.js b/app/lib/instance-status.js
index 34c8109..6a6e65d 100644
--- a/app/lib/instance-status.js
+++ b/app/lib/instance-status.js
@@ -15,7 +15,7 @@ function e(e, t) {
         }[e.suspend_type || ``] ||
         `暂停原因暂未提供，请联系支持`;
 }
-// 业务状态优先于电源状态；只有 Active 实例才显示运行/关机等即时状态。
+// 明确的非 Active 业务状态优先；Active 或未提供业务状态时才读取运行/关机等即时状态。
 function t(e, t = `Active`, n = !1) {
   let r = {
     Unpaid: `未付款`,
diff --git a/app/lib/product-fields.js b/app/lib/product-fields.js
index 7d2ff17..893ee53 100644
--- a/app/lib/product-fields.js
+++ b/app/lib/product-fields.js
@@ -195,7 +195,7 @@ function o(e) {
     e.filter((e) => e.kind !== `explain`).map((e) => [e.id, (e.kind, ``)]),
   );
 }
-/** 逐字段检查必填、选项值和可本地执行的正则；布尔字段按后端约定归一为 "1"/空串。 */
+/** 检查必填、选项和可本地执行的正则；校验时将布尔值视为 "1"/空串，不修改传入表单。 */
 function s(e, t) {
   for (let n of e) {
     if (n.kind === `explain`) continue;
diff --git a/app/lib/server-page.js b/app/lib/server-page.js
index 51ab295..5296023 100644
--- a/app/lib/server-page.js
+++ b/app/lib/server-page.js
@@ -1,5 +1,5 @@
 /**
- * 服务器列表分类适配：优先使用后端 classified-v1 分页，旧协议才完整拉取后在前端分类。
+ * 服务器列表分类适配：优先使用 classified-v1 分页；旧协议或跨页自然排序时完整拉取。
  * 分类结果和请求只在当前工厂实例内缓存，invalidate 作废在途结果对应的代次。
  */
 // 这些既有通用商品在当前业务中按独立服务器展示；变更须与商品配置约定一起核对。
@@ -76,7 +76,7 @@ function n(e, n, r) {
       l.get(a) === o && l.delete(a);
     }
   }
-  /** 旧协议完整加载列表并去重，最多四个并发详情请求补齐分类，再按目标模块筛选。 */
+  /** 完整加载列表并去重；旧协议的通用商品最多四个并发详情请求补齐分类，再按模块筛选。 */
   async function _(n, o, c) {
     let l = [],
       u = {},
@@ -223,7 +223,7 @@ function n(e, n, r) {
           Number(s.count) === s.list.length &&
           (a = s));
     }
-    // 老协议缓存最多四组筛选条件；加载中共用 Promise，失败移除，成功后才开始 30 秒 TTL。
+    // 全量结果最多缓存四组筛选条件；加载中共用 Promise，失败移除，成功后开始 30 秒 TTL。
     let s = Date.now();
     for (let [e, t] of u) t.expires <= s && u.delete(e);
     let c = u.get(r);
diff --git a/app/lib/storage-capacity.js b/app/lib/storage-capacity.js
index 8a09bcb..cef23b7 100644
--- a/app/lib/storage-capacity.js
+++ b/app/lib/storage-capacity.js
@@ -41,7 +41,7 @@ function d(e) {
     e
   );
 }
-// 仅清理区域文案中的“第一区/1区”等展示后缀，不改区域 id。
+// 清理区域文案中的“第一区/1区”等编号及冗余分隔，不改区域 id。
 function f(e) {
   let t = `(?:第\\s*)?(?:[一二三四五六七八九十百零〇两]+|[0-9０-９]+)\\s*区`;
   return e
diff --git a/app/lib/useCaptcha.js b/app/lib/useCaptcha.js
index aa15c33..41c0ca8 100644
--- a/app/lib/useCaptcha.js
+++ b/app/lib/useCaptcha.js
@@ -54,7 +54,7 @@ function u(e) {
       typeof t[e] == `string` && t[e].trim().length > 0 && t[e].length <= 8192,
   );
 }
-/** d 为场景名；无场景时由调用方手动控制加载，组件销毁会取消请求并清空凭证。 */
+/** d 为场景名；无场景时手动控制，销毁时中止图片请求、清空凭证并作废迟到的接口响应。 */
 function d(d) {
   let f = useSiteConfig_t(),
     p = useApi(),
diff --git a/app/lib/useListPage.js b/app/lib/useListPage.js
index 7679ad4..51cefbb 100644
--- a/app/lib/useListPage.js
+++ b/app/lib/useListPage.js
@@ -1,5 +1,5 @@
 /**
- * 列表页面共用加载器：分页、同请求去重、身份隔离、缓存首屏与刷新失败保留旧结果。
+ * 列表共用加载器：分页、同请求去重、身份隔离、初次加载回显缓存与刷新失败保留旧结果。
  * 缓存来自统一 auth 模块；旧查询/旧账号/已卸载组件的响应不能覆盖当前列表。
  */
 import { onMounted } from "vue";