# 飞书API集成模块使用指南
## 快速开始
### 1. 安装依赖
```bash
npm install express
```
### 2. 引入模块并配置
```typescript
import express from 'express';
import { createFeishuRouter } from './fmode-server/modules/fmode-feishu-api/src/index.ts';
const app = express();
// 创建飞书路由（直接传入配置）
const feishuRouter = createFeishuRouter({
'cli_a1b2c3d4e5f6g7h8': {
appId: 'cli_a1b2c3d4e5f6g7h8',
appSecret: 'your_app_secret_here',
company: 'your_company_id',
enabled: true
}
});
// 挂载到Express应用
app.use('/api/feishu', feishuRouter);
app.listen(3000, () => {
console.log('服务器启动在端口 3000');
});
```
### 3. 测试模块是否正常加载
访问 `http://localhost:3000/api/feishu/test` 查看模块状态。
## 配置说明
### 单个应用配置
```typescript
const feishuRouter = createFeishuRouter({
'cli_xxx': {
appId: 'cli_xxx', // 飞书应用ID
appSecret: 'your_secret', // 飞书应用密钥
company: 'company_id', // 公司ID（用于用户管理）
enabled: true // 是否启用
}
});
```
### 多个应用配置
```typescript
const feishuRouter = createFeishuRouter({
'app1': {
appId: 'cli_xxx1',
appSecret: 'secret1',
company: 'company1',
enabled: true
},
'app2': {
appId: 'cli_xxx2',
appSecret: 'secret2',
company: 'company2',
enabled: true
}
});
```
## OAuth2扫码登录
### 前端实现
```html
飞书登录
```
### 后端API调用
```typescript
// POST /api/feishu/oauth2/login
fetch('/api/feishu/oauth2/login', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
appId: 'cli_a1b2c3d4e5f6g7h8',
code: '授权码'
})
})
.then(res => res.json())
.then(data => {
console.log('登录成功:', data.data.sessionToken);
});
```
## 网页应用免登录
### 前端实现
```html
飞书应用
飞书应用
```
## API接口说明
### 1. OAuth2扫码登录
- **接口**: `POST /api/feishu/oauth2/login`
- **参数**: `{ appId, code }`
- **返回**: 用户信息、令牌信息、sessionToken
### 2. 网页应用免登录
- **接口**: `POST /api/feishu/oauth2/feishu`
- **参数**: `{ appId, code }`
- **返回**: 用户信息、sessionToken
### 3. 刷新OAuth2令牌
- **接口**: `POST /api/feishu/oauth2/refresh_token`
- **参数**: `{ appId, refreshToken }`
### 4. 同步用户信息
- **接口**: `POST /api/feishu/user/sync`
- **参数**: `{ appId, userInfo }`
### 5. 转发API请求
- **接口**: `POST /api/feishu/forward`
- **参数**: `{ appId, path, method, query, body }`
### 6. 获取Token状态
- **接口**: `POST /api/feishu/token/status`
- **参数**: `{ appId }`
### 7. 强制刷新Token
- **接口**: `POST /api/feishu/token/refresh`
- **参数**: `{ appId }`
## 与旧版本的区别
### 旧版本（繁琐）
```typescript
import { createFeishuRouter, feishuConfig } from 'fmode-feishu-api';
// 需要先单独配置
feishuConfig.setAppConfig('cli_xxx', {
appId: 'cli_xxx',
appSecret: 'secret',
company: 'company_id',
enabled: true
});
// 然后创建路由
const feishuRouter = createFeishuRouter();
app.use('/api/feishu', feishuRouter);
```
### 新版本（简洁）
```typescript
import { createFeishuRouter } from 'fmode-feishu-api';
// 直接传入配置，一步完成
const feishuRouter = createFeishuRouter({
'cli_xxx': {
appId: 'cli_xxx',
appSecret: 'secret',
company: 'company_id',
enabled: true
}
});
app.use('/api/feishu', feishuRouter);
```
## 常见问题
### 1. 如何获取飞书应用ID和密钥？
访问 [飞书开放平台](https://open.feishu.cn/) 创建企业自建应用。
### 2. 如何配置回调地址？
在飞书开放平台的应用配置中，设置"重定向URL"。
### 3. Token过期怎么办？
- `tenant_access_token`: 自动管理，有效期2小时，提前5分钟自动刷新
- `user_access_token`: 使用 `/oauth2/refresh_token` 接口刷新
### 4. 如何处理多个飞书应用？
在 `createFeishuRouter` 中传入多个应用配置即可。
## 技术支持
- [飞书开放平台文档](https://open.feishu.cn/document/)
- [项目源码](./src/)