first commit

2026-02-22 12:12:02 +08:00
commit b236048a24
1467 changed files with 160403 additions and 0 deletions
@@ -0,0 +1,718 @@
+# 登录模块综合开发指南（LOGIN_COMPREHENSIVE_GUIDE）
+
+版本：v1.1.0（2025-12-27）  
+适用范围：Sys（后台管理端）、App（移动端）两套登录体系及微信公众号整合  
+最后更新：2025-12-27
+
+---
+
+## 目录
+1. 登录模块概述
+2. 详细开发指南
+3. 登录流程示意图
+4. 实现方案
+5. 模块规范
+6. App 会话管理 API
+7. Sys 在线用户管理 API
+8. Sys 登录日志管理 API
+9. 相关代码路径参考
+
+---
+
+## 1. 登录模块概述
+
+- 背景与目的  
+  - 系统同时支持 Sys 与 App 两套登录体系，分别面向管理员与 C 端用户，要求登录态、权限与数据完全隔离，同时提供统一的扩展与维护指引。  
+  - 采用策略模式（Strategy Pattern）实现登录方式的可插拔扩展，基于 Sa-Token 管理会话与权限，支持验证码、限流、并发与设备维度会话。  
+  - 集成微信公众号能力：App 用于授权登录与业务交互；Sys 用于管理员绑定与模板消息推送。
+
+- 目标  
+  - 统一规范开发流程与接口定义，保障多端、多方式登录的稳定性与可扩展性。  
+  - 为新增登录方式与微信能力提供清晰的落地步骤与测试方案。
+
+---
+
+## 2. 详细开发指南
+
+### 2.1 多用户体系与会话隔离
+- 物理隔离 + 逻辑统一：`sys_user` 与 `app_user` 两套用户体系；统一使用 Sa-Token 管理会话。  
+- LoginId 前缀隔离：  
+  - Sys：`sys_user:{id}`  
+  - App：`app:{id}`  
+- 会话校验（Sys 全局拦截）：参考 SecurityConfig 的 `StpUtil.checkLogin()` 与路由校验，确保 Token 与 clientid 一致。
+
+### 2.2 App 开发要点
+- 策略模式登录：`IAppAuthStrategy` 以 `grantType` 路由到具体策略（密码、短信、社交、微信等）。  
+- 验证码与密码重试：`captcha.enable=true` 可开关；错误次数与锁定时间通过配置项控制。  
+- 信息补全向导（过滤器）：登录后若用户资料未完善，仅放行“查询个人信息/绑定手机号”接口，其余拦截返回 403。
+
+### 2.3 Sys 开发要点
+- 安全加固：  
+  - 异地登录检测：比对最近一次登录 IP 归属地变化并告警（日志/邮件）。  
+  - 强制改密策略：登录后检查密码更新时间是否超期，超期在 Session 写入标记，拦截除改密外所有接口。  
+- 管理员微信绑定与消息推送：后台生成带参二维码，管理员扫码绑定 `openId/unionId`，用于模板消息推送。
+  
+（最小改动策略）  
+- 保留现有 Sys 登录与权限实现，不做核心代码改造。  
+- 新增或接入的仅为“管理员微信绑定二维码生成”“SCAN/SUBSCRIBE 回调绑定”“模板消息推送”三个能力点；其余增强（如异地登录与强制改密）可按需增量加入，不影响主流程。
+
+### 2.4 微信公众号整合（双端）
+- App：OAuth2 获取 `openId/unionId`，优先 `unionId` 进行跨应用账号识别；若未绑定则返回 401 并引导绑定手机号。  
+- Sys：生成 `scene_str=sys_user:{userId}` 的二维码，接收 `SCAN/SUBSCRIBE` 事件解析并绑定，后续通过模板消息进行系统通知与订单推送。
+
+---
+
+## 3. 登录流程示意图
+
+### 3.1 App 登录总体流程
+```mermaid
+sequenceDiagram
+  participant Client as 客户端
+  participant Controller as AppAuthController
+  participant Strategy as IAppAuthStrategy
+  participant Service as AppLoginService
+  participant Redis as Redis
+  Client->>Controller: POST /app/auth/login
+  Controller->>Strategy: authenticate(body, client, grantType)
+  Strategy->>Service: checkLogin(...)
+  Service->>Redis: PWD_ERR_CNT_KEY
+  Strategy->>Controller: LoginVo(token, expire)
+  Controller-->>Client: 返回结果
+```
+
+### 3.2 App 微信公众号授权登录
+```mermaid
+sequenceDiagram
+  participant H5 as 前端网页
+  participant Wx as 微信OAuth2
+  participant AppAPI as AppAuthController
+  participant MP as WxMpService
+  H5->>Wx: 跳转授权，获取code
+  H5->>AppAPI: grantType=wechat_mp, code
+  AppAPI->>MP: getAccessToken(code)
+  MP-->>AppAPI: openId, accessToken
+  AppAPI->>MP: userInfo(openId)
+  MP-->>AppAPI: unionId
+  AppAPI->>DB: 查询app_social_auth by unionId
+  alt 已绑定
+    AppAPI-->>H5: 登录成功
+  else 未绑定
+    AppAPI-->>H5: 401_BIND_REQUIRED + tempKey
+  end
+```
+
+### 3.3 Sys 管理员绑定与模板消息推送
+```mermaid
+flowchart LR
+  A[管理员点击绑定] --> B[生成带参二维码 scene_str=sys_user:{userId}]
+  B --> C[管理员扫码]
+  C --> D[WxMpPortal接收SCAN/SUBSCRIBE]
+  D --> E[解析EventKey与OpenId]
+  E --> F[查询UnionId]
+  F --> G[更新管理员绑定信息]
+  G --> H[SysMessageService发送模板消息]
+```
+
+---
+
+## 4. 实现方案
+
+### 4.1 架构与技术选型
+- Sa-Token：统一的会话与权限管理（Token 名称、并发、多设备）。  
+- 策略模式：按 `grantType` 定位不同登录策略，低耦合、易扩展。  
+- WxJava：`ruoyi-mp` 模块提供的公众号 OAuth2 与模板消息能力。  
+- 线程池与并发：按需启用全局线程池或在 JDK21 使用虚拟线程。
+
+### 4.2 关键实现细节
+- LoginId 前缀实现：`LoginUser.getLoginId()` 返回 `userType + ":" + userId`。  
+- App 密码策略：开启验证码校验时执行 `validateCaptcha()`；错误次数与锁定时间通过配置项 `user.password.maxRetryCount`、`user.password.lockTime` 控制。  
+- App 信息补全：过滤器中检查 `infoComplete`，仅放行指定白名单接口（配置项 `user.auth.whitelist`），其余拦截返回 403。  
+- App 微信授权：`getAccessToken(code) → userInfo(openId)`，优先使用 `unionId` 识别；未绑定返回 401 与临时 Key，引导绑定手机号。  
+- Sys 管理员绑定：二维码 `scene_str=sys_user:{userId}`；接收事件后解析 `EventKey` 与 `OpenId`，查询 `unionId` 并写入绑定信息；后续根据 `openId` 推送模板消息。  
+- 异地登录检测：在记录登录信息时调用 `LoginRiskService.checkRisk(userId, ip)`，比较归属地变化并告警。  
+- 强制改密：登录后检查密码更新时间是否超期，标记 Session 并在拦截器中只放行改密接口。
+
+### 4.4 配置项说明
+- **验证码配置**（`application.yml`）：
+  ```yaml
+  captcha:
+    enable: true              # 是否启用验证码校验
+    type: MATH                # 验证码类型（MATH数学计算 / CHAR字符验证）
+    category: CIRCLE          # 干扰类型（LINE线段 / CIRCLE圆圈 / SHEAR扭曲）
+    numberLength: 1           # 数字验证码位数
+    charLength: 4             # 字符验证码长度
+  ```
+- **用户密码策略配置**（`application.yml`）：
+  ```yaml
+  user:
+    password:
+      maxRetryCount: 5        # 密码最大错误次数
+      lockTime: 10            # 密码锁定时间（分钟）
+  ```
+- **App端验证码与白名单配置**（`application.yml`）：
+  ```yaml
+  user:
+    auth:
+      captcha:
+        enabled: false        # App端验证码开关
+        type: math            # 验证码类型
+      whitelist: /app/user/profile,/app/user/bind,/app/auth/logout  # 信息补全白名单
+  ```
+- **客户端配置**：在 `sys_client` 表中配置客户端信息，包括 `client_id`、`grant_type`（支持多个，逗号分隔）、`status`、`timeout`、`active_timeout` 等。
+
+### 4.3 OAuth 与 MP 职责划分
+- 第三方登录（OAuth）：使用 justauth
+  - 属性来源：`application*.yml` 中的 `justauth.type.*`
+  - 代码路径：属性绑定 [SocialProperties](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/ruoyi-common/ruoyi-common-social/src/main/java/org/dromara/common/social/config/properties/SocialProperties.java)，工厂方法 [SocialUtils.getAuthRequest](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/ruoyi-common/ruoyi-common-social/src/main/java/org/dromara/common/social/utils/SocialUtils.java#L35-L74)
+  - 使用位置：App 端策略 [AppWechatMpAuthStrategy](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/ruoyi-server/src/main/java/org/dromara/app/service/impl/AppWechatMpAuthStrategy.java)、[AppWechatOpenAuthStrategy](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/ruoyi-server/src/main/java/org/dromara/app/service/impl/AppWechatOpenAuthStrategy.java)、[AppWechatMiniprogramAuthStrategy](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/ruoyi-server/src/main/java/org/dromara/app/service/impl/AppWechatMiniprogramAuthStrategy.java)
+  - 说明：source 包含 `wechat_mp`、`wechat_open`、`wechat_miniprogram`、`github`、`gitee` 等，统一由 justauth 提供 OAuth 能力
+- 公众号服务端能力（MP）：使用 `wx.*`
+  - 属性来源：`application*.yml` 中的 `wx.mp.*`、`wx.miniapp.*`、`wx.pay.*`
+  - 代码路径：属性绑定 [WxMpProperties](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/ruoyi-modules/ruoyi-mp/src/main/java/org/dromara/mp/config/WxMpProperties.java)，装配 [WxMpConfiguration](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/ruoyi-modules/ruoyi-mp/src/main/java/org/dromara/mp/config/WxMpConfiguration.java)
+  - 使用位置：消息入口 [WxMpPortalController](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/ruoyi-modules/ruoyi-mp/src/main/java/org/dromara/mp/controller/WxMpPortalController.java)、二维码接口 [WxMpQrCodeController](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/ruoyi-modules/ruoyi-mp/src/main/java/org/dromara/mp/controller/WxMpQrCodeController.java)
+  - 说明：MP 提供消息接收、二维码、模板消息推送等服务端功能，不用于 OAuth 登录
+  
+---
+
+## 5. 模块规范
+
+### 5.1 接口定义与参数
+
+#### Sys 登录接口
+- **路径**：`/auth/login`  
+- **方法**：`POST`
+- **支持的grantType**：
+  - `password` - 密码登录（参数：`username`, `password`, 可选 `code/uuid`验证码）
+  - `sms` - 短信登录（参数：`phonenumber`, `smsCode`）
+  - `email` - 邮箱登录（参数：`email`, `emailCode`）
+  - `social` - 第三方登录（参数：`source`, `socialCode`, `socialState`）
+- **通用参数**：`clientId`（必填）
+- **返回**：`LoginVo`（包含 `accessToken`, `expireIn`, `clientId`）
+- **代码路径**：[AuthController.login](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/ruoyi-server/src/main/java/org/dromara/web/controller/AuthController.java#L75-L101)
+
+#### Sys 退出登录接口
+- **路径**：`/auth/logout`  
+- **方法**：`POST`
+- **权限**：需要登录态
+- **说明**：退出当前登录会话，清除Token
+- **代码路径**：[AuthController.logout](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/ruoyi-server/src/main/java/org/dromara/web/controller/AuthController.java#L164-L168)
+
+#### Sys 用户注册接口
+- **路径**：`/auth/register`  
+- **方法**：`POST`
+- **参数**：`username`, `password`, `userType`, 可选 `code/uuid`（验证码）
+- **说明**：系统用户注册，需系统开启注册功能
+- **代码路径**：[AuthController.register](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/ruoyi-server/src/main/java/org/dromara/web/controller/AuthController.java#L174-L181)
+
+#### Sys 第三方绑定接口
+- **获取绑定URL**：`GET /auth/binding/{source}?domain={domain}`
+  - 生成第三方授权跳转URL，用于绑定第三方账号
+- **回调绑定**：`POST /auth/social/callback`
+  - 前端回调后绑定第三方账号（需token）
+- **取消绑定**：`DELETE /auth/unlock/{socialId}`
+  - 取消已绑定的第三方账号（需token）
+- **代码路径**：[AuthController](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/ruoyi-server/src/main/java/org/dromara/web/controller/AuthController.java#L109-L158)
+
+#### App 登录接口
+- **路径**：`/app/auth/login`  
+- **方法**：`POST`
+- **支持的grantType**：
+  - `app_password` - 密码登录（参数：`username`, `password`）
+  - `sms` - 短信登录（参数：`phonenumber`, `smsCode`）
+  - `email` - 邮箱登录（参数：`email`, `emailCode`）
+  - `social` - 第三方登录（参数：`source`, `socialCode`, `socialState`）
+  - `wechat_mp` - 微信公众号登录（参数：`socialCode`, `socialState`）
+  - `wechat_open` - 微信开放平台登录（参数：`socialCode`, `socialState`）
+  - `wechat_miniprogram` - 微信小程序登录（参数：`socialCode`, `socialState`）
+- **通用参数**：`clientId`（必填）
+- **返回**：`LoginVo`（包含 `accessToken`, `expireIn`, `clientId`）
+- **代码路径**：[AppAuthController.login](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/ruoyi-server/src/main/java/org/dromara/app/controller/AppAuthController.java#L69-L93)
+
+#### App 退出登录接口
+- **路径**：`/app/auth/logout`  
+- **方法**：`POST`
+- **权限**：需要登录态
+- **说明**：退出当前登录会话，清除Token
+- **代码路径**：[AppAuthController.logout](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/ruoyi-server/src/main/java/org/dromara/app/controller/AppAuthController.java#L100-L104)
+
+#### App 用户注册接口
+- **路径**：`/app/auth/register`  
+- **方法**：`POST`
+- **参数**：`username`, `password`
+- **限流**：60秒内最多1次（按IP）
+- **说明**：App用户注册，需系统开启注册功能
+- **代码路径**：[AppAuthController.register](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/ruoyi-server/src/main/java/org/dromara/app/controller/AppAuthController.java#L115-L132)
+
+#### App 配置接口
+- **路径**：`/app/auth/config`  
+- **方法**：`GET`
+- **说明**：获取App端配置信息（如注册开关等）
+- **代码路径**：[AppAuthController.getConfig](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/ruoyi-server/src/main/java/org/dromara/app/controller/AppAuthController.java#L139-L145)
+
+#### 验证码接口
+- **图形验证码**：`GET /auth/code`
+  - 返回：`CaptchaVo`（包含 `uuid`, `img`（Base64图片）, `captchaEnabled`）
+  - 限流：60秒内最多10次（按IP）
+  - **代码路径**：[CaptchaController.getCode](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/ruoyi-server/src/main/java/org/dromara/web/controller/CaptchaController.java#L112-L121)
+- **短信验证码**：`GET /resource/sms/code?phonenumber={phonenumber}`
+  - 限流：60秒内最多1次（按手机号）
+  - **代码路径**：[CaptchaController.smsCode](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/ruoyi-server/src/main/java/org/dromara/web/controller/CaptchaController.java#L59-L76)
+- **邮箱验证码**：`GET /resource/email/code?email={email}`
+  - 限流：60秒内最多1次（按邮箱）
+  - **代码路径**：[CaptchaController.emailCode](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/ruoyi-server/src/main/java/org/dromara/web/controller/CaptchaController.java#L83-L90)
+
+#### 管理员绑定微信（建议）
+- **生成绑定二维码**：`POST /wx/mp/qrcode/{appid}/forever?sceneStr=sys_user:{userId}`
+  - 生成永久二维码，scene_str = sys_user:{userId}
+- **获取二维码URL**：`GET /wx/mp/qrcode/{appid}/url?ticket={ticket}`
+  - 根据ticket获取二维码图片URL
+- **事件回调**：`WxMpPortalController` 处理 `SCAN/SUBSCRIBE` 事件并完成绑定
+  - **代码路径**：[WxMpPortalController](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/ruoyi-modules/ruoyi-mp/src/main/java/org/dromara/mp/controller/WxMpPortalController.java)
+
+### 5.2 会话与权限规范
+- Token 名称：`Authorization`（统一）。  
+- 并发策略：`is-concurrent=true` 支持多设备，按需要设置 `deviceType`。  
+- 登录态隔离：Sys 与 App 使用不同 LoginId 前缀与独立会话空间。  
+- 鉴权方式：Sys 采用注解鉴权（`@SaCheckPermission` 等）；App 采用资源级鉴权（业务层校验 `userId` 所属资源）。
+
+### 5.3 错误码与处理
+- `401_BIND_REQUIRED`：微信授权成功但未绑定手机号，引导前端跳转绑定流程。  
+- `403_UPDATE_PWD`：Sys 账号密码超期未改，拦截除改密外所有接口。  
+- `403_INFO_INCOMPLETE`：App 用户信息未补全，仅放行资料完善接口。
+
+### 5.4 约束与约定
+- 不混用 Sys 与 App 的用户体系与权限模型。  
+- 微信授权优先使用 `unionId` 进行跨应用识别；若缺失则降级使用 `openId`。  
+- 新增登录方式遵循 `{grantType}AppAuthStrategy` 命名与策略路由约定。
+
+### 5.5 App 角色与关联关系
+- 表结构与关系：
+  - 用户表：`app_user`，参见 [ry_app.sql:app_user](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/script/sql/ry_app.sql#L6-L27)
+  - 角色表：`app_role`（角色键如 `app_user`、`app_vip`），参见 [ry_app.sql:app_role](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/script/sql/ry_app.sql#L35-L53)
+  - 关联表：`app_user_role`（多对多关联），参见 [ry_app.sql:app_user_role](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/script/sql/ry_app.sql#L56-L64)
+- 规范说明：
+  - App 端角色用于业务权益与标签管理（如普通用户、VIP），不等同于 Sys 端的 RBAC 功能权限。
+  - 业务层根据 `role_key`（如 `app_vip`）判断权益与展示（价格、特权、活动资格等），避免与后台菜单/按钮权限混用。
+  - 登录后构建的 `AppLoginUser` 可加载角色集合用于业务判定；权限校验仍以资源归属为主（基于 `userId`）。
+- 第三方授权表：
+  - `app_social_auth` 用于存储平台标识（`platform`/`platform_uid`）与微信 `open_id`/`union_id`，参见 [ry_app.sql:app_social_auth](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/script/sql/ry_app.sql#L67-L85)
+  - App 微信登录优先使用 `union_id` 进行账号打通；若缺失则降级使用 `open_id`。
+
+### 5.6 调用实例（curl）
+- Sys 密码登录（grantType=password）：
+```bash
+curl -sS -X POST "http://localhost:8080/auth/login" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "clientId": "e5cd7e4891bf95d1d19206ce24a7b32e",
+    "grantType": "password",
+    "username": "admin",
+    "password": "admin123",
+    "code": "a1b2",
+    "uuid": "captcha-uuid"
+  }'
+```
+- Sys 短信登录（grantType=sms）：
+```bash
+curl -sS -X POST "http://localhost:8080/auth/login" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "clientId": "e5cd7e4891bf95d1d19206ce24a7b32e",
+    "grantType": "sms",
+    "phonenumber": "13800000000",
+    "smsCode": "123456"
+  }'
+```
+- Sys 邮箱登录（grantType=email）：
+```bash
+curl -sS -X POST "http://localhost:8080/auth/login" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "clientId": "e5cd7e4891bf95d1d19206ce24a7b32e",
+    "grantType": "email",
+    "email": "admin@example.com",
+    "emailCode": "654321"
+  }'
+```
+- Sys 第三方登录（grantType=social，source∈{github,gitee,wechat_open,wechat_mp…}）：
+```bash
+curl -sS -X POST "http://localhost:8080/auth/login" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "clientId": "e5cd7e4891bf95d1d19206ce24a7b32e",
+    "grantType": "social",
+    "source": "github",
+    "socialCode": "oauth-code",
+    "socialState": "state-123"
+  }'
+```
+- App 密码登录（grantType=app_password）：
+```bash
+curl -sS -X POST "http://localhost:8080/app/auth/login" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "clientId": "428a8310cd442757ae699df5d894f051",
+    "grantType": "app_password",
+    "username": "appuser",
+    "password": "admin123"
+  }'
+```
+- App 短信登录（grantType=sms）：
+```bash
+curl -sS -X POST "http://localhost:8080/app/auth/login" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "clientId": "428a8310cd442757ae699df5d894f051",
+    "grantType": "sms",
+    "phonenumber": "13800000000",
+    "smsCode": "123456"
+  }'
+```
+- App 邮箱登录（grantType=email）：
+```bash
+curl -sS -X POST "http://localhost:8080/app/auth/login" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "clientId": "428a8310cd442757ae699df5d894f051",
+    "grantType": "email",
+    "email": "user@example.com",
+    "emailCode": "654321"
+  }'
+```
+- App 第三方登录（grantType=social，source∈{github,gitee,wechat_open…}）：
+```bash
+curl -sS -X POST "http://localhost:8080/app/auth/login" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "clientId": "428a8310cd442757ae699df5d894f051",
+    "grantType": "social",
+    "source": "gitee",
+    "socialCode": "oauth-code",
+    "socialState": "state-xyz"
+  }'
+```
+- App 微信公众号登录（grantType=wechat_mp，前端已拿到 code 与 state）：
+```bash
+curl -sS -X POST "http://localhost:8080/app/auth/login" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "clientId": "428a8310cd442757ae699df5d894f051",
+    "grantType": "wechat_mp",
+    "socialCode": "wx-oauth-code",
+    "socialState": "state-123"
+  }'
+```
+- App 微信开放平台登录（grantType=wechat_open）：
+```bash
+curl -sS -X POST "http://localhost:8080/app/auth/login" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "clientId": "428a8310cd442757ae699df5d894f051",
+    "grantType": "wechat_open",
+    "socialCode": "wx-open-code",
+    "socialState": "state-456"
+  }'
+```
+- App 微信小程序登录（grantType=wechat_miniprogram）：
+```bash
+curl -sS -X POST "http://localhost:8080/app/auth/login" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "clientId": "428a8310cd442757ae699df5d894f051",
+    "grantType": "wechat_miniprogram",
+    "socialCode": "wx-mini-code",
+    "socialState": "state-789"
+  }'
+```
+- Sys 管理员绑定二维码（生成永久二维码 ticket 与 URL）：
+```bash
+# 生成永久二维码，scene_str = sys_user:{userId}
+curl -sS -X POST "http://localhost:8080/wx/mp/qrcode/{appid}/forever" \
+  -d "sceneStr=sys_user:1"
+
+# 根据 ticket 获取二维码 URL
+curl -sS -X GET "http://localhost:8080/wx/mp/qrcode/{appid}/url" \
+  --data-urlencode "ticket=YOUR_TICKET"
+```
+- 获取公众号配置：
+```bash
+curl -sS "http://localhost:8080/wx/mp/portal/{appid}/config"
+```
+- App 用户信息补全白名单接口示例（占位）：
+```bash
+# 获取个人信息
+curl -sS "http://localhost:8080/app/user/profile" -H "Authorization: Bearer YOUR_TOKEN"
+
+# 绑定手机号
+curl -sS -X POST "http://localhost:8080/app/user/bind" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -d '{ "phone": "13800000000", "smsCode": "123456" }'
+```
+- Sys 退出登录：
+```bash
+curl -sS -X POST "http://localhost:8080/auth/logout" \
+  -H "Authorization: Bearer YOUR_TOKEN"
+```
+- App 退出登录：
+```bash
+curl -sS -X POST "http://localhost:8080/app/auth/logout" \
+  -H "Authorization: Bearer YOUR_TOKEN"
+```
+- Sys 用户注册：
+```bash
+curl -sS -X POST "http://localhost:8080/auth/register" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "username": "newuser",
+    "password": "password123",
+    "userType": "sys_user",
+    "code": "a1b2",
+    "uuid": "captcha-uuid"
+  }'
+```
+- App 用户注册：
+```bash
+curl -sS -X POST "http://localhost:8080/app/auth/register" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "username": "appuser",
+    "password": "password123"
+  }'
+```
+- 获取图形验证码：
+```bash
+curl -sS "http://localhost:8080/auth/code"
+# 返回: {"code":200,"data":{"uuid":"xxx","img":"data:image/png;base64,...","captchaEnabled":true}}
+```
+- 获取短信验证码：
+```bash
+curl -sS "http://localhost:8080/resource/sms/code?phonenumber=13800000000"
+```
+- 获取邮箱验证码：
+```bash
+curl -sS "http://localhost:8080/resource/email/code?email=user@example.com"
+```
+- 获取App配置：
+```bash
+curl -sS "http://localhost:8080/app/auth/config"
+# 返回: {"code":200,"data":{"registerEnabled":true}}
+```
+- Sys 获取第三方绑定URL：
+```bash
+curl -sS "http://localhost:8080/auth/binding/github?domain=http://localhost:8080"
+# 返回: {"code":200,"data":"https://github.com/login/oauth/authorize?..."}
+```
+- Sys 第三方绑定回调：
+```bash
+curl -sS -X POST "http://localhost:8080/auth/social/callback" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -d '{
+    "source": "github",
+    "socialCode": "oauth-code",
+    "socialState": "state-123"
+  }'
+```
+- Sys 取消第三方绑定：
+```bash
+curl -sS -X DELETE "http://localhost:8080/auth/unlock/1" \
+  -H "Authorization: Bearer YOUR_TOKEN"
+```
+
+---
+
+## 6. App 会话管理 API
+
+- 基础路径：`/app/session`  
+- 鉴权：登录态（Sa-Token）
+
+### 6.1 接口列表
+- `GET /app/session/active` 获取当前用户活跃会话列表
+- `POST /app/session/terminate` 终止指定会话（参数：`sessionId`）
+- `POST /app/session/heartbeat` 会话续期（参数：`sessionId`，默认延长至 30 天）
+- `GET /app/session/sse` 订阅会话事件（SSE），事件名：`session`，数据格式：`<TYPE>:<SESSION_ID>`
+
+### 6.2 会话数据结构（AppSession）
+- `sessionId` 会话ID（token值）
+- `userId` 用户ID
+- `deviceType` 设备类型（Web/iOS/Android/Desktop）
+- `deviceId` 设备标识（`X-Device-Id` 或生成）
+- `userAgent` UA 字符串
+- `ip` 登录IP
+- `location` 地理位置（预留）
+- `loginAt` 登录时间戳（毫秒）
+- `expireAt` 过期时间戳（毫秒）
+- `active` 活跃状态
+- `token` 令牌原文
+
+### 6.3 存储键规范
+- 索引：`APP:SESS_INDEX:{userId}`
+- 会话：`APP:SESS:{userId}:{sessionId}`（TTL 与 token 同步）
+- 事件通道：`APP:SESS_EVT:{userId}`
+
+### 6.4 调用示例（curl）
+- 获取活跃会话：
+```bash
+curl -sS "http://localhost:8080/app/session/active" \
+  -H "Authorization: Bearer YOUR_TOKEN"
+```
+- 终止指定会话：
+```bash
+curl -sS -X POST "http://localhost:8080/app/session/terminate" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -d '{ "sessionId": "TOKEN_VALUE_TO_TERMINATE" }'
+```
+- 会话续期（心跳）：
+```bash
+curl -sS -X POST "http://localhost:8080/app/session/heartbeat" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -d '{ "sessionId": "CURRENT_TOKEN_VALUE" }'
+```
+- 订阅会话事件（SSE）：
+```bash
+curl -sS "http://localhost:8080/app/session/sse" \
+  -H "Authorization: Bearer YOUR_TOKEN"
+```
+
+### 6.5 优化建议
+- 统一设备标识头 `X-Device-Id`，策略层在登录时读取并写入会话，便于同账号多设备管理。
+- 事件命名与负载标准化：`<TYPE>:<SESSION_ID>`（TYPE ∈ {login, logout, heartbeat, terminate}）。
+- TTL 与 Sa-Token 同步：确保 `APP:SESS:{userId}:{sessionId}` 的过期时间与 Token 过期保持一致，避免“僵尸会话”。
+
+---
+
+## 7. Sys 在线用户管理 API
+
+- 基础路径：`/monitor/online`  
+- 鉴权：登录态（Sa-Token），需要权限 `monitor:online:*`
+
+### 7.1 接口列表
+- `GET /monitor/online/list` 获取在线用户监控列表（支持按IP、用户名筛选）
+- `GET /monitor/online` 获取当前用户登录的在线设备列表
+- `DELETE /monitor/online/{tokenId}` 强退指定用户（需要权限 `monitor:online:forceLogout`）
+- `DELETE /monitor/online/myself/{tokenId}` 强退当前用户的指定设备
+
+### 7.2 在线用户数据结构（SysUserOnline）
+- `tokenId` 会话编号（Token值）
+- `userName` 用户名称
+- `deptName` 部门名称
+- `clientKey` 客户端标识
+- `deviceType` 设备类型
+- `ipaddr` 登录IP地址
+- `loginLocation` 登录地点
+- `browser` 浏览器类型
+- `os` 操作系统
+- `loginTime` 登录时间（时间戳，毫秒）
+
+### 7.3 调用示例（curl）
+- 获取在线用户列表：
+```bash
+curl -sS "http://localhost:8080/monitor/online/list?ipaddr=127.0.0.1&userName=admin" \
+  -H "Authorization: Bearer YOUR_TOKEN"
+```
+- 获取当前用户在线设备：
+```bash
+curl -sS "http://localhost:8080/monitor/online" \
+  -H "Authorization: Bearer YOUR_TOKEN"
+```
+- 强退指定用户：
+```bash
+curl -sS -X DELETE "http://localhost:8080/monitor/online/TOKEN_VALUE" \
+  -H "Authorization: Bearer YOUR_TOKEN"
+```
+- 强退当前用户的指定设备：
+```bash
+curl -sS -X DELETE "http://localhost:8080/monitor/online/myself/TOKEN_VALUE" \
+  -H "Authorization: Bearer YOUR_TOKEN"
+```
+- **代码路径**：[SysUserOnlineController](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/controller/monitor/SysUserOnlineController.java)
+
+---
+
+## 8. Sys 登录日志管理 API
+
+- 基础路径：`/monitor/logininfor`  
+- 鉴权：登录态（Sa-Token），需要权限 `monitor:logininfor:*`
+
+### 8.1 接口列表
+- `GET /monitor/logininfor/list` 获取系统访问记录列表（分页，支持按IP、状态、用户名、时间范围筛选）
+- `POST /monitor/logininfor/export` 导出系统访问记录列表（需要权限 `monitor:logininfor:export`）
+- `DELETE /monitor/logininfor/{infoIds}` 批量删除登录日志（需要权限 `monitor:logininfor:remove`）
+- `DELETE /monitor/logininfor/clean` 清理系统访问记录（需要权限 `monitor:logininfor:remove`）
+- `GET /monitor/logininfor/unlock/{userName}` 解锁指定用户的登录锁定（需要权限 `monitor:logininfor:unlock`）
+
+### 8.2 登录日志数据结构（SysLogininfor）
+- `infoId` 日志ID
+- `userName` 用户账号
+- `clientKey` 客户端标识
+- `deviceType` 设备类型
+- `status` 登录状态（0成功 1失败）
+- `ipaddr` 登录IP地址
+- `loginLocation` 登录地点
+- `browser` 浏览器类型
+- `os` 操作系统
+- `msg` 提示消息
+- `loginTime` 访问时间
+
+### 8.3 调用示例（curl）
+- 获取登录日志列表：
+```bash
+curl -sS "http://localhost:8080/monitor/logininfor/list?ipaddr=127.0.0.1&status=0&userName=admin&beginTime=2024-01-01&endTime=2024-12-31&pageNum=1&pageSize=10" \
+  -H "Authorization: Bearer YOUR_TOKEN"
+```
+- 导出登录日志：
+```bash
+curl -sS -X POST "http://localhost:8080/monitor/logininfor/export" \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -o logininfor.xlsx
+```
+- 批量删除登录日志：
+```bash
+curl -sS -X DELETE "http://localhost:8080/monitor/logininfor/1,2,3" \
+  -H "Authorization: Bearer YOUR_TOKEN"
+```
+- 清理登录日志：
+```bash
+curl -sS -X DELETE "http://localhost:8080/monitor/logininfor/clean" \
+  -H "Authorization: Bearer YOUR_TOKEN"
+```
+- 解锁用户登录：
+```bash
+curl -sS "http://localhost:8080/monitor/logininfor/unlock/admin" \
+  -H "Authorization: Bearer YOUR_TOKEN"
+```
+- **代码路径**：[SysLogininforController](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/controller/monitor/SysLogininforController.java)
+
+---
+
+## 9. 相关代码路径参考
+
+### 9.1 核心控制器
+- **Sys登录控制器**：[AuthController](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/ruoyi-server/src/main/java/org/dromara/web/controller/AuthController.java)
+- **App登录控制器**：[AppAuthController](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/ruoyi-server/src/main/java/org/dromara/app/controller/AppAuthController.java)
+- **验证码控制器**：[CaptchaController](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/ruoyi-server/src/main/java/org/dromara/web/controller/CaptchaController.java)
+
+### 9.2 核心服务
+- **Sys登录服务**：[SysLoginService](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/ruoyi-server/src/main/java/org/dromara/web/service/SysLoginService.java)
+- **App登录服务**：[AppLoginService](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/ruoyi-server/src/main/java/org/dromara/app/service/AppLoginService.java)
+- **Sys注册服务**：[SysRegisterService](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/ruoyi-server/src/main/java/org/dromara/web/service/SysRegisterService.java)
+
+### 9.3 登录策略
+- **Sys策略接口**：[IAuthStrategy](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/ruoyi-server/src/main/java/org/dromara/web/service/IAuthStrategy.java)
+- **App策略接口**：[IAppAuthStrategy](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/ruoyi-server/src/main/java/org/dromara/app/service/IAppAuthStrategy.java)
+- **密码策略**：[PasswordAuthStrategy](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/ruoyi-server/src/main/java/org/dromara/web/service/impl/PasswordAuthStrategy.java), [AppPasswordAuthStrategy](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/ruoyi-server/src/main/java/org/dromara/app/service/impl/AppPasswordAuthStrategy.java)
+- **短信策略**：[SmsAuthStrategy](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/ruoyi-server/src/main/java/org/dromara/web/service/impl/SmsAuthStrategy.java), [AppSmsAuthStrategy](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/ruoyi-server/src/main/java/org/dromara/app/service/impl/AppSmsAuthStrategy.java)
+- **邮箱策略**：[EmailAuthStrategy](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/ruoyi-server/src/main/java/org/dromara/web/service/impl/EmailAuthStrategy.java), [AppEmailAuthStrategy](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/ruoyi-server/src/main/java/org/dromara/app/service/impl/AppEmailAuthStrategy.java)
+- **第三方策略**：[SocialAuthStrategy](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/ruoyi-server/src/main/java/org/dromara/web/service/impl/SocialAuthStrategy.java), [AppSocialAuthStrategy](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/ruoyi-server/src/main/java/org/dromara/app/service/impl/AppSocialAuthStrategy.java)
+
+### 9.4 管理接口
+- **在线用户管理**：[SysUserOnlineController](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/controller/monitor/SysUserOnlineController.java)
+- **登录日志管理**：[SysLogininforController](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/controller/monitor/SysLogininforController.java)
+- **登录日志服务**：[SysLogininforService](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/SysLogininforService.java), [SysLogininforServiceImpl](file:///Users/lihaha/Documents/Projecte/PoJie/PoJie/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysLogininforServiceImpl.java)
+
+---
+
+所有代码与配置参考项目既有实现与路径，确保可在 IDE 中点击跳转进行联查与验证。