diff --git a/CLAUDE.md b/CLAUDE.md
index 294f0ae..9fa2b99 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -69,8 +69,11 @@ Lang::setLocale('en');
 ├── nginx/                # OpenResty 配置
 ├── frpc/                 # frpc 配置
 ├── docs/                # 项目文档
-│   ├── PROJECT.md            # 项目详细文档
-│   └── IMPLEMENTATION_PLAN.md # 实现计划
+│   ├── PROJECT.md                  # 项目详细文档
+│   ├── FEISHU_LOGIN_EXPERIENCE.md  # 飞书登录实现经验（重要）
+│   ├── feishu-qrcode-login.md      # 飞书扫码登录原始文档
+│   ├── PROJECT_ISSUES.md           # 历史问题汇总
+│   └── IMPLEMENTATION_PLAN.md      # 实现计划
 ```
 
 ## 环境配置
@@ -97,9 +100,14 @@ Lang::setLocale('en');
 
 ### 前端关键文件
 - 入口：`frontend/src/main.tsx`
+- SDK 引入：`frontend/index.html`（飞书 H5 JSSDK + QR SDK）
 - 路由：`frontend/src/router/index.tsx`
 - 布局：`frontend/src/components/layout/`
 - 状态管理：`frontend/src/stores/`
+- API 封装：`frontend/src/services/api.ts`（含 401 token 刷新）
+- 登录页：`frontend/src/pages/login/index.tsx`
+- 扫码登录：`frontend/src/pages/login/QRCodeLogin.tsx`
+- 环境检测：`frontend/src/pages/feishu-env-test.tsx`
 - rem 适配：`frontend/src/utils/rem.ts`
 
 ### 后端关键文件
@@ -153,8 +161,35 @@ docker exec x-server-backend php test_data.php
 
 ## 飞书集成
 
-### 免登接口
-- 回调：`POST /api/v1/auth/feishu-login`
+### 登录方式
+支持两种飞书登录方式：
+
+| 方式 | 使用场景 | SDK |
+|------|----------|-----|
+| **飞书内免登** | 用户在飞书客户端内打开应用，自动登录 | H5 JSSDK (`h5-js-sdk-1.5.19.js`) |
+| **飞书外扫码登录** | 用户在普通浏览器中打开，用飞书扫码登录 | QR SDK (`LarkSSOSDKWebQRCode-1.0.3.js`) |
+
+### 核心接口
+- `POST /api/v1/auth/feishu-login` - 飞书免登/扫码登录
+- `GET /api/v1/auth/feishu-config?company=2` - 获取公司飞书应用配置
+- `POST /api/v1/auth/qrcode-login` - 生成扫码登录二维码
+- `GET /api/v1/auth/qrcode-login/status?session_id=xxx` - 轮询扫码状态
+- `GET /login/callback` - 飞书授权回调
+
+### URL 参数
+| 参数 | 说明 | 示例 |
+|------|------|------|
+| `company` | 公司ID（必需） | `?company=2` |
+| `app_id` | 飞书应用ID（可选） | `?app_id=cli_xxx` |
+| `redirect` | 登录成功后跳转地址 | `?redirect=/dashboard` |
+
+### Token 自动刷新
+- API 返回 401 时，在飞书环境中自动调用免登刷新 token
+- 刷新成功后自动重试原始请求，用户无感知
+- 使用 `_retry` 标记防止死循环
+
+### 详细文档
+飞书登录完整实现经验：`docs/FEISHU_LOGIN_EXPERIENCE.md`
 
 ### 环境变量
 ```env
@@ -250,6 +285,11 @@ composer require symfony/var-dumper:^7.0
 - ✅ 后端 API 框架搭建完成
 - ✅ 5语言国际化支持完成
 - ✅ Docker 开发环境配置完成
+- ✅ 飞书登录完成
+  - ✅ 飞书内免登（静默授权）
+  - ✅ 飞书外扫码登录
+  - ✅ Token 过期自动刷新（飞书环境）
+  - ✅ 多租户支持（company 参数）
 - ✅ 审批流程引擎完成
   - ✅ 通用审批列表页（我发起的/待我审批/我已审批）
   - ✅ 通用审批详情页（支持审批通过/拒绝/撤销操作）
@@ -272,9 +312,13 @@ composer require symfony/var-dumper:^7.0
 ### 查看问题汇总
 所有历史问题已整理在 `docs/PROJECT_ISSUES.md` 文件中。
 
+### 飞书登录文档
+飞书登录完整实现经验和调试技巧：`docs/FEISHU_LOGIN_EXPERIENCE.md`
+
 ### 让 CLAUDE 加载问题文档
 ```
 请参考 docs/PROJECT_ISSUES.md 中的问题汇总
+请参考 docs/FEISHU_LOGIN_EXPERIENCE.md 中的飞书登录经验
 ```
 
 ### 调试后端