# @luka-cat-mimi/n8n-nodes-feishu-project

在 n8n 中轻松操作飞书项目 —— 无需写代码，拖拽即可实现工作项管理自动化。

## 为什么选择这个节点？

| 痛点 | 解决方案 |
|------|----------|
| 飞书项目 API 调用复杂 | **动态表单**：空间、工作项类型自动加载，下拉选择即可 |
| 分页数据获取麻烦 | **一键获取全部**：自动处理分页，返回完整数据 |
| API 限流导致失败 | **批次处理**：自动控制请求频率，避免触发限流 |
| 请求卡死无响应 | **超时保护**：设置超时时间，请求异常及时中断 |

## 安装

```
npm install @luka-cat-mimi/n8n-nodes-feishu-project
```

或在 n8n 社区节点中搜索安装，参考：[社区节点安装指南](https://docs.n8n.io/integrations/community-nodes/installation/)

## 节点概览

本插件包含两个节点：

| 节点 | 类型 | 说明 |
|------|------|------|
| **飞书项目** | 操作节点 | 调用飞书项目 API，支持工作项、空间、用户、工作流等 68 个操作 |
| **监听事件** | 触发器（Webhook） | 接收飞书项目回调事件，按条件触发工作流 |

## 触发器：监听事件

通过 Webhook 接收飞书项目的回调事件来触发工作流，固定使用 **POST** 方法。

### 支持的事件

| 类型 | 事件（编码） |
|------|------|
| 工作项（100） | 创建（1001）/ 删除（1002）/ 恢复（1004）/ 终止（1005）/ 模版升级（1006）/ 修改字段（1009） |
| 节点（200） | 完成（2001）/ 删除（2002）/ 恢复（2003）/ 回滚（2004）/ 修改估分与排期（2005）/ 修改负责人（2006）/ 修改实际工时（2007）/ 多人确认流转（2009） |
| 状态（300） | 状态变更（3001） |
| 子任务（400） | 新建（4001）/ 删除（4002）/ 完成（4003）/ 取消完成（4004）/ 修改负责人（4005）/ 修改估分（4006）/ 修改排期（4007）/ 修改实际工时（4008）/ 修改字段（4009） |
| 空间（500） | 添加成员（5001）/ 删除成员（5002）/ 完成工作移交（5003）/ 拒绝工作移交（5004） |
| 插件（600） | 安装（6001）/ 卸载（6002）/ 更新（6003）/ 购买（6004） |

「监听事件」支持通配符 `*`（所有事件），默认选中。

### 配置回调地址

将节点生成的 Webhook URL 填入飞书项目对应的回调地址中：

1. 工作项 / 节点 / 状态 / 子任务 / 空间等业务事件（100~500）：**开发者后台 → 插件功能 → 插件构成 添加构成 → 监听事件**
2. 插件安装 / 卸载 / 更新 / 购买等插件事件（600）：**开发者后台 → 插件发布 → 插件事件订阅**

### 验证签名（可选）

开启「验证签名」后填入回调 Token，节点会按 `sha256(plugin_id + request_time + token)` 计算签名并与请求体 `signature` 比对，校验失败返回 401。

### 过滤选项（Options）

支持对回调进行多级过滤，判断顺序为：**签名 → 来源类型 → 监听事件 → 飞书项目空间 → 工作项类型**，任一不匹配则忽略（返回 200 但不触发工作流）。

| 选项 | 说明 |
|------|------|
| **允许来源类型** | 多选：普通用户操作（normal）、OpenAPI（openapi）、系统行为（system）、自动化（automation）。按 `source` 匹配 |
| **允许飞书项目空间** | 动态多选，默认通配符。按 `data.project_key` 匹配 |
| **允许的工作项类型** | 字符串，支持逗号分隔、JSON 数组或表达式数组（如 `["issue","story"]`、`issue,story`、`{{ ["issue","story"] }}`），默认通配符 `*`。按 `data.work_item_type_key` 匹配；事件不含该字段时视为通过 |

## 支持的功能（68 个操作）

<details>
<summary><b>工作项管理（16 个）</b>- 创建、更新、删除、批量操作...</summary>

- 创建工作项 / 查询工作项详情 / 更新工作项 / 删除工作项
- 批量更新工作项 / 终止工作项 / 获取工作项元数据 / 获取工作项操作记录
- 获取工作项任务结果 / 批量查询评审信息 / 查询评审结论 / 更新评审
- 创建工时记录 / 获取工时记录列表 / 更新工时记录 / 删除工时记录
</details>

<details>
<summary><b>工作项搜索（4 个）</b>- 单空间搜索、复杂条件、全局搜索...</summary>

- 单空间工作项搜索 / 复杂条件搜索 / 全局搜索 / 关联工作项搜索
</details>

<details>
<summary><b>工作项配置（9 个）</b>- 字段管理、关联配置...</summary>

- 获取/更新工作项基础信息
- 创建/获取/更新工作项字段
- 创建/获取/更新/删除工作项关联配置
</details>

<details>
<summary><b>空间管理（6 个）</b>- 空间列表、详情、成员...</summary>

- 获取空间列表 / 获取空间列表详情 / 获取空间详情
- 获取空间业务线 / 获取空间工作项类型列表
- 获取空间团队成员（支持分页、Return All、自动获取用户详情）
</details>

<details>
<summary><b>空间关联（4 个）</b>- 工作项关联绑定...</summary>

- 获取关联规则列表 / 绑定工作项关联 / 解绑工作项关联 / 获取关联工作项列表
</details>

<details>
<summary><b>流程与节点（5 个）</b>- 流程节点操作、状态变更...</summary>

- 查询流程节点 / 更新流程节点 / 操作流程节点 / 变更工作项状态 / 获取WBS视图
</details>

<details>
<summary><b>子任务（5 个）</b>- 子任务 CRUD...</summary>

- 创建子任务 / 获取子任务详情 / 更新子任务 / 操作子任务 / 删除子任务
</details>

<details>
<summary><b>视图管理（8 个）</b>- 视图创建、更新...</summary>

- 获取视图列表 / 创建条件视图 / 更新条件视图 / 创建固定视图
- 更新固定视图 / 删除视图 / 获取全景视图 / 获取视图工作项列表
</details>

<details>
<summary><b>评论管理（4 个）</b>- 评论 CRUD，支持多种对象与内容类型...</summary>

- 添加评论 / 查询评论 / 更新评论 / 删除评论
- 支持评论对象类型：工作项（WORKITEM）、工作项字段（WORKITEMFIELD）、子评论（CHILDCOMMENT）
- 支持内容类型：纯文本（TEXT）、富文本（RICHTEXT）、附件（FILE）
- 查询评论支持分页方向、返回富文本 Markdown
</details>

<details>
<summary><b>附件管理（4 个）</b>- 工作项附件上传下载...</summary>

- 添加附件 / 下载附件 / 删除附件
- 上传文件或富文本图片（通用上传，主要用于富文本中插入图片）
</details>

<details>
<summary><b>文件管理（2 个）</b>- 评论附件上传下载...</summary>

- 上传文件（小于 20MB，用于评论附件或富文本图片，上传后需绑定到业务）
- 下载文件（通过 file_token 下载已绑定业务的文件，支持二进制输出）
</details>

<details>
<summary><b>用户管理（2 个）</b>- 用户信息、用户搜索...</summary>

- 获取用户信息 / 搜索租户内的用户列表
</details>

<details>
<summary><b>其他（3 个）</b>- 流程模板、角色、群组、度量...</summary>

- 创建流程模板 / 获取流程角色列表 / 机器人加入聊天 / 获取图表详情
</details>

## 快速开始

### 1. 获取凭证

| 凭证 | 获取方式 |
|------|----------|
| **插件 ID / 密钥** | 飞书项目管理后台 → 插件管理 → 创建或查看插件 |
| **用户 ID** | 飞书项目空间左下角 → 双击个人头像 |
| **Host** | 通常为 `project.feishu.cn` |

### 2. 配置凭证

在 n8n 中创建 **飞书项目 API** 凭据：

| 字段 | 示例 |
|------|------|
| 飞书项目 Host | `project.feishu.cn` |
| 插件 ID | `MII_0000000000000000` |
| 插件密钥 | `AB92E56666CT8D60704743BF69C92C16` |
| 用户 ID | `7568516887894324252` |
| 鉴权模式 | 默认开启强制鉴权（`1`），严格按用户 ID 校验权限；设为 `0` 可切换兼容模式 |

### 3. 评论附件工作流示例

在评论中插入附件的典型流程：

1. **文件 → 上传文件**：上传二进制文件，获取 `file_token`
2. **评论 → 添加评论**：内容类型选「附件 (FILE)」，填入上一步的 `file_token`
3. **文件 → 下载文件**：文件绑定到评论后，可用 `file_token` 下载

> 上传的文件在未绑定到评论等业务前无法下载，超过 7 天未绑定会自动删除。

### 4. 开始使用

拖入节点 → 选择资源和操作 → 填写参数 → 执行！

## 注意事项

- 确保插件具有所需 API 的访问权限
- [错误码查询](https://project.feishu.cn/b/helpcenter/1p8d7djs/4bsmoql6)

## 支持

- 邮箱：luka.cat.mimi@gmail.com
- [问题反馈](https://github.com/luka-n8n-nodes/n8n-nodes-feishu-project/issues)

## 许可证

MIT License