youfool-project
/
youfool-holiday-sdk
16
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
youfool-holiday-sdk/CLAUDE.md

7.9 KiB
Raw Blame History

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

# 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. 添加依赖

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

2. YAML 配置 (application.yml)

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)

# 是否启用假期计算器
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. 直接使用（无需手动初始化）

配置完成后，直接使用：

@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 是否自动初始化

🕐 工作时间配置详解

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

# 标准工作时间：上午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"

🌐 数据模式选择

在线模式

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

离线模式（推荐）

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

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

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

// 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:

mvn test -DskipTests=false

Deployment

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