docs: align shared-module comments with actual edge cases

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("登录响应无效，请重新登录；若持续失败，请联系客服。");