# 八字择吉测算API使用示例

## 接口概述

八字择吉测算业务提供基于传统八字命理学的择吉服务，帮助用户选择最适宜的吉日良辰进行重要活动。

## 接口地址

- **测算接口**: `POST /yifan_bazi_zeji/calculate`
- **结果查询**: `GET /yifan_bazi_zeji/result/{zeji_id}`
- **列表查询**: `GET /yifan_bazi_zeji/list`
- **详情查询**: `GET /yifan_bazi_zeji/{zeji_id}`

## 1. 八字择吉测算请求

### 请求示例

```bash
curl -X POST "http://localhost:8000/api/v1/yifan_bazi_zeji/calculate" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "张三",
    "gender": "male",
    "birth_date": "1990年1月1日 子时",
    "birth_date_api": "1990-01-01T00:30:00",
    "birth_place": "北京市",
    "zeji_type": "wedding",
    "zeji_purpose": "选择结婚吉日，希望婚姻美满幸福",
    "date_range_start": "2024-03-01",
    "date_range_end": "2024-06-30"
  }'
```

### 请求参数说明

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | 是 | 姓名 |
| gender | string | 是 | 性别(male/female) |
| birth_date | string | 是 | 生辰八字显示格式 |
| birth_date_api | datetime | 是 | 生辰八字API格式 |
| birth_place | string | 是 | 出生地 |
| zeji_type | string | 是 | 择吉类型 |
| zeji_purpose | string | 是 | 择吉目的描述 |
| date_range_start | date | 是 | 期望日期范围开始 |
| date_range_end | date | 是 | 期望日期范围结束 |

### 择吉类型说明

| 类型值 | 说明 | 适用场景 |
|--------|------|----------|
| wedding | 婚嫁择吉 | 结婚、订婚、求婚 |
| business | 开业择吉 | 开店、公司成立、项目启动 |
| move | 搬家择吉 | 搬迁、入宅、装修 |
| travel | 出行择吉 | 旅游、出差、远行 |
| investment | 投资择吉 | 投资、理财、购买 |
| surgery | 手术择吉 | 医疗手术、体检 |
| contract | 签约择吉 | 合同签署、协议达成 |
| other | 其他择吉 | 其他重要事项 |

### 响应示例

```json
{
  "code": 200,
  "msg": "八字择吉任务已创建，正在测算中",
  "data": {
    "zeji_id": 12345,
    "status": 1
  }
}
```

## 2. 获取择吉结果

### 请求示例

```bash
curl -X GET "http://localhost:8000/api/v1/yifan_bazi_zeji/result/12345" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### 响应示例

```json
{
  "code": 200,
  "msg": "获取八字择吉结果成功",
  "data": {
    "zeji_id": 12345,
    "name": "张三",
    "zeji_type": "wedding",
    "zeji_type_label": "婚嫁择吉",
    "lucky_score": 88,
    "lucky_level": "中吉",
    "recommended_dates": [
      {
        "date": "2024-03-15",
        "lunar_date": "二月初六",
        "weekday": "星期五",
        "score": 92,
        "level": "大吉",
        "best_times": ["09:00-11:00", "13:00-15:00"],
        "reason": "此日天干地支与您八字相合，五行流通顺畅，最宜婚嫁庆典",
        "yi": ["嫁娶", "祈福", "开市"],
        "ji": ["动土", "安葬"]
      },
      {
        "date": "2024-04-08",
        "lunar_date": "二月三十",
        "weekday": "星期一",
        "score": 85,
        "level": "中吉",
        "best_times": ["10:00-12:00", "14:00-16:00"],
        "reason": "月令相助，适宜举办喜庆之事",
        "yi": ["嫁娶", "出行", "祭祀"],
        "ji": ["破土", "开仓"]
      }
    ],
    "wuxing_analysis": {
      "personal_wuxing": "金旺木弱",
      "suitable_elements": ["水", "木"],
      "avoid_elements": ["火", "土"],
      "balance_suggestion": "宜多接触水木属性事物，避免火土过旺"
    },
    "bazi_analysis": "您的八字显示金旺木弱，日主偏强，需要水来调和五行平衡。命中带有贵人星，适合在春季进行重要决策...",
    "tiangang_analysis": "天干地支分析显示您的命格中庚金当令，适合在卯月、辰月进行婚嫁大事，能得到五行相助...",
    "zeji_suggestions": "根据您的八字特点，建议选择水旺木盛的日子举办婚礼，最好选择上午时辰，有利于新婚和谐...",
    "avoid_suggestions": "需要避开火土过旺的时间，特别是午时和未时，以免冲克您的命格...",
    "best_time_periods": [
      {
        "time": "09:00-11:00",
        "name": "巳时",
        "description": "此时辰阳气上升，最利开创事业和婚姻大事"
      },
      {
        "time": "13:00-15:00", 
        "name": "未时",
        "description": "午后时光，阴阳调和，适合庆典仪式"
      }
    ],
    "fengshui_tips": "建议婚礼现场布置以绿色和蓝色为主色调，在东南方位设置主席台，有利于新人感情和谐...",
    "lucky_directions": ["东南", "正东"],
    "lucky_colors": ["绿色", "蓝色", "黑色"],
    "lucky_numbers": [3, 8, 13, 18],
    "unlocked": null,
    "is_unlocked": false,
    "unlock_price": 19.90
  }
}
```

## 3. 状态码说明

| 状态值 | 状态名称 | 说明 |
|--------|----------|------|
| 1 | 已创建 | 测算任务已创建，等待处理 |
| 2 | 测算中 | 正在进行AI测算 |
| 5 | 测算成功 | 测算完成，可获取结果 |
| 3 | 测算超时 | AI测算超时 |
| 0 | 任务失败 | 测算过程中出现错误 |

## 4. 错误处理

### 常见错误码

- `400`: 请求参数错误
- `401`: 未授权访问
- `404`: 记录不存在
- `503`: AI服务不可用

### 错误响应示例

```json
{
  "code": 404,
  "msg": "八字择吉测算记录不存在",
  "data": null
}
```

## 5. 使用注意事项

1. **日期范围**: 建议期望日期范围不超过6个月，以确保推荐结果的准确性
2. **生辰格式**: birth_date_api必须是标准的ISO 8601格式
3. **异步处理**: 测算是异步进行的，需要轮询结果接口获取最终结果
4. **权限控制**: 用户只能查看自己创建的测算记录
5. **AI服务**: 依赖AI服务，如服务不可用会返回模拟数据

## 6. 集成建议

1. **前端轮询**: 建议每5-10秒轮询一次结果接口，直到状态为5(成功)或失败
2. **错误重试**: 对于网络错误，建议实现重试机制
3. **缓存策略**: 可以缓存已完成的测算结果，避免重复请求
4. **用户体验**: 在测算过程中显示进度提示，提升用户体验