npm package: @luka-cat-mimi/n8n-nodes-italent
Description: 北森 iTalent N8N 集成插件
Author: luka-cat
Latest version: 1.0.7

# 北森 iTalent N8N 集成插件

![License](https://img.shields.io/badge/license-MIT-blue.svg)
![N8N](https://img.shields.io/badge/platform-N8N-brightgreen.svg)
![TypeScript](https://img.shields.io/badge/language-TypeScript-blue.svg)
![Node.js](https://img.shields.io/badge/node-%3E%3D20.15-green.svg)

一个功能完整的 N8N 自定义节点，用于集成北森 iTalent AI面试官 API，支持工作意向题目、作答结果、邀请链接、应聘者信息等核心功能。

## 🚀 特性

- ✅ **AI面试官模块**，完整支持北森AI面试官API
- ✅ **安全认证**，自动管理Access Token和凭证刷新
- ✅ **智能分页**，支持自动分页获取大量数据
- ✅ **批处理支持**，可配置批量请求和请求间隔
- ✅ **数组限制**，智能验证inviteIds数量（10/20/100）
- ✅ **表达式支持**，完美支持n8n表达式传递数组数据
- ✅ **TypeScript支持**，完整的类型定义和智能提示
- ✅ **灵活扩展**，基于模块化设计，易于添加新功能

## 📦 安装

### 方式一：NPM 安装 (推荐)

```bash
npm install @luka-cat-mimi/n8n-nodes-italent
```

### 方式二：手动安装

1. 下载项目到本地
2. 编译项目

```bash
npm install
npm run build
```

3. 将编译后的文件复制到 N8N 的 `custom` 目录

## ⚙️ 配置

### 1. 创建凭据

在 N8N 中创建新的 "北森 iTalent API" 凭据，填入以下信息：

| 字段 | 说明 | 示例 |
|------|------|------|
| **请求地址** | 北森API的基础地址 | `https://open.italent.cn` |
| **App Key** | 应用的App Key | `your_app_key` |
| **App Secret** | 应用的App Secret | `your_app_secret` |

### 2. 获取凭据信息

#### 请求地址

默认使用北森开放平台地址：`https://open.italent.cn`

如果您使用的是私有化部署，请联系北森技术支持获取对应的API地址。

#### App Key 和 App Secret

1. 登录北森开放平台（https://open.italent.cn）
2. 进入"应用管理"页面
3. 创建或查看应用，获取 App Key 和 App Secret

## 📊 功能模块

### AI面试官模块

| 操作 | 限制 | 主要功能 |
|------|------|----------|
| **获取工作意向题目详情** | - | 获取AI面试的工作意向题目，支持自动分页 |
| **获取作答结果** | 最多10个ID | 批量获取面试作答结果 |
| **发起AI面试** | - | 根据规则对象发起AI面试 |
| **获取邀请链接** | 最多20个ID | 批量获取面试邀请链接 |
| **获取通知模板列表** | - | 获取所有启用的AI面试通知模板，支持自动分页 |
| **取消AI面试** | 最多100个ID | 批量取消AI面试 |
| **获取应聘者信息** | 最多100个ID | 获取AI面试应聘者详细信息 |
| **获取活动数据** | - | 获取所有启用的AI面试活动，支持自动分页 |

### 核心特性

#### 1. 智能数组限制
不同操作有不同的inviteIds数量限制：
- **获取作答结果**：最多 10 个
- **获取邀请链接**：最多 20 个  
- **获取应聘者信息**：最多 100 个
- **取消AI面试**：最多 100 个

#### 2. 表达式支持
所有inviteIds字段支持：
- JSON字符串：`["id1", "id2", "id3"]`
- n8n表达式：`{{ $json.inviteIds }}`
- 自动类型转换和验证

#### 3. 自动分页
以下操作支持 Return All 开关自动获取所有分页数据：
- 获取工作意向题目详情
- 获取通知模板列表
- 获取活动数据

#### 4. 批处理配置
所有操作都支持Options配置：
- **Batching**：批量处理和间隔控制
- **Timeout**：请求超时设置

## 🔧 使用示例

### 示例1：获取作答结果

```javascript
// 使用JSON字符串
Invite IDs: ["7e35949f-6e10-401a-b507-618eaa015130", "bf50fc2a-e009-49c2-8b1b-c2e1675a0dc9"]

// 或使用表达式
Invite IDs: {{ $json.inviteIds }}
```

### 示例2：获取邀请链接

```javascript
// 最多20个ID
Invite IDs: {{ $items().map(item => item.json.inviteId).slice(0, 20) }}
```

### 示例3：自动分页获取工作意向题目

1. 选择操作：**获取工作意向题目详情**
2. 开启 **Return All** 开关
3. 系统自动处理分页，返回所有题目数据

### 示例4：批量获取应聘者信息

```javascript
// 最多100个ID，支持额外字段
Invite IDs: {{ $json.inviteIds }}
Ext Columns: ["name", "height", "weight", "Email"]

// 配置批处理（避免频控）
Options → Batching:
  - Items per Batch: 50
  - Batch Interval: 1000ms
```

## 🔧 开发

### 项目结构

```text
n8n-nodes-italent/
├── credentials/                 # 凭据定义
│   └── ITalentApi.credentials.ts
├── nodes/                      # 节点定义
│   ├── help/                   # 工具类和类型定义
│   │   ├── builder/           # 资源构建器
│   │   ├── type/              # 类型定义
│   │   └── utils/             # 工具函数
│   └── ITalent/
│       ├── ITalent.node.ts
│       └── resource/           # 资源模块
│           └── aiInterview/    # AI面试官模块
│               ├── GetWorkIntentionQuestions.ts
│               ├── GetAIInterviewReportResult.ts
│               ├── ArrangeAIInterview.ts
│               ├── GetInviteTestUrl.ts
│               ├── GetSysMessageTemplateList.ts
│               ├── CancelAIInterview.ts
│               ├── GetInviteRecordInfo.ts
│               └── GetActivityViewActivities.ts
└── package.json
```

### 构建命令

```bash
# 开发模式
npm run dev

# 构建
npm run build

# 代码检查
npm run lint

# 格式化代码
npm run format
```

### 添加新操作

参考现有的AI面试官操作文件，在 `nodes/ITalent/resource/aiInterview/` 下创建新的操作文件。

所有操作都遵循统一的模式：
1. 支持表达式和JSON字符串输入
2. 包含Options配置（Batching和Timeout）
3. 智能验证和错误提示
4. 自动批次延迟处理

**就这样！** 无需修改其他任何代码，新操作会被自动发现和加载。

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

### 贡献指南

1. Fork 项目
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开 Pull Request

## 📝 许可证

本项目采用 MIT 许可证。详情请参见 [LICENSE.md](./LICENSE.md) 文件。

## 🆘 支持

- 📧 邮箱：**luka.cat.mimi@gmail.com**
- 🐛 问题反馈：[GitHub Issues](https://github.com/luka-n8n-nodes/n8n-nodes-italent/issues)
- 📖 北森开放平台：[官方文档](https://open.italent.cn/)

## ⭐ 致谢

感谢 [N8N](https://n8n.io/) 提供的强大自动化平台

---

如果这个项目对你有帮助，请给它一个 ⭐️！