品牌主题定制

品牌主题在一个页面里集中管 3 件事：基础（系统名 + 主 Logo + 主题色 + 灰色模式）、登录页（大图 / 图文 + 标题副标题）、欢迎页（顶部 banner + 能力卡片列数）。改完即时生效不重启，右侧 ThemePreview 常驻实时预览登录页和会话页两个 tab。

8.1 入口与 BrandThemeStudio 单页结构

左侧菜单「品牌主题」打开 /admin/brand-theme，顶部一行 tab 切 3 段；右侧常驻 ThemePreview，960×600 1:1 照搬 LoginShell 和 ChatSidebar+ChatView，所见即所得。

左菜单「品牌主题」进入 BrandThemeView
顶部段切换：基础 / 登录页 / 欢迎页（注意：「主题」并不是独立的 tab，主题色和灰色模式在「基础」段下半部分）
左侧 form 改任何字段，右侧 ThemePreview 立刻刷新
左侧 form 底部「保存」会弹「应用到全站」二次确认，确认后写盘 + 即时应用到当前浏览器

小贴士： BrandThemeStudio 是单一 form，3 段共用一份数据（branding + welcome_hero），统一保存——切段不会丢已改未存的字段。

8.2 基础段：系统主 Logo + 系统名称 + 主题

「基础」段把品牌身份和主题色合并在一页：上半部分是系统主 Logo + 系统名称；下半部分（以「主题」小标题分隔）是 主题色 + 推荐配色 + 灰色模式。系统名同时绑定到浏览器标题、提示词、企微推送等多处模板变量 {{system_name}}。

字段	说明	校验
系统主 Logo	png / jpg / webp / svg ≤ 5 MB，推荐方形	—
系统名称	对应模板变量 `{{system_name}}`	必填，maxlength=40
主题色 brand_color	#RRGGBB，`deriveBrandVars` 自动派生 bg-2/3、shadow-rgb、brand-900、深浅渐变	正则 `/^#[0-9A-Fa-f]{6}$/`
推荐配色	6 个预设：电光蓝 / 翠绿 / 品橙 / 朱红 / 玫粉 / 智能紫	—
灰色模式 gray_mode	国家重大事件置灰使用端（登录 / 业务对话），管理后台不受影响	—

点「更换 Logo」上传系统主 Logo（不在此处配 favicon / AI 头像，那些保留库值）
填「系统名称」（例：助手小匠）
「主题色」点色块取色或填 #RRGGBB，或点「推荐配色」预设
需要灰显时打开「灰色模式」开关
底部「保存」 → 弹「应用到全站」二次确认 → 落库 + 当前浏览器即时应用

注意： favicon 和 AI 消息头像不在「品牌主题」页配置，会保留数据库现值不变。

8.3 登录页段：图文 / 大图双模式

登录页段先用「展示方式」二选一：图文（主题色底 + 品牌 + 标题/副标题 + 能力高亮）或大图（左侧整块铺登录大图）。两种模式字段不同：图文模式露出标题/副标题/文字色；大图模式只露出图片上传。

展示方式	露出字段	留空回退
图文 (login_layout='text')	主标题 login_title / 副标题 login_subtitle / 文字颜色 login_title_color	标题副标题留空用内置文案；文字色留空用白色压主题色深渐变
大图 (login_layout='image')	登录大图 login_image_url（上传 png/jpg/webp/svg）	无图退主题色深渐变

切到「登录页」段
「展示方式」选图文或大图
图文：填主标题（textarea 2 行）/ 副标题 / 文字颜色（取色器 + hex + 「默认(白)」按钮）
大图：点「上传图片」选品牌图；已有图可点「移除（用渐变）」
右侧 ThemePreview 切到「登录页」tab 1:1 看实际效果
底部「保存」 → 二次确认 → 生效

8.4 欢迎页段：顶部欢迎 banner + 能力卡片列数

「欢迎页」段管 ChatView 进入空会话时的顶部 banner（welcome_hero）+ 下方能力卡片每行列数。banner 同样有「图文 / 大图」二选一；能力卡片只配「列数」(2/3/4)，要改卡片文案/图标/排序走欢迎页。

字段 / 控件	说明
展示方式 hero_layout	icon（图文：主题色底 + 图标 + 标题/副标题）/ image（大图：整块铺图不含文字）
标题模板 hero_title_template	仅图文模式露出。支持变量 `{{user_name}}`、`{{greeting}}`（按时段，如「上午好」）、`{{system_name}}`。默认「下午好，{{user_name}}」
副标题 hero_subtitle	仅图文模式露出
文字颜色 hero_title_color	仅图文模式露出。默认白
欢迎大图 hero_image_url	仅大图模式露出。png/jpg/webp/gif，整块铺满；无图退主题色深渐变
能力卡片每行列数 cards_columns	2 / 3 / 4 三选一，窄屏自动回落。默认 4

切到「欢迎页」段
「展示方式」选图文或大图
图文：填标题模板（含变量）/ 副标题 / 文字色
大图：点「上传图片」选 banner 图（建议 22:5 横图，约 880×200）；已有图可「移除（用渐变）」
选「能力卡片每行列数」2/3/4
右侧 ThemePreview 自动切到「会话页」tab 看 WelcomeHero + 卡片布局
「保存」 → 二次确认 → 生效
底部「能力卡片更多配置（增删 / 文案 / 图标 / 排序）→」链接跳 /admin/welcome

小贴士： 要改 banner 下方的能力卡片文案 / 推荐问题，点底部「能力卡片更多配置 →」或去欢迎页。

8.5 ThemePreview 常驻预览 + 即时生效

右侧 ThemePreview 是常驻组件，不是弹窗——两个 tab：登录页 / 会话页，960×600 等比，分别 1:1 照搬 LoginShell 和 ChatSidebar + ChatView。本质是把 form 改的字段实时 scope 注入到预览容器的 CSS 变量（deriveBrandVars 派生），所以你看到的就是用户最终看到的。