youfool-holiday-sdk/README.md

# YouFool Holiday SDK

[![Maven Central](https://img.shields.io/badge/Maven%20Central-1.0.0-blue.svg)](https://search.maven.org/artifact/com.chinaweal.youfool/youfool-holiday-sdk)
[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-2.x%2B%20%7C%203.x-green.svg)](https://spring.io/projects/spring-boot)
[![JDK](https://img.shields.io/badge/JDK-1.8%2B-brightgreen.svg)](https://www.oracle.com/java/technologies/javase-downloads.html)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

一个强大的 Java 假期和工作日计算 SDK，支持 Spring Boot 自动配置，提供在线和离线两种数据模式。

## 🌟 特性

- ✅ **工作日计算** - 自动跳过节假日和周末
- ✅ **工作日判断** - 判断指定日期是否为工作日
- ✅ **工作时间判断** - 判断指定时间是否在工作时间内
- ✅ **双重数据模式** - 支持在线API和离线文件两种数据源
- ✅ **Spring Boot 集成** - 自动配置，开箱即用
- ✅ **多时间段支持** - 支持复杂的工作时间配置
- ✅ **高性能缓存** - 内置缓存机制，提升性能

## 🚀 快速开始

### 1. 添加依赖

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

### 2. 配置文件

在 `application.yml` 中添加配置：

```yaml
youfool:
  holiday:
    enabled: true
    online: false
    work-time: "08:00-12:00;14:00-18:00"
    config-path: classpath:holiday
    auto-init: true
```

### 3. 直接使用

配置完成后，无需任何初始化代码，直接使用：

```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());
    }
}
```

就这么简单！SDK 会自动初始化并开始工作。

## 📋 配置参数

| 参数名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `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: false
    config-path: classpath:holiday
```

**优势：**
- 性能更好，无网络依赖
- 启动速度更快
- 数据稳定可控

**文件结构：**
```
src/main/resources/
└── holiday/
    ├── 2024.json
    ├── 2025.json
    └── 2026.json
```

### 在线模式

```yaml
youfool:
  holiday:
    online: true
    host: http://your-api-server.com/holiday-api
    flush-interval: 900  # 15分钟刷新一次
```

**优势：**
- 数据实时更新
- 集中管理
- 适合分布式系统

## 🎯 API 使用方法

### 核心方法

```java
// 计算工作日
LocalDate workDay = HolidayCalculator.calcWorkDate(startDate, plusDays);

// 判断工作日
boolean isWorkDay = HolidayCalculator.isWorkDay(date);

// 判断工作时间
boolean isWorkTime = HolidayCalculator.isWorkTime(dateTime);
```

### 使用示例

```java
@Service
public class BusinessService {

    public LocalDate getDeliveryDate(LocalDate orderDate, int processingDays) {
        // 计算处理完成后的工作日（排除节假日和周末）
        return HolidayCalculator.calcWorkDate(orderDate, processingDays);
    }

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

    public boolean isValidBusinessDay(LocalDate date) {
        // 判断是否为有效工作日
        return HolidayCalculator.isWorkDay(date);
    }
}
```

## 🔄 传统 Java 项目配置

如果你不使用 Spring Boot，可以这样配置：

```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);

// 在线模式
HolidayCalculatorConfig config = new HolidayCalculatorConfig();
config.setOnline(true);
config.setHost("http://api.example.com/holiday");
config.setWorkTime("08:00-12:00;14:00-18:00");
HolidayCalculator.init(config);
```

## 🏗️ 项目结构

```
youfool-holiday-sdk/
├── src/main/java/com/chinaweal/youfool/holiday/sdk/
│   ├── HolidayCalculator.java                 # 主API类
│   ├── config/
│   │   ├── HolidayCalculatorConfig.java      # 传统配置类
│   │   ├── HolidayCalculatorProperties.java  # Spring Boot配置类
│   │   ├── HolidayCalculatorAutoConfiguration.java    # Spring Boot 2.x自动配置
│   │   └── HolidayCalculatorAutoConfigurationV3.java  # Spring Boot 3.x自动配置
│   ├── data/
│   │   ├── entity/Holiday.java               # 假期实体类
│   │   └── manager/                          # 数据管理器
│   └── ...                                   # 其他工具类
├── src/main/resources/
│   ├── META-INF/
│   │   ├── spring.factories                  # Spring Boot 2.x自动配置注册
│   │   └── spring/                           # Spring Boot 3.x自动配置注册
│   └── META-INF/additional-spring-configuration-metadata.json  # 配置元数据
└── example/                                  # 示例代码
```

## 🔧 构建

```bash
# 编译项目
mvn clean compile

# 打包项目
mvn clean package

# 安装到本地仓库
mvn clean install
```

## 📄 文档

- [详细配置说明](CLAUDE.md)
- [Spring Boot 集成指南](README-SPRING-BOOT.md)
- [Spring Boot 3 部署指南](SPRING-BOOT-3-GUIDE.md)
- [部署指南](DEPLOYMENT-GUIDE.md)
- [Bean 冲突修复说明](BEAN-CONFLICT-FIX.md)

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 许可证

MIT License

## 🔗 相关链接

- [Spring Boot 官方文档](https://spring.io/projects/spring-boot)
- [Maven 中央仓库](https://search.maven.org/)