提交

docs/开发文档/API/用户认证登录API.md

@@ -395,7 +395,8 @@ loginWithEncryption()
             "email": "admin@example.com",
             "phonenumber": "13800138000",
             "sex": "1",
-            "avatar": "/profile/avatar/default.jpg",
+            "avatar": "1938120323613728770",
+            "avatarUrl": "http://example.com/ruoyi/2025/08/31/xxxx.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&...",
             "status": "0",
             "loginIp": "127.0.0.1",
             "loginDate": "2025-01-26 10:30:00",
@@ -409,6 +410,13 @@ loginWithEncryption()
 }
 ```
 
+**字段说明补充**:
+
+- `avatar`：始终返回 `sys_user.avatar` 中存储的 OSS ID（字符串），用于鉴权下载接口 `/resource/oss/download/{ossId}`。
+- `avatarUrl`：系统通过 `TransConstant.OSS_ID_TO_URL` 规则实时翻译得到的可直接访问地址（MinIO 预签名 URL），供无需链路改造的场景快速显示；有效期受 OSS 策略控制。
+
+前端如需在带 Token 的受保护组件（如 `ImagePreview`）中展示，请优先使用 `avatar` 并通过统一的认证下载逻辑获取图片，避免直接暴露临时 URL。
+
 **超级管理员权限说明**:
 
 admin 用户具有系统最高权限`*:*:*`，可以访问所有功能模块和执行所有操作。
@@ -663,7 +671,9 @@ methods: {
 ---
 
 **📝 维护**: 用户认证登录 API 文档  
-**🔄 更新**: 2025-01-03  
+**🔄 更新记录**:  
+- 2025-11-28：`/system/user/getInfo` 增加 `avatarUrl` 字段，并明确 `avatar` 返回 OSS ID  
+- 2025-01-03：文档初始化  
 **📁 文件**: 用户认证登录 API.md
 
 ## 获取具有指定权限的用户列表
@@ -693,7 +703,8 @@ methods: {
       deptId: string;   // 部门ID
       deptName: string; // 部门名称
     };
-    avatar: string;   // 头像URL
+    avatar: string;   // 头像OSS ID
+    avatarUrl?: string; // 头像访问URL（可选，预签名）
   }[];
   total: number;      // 总记录数
 }
@@ -713,7 +724,8 @@ methods: {
         "deptId": "1",
         "deptName": "后勤部"
       },
-      "avatar": "http://example.com/avatar.jpg"
+      "avatar": "1938120323613728770",
+      "avatarUrl": "http://example.com/avatar.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&..."
     }
   ],
   "total": 1

docs/开发文档/ImagePreview组件使用说明.md

@@ -65,6 +65,36 @@ ImagePreview 是一个图片预览组件，支持两种模式：
 </template>
 ```
 
+### 4. 顶部个人头像（自动识别OSS ID）
+
+```vue
+<script setup lang="ts">
+import { computed } from 'vue';
+import ImagePreview from '@/components/ImagePreview/index.vue';
+import { useUserStore } from '@/store/modules/user';
+
+const userStore = useUserStore();
+const avatarIsOssId = computed(() => {
+  const avatar = userStore.avatar;
+  if (!avatar) return false;
+  return !/^https?:\/\//i.test(avatar) && !avatar.startsWith('/');
+});
+</script>
+
+<template>
+  <ImagePreview
+    v-if="userStore.avatar"
+    class="user-avatar"
+    :src="userStore.avatar"
+    :width="24"
+    :height="24"
+    :is-oss-id="avatarIsOssId"
+  />
+</template>
+```
+
+> ✅ 用于首页 `Navbar` 头像区域时，`avatarIsOssId` 会自动识别当前值是否为 OSS ID，从而在带 Token 的 `/resource/oss/download/{ossId}` 接口与传统 URL 之间无缝切换，保证头像始终通过认证通道加载。
+
 ## 技术实现
 
 ### 核心功能
@@ -126,6 +156,7 @@ const urlCache = ref<Map<string, string>>(new Map());
 
 ## 更新记录
 
+- **2025-11-28**：补充顶部栏个人头像场景示例，强调 OSS ID 自动识别策略，确保 `Navbar` 等公共区域也复用统一的图片安全加载方案。
 - **2025-08-02**：修复组件，支持OSS ID模式，添加缓存机制和加载状态
 - 修复了导入错误和computed未定义的问题
 - 添加了完整的错误处理和日志记录 

docs/开发文档/移动端开发规范总结.md

@@ -737,6 +737,13 @@ export default {
 </script>
 ```
 
+#### 头像鉴权加载
+
+- 统一从 `/system/user/getInfo` 获取 `avatar`（OSS ID）与 `avatarUrl`（预签名地址）。
+- 页面中优先识别 `avatar` 是否为 OSS ID，使用 `uni.request`（`responseType: 'arraybuffer'`）访问 `/resource/oss/download/{ossId}` 并转换为 `Blob URL/Base64`，确保 Token 认证生效。
+- 若历史账号仍存储直接 URL，则回退到 `avatar` 或 `avatarUrl` 原始值，最后兜底 `/static/111.png`。
+- 首页、详情页等通用区域必需复用该策略，避免直接暴露预签名链接导致过期或越权。
+
 #### 列表优化
 
 ```vue