# 认证模块 (Auth Module)

## 概述

认证模块负责用户登录、登出、token 管理等功能。支持多种登录方式：

| 登录方式 | 说明 | 文档 |
|---------|------|------|
| 飞书内免登 | 在飞书客户端内自动登录 | [feishu-login.md](./feishu-login.md) |
| 飞书外扫码登录 | 普通浏览器扫码登录 | [feishu-qrcode.md](./feishu-qrcode.md) |
| 邮箱密码登录 | 传统账号密码登录 | - |
| 飞书消息通知 | 飞书卡片消息通知 | [feishu-notification.md](./feishu-notification.md) |

---

## 核心功能

### 1. 飞书免登

用户在飞书客户端内打开应用时，自动完成登录，无需输入密码。

**关键点：**
- 使用 H5 JSSDK (`h5-js-sdk-1.5.19.js`)
- 调用 `tt.requestAuthCode()` 获取授权码
- 支持多租户（通过 `company` 参数）

### 2. Token 自动刷新

当 API 返回 401 时，在飞书环境中自动刷新 token，用户无感知。

**流程：**
```
API 返回 401
  ↓
检测飞书环境
  ↓
调用 tt.requestAuthCode 获取新授权码
  ↓
用新授权码登录获取新 token
  ↓
用新 token 重试原始请求
```

### 3. 扫码登录

用户在普通浏览器中使用飞书 APP 扫码登录。

---

## API 接口

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/v1/auth/feishu-login` | POST | 飞书免登/扫码登录 |
| `/api/v1/auth/feishu-config` | GET | 获取公司飞书应用配置 |
| `/api/v1/auth/qrcode-login` | POST | 生成扫码登录二维码 |
| `/api/v1/auth/qrcode-login/status` | GET | 轮询扫码状态 |
| `/login/callback` | GET | 飞书授权回调 |
| `/api/v1/auth/login` | POST | 邮箱密码登录 |

---

## 前端关键文件

```
frontend/src/
├── pages/login/
│   ├── index.tsx           # 登录页主逻辑
│   └── QRCodeLogin.tsx     # 扫码登录组件
├── services/
│   └── api.ts              # API 封装（含 401 token 刷新）
└── stores/
    └── user.ts             # 用户状态管理
```

---

## 后端关键文件

```
backend/app/
├── Controller/
│   └── AuthController.php  # 认证控制器
├── Service/
│   └── FeishuService.php   # 飞书服务
└── Model/
    ├── User.php            # 用户模型
    └── CompanyFeishuApp.php # 飞书应用配置
```

---

## 环境变量

```env
# 飞书应用配置（多租户时在数据库中配置）
FEISHU_APP_ID=cli_xxxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxx
FEISHU_ENCRYPT_KEY=xxxxxxxxxxxxxxxxxxxx
FEISHU_VERIFICATION_TOKEN=xxxxxxxxxxxxxxxxxxxx
```

---

## URL 参数

| 参数 | 说明 | 示例 |
|------|------|------|
| `company` | 公司ID（必需） | `?company=2` |
| `app_id` | 飞书应用ID（可选） | `?app_id=cli_xxx` |
| `redirect` | 登录成功后跳转地址 | `?redirect=/dashboard` |

---

## 常见问题

### Q1: 飞书免登失败 "invalid appId"
**A:** 确保 URL 中有 `company` 参数，或直接传 `app_id` 参数。

### Q2: 扫码后没反应
**A:** 检查飞书开放平台是否配置了正确的重定向 URL 白名单。

### Q3: Token 过期后需要重新登录
**A:** 已实现自动刷新，在飞书环境中会自动获取新 token。

---

## 相关文档

- [飞书登录完整经验](./feishu-login.md)
- [飞书扫码登录详解](./feishu-qrcode.md)
- [环境配置说明](../guides/environment.md)

---

**负责人**: mzl
**最后更新**: 2026-02-28