# 日历API集成功能说明

## 功能概述

`get_calendar_by_date` 函数现在具备了完整的智能查询功能：

1. **优先查询数据库**: 首先在本地 `calendar_info` 表中查找指定日期的黄历信息
2. **自动API调用**: 如果数据库中没有找到记录，自动调用外部API获取数据
3. **数据持久化**: 将API获取的数据自动保存到数据库中
4. **统一返回格式**: 无论数据来源如何，都返回标准化的JSON格式

## 工作流程

```
用户请求日期 → 查询数据库 → 找到数据？ → 是 → 返回数据
                    ↓
                  否
                    ↓
              调用外部API → 成功？ → 是 → 保存到数据库 → 返回数据
                    ↓
                  否
                    ↓
              返回错误信息
```

## 新增方法

### CalendarService.fetch_calendar_from_api()

从聚合数据黄历API获取指定日期的黄历信息。

**参数:**
- `yangli_date (date)`: 阳历日期

**返回:**
- `Optional[dict]`: API返回的黄历信息，失败时返回None

### CalendarService.save_calendar_from_api()

将API返回的黄历信息保存到数据库。

**参数:**
- `api_data (dict)`: API返回的黄历信息数据

**返回:**
- `Optional[CalendarInfo]`: 保存后的黄历信息对象，失败时返回None

## 配置文件

新增 `calendar_config.py` 配置文件，集中管理API相关配置：

```python
CALENDAR_API_CONFIG = {
    'url': 'http://v.juhe.cn/laohuangli/d',
    'key': 'your-api-key-here',
    'timeout': 10,
    'retry_times': 3
}
```

## API数据格式转换

外部API返回的数据格式与数据库字段的映射关系：

| API字段 | 数据库字段 | 说明 |
|---------|------------|------|
| `yangli` | `yangli` | 阳历日期 |
| `yinli` | `yinli` | 阴历日期 |
| `wuxing` | `wuxing` | 五行 |
| `chongsha` | `chongsha` | 冲煞 |
| `baiji` | `baiji` | 彭祖百忌 |
| `jishen` | `jishen` | 吉神宜趋 |
| `yi` | `yi` | 宜 |
| `xionshen` | `xiongshen` | 凶神宜忌 (注意字段名差异) |
| `ji` | `ji` | 忌 |

## 错误处理

函数包含完整的错误处理机制：

- **400**: 日期格式错误
- **404**: 数据库和API都没有找到数据
- **500**: 系统内部错误（如API调用失败、数据库保存失败等）

## 使用示例

```python
from app.core.data_parse.calendar import get_calendar_by_date

# 查询指定日期的黄历信息
result = get_calendar_by_date("2025-08-24")

if result['return_code'] == 200:
    calendar_data = result['result']
    print(f"阳历: {calendar_data['yangli']}")
    print(f"阴历: {calendar_data['yinli']}")
    print(f"宜: {calendar_data['yi']}")
    print(f"忌: {calendar_data['ji']}")
else:
    print(f"查询失败: {result['error']}")
```

## 注意事项

1. **API密钥**: 当前硬编码在配置文件中，生产环境建议使用环境变量
2. **网络超时**: API调用设置了10秒超时，可根据网络情况调整
3. **数据一致性**: API数据保存到数据库后，后续查询将直接从数据库返回
4. **错误日志**: 所有API调用和数据库操作的错误都会记录到控制台

## 测试

运行以下测试文件验证功能：

```bash
# 测试基本功能
python test_calendar_function.py

# 测试API集成功能
python test_calendar_api_integration.py
```

## 依赖要求

确保安装了以下Python包：

```bash
pip install requests sqlalchemy
```