suanming/docs/API.md

# API 文档

本文档描述了神机阁平台的后端API接口，基于Node.js Express框架实现。

## 基础信息

- **Base URL**: `http://localhost:3001/api` (开发环境)
- **认证方式**: Bearer Token (JWT)
- **数据格式**: JSON
- **字符编码**: UTF-8
- **架构特点**: 分析计算与历史记录存储分离

## 通用响应格式

### 分析接口成功响应
```json
{
  "data": {
    "analysis": {
      // 分析结果数据
    }
  }
}
```

### 历史记录存储成功响应
```json
{
  "data": {
    "record_id": "number",
    "message": "历史记录保存成功"
  }
}
```

### 错误响应
```json
{
  "error": {
    "code": "ERROR_CODE",
    "message": "错误描述信息"
  }
}
```

## 认证

所有API请求都需要在请求头中包含认证信息：

```http
Authorization: Bearer <your-jwt-token>
Content-Type: application/json
```

## API 接口

### 1. 八字命理分析

**接口地址**: `POST /analysis/bazi`

**功能说明**: 纯分析接口，只返回分析结果，不存储历史记录

**请求参数**:
```json
{
  "birth_data": {
    "name": "string",
    "birth_date": "YYYY-MM-DD",
    "birth_time": "HH:MM",
    "gender": "male|female",
    "birth_place": "string"
  }
}
```

**响应示例**:
```json
{
  "data": {
    "analysis": {
      "basic_info": {
        "personal_data": {
          "name": "张三",
          "birth_date": "1990-01-01",
          "birth_time": "12:00",
          "gender": "男性"
        },
        "bazi_chart": {
          "year_pillar": { "stem": "庚", "branch": "午" },
          "month_pillar": { "stem": "戊", "branch": "寅" },
          "day_pillar": { "stem": "甲", "branch": "子" },
          "hour_pillar": { "stem": "丙", "branch": "寅" },
          "day_master": "甲",
          "day_master_element": "木"
        }
      },
      "detailed_analysis": {
        "character_analysis": "性格分析内容",
        "career_analysis": "事业分析内容",
        "wealth_analysis": "财运分析内容",
        "health_analysis": "健康分析内容",
        "relationship_analysis": "感情分析内容"
      },
      "analysis_date": "2024-01-01T12:00:00.000Z"
    }
  }
}
```

### 2. 紫微斗数分析

**接口地址**: `POST /analysis/ziwei`

**功能说明**: 纯分析接口，只返回分析结果，不存储历史记录

**请求参数**:
```json
{
  "birth_data": {
    "name": "string",
    "birth_date": "YYYY-MM-DD",
    "birth_time": "HH:MM",
    "gender": "male|female",
    "birth_place": "string"
  }
}
```

**响应示例**:
```json
{
  "data": {
    "analysis": {
      "basic_info": {
        "personal_data": {
          "name": "张三",
          "birth_date": "1990-01-01",
          "birth_time": "12:00",
          "gender": "男性"
        },
        "ziwei_chart": {
          "ming_gong": "子",
          "ming_gong_stars": ["紫微", "天机"],
          "twelve_palaces": {
            "命宫": {
              "branch": "子",
              "main_stars": ["紫微", "天机"],
              "interpretation": "命宫解读内容"
            }
            // ... 其他宫位
          },
          "four_transformations": {
            "hua_lu": { "star": "廉贞", "meaning": "财禄亨通" },
            "hua_quan": { "star": "破军", "meaning": "权力地位" },
            "hua_ke": { "star": "武曲", "meaning": "贵人相助" },
            "hua_ji": { "star": "太阳", "meaning": "需要谨慎" }
          }
        }
      },
      "detailed_analysis": {
         "character_analysis": "性格分析内容",
         "career_analysis": "事业分析内容",
         "wealth_analysis": "财运分析内容",
         "health_analysis": "健康分析内容",
         "relationship_analysis": "感情分析内容"
       },
       "analysis_date": "2024-01-01T12:00:00.000Z"
     }
   }
 }
```

### 3. 易经占卜分析

**接口地址**: `POST /analysis/yijing`

**功能说明**: 纯分析接口，只返回分析结果，不存储历史记录

**请求参数**:
```json
{
  "question": "string",
  "user_id": "string",
  "divination_method": "time",
  "user_timezone": "string (可选)",
  "local_time": "string (可选)"
}
```

**时区处理说明**:
- `user_timezone`: 用户时区标识符（如 "Asia/Shanghai", "America/New_York"）
- `local_time`: 用户当地时间的ISO字符串格式
- 优先级：local_time > user_timezone > 服务器时间
- 时间起卦法依赖准确的当地时间，建议前端传递用户时区信息

**响应示例**:
```json
{
  "data": {
    "analysis": {
      "basic_info": {
        "divination_data": {
          "question": "事业发展如何？",
          "method": "梅花易数时间起卦法",
          "divination_time": "2024-01-01T12:00:00.000Z"
        },
        "hexagram_info": {
          "main_hexagram": {
            "name": "乾为天",
            "number": 1,
            "description": "元亨利贞"
          },
          "changing_hexagram": {
            "name": "天风姤",
            "number": 44
          }
        }
      },
      "detailed_analysis": {
        "hexagram_analysis": {
          "judgment": "大吉大利",
          "image": "天行健，君子以自强不息",
          "interpretation": "详细解释内容"
        },
        "changing_lines": [
          {
            "position": "初九",
            "line_text": "潜龙勿用",
            "meaning": "时机未到，需要等待"
          }
        ]
      },
      "dynamic_guidance": {
        "overall_fortune": "整体运势良好",
        "specific_advice": "具体建议内容",
        "timing_analysis": "时机分析"
      },
      "divination_wisdom": {
        "key_message": "核心启示",
        "philosophical_insight": "哲学思考"
      },
      "analysis_date": "2024-01-01T12:00:00.000Z"
    }
  }
}
```

### 4. 历史记录存储

**接口地址**: `POST /analysis/save-history`

**功能说明**: 专门用于保存分析结果到历史记录

**请求参数**:
```json
{
  "analysis_type": "bazi|ziwei|yijing",
  "analysis_data": {
    // 完整的分析结果数据
  },
  "input_data": {
    // 原始输入数据（可选）
    "name": "string",
    "birth_date": "YYYY-MM-DD",
    "birth_time": "HH:MM",
    "gender": "male|female",
    "question": "string",
    "divination_method": "string"
  }
}
```

**响应示例**:
```json
{
  "data": {
    "record_id": 123,
    "message": "历史记录保存成功"
  }
}
```

### 5. 五行分析

**接口地址**: `POST /bazi-wuxing-analysis`

**请求参数**:
```json
{
  "user_id": "string",
  "birth_data": {
    "name": "string",
    "birth_date": "YYYY-MM-DD",
    "birth_time": "HH:MM",
    "gender": "male|female"
  }
}
```

**响应示例**:
```json
{
  "data": {
    "record_id": "123e4567-e89b-12d3-a456-426614174000",
    "analysis": {
      "wuxing_distribution": {
        "wood": 2,
        "fire": 1,
        "earth": 2,
        "metal": 2,
        "water": 1
      },
      "balance_analysis": {
        "dominant_element": "wood",
        "lacking_element": "fire",
        "balance_score": 75
      },
      "recommendations": {
        "colors": ["红色", "橙色"],
        "directions": ["南方"],
        "career_fields": ["文化教育", "艺术创作"],
        "lifestyle_advice": "生活建议内容"
      }
    }
  }
}
```

### 5. 八字详细分析

**接口地址**: `POST /bazi-details`

**请求参数**:
```json
{
  "user_id": "string",
  "birth_data": {
    "name": "string",
    "birth_date": "YYYY-MM-DD",
    "birth_time": "HH:MM",
    "gender": "male|female",
    "birth_place": "string"
  }
}
```

**响应示例**:
```json
{
  "data": {
    "record_id": "123e4567-e89b-12d3-a456-426614174000",
    "analysis": {
      "basic_info": {
        "bazi": {
          "year": "甲子",
          "month": "丙寅",
          "day": "戊辰",
          "hour": "庚申"
        },
        "solar_terms": "立春后",
        "lunar_info": {
          "lunar_date": "农历日期",
          "lunar_month": "农历月份"
        }
      },
      "detailed_analysis": {
        "daymaster_analysis": "日主分析",
        "pattern_analysis": "格局分析",
        "useful_god": "用神分析",
        "taboo_god": "忌神分析"
      },
      "life_stages": {
        "childhood": "童年运势",
        "youth": "青年运势",
        "middle_age": "中年运势",
        "old_age": "晚年运势"
      },
      "annual_fortune": [
        {
          "year": 2024,
          "fortune": "年运分析",
          "advice": "建议事项"
        }
      ]
    }
  }
}
```

## 错误代码

| 错误代码 | 描述 | HTTP状态码 |
|---------|------|----------|
| INVALID_JSON | 请求JSON格式错误 | 400 |
| MISSING_PARAMETERS | 缺少必需参数 | 400 |
| INVALID_DATE_FORMAT | 日期格式错误 | 400 |
| INVALID_TIME_FORMAT | 时间格式错误 | 400 |
| UNAUTHORIZED | 未授权访问 | 401 |
| FORBIDDEN | 禁止访问 | 403 |
| ANALYSIS_ERROR | 分析过程错误 | 500 |
| DATABASE_ERROR | 数据库操作错误 | 500 |
| INTERNAL_ERROR | 内部服务器错误 | 500 |

## 使用示例

### JavaScript/TypeScript

```typescript
// API客户端配置
const API_BASE_URL = 'http://localhost:3001/api'
const authToken = 'your-jwt-token'

// 八字分析示例
async function analyzeBazi(birthData: any) {
  // 第一步：获取分析结果
  const analysisResponse = await fetch(`${API_BASE_URL}/analysis/bazi`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${authToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ birth_data: birthData })
  })
  
  if (!analysisResponse.ok) {
    throw new Error('分析失败')
  }
  
  const analysisResult = await analysisResponse.json()
  
  // 第二步：保存历史记录
  try {
    await fetch(`${API_BASE_URL}/analysis/save-history`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${authToken}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        analysis_type: 'bazi',
        analysis_data: analysisResult.data.analysis,
        input_data: birthData
      })
    })
  } catch (error) {
    console.warn('历史记录保存失败:', error)
    // 不影响分析结果的返回
  }
  
  return analysisResult
}

// 使用示例
const result = await analyzeBazi({
  name: '张三',
  birth_date: '1990-01-01',
  birth_time: '12:00',
  gender: 'male',
  birth_place: '北京市'
})
```

### cURL

```bash
# 第一步：八字分析
curl -X POST 'http://localhost:3001/api/analysis/bazi' \
  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "birth_data": {
      "name": "张三",
      "birth_date": "1990-01-01",
      "birth_time": "12:00",
      "gender": "male",
      "birth_place": "北京市"
    }
  }'

# 第二步：保存历史记录
curl -X POST 'http://localhost:3001/api/analysis/save-history' \
  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "analysis_type": "bazi",
    "analysis_data": {
      // 从第一步获取的完整分析结果
    },
    "input_data": {
      "name": "张三",
      "birth_date": "1990-01-01",
      "birth_time": "12:00",
      "gender": "male",
      "birth_place": "北京市"
    }
  }'
```

## 注意事项

1. **架构设计**: 分析计算与历史记录存储完全分离
2. **请求流程**: 先调用分析接口获取结果，再调用存储接口保存历史记录
3. **数据格式**: 所有日期使用ISO 8601格式 (YYYY-MM-DD)
4. **时间格式**: 使用24小时制 (HH:MM)
5. **字符编码**: 所有文本数据使用UTF-8编码
6. **错误处理**: 历史记录保存失败不影响分析结果的获取
7. **请求去重**: 前端实现了API请求去重机制，防止重复调用
8. **时间显示**: 统一使用本地化时间格式显示

## 更新日志

### v2.0.0 (2024-01-19)
- **重大架构重构**: 分离分析计算与历史记录存储
- **新增接口**: `/analysis/save-history` 专门用于保存历史记录
- **接口变更**: 所有分析接口不再返回 `record_id`，只返回分析结果
- **重复记录修复**: 彻底解决了一次分析产生多条历史记录的问题
- **时间显示优化**: 统一使用ISO时间戳和本地化显示
- **前端优化**: 移除React StrictMode，优化组件渲染性能
- **API去重**: 实现了请求去重机制，防止并发重复调用

### v1.0.0 (2024-01-01)
- 初始版本发布
- 支持八字命理、紫微斗数、易经占卜三大分析功能
- 完整的用户认证和数据存储功能

---

如有疑问或需要技术支持，请通过GitHub Issues联系我们。