# 财运解析API使用示例

## 接口概述

财运解析业务基于现有的命名方案，通过传统命理学和现代财富管理理论，为用户提供全面的财运分析和投资建议。

## 接口地址

- **财运解析**: `POST /yifan_caiyun_jiexi/analyze`
- **结果查询**: `GET /yifan_caiyun_jiexi/result/{jiexi_id}`
- **状态查询**: `GET /yifan_caiyun_jiexi/status/{jiexi_id}`
- **列表查询**: `GET /yifan_caiyun_jiexi/list`
- **详情查询**: `GET /yifan_caiyun_jiexi/{jiexi_id}`

## 1. 财运解析请求

### 请求示例

```bash
curl -X POST "http://localhost:8000/api/v1/yifan_caiyun_jiexi/analyze" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "report_id": 12345
  }'
```

### 请求参数说明

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| report_id | int | 是 | 方案ID(yifan_naming_reports表的ID) |

### 响应示例

```json
{
  "code": 200,
  "msg": "财运解析任务已创建，正在分析中",
  "data": {
    "jiexi_id": 67890,
    "status": 1,
    "message": "财运解析任务已创建"
  }
}
```

## 2. 获取解析状态

### 请求示例

```bash
curl -X GET "http://localhost:8000/api/v1/yifan_caiyun_jiexi/status/67890" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### 响应示例

```json
{
  "code": 200,
  "msg": "获取财运解析状态成功",
  "data": {
    "jiexi_id": 67890,
    "status": 2,
    "message": "正在解析中",
    "progress": 50
  }
}
```

## 3. 获取解析结果

### 请求示例

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

### 响应示例

```json
{
  "code": 200,
  "msg": "获取财运解析结果成功",
  "data": {
    "jiexi_id": 67890,
    "report_id": 12345,
    "name": "张三",
    "wealth_score": 85,
    "wealth_level": "中富",
    "wealth_trend": "上升",
    "wealth_dimensions": {
      "zhengcai": {
        "score": 88,
        "desc": "正财运强劲，工作收入稳定增长"
      },
      "piancai": {
        "score": 75,
        "desc": "偏财运中等，投资需谨慎选择"
      },
      "touzi": {
        "score": 82,
        "desc": "投资运较好，适合稳健型投资"
      },
      "shiye": {
        "score": 90,
        "desc": "事业财运极佳，创业成功率高"
      },
      "yiwai": {
        "score": 65,
        "desc": "意外财运一般，不宜过度依赖"
      }
    },
    "wealth_periods": {
      "qingnian": {
        "score": 78,
        "desc": "青年期财运渐起，需积累经验"
      },
      "zhongnian": {
        "score": 92,
        "desc": "中年期财运鼎盛，把握机遇"
      },
      "laonian": {
        "score": 85,
        "desc": "老年期财运稳固，重在保值"
      }
    },
    "wealth_months": {
      "1": 7, "2": 8, "3": 9, "4": 6, "5": 8, "6": 9,
      "7": 7, "8": 6, "9": 8, "10": 9, "11": 8, "12": 7
    },
    "wealth_advice": "您的财运整体向好，建议在中年期把握事业发展机遇，通过稳健投资实现财富增值。",
    "investment_advice": "适合稳健型投资，可考虑基金定投和房产投资，避免高风险投机。",
    "career_advice": "事业财运极佳，建议在35-45岁期间考虑创业或职业转型。",
    "risk_warning": "需注意偏财运波动，避免高风险投机性投资，保持理性投资心态。",
    "fengshui_wealth": {
      "directions": ["东南", "正南"],
      "colors": ["金色", "红色", "绿色"],
      "numbers": [8, 6, 9],
      "items": ["貔貅", "金蟾", "发财树"]
    },
    "lucky_items": [
      {
        "name": "黄水晶",
        "effect": "增强正财运",
        "placement": "办公桌左侧"
      },
      {
        "name": "招财猫",
        "effect": "招揽客源财源",
        "placement": "店铺收银台"
      }
    ],
    "wealth_taboos": [
      "避免在财运低谷月进行大额投资",
      "不宜在卧室摆放镜子对床",
      "避免钱包颜色过于暗沉"
    ],
    "unlocked": null,
    "is_unlocked": false,
    "unlock_price": 19.90
  }
}
```

## 4. 财运维度说明

### 财运五维分析
| 维度 | 权重 | 说明 |
|------|------|------|
| 正财运 | 40% | 工资收入、稳定收益能力 |
| 偏财运 | 25% | 投资收益、意外之财能力 |
| 投资运 | 20% | 理财投资的成功概率 |
| 事业财 | 10% | 通过事业创造财富的能力 |
| 意外财 | 5% | 中奖、继承等意外财富 |

### 财运时期分析
| 时期 | 年龄段 | 特点 |
|------|--------|------|
| 青年期 | 20-35岁 | 财运启动期，重在积累 |
| 中年期 | 36-55岁 | 财运黄金期，把握机遇 |
| 老年期 | 56岁以上 | 财运守成期，保值增值 |

### 财运等级说明
| 等级 | 分数范围 | 说明 |
|------|----------|------|
| 大富 | 90-100 | 财运极佳，富贵命格 |
| 中富 | 75-89 | 财运良好，中产阶层 |
| 小富 | 60-74 | 财运一般，小康水平 |
| 平财 | 40-59 | 财运平平，温饱无忧 |
| 欠财 | 0-39 | 财运较弱，需要努力 |

## 5. 状态码说明

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

## 6. 错误处理

### 常见错误码

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

### 错误响应示例

```json
{
  "code": 404,
  "msg": "方案记录不存在",
  "data": null
}
```

## 7. 使用注意事项

1. **方案依赖**: 必须先有有效的命名方案记录才能进行财运解析
2. **重复解析**: 同一个方案ID只能生成一次财运解析，重复请求会返回已有结果
3. **异步处理**: 解析是异步进行的，需要轮询状态接口获取进度
4. **权限控制**: 用户只能查看自己创建的解析记录
5. **AI服务**: 依赖AI服务，如服务不可用会返回模拟数据

## 8. 集成建议

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

## 9. 业务流程

```mermaid
sequenceDiagram
    participant User as 用户
    participant API as 财运解析API
    participant AI as AI服务
    participant DB as 数据库

    User->>API: 提交方案ID
    API->>DB: 查询方案详情
    API->>DB: 创建解析记录
    API-->>User: 返回解析ID和状态
    
    API->>AI: 异步调用AI解析
    AI-->>API: 返回解析结果
    API->>DB: 保存解析结果
    
    User->>API: 轮询解析状态
    API->>DB: 查询解析状态
    API-->>User: 返回当前状态
    
    User->>API: 获取解析结果
    API->>DB: 查询解析结果
    API-->>User: 返回完整结果
```