282 lines
7.9 KiB
Markdown
282 lines
7.9 KiB
Markdown
# 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. |