docs: 重组文档结构，按模块分类

新的文档结构： 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
parent d37d82bc13
commit e3fa7e86f3
16 changed files with 741 additions and 0 deletions
@@ -0,0 +1,137 @@
+# 认证模块 (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