kaoqin-services/README.md

考勤系统服务库 (重构版 - 支持n8n webhook)

# kaoqin-services

考勤系统服务库，提供考勤相关服务功能。重构版支持 n8n webhook 接口。

## 特性

- ✅ 支持 n8n webhook 接口调用
- ✅ 灵活的考勤记录处理和转换
- ✅ 多种通知方式（微信、Ntfy）
- ✅ 节假日判断功能
- ✅ 状态管理和时间控制
- ✅ 出差、迟到等特殊状态处理

## 安装

```bash
npm install kaoqin-services
```

或者使用yarn：

```bash
yarn add kaoqin-services
```

## 版本说明

### v2.0.0 (重构版)
- 🔄 重构考勤记录获取接口，支持 n8n webhook
- 🆕 新增数据格式转换功能
- 🆕 支持出差、迟到等特殊考勤状态
- 🆕 增强调试日志输出
- ⚡ 简化用户初始化流程

### v1.x.x (传统版)
- 基于原有 API 接口的考勤服务

## 核心服务

### KaoqinService 
考勤服务，处理用户初始化、打卡记录查询和通知发送

### ApiService
API服务，处理HTTP请求和响应

### HolidayService
节假日服务，判断日期是否为工作日

### NotificationServices
通知服务集合，包含多种通知方式

## 使用示例

```javascript
const { 
  KaoqinService, 
  ApiService, 
  HolidayService, 
  NotificationServices 
} = require('kaoqin-services');
const { StateManager } = require('kaoqin-utils');

// 配置管理器
class ConfigManager {
  constructor() {
    this.config = {
      USERNAME: '您的用户名',
      API_BASE_URL: 'https://appsy.jbysoft.com',
      NTFY: {
        serverUrl: "https://ntfy.example.com",
        topic: "test",
        enabled: true
      },
      REMINDER: {
        morningStart: { hour: 6, minute: 0 },
        morningEnd: { hour: 10, minute: 0 },
        eveningStart: { hour: 18, minute: 0 },
        eveningEnd: { hour: 23, minute: 59 }
      }
    };
  }
  
  get(key) {
    return key.split('.').reduce((obj, k) => obj && obj[k], this.config);
  }
}

// 初始化服务
const configManager = new ConfigManager();
const stateManager = new StateManager('./kaoqin-state.json');
const apiService = new ApiService(configManager);

// 创建通知服务
const { CompositeNotificationService, NtfyService, WeChatService } = NotificationServices;
const notificationService = new CompositeNotificationService([
  new NtfyService(configManager),
  new WeChatService(configManager)
]);

// 创建假日服务
const holidayService = new HolidayService({
  holidayFilePath: './holiday.json',
  stateManager
});

// 创建考勤服务
const kaoqinService = new KaoqinService({
  configManager,
  stateManager,
  apiService,
  notificationService,
  holidayService
});

async function main() {
  // 初始化服务
  const userInfo = await kaoqinService.initialize();
  if (!userInfo) {
    console.error('用户初始化失败');
    return;
  }

  // 处理考勤记录
  await kaoqinService.processKaoqinRecords();
}

main().catch(console.error);
```

## 配置说明

### n8n Webhook 配置

服务会调用 n8n webhook 接口获取考勤数据：

```javascript
const webhookConfig = {
  url: 'https://n8n.201807.xyz/webhook/dkjl',
  timeout: 10000,
  auth: 'Basic <base64编码的认证信息>'
};
```

### 支持的考勤状态

- `出差`: 自动根据时间判断上班/下班
- `迟到`: 识别为上班打卡
- `早退`: 识别为下班打卡
- 其他状态: 按默认规则处理

## API 文档

### KaoqinService

#### `initialize(username?)`
初始化考勤服务
- `username`: 可选，用户名

#### `queryKaoqinRecords(date)`
查询指定日期的考勤记录
- `date`: 查询日期

#### `processKaoqinRecords(date?)`
处理考勤记录并发送通知
- `date`: 可选，处理日期

#### `testNtfyNotification()`
测试 Ntfy 通知功能

#### `resetNotificationStatus()`
重置通知状态

## 变更日志

### v2.0.0
- 重构接口调用方式，支持 n8n webhook
- 新增考勤状态智能识别
- 优化数据转换逻辑
- 增强错误处理和日志输出

## 许可证

ISC