# aio

**Repository Path**: webvip/aio

## Basic Information

- **Project Name**: aio
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: develop
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-18
- **Last Updated**: 2026-05-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AIO

AIO 是一个面向 Frappe / ERPNext 的企业协同集成应用。目前重点实现飞书接入，包含飞书登录、用户绑定、通讯录同步、通讯录推送和同步日志。

## 功能概览

- 在 Frappe 登录页增加“Login with Feishu”按钮，用户可通过飞书 OAuth 登录。
- 支持独立测试页 `/feishu-login`，用于验证飞书授权回调。
- 支持按邮箱、手机号匹配飞书用户与 Frappe 用户。
- 支持在 `User` 和 `Employee` 表单中手动绑定飞书账号。
- 支持从飞书同步部门和用户到 Frappe。
- 支持从 Frappe / ERPNext 推送部门和用户到飞书。
- 提供 `Feishu Settings`、`Feishu User Binding`、`Feishu Department`、`Feishu Sync Log` 等 DocType 管理界面。

## 安装

在 bench 目录中安装应用：

```bash
cd $PATH_TO_YOUR_BENCH
bench get-app $URL_OF_THIS_REPO --branch develop
bench --site $SITE_NAME install-app aio
bench --site $SITE_NAME migrate
bench --site $SITE_NAME clear-cache
bench build --app aio
```

如果已经安装过应用，更新代码后至少执行：

```bash
bench --site $SITE_NAME migrate
bench --site $SITE_NAME clear-cache
bench build --app aio
```

## 飞书开放平台配置

在飞书开放平台创建或打开企业自建应用，记录：

- `App ID`
- `App Secret`

在飞书应用的安全设置中配置重定向 URL：

```text
https://$YOUR_SITE/api/method/aio.feishu.auth.callback
```

本地开发时可使用类似：

```text
http://127.0.0.1:8000/api/method/aio.feishu.auth.callback
```

这个地址必须和 AIO 中 `Feishu Settings` 的 `Redirect URI` 完全一致。

## AIO 配置

以 `System Manager` 身份进入 Desk，打开 `Feishu Settings`，填写：

- `Enabled`：启用飞书集成。
- `App ID`：飞书应用的 App ID。
- `App Secret`：飞书应用的 App Secret。
- `Redirect URI`：飞书开放平台中配置的回调地址。
- `Auto Create Users`：从飞书同步通讯录时，是否自动创建 Frappe 用户。
- `Default User Type`：自动创建用户时使用 `System User` 或 `Website User`。
- `Push Parent Department ID`：从 Frappe 推送根部门到飞书时使用的父级飞书部门 ID。只有应用具备根部门权限时才建议使用 `0`。

保存后可以点击 `Test Connection` 验证 App ID 和 App Secret 是否可用。

## 飞书登录

启用飞书配置后，AIO 会在 Frappe 标准登录页 `/login` 自动增加飞书登录按钮。点击按钮后会进入飞书授权页，授权成功后回调：

```text
/api/method/aio.feishu.auth.callback
```

登录匹配逻辑：

1. 优先使用已有的 `Feishu User Binding` 匹配。
2. 如果没有绑定，则按飞书返回的邮箱匹配 Frappe `User.email`。
3. 如果邮箱未命中，则按手机号匹配。
4. 匹配成功后会写入或更新 `Feishu User Binding`。

如果无法匹配用户，回调页面会显示飞书账号的 `open_id`、`union_id`、`user_id`、邮箱和手机号，方便管理员手动绑定。

也可以直接打开测试页：

```text
/feishu-login
```

## 手动绑定飞书用户

管理员可以通过以下入口手动绑定：

- `User` 表单：点击 `Feishu > Bind Feishu User`
- `Employee` 表单：点击 `Feishu > Bind Feishu User`
- `Feishu User Binding` 列表：直接新增或编辑绑定记录

绑定时至少需要填写 `Open ID`。如果知道 `Union ID`、飞书 `User ID`、邮箱或手机号，也可以一并填写，后续登录和同步会更稳定。

## 通讯录同步

### 从飞书同步到 Frappe

在 `Feishu Settings` 中可以使用：

- `Preview From Feishu`：预览同步结果，不写入数据。
- `Sync From Feishu`：创建后台任务，从飞书同步部门和用户。

命令行也可以执行：

```bash
bench --site $SITE_NAME execute aio.feishu.contact.preview_sync_contacts
bench --site $SITE_NAME execute aio.feishu.contact.sync_contacts
```

同步结果会写入：

- `Feishu Department`
- `Feishu User Binding`
- `Feishu Sync Log`

当飞书用户返回邮箱且 `Auto Create Users` 已启用时，系统会自动创建或更新 Frappe 用户。

### 从 Frappe 推送到飞书

在 `Feishu Settings` 中可以使用：

- `Preview Push To Feishu`：预览推送结果，不写入飞书。
- `Push To Feishu`：创建后台任务，将 Frappe / ERPNext 部门和用户推送到飞书。

命令行也可以执行：

```bash
bench --site $SITE_NAME execute aio.feishu.contact.preview_push_contacts
bench --site $SITE_NAME execute aio.feishu.contact.push_contacts_to_feishu
```

推送会创建或更新飞书部门和用户，不会删除飞书通讯录中的数据。

## 员工自动同步

应用会监听 `Employee` 的新增和更新事件，并尝试将员工联系人同步到飞书：

- `after_insert`
- `on_update`

在单个 `Employee` 表单中，也可以点击 `Feishu > Sync to Feishu` 手动同步当前员工。

## 权限

- `Feishu Settings` 仅 `System Manager` 可读写。
- 启动同步、推送、预览和手动绑定飞书用户都要求 `System Manager` 权限。
- 飞书登录回调允许 Guest 访问，这是 OAuth 登录流程必需的。

## 常见问题

### 登录页没有飞书按钮

请检查：

1. 已执行 `bench build --app aio`。
2. 已执行 `bench --site $SITE_NAME clear-cache`。
3. 浏览器对 `/login` 做了硬刷新，或退出登录后重新打开。
4. `/assets/aio/js/feishu_login_button.js` 可以正常访问。
5. `Feishu Settings` 已启用，并且 App ID、App Secret、Redirect URI 都已填写。

### 点击飞书登录后提示无法匹配用户

说明飞书账号没有匹配到 Frappe 用户。可以选择：

- 确认 Frappe 用户邮箱和飞书邮箱一致。
- 确认 Frappe 用户手机号和飞书手机号一致。
- 在 `User` 或 `Employee` 表单中手动绑定飞书账号。
- 直接在 `Feishu User Binding` 中新增绑定记录。

### 通讯录同步失败

优先检查：

- 飞书应用是否已发布或已对当前企业可用。
- 飞书应用是否具备通讯录读取、用户读取、部门读取等权限。
- 如果要推送到飞书，是否具备通讯录写入权限。
- `Push Parent Department ID` 是否和飞书应用的部门权限范围一致。
- `Feishu Sync Log` 中的错误详情。

## 开发

安装 pre-commit：

```bash
cd apps/aio
pre-commit install
```

常用检查：

```bash
python -m py_compile aio/feishu/auth.py aio/feishu/contact.py aio/feishu/sync_job.py
node --check aio/public/js/feishu_login_button.js
node --check aio/public/js/employee.js
node --check aio/public/js/user.js
```

## 许可证

MIT