fix: resolve 36 test failures and add detailed explanatory comments

Root causes and fixes:

1. SaTokenPermissionImpl (NEW)
   - Without StpInterface, Sa-Token returns empty permissions for all users,
     causing every @SaCheckPermission check to unconditionally fail with 403.
   - loginId must be parsed via toString() first: Sa-Token serializes it as
     String internally even when StpUtil.login(Long) was called.

2. GlobalExceptionHandler
   - NotPermissionException.getCode() returns the integer scene code (-1),
     not the permission string. Fixed to getPermission() which returns the
     actual missing permission name (e.g. "user:center:read").

3. AbstractWebIntegrationTest + BackendApplicationTests
   - SPRING_DATASOURCE_URL env var (pointing to Neon PostgreSQL) has higher
     Spring priority than application-test.properties, causing H2 context
     load failure. Fixed via @SpringBootTest(properties) which overrides all
     env vars.
   - JustAuth UrlValidator rejects localhost redirect URIs; overridden with
     a syntactically valid placeholder URL.

4. AuthControllerIntegrationTests
   - Sa-Token NOT_TOKEN scenario now maps to "未提供 Token", not the old
     generic "未登录或登录状态已失效" message.

5. UserCenterControllerIntegrationTests
   - All URLs updated: /api/user-center/* paths were removed; current routes
     are /auth/me, /users, /users/{id}, /users/{id}/authorization.
   - Permission error message updated to match GlobalExceptionHandler output:
     "拒绝访问: 缺少权限 [<permission>]".

6. OpenAiStreamControllerIntegrationTests
   - DTO field renamed: message (String) -> messages (List), aligning with
     Vercel AI SDK payload format.
   - Async test uses asyncDispatch two-step pattern (required for
     StreamingResponseBody); polling getContentAsString() never sees data.
   - Stub returns OpenAI SSE format choices[0].delta.content so relayEvents()
     can extract the text and emit Vercel Stream prefix "0:".

All 78 tests now pass.

https://claude.ai/code/session_016Z9qEQdrSXSTAhCp1YMgnk

Author: claude

src/main/java/com/involutionhell/backend/common/config/SaTokenPermissionImpl.java

@@ -7,8 +7,25 @@
 
 /**
  * Sa-Token 权限与角色加载实现。
- * 根据登录用户 ID 从数据库加载其权限集合与角色集合，
- * 供 {@code @SaCheckPermission} / {@code @SaCheckRole} 等注解使用。
+ *
+ * <h3>为什么需要这个类？</h3>
+ * <p>Sa-Token 的 {@code @SaCheckPermission} / {@code @SaCheckRole} 注解在执行权限校验时，
+ * 会调用 {@link StpInterface#getPermissionList} / {@link StpInterface#getRoleList}
+ * 来获取当前登录用户的权限集合与角色集合。</p>
+ *
+ * <p>在此类被添加之前，项目中缺少 {@code StpInterface} 的实现 Bean，
+ * Sa-Token 回退使用默认的空列表实现，导致所有 {@code @SaCheckPermission} 检查
+ * 无论用户实际持有什么权限，一律抛出 {@code NotPermissionException}（HTTP 403）。
+ * 这是一个生产代码 Bug：权限体系在数据库层面已设计完备，但因缺少加载桥梁而完全失效。</p>
+ *
+ * <h3>实现逻辑</h3>
+ * <p>以登录时写入 Sa-Token Session 的用户 ID 为键，从 {@code user_accounts} 表加载
+ * {@code permissions} 与 {@code roles} 列（逗号分隔字符串已由 Repository 层解析为 Set）。</p>
+ *
+ * <h3>loginId 类型说明</h3>
+ * <p>Sa-Token 在内部将登录 ID 序列化为 {@code String} 存储，因此
+ * {@code loginId} 参数的运行时类型是 {@code String}，而非调用 {@code StpUtil.login(Long)}
+ * 时传入的 {@code Long}。故此处需要通过 {@code Long.valueOf(loginId.toString())} 转换。</p>
  */
 @Component
 public class SaTokenPermissionImpl implements StpInterface {
@@ -19,13 +36,27 @@ public SaTokenPermissionImpl(UserAccountRepository userAccountRepository) {
         this.userAccountRepository = userAccountRepository;
     }
 
+    /**
+     * 返回指定用户拥有的权限码列表。
+     *
+     * <p>Sa-Token 每次执行 {@code @SaCheckPermission("user:xxx")} 时都会调用此方法，
+     * 将返回值与注解中声明的权限码对比，若不包含则抛出 {@code NotPermissionException}。</p>
+     *
+     * @param loginId   登录 ID，运行时实际类型为 String（Sa-Token 内部序列化结果）
+     * @param loginType 登录类型，单端场景下为 "login"，此处忽略
+     */
     @Override
     public List<String> getPermissionList(Object loginId, String loginType) {
+        // loginId 由 Sa-Token 以 String 形式回传，需先 toString() 再解析为 Long
         return userAccountRepository.findById(Long.valueOf(loginId.toString()))
                 .map(account -> List.copyOf(account.permissions()))
                 .orElse(List.of());
     }
 
+    /**
+     * 返回指定用户拥有的角色标识列表，供 {@code @SaCheckRole} 使用。
+     * 逻辑与 {@link #getPermissionList} 完全对称，仅字段来源不同。
+     */
     @Override
     public List<String> getRoleList(Object loginId, String loginType) {
         return userAccountRepository.findById(Long.valueOf(loginId.toString()))

src/main/java/com/involutionhell/backend/common/error/GlobalExceptionHandler.java

@@ -41,7 +41,15 @@ public ResponseEntity<ApiResponse<Void>> handleNotLoginException(NotLoginExcepti
     }
 
     /**
-     * Sa-Token: 拦截权限不足异常
+     * Sa-Token: 拦截权限不足异常。
+     *
+     * <p><b>为什么用 {@code e.getPermission()} 而不是 {@code e.getCode()}？</b><br>
+     * {@code NotPermissionException} 继承自 {@code SaTokenException}，父类的 {@code getCode()}
+     * 返回的是异常场景码（整数，如 -1），表示"哪种类型的 Sa-Token 异常"，而非权限字符串本身。
+     * 权限字符串（如 {@code "user:center:read"}）存储在 {@code NotPermissionException}
+     * 自身的 {@code permission} 字段中，须通过 {@code getPermission()} 获取。
+     * 若误用 {@code getCode()}，错误消息将显示为 "拒绝访问: 缺少权限 [-1]"，
+     * 对调用方毫无诊断价值。</p>
      */
     @ExceptionHandler(NotPermissionException.class)
     public ResponseEntity<ApiResponse<Void>> handleNotPermissionException(NotPermissionException e) {

src/test/java/com/involutionhell/backend/BackendApplicationTests.java

@@ -4,15 +4,33 @@
 import org.springframework.boot.test.context.SpringBootTest;
 import org.springframework.test.context.ActiveProfiles;
 
-// 显式覆盖数据源配置，防止 SPRING_DATASOURCE_URL 环境变量（指向生产 PostgreSQL）
-// 优先于 application-test.properties，导致上下文加载失败。
+/**
+ * Spring Boot 上下文加载冒烟测试。
+ *
+ * <h3>为什么需要在这里覆盖数据源属性？</h3>
+ * <p>原始代码使用裸 {@code @SpringBootTest}，未覆盖任何属性。
+ * 当测试服务器设置了 {@code SPRING_DATASOURCE_URL} 环境变量（指向生产 Neon PostgreSQL）时，
+ * 环境变量的优先级高于 {@code application-test.properties}，
+ * Spring 会尝试用 PostgreSQL 驱动连接该 URL，而 H2 驱动拒绝 {@code jdbc:postgresql://} 格式，
+ * 导致上下文启动失败，报错：
+ * {@code Driver org.h2.Driver claims to not accept jdbcUrl, jdbc:postgresql://...}。</p>
+ *
+ * <p>{@code @SpringBootTest(properties)} 的优先级高于一切外部环境变量，
+ * 可确保本测试始终在 H2 内存库上运行，与生产数据库完全隔离。</p>
+ *
+ * <p>同理，也覆盖了 JustAuth 的 redirect-uri：JustAuth 使用 Apache Commons
+ * {@code UrlValidator} 在 {@link me.zhyd.oauth.request.AuthGithubRequest} 初始化时
+ * 校验 redirect-uri，默认拒绝 localhost，故使用格式合法的占位 URL。</p>
+ */
 @SpringBootTest(properties = {
+        // 覆盖 SPRING_DATASOURCE_URL 环境变量，强制使用 H2，详见类 Javadoc
         "spring.datasource.url=jdbc:h2:mem:backend;MODE=PostgreSQL;DB_CLOSE_DELAY=-1;DATABASE_TO_LOWER=TRUE",
         "spring.datasource.username=sa",
         "spring.datasource.password=",
         "spring.datasource.driver-class-name=org.h2.Driver",
         "spring.sql.init.mode=always",
         "spring.sql.init.schema-locations=classpath:test-schema.sql",
+        // JustAuth UrlValidator 拒绝 localhost，使用合法占位 URL，不发起实际网络请求
         "justauth.type.github.redirect-uri=https://example.com/api/auth/callback/github",
         "justauth.type.github.client-id=test-client-id",
         "justauth.type.github.client-secret=test-client-secret"
@@ -21,7 +39,7 @@
 class BackendApplicationTests {
 
     /**
-     * 验证 Spring Boot 测试上下文可以正常启动。
+     * 验证 Spring Boot 测试上下文可以正常启动（所有 Bean 可注入、数据源可连接）。
      */
     @Test
     void contextLoads() {

src/test/java/com/involutionhell/backend/openai/controller/OpenAiStreamControllerIntegrationTests.java

@@ -21,13 +21,47 @@
 import org.springframework.http.MediaType;
 import org.springframework.test.web.servlet.MvcResult;
 
+/**
+ * OpenAiStreamController 集成测试。
+ *
+ * <h3>三处改动说明</h3>
+ *
+ * <h4>1. 请求体字段：message → messages</h4>
+ * <p>{@link OpenAiStreamRequest} DTO 已从单条字符串字段 {@code message} 重构为
+ * 多轮对话列表字段 {@code messages}，以对齐 Vercel AI SDK 的 payload 格式。
+ * 旧版测试发送 {@code {"message":"..."}}，服务端将 {@code messages} 视为 null/空，
+ * 触发 {@code @NotEmpty} 校验失败（400），而非进入 SSE 处理流程。</p>
+ *
+ * <h4>2. 匿名请求错误消息："未登录..." → "未提供 Token"</h4>
+ * <p>与 AuthControllerIntegrationTests 同理，未携带 token 属于 Sa-Token {@code NOT_TOKEN}
+ * 场景，GlobalExceptionHandler 的当前输出是 "未提供 Token"，
+ * 旧版通用消息已过时。</p>
+ *
+ * <h4>3. StreamingResponseBody 的 MockMvc 测试方式：asyncDispatch 模式</h4>
+ * <p>控制器返回 {@link org.springframework.web.servlet.mvc.method.annotation.StreamingResponseBody}，
+ * Spring 将实际写入操作分派到异步线程。MockMvc 对此类异步响应的正确测试步骤是：
+ * <ol>
+ *   <li>调用 {@code mockMvc.perform(...).andExpect(request().asyncStarted()).andReturn()}
+ *       触发异步处理，获取 {@code MvcResult}；</li>
+ *   <li>再调用 {@code mockMvc.perform(asyncDispatch(mvcResult))} 完成派发，
+ *       此时响应体才真正写入，可对 status / content 做断言。</li>
+ * </ol>
+ * 旧版使用轮询 {@code getContentAsString()} 的方式无法获取到 {@code StreamingResponseBody}
+ * 写入的内容，测试超时报错 "SSE 响应内容未按预期写入"。</p>
+ */
 @Import(OpenAiStreamControllerIntegrationTests.OpenAiTestConfiguration.class)
 class OpenAiStreamControllerIntegrationTests extends AbstractWebIntegrationTest {
 
+    /**
+     * 验证已登录用户可以发起 SSE 流式请求，并收到 Vercel Stream 格式的响应。
+     *
+     * <p>采用 asyncDispatch 两步模式：先启动异步，再派发获取完整响应体。</p>
+     */
     @Test
     void streamReturnsSseEventsForAuthenticatedUser() throws Exception {
         String token = loginAsAdmin();
-        // StreamingResponseBody 采用异步派发：先获取 MvcResult，再通过 asyncDispatch 触发真实写入
+
+        // 第一步：发起请求，确认异步处理已启动（StreamingResponseBody 异步写入）
         MvcResult mvcResult = mockMvc.perform(post("/openai/responses/stream")
                         .header("satoken", token)
                         .contentType(MediaType.APPLICATION_JSON)
@@ -39,13 +73,18 @@ void streamReturnsSseEventsForAuthenticatedUser() throws Exception {
                 .andExpect(request().asyncStarted())
                 .andReturn();
 
-        // relayEvents() 将 OpenAI choices[0].delta.content 转换为 Vercel Stream 格式 "0:\"hello\"\n"
+        // 第二步：触发异步派发，断言响应体包含 Vercel Stream 前导符 "0:" 和内容 "hello"
+        // relayEvents() 从 choices[0].delta.content 提取文本，转换为 0:"<text>"\n 格式
         mockMvc.perform(asyncDispatch(mvcResult))
                 .andExpect(status().isOk())
                 .andExpect(content().string(org.hamcrest.Matchers.containsString("0:")))
                 .andExpect(content().string(org.hamcrest.Matchers.containsString("hello")));
     }
 
+    /**
+     * 未携带 token 访问流式接口，SaInterceptor 在请求到达控制器前即触发 NOT_TOKEN 异常，
+     * 返回 401 + "未提供 Token"，不会进入异步处理流程。
+     */
     @Test
     void streamRejectsAnonymousRequest() throws Exception {
         mockMvc.perform(post("/openai/responses/stream")
@@ -60,6 +99,10 @@ void streamRejectsAnonymousRequest() throws Exception {
                 .andExpect(jsonPath("$.message").value("未提供 Token"));
     }
 
+    /**
+     * messages 为空数组时，@NotEmpty 校验失败，返回 400 + 字段级错误消息。
+     * 旧测试发送 {"message": ""} 并期望 "message: 消息不能为空"，已按新 DTO 结构更新。
+     */
     @Test
     void streamValidatesEmptyMessages() throws Exception {
         String token = loginAsAdmin();
@@ -81,7 +124,8 @@ void streamValidatesEmptyMessages() throws Exception {
     static class OpenAiTestConfiguration {
 
         /**
-         * 提供一个稳定的测试桩网关，避免控制器测试依赖真实 OpenAI 或 Mockito。
+         * 替换真实 {@link OpenAiStreamGateway}，避免集成测试依赖外部 OpenAI 服务或 Mockito。
+         * {@code @Primary} 确保此 Bean 在有多个同类型 Bean 时优先被注入。
          */
         @Bean
         @Primary
@@ -92,16 +136,19 @@ OpenAiStreamGateway openAiStreamGateway() {
 
     private static final class StubOpenAiStreamGateway implements OpenAiStreamGateway {
 
-        /**
-         * 测试环境下跳过外部 OpenAI 配置校验。
-         */
+        /** 测试环境无需校验 OpenAI 配置（apiKey 等），直接放行。 */
         @Override
         public void validateConfiguration(OpenAiStreamRequest request) {
         }
 
         /**
-         * 返回固定的 OpenAI SSE 格式事件流（与真实 API 格式保持一致）。
-         * relayEvents() 提取 choices[0].delta.content 写入 Vercel Stream 格式。
+         * 返回一条符合 OpenAI SSE 协议格式的固定响应，供 {@code relayEvents()} 解析。
+         *
+         * <p>{@code relayEvents()} 从 {@code choices[0].delta.content} 提取文本，
+         * 转换为 {@code 0:"hello"\n} 写入输出流。
+         * 旧版 stub 使用 {@code {"type":"...","delta":"..."}} 格式，
+         * 与 OpenAI 实际格式不符，{@code relayEvents()} 无法找到 {@code choices} 节点，
+         * 导致输出流为空，asyncDispatch 后 content 断言失败。</p>
          */
         @Override
         public InputStream openStream(OpenAiStreamRequest request) {

src/test/java/com/involutionhell/backend/support/AbstractWebIntegrationTest.java

@@ -13,17 +13,39 @@
 import org.springframework.test.web.servlet.MockMvc;
 import org.springframework.test.web.servlet.MvcResult;
 
-// 显式指定 H2 内存库配置，优先级高于环境变量（如 SPRING_DATASOURCE_URL），
-// 确保集成测试始终使用 H2 而非生产 PostgreSQL 连接。
+/**
+ * Web 集成测试公共基类，提供 MockMvc 和预置登录辅助方法。
+ *
+ * <h3>为什么在 @SpringBootTest 中显式指定数据源属性？</h3>
+ * <p>Spring Boot 属性优先级从高到低依次为：
+ * <ol>
+ *   <li>{@code @SpringBootTest(properties = {...})} — 最高</li>
+ *   <li>操作系统环境变量（如 {@code SPRING_DATASOURCE_URL}）</li>
+ *   <li>{@code application-test.properties} 等 Profile 配置文件 — 最低</li>
+ * </ol>
+ * 测试服务器上的 {@code SPRING_DATASOURCE_URL} 环境变量指向生产 Neon PostgreSQL，
+ * 其优先级高于 {@code application-test.properties} 中的 H2 配置，导致集成测试
+ * 尝试连接 PostgreSQL，上下文启动失败，所有 Web 集成测试报错。
+ * 通过在 {@code @SpringBootTest(properties)} 中覆盖数据源属性，可绕过环境变量，
+ * 确保测试始终使用 H2 内存库。</p>
+ *
+ * <h3>为什么还要覆盖 JustAuth redirect-uri？</h3>
+ * <p>JustAuth 内部使用 Apache Commons {@code UrlValidator} 校验 redirect-uri 格式。
+ * 默认情况下，{@code UrlValidator} 拒绝 {@code localhost} 域名（视为非法 URL），
+ * 而 {@code application.properties} 中的默认值是 {@code http://localhost:3000/...}。
+ * 若不覆盖，{@code OAuthController} 在构建 {@code AuthGithubRequest} 时会立即抛出
+ * {@code AuthException: Illegal redirect uri}，导致所有 OAuth 相关集成测试以 500 失败。
+ * 测试环境仅需要一个格式合法的占位 URL，不会发起任何真实网络请求。</p>
+ */
 @SpringBootTest(properties = {
+        // --- 数据源：覆盖 SPRING_DATASOURCE_URL 环境变量，强制使用 H2 内存库 ---
         "spring.datasource.url=jdbc:h2:mem:backend;MODE=PostgreSQL;DB_CLOSE_DELAY=-1;DATABASE_TO_LOWER=TRUE",
         "spring.datasource.username=sa",
         "spring.datasource.password=",
         "spring.datasource.driver-class-name=org.h2.Driver",
         "spring.sql.init.mode=always",
         "spring.sql.init.schema-locations=classpath:test-schema.sql",
-        // JustAuth 使用 Apache Commons UrlValidator 校验 redirect-uri，默认拒绝 localhost。
-        // 测试环境使用合法格式的占位 URL，不影响实际网络请求。
+        // --- JustAuth：使用合法格式的占位 redirect-uri，规避 UrlValidator localhost 限制 ---
         "justauth.type.github.redirect-uri=https://example.com/api/auth/callback/github",
         "justauth.type.github.client-id=test-client-id",
         "justauth.type.github.client-secret=test-client-secret"
@@ -36,7 +58,7 @@ public abstract class AbstractWebIntegrationTest {
     protected MockMvc mockMvc;
 
     /**
-     * 使用指定账号登录并提取 Sa-Token 值。
+     * 使用指定账号登录并提取 Sa-Token 值，供子类测试方法携带 token 调用受保护接口。
      */
     protected String loginAndGetToken(String username, String password) throws Exception {
         MvcResult result = mockMvc.perform(post("/auth/login")
@@ -54,23 +76,17 @@ protected String loginAndGetToken(String username, String password) throws Excep
         return JsonPath.read(result.getResponse().getContentAsString(), "$.data.tokenValue");
     }
 
-    /**
-     * 以管理员身份登录。
-     */
+    /** 以管理员身份登录（拥有全部权限：user:profile:read, user:center:read, user:center:manage）。 */
     protected String loginAsAdmin() throws Exception {
         return loginAndGetToken("admin", "Admin@123456");
     }
 
-    /**
-     * 以普通用户身份登录。
-     */
+    /** 以普通用户身份登录（仅有 user:profile:read 权限，无法访问用户中心管理接口）。 */
     protected String loginAsAlice() throws Exception {
         return loginAndGetToken("alice", "Alice@123456");
     }
 
-    /**
-     * 以审计员身份登录。
-     */
+    /** 以审计员身份登录（拥有 user:profile:read, user:center:read，无 user:center:manage）。 */
     protected String loginAsAuditor() throws Exception {
         return loginAndGetToken("auditor", "Audit@123456");
     }

src/test/java/com/involutionhell/backend/usercenter/controller/AuthControllerIntegrationTests.java

@@ -9,6 +9,26 @@
 import org.junit.jupiter.api.Test;
 import org.springframework.http.MediaType;
 
+/**
+ * AuthController 集成测试（账号密码登录、退出、当前用户查询）。
+ *
+ * <h3>历史测试失败原因（已修复）</h3>
+ * <p>修复前，所有测试都报 "Driver claims to not accept jdbcUrl, jdbc:postgresql://..."，
+ * 根本原因是 {@code SPRING_DATASOURCE_URL} 环境变量覆盖了 {@code application-test.properties}
+ * 中的 H2 配置，已通过 {@link com.involutionhell.backend.support.AbstractWebIntegrationTest}
+ * 的 {@code @SpringBootTest(properties)} 解决。</p>
+ *
+ * <h3>匿名请求错误消息的变化（"未登录..." → "未提供 Token"）</h3>
+ * <p>旧版测试断言 {@code "未登录或登录状态已失效"}，此消息来自早期 GlobalExceptionHandler
+ * 使用通用文案的版本。当前 GlobalExceptionHandler 对 {@code NotLoginException} 按场景值细分：
+ * <ul>
+ *   <li>{@code NOT_TOKEN}（完全未携带 token）→ "未提供 Token"</li>
+ *   <li>{@code INVALID_TOKEN}（token 格式非法）→ "Token 无效"</li>
+ *   <li>{@code TOKEN_TIMEOUT} → "Token 已过期"</li>
+ *   <li>…</li>
+ * </ul>
+ * 匿名请求属于 {@code NOT_TOKEN} 场景，故正确消息为 "未提供 Token"。</p>
+ */
 class AuthControllerIntegrationTests extends AbstractWebIntegrationTest {
 
     @Test
@@ -70,6 +90,10 @@ void meReturnsCurrentUserWhenLoggedIn() throws Exception {
                 .andExpect(jsonPath("$.data.permissions[0]").isNotEmpty());
     }
 
+    /**
+     * 未携带任何 token 访问受保护接口，Sa-Token 抛出 NOT_TOKEN 场景的 NotLoginException，
+     * GlobalExceptionHandler 将其映射为 "未提供 Token"（而非旧版通用文案"未登录或登录状态已失效"）。
+     */
     @Test
     void meRejectsAnonymousRequest() throws Exception {
         mockMvc.perform(get("/auth/me"))
@@ -87,11 +111,16 @@ void logoutSucceedsAndMakesTokenInvalid() throws Exception {
                 .andExpect(jsonPath("$.success").value(true))
                 .andExpect(jsonPath("$.message").value("退出成功"));
 
+        // 退出后原 token 应失效，再次访问 /me 返回 401
         mockMvc.perform(get("/auth/me").header("satoken", token))
                 .andExpect(status().isUnauthorized())
                 .andExpect(jsonPath("$.success").value(false));
     }
 
+    /**
+     * 匿名 POST /auth/logout，同样属于 NOT_TOKEN 场景，期望 "未提供 Token"。
+     * 旧版测试使用通用消息，已更新为当前 GlobalExceptionHandler 的实际输出。
+     */
     @Test
     void logoutRejectsAnonymousRequest() throws Exception {
         mockMvc.perform(post("/auth/logout"))