@alanwang-merit/meritdata-platform-skill-package 1.0.0

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

@@ -0,0 +1,44 @@
+---
+name: meritdata-platform-playbook
+description: |
+  MeritData 二开标准件 L1 唯一入口。识别用户的"动作意图"→ 路由到对应 L2 skill（code-spec / data-boundary / domain-model / bpm / entities / services / integration / frontend / job / impexp / sso）。
+  触发场景：用户说"我要做XX"但不确定从哪个 skill 开始；新二开项目冷启动；跨 skill 的复合需求（如"加一个审批流"= domain-model + bpm + code-spec）。
+  何时不用：用户明确说了 skill 名（如 /code-spec）→ 直接调对应 skill；纯查铁律 → 直接读 rules/。
+metadata:
+  version: "1.0.0"
+  author: petroleum+rd
+  source: petroleum+rd
+  date_added: "2026-09-07"
+  last_modified: "2026-09-07"
+  risk: low
+  layer: L1
+allowed-tools: Read, Grep, Glob, AskUserQuestion
+---
+
+# MeritData 二开 playbook（L1 入口）
+
+## 触发
+- 用户描述"我要做XX"但没说 skill 名
+- 新二开项目冷启动，从需求到上线的完整路径
+- 跨多个 skill 的复合需求（如"加采购审批流"= domain-model + bpm + code-spec）
+- 用户明确说"我不知道从哪开始"
+
+## 不触发
+- 用户明确说了 skill 名（如 `/code-spec`）→ 直接调对应 skill
+- 纯查铁律 / 命名规范 → 直接读 `../../rules/`
+- 纯前端样式调整 → `meritdata-platform-frontend`
+- 平台模块（与平台同 JVM）的代码 → `meritdata-platform-entities` / `services`
+
+## 路由
+
+按用户意图二选一：
+
+### 路径 A：单动作（用户表达明确）
+→ 查 [references/intent-routing.md](references/intent-routing.md) 的"意图关键词表"，直接路由到唯一 L2 skill。
+
+### 路径 B：复合需求（多 skill 组合）
+→ 查 [references/flows.md](references/flows.md) 的典型流程（如"加审批流"/"加定时任务"/"加导入"），按顺序调多个 L2 skill。
+
+## 前置约束
+- 所有目标 skill 的铁律都在 `../../rules/code-dev-rules.md §八`，必须先读
+- 路由前**先问 1 个澄清问题**确认意图（避免误路由），见 [references/intent-routing.md §问询模板](references/intent-routing.md#问询模板)

package/skills/meritdata-platform-playbook/references/flows.md

@@ -0,0 +1,186 @@
+# 典型流程（flows）
+
+> **用法**：复合需求（用户一句话涵盖多个 skill 职责）时，按本文档的流程图依次调用多个 L2 skill。
+>
+> **每个流程给出**：典型场景 → 涉及 skill 顺序 → 每步的产出物 → 终止条件。
+
+---
+
+## 流程 1：新建二开业务模块（最常见）
+
+**典型场景**："我要做一个采购订单模块"
+
+**skill 串联**：
+
+```
+[1] domain-model          ← 数据库表设计（先做）
+       ↓ 输出：t_purchase_order + t_purchase_order_item + 索引 + 外键策略
+[2] code-spec             ← Controller/Service/Repository 代码规范
+       ↓ 输出：分层结构 + 软删除实体 + 异常处理
+[3] data-boundary         ← 跨服务数据装配（如果涉及平台人员/组织）
+       ↓ 输出：Feign 批量调用 + 内存 join
+[4] code-spec             ← PR 前自查
+       ↓ 输出：通过 CI
+```
+
+**终止条件**：CI 全绿 + 通过 PR review。
+
+---
+
+## 流程 2：加审批流
+
+**典型场景**："采购订单要加部门领导审批"
+
+**skill 串联**：
+
+```
+[1] domain-model          ← 业务表加 status + process_instance_id 字段
+       ↓ 输出：t_purchase_order 增加两列
+[2] bpm（待建）           ← 流程图设计（节点/网关/条件）
+       ↓ 输出：BPMN XML
+[3] code-spec             ← 启动流程 + 监听回调代码
+       ↓ 输出：启动/回调 Service
+[4] code-spec             ← PR 前自查
+```
+
+**关键约束**（rules/code-dev-rules.md §8.1 §8.2）：
+- 业务状态字段独立，不与 process_instance_id 混用
+- 流程状态变更走平台公共方法，不直接 UPDATE
+
+---
+
+## 流程 3：加导入导出
+
+**典型场景**："采购订单要支持 Excel 导入导出"
+
+**skill 串联**：
+
+```
+[1] impexp（待建）        ← 模板设计 + 导入校验
+       ↓ 输出：模板文件 + 导入 DTO + 校验规则
+[2] code-spec             ← Controller + Service + Repository
+       ↓ 输出：分层代码
+[3] code-spec             ← PR 前自查
+```
+
+**关键约束**：
+- 导入走平台公共校验（不重复实现）
+- 大文件异步处理（不能同步阻塞）
+
+---
+
+## 流程 4：加定时任务
+
+**典型场景**："每天凌晨同步 HR 数据"
+
+**skill 串联**：
+
+```
+[1] job（待建）           ← XXL-JOB 调度配置
+       ↓ 输出：JobHandler + 调度 cron
+[2] data-access          ← Feign Client 调 HR 接口 + 批量装配
+       ↓ 输出：HR 同步 Client + 幂等设计
+[3] data-boundary         ← Feign 批量调用 + 失败处理
+       ↓ 输出：不掩盖异常 + 幂等设计
+[4] code-spec             ← PR 前自查
+```
+
+**关键约束**（rules/code-dev-rules.md §1）：
+- Feign 必须批量调用（不能循环 getById）
+- 失败必须显式上抛（不能 catch + 空集合）
+
+---
+
+## 流程 5：接入平台 UI 组件
+
+**典型场景**："采购订单要加人员选择弹框"
+
+**skill 串联**：
+
+```
+[1] frontend（待建）      ← 前端组件选择（人员弹框）
+       ↓ 输出：Vue/React 组件名 + props
+[2] code-spec             ← 前端调用后端的 API 路径
+       ↓ 输出：REST URL + 请求/响应结构
+[3] code-spec             ← PR 前自查
+```
+
+**关键约束**（rules/api-design-rules.md）：
+- URL 用复数 `/api/v1/users`
+- 响应包装 `{ code, data, message }`
+
+---
+
+## 流程 6：排查 Bug
+
+**典型场景**："创建采购订单报 SQLIntegrityConstraintViolationException"
+
+**skill 串联**：
+
+```
+[1] investigate-bug       ← 3 步调试法（复现→分析→修）
+       ↓ 输出：根因写在 TODO
+[2] code-spec             ← 修复方案对照软删除铁律
+       ↓ 输出：使用 findXxxIncludingDeleted
+[3] code-spec             ← 加回归用例（GEN-SOFT-DELETE + DUP-SOFT-DELETE）
+       ↓ 输出：TDD 用例
+```
+
+**终止条件**：回归用例通过 + 根因写入文档。
+
+---
+
+## 流程 7：新二开项目冷启动
+
+**典型场景**："我要从零开始做一个新的二开服务"
+
+**skill 串联**：
+
+```
+[1] meritdata-bootstrap-2nd-dev（待建 L4）   ← 项目脚手架
+       ↓ 输出：Maven/Gradle 骨架 + application.yml + 启动类
+[2] meritdata-platform-2nd-dev-check（待建 L4）← 合规基线检查
+       ↓ 输出：CI baseline pass
+[3] domain-model          ← 第一张业务表
+       ↓ 输出：t_xxx 实体 + Repository
+[4] code-spec             ← 第一个 Controller/Service
+       ↓ 输出：CRUD 完成
+[5] data-boundary         ← 接入平台公共 API
+       ↓ 输出：Feign 装配
+[6] code-spec             ← 第一个 PR 自查
+```
+
+---
+
+## 流程 8：加权限 / 数据范围
+
+**典型场景**："采购订单要按部门过滤"
+
+**skill 串联**：
+
+```
+[1] L3 资源授权（待建）   ← 按钮权限 + 数据权限规则
+       ↓ 输出：权限点注册 + 过滤 SQL 片段
+[2] domain-model          ← 业务表加 dept_id 字段
+       ↓ 输出：t_purchase_order.dept_id
+[3] code-spec             ← Service 层注入权限过滤
+       ↓ 输出：MyBatis Interceptor 或 AOP
+[4] code-spec             ← PR 前自查
+```
+
+---
+
+## 流程间的通用规则
+
+1. **先设计后编码**：domain-model 永远在前（流程 1/2/3/5/7/8）
+2. **先数据后规范**：data-boundary 在 code-spec 之前（流程 1/4）
+3. **最后自查**：code-spec 永远在最后（所有流程）
+4. **遇到 Bug 走流程 6**：不直接修，先 investigate-bug
+
+---
+
+## 关联阅读
+
+- [intent-routing.md](intent-routing.md) — 单动作的关键词路由
+- [SKILL.md](../SKILL.md) — 顶层路由器
+- [rules/code-dev-rules.md §八](../../rules/code-dev-rules.md#八方法论补充铁律) — 所有目标 skill 的铁律摘要

package/skills/meritdata-platform-playbook/references/intent-routing.md

@@ -0,0 +1,180 @@
+# 意图路由表（intent-routing）
+
+> **用法**：根据用户原话中的"动作关键词"匹配到唯一 L2 skill。**匹配不到则用 flows.md 的复合流程**。
+
+---
+
+## 问询模板
+
+路由前先问 1 个澄清问题，避免误判：
+
+```
+你现在处在哪个阶段？
+  1. 还在设计/规划（还没写代码）
+  2. 已经写完代码，准备提交/合并
+  3. 在排查 bug / 修代码
+  4. 不确定，纯学习
+```
+
+- 答 1 → 路由到"建模类" skill（domain-model / bpm 等）
+- 答 2 → 路由到"门禁类" skill（code-spec / data-boundary 等）
+- 答 3 → 路由到"诊断类" skill（investigate-bug）
+- 答 4 → 给出本 playbook 的目录树，让用户选
+
+---
+
+## 意图关键词表
+
+### 建模类（设计阶段）
+
+| 用户原话关键词 | → 目标 skill | sub-layer | stack |
+|----------------|-------------|-----------|-------|
+| 新建业务模块 / 新功能 / 设计数据库表 / 建表 / 聚合根 / 实体设计 | `meritdata-platform-domain-model` | L2-M | methodology |
+| 字段加一列 / 改字段类型 / 加索引 | `meritdata-platform-domain-model` §加字段（轻量场景）| L2-M | methodology |
+| 流程引擎 / 审批流 / BPMN / 工作流 / 节点 / 流程图 | `meritdata-platform-bpm` | L2-C | java |
+| 平台 UserDTO / 用平台实体 / OrgDTO / Q类查询 / 同 JVM 注入 / Feign Client / HR 同步 / 第三方调用 | `meritdata-platform-data-access` | L2-C | java |
+| **对外发布 WebApi**（外部供应商/银行/合作伙伴调平台，`/webapi/**` + App-Key 认证）🆕 v2.6.0 | `meritdata-platform-data-access/references/outbound/webapi.md` | L2-C 子文档 | java |
+
+### 数据访问类（编码阶段）
+
+| 用户原话关键词 | → 目标 skill | sub-layer | stack |
+|----------------|-------------|-----------|-------|
+| @TableName / CREATE TABLE / Repository 设计 | `meritdata-platform-data-boundary` | L2-M | methodology |
+| for 循环 Feign / userClient.getById / N+1 | `meritdata-platform-data-boundary` §2 | L2-M | methodology |
+| 跨服务 JOIN / 关联平台表 / 复制平台 Entity | `meritdata-platform-data-boundary` §1 | L2-M | methodology |
+| catch 吞异常 / 返回空集合掩盖失败 | `meritdata-platform-data-boundary` §4 | L2-M | methodology |
+
+### 编码规范类（提交前）
+
+| 用户原话关键词 | → 目标 skill | sub-layer | stack |
+|----------------|-------------|-----------|-------|
+| 自查 / 提交前 / PR review / 编码规范 | `meritdata-platform-code-spec` | L2-M | methodology |
+| 软删除 / SQLIntegrityConstraintViolation / findIncludingDeleted | `meritdata-platform-code-spec` §软删除 | L2-M | methodology |
+| 死循环 / 循环内调数据库 / 资源没关 | `meritdata-platform-code-spec` §循环 / §资源 | L2-M | methodology |
+| 敏感信息 / 密码打印 / 日志脱敏 | `meritdata-platform-code-spec` §敏感信息 | L2-M | methodology |
+| 数据访问审查 / 4 铁律 / 跨库 JOIN 扫描 | `meritdata-platform-data-access-review` | L2-M | methodology |
+| 代码审查 / Code Review / 评审清单 | `meritdata-platform-code-review` | L2-M | methodology |
+| 写测试 / 单元测试 / 覆盖率 / TDD | `meritdata-platform-test-case` | L2-M | methodology |
+
+### 平台能力类（接入平台公共服务）
+
+| 用户原话关键词 | → 目标 skill | sub-layer | stack |
+|----------------|-------------|-----------|-------|
+| 字典 / lookup / ILookupService / 枚举下拉 | `meritdata-platform-lookup-api` | L3-C | java |
+| 组织树 / 人员弹框 / 部门选择 | `meritdata-platform-org-user-api` | L3-C | java |
+| 缓存 / Redis / @Cacheable / Caffeine / 多级缓存 | `meritdata-platform-cache` | L3-C | java |
+| Nacos 配置 / @NacosValue / 配置中心 / 灰度 | `meritdata-platform-nacos-config` | L3-C | java |
+| 国密 / SM2 / SM4 / 加密 / 密钥 | `meritdata-platform-sm-crypto` | L3-C | java |
+| 密级 / 数据权限 / 行列权限 / DAM | `meritdata-platform-data-classification` | L3-C | java |
+| 会话 / Session / 登录态 / 多端登录 / Token | `meritdata-platform-session` | L3-C | java |
+| 日志 / 操作日志 / 审计日志 / @LogMask / 异步日志 | `meritdata-platform-operation-log` | L3-C | java |
+| 消息中心 / 站内信 / 短信 / 邮件 / 通知 | `meritdata-platform-message-center` | L3-C | java |
+| 资源授权 / 按钮权限 / 数据权限 / 自定义规则 | `meritdata-platform-permission` | L3-C | java |
+| 菜单配置 / 菜单资源 / Ant 路径匹配 | `meritdata-platform-menu-config` / `meritdata-platform-menu-resource` | L3-C | java |
+| 平台基础配置 / 全局开关 / 系统参数 | `meritdata-platform-platform-config` | L3-C | java |
+
+### 前端 / 部署
+
+| 用户原话关键词 | → 目标 skill | sub-layer | stack |
+|----------------|-------------|-----------|-------|
+| 前端组件 / 弹框 / 树 / 前端工程 | `meritdata-platform-frontend` | L2-F | frontend |
+| **前端多服务 HTTP 客户端**（registry 声明式 / 平台 plugin / 5 段路径 / HC-01~HC-08 验收）🆕 v2.6.0 | `meritdata-platform-frontend/references/http-client/` | L2-F 子目录 | frontend |
+| 前端组件库 / meritdata-platform-ui-components / 统一弹框 | `meritdata-platform-ui-components` | L3-F | frontend |
+| 前端部署 / 打包 / nginx / CDN | `meritdata-platform-frontend-deploy` | L3-F | frontend |
+| 后端部署 / Dockerfile / 启动脚本 / Actuator | `meritdata-platform-backend-deploy` | L3-C | java |
+| 定时任务 / XXL-JOB / 调度 | `meritdata-platform-job` | L2-C | java |
+| 导入 Excel / 导出 Excel / 模板下载 | `meritdata-platform-impexp` | L2-C | java |
+| SSO / 登录 / 认证 / OAuth | `meritdata-platform-sso` | L2-C | java |
+| 二开项目脚手架 / bootstrap | `meritdata-bootstrap-2nd-dev` | L4-T | tool |
+| Nacos 配置导入 | `meritdata-nacos-importer` | L4-T | tool |
+| 二开合规扫描 | `meritdata-platform-2nd-dev-check` | L4-T | tool |
+
+### 诊断 / 学习
+
+| 用户原话关键词 | → 目标 skill | 路由理由 |
+|----------------|-------------|---------|
+| Bug / 报错 / 失败 / 不工作 | `investigate-bug`（全局 skill）| 3 步调试法 |
+| 学习 MeritData 平台 | 输出本 playbook 的目录树 + 推荐阅读顺序 | 自助 |
+
+### 执行引擎（动手生成代码）
+
+| 用户原话关键词 | → 目标 skill | 路由理由 |
+|----------------|-------------|---------|
+| 加新功能 / 加新模块 / 二开整体流程 / 怎么开始 / 第一次做二开 / 跨模块需求 / 新建工程 / 平台能力查询 / 方案设计 / 现有项目新增模块字段接口页面流程 / 生成代码 / scaffold | `meritdata-platform-cloud-dev` | L2-C 执行引擎（22 modules 路由）；playbook 路由完再交给它动手 |
+| 不知道从哪开始 / 不知道用什么 skill / 帮我规划一下 | 先走本表其他条目（按意图）| playbook 才是 L1 入口 |
+
+> **playbook vs cloud-dev 分工**：
+> - playbook（L1）= 路由器，输出"用哪个 skill"
+> - cloud-dev（L2-C）= 执行引擎，输出"模块代码 + DDL + SQL migration + 验证"
+> - 用户说"我应该看哪个 skill" → playbook；用户说"我来做这个需求" → cloud-dev
+
+---
+
+## 路由优先级
+
+当用户原话命中多个关键词时：
+
+1. **先按阶段**：1 设计 > 2 提交 > 3 诊断
+2. **后按范围**：建模 > 数据访问 > 编码规范 > 平台能力
+3. **最后看 layer**：L2 > L3 > L4
+
+**例**：
+- "我要加一个采购审批流" → 1（设计）+ 1（建模）→ domain-model
+- "我写了 Feign 调用循环，要提交" → 2（提交）+ 2（数据访问）→ data-boundary
+- "Bug：循环 Feign 失败" → 3（诊断）→ investigate-bug
+
+---
+
+## L3 skill 清单（19 个，全部已交付）
+
+### L3-C java（13 个）
+
+| skill | 主题 | group |
+|-------|------|-------|
+| `meritdata-platform-cache` | 多级缓存 | 1 |
+| `meritdata-platform-nacos-config` | Nacos 配置中心 | 1 |
+| `meritdata-platform-sm-crypto` | 国密算法 | 1 |
+| `meritdata-platform-data-classification` | 数据密级 / 行列权限 | 1 |
+| `meritdata-platform-session` | 会话管理 | 2 |
+| `meritdata-platform-operation-log` | 操作日志 | 2 |
+| `meritdata-platform-message-center` | 消息中心 | 2 |
+| `meritdata-platform-lookup-api` | 字典 API | 2 |
+| `meritdata-platform-org-user-api` | 组织人员 API | 3 |
+| `meritdata-platform-menu-config` | 菜单配置 | 3 |
+| `meritdata-platform-menu-resource` | 菜单资源 | 3 |
+| `meritdata-platform-permission` | 权限资源 | 3 |
+| `meritdata-platform-platform-config` | 平台基础配置 | 3 |
+| `meritdata-platform-backend-deploy` | 后端部署 | 4 |
+
+### L3-F frontend（2 个）
+
+| skill | 主题 | group |
+|-------|------|-------|
+| `meritdata-platform-ui-components` | 前端组件库 | 4 |
+| `meritdata-platform-frontend-deploy` | 前端部署 | 4 |
+
+### L2-M methodology（3 个）
+
+| skill | 主题 | group |
+|-------|------|-------|
+| `meritdata-platform-data-access-review` | 数据访问审查（4 铁律）| 5 |
+| `meritdata-platform-code-review` | 代码审查（4 维度）| 5 |
+| `meritdata-platform-test-case` | 测试用例（TDD）| 5 |
+
+---
+
+## L4 工具 skill 清单（3 个，全部已交付）
+
+| skill | 主题 | sub-layer | stack |
+|-------|------|-----------|-------|
+| `meritdata-bootstrap-2nd-dev` | 二开项目脚手架 | L4-T | tool |
+| `meritdata-nacos-importer` | Nacos 配置批量导入 | L4-T | tool |
+| `meritdata-platform-2nd-dev-check` | 二开项目合规扫描 | L4-T | tool |
+
+---
+
+## 关联阅读
+
+- [flows.md](flows.md) — 复合需求的多 skill 串联流程
+- [SKILL.md](../SKILL.md) — 顶层路由器
+- [rules/code-dev-rules.md §八](../../rules/code-dev-rules.md#八方法论补充铁律) — 所有目标 skill 的铁律摘要

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

@@ -0,0 +1,42 @@
+---
+name: meritdata-platform-session
+description: |
+  会话管理。SSO 单点登录 / Token 续期 / 多端登录互踢 / 强制下线 / 在线用户查询。
+  触发场景：登录认证 / Token 校验 / 会话状态查询 / 单点登出。
+  何时不用：纯 SSO 协议细节 → 用 meritdata-platform-sso；菜单权限 → 用 menu-config。
+metadata:
+  version: "1.0.0"
+  author: petroleum+rd
+  source: petroleum+rd
+  date_added: "2026-09-07"
+  last_modified: "2026-09-07"
+  risk: high
+  layer: L3
+  sub-layer: L3-C
+  stack: java
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# 会话管理（session）
+
+## 触发
+- 需要登录、登出、Token 校验、Token 续期
+- 多端登录互踢（同一账号新登录踢旧设备）
+- 强制下线（管理员踢指定会话）
+- 在线用户查询（在线列表、活跃会话）
+
+## 不触发
+- SSO 协议实现细节（SAML/OIDC/CAS）→ 用 `meritdata-platform-sso`
+- 菜单权限 / 按钮权限 → 用 `meritdata-platform-permission`
+- 用户/组织 CRUD → 用 `meritdata-platform-org-user-api`
+
+## 前置约束
+- 会话**必须**存服务端（Redis），不依赖客户端 Cookie
+- Token 校验在网关层 + 服务层双重校验
+- 敏感操作必须强制二次认证或会话强度检查
+
+## 路由
+- 会话接口 + Token 生命周期 → [references/guide.md](references/guide.md)
+- 多端登录互踢 / 强制下线 → [references/multi-device.md](references/multi-device.md)
+- 在线用户 / 会话监控 → [references/online-monitor.md](references/online-monitor.md)
+- [SKILL.md](../SKILL.md)

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

@@ -0,0 +1,157 @@
+# 会话基础指南（session）
+
+> 平台会话基于 Redis。Token 是会话标识，不是权限载体。
+
+---
+
+## 1. 会话模型
+
+```
+┌─────────┐   1. login   ┌─────────┐
+│  Client │ ───────────→ │   SSO   │
+└─────────┘              └─────────┘
+     ↑                        │
+     │ 2. accessToken        │
+     │←──────────────────────┘
+     │
+     │ 3. API 请求（带 accessToken）
+     ↓
+┌─────────┐  4. 校验 Token  ┌─────────┐
+│  Server │ ──────────────→ │  Redis  │
+└─────────┘                │ session │
+     ↑                     └─────────┘
+     │ 5. 业务响应
+     ↓
+```
+
+## 2. 核心接口
+
+```java
+@Resource
+private ISessionService sessionService;
+
+// 登录 → 返回 accessToken + refreshToken
+LoginResult login(String username, String password);
+
+// 校验 Token → 返回 SessionInfo
+SessionInfo validate(String accessToken);
+
+// 刷新 Token
+LoginResult refresh(String refreshToken);
+
+// 登出
+void logout(String accessToken);
+```
+
+## 3. 登录返回
+
+```json
+{
+  "accessToken": "eyJhbGc...",
+  "refreshToken": "rt_xxx",
+  "expiresIn": 7200,
+  "userId": "10001",
+  "tenantId": "T001",
+  "sessionId": "sid_xxx"
+}
+```
+
+## 4. 会话信息
+
+```java
+public class SessionInfo {
+    private String sessionId;
+    private String userId;
+    private String tenantId;
+    private String clientIp;
+    private String userAgent;
+    private long loginTime;
+    private long lastAccessTime;
+    private SessionStatus status;  // ONLINE, OFFLINE, KICKED, EXPIRED
+}
+```
+
+## 5. 当前会话上下文
+
+### 5.1 获取当前用户
+
+```java
+import com.meritdata.cloud.security.SecurityUtils;
+
+UserDTO current = SecurityUtils.getCurrentUser();
+String userId = SecurityUtils.getCurrentUserId();
+String tenantId = SecurityUtils.getCurrentTenantId();
+String sessionId = SecurityUtils.getCurrentSessionId();
+```
+
+### 5.2 判当前角色/权限
+
+```java
+boolean isAdmin = SecurityUtils.hasRole("admin");
+boolean hasPerm = SecurityUtils.hasPermission("order:delete");
+```
+
+## 6. Token 续期
+
+### 6.1 自动续期
+
+平台拦截器自动续期：
+
+```
+请求时校验 accessToken
+  ↓
+剩余有效期 < 5 分钟
+  ↓
+自动用 refreshToken 换新 accessToken
+  ↓
+响应头返回新 token
+```
+
+业务代码**无需任何处理**。
+
+### 6.2 手动续期
+
+```java
+@PostMapping("/auth/refresh")
+public Result<LoginResult> refresh(@RequestBody RefreshRequest req) {
+    return Result.success(sessionService.refresh(req.getRefreshToken()));
+}
+```
+
+## 7. ❌ 反模式
+
+### 7.1 ❌ Token 里塞权限信息
+
+```java
+// ❌ 错：JWT payload 里塞权限列表
+{
+  "userId": "10001",
+  "permissions": ["order:view", "order:delete", ...]  // 权限变化时 token 失效
+}
+```
+
+✅ Token 只放 userId/tenantId，权限每次请求查 DAM。
+
+### 7.2 ❌ Token 不过期
+
+```java
+// ❌ 错：Token 永不过期
+String token = jwt.sign(claims);  // 没有 expiresAt
+```
+
+✅ accessToken 2 小时 + refreshToken 7 天。
+
+### 7.3 ❌ 会话只存 Cookie
+
+```java
+// ❌ 错：会话只在客户端 Cookie
+Cookie cookie = new Cookie("sessionId", "sid_xxx");
+```
+
+✅ 服务端 Redis 存 sessionId → userId 映射。
+
+## 8. 关联阅读
+
+- [multi-device.md](multi-device.md) — 多端互踢
+- [online-monitor.md](online-monitor.md) — 在线监控
+- [SKILL.md](../SKILL.md)