docs: annotate all shared frontend modules in Chinese

app/lib/useCaptcha.js

@@ -1,3 +1,7 @@
+/**
+ * 登录/注册等场景的人机验证状态：先读站点开关，再识别图片或极验提供商。
+ * /captcha API 走统一后端 origin，但图片刷新 /captcha/tp_captcha/... 始终走前端同源反代。
+ */
 import { onMounted } from "vue";
 import { watch } from "vue";
 import { onScopeDispose } from "vue";
@@ -6,6 +10,7 @@ import { ApiError } from "~/lib/auth.js";
 import { useApi } from "~/lib/auth.js";
 import { t as useSiteConfig_t } from "~/lib/useSiteConfig.js";
 var s = (e) => e === !0 || e === 1 || e === `1`;
+// 登录可由全局开关或后端“失败三次后验证”状态开启，其他场景读取各自开关。
 function c(e, t) {
   return s(e?.[`captcha_client_${t}`])
     ? !0
@@ -13,6 +18,7 @@ function c(e, t) {
         s(e?.captcha_client_login_error) &&
         s(e?.captcha_client_login_error_3_times);
 }
+/** 只解析 HTML 中的提供商标识，不执行其中脚本；未知插件或异常极验 id 明确报错。 */
 function l(e) {
   if (typeof e != `string` || e.length > 262144) throw Error(`验证码响应无效`);
   let t = new DOMParser().parseFromString(e, `text/html`),
@@ -39,6 +45,7 @@ function l(e) {
     };
   throw Error(`当前验证码插件暂不受支持，请联系管理员`);
 }
+// 极验四个结果字段均需非空且有长度上限；真实挑战仍由服务端校验。
 function u(e) {
   if (!e || typeof e != `object`) return !1;
   let t = e;
@@ -47,6 +54,7 @@ function u(e) {
       typeof t[e] == `string` && t[e].trim().length > 0 && t[e].length <= 8192,
   );
 }
+/** d 为场景名；无场景时由调用方手动控制加载，组件销毁会取消请求并清空凭证。 */
 function d(d) {
   let f = useSiteConfig_t(),
     p = useApi(),
@@ -63,9 +71,11 @@ function d(d) {
     w = 0,
     T = null,
     E = !1;
+  // 每次加载或失效都清掉旧答案和 token，避免把不同验证码的结果混在一起提交。
   function D() {
     ((y.value = ``), (v.value = ``));
   }
+  // 序号 w 和销毁标记 C 防止旧响应回填；定时 AbortController 限制同源图片请求。
   async function O() {
     if (C || b.value) return;
     let e = ++w;
@@ -117,6 +127,7 @@ function d(d) {
       (clearTimeout(n), !C && e === w && (b.value = !1));
     }
   }
+  // 仅在当前确实需要极验且没有加载时接受完成结果，按后端约定序列化四个字段。
   function k(e) {
     (D(),
       !C &&
@@ -132,6 +143,7 @@ function d(d) {
         })),
         (v.value = e.lot_number)));
   }
+  // 提交前将“配置未加载”“正在加载”“未完成”等情况区分，空串才表示可继续。
   function A() {
     return S.value
       ? `验证码设置正在加载，请稍候`
@@ -153,6 +165,7 @@ function d(d) {
                   : `请先重新加载图形验证码`
           : ``;
   }
+  // 后端报错可临时强制开启验证码，刷新后再由页面让用户重试原动作，不自动重复登录。
   async function j(e) {
     let t = e instanceof ApiError && s(e.data?.captcha);
     return (t && ((E = !0), (m.value = !0)), m.value && (await O()), t);
@@ -178,6 +191,7 @@ function d(d) {
             f.config.value ||
               (x.value = `验证码设置加载失败，请刷新页面重试`)));
       })),
+    // 组件离开后即使不可取消的 API 请求返回，也不能继续写入当前验证码状态。
     onScopeDispose(() => {
       ((C = !0), (w += 1), T?.abort(), D());
     }),