root
e3fa7e86f3
新的文档结构：
docs/
├── README.md # 文档中心导航
├── modules/ # 模块文档
│ ├── auth/ # 认证模块
│ │ ├── README.md
│ │ ├── feishu-login.md
│ │ ├── feishu-qrcode.md
│ │ └── feishu-notification.md
│ ├── approval/ # 审批流程模块
│ │ └── README.md
│ ├── business-trip/ # 出差申请模块
│ │ └── README.md
│ └── user/ # 用户管理模块
│ └── README.md
└── guides/ # 指南文档
├── deployment.md
├── environment.md
├── git-workflow.md
└── ...
每个模块都有独立的 README.md 说明概述、API、关键文件等
138 lines
3.4 KiB
Markdown
138 lines
3.4 KiB
Markdown
# 认证模块 (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
|