@alanwang-merit/meritdata-platform-skill-package 1.0.9 → 1.0.11

package/skills/meritdata-platform-session/references/session.md

@@ -0,0 +1,125 @@
+## 前置条件
+
+Maven 依赖已包含在 `cloud-starter-core` 基础包中，二开项目继承平台脚手架后自动引入，无需额外配置。
+
+---
+
+## SessionUtils — 会话工具类
+
+**完整包路径**: `com.meritdata.cloud.utils.SessionUtils`
+
+通过依赖注入使用：
+
+```java
+@Autowired
+private SessionUtils sessionUtils;
+```
+
+> **注意**: `getUserName()` 和 `getCurrentUserName()` 方法均可用，返回相同结果。
+
+### 用户信息
+
+| 方法 | 返回 | 说明 |
+|------|------|------|
+| `getUserId()` | String | 用户 ID（`pf_user_info.id`） |
+| `getUserName()` | String | 用户名 |
+| `getCurrentUserName()` | String | 用户名（同 getUserName） |
+| `getPrincipal()` | User | 整个用户对象 |
+
+```java
+String userId = sessionUtils.getUserId();
+String userName = sessionUtils.getUserName();
+User user = sessionUtils.getPrincipal();
+```
+
+### 人员信息
+
+| 方法 | 返回 | 说明 |
+|------|------|------|
+| `getEmpId()` | String | 人员 ID（`pf_org_user.id`） |
+| `getEmpName()` | String | 人员姓名 |
+| `getEmpCode()` | String | 人员编号 |
+
+```java
+String empId = sessionUtils.getEmpId();
+String empName = sessionUtils.getEmpName();
+String empCode = sessionUtils.getEmpCode();
+```
+
+### 部门信息
+
+| 方法 | 返回 | 说明 |
+|------|------|------|
+| `getDeptId()` | String | 部门 ID |
+| `getDeptCode()` | String | 部门编码 |
+| `getDeptName()` | String | 部门名称 |
+| `getDept()` | Organization | 部门对象 |
+
+```java
+String deptId = sessionUtils.getDeptId();
+Organization dept = sessionUtils.getDept();
+String deptName = dept.getName();
+```
+
+### 组织信息
+
+| 方法 | 返回 | 说明 |
+|------|------|------|
+| `getOrgId()` | String | 组织 ID |
+| `getOrgName()` | String | 组织名称 |
+| `getOrgDlevelCode()` | String | 组织层级编码 |
+| `getRootOrgId()` | String | 根组织 ID |
+| `getRootOrg()` | Organization | 根组织对象 |
+
+```java
+String orgId = sessionUtils.getOrgId();
+Organization rootOrg = sessionUtils.getRootOrg();
+```
+
+### 角色与权限
+
+| 方法 | 返回 | 说明 |
+|------|------|------|
+| `getSysRoleCodes()` | List\<String\> | 系统角色编码列表 |
+| `getRoleCodes()` | List\<String\> | 所有角色编码列表 |
+| `getRoleNames()` | List\<String\> | 所有角色名称列表 |
+| `getAuthoritiesIds()` | List\<String\> | 所有权限 ID 列表 |
+
+### 租户与登录信息
+
+| 方法 | 返回 | 说明 |
+|------|------|------|
+| `getTenantId()` | String | 租户 ID |
+| `getCurrentLoginIp()` | String | 当前登录 IP |
+
+---
+
+## IUserOnlineTime — 在线用户管理
+
+**完整包路径**: `com.meritdata.cloud.security.sso.IUserOnlineTime`
+
+Feign 客户端接口，通过依赖注入使用：
+
+```java
+@Autowired
+private IUserOnlineTime iUserOnlineTime;
+```
+
+### 踢出在线用户
+
+**接口**: `POST /api/basic/online-account/getOutOnlineByUserNames`
+
+批量踢出指定用户名的在线用户，清除其所有会话信息。
+
+这是高影响操作。调用前确认操作权限、目标用户名和业务影响，并记录操作者、原因与结果。
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| userNames | String | 用户名，多个用逗号分隔 |
+
+---
+
+## 会话注意事项
+
+1. `SessionUtils` 通过 `@Autowired` 注入，不是静态工具类
+2. `IUserOnlineTime` 是 Feign 远程调用，踢出操作会记录登录日志（`loginOut` 类型）

package/skills/meritdata-platform-sso/SKILL.md

@@ -1,41 +1,59 @@
 ---
 name: meritdata-platform-sso
-description: |
-  SSO 单点登录。OAuth2/CAS 接入、Token 管理、过滤器配置、跳转登录、退出登录、Token 刷新、跨域。
-  触发场景：新二开模块接入平台 SSO；需要统一登录态；对接第三方 OAuth（微信/钉钉/企业微信）。
-  何时不用：纯前端登录 → 用 frontend；权限点控制 → L3 资源授权（待建）。
+description: MeritData SSO/CAS 单点登录接入。用于多应用统一登录、会话共享、Token 透传、CAS 协议对接。
 metadata:
   version: "1.0.0"
-  author: petroleum+rd
-  source: petroleum+rd
-  date_added: "2026-09-07"
-  last_modified: "2026-09-07"
-  risk: high
-  layer: L2
-  sub-layer: L2-C
-  stack: java
-allowed-tools: Read, Grep, Glob, Bash
+  author: 技术平台部门架构组
+  source: company
+  date_added: "2026-09-01"
+  last_updated: "2026-09-01"
+  risk: medium
+  allowed-tools: Read, Grep, Glob
 ---
 
-# SSO 单点登录（sso）
+## ⭐ MUST DO
 
-## 触发
-- 新二开模块需要接入平台 SSO
-- 需要对接第三方 OAuth（微信/钉钉/企业微信）
-- 需要 Token 刷新 / 跨域登录
-- 需要统一退出登录
+**SSO Token 通过 Header 传递，禁止 URL 携带；登出必须调用中心会话失效接口。**
 
-## 不触发
-- 纯前端样式调整 → 用 `meritdata-platform-frontend`
-- 资源/数据权限控制 → L3 资源授权（待建）
-- 已登录态使用 → 用 `meritdata-platform-entities` 获取 UserDTO
+## 触发条件 / 不适用
 
-## 前置约束
-- Token **禁止**写入 URL（详见 [rules/security-rules.md](../../rules/security-rules.md)）
-- 认证失败提示信息**不能过于详细**（不能区分"密码错误"vs"用户不存在"）
-- 敏感操作（修改密码/绑定手机）必须二次认证
+**适用**：
+- 多应用统一登录
+- CAS 协议对接
+- Token 透传与校验
 
-## 路由
-- SSO 接入流程 + Token 管理 → [references/sso-guide.md](references/sso-guide.md)
-- 第三方 OAuth 接入 → [references/oauth-providers.md](references/oauth-providers.md)
-- 过滤器配置 + 拦截规则 → [references/filter-config.md](references/filter-config.md)
+**不适用**：
+- 单应用 Session → `meritdata-platform-session`
+- 平台基础会话 → `meritdata-platform-core`
+
+## 主题路由
+
+| 任务 | 优先读取 |
+| --- | --- |
+
+### 公司级研发攻略（dev-docs 整合）
+
+| 攻略 | 内容 | 入口 |
+|------|------|------|
+| **攻略06：系统认证（6 章）** | token 认证集成、CAS 统一认证中心、第三方认证 | [`references/auth/攻略-06-系统认证-00_总览.md`](references/auth/攻略-06-系统认证-00_总览.md) |
+
+## 工作方式
+
+1. 确认 SSO 服务地址（cas.example.com）
+2. 配置 Filter 拦截未登录请求
+3. 登录后从 SSO 获取 ticket，校验后写入本地 Session
+4. Feign 调用通过 Header 透传 token
+
+## 🚨 常见错误
+
+| 错误 | 后果 | 正确做法 |
+| --- | --- | --- |
+| Token 写入 URL | 日志泄露 | Header 透传 |
+| 登出不调中心 | 跨应用仍登录 | 调 SSO logout |
+
+## 边界
+
+- **不在本 skill 范围的**：
+  - 单应用 Session → `meritdata-platform-session`
+  - 鉴权 → `meritdata-platform-resource-auth`
+- **强制要求**：Token 通过 Header 传递

package/skills/meritdata-platform-sso/agents/openai.yaml

@@ -0,0 +1,19 @@
+display_name: "MeritData SSO"
+short_description: "SSO/CAS 单点登录接入"
+default_prompt: |
+  meritdata-platform-sso 处理 SSO/CAS 单点登录场景。
+
+  适用场景：
+  - 多应用统一登录
+  - CAS 协议对接
+  - Token 透传与校验
+
+  使用方式：
+  ```
+  meritdata-platform-sso <SSO 需求>
+  ```
+
+  强制约束：
+  - Token 通过 Header 传递（不写入 URL）
+  - 登出调用 SSO 中心会话失效接口
+  - 跨应用会话通过 SSO 中心共享

package/skills/{meritdata-dev-docs-file-finder/references/dev-docs → meritdata-platform-sso/references/auth}//346/224/273/347/225/245-06-/347/263/273/347/273/237/350/256/244/350/257/201-/347/253/240/350/212/20202_token_/350/256/244/350/257/201/351/233/206/346/210/220.md

@@ -46,15 +46,15 @@ source-file: 应用开发平台-基础平台-使用攻略（四）：系统认
 
 - 操作步骤：
   新建 java 应用（如果是适配微服务6.13版本，则使用jdk21），如图：
-  ![image](./imgs/系统认证集成/token集成/3-1.png)
+  [IMG: image]
   选择 maven，直接 next
-  ![image](./imgs/系统认证集成/token集成/3-2.png)
+  [IMG: image]
   可按示例内容填入:
-  ![image](./imgs/系统认证集成/token集成/3-3.png)
+  [IMG: image]
 
   继续按图示操作：
-  ![image](./imgs/系统认证集成/token集成/3-4.png)
-  ![image](./imgs/系统认证集成/token集成/3-5.png)
+  [IMG: image]
+  [IMG: image]
 
   继续修改 pom 文件
   将 pom.xml 内容替换为（目的为了导入 RSAUTils 所需 jar 包）：
@@ -135,12 +135,12 @@ public class SSOMain {
 ```
 
 结构图：
-![image](./imgs/系统认证集成/token集成/3-6.png)
+[IMG: image]
 
 在 SSOMain 中运行项目，鼠标右键启动，如图：
-![image](./imgs/系统认证集成/token集成/3-7.png)
+[IMG: image]
 生成的 token 打印在控制台,如图所示:
-![image](./imgs/系统认证集成/token集成/3-8.png)
+[IMG: image]
 
 - 平台 token 登录展示
 
@@ -149,9 +149,9 @@ public class SSOMain {
 例如：http://191.168.2.90:8080/portal/#/?userId=merit&token=kK+7QHYuVHToVyYch0ksOCn6isbaDIx6/6ftcSumS247lRkKTIhb4+0kyGr9JTVHRqU8/LGOrcBVAJxSdRstIDzPwpks/wfLiLnISEue4MFqMskmDip6yU++InrDobIuaqL2ycQRkJMJsHUal7jLHl/cRMnKtgnCUdc0R1N2RBo=
 
 如图：
-![image](./imgs/系统认证集成/token集成/3-9.png)
+[IMG: image]
 认证成功后跳转如图：
-![image](./imgs/系统认证集成/token集成/3-10.png)
+[IMG: image]
 
 #### 2.3.2 自定义 token 单点登录(内置服务,推荐使用)
 
@@ -162,7 +162,7 @@ public class SSOMain {
   创建 project-business-sso 工程
 
   工程创建完毕后的目录结构如图所示：
-  ![image](./imgs/系统认证集成/token集成/3-11.jpg)
+  [IMG: image]
 
   pom.xml 文件
   
@@ -308,16 +308,16 @@ public class RSAUtils {
 ```
 
 工程创建完成后结构如图：
-![image](./imgs/系统认证集成/token集成/3-13.jpg)
+[IMG: image]
 
 实现以上步骤之后，将项目编译，然后将编译后的文件target下面的CustomSSOApi.class,(完整路径为cloud.meritdata.cloud\security\sso\token\CustomSSOApi.class复制，建议在文件夹下复制。
 
-![image](./imgs/系统认证集成/token集成/3-13-1.jpg)
+[IMG: image]
 
 - 配置项管理配置 ：
 
   Nacos 中 common.properties 中需要修改配置自定义 token 认证接口类。此处的配置为业务应用的 spring.application.name 的值
-  如图： ![image](./imgs/系统认证集成/token集成/3-14.png)
+  如图： [IMG: image]
 
   ```
   #自定义认证token接口类应用名,实现自定义token认证
@@ -331,7 +331,7 @@ public class RSAUtils {
   ```
 
   如图：修改后,点击发布
-  ![image](./imgs/系统认证集成/token集成/3-15.png)
+  [IMG: image]
 
 将 security\sso\token\CustomSSOApi.class放到所需要嵌入的工程服务下：
 本案例中放在 manage 中：apps\system\server\manage\WEB-INF\classes\com\meritdata\cloud 中,完整路径为：apps\system\server\manage\WEB-INF\classes\com\meritdata\cloud\security\sso\token\CustomSSOApi.class
@@ -348,12 +348,12 @@ public class RSAUtils {
   注意服务器 ip：查看 Nacos 中 common.properties 文件中 meritdata.cloud.server.ip 值
   如下图所示：
 
-  ![image](./imgs/系统认证集成/token集成/3-16.png)
+  [IMG: image]
 
   进行访问：
-  ![image](./imgs/系统认证集成/token集成/3-17.png)
+  [IMG: image]
   成功后跳转如图：
-  ![image](./imgs/系统认证集成/token集成/3-10.png)
+  [IMG: image]
 
 #### 2.3.3 自定义 token 单点登录(独立服务)
 
@@ -364,12 +364,12 @@ public class RSAUtils {
   创建 project-base-demo 工程
 
   工程创建完毕后的目录结构如图所示：
-  ![image](./imgs/系统认证集成/token集成/3-11.PNG)
+  [IMG: image]
 
 - 后端工程配置
   点击工程名选择编辑配置，配置 key 路径，更改为自己的本地 key 路径即可
-- ![image](./imgs/系统认证集成/token集成/3-18.png)
-  ![image](./imgs/系统认证集成/token集成/3-19.png)
+- [IMG: image]
+  [IMG: image]
 
 注：
 
@@ -521,7 +521,7 @@ public interface IPortalSSOApi {
 
 工程创建完成后结构如图：
 
-![image](./imgs/系统认证集成/token集成/3-20.jpg)
+[IMG: image]
 
 - 配置项管理配置 ：
 
@@ -530,7 +530,7 @@ public interface IPortalSSOApi {
   密码：BigData.2018v6
   
   Nacos 中 common.properties 中需要修改配置自定义 token 认证接口类。此处的配置为业务应用的 spring.application.name 的值
-  如图： ![image](./imgs/系统认证集成/token集成/3-14.png)
+  如图： [IMG: image]
 
   ```properties
   #自定义认证token接口类应用名,实现自定义token认证
@@ -544,12 +544,12 @@ meritdata.cloud.custom-sso-application-name=none
 ```
 
   如图：修改后,点击发布
-  ![image](./imgs/系统认证集成/token集成/3-21.png)
+  [IMG: image]
 
 * 启动服务：
-  ![image](./imgs/系统认证集成/token集成/3-22.jpg)
+  [IMG: image]
   启动后进入 nacos 查看服务列表，出现服务名则启动成功：
-  ![image](./imgs/系统认证集成/token集成/3-23.jpg)
+  [IMG: image]
 
 - 自定义 token 登录展示
   在自定义接口 CustomSSOApi 中制定加密逻辑，目前没有进行加密，只需要使用 userId 进行登录即可进行访问：
@@ -560,9 +560,9 @@ meritdata.cloud.custom-sso-application-name=none
   注意服务器 ip：查看 Nacos 中 common.properties 文件中 meritdata.cloud.server.ip 值
   如下图所示：
 
-  ![image](./imgs/系统认证集成/token集成/3-16.png)
+  [IMG: image]
 
   进行访问：
-  ![image](./imgs/系统认证集成/token集成/3-17.png)
+  [IMG: image]
   成功后跳转如图：
-  ![image](./imgs/系统认证集成/token集成/3-10.png)
+  [IMG: image]

package/skills/{meritdata-dev-docs-file-finder/references/dev-docs → meritdata-platform-sso/references/auth}//346/224/273/347/225/245-06-/347/263/273/347/273/237/350/256/244/350/257/201-/347/253/240/350/212/20203_cas_/347/273/237/344/270/200/350/256/244/350/257/201/344/270/255/345/277/203.md

@@ -123,6 +123,6 @@ server 节点下添加如下配置(注意：先检查一下是否存在以下内
 登录名：admin
 密码：BigData.2018v6
 
-![image](./imgs/系统认证集成/cas集成/1-2.jpg)
+[IMG: image]
 
 cas 用户认证成功后会默认跳转到系统首页。如果访问的是系统内的某个业务页面，会跳转至该页面

package/skills/{meritdata-dev-docs-file-finder/references/dev-docs → meritdata-platform-sso/references/auth}//346/224/273/347/225/245-06-/347/263/273/347/273/237/350/256/244/350/257/201-/347/253/240/350/212/20204_/347/254/254/344/270/211/346/226/271/350/256/244/350/257/201/344/270/255/345/277/203.md

@@ -19,7 +19,7 @@ source-file: 应用开发平台-基础平台-使用攻略（四）：系统认
 
 ### 4.3 认证流程
 
-<img src="./imgs/系统认证集成/cas集成/1-3.jpg" width="350px">
+[IMG: 第三方认证中心认证流程示意图（图源待补充，原始路径 ./imgs/系统认证集成/cas集成/1-3.jpg）]
 
 - 1.客户端请求接口，filter 进行拦截。如果没有回话跳转至配置的认证中心地址进行登录，如果有会话到步骤 2；
 - 2.校验会话，如果有会话直接请求接口。如果没有会话，访问自定义 token 接口，根据返回的用户标识在接口中返回 userId 和 token 信息；
@@ -72,7 +72,7 @@ meritdata.cloud.third-filter.parmaters[1].key=userAuthorizationUri
 meritdata.cloud.third-filter.parmaters[1].value=https://cas.merit.com:8443/cas_server/login
 ```
 
-![image](./imgs/系统认证集成/cas集成/1-4.jpg)
+[IMG: image]
 <br>
 
 - filter 类示例：

package/skills/{meritdata-dev-docs-file-finder/references/dev-docs → meritdata-platform-sso/references/auth}//346/224/273/347/225/245-06-/347/263/273/347/273/237/350/256/244/350/257/201-/347/253/240/350/212/20205_/351/231/204/345/275/225_1_/350/256/244/350/257/201/344/270/255/345/277/203/347/253/257/351/205/215/347/275/256.md

@@ -19,7 +19,7 @@ keytool -genkey -alias tomcat -keystore C:\resource\cas\mykeystore -keyalg RSA -
 
 ```
 
-![image](./imgs/系统认证集成/cas集成/1-5.jpg)
+[IMG: image]
 | 名称 | 值 |
 | -------------------- | ------------- |
 | 口令 | changeit |

package/skills/meritdata-platform-sso/references/cas-token-flow.md

@@ -0,0 +1,52 @@
+# CAS + Token 全流程
+
+## 流程图
+
+```
+┌─────────────┐                ┌──────────────┐
+│   用户       │                │  美林平台     │
+│  (浏览器)    │                │  Cloud       │
+└──────┬──────┘                └──────┬───────┘
+       │ 1. 访问 http://your-app      │
+       ├─────────────────────────────>│
+       │                              │ 2. 未登录 → 重定向到 CAS
+       │<─────────────────────────────┤
+       │                              │
+       │ 3. 输入用户名密码 (CAS 登录页) │
+       ├─────────────────────────────>│
+       │                              │ 4. 验证 → 发 ticket
+       │<─────────────────────────────┤
+       │                              │
+       │ 5. 带 ticket 重定向回 your-app│
+       ├─────────────────────────────>│
+       │                              │
+       │                       ┌──────▼─────────┐
+       │                       │ your-app       │
+       │                       │ IPortalSSOApi  │
+       │                       └──────┬─────────┘
+       │                              │
+       │ 6. 调 IPortalSSOApi.getUserIdAndToken(platformToken)
+       │                       ┌──────▼─────────┐
+       │                       │ 你的后端         │
+       │                       │ 1. 验 platformToken │
+       │                       │ 2. 本地用户映射  │
+       │                       │ 3. 建 session   │
+       │                       │ 4. 返回 localToken│
+       │                       └──────┬─────────┘
+       │                              │
+       │ 7. 返回 localToken → Cookie │
+       │<─────────────────────────────┤
+       │                              │
+       │ 8. 后续请求带 Cookie → 已登录 │
+       ├─────────────────────────────>│
+```
+
+## 关键点
+
+| 点 | 说明 |
+|-----|------|
+| 平台登录入口 | `http://gateway:8080/your-app/login` |
+| 重定向 | CAS 登录成功后跳回 `your-app/callback?token=xxx` |
+| Token 存储 | Header `Authorization: Bearer <token>` 或 Cookie |
+| Token TTL | 默认 30 分钟，可在 Nacos 覆盖 |
+| Session 存储 | Redis（key 格式 `spring:session:sessions:<sessionId>`）|

package/skills/meritdata-platform-sso/references/iportal-sso-api.md

@@ -0,0 +1,66 @@
+# IPortalSSOApi 接口规范
+
+## 接口定义
+
+```java
+public interface IPortalSSOApi {
+    /**
+     * 获取用户 ID 和 token
+     * 平台调用此接口换用户身份
+     *
+     * @param params 含 platformToken（平台临时凭证）
+     * @return String[0]=userId, String[1]=localToken
+     */
+    String[] getUserIdAndToken(Map<String, Object> params);
+}
+```
+
+## 入参 params
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `platformToken` | String | ✅ | 平台给的临时凭证 |
+| `timestamp` | Long | ❌ | 时间戳（防重放） |
+| `appKey` | String | ❌ | 应用 key |
+
+## 出参
+
+```json
+["user_12345", "local_session_token_abc..."]
+```
+
+- `[0]` userId：本地用户系统的用户 ID
+- `[1]` token：本服务生成的 session token（写入 Redis）
+
+## 实现要点
+
+```java
+@RestController
+public class PortalSSOApiImpl implements IPortalSSOApi {
+
+    @Autowired
+    private PlatformAuthClient authClient;  // 平台认证客户端
+
+    @Override
+    public String[] getUserIdAndToken(Map<String, Object> params) {
+        String platformToken = (String) params.get("platformToken");
+
+        // 1. 调平台接口验证 platformToken（带回 userId）
+        PlatformUserInfo info = authClient.verifyToken(platformToken);
+
+        // 2. 本地用户映射（按平台 userId → 本地 userId）
+        String localUserId = userMappingService.getLocalUserId(info.getUserId());
+
+        // 3. 生成本地 session token（写入 Redis）
+        String localToken = sessionService.createSession(localUserId);
+
+        return new String[]{localUserId, localToken};
+    }
+}
+```
+
+## 验证测试
+
+平台已有测试覆盖：
+- `iPortalSSOApi_shouldExist` - 接口存在性
+- `iPortalSSOApi_getUserIdAndToken_shouldExist` - 方法存在性

package/skills/meritdata-platform-sso/references/spring-session-pitfalls.md

@@ -0,0 +1,71 @@
+# Spring Session 跨服务踩坑
+
+> 配合 [[memory:spring-session-cross-service]] 记忆文件
+
+## 5 大常见坑
+
+### 坑 1：`SecurityContextImpl` 反序列化失败
+
+**症状**：启动报 `InvalidClassException` / `ClassNotFoundException`
+
+**根因**：pom.xml 里 `cloud-starter-core` 没在第一位，**加载了旧版的 Spring Session 类**
+
+**解决**：
+```xml
+<dependencies>
+    <!-- 必须第一！ -->
+    <dependency>
+        <groupId>com.meritdata.cloud</groupId>
+        <artifactId>cloud-starter-core</artifactId>
+    </dependency>
+    <dependency>...</dependency>
+</dependencies>
+```
+
+### 坑 2：Redis 连接失败
+
+**症状**：session 写入失败，自动 fallback 到内存 session
+
+**根因**：bootstrap.properties 里 `spring.redis.*` 配置错
+
+**解决**：检查 `meritdata.cloud.cache.serve-hosts` 或 `spring.data.redis.host`
+
+### 坑 3：session 跨服务漂移
+
+**症状**：A 服务登录后，调 B 服务丢失用户
+
+**根因**：Feign 调用没带 Cookie / Authorization
+
+**解决**：加 Feign 拦截器：
+```java
+public class FeignSessionInterceptor implements RequestInterceptor {
+    public void apply(RequestTemplate template) {
+        ServletRequestAttributes attrs = (ServletRequestAttributes)
+            RequestContextHolder.getRequestAttributes();
+        if (attrs != null) {
+            HttpServletRequest req = attrs.getRequest();
+            String cookie = req.getHeader("Cookie");
+            if (cookie != null) template.header("Cookie", cookie);
+        }
+    }
+}
+```
+
+### 坑 4：CLOUD_HOME 路径错
+
+**症状**：启动报 `IllegalArgumentException: CLOUD_HOME not set`
+
+**根因**：bootstrap.properties 没设 CLOUD_HOME，或环境变量没生效
+
+**解决**：
+```properties
+CLOUD_HOME=${CLOUD_HOME_ENV:D:/A_meritdata/Env_windows_V6.13.2}
+```
+
+### 坑 5：SSO 凭据过期
+
+**症状**：IPortalSSOApi 调平台返回 401
+
+**根因**：Nacos 的 `meritdata.cloud.sso.app-secret` 过期
+
+**解决**：在 Nacos 重新生成 app-secret 并推送