Files

T

新的文档结构：
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、关键文件等

2026-02-28 11:42:51 +08:00

3.4 KiB

Raw Blame History

认证模块 (Auth Module)

概述

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

登录方式	说明	文档
飞书内免登	在飞书客户端内自动登录	feishu-login.md
飞书外扫码登录	普通浏览器扫码登录	feishu-qrcode.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 # 飞书应用配置

环境变量

# 飞书应用配置（多租户时在数据库中配置）
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。

3.4 KiB Raw Blame History