# 登录模块综合开发指南（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 中点击跳转进行联查与验证。