feat(appearance): 主题档存储/传输全面 JSON 化（读侧兼容旧紧凑值）+ LOGO 文字 sch_settings.logo_text 级联读写（LOGO文字与主题JSON化）

src/main/java/com/yunhai/userhome/controller/api/SchSettingsController.java

@@ -28,8 +28,8 @@ import java.util.Optional;
  * <p>主题设置轮（2026-09-30）新增学校默认主题档三接口（契约见 YschTheme《主题设置与通道改动-执行方案》§3.5）：
  * schTheme 读（已登录可读，当时"可空不兜底"——S7 起改为学校→平台级联，见文末说明）；
  * saveSchThemeState 写（仅学校管理员/超管）；clearSchTheme 清空（置空 theme 字段——sch_settings 行还承载
- * logo 等字段不能删行，置空后读侧返回 null，效果等同"未配置"）。存储形态：theme_name 列存紧凑四段编码
- * {@code theme|sideDeep01|gradOn01|sideFollow01}（如 teal|0|1|1；不拆列、零 DDL，列宽未确认故不存整份 JSON；
+ * logo 等字段不能删行，置空后读侧返回 null，效果等同"未配置"）。存储形态（2026-10-09 JSON 化）：
+ * theme_name 列存规范化 ThemeState JSON 串（固定字段序；历史紧凑四段编码读侧兼容自动转 JSON；
  * 旧格式值/非法值读侧一律视同未配置）。</p>
  * <p>默认头像轮（2026-09-30）同构新增学校默认头像样式三接口：schAvatarStyle 读（可空不兜底）；
  * saveSchAvatarStyle 写（仅学校管理员/超管，值只接受 text|silhouette）；clearSchAvatarStyle 清空（置空
@@ -121,7 +121,7 @@ public class SchSettingsController {
         return out;
     }
 
-    /** 保存学校默认主题档（仅学校管理员/超管）：themeState 为整份 ThemeState JSON，服务端转紧凑编码存 theme_name。 */
+    /** 保存学校默认主题档（仅学校管理员/超管）：themeState 为整份 ThemeState JSON，规范化后原形态存 theme_name（2026-10-09 JSON 化）。 */
     @PostMapping("saveSchThemeState")
     public void saveSchThemeState(BoaUser authUserWithDept,
                                   @RequestParam("themeState") String themeState,
@@ -150,6 +150,37 @@ public class SchSettingsController {
         schSettingsService.save(schSettings);
     }
 
+    // ===== LOGO 文字（平台/学校名称，LOGO 文字轮 2026-10-09）：与主题三件套同模式 =====
+
+    /** LOGO 文字读（已登录可读）：{logoText: string|null, schId=实际命中层}。本校空 → 平台层 → null。 */
+    @GetMapping("schLogoText")
+    public Map<String, Object> schLogoText(BoaUser authUserWithDept) {
+        ISchSettingsService.LayerValue hit =
+                schSettingsService.readLogoTextWithFallback(schSettingsService.resolveThemeSchId(authUserWithDept, null));
+        Map<String, Object> out = new HashMap<>();
+        out.put("logoText", hit.getValue());
+        out.put("schId", hit.getHitSchId());
+        return out;
+    }
+
+    /** 保存 LOGO 文字（仅学校管理员/超管）：trim 后落本级（超管=平台层 0，校管=本校）；空串存 null（=清空）。 */
+    @PostMapping("saveSchLogoText")
+    public void saveSchLogoText(BoaUser authUserWithDept,
+                                @RequestParam("logoText") String logoText) {
+        requireThemeAdmin(authUserWithDept);
+        String text = logoText == null ? "" : logoText.trim();
+        if (text.length() > 64) {
+            throw new DException("LOGO 文字不能超过 64 个字符");
+        }
+        Integer targetSchId = schSettingsService.resolveThemeSchId(authUserWithDept, null);
+        SchSettings schSettings = schSettingsService.findBySchIdRaw(targetSchId).orElseGet(SchSettings::new);
+        schSettings.setCDate(new Date());
+        schSettings.setSchId(targetSchId);
+        schSettings.setCId(authUserWithDept.getId());
+        schSettings.setLogoText(text.isEmpty() ? null : text);
+        schSettingsService.save(schSettings);
+    }
+
     @PostMapping("saveSchTheme")
     public void saveSchTheme(BoaUser authUserWithDept, String themeName, @RequestParam(name = "schId", defaultValue = "0") Integer schId) {
         if (schId == null || schId == 0) {

src/main/java/com/yunhai/userhome/entity/SchSettings.java

@@ -37,6 +37,10 @@ public class SchSettings {
     @Column(name = "logo_url")
     private String logoUrl;
 
+    /** LOGO 配套平台/学校名称文字（LOGO 图在 logo 表池，文字是单值配置随 settings；NULL=未配置回落上级） */
+    @Column(name = "logo_text")
+    private String logoText;
+
     @Column(name = "home_img_url")
     private String homeImgUrl;
 

src/main/java/com/yunhai/userhome/service/ISchSettingsService.java

@@ -38,6 +38,9 @@ public interface ISchSettingsService {
     /** 头像样式读侧级联：语义与 {@link #readThemeWithFallback} 同构（本校空/脏 → 平台层 → null）。 */
     LayerValue readAvatarWithFallback(Integer schId);
 
+    /** LOGO 文字读侧级联（LOGO 文字轮 2026-10-09）：本校空 → 平台层 → null。 */
+    LayerValue readLogoTextWithFallback(Integer schId);
+
     /** 级联读命中结果：{@code value}=命中的档位值（两级都无则 null），{@code hitSchId}=实际命中层的 schId
      * （回落发生时是 0，不是解析出的本校 schId）。设置中心读端点的响应体 schId 即此语义——
      * 前端据此区分「本校已配置」与「本校未配置、正在回落平台默认」。 */

src/main/java/com/yunhai/userhome/service/impl/AppearanceServiceImpl.java

@@ -65,7 +65,7 @@ public class AppearanceServiceImpl implements IAppearanceService {
         try {
             Optional<UserAppearance> ua = userAppearanceRepository.findByUserId(user.getId());
             if (ua.isPresent()) {
-                out.put("myTheme", validCompactTheme(ua.get().getThemeState()));
+                out.put("myTheme", validThemeState(ua.get().getThemeState()));
                 out.put("avatarMy", validAvatarStyle(ua.get().getAvatarStyle()));
             }
         } catch (Exception e) {
@@ -77,7 +77,7 @@ public class AppearanceServiceImpl implements IAppearanceService {
             if (schId != null) {
                 SchSettings sch = schSettingsService.findBySchIdRaw(schId).orElse(null);
                 if (sch != null) {
-                    out.put("schTheme", validCompactTheme(sch.getThemeName()));
+                    out.put("schTheme", validThemeState(sch.getThemeName()));
                     out.put("avatarSch", validAvatarStyle(sch.getAvatarStyle()));
                 }
                 out.put("logoUrl", resolveLogoUrl(schId));
@@ -89,9 +89,10 @@ public class AppearanceServiceImpl implements IAppearanceService {
     }
 
     /**
-     * 当前用户生效外观（oapi 代理轮 2026-10-08，{@code /oapi/appearance} 出参真源）：
-     * {@code {theme, avatar, logoUrl}}——主题/头像为【合成后的生效值】（个人自选 → 学校默认 → 平台默认(schId=0)
-     * 级联，层级知识留在 UserHome 内部，对外不拆 my/sch）；logoUrl 为本校 type=1 → 平台 type=0 择优。
+     * 当前用户生效外观（oapi 代理轮 2026-10-08，{@code /oapi/appearance} 出参真源；2026-10-09 JSON 化+LOGO 文字）：
+     * {@code {theme, avatar, logoText, logoUrl}}——theme 为【JSON 对象】（个人自选 → 学校默认 → 平台默认(schId=0)
+     * 级联，层级知识留在 UserHome 内部，对外不拆 my/sch）；avatar 为生效样式；logoText 本校→平台级联；
+     * logoUrl 为本校 type=1 → 平台 type=0 择优。
      *
      * <p>schId 解析走本地 user_current_role（oapi 入参只有 userId，不引 identity 跨仓）：roleId 当前角色学校，
      * 无角色/跨校态回落 0（平台层）。与 /api/appearance 的 resolveThemeSchId（超管强制 0）仅在「超管临时切入
@@ -102,6 +103,7 @@ public class AppearanceServiceImpl implements IAppearanceService {
         Map<String, Object> out = new HashMap<>();
         out.put("theme", null);
         out.put("avatar", null);
+        out.put("logoText", null);
         out.put("logoUrl", null);
         if (userId == null) {
             return out;
@@ -115,7 +117,7 @@ public class AppearanceServiceImpl implements IAppearanceService {
         try {
             Optional<UserAppearance> ua = userAppearanceRepository.findByUserId(userId);
             if (ua.isPresent()) {
-                myTheme = validCompactTheme(ua.get().getThemeState());
+                myTheme = validThemeState(ua.get().getThemeState());
                 myAvatar = validAvatarStyle(ua.get().getAvatarStyle());
             }
         } catch (Exception e) {
@@ -125,25 +127,18 @@ public class AppearanceServiceImpl implements IAppearanceService {
         String avatar = myAvatar;
         try {
             if (theme == null) {
-                // readThemeWithFallback 命中值是 ThemeState JSON（schTheme 端点口径）；oapi 契约统一出
-                // 紧凑编码（init 侧 compactThemeToJson 只认紧凑形态），脏值宽松降 null 不抛
-                String hit = schSettingsService.readThemeWithFallback(schId).getValue();
-                if (hit != null) {
-                    try {
-                        theme = ThemeCodec.encodeThemeState(hit);
-                    } catch (DException e) {
-                        theme = null;
-                    }
-                }
+                theme = schSettingsService.readThemeWithFallback(schId).getValue();
             }
             if (avatar == null) {
                 avatar = schSettingsService.readAvatarWithFallback(schId).getValue();
             }
+            out.put("logoText", schSettingsService.readLogoTextWithFallback(schId).getValue());
             out.put("logoUrl", resolveLogoUrl(schId));
         } catch (Exception e) {
-            // 学校/平台段降级：theme/avatar/logoUrl 保持已得值或 null
+            // 学校/平台段降级：theme/avatar/logoText/logoUrl 保持已得值或 null
         }
-        out.put("theme", theme);
+        // theme 出 JSON 对象（2026-10-09 契约）；值已过 decodeThemeState 校验，解析失败按 null 降级
+        out.put("theme", theme == null ? null : ThemeCodec.toJsonNode(theme));
         out.put("avatar", avatar);
         return out;
     }
@@ -155,11 +150,8 @@ public class AppearanceServiceImpl implements IAppearanceService {
             // 跟随学校默认：置 NULL（列语义见实体注释）
             ua.setThemeState(null);
         } else {
-            String compact = themeState.trim();
-            if (ThemeCodec.decodeThemeState(compact) == null) {
-                throw new DException("主题档不合法: " + themeState);
-            }
-            ua.setThemeState(compact);
+            // 写侧从严：只收 JSON、产规范化 JSON 串（紧凑入参抛 DException，2026-10-09 JSON 化契约）
+            ua.setThemeState(ThemeCodec.encodeThemeState(themeState));
         }
         ua.setUDate(new Date());
         userAppearanceRepository.save(ua);
@@ -190,11 +182,9 @@ public class AppearanceServiceImpl implements IAppearanceService {
         });
     }
 
-    /** 紧凑编码校验读（非法/脏值/旧格式 → null 视同未配置；合法返回原紧凑串） */
-    private String validCompactTheme(String raw) {
-        if (!StringUtils.hasText(raw)) return null;
-        String compact = raw.trim();
-        return ThemeCodec.decodeThemeState(compact) == null ? null : compact;
+    /** 主题档校验读（JSON 校验→规范化；旧紧凑四段兼容转 JSON；脏值 → null 视同未配置） */
+    private String validThemeState(String raw) {
+        return StringUtils.hasText(raw) ? ThemeCodec.decodeThemeState(raw) : null;
     }
 
     private String validAvatarStyle(String raw) {

src/main/java/com/yunhai/userhome/service/impl/SchSettingsServiceImpl.java

@@ -96,6 +96,25 @@ public class SchSettingsServiceImpl implements ISchSettingsService {
                 ISchSettingsService.PLATFORM_SCH_ID);
     }
 
+    @Override
+    public ISchSettingsService.LayerValue readLogoTextWithFallback(Integer schId) {
+        String text = readLogoTextAt(schId);
+        if (text != null || schId == null || schId == ISchSettingsService.PLATFORM_SCH_ID) {
+            return new ISchSettingsService.LayerValue(text, schId);
+        }
+        return new ISchSettingsService.LayerValue(readLogoTextAt(ISchSettingsService.PLATFORM_SCH_ID),
+                ISchSettingsService.PLATFORM_SCH_ID);
+    }
+
+    /** 原样读某层 LOGO 文字（查无行/空白 → null；trim 后存储口径） */
+    private String readLogoTextAt(Integer schId) {
+        return schSettingsRepository.findFirstBySchId(schId)
+                .map(SchSettings::getLogoText)
+                .map(String::trim)
+                .filter(s -> !s.isEmpty())
+                .orElse(null);
+    }
+
     /** 原样读某层主题档并解码（查无行/旧格式/脏值 → null） */
     private String decodeTheme(Integer schId) {
         return schSettingsRepository.findFirstBySchId(schId)

src/main/java/com/yunhai/userhome/utils/ThemeCodec.java

@@ -1,13 +1,18 @@
 package com.yunhai.userhome.utils;
 
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
 import com.yunhai.platform.utils.exception.DException;
 import org.springframework.util.StringUtils;
 
 /**
- * 主题档/头像样式的编解码与校验（原 SchSettingsController 私有实现下沉，2026-10-08 外观偏好轮
- * 供 AppearanceController 共享；行为与原私有版本逐字节一致，勿改语义）。
- * <p>紧凑编码形态：{@code theme|sideDeep01|gradOn01|sideFollow01}（如 {@code teal|0|1|1}）；
- * 读侧宽松（脏值一律 null 视同未配置），写侧从严（非法抛 DException）。</p>
+ * 主题档/头像样式的编解码与校验（原 SchSettingsController 私有实现下沉，2026-10-08 外观偏好轮；
+ * 2026-10-09 存储与传输全面 JSON 化）。
+ * <p>存储形态：{@code {"theme":"teal","sideDeep":false,"gradOn":false,"sideFollow":false}}
+ * （固定字段序的规范化 JSON 串；sch_settings.theme_name 与 user_appearance.theme_state 同形态）。
+ * 历史紧凑编码 {@code theme|sideDeep01|gradOn01|sideFollow01} 仅在【读侧】兼容——解码时自动转 JSON，
+ * 写侧一律产出 JSON（存量行靠迁移 UPDATE 或读时懒迁移消化）。
+ * 读侧宽松（脏值/不可解析一律 null 视同未配置），写侧从严（非法抛 DException）。</p>
  */
 public final class ThemeCodec {
 
@@ -17,39 +22,74 @@ public final class ThemeCodec {
     /** 合法头像样式（与前端 avatar.ts 的 AvatarStyle 一致；写入侧从严，对齐 encodeThemeState 做法） */
     public static final String[] AVATAR_STYLES = {"text", "silhouette"};
 
+    private static final ObjectMapper MAPPER = new ObjectMapper();
+
     private ThemeCodec() {
     }
 
-    /** 紧凑编码 → ThemeState JSON；非本编码形态（旧档名/脏值/字段非法）一律 null（视同未配置） */
-    public static String decodeThemeState(String encoded) {
-        if (!StringUtils.hasText(encoded)) return null;
-        String[] parts = encoded.trim().split("\\|");
-        if (parts.length != 4) return null;
-        if (!isThemeKey(parts[0])) return null;
-        for (int i = 1; i < 4; i++) {
-            if (parts[i].length() != 1 || (parts[i].charAt(0) != '0' && parts[i].charAt(0) != '1')) return null;
+    /** 解析并校验 ThemeState JSON（四字段齐全、档名合法），合法返回【规范化 JSON 串】；非法 null */
+    private static String normalizeJson(String themeStateJson) {
+        try {
+            JsonNode n = MAPPER.readTree(themeStateJson);
+            if (n == null || !n.isObject() || !n.hasNonNull("theme") || !n.has("sideDeep")
+                    || !n.has("gradOn") || !n.has("sideFollow")) {
+                return null;
+            }
+            String theme = n.get("theme").asText();
+            if (!isThemeKey(theme)) {
+                return null;
+            }
+            return "{\"theme\":\"" + theme + "\",\"sideDeep\":" + n.get("sideDeep").asBoolean()
+                    + ",\"gradOn\":" + n.get("gradOn").asBoolean()
+                    + ",\"sideFollow\":" + n.get("sideFollow").asBoolean() + "}";
+        } catch (Exception e) {
+            return null;
         }
-        return "{\"theme\":\"" + parts[0] + "\",\"sideDeep\":" + parts[1]
-                + ",\"gradOn\":" + parts[2] + ",\"sideFollow\":" + parts[3] + "}";
     }
 
-    /** ThemeState JSON 校验（四字段齐全、档名合法）+ → 紧凑编码；非法抛业务异常（写入侧从严） */
+    /** 旧紧凑编码 theme|01|01|01 → JSON；非本形态返回 null */
+    private static String fromCompact(String compact) {
+        String[] p = compact.trim().split("\\|");
+        if (p.length != 4 || !isThemeKey(p[0])) {
+            return null;
+        }
+        for (int i = 1; i < 4; i++) {
+            if (p[i].length() != 1 || (p[i].charAt(0) != '0' && p[i].charAt(0) != '1')) {
+                return null;
+            }
+        }
+        return "{\"theme\":\"" + p[0] + "\",\"sideDeep\":" + ("1".equals(p[1]))
+                + ",\"gradOn\":" + ("1".equals(p[2]))
+                + ",\"sideFollow\":" + ("1".equals(p[3])) + "}";
+    }
+
+    /**
+     * 读侧统一入口：JSON 校验 → 规范化 JSON；旧紧凑四段 → 转 JSON；其余（旧档名/脏值）null（视同未配置）。
+     * 返回值形态：ThemeState JSON 串（与 localStorage yh-theme 键形态一致）。
+     */
+    public static String decodeThemeState(String raw) {
+        if (!StringUtils.hasText(raw)) return null;
+        String s = raw.trim();
+        return s.startsWith("{") ? normalizeJson(s) : fromCompact(s);
+    }
+
+    /** ThemeState JSON 校验（四字段齐全、档名合法）+ 规范化（固定字段序）；非法抛业务异常（写入侧从严） */
     public static String encodeThemeState(String themeStateJson) {
         if (!StringUtils.hasText(themeStateJson)) throw new DException("主题档不能为空");
-        com.fasterxml.jackson.databind.JsonNode n;
+        String normalized = normalizeJson(themeStateJson.trim());
+        if (normalized == null) {
+            throw new DException("主题档格式不合法");
+        }
+        return normalized;
+    }
+
+    /** ThemeState JSON 串 → 节点（oapi 出参对象形态用）；入串须先过 decodeThemeState 校验 */
+    public static JsonNode toJsonNode(String themeStateJson) {
         try {
-            n = new com.fasterxml.jackson.databind.ObjectMapper().readTree(themeStateJson);
+            return MAPPER.readTree(themeStateJson);
         } catch (Exception e) {
-            throw new DException("主题档格式不合法");
+            return null;
         }
-        if (n == null || !n.isObject() || !n.hasNonNull("theme") || !n.has("sideDeep") || !n.has("gradOn") || !n.has("sideFollow")) {
-            throw new DException("主题档格式不合法");
-        }
-        String theme = n.get("theme").asText();
-        if (!isThemeKey(theme)) throw new DException("主题档名不合法: " + theme);
-        return theme + "|" + (n.get("sideDeep").asBoolean() ? 1 : 0)
-                + "|" + (n.get("gradOn").asBoolean() ? 1 : 0)
-                + "|" + (n.get("sideFollow").asBoolean() ? 1 : 0);
     }
 
     public static boolean isThemeKey(String theme) {