# 授权单元与水印 **本文引用的文件** - [App.vue](file://ai-electron/frontend/src/App.vue) - [license.ts](file://ai-electron/frontend/src/core/utils/license.ts) - [login.ts](file://ai-electron/frontend/src/core/api/sys/login.ts) - [useWatermark.ts](file://ai-electron/frontend/src/core/hooks/web/useWatermark.ts) - [AuthorizationInfoModal.vue](file://ai-electron/frontend/src/core/layouts/default/setting/components/AuthorizationInfoModal.vue) - [authorization/index.vue](file://ai-electron/frontend/src/plat/views/authorization/index.vue) ## 目录 1. [引言](#引言) 2. [项目结构定位](#项目结构定位) 3. [核心组件总览](#核心组件总览) 4. [架构总览](#架构总览) 5. [详细组件分析](#详细组件分析) 6. [依赖关系分析](#依赖关系分析) 7. [新增授权字段、扩展水印内容与过期处理示例](#新增授权字段扩展水印内容与过期处理示例) 8. [性能与行为特性](#性能与行为特性) 9. [常见问题排查](#常见问题排查) 10. [结论](#结论) ## 引言 本文聚焦桌面客户端前端中“授权单元”和“页面水印”机制。重点说明: - `App.vue` 如何在应用启动后通过 `authorizationInfoApi` 获取服务端授权信息; - `license.ts` 中的 `extractAuthorizationCache` 如何解析 `authorizationLabel`、`overDateTime`、`authorizationUnit`,并写入用户页缓存; - `useWatermark.ts` 如何根据 `authorizationUnit` 动态设置或清除页面水印; - 授权缓存提取、过期判断、过期消息生成逻辑; - 与登录模块中 `checkAuthApi`、`authorizationInfoApi` 的关系; - 新增授权字段、扩展水印内容、处理授权过期的实践方式; - 常见故障场景及排查方法。 ## 项目结构定位 授权与水印相关代码集中在 Electron 桌面端的前端工程内: - 应用入口组件:`ai-electron/frontend/src/App.vue` - 授权工具函数:`ai-electron/frontend/src/core/utils/license.ts` - 登录与系统信息接口:`ai-electron/frontend/src/core/api/sys/login.ts` - 水印 Hook:`ai-electron/frontend/src/core/hooks/web/useWatermark.ts` - 授权信息弹窗:`ai-electron/frontend/src/core/layouts/default/setting/components/AuthorizationInfoModal.vue` - 授权管理页面:`ai-electron/frontend/src/plat/views/authorization/index.vue` ```mermaid graph TB App["App.vue
应用根组件"] --> LoginApi["login.ts
authorizationInfoApi / checkAuthApi"] App --> License["license.ts
extractAuthorizationCache"] App --> Watermark["useWatermark.ts
setWatermark / clear"] AuthorizationPage["authorization/index.vue
授权管理页"] --> LoginApi AuthorizationPage --> License AuthorizationModal["AuthorizationInfoModal.vue
授权信息弹窗"] --> LoginApi AuthorizationModal --> License ``` **图表来源** - [App.vue:1-85](file://ai-electron/frontend/src/App.vue#L1-L85) - [login.ts:1-152](file://ai-electron/frontend/src/core/api/sys/login.ts#L1-L152) - [license.ts:1-124](file://ai-electron/frontend/src/core/utils/license.ts#L1-L124) - [useWatermark.ts:1-205](file://ai-electron/frontend/src/core/hooks/web/useWatermark.ts#L1-L205) - [AuthorizationInfoModal.vue:158-390](file://ai-electron/frontend/src/core/layouts/default/setting/components/AuthorizationInfoModal.vue#L158-L390) - [authorization/index.vue:296-592](file://ai-electron/frontend/src/plat/views/authorization/index.vue#L296-L592) **章节来源** - [App.vue:1-85](file://ai-electron/frontend/src/App.vue#L1-L85) - [login.ts:1-152](file://ai-electron/frontend/src/core/api/sys/login.ts#L1-L152) - [license.ts:1-124](file://ai-electron/frontend/src/core/utils/license.ts#L1-L124) - [useWatermark.ts:1-205](file://ai-electron/frontend/src/core/hooks/web/useWatermark.ts#L1-L205) ## 核心组件总览 | 组件 | 职责 | 关键输出/副作用 | |---|---|---| | `App.vue` | 应用初始化时拉取授权信息,监听授权单元变化,驱动水印显示 | 调用 `authorizationInfoApi`、写入 `userStore` 的 `authorizationUnit`、调用 `setWatermark` 或 `clear` | | `license.ts` | 从任意结构的授权响应中提取授权标签、过期时间、授权单元,并提供过期判断和消息生成 | `extractAuthorizationCache`、`isAuthorizationExpired`、`getAuthorizationExpiredMessage`、`getAuthorizationLabel`、`isFormalAuthorization` | | `login.ts` | 定义与后端 `/sys/info`、`/sys/checkAuth` 等接口的请求封装 | `authorizationInfoApi`、`checkAuthApi`、`offlineAuthorizationApi` 等 | | `useWatermark.ts` | 在页面 DOM 上绘制可防篡改、自适应尺寸的水印层 | `setWatermark(str)`、`clear()`、`clearAll()` | | `AuthorizationInfoModal.vue` | 展示当前授权信息,计算是否正式授权、是否过期 | 使用 `extractAuthorizationCache`、`isAuthorizationExpired` | | `authorization/index.vue` | 授权管理主流程:加载授权信息、校验授权、更新授权、提示过期 | 同时使用 `checkAuthApi`、`authorizationInfoApi`、`isAuthorizationExpired`、`getAuthorizationExpiredMessage` | **章节来源** - [App.vue:1-85](file://ai-electron/frontend/src/App.vue#L1-L85) - [license.ts:1-124](file://ai-electron/frontend/src/core/utils/license.ts#L1-L124) - [login.ts:1-152](file://ai-electron/frontend/src/core/api/sys/login.ts#L1-L152) - [useWatermark.ts:1-205](file://ai-electron/frontend/src/core/hooks/web/useWatermark.ts#L1-L205) - [AuthorizationInfoModal.vue:158-390](file://ai-electron/frontend/src/core/layouts/default/setting/components/AuthorizationInfoModal.vue#L158-L390) - [authorization/index.vue:296-592](file://ai-electron/frontend/src/plat/views/authorization/index.vue#L296-L592) ## 架构总览 整体数据流分为两条主线: 1. **授权信息加载线**:`App.vue` → `authorizationInfoApi` → 后端 `/sys/info` → `extractAuthorizationCache` → `userStore` 页面缓存。 2. **水印渲染线**:`authorizationUnit` 变化 → `useWatermark.setWatermark` 或 `clear` → Canvas 生成背景图 → 注入全局水印节点。 ```mermaid sequenceDiagram participant App as "App.vue" participant Api as "login.ts authorizationInfoApi" participant Server as "后端 /sys/info" participant License as "license.ts extractAuthorizationCache" participant Store as "userStore 页面缓存" participant WM as "useWatermark.ts" App->>Api: "GET /sys/info" Api-->>App: "授权原始响应" App->>License: "extractAuthorizationCache(响应)" License-->>App: "{ authorizationLabel, overDateTime, authorizationUnit }" App->>Store: "写入 authorizationUnit" Store-->>App: "authorizationUnit 变化" App->>WM: "setWatermark(authorizationUnit) 或 clear()" WM-->>WM: "Canvas 生成水印背景并插入 DOM" ``` **图表来源** - [App.vue:40-75](file://ai-electron/frontend/src/App.vue#L40-L75) - [login.ts:110-120](file://ai-electron/frontend/src/core/api/sys/login.ts#L110-L120) - [license.ts:100-124](file://ai-electron/frontend/src/core/utils/license.ts#L100-L124) - [useWatermark.ts:120-205](file://ai-electron/frontend/src/core/hooks/web/useWatermark.ts#L120-L205) ## 详细组件分析 ### `App.vue`:授权信息加载与水印联动 `App.vue` 是授权单元与水标的协调者: - 从 `userStore` 读取 `authorizationUnit` 作为计算属性; - 如果授权单元为空,且服务器地址可用,则调用 `authorizationInfoApi`; - 将 `extractAuthorizationCache(res).authorizationUnit` 写回 `userStore.setPageCache('authorizationUnit', unit)`; - 监听 `authorizationUnit` 变化:非空时调用 `setWatermark(unit)`,为空时调用 `clear()`; - 请求失败时直接清理水印,避免残留旧水印。 ```mermaid flowchart TD Start["onMounted"] --> CheckUnit["检查 authorizationUnit 是否为空"] CheckUnit -->|不为空| WatchUnit["监听授权单元变化"] CheckUnit -->|为空| CheckServer["检查服务器地址是否可用"] CheckServer -->|不可用| Wait["等待网络就绪"] CheckServer -->|可用| CallApi["调用 authorizationInfoApi"] CallApi --> Parse["extractAuthorizationCache 解析"] Parse --> WriteStore["写入 userStore.authorizationUnit"] WriteStore --> WatchUnit CallApi --> Error["请求失败"] Error --> ClearWm["clear() 清除水印"] WatchUnit --> UnitEmpty{"authorizationUnit 是否为空"} UnitEmpty -->|是| ClearWm UnitEmpty -->|否| SetWm["setWatermark(authorizationUnit)"] ``` **图表来源** - [App.vue:40-75](file://ai-electron/frontend/src/App.vue#L40-L75) **章节来源** - [App.vue:1-85](file://ai-electron/frontend/src/App.vue#L1-L85) ### `license.ts`:授权缓存提取、过期判断与消息生成 `license.ts` 的核心目标是把后端返回的结构化或非结构化授权响应,统一成前端可用的三个字段: - `authorizationLabel`:授权标签,如“试用”或正式授权时的空字符串; - `overDateTime`:授权过期时间; - `authorizationUnit`:授权单元,用于水印展示。 #### 解析策略 `extractAuthorizationCache` 的处理顺序为: 1. 从 `source.data` 优先取值; 2. 若 `data` 中没有目标字段,则回退到顶层 `rawData`; 3. `overDateTime` 从 `overDateTime` 或 `overdatetime` 两个键中匹配; 4. `authorizationUnit` 从 `unit` 键取值; 5. `authorizationLabel` 优先从以下位置取值: - `rawData` 本身是字符串时,直接作为标签; - `data.authorizationLabel`、`data.authorizationStatus`、`data.authStatus`、`data.message`; - 最后回退到根据 `overDateTime` 计算的 `getAuthorizationLabel`。 #### 过期判断 - `getAuthorizationExpirationTime` 支持带时区的时间字符串、日期格式、以及包含时分秒的完整时间; - `isAuthorizationExpired` 比较过期时间与当前时间; - `isFormalAuthorization` 通过固定正式授权日期常量判断正式授权; - `getAuthorizationExpiredMessage` 根据是否存在规范化后的 `overDateTime` 生成中文提示。 ```mermaid flowchart TD Input["输入 source"] --> Resolve["resolveAuthorizationSource
分离 raw/rawData/data"] Resolve --> OverDateTime["读取 overDateTime
overDateTime / overdatetime"] Resolve --> Unit["读取 authorizationUnit
unit"] Resolve --> LabelFallback["读取 authorizationLabel
authorizationLabel / authorizationStatus / authStatus / message"] LabelFallback --> StringRaw{"rawData 是否为字符串"} StringRaw -->|是| UseString["直接使用 rawData 作为 label"] StringRaw -->|否| ComputeLabel["按 overDateTime 计算 label"] OverDateTime --> Expire["isAuthorizationExpired / getAuthorizationExpirationTime"] Unit --> Output["输出 { authorizationLabel, overDateTime, authorizationUnit }"] ComputeLabel --> Output UseString --> Output ``` **图表来源** - [license.ts:1-124](file://ai-electron/frontend/src/core/utils/license.ts#L1-L124) **章节来源** - [license.ts:1-124](file://ai-electron/frontend/src/core/utils/license.ts#L1-L124) ### `login.ts`:授权相关接口 `login.ts` 提供两类授权相关接口: - `authorizationInfoApi`:获取 `/sys/info`,用于展示授权信息和驱动水印; - `checkAuthApi`:获取 `/sys/checkAuth`,用于授权拦截判断。 两者都配置了 `errorMessageMode: 'none'`,表示错误不自动弹出默认错误提示,由调用方自行处理。`authorizationInfoApi` 还关闭响应转换,以便 `App.vue` 和授权模块能拿到原始结构,再由 `extractAuthorizationCache` 解析。 ```mermaid graph LR Client["前端业务组件"] --> AuthorizationInfo["authorizationInfoApi
/sys/info"] Client --> CheckAuth["checkAuthApi
/sys/checkAuth"] AuthorizationInfo --> RawResponse["原始 Result 响应"] CheckAuth --> AuthCheckResult["授权校验结果"] ``` **图表来源** - [login.ts:100-140](file://ai-electron/frontend/src/core/api/sys/login.ts#L100-L140) **章节来源** - [login.ts:1-152](file://ai-electron/frontend/src/core/api/sys/login.ts#L1-L152) ### `useWatermark.ts`:水印绘制与防篡改 `useWatermark` 是一个 Vue Hook,负责: - 使用 Canvas 将水印文本转为 Base64 背景图; - 在指定目标元素(默认 `document.body`)上插入一个绝对定位的水印层; - 使用 `MutationObserver` 监听 DOM 变更,防止控制台删除或修改水印; - 监听窗口尺寸变化,重新计算水印尺寸; - 提供 `setWatermark(str)`、`clear()`、`clearAll()` 三个对外方法。 关键行为: - `setWatermark` 会创建水印节点并注册 ResizeListener; - `clear` 会移除水印节点、断开观察者、移除监听; - `clearAll` 会清理所有已注册水印实例; - 当父容器被删除时,`MutationObserver` 会尝试恢复水印节点; - 当水印层样式被修改时,会重新执行 `setWatermark`,实现防篡改。 ```mermaid classDiagram class UseWatermark { +setWatermark(str) +clear() +clearAll() -createBase64(str, options) -resetWatermarkStyle(element, text, options) -updateWatermark(options) -createWatermark(str) } class MutationObserver { +observe(node, config) +disconnect() } class Canvas { +toDataURL(type) +fillText(text, x, y) } UseWatermark --> MutationObserver : "监听 DOM 变更" UseWatermark --> Canvas : "生成水印图片" ``` **图表来源** - [useWatermark.ts:1-205](file://ai-electron/frontend/src/core/hooks/web/useWatermark.ts#L1-L205) **章节来源** - [useWatermark.ts:1-205](file://ai-electron/frontend/src/core/hooks/web/useWatermark.ts#L1-L205) ### `AuthorizationInfoModal.vue` 与 `authorization/index.vue`:授权界面联动 这两个组件展示了授权能力在真实页面中的用法: - `AuthorizationInfoModal.vue` 调用 `authorizationInfoApi`,再用 `extractAuthorizationCache` 解析,并通过 `isAuthorizationExpired` 判断是否过期; - `authorization/index.vue` 同时使用 `checkAuthApi` 做授权拦截判断,并使用 `getAuthorizationExpiredMessage` 生成过期提示。 ```mermaid sequenceDiagram participant Modal as "AuthorizationInfoModal.vue" participant Page as "authorization/index.vue" participant Api as "login.ts" participant License as "license.ts" Modal->>Api: "authorizationInfoApi()" Api-->>Modal: "授权响应" Modal->>License: "extractAuthorizationCache / isAuthorizationExpired" Page->>Api: "checkAuthApi()" Page->>License: "isAuthorizationExpired / getAuthorizationExpiredMessage" ``` **图表来源** - [AuthorizationInfoModal.vue:158-390](file://ai-electron/frontend/src/core/layouts/default/setting/components/AuthorizationInfoModal.vue#L158-L390) - [authorization/index.vue:296-592](file://ai-electron/frontend/src/plat/views/authorization/index.vue#L296-L592) **章节来源** - [AuthorizationInfoModal.vue:158-390](file://ai-electron/frontend/src/core/layouts/default/setting/components/AuthorizationInfoModal.vue#L158-L390) - [authorization/index.vue:296-592](file://ai-electron/frontend/src/plat/views/authorization/index.vue#L296-L592) ## 依赖关系分析 授权与水印的依赖关系可以概括为: - `App.vue` 依赖 `login.ts` 的 `authorizationInfoApi`; - `App.vue` 依赖 `license.ts` 的 `extractAuthorizationCache`; - `App.vue` 依赖 `useWatermark.ts` 的 `setWatermark` 和 `clear`; - `authorization/index.vue` 和 `AuthorizationInfoModal.vue` 同时依赖 `login.ts` 和 `license.ts`; - `license.ts` 是纯工具模块,不依赖 UI 组件。 ```mermaid graph TB App["App.vue"] --> LoginApi["login.ts"] App --> License["license.ts"] App --> Watermark["useWatermark.ts"] AuthPage["authorization/index.vue"] --> LoginApi AuthPage --> License AuthModal["AuthorizationInfoModal.vue"] --> LoginApi AuthModal --> License ``` **图表来源** - [App.vue:1-85](file://ai-electron/frontend/src/App.vue#L1-L85) - [login.ts:1-152](file://ai-electron/frontend/src/core/api/sys/login.ts#L1-L152) - [license.ts:1-124](file://ai-electron/frontend/src/core/utils/license.ts#L1-L124) - [useWatermark.ts:1-205](file://ai-electron/frontend/src/core/hooks/web/useWatermark.ts#L1-L205) - [authorization/index.vue:296-592](file://ai-electron/frontend/src/plat/views/authorization/index.vue#L296-L592) - [AuthorizationInfoModal.vue:158-390](file://ai-electron/frontend/src/core/layouts/default/setting/components/AuthorizationInfoModal.vue#L158-L390) **章节来源** - [App.vue:1-85](file://ai-electron/frontend/src/App.vue#L1-L85) - [login.ts:1-152](file://ai-electron/frontend/src/core/api/sys/login.ts#L1-L152) - [license.ts:1-124](file://ai-electron/frontend/src/core/utils/license.ts#L1-L124) - [useWatermark.ts:1-205](file://ai-electron/frontend/src/core/hooks/web/useWatermark.ts#L1-L205) ## 新增授权字段、扩展水印内容与过期处理示例 ### 新增授权字段 假设后端在 `/sys/info` 返回的新字段名为 `enterpriseCode`,新增步骤如下: 1. 在 `license.ts` 的 `extractAuthorizationCache` 中增加对 `enterpriseCode` 的读取; 2. 如果字段可能出现在 `data` 或 `rawData`,复用现有 `getAuthorizationValue` 的容错逻辑; 3. 返回对象中增加该字段; 4. 在需要展示的企业编码位置(例如水印或授权弹窗)使用该字段; 5. 如果该字段影响授权状态,可在 `isAuthorizationExpired` 或新的状态函数中扩展判断。 参考路径: - [license.ts:100-124](file://ai-electron/frontend/src/core/utils/license.ts#L100-L124) ### 扩展水印内容 当前水印文字来自 `authorizationUnit`。如需同时显示企业编码或授权类型: 1. 在 `App.vue` 中组合新的水印文本,例如拼接 `authorizationUnit` 与新增字段; 2. 将新文本传给 `setWatermark(newText)`; 3. 如果水印字体、颜色、旋转角度需要调整,可基于 `useWatermark` 的选项类型扩展配置; 4. 注意保持水印文本简洁,避免 Canvas 绘制过大导致性能下降。 参考路径: - [App.vue:40-75](file://ai-electron/frontend/src/App.vue#L40-L75) - [useWatermark.ts:1-80](file://ai-electron/frontend/src/core/hooks/web/useWatermark.ts#L1-L80) ### 处理授权过期 当前过期逻辑主要由 `license.ts` 提供: - `isAuthorizationExpired` 用于判断是否过期; - `getAuthorizationExpiredMessage` 用于生成中文提示; - `authorization/index.vue` 在授权管理页中使用这两个函数; - `AuthorizationInfoModal.vue` 也使用 `isAuthorizationExpired` 展示过期状态。 建议扩展点: - 若需要更细粒度的过期控制,可在 `getAuthorizationExpirationTime` 中增加自定义规则; - 若需要在应用级拦截过期用户,可在路由守卫或全局初始化流程中调用 `checkAuthApi` 并结合 `isAuthorizationExpired` 做跳转或提示; - 不要仅依赖水印判断授权,因为水印只是展示层,真正权限判断应结合后端接口。 参考路径: - [license.ts:60-124](file://ai-electron/frontend/src/core/utils/license.ts#L60-L124) - [authorization/index.vue:584-592](file://ai-electron/frontend/src/plat/views/authorization/index.vue#L584-L592) - [AuthorizationInfoModal.vue:258-390](file://ai-electron/frontend/src/core/layouts/default/setting/components/AuthorizationInfoModal.vue#L258-L390) ## 性能与行为特性 - `useWatermark` 使用 Canvas 生成 Base64 背景图,适合短文本水印;长文本会增加绘图和内存开销; - 水印层使用绝对定位和较高 z-index,覆盖整个目标容器; - 通过 `MutationObserver` 监听 DOM 变更,存在一定监听成本,但用于防篡改是必要代价; - `App.vue` 仅在 `authorizationUnit` 为空时才请求授权信息,减少重复请求; - `authorizationInfoApi` 超时时间为 10 秒,避免长时间阻塞应用启动; - 授权信息接口禁用自动错误提示,便于上层统一处理; - 水印在组件卸载时会尝试清理,避免多实例残留。 [本节为通用行为说明,未直接分析具体代码片段] ## 常见问题排查 ### 授权信息未加载 **现象**:页面启动后没有水印,`userStore` 中也没有 `authorizationUnit`。 **可能原因**: - 服务器地址缺失或未配置,`isServerSetupMissing()` 或 `getApiOrigin()` 返回无效值; - `/sys/info` 接口返回空对象或结构不符合预期; - 网络请求失败,`catch` 分支调用了 `clear()` 清理水印; - 后端返回的 `unit`、`overDateTime`、`authorizationLabel` 字段名不一致。 **排查步骤**: 1. 检查网络请求是否成功访问 `/sys/info`; 2. 打印 `authorizationInfoApi` 返回的原始响应; 3. 确认后端返回结构中是否存在 `data.unit`、`data.overDateTime`、`data.authorizationLabel` 或其兼容键; 4. 检查 `App.vue` 中 `ensureAuthorizationUnit` 是否进入 try 分支; 5. 检查 `license.ts` 的 `extractAuthorizationCache` 是否能正确解析返回值。 参考路径: - [App.vue:40-75](file://ai-electron/frontend/src/App.vue#L40-L75) - [login.ts:110-120](file://ai-electron/frontend/src/core/api/sys/login.ts#L110-L120) - [license.ts:100-124](file://ai-electron/frontend/src/core/utils/license.ts#L100-L124) ### 水印不显示 **现象**:授权单元已有值,但页面没有水印。 **可能原因**: - `authorizationUnit` 为空字符串或空白字符; - `setWatermark` 没有被调用; - 目标容器不存在或已被销毁; - 水印层被其他样式覆盖或被手动删除; - `useWatermark` 的 MutationObserver 被异常中断。 **排查步骤** 1. 检查 `userStore.getPageCacheByKey('authorizationUnit')` 的值; 2. 在 `watch(authorizationUnit)` 中添加日志,确认是否触发 `setWatermark` 或 `clear`; 3. 打开浏览器开发者工具,查看是否存在带水印类名的 DOM 节点; 4. 检查是否有第三方样式覆盖了 z-index 或 visibility; 5. 检查控制台是否出现 MutationObserver 相关错误。 参考路径: - [App.vue:60-75](file://ai-electron/frontend/src/App.vue#L60-L75) - [useWatermark.ts:1-205](file://ai-electron/frontend/src/core/hooks/web/useWatermark.ts#L1-L205) ### 授权过期仍可使用 **现象**:`overDateTime` 已过期,但用户仍可继续使用。 **重要区分**: - 水印只是展示层,不能代替权限校验; - 真正的授权拦截应使用 `checkAuthApi` 与 `isAuthorizationExpired`; - `authorization/index.vue` 明确说明其判定方式与合并前一致,即 `checkAuthApi()` + `isAuthorizationExpired()`。 **排查步骤** 1. 确认过期判断使用的是 `isAuthorizationExpired`; 2. 检查是否只依赖水印或 `authorizationLabel` 做拦截; 3. 检查 `checkAuthApi` 是否返回允许继续使用的结果; 4. 检查授权管理页面是否正确调用 `getAuthorizationExpiredMessage` 并提示用户; 5. 检查是否在后端网关或路由守卫中也实现了相同过期策略。 参考路径: - [license.ts:60-124](file://ai-electron/frontend/src/core/utils/license.ts#L60-L124) - [authorization/index.vue:584-592](file://ai-electron/frontend/src/plat/views/authorization/index.vue#L584-L592) - [login.ts:130-140](file://ai-electron/frontend/src/core/api/sys/login.ts#L130-L140) ### localStorage 缓存不一致 **现象**:本地缓存中的 `authorizationUnit` 与实际后端返回不一致。 **可能原因**: - 用户手动修改了 `localStorage`; - 多次导入授权后,前端未刷新缓存; - 不同页面或模块各自维护缓存,但没有统一更新; - `userStore.setPageCache` 写入后,其他组件未重新读取。 **处理建议** 1. 以 `App.vue` 启动时拉取的授权信息为准; 2. 导入授权成功后,显式更新 `userStore.setPageCache('authorizationUnit', unit)`; 3. 如果需要持久化,确保只在一个入口处写入; 4. 调试时可清空 `localStorage` 中相关键,观察应用是否重新拉取; 5. 不要在多个地方随意覆盖同一缓存键。 参考路径: - [App.vue:40-60](file://ai-electron/frontend/src/App.vue#L40-L60) ### 授权信息与网关 token 不一致 **现象**:前端授权信息显示正常,但网关拒绝请求或提示无权限。 **可能原因**: - 前端使用 `/sys/info` 展示授权信息,而网关可能基于 token 或会话状态做权限校验; - 用户切换了账号、租户、企业或角色; - 后端授权状态变更后,前端缓存未刷新; - 网关与服务端授权数据库不同步。 **处理建议** 1. 不要将水印或前端授权标签视为网关权限依据; 2. 检查登录态、token、会话是否与当前授权主体一致; 3. 在授权变更后,考虑退出登录或刷新会话; 4. 检查 `authorization/index.vue` 中授权更新流程是否同步了必要的认证上下文; 5. 如果问题持续,结合后端日志检查 `/sys/checkAuth`、网关鉴权和授权库一致性。 参考路径: - [login.ts:100-140](file://ai-electron/frontend/src/core/api/sys/login.ts#L100-L140) - [authorization/index.vue:296-592](file://ai-electron/frontend/src/plat/views/authorization/index.vue#L296-L592) ## 结论 授权单元与水印机制在前端工程中形成了清晰的职责分工: - `login.ts` 负责与后端交互; - `license.ts` 负责解析授权数据、判断过期和生成提示; - `App.vue` 负责启动时拉取授权信息、写入缓存并驱动水印; - `useWatermark.ts` 负责在 DOM 层绘制稳定、可恢复的水印; - 授权管理页面和授权弹窗负责向用户展示授权状态和过期信息。 实际权限控制不应依赖水印。水印是可视化手段,真正的授权判断应结合 `checkAuthApi`、后端接口和用户会话。新增授权字段时,应优先扩展 `license.ts` 的解析逻辑,再在需要的 UI 层消费新字段,并确保授权过期路径在所有相关页面保持一致。