# 系统外观设置(登录页背景图 + 企业 Logo)- 前端联调方案 ## 涉及页面 - 系统管理 → 外观设置(`system/appearance/index`) - 登录页(品牌 Logo、登录背景图) - 首页(侧边栏企业 Logo) ## 业务流程与数据带入 1. 管理员在「外观设置」页上传登录页背景图 / 企业 Logo,图片通过公共上传接口直接获得永久访问地址与 `blobId`。 2. 点击保存后,后端把 `blobId` 与固定记录(`recordType = system_appearance`、`recordId = 1`)绑定,并分别以 `application = logo`、`application = login_background` 区分两类图片。 3. 前端保存成功后立即应用:登录页背景、登录页 Logo、首页侧边栏 Logo 实时变化。 4. 浏览器刷新或重新登录时,前端在应用启动阶段调用「获得系统外观」接口,读取服务端配置并应用;未登录的登录页也能显示已配置的背景图与 Logo。 ## API | 方法 | 路径 | 说明 | 权限 | |------|------|------|------| | GET | /system/appearance/get | 获得系统外观配置 | 匿名可访问(@PermitAll) | | POST | /system/appearance/save | 保存系统外观配置 | `system:appearance:update` | | POST | /system/storage-blob/public-upload | 公共文件上传(永久有效) | 登录用户 | | GET | /system/storage-blob/preview/{fileName}?publicKey=xxx | 图片预览(永久地址) | 匿名可访问(@PermitAll) | ### 获得系统外观 **响应字段:** | 字段 | 类型 | 说明 | |------|------|------| | logoBlobId | Long | 企业 Logo 的文件编号,未配置为 null | | logoUrl | String | 企业 Logo 的永久访问地址,未配置为 null | | loginBackgroundBlobId | Long | 登录背景图的文件编号,未配置为 null | | loginBackgroundUrl | String | 登录背景图的永久访问地址,未配置为 null | **响应示例:** ```json { "code": 0, "data": { "logoBlobId": 1024, "logoUrl": "http://192.168.0.10:48080/admin-api/system/storage-blob/preview/xxx.png?publicKey=yyy", "loginBackgroundBlobId": 1025, "loginBackgroundUrl": "http://192.168.0.10:48080/admin-api/system/storage-blob/preview/zzz.png?publicKey=www" }, "msg": "" } ``` ### 公共文件上传 - 请求方式:`multipart/form-data` - 参数:`files`(可多个文件,本场景一次一个文件) - 响应为文件数组,本场景取第一个元素,使用其中的 `id`(即 `blobId`)与 `previewURL`(永久访问地址)。 ### 保存系统外观 **请求参数:** | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | logoBlobId | Long | 否 | 企业 Logo 文件编号;传 null 表示清除 | | loginBackgroundBlobId | Long | 否 | 登录背景图文件编号;传 null 表示清除 | **请求示例:** ```json { "logoBlobId": 1024, "loginBackgroundBlobId": 1025 } ``` **响应:** `{ "code": 0, "data": true }` ## 接口调用时序 1. 进入「外观设置」页 → 调用 `GET /system/appearance/get`,回显已配置的图片与 `blobId`。 2. 选择图片 → 调用 `POST /system/storage-blob/public-upload` → 记录返回的 `blobId` 与 `previewURL`,页面立即预览。 3. 点击保存 → 调用 `POST /system/appearance/save`,提交两个 `blobId`。 4. 保存成功后 → 立即更新首页 Logo 与登录页背景/Logo,无需刷新。 ## 字段展示规则 | 字段 | 展示位置 | 说明 | |------|----------|------| | loginBackgroundUrl | 外观设置页预览、登录页整页背景 | 登录页背景图,未配置时使用系统默认背景 | | logoUrl | 外观设置页预览、登录页品牌区 Logo、首页侧边栏 Logo | 一套配置同时作用于登录页与首页,未配置时使用系统默认 Logo | ## 业务规则说明 | 场景 | 规则 | |------|------| | 上传 | 仅接受常规图片格式(image/*),使用公共上传接口,返回永久可访问地址 | | 保存 | 两类图片独立保存,替换其中一张不影响另一张 | | 清除 | 对应 `blobId` 传 null,保存后恢复系统默认样式 | | 未登录访问 | 登录页通过 `@PermitAll` 的外观查询接口读取配置,背景图/Logo 使用 `?publicKey=` 永久地址,无需登录 | | 加载失败 | 前端启动阶段查询外观失败时静默保留默认样式,不阻塞应用启动 | ## 注意事项 - 图片上传与保存是两步操作,上传成功但未点击保存不会生效。 - 外观配置为全系统级(`recordId = 1`),不区分租户与用户。 - 前端启动阶段查询外观接口需带 `tenant-id` 请求头。 - 菜单「外观设置」由 SQL 脚本初始化,超级管理员默认拥有权限,其他角色需在角色菜单中勾选「保存外观设置」按钮权限。 - 更换图片后建议使用固定尺寸的横版背景图(如 1920×1080),Logo 建议使用透明背景 PNG。