Mirrors/suanming

Fork 0

mirror of https://github.com/patdelphi/suanming.git synced 2026-02-28 05:33:11 +08:00

Files

patdelphi e00a5e6101 更新系统文档，反映v2.0架构重构

2025-08-19 14:17:02 +08:00

12 KiB

Raw Blame History

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

响应示例:

{
  "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": "北京市"
    }
  }'

注意事项

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

更新日志

v2.0.0 (2024-01-19)

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

v1.0.0 (2024-01-01)

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

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

12 KiB Raw Blame History Unescape Escape

API 文档

基础信息

通用响应格式

分析接口成功响应

历史记录存储成功响应

错误响应

认证

API 接口

1. 八字命理分析

2. 紫微斗数分析

3. 易经占卜分析

4. 历史记录存储

5. 五行分析

5. 八字详细分析

错误代码

使用示例

JavaScript/TypeScript

cURL

注意事项

更新日志

v2.0.0 (2024-01-19)

v1.0.0 (2024-01-01)

12 KiB

Raw Blame History