feat(user-center): 用户偏好读写 API + preferences JSONB 列 (#7)

* feat(user-center): user_accounts 加 preferences 列

* feat(user-center): 偏好读写接口 GET/PATCH /api/user-center/preferences

* chore(user-center): CR - patchPreferences 走 jsonb DB 合并避免并发 lost update

Copilot CR #7（多项）：
- UserAccount: preferences 用 Map.copyOf 做防御性拷贝，保证 record 的不可变快照语义
- JdbcUserAccountRepository.insert: INSERT 写入 preferences 列，插入后 findById 回读，
  避免初始偏好被丢 + 字段漂移
- JdbcUserAccountRepository.patchPreferences: 改名自 updatePreferences，
  PostgreSQL 路径用 'preferences || ?::jsonb' 单条 UPDATE 原子合并，setObject + Types.OTHER
  替代反射 PGobject，兼容 GraalVM native image；H2 测试路径保留 read-merge-write
- JdbcUserAccountRepository.parseJson/toJson: 失败时抛异常 + log.error，
  不再静默吞掉把偏好覆盖成 '{}'
- UserAccountRepository: 接口改名 updatePreferences → patchPreferences，写清合并语义
- UserCenterService: 删 Java 侧 read-merge-write，直接交给 repository 原子操作

Author: longsizhuo

src/main/java/com/involutionhell/backend/usercenter/controller/UserPreferencesController.java

@@ -0,0 +1,47 @@
+package com.involutionhell.backend.usercenter.controller;
+
+import cn.dev33.satoken.annotation.SaCheckLogin;
+import cn.dev33.satoken.stp.StpUtil;
+import com.involutionhell.backend.common.api.ApiResponse;
+import com.involutionhell.backend.usercenter.service.UserCenterService;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PatchMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.Map;
+
+/**
+ * 用户偏好读写接口，偏好以 JSONB 顶层合并方式存储，前端可自由扩展 key。
+ */
+@RestController
+@RequestMapping("/api/user-center")
+public class UserPreferencesController {
+
+    private final UserCenterService userCenterService;
+
+    public UserPreferencesController(UserCenterService userCenterService) {
+        this.userCenterService = userCenterService;
+    }
+
+    /**
+     * 获取当前登录用户的偏好，未设置时返回空对象。
+     */
+    @SaCheckLogin
+    @GetMapping("/preferences")
+    public ApiResponse<Map<String, Object>> getPreferences() {
+        long userId = StpUtil.getLoginIdAsLong();
+        return ApiResponse.ok(userCenterService.getPreferences(userId));
+    }
+
+    /**
+     * 合并更新当前登录用户的偏好，body 中的 key 覆盖已有同名 key，其余 key 保留。
+     */
+    @SaCheckLogin
+    @PatchMapping("/preferences")
+    public ApiResponse<Map<String, Object>> patchPreferences(@RequestBody Map<String, Object> patch) {
+        long userId = StpUtil.getLoginIdAsLong();
+        return ApiResponse.ok(userCenterService.patchPreferences(userId, patch));
+    }
+}

src/main/java/com/involutionhell/backend/usercenter/model/UserAccount.java

@@ -2,6 +2,7 @@
 
 import java.util.LinkedHashSet;
 import java.util.Locale;
+import java.util.Map;
 import java.util.Set;
 
 public record UserAccount(
@@ -12,24 +13,26 @@ public record UserAccount(
         boolean enabled,
         Set<String> roles,
         Set<String> permissions,
-        String avatarUrl,   // GitHub 头像 URL
-        String email,       // GitHub 邮箱（可为 null，GitHub 用户可设为私密）
-        Long githubId       // GitHub 数字 ID，用于 doc_contributors 贡献者追踪
+        String avatarUrl,           // GitHub 头像 URL
+        String email,               // GitHub 邮箱（可为 null，GitHub 用户可设为私密）
+        Long githubId,              // GitHub 数字 ID，用于 doc_contributors 贡献者追踪
+        Map<String, Object> preferences  // 用户偏好，JSONB 顶层 key 自由扩展
 ) {
 
     /**
-     * 创建用户对象时统一规范化角色与权限集合。
+     * 创建用户对象时统一规范化角色与权限集合，偏好为 null 时初始化为空 Map。
      */
     public UserAccount {
         roles = normalizeSet(roles);
         permissions = normalizeSet(permissions);
+        preferences = preferences != null ? preferences : Map.of();
     }
 
     /**
      * 基于当前用户信息生成一个新的授权快照。
      */
     public UserAccount withAuthorization(Set<String> newRoles, Set<String> newPermissions) {
-        return new UserAccount(id, username, passwordHash, displayName, enabled, newRoles, newPermissions, avatarUrl, email, githubId);
+        return new UserAccount(id, username, passwordHash, displayName, enabled, newRoles, newPermissions, avatarUrl, email, githubId, preferences);
     }
 
     /**

src/main/java/com/involutionhell/backend/usercenter/repository/JdbcUserAccountRepository.java

@@ -1,13 +1,20 @@
 package com.involutionhell.backend.usercenter.repository;
 
+import tools.jackson.core.type.TypeReference;
+import tools.jackson.databind.ObjectMapper;
 import com.involutionhell.backend.usercenter.model.UserAccount;
 
 import java.sql.PreparedStatement;
+import java.sql.Types;
 import java.util.Arrays;
+import java.util.HashMap;
 import java.util.HashSet;
 import java.util.List;
+import java.util.Map;
 import java.util.Optional;
 import java.util.Set;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 import org.springframework.jdbc.core.JdbcTemplate;
 import org.springframework.jdbc.core.RowMapper;
 import org.springframework.jdbc.support.GeneratedKeyHolder;
@@ -20,13 +27,19 @@
 @Repository
 public class JdbcUserAccountRepository implements UserAccountRepository {
 
+    private static final Logger log = LoggerFactory.getLogger(JdbcUserAccountRepository.class);
+
     private final JdbcTemplate jdbc;
+    private final ObjectMapper objectMapper;
+
+    private static final TypeReference<Map<String, Object>> MAP_TYPE = new TypeReference<>() {};
 
     /**
      * 将数据库行映射为 UserAccount 记录。
      * roles / permissions 以逗号分隔字符串存储，空字符串对应空集合。
+     * preferences 存为 JSONB（测试 H2 用 VARCHAR），读出后解析为 Map。
      */
-    private static final RowMapper<UserAccount> ROW_MAPPER = (rs, rowNum) -> new UserAccount(
+    private final RowMapper<UserAccount> rowMapper = (rs, rowNum) -> new UserAccount(
             rs.getLong("id"),
             rs.getString("username"),
             rs.getString("password_hash"),
@@ -36,30 +49,32 @@ public class JdbcUserAccountRepository implements UserAccountRepository {
             parseSet(rs.getString("permissions")),
             rs.getString("avatar_url"),
             rs.getString("email"),
-            rs.getObject("github_id", Long.class)  // nullable Long
+            rs.getObject("github_id", Long.class),
+            parseJson(rs.getString("preferences"))
     );
 
-    public JdbcUserAccountRepository(JdbcTemplate jdbc) {
+    public JdbcUserAccountRepository(JdbcTemplate jdbc, ObjectMapper objectMapper) {
         this.jdbc = jdbc;
+        this.objectMapper = objectMapper;
     }
 
     @Override
     public Optional<UserAccount> findById(Long id) {
         List<UserAccount> results = jdbc.query(
-                "SELECT * FROM user_accounts WHERE id = ?", ROW_MAPPER, id);
+                "SELECT * FROM user_accounts WHERE id = ?", rowMapper, id);
         return results.stream().findFirst();
     }
 
     @Override
     public Optional<UserAccount> findByUsername(String username) {
         List<UserAccount> results = jdbc.query(
-                "SELECT * FROM user_accounts WHERE username = ?", ROW_MAPPER, username);
+                "SELECT * FROM user_accounts WHERE username = ?", rowMapper, username);
         return results.stream().findFirst();
     }
 
     @Override
     public List<UserAccount> findAll() {
-        return jdbc.query("SELECT * FROM user_accounts ORDER BY id", ROW_MAPPER);
+        return jdbc.query("SELECT * FROM user_accounts ORDER BY id", rowMapper);
     }
 
     @Override
@@ -74,8 +89,11 @@ public UserAccount updateAuthorization(Long userId, Set<String> roles, Set<Strin
     @Override
     public UserAccount insert(UserAccount userAccount) {
         KeyHolder keyHolder = new GeneratedKeyHolder();
-        String sql = "INSERT INTO user_accounts (username, password_hash, display_name, enabled, roles, permissions, avatar_url, email, github_id) " +
-                     "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)";
+        // 把 preferences 一并写入 INSERT，避免创建用户时携带的初始偏好被丢弃
+        String sql = "INSERT INTO user_accounts (username, password_hash, display_name, enabled, roles, permissions, avatar_url, email, github_id, preferences) " +
+                     "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)";
+
+        String prefsJson = toJson(userAccount.preferences());
 
         jdbc.update(connection -> {
             PreparedStatement ps = connection.prepareStatement(sql, new String[]{"id"});
@@ -89,6 +107,8 @@ public UserAccount insert(UserAccount userAccount) {
             ps.setString(8, userAccount.email());
             // github_id 可为 null，用 setObject 处理
             ps.setObject(9, userAccount.githubId());
+            // jsonb 用 Types.OTHER 让 PostgreSQL 驱动自行识别；H2 会当作字符串处理
+            ps.setObject(10, prefsJson, Types.OTHER);
             return ps;
         }, keyHolder);
 
@@ -97,18 +117,9 @@ public UserAccount insert(UserAccount userAccount) {
             throw new IllegalStateException("插入用户失败，无法获取生成的 ID");
         }
 
-        return new UserAccount(
-                key.longValue(),
-                userAccount.username(),
-                userAccount.passwordHash(),
-                userAccount.displayName(),
-                userAccount.enabled(),
-                userAccount.roles(),
-                userAccount.permissions(),
-                userAccount.avatarUrl(),
-                userAccount.email(),
-                userAccount.githubId()
-        );
+        // 插入后回读整行，确保返回值与数据库一致，避免遗漏新列或字段漂移
+        return findById(key.longValue())
+                .orElseThrow(() -> new IllegalStateException("插入用户后无法读取回数据: id=" + key.longValue()));
     }
 
     @Override
@@ -121,6 +132,72 @@ public UserAccount updateProfile(Long userId, String displayName, String avatarU
                 .orElseThrow(() -> new IllegalArgumentException("用户不存在: " + userId));
     }
 
+    @Override
+    public Map<String, Object> findPreferences(Long userId) {
+        List<String> results = jdbc.query(
+                "SELECT preferences FROM user_accounts WHERE id = ?",
+                (rs, rn) -> rs.getString("preferences"),
+                userId);
+        if (results.isEmpty()) {
+            throw new IllegalArgumentException("用户不存在: " + userId);
+        }
+        return parseJson(results.get(0));
+    }
+
+    @Override
+    public Map<String, Object> patchPreferences(Long userId, Map<String, Object> patch) {
+        // 直接在 DB 端做原子 merge，避免 Java 侧 read-merge-write 的并发 lost update；
+        // 同时用 setObject + Types.OTHER，避开反射 PGobject 在 GraalVM native image 下
+        // reflection hints 未注册导致的启动失败。
+        //
+        // PostgreSQL：UPDATE ... SET preferences = preferences || ?::jsonb
+        //   使用 jsonb 原生 `||` 操作符做顶层 key 合并，单条语句原子完成
+        // H2（测试环境）：UPDATE ... SET preferences = ? （全量覆盖）
+        //   测试环境不追求并发正确性，由 service 层先 read-merge-write 保证合并语义
+        String patchJson = toJson(patch);
+        boolean isPostgres = isPostgres();
+
+        if (isPostgres) {
+            int updated = jdbc.update(connection -> {
+                var ps = connection.prepareStatement(
+                        "UPDATE user_accounts SET preferences = preferences || ?::jsonb WHERE id = ?");
+                ps.setObject(1, patchJson, Types.OTHER);
+                ps.setLong(2, userId);
+                return ps;
+            });
+            if (updated == 0) {
+                throw new IllegalArgumentException("用户不存在: " + userId);
+            }
+        } else {
+            // H2 路径：先读后合并再整体写入（测试环境无并发压力）
+            Map<String, Object> existing = findPreferences(userId);
+            Map<String, Object> merged = new HashMap<>(existing);
+            merged.putAll(patch);
+            String mergedJson = toJson(merged);
+            int updated = jdbc.update(
+                    "UPDATE user_accounts SET preferences = ? WHERE id = ?",
+                    mergedJson, userId);
+            if (updated == 0) {
+                throw new IllegalArgumentException("用户不存在: " + userId);
+            }
+        }
+
+        return findPreferences(userId);
+    }
+
+    /** 判断当前数据源是否为 PostgreSQL（通过驱动名识别）。 */
+    private boolean isPostgres() {
+        try {
+            return Boolean.TRUE.equals(jdbc.execute((java.sql.Connection c) -> {
+                String name = c.getMetaData().getDriverName();
+                return name != null && name.toLowerCase().contains("postgresql");
+            }));
+        } catch (Exception e) {
+            log.warn("检测数据源驱动失败，按非 PostgreSQL 兜底: {}", e.getMessage());
+            return false;
+        }
+    }
+
     /**
      * 将逗号分隔字符串解析为集合，空串返回空集合。
      */
@@ -140,4 +217,34 @@ private static String joinSet(Set<String> values) {
         }
         return String.join(",", values);
     }
-}
+
+    /**
+     * 将 JSON 字符串解析为 Map。
+     * null / 空串 / "{}" 视为"未设置"返回空 Map；解析失败（数据库里脏数据）则抛出异常，
+     * 避免静默吞错，让调用方感知并由全局异常处理器返回 500。
+     */
+    private Map<String, Object> parseJson(String json) {
+        if (json == null || json.isBlank() || "{}".equals(json.trim())) {
+            return new HashMap<>();
+        }
+        try {
+            return objectMapper.readValue(json, MAP_TYPE);
+        } catch (Exception e) {
+            log.error("解析 preferences JSON 失败，数据可能已损坏: {}", json, e);
+            throw new IllegalStateException("解析 preferences 失败", e);
+        }
+    }
+
+    /**
+     * 将 Map 序列化为 JSON 字符串。
+     * 失败时抛出异常而不是返回 "{}"，避免把有问题的偏好当成空偏好静默覆盖掉原有数据。
+     */
+    private String toJson(Map<String, Object> map) {
+        try {
+            return objectMapper.writeValueAsString(map);
+        } catch (Exception e) {
+            log.error("序列化 preferences 失败: {}", map, e);
+            throw new IllegalStateException("序列化 preferences 失败", e);
+        }
+    }
+}

src/main/java/com/involutionhell/backend/usercenter/repository/UserAccountRepository.java

@@ -2,6 +2,7 @@
 
 import com.involutionhell.backend.usercenter.model.UserAccount;
 import java.util.List;
+import java.util.Map;
 import java.util.Optional;
 import java.util.Set;
 
@@ -39,4 +40,16 @@ public interface UserAccountRepository {
      * 更新 GitHub 用户的个人资料（展示名、头像、邮箱、GitHub ID），每次登录时刷新。
      */
     UserAccount updateProfile(Long userId, String displayName, String avatarUrl, String email, Long githubId);
+
+    /**
+     * 查询指定用户的偏好 Map，用户不存在时抛 IllegalArgumentException。
+     */
+    Map<String, Object> findPreferences(Long userId);
+
+    /**
+     * 以 patch 为单位在数据库端原子合并用户偏好（顶层 key 覆盖），返回合并后的全量偏好。
+     * PostgreSQL 实现走 `preferences || ?::jsonb` 单条 UPDATE，避免并发 lost update；
+     * H2 走 read-merge-write 路径兼容测试。
+     */
+    Map<String, Object> patchPreferences(Long userId, Map<String, Object> patch);
 }

src/main/java/com/involutionhell/backend/usercenter/service/AuthService.java

@@ -81,7 +81,8 @@ public LoginResponse loginByGithub(AuthUser githubUser) {
                     Set.of(),       // 默认权限
                     avatarUrl,
                     email,
-                    githubId
+                    githubId,
+                    null            // 偏好由数据库默认值初始化为 {}
             );
             return userCenterService.createUser(newUser);
         });

src/main/java/com/involutionhell/backend/usercenter/service/UserCenterService.java

@@ -8,6 +8,7 @@
 import org.springframework.stereotype.Service;
 
 import java.util.List;
+import java.util.Map;
 import java.util.Optional;
 
 @Service
@@ -80,4 +81,19 @@ public UserView updateAuthorization(Long userId, UserAuthorizationUpdateRequest
         );
         return UserView.from(updatedAccount);
     }
+
+    /**
+     * 获取指定用户的偏好 Map，未设置时返回空 Map。
+     */
+    public Map<String, Object> getPreferences(Long userId) {
+        return userAccountRepository.findPreferences(userId);
+    }
+
+    /**
+     * 将 patch 合并进用户偏好（顶层 key 覆盖），返回更新后全量偏好。
+     * 合并原子性由 repository 层保证（PostgreSQL 用 jsonb 原生 `||` 单条 UPDATE，避免并发 lost update）。
+     */
+    public Map<String, Object> patchPreferences(Long userId, Map<String, Object> patch) {
+        return userAccountRepository.patchPreferences(userId, patch);
+    }
 }

src/main/resources/schema.sql

@@ -14,6 +14,9 @@ CREATE TABLE IF NOT EXISTS user_accounts (
     github_id     BIGINT       UNIQUE
 );
 
+-- 偏好设置列（JSONB 顶层合并，前端可自由扩展 key）
+ALTER TABLE user_accounts ADD COLUMN IF NOT EXISTS preferences JSONB NOT NULL DEFAULT '{}'::jsonb;
+
 -- 默认种子账号（已存在则跳过）
 -- admin / Admin@123456
 -- alice / Alice@123456