youfool-holiday-sdk/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a Java SDK for holiday/workday calculations called `youfool-holiday-sdk`. It provides functionality to:

- Calculate workdays by skipping holidays and weekends
- Check if a specific date is a workday
- Check if a specific datetime is within working hours
- Support both online and offline data modes for holiday information

## Build Commands

```bash
# Compile the project
mvn compile

# Build the JAR with sources
mvn clean package

# Install to local repository
mvn clean install

# Skip tests during build (default behavior)
mvn clean package -DskipTests
```

## Architecture

The SDK follows a factory pattern with strategy implementation for data management:

### Core Components

1. **HolidayCalculator** (`src/main/java/com/chinaweal/youfool/holiday/sdk/HolidayCalculator.java`)
   - Main API entry point with static methods
   - Provides workday calculation and date/time validation methods
   - Must be initialized with `HolidayCalculatorConfig` before use

2. **HolidayCalculatorConfig** (`src/main/java/com/chinaweal/youfool/holiday/sdk/config/HolidayCalculatorConfig.java`)
   - Configuration class with Lombok annotations
   - Controls online/offline mode, work hours, data refresh intervals
   - Online mode: fetches from API endpoint
   - Offline mode: loads from local JSON files

3. **Data Management Strategy Pattern**
   - `AbstractHolidayDataManager`: Base class with caching and synchronization logic
   - `OnlineHolidayDataManager`: Fetches data from REST API
   - `LocationHolidayDataManager`: Loads from local JSON files in classpath or filesystem

4. **Holiday Entity** (`src/main/java/com/chinaweal/youfool/holiday/sdk/data/entity/Holiday.java`)
   - Data model with Jackson JSON serialization
   - Contains date, festival name, type (holiday/workday), and descriptions

### Data Flow

1. Initialization creates appropriate data manager based on config
2. Data managers implement lazy loading with configurable refresh intervals
3. Thread-safe data access with synchronization blocks
4. Work time validation uses configurable time ranges

## Dependencies

- **Lombok 1.18.12**: Code generation for getters/setters
- **FastJSON2 2.0.56**: JSON serialization/deserialization
- **Jackson Annotations 2.18.5**: JSON format annotations
- **JUnit 4.12**: Testing framework

## 配置方式

### 🔧 Spring Boot 项目配置（推荐）

在 Spring Boot 项目中，SDK 支持自动配置和 YAML/Properties 文件配置：

#### 1. 添加依赖

```xml
<dependency>
    <groupId>com.chinaweal.youfool</groupId>
    <artifactId>youfool-holiday-sdk</artifactId>
    <version>1.0.0</version>
</dependency>
```

#### 2. YAML 配置 (`application.yml`)

```yaml
youfool:
  holiday:
    # 是否启用假期计算器，默认启用
    enabled: true

    # 数据模式：true=在线模式，false=离线模式，默认离线
    online: false

    # 在线模式下的API服务器地址
    host: http://www.chinaweal.com.cn:8090/holiday-api

    # 离线模式下的本地配置目录
    config-path: classpath:holiday

    # 工作时间配置，多个时间段用分号分隔
    # 格式：HH:mm-HH:mm;HH:mm-HH:mm
    work-time: "08:00-12:00;14:00-18:00"

    # 数据刷新间隔（秒），-1表示不刷新，默认15分钟
    flush-interval: 900

    # 是否在Spring Boot启动时自动初始化
    auto-init: true
```

#### 3. Properties 配置 (`application.properties`)

```properties
# 是否启用假期计算器
youfool.holiday.enabled=true

# 数据模式：true=在线模式，false=离线模式
youfool.holiday.online=false

# API服务器地址（在线模式）
youfool.holiday.host=http://www.chinaweal.com.cn:8090/holiday-api

# 本地配置目录（离线模式）
youfool.holiday.config-path=classpath:holiday

# 工作时间配置
youfool.holiday.work-time=08:00-12:00;14:00-18:00

# 数据刷新间隔（秒）
youfool.holiday.flush-interval=900

# 是否自动初始化
youfool.holiday.auto-init=true
```

#### 4. 直接使用（无需手动初始化）

配置完成后，直接使用：

```java
@RestController
public class HolidayController {

    @GetMapping("/workdate")
    public LocalDate getWorkDate() {
        // 计算5个工作日后的日期
        return HolidayCalculator.calcWorkDate(LocalDate.now(), 5);
    }

    @GetMapping("/isWorkDay")
    public boolean isWorkDay(@RequestParam LocalDate date) {
        // 判断指定日期是否为工作日
        return HolidayCalculator.isWorkDay(date);
    }

    @GetMapping("/isWorkTime")
    public boolean isWorkTime() {
        // 判断当前时间是否为工作时间
        return HolidayCalculator.isWorkTime(LocalDateTime.now());
    }
}
```

### 📋 配置参数说明

| 参数名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `youfool.holiday.enabled` | boolean | `true` | 是否启用假期计算器 |
| `youfool.holiday.online` | boolean | `false` | 数据模式：true=在线，false=离线 |
| `youfool.holiday.host` | String | `http://www.chinaweal.com.cn:8090/holiday-api` | 在线模式API地址 |
| `youfool.holiday.config-path` | String | `classpath:holiday` | 离线模式配置目录 |
| `youfool.holiday.work-time` | String | `"09:00-18:00"` | 工作时间配置 |
| `youfool.holiday.flush-interval` | long | `900` | 数据刷新间隔（秒） |
| `youfool.holiday.auto-init` | boolean | `true` | 是否自动初始化 |

### 🕐 工作时间配置详解

工作时间支持多个时间段配置：

```yaml
# 标准工作时间：上午9点到下午6点
work-time: "09:00-18:00"

# 分段工作时间：上午和下午分开
work-time: "08:00-12:00;14:00-17:30"

# 多个时间段
work-time: "06:00-09:00;10:00-12:00;14:00-18:00;20:00-22:00"

# 24小时工作时间
work-time: "00:00-23:59"
```

### 🌐 数据模式选择

#### 在线模式
```yaml
youfool:
  holiday:
    online: true
    host: http://your-api-server.com/holiday-api
    flush-interval: 900  # 15分钟刷新一次
```
- 从配置的API接口获取假期数据
- 支持定时刷新数据
- 适合需要实时数据的场景

#### 离线模式（推荐）
```yaml
youfool:
  holiday:
    online: false
    config-path: classpath:holiday
```
- 从本地JSON文件读取假期数据
- 性能更好，无网络依赖
- 支持classpath和文件系统路径

#### 离线模式文件结构
```
src/main/resources/
└── holiday/
    ├── 2024.json
    ├── 2025.json
    └── 2026.json
```

### 🔧 传统Java项目配置

对于非Spring Boot项目，可以使用传统配置方式：

#### Online Mode
```java
HolidayCalculatorConfig config = new HolidayCalculatorConfig();
config.setOnline(true);
config.setHost("http://www.chinaweal.com.cn:8090/holiday-api");
config.setWorkTime("08:00-12:00;14:00-17:00");
HolidayCalculator.init(config);
```

#### Offline Mode
```java
HolidayCalculatorConfig config = new HolidayCalculatorConfig();
config.setOnline(false);
config.setConfigPath("classpath:holiday");
config.setWorkTime("08:00-12:00;14:00-18:00");
HolidayCalculator.init(config);
```

## API Usage

```java
// Calculate workday 4 days from now
LocalDate workDay = HolidayCalculator.calcWorkDate(LocalDate.now(), 4);

// Check if today is a workday
boolean isWorkDay = HolidayCalculator.isWorkDay(LocalDate.now());

// Check if current time is within working hours
boolean isWorkTime = HolidayCalculator.isWorkTime(LocalDateTime.now());
```

## Data Sources

- **Online API**: `{host}/api/holiday/list?year={year}`
- **Offline Files**: JSON files in configured directory (e.g., `classpath:holiday/2025.json`)
- **Data Format**: Array of Holiday objects with date, festival name, and type fields

## Testing

Tests are currently skipped by default (`<skipTests>true</skipTests>` in pom.xml). To run tests:

```bash
mvn test -DskipTests=false
```

## Deployment

The project includes Maven source plugin configuration and nexus repository deployment setup for snapshot versions.