# 飞书应用免登集成 (Step 5) — 2026-07-26 更新

## 目标
将 CloudBase 工作台嵌入飞书工作台。销售员从飞书打开 → 首次输密码 → 后续自动登录。

## 架构

```
飞书工作台 → 点应用 → CloudBase 页面
  → URL 含 ?code=xxx → feishuAutoLogin() → 云函数换身份 → 免登
  → 无 code → 首次密码登录 → localStorage 记住 → 后续自动
```

## 已完成

### 飞书应用
- ✅ App ID: `cli_aaee6a2f90b89bc1`
- ✅ 网页应用配置（主页 URL / 安全域名）
- ✅ 通讯录权限（待管理员审批）
- ✅ 已发布到飞书工作台

### 前端 OAuth 检测
- `init()` 检测 URL `?code=xxx` 参数
- `feishuAutoLogin(code)` → fetch 云函数 → 正常则免登，失败回退密码

### 鉴权系统（CloudBase）
- 匿名登录 → 查询 `user_roles` 集合 → 验证 password
- 23人权限体系：admin(1)/manager(3)/sales(19)
- Tab 按 tabs 字段过滤，数据按 role+dept 过滤

## 待完成

### 云函数 HTTP 触发器
代码：`/tmp/cloudbase-setup/feishuAuth/index.js`
部署：CloudBase 控制台 → feishuAuth 函数 → 触发管理 → 新建 HTTP 触发器 → 路径 `/feishuAuth`

### 通讯录权限
`contact:contact.base:readonly` + `contact:department.organize:readonly` 待飞书管理员审批

## Feishu App 配置

| Setting | Value |
|---------|-------|
| 桌面端主页 | `https://bier-sales-d0gatbvlx288724e9-1458438710.tcloudbaseapp.com/index.html` |
| 移动端主页 | 同上 |
| H5 可信域名 | `https://bier-sales-d0gatbvlx288724e9-1458438710.tcloudbaseapp.com` |
| 安全域名 | 同上 |

## 关键教训

1. **URL 中文问题**：飞书校验拒绝含中文的 URL，必须部署到根路径 ASCII 路径
2. **MCP 写权限**：需用户在飞书项目个人偏好中单独开启，默认只读。替代方案：用 URL 跳转飞书原生页面
3. **CloudBase 云函数 CLI**：`tcb fn deploy` 交互式选择无法自动化，HTTP 触发器必须控制台手动添加
4. **CloudBase DB 写权限**：安全规则「仅创建者可写」导致匿名用户无写权限，admin.html 改为 JSON 导出模式
5. **localStorage 够用**：23人内部团队，首次密码登录 + 后续自动登录可接受