# 日历API路由接口说明

## 接口概述

新增的 `get-calendar-info` API接口用于获取指定日期的黄历信息，支持智能查询：优先从数据库查询，未找到时自动调用外部API获取数据并保存到数据库。

## 接口详情

### 基本信息

- **接口名称**: `get-calendar-info`
- **请求方法**: `GET`
- **接口路径**: `/api/data_parse/get-calendar-info`
- **功能描述**: 获取指定日期的黄历信息

### 请求参数

| 参数名 | 类型 | 必填 | 格式 | 说明 |
|--------|------|------|------|------|
| date | string | 是 | YYYY-MM-DD | 查询日期，如：2025-01-19 |

### 请求示例

```bash
# 使用curl
curl -X GET "http://localhost:5000/api/data_parse/get-calendar-info?date=2025-01-19"

# 使用浏览器
GET http://localhost:5000/api/data_parse/get-calendar-info?date=2025-01-19
```

### 响应格式

#### 成功响应 (200)

```json
{
    "reason": "successed",
    "return_code": 200,
    "result": {
        "id": "1657",
        "yangli": "2014-09-11",
        "yinli": "甲午(马)年八月十八",
        "wuxing": "井泉水 建执位",
        "chongsha": "冲兔(己卯)煞东",
        "baiji": "乙不栽植千株不长 酉不宴客醉坐颠狂",
        "jishen": "官日 六仪 益後 月德合 除神 玉堂 鸣犬",
        "yi": "祭祀 出行 扫舍 馀事勿取",
        "xiongshen": "月建 小时 土府 月刑 厌对 招摇 五离",
        "ji": "诸事不宜"
    }
}
```

#### 错误响应

**参数缺失 (400)**
```json
{
    "reason": "failed",
    "return_code": 400,
    "result": null,
    "error": "缺少必填参数: date"
}
```

**日期格式错误 (400)**
```json
{
    "reason": "failed",
    "return_code": 400,
    "result": null,
    "error": "日期格式错误，请使用YYYY-MM-DD格式"
}
```

**数据未找到 (404)**
```json
{
    "reason": "failed",
    "return_code": 404,
    "result": null,
    "error": "未找到日期 2025-01-19 的黄历信息，且API获取失败"
}
```

**服务器错误 (500)**
```json
{
    "reason": "failed",
    "return_code": 500,
    "result": null,
    "error": "查询过程中发生错误: 具体错误信息"
}
```

## 响应字段说明

### 成功响应字段

| 字段名 | 类型 | 说明 |
|--------|------|------|
| reason | string | 操作结果描述，"successed"表示成功 |
| return_code | integer | HTTP状态码，200表示成功 |
| result | object | 黄历信息数据对象 |

### 黄历信息字段 (result)

| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | string | 记录ID |
| yangli | string | 阳历 |
| yinli | string | 阴历 |
| wuxing | string | 五行 |
| chongsha | string | 冲煞 |
| baiji | string | 彭祖百忌 |
| jishen | string | 吉神宜趋 |
| yi | string | 宜 |
| xiongshen | string | 凶神宜忌 |
| ji | string | 忌 |

### 错误响应字段

| 字段名 | 类型 | 说明 |
|--------|------|------|
| reason | string | 操作结果描述，"failed"表示失败 |
| return_code | integer | HTTP状态码 |
| result | null | 失败时为null |
| error | string | 错误描述信息 |

## 业务逻辑

### 查询流程

1. **参数验证**: 检查date参数是否存在且格式正确
2. **数据库查询**: 在`calendar_info`表中查找指定日期的记录
3. **API调用**: 如果数据库中没有找到，自动调用外部黄历API
4. **数据保存**: 将API获取的数据保存到数据库
5. **结果返回**: 返回标准化的JSON响应

### 智能查询特性

- **优先本地**: 首先查询本地数据库，响应速度快
- **自动补充**: 数据库缺失时自动从API获取
- **数据持久化**: API数据自动保存，避免重复调用
- **统一格式**: 无论数据来源如何，都返回相同格式

## 错误处理

### HTTP状态码

| 状态码 | 说明 |
|--------|------|
| 200 | 查询成功 |
| 400 | 请求参数错误 |
| 404 | 数据未找到 |
| 500 | 服务器内部错误 |

### 错误类型

1. **参数错误**: 缺少date参数或格式不正确
2. **数据缺失**: 指定日期在数据库和API中都没有数据
3. **API错误**: 外部API调用失败
4. **系统错误**: 数据库操作异常等

## 使用示例

### Python示例

```python
import requests

# 查询指定日期的黄历信息
url = "http://localhost:5000/api/data_parse/get-calendar-info"
params = {"date": "2025-01-19"}

response = requests.get(url, params=params)

if response.status_code == 200:
    data = response.json()
    if data['return_code'] == 200:
        calendar_info = data['result']
        print(f"阳历: {calendar_info['yangli']}")
        print(f"阴历: {calendar_info['yinli']}")
        print(f"宜: {calendar_info['yi']}")
        print(f"忌: {calendar_info['ji']}")
    else:
        print(f"查询失败: {data['error']}")
else:
    print(f"HTTP请求失败: {response.status_code}")
```

### JavaScript示例

```javascript
// 查询指定日期的黄历信息
async function getCalendarInfo(date) {
    try {
        const response = await fetch(`/api/data_parse/get-calendar-info?date=${date}`);
        const data = await response.json();
        
        if (data.return_code === 200) {
            const calendarInfo = data.result;
            console.log(`阳历: ${calendarInfo.yangli}`);
            console.log(`阴历: ${calendarInfo.yinli}`);
            console.log(`宜: ${calendarInfo.yi}`);
            console.log(`忌: ${calendarInfo.ji}`);
            return calendarInfo;
        } else {
            console.error(`查询失败: ${data.error}`);
            return null;
        }
    } catch (error) {
        console.error('请求失败:', error);
        return null;
    }
}

// 使用示例
getCalendarInfo('2025-01-19');
```

## 测试

### 测试文件

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

```bash
# 测试API路由接口
python test_calendar_api_route.py
```

### 测试用例

1. **有效日期**: 测试正常日期查询
2. **无效格式**: 测试错误日期格式
3. **参数缺失**: 测试缺少date参数
4. **空参数**: 测试空字符串参数

## 注意事项

1. **日期格式**: 必须使用YYYY-MM-DD格式，如2025-01-19
2. **API密钥**: 外部API调用需要有效的API密钥
3. **网络超时**: API调用设置了超时时间，网络不稳定可能影响结果
4. **数据一致性**: API数据保存到数据库后，后续查询将直接从数据库返回
5. **错误日志**: 所有操作都会记录详细日志，便于问题排查

## 依赖要求

确保安装了以下Python包：

```bash
pip install flask requests sqlalchemy
```

## 部署说明

1. 确保Flask应用正在运行
2. 检查数据库连接配置
3. 验证外部API密钥有效性
4. 测试接口可访问性

## 更新日志

- **v1.0.0**: 初始版本，支持基本的黄历信息查询
- **v1.1.0**: 新增API集成功能，支持自动数据补充
- **v1.2.0**: 新增路由接口，支持HTTP GET请求