diff --git a/.gitignore b/.gitignore
index 0aa5210..761b3c6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,4 @@
/.idea
/*.iml
/target
+settings.local.json
\ No newline at end of file
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..a16cb1a
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,282 @@
+# 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
+
+ com.chinaweal.youfool
+ youfool-holiday-sdk
+ 1.0.0
+
+```
+
+#### 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 (`true` 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.
\ No newline at end of file
diff --git a/README.md b/README.md
index 94b654d..e887491 100644
--- a/README.md
+++ b/README.md
@@ -1,66 +1,258 @@
-# youfool-holiday-sdk
+# YouFool Holiday SDK
-youfool-holiday调度sdk
+[](https://search.maven.org/artifact/com.chinaweal.youfool/youfool-holiday-sdk)
+[](https://spring.io/projects/spring-boot)
+[](LICENSE)
-## 使用方法
+一个强大的 Java 假期和工作日计算 SDK，支持 Spring Boot 自动配置，提供在线和离线两种数据模式。
-### 配置初始化
+## 🌟 特性
+
+- ✅ **工作日计算** - 自动跳过节假日和周末
+- ✅ **工作日判断** - 判断指定日期是否为工作日
+- ✅ **工作时间判断** - 判断指定时间是否在工作时间内
+- ✅ **双重数据模式** - 支持在线API和离线文件两种数据源
+- ✅ **Spring Boot 集成** - 自动配置，开箱即用
+- ✅ **多时间段支持** - 支持复杂的工作时间配置
+- ✅ **高性能缓存** - 内置缓存机制，提升性能
+
+## 🚀 快速开始
+
+### 1. 添加依赖
+
+```xml
+
+ com.chinaweal.youfool
+ youfool-holiday-sdk
+ 1.0.0
+
+```
+
+### 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(Boolean.parseBoolean(environment.getProperty("holiday.online")));
-// 离线模式配置文件路径（默认：classpath:holiday）
- config.
-
-setConfigPath(environment.getProperty("holiday.config-path"));
-// 工作时间区间配置，多个用;隔开，示例：08:00-12:00;14:00-17:00
- config.
-
-setWorkTime(environment.getProperty("holiday.work-time"));
-// 数据同步间隔，默认-1（只在初始化时同步）
-String interval = environment.getProperty("holiday.flush-interval");
-if(interval !=null){
- config.
-
-setFlushInterval(Long.parseLong(interval.trim()));
- }
- HolidayCalculator.
-
-init(config);
-```
-
-### 在线假期信息配置路径
-
-> 在线模式：config.setOnline(true);时，需要配置在线数据获取路径
-
-```java
-config.setHost("http://www.chinaweal.com.cn:8090/holiday-api");// 目前公司的数据后端路径
-```
-
-> 离线模式：config.setOnline(false);时，需要配置离线数据获取路径
-
-```java
+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);
```
-> json数据通过公司后端接口 http://www.chinaweal.com.cn:8090/holiday-api/api/holiday/export/{year}.json 获取，并以`.json`
-> 为扩展名，保存到上面配置的路径下，配置了定时采集任务的时间后，只需通过修改或增添`.json`文件即可。无需重启项目
+## 🏗️ 项目结构
-### 初始化后调用
+```
+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/ # 示例代码
+```
-```java
-// 推算工作日
-HolidayCalculator.calcWorkDate(LocalDate.now(), 4);
-// 判断是否是工作日
- HolidayCalculator.
+## 🔧 构建
-isWorkDay(LocalDate.now());
-// 判断限制是否为工作时间
- HolidayCalculator.
+```bash
+# 编译项目
+mvn clean compile
-isWorkTime(LocalDateTime.now());
-```
\ No newline at end of file
+# 打包项目
+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/)
\ No newline at end of file
diff --git a/pom.xml b/pom.xml
index 4c74f3a..76e5b3e 100644
--- a/pom.xml
+++ b/pom.xml
@@ -6,7 +6,7 @@
com.chinaweal.youfool
youfool-holiday-sdk
- 1.0.0-SNAPSHOT
+ 1.0.0
jar
${project.artifactId}
https://www.chinaweal.com.cn
@@ -26,7 +26,7 @@
org.projectlombok
lombok
- 1.18.12
+ 1.18.30
provided
@@ -41,6 +41,24 @@
4.12
test
+
+
+
+ org.springframework.boot
+ spring-boot-autoconfigure
+ 2.7.18
+ provided
+ true
+
+
+
+
+ org.springframework.boot
+ spring-boot-configuration-processor
+ 2.7.18
+ provided
+ true
+
@@ -69,5 +87,10 @@
Nexus Snapshot Repository
http://121.8.152.130:8081/nexus/content/repositories/snapshots/
+
+ nexus
+ Nexus Release Repository
+ http://121.8.152.130:8081/nexus/content/repositories/releases/
+
diff --git a/src/main/java/com/chinaweal/youfool/holiday/sdk/HolidayCalculator.java b/src/main/java/com/chinaweal/youfool/holiday/sdk/HolidayCalculator.java
index 4666124..3731687 100644
--- a/src/main/java/com/chinaweal/youfool/holiday/sdk/HolidayCalculator.java
+++ b/src/main/java/com/chinaweal/youfool/holiday/sdk/HolidayCalculator.java
@@ -1,6 +1,7 @@
package com.chinaweal.youfool.holiday.sdk;
import com.chinaweal.youfool.holiday.sdk.config.HolidayCalculatorConfig;
+import com.chinaweal.youfool.holiday.sdk.config.HolidayCalculatorProperties;
import com.chinaweal.youfool.holiday.sdk.data.entity.Holiday;
import com.chinaweal.youfool.holiday.sdk.data.manager.HolidayDataManager;
import com.chinaweal.youfool.holiday.sdk.data.manager.LocationHolidayDataManager;
@@ -78,6 +79,28 @@ public abstract class HolidayCalculator {
}
}
+ /**
+ * 从 Spring Boot 配置属性初始化
+ *
+ * @param properties Spring Boot 配置属性
+ * @author lroyia
+ * @since 2025/11/12
+ */
+ public static void initFromProperties(HolidayCalculatorProperties properties) {
+ if (!properties.isEnabled()) {
+ return;
+ }
+
+ HolidayCalculatorConfig config = new HolidayCalculatorConfig();
+ config.setOnline(properties.isOnline());
+ config.setHost(properties.getHost());
+ config.setConfigPath(properties.getConfigPath());
+ config.setWorkTime(properties.getWorkTime());
+ config.setFlushInterval(properties.getFlushInterval());
+
+ init(config);
+ }
+
/**
* 计算工作日
*
diff --git a/src/main/java/com/chinaweal/youfool/holiday/sdk/config/HolidayCalculatorAutoConfiguration.java b/src/main/java/com/chinaweal/youfool/holiday/sdk/config/HolidayCalculatorAutoConfiguration.java
new file mode 100644
index 0000000..8901030
--- /dev/null
+++ b/src/main/java/com/chinaweal/youfool/holiday/sdk/config/HolidayCalculatorAutoConfiguration.java
@@ -0,0 +1,61 @@
+package com.chinaweal.youfool.holiday.sdk.config;
+
+import com.chinaweal.youfool.holiday.sdk.HolidayCalculator;
+import org.springframework.boot.autoconfigure.AutoConfiguration;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.boot.context.properties.EnableConfigurationProperties;
+import org.springframework.context.annotation.Bean;
+
+/**
+ * 假期计算器自动配置类
+ * 兼容 Spring Boot 2.7.x 和 3.x
+ *
+ * @author lroyia
+ * @since 2025/11/12
+ */
+@AutoConfiguration
+@ConditionalOnClass(HolidayCalculator.class)
+@ConditionalOnProperty(prefix = "youfool.holiday", name = "enabled", havingValue = "true", matchIfMissing = true)
+@EnableConfigurationProperties(HolidayCalculatorProperties.class)
+public class HolidayCalculatorAutoConfiguration {
+
+ /**
+ * 假期计算器配置属性 Bean
+ * Spring Boot 2.x 中需要手动创建配置属性 Bean
+ *
+ * @param properties 配置属性
+ * @return 配置属性 Bean
+ */
+ @Bean
+ @ConditionalOnMissingBean
+ public HolidayCalculatorProperties holidayCalculatorProperties() {
+ System.out.println("Spring Boot 2 - 注册 HolidayCalculatorProperties Bean");
+ return new HolidayCalculatorProperties();
+ }
+
+ /**
+ * 自动初始化假期计算器
+ *
+ * @param properties 配置属性
+ */
+ @Bean
+ @ConditionalOnProperty(prefix = "youfool.holiday", name = "auto-init", havingValue = "true", matchIfMissing = true)
+ public HolidayCalculatorInitializer holidayCalculatorInitializer(HolidayCalculatorProperties properties) {
+ System.out.println("自动初始化假期计算器，配置: 在线模式=" + properties.isOnline() + ", 工作时间=" + properties.getWorkTime());
+
+ // 初始化假期计算器
+ HolidayCalculator.initFromProperties(properties);
+
+ return new HolidayCalculatorInitializer();
+ }
+
+ /**
+ * 假期计算器初始化器
+ * 用于标记自动初始化已完成
+ */
+ public static class HolidayCalculatorInitializer {
+ // 空实现，仅用于标记
+ }
+}
\ No newline at end of file
diff --git a/src/main/java/com/chinaweal/youfool/holiday/sdk/config/HolidayCalculatorAutoConfigurationV3.java b/src/main/java/com/chinaweal/youfool/holiday/sdk/config/HolidayCalculatorAutoConfigurationV3.java
new file mode 100644
index 0000000..a465fe6
--- /dev/null
+++ b/src/main/java/com/chinaweal/youfool/holiday/sdk/config/HolidayCalculatorAutoConfigurationV3.java
@@ -0,0 +1,47 @@
+package com.chinaweal.youfool.holiday.sdk.config;
+
+import com.chinaweal.youfool.holiday.sdk.HolidayCalculator;
+import org.springframework.boot.autoconfigure.AutoConfiguration;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.boot.context.properties.EnableConfigurationProperties;
+import org.springframework.context.annotation.Bean;
+
+/**
+ * 假期计算器 Spring Boot 3 自动配置类
+ * 针对 Spring Boot 3.x 优化
+ *
+ * @author lroyia
+ * @since 2025/11/12
+ */
+@AutoConfiguration
+@ConditionalOnClass(HolidayCalculator.class)
+@ConditionalOnProperty(prefix = "youfool.holiday", name = "enabled", havingValue = "true", matchIfMissing = true)
+@EnableConfigurationProperties(HolidayCalculatorProperties.class)
+public class HolidayCalculatorAutoConfigurationV3 {
+
+ /**
+ * 自动初始化假期计算器
+ * Spring Boot 3 中，@ConfigurationProperties 会自动注册 Bean，不需要手动创建
+ *
+ * @param properties 配置属性（由 Spring Boot 3 自动注入）
+ */
+ @Bean
+ @ConditionalOnProperty(prefix = "youfool.holiday", name = "auto-init", havingValue = "true", matchIfMissing = true)
+ public HolidayCalculatorInitializerV3 holidayCalculatorInitializer(HolidayCalculatorProperties properties) {
+ System.out.println("Spring Boot 3 - 自动初始化假期计算器，配置: 在线模式=" + properties.isOnline() + ", 工作时间=" + properties.getWorkTime());
+
+ // 初始化假期计算器
+ HolidayCalculator.initFromProperties(properties);
+
+ return new HolidayCalculatorInitializerV3();
+ }
+
+ /**
+ * 假期计算器初始化器
+ * 用于标记自动初始化已完成
+ */
+ public static class HolidayCalculatorInitializerV3 {
+ // 空实现，仅用于标记
+ }
+}
\ No newline at end of file
diff --git a/src/main/java/com/chinaweal/youfool/holiday/sdk/config/HolidayCalculatorProperties.java b/src/main/java/com/chinaweal/youfool/holiday/sdk/config/HolidayCalculatorProperties.java
new file mode 100644
index 0000000..f30f3b8
--- /dev/null
+++ b/src/main/java/com/chinaweal/youfool/holiday/sdk/config/HolidayCalculatorProperties.java
@@ -0,0 +1,53 @@
+package com.chinaweal.youfool.holiday.sdk.config;
+
+import lombok.Data;
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.stereotype.Component;
+
+/**
+ * 假期计算器 Spring Boot 配置属性
+ *
+ * @author lroyia
+ * @since 2025/11/12
+ */
+@Data
+@ConfigurationProperties(prefix = "youfool.holiday")
+public class HolidayCalculatorProperties {
+
+ /**
+ * 是否启用假期计算器，默认启用
+ */
+ private boolean enabled = true;
+
+ /**
+ * 是否在线模式，在线模式会从网络获取数据，离线模式会从本地文件获取数据
+ * 默认为离线模式
+ */
+ private boolean online = false;
+
+ /**
+ * 服务器地址，在线模式下使用
+ */
+ private String host = "http://www.chinaweal.com.cn:8090/holiday-api";
+
+ /**
+ * 本地假期配置目录，默认为classpath:holiday
+ */
+ private String configPath = "classpath:holiday";
+
+ /**
+ * 工作时间区间配置，多个用;隔开，示例：08:00-12:00;14:00-17:00
+ * 默认为 09:00-18:00
+ */
+ private String workTime = "09:00-18:00";
+
+ /**
+ * 刷新间隔（秒），-1为不刷新，默认15分钟
+ */
+ private long flushInterval = 60 * 15;
+
+ /**
+ * 是否在 Spring Boot 启动时自动初始化，默认自动初始化
+ */
+ private boolean autoInit = true;
+}
\ No newline at end of file
diff --git a/src/main/resources/META-INF/additional-spring-configuration-metadata.json b/src/main/resources/META-INF/additional-spring-configuration-metadata.json
new file mode 100644
index 0000000..fa16639
--- /dev/null
+++ b/src/main/resources/META-INF/additional-spring-configuration-metadata.json
@@ -0,0 +1,46 @@
+{
+ "properties": [
+ {
+ "name": "youfool.holiday.enabled",
+ "type": "java.lang.Boolean",
+ "defaultValue": true,
+ "description": "是否启用假期计算器。"
+ },
+ {
+ "name": "youfool.holiday.online",
+ "type": "java.lang.Boolean",
+ "defaultValue": false,
+ "description": "是否在线模式。在线模式会从网络获取数据，离线模式会从本地文件获取数据。"
+ },
+ {
+ "name": "youfool.holiday.host",
+ "type": "java.lang.String",
+ "defaultValue": "http://www.chinaweal.com.cn:8090/holiday-api",
+ "description": "服务器地址，在线模式下使用。"
+ },
+ {
+ "name": "youfool.holiday.config-path",
+ "type": "java.lang.String",
+ "defaultValue": "classpath:holiday",
+ "description": "本地假期配置目录。"
+ },
+ {
+ "name": "youfool.holiday.work-time",
+ "type": "java.lang.String",
+ "defaultValue": "09:00-18:00",
+ "description": "工作时间区间配置，多个用;隔开，示例：08:00-12:00;14:00-17:00。"
+ },
+ {
+ "name": "youfool.holiday.flush-interval",
+ "type": "java.lang.Long",
+ "defaultValue": 900,
+ "description": "刷新间隔（秒），-1为不刷新，默认15分钟。"
+ },
+ {
+ "name": "youfool.holiday.auto-init",
+ "type": "java.lang.Boolean",
+ "defaultValue": true,
+ "description": "是否在 Spring Boot 启动时自动初始化。"
+ }
+ ]
+}
\ No newline at end of file
diff --git a/src/main/resources/META-INF/spring.factories b/src/main/resources/META-INF/spring.factories
new file mode 100644
index 0000000..a1e5a7b
--- /dev/null
+++ b/src/main/resources/META-INF/spring.factories
@@ -0,0 +1,2 @@
+org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
+com.chinaweal.youfool.holiday.sdk.config.HolidayCalculatorAutoConfiguration
\ No newline at end of file
diff --git a/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports b/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
new file mode 100644
index 0000000..a846a87
--- /dev/null
+++ b/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
@@ -0,0 +1 @@
+com.chinaweal.youfool.holiday.sdk.config.HolidayCalculatorAutoConfigurationV3
\ No newline at end of file