suanming/docs/API.md

API 文档

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

基础信息

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

通用响应格式

分析接口成功响应

{
  "data": {
    "analysis": {
      // 分析结果数据
    }
  }
}

历史记录存储成功响应

{
  "data": {
    "record_id": "number",
    "message": "历史记录保存成功"
  }
}

错误响应

{
  "error": {
    "code": "ERROR_CODE",
    "message": "错误描述信息"
  }
}

认证

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

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

API 接口

1. 八字命理分析

接口地址: POST /analysis/bazi

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

请求参数:

{
  "birth_data": {
    "name": "string",
    "birth_date": "YYYY-MM-DD",
    "birth_time": "HH:MM",
    "gender": "male|female",
    "birth_place": "string"
  }
}

响应示例:

{
  "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

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

请求参数:

{
  "birth_data": {
    "name": "string",
    "birth_date": "YYYY-MM-DD",
    "birth_time": "HH:MM",
    "gender": "male|female",
    "birth_place": "string"
  }
}

响应示例:

{
  "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

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

请求参数:

{
  "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 > 服务器时间
• 时间起卦法依赖准确的当地时间，建议前端传递用户时区信息

响应示例:

{
  "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

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

请求参数:

{
  "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"
  }
}

响应示例:

{
  "data": {
    "record_id": 123,
    "message": "历史记录保存成功"
  }
}

5. 五行分析

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

请求参数:

{
  "user_id": "string",
  "birth_data": {
    "name": "string",
    "birth_date": "YYYY-MM-DD",
    "birth_time": "HH:MM",
    "gender": "male|female"
  }
}

响应示例:

{
  "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

请求参数:

{
  "user_id": "string",
  "birth_data": {
    "name": "string",
    "birth_date": "YYYY-MM-DD",
    "birth_time": "HH:MM",
    "gender": "male|female",
    "birth_place": "string"
  }
}

响应示例:

{
  "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

// 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

# 第一步：八字分析
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联系我们。