healthapp/server/docs/API.md

健康AI问询助手 - 后端API文档

后端服务地址: http://localhost:8080

所有需要认证的接口，请在Header中添加: Authorization: Bearer <token>

---

一、认证接口

1.1 用户注册

• POST /api/auth/register

请求体：

{
  "phone": "13800138000",
  "password": "123456",
  "nickname": "用户昵称"  // 可选
}

响应：

{
  "code": 0,
  "message": "success",
  "data": {
    "token": "eyJhbGc...",
    "user_id": 1,
    "nickname": "用户昵称",
    "avatar": "",
    "survey_completed": false
  }
}

1.2 用户登录

• POST /api/auth/login

请求体：

{
  "phone": "13800138000",
  "password": "123456"
}

响应： 同注册接口

1.3 刷新Token

• POST /api/auth/refresh
• 需要认证

响应：

{
  "code": 0,
  "message": "success",
  "data": {
    "token": "新的token"
  }
}

---

二、用户接口

2.1 获取用户信息

• GET /api/user/profile
• 需要认证

响应：

{
  "code": 0,
  "message": "success",
  "data": {
    "user_id": 1,
    "phone": "13800138000",
    "email": "",
    "nickname": "用户昵称",
    "avatar": "",
    "survey_completed": false
  }
}

2.2 更新用户资料

• PUT /api/user/profile
• 需要认证

请求体：

{
  "nickname": "新昵称",
  "avatar": "头像URL"
}

---

三、健康调查接口

3.1 获取调查状态

• GET /api/survey/status
• 需要认证

响应：

{
  "code": 0,
  "message": "success",
  "data": {
    "basic_info": true,
    "lifestyle": false,
    "medical_history": false,
    "family_history": false,
    "allergy": false,
    "all_completed": false
  }
}

3.2 提交基础信息

• POST /api/survey/basic-info
• 需要认证

请求体：

{
  "name": "张三",
  "birth_date": "1990-05-15",
  "gender": "male",           // male/female
  "height": 175,              // cm
  "weight": 70,               // kg
  "blood_type": "A",          // A/B/AB/O
  "occupation": "工程师",
  "marital_status": "married", // single/married/divorced
  "region": "北京"
}

3.3 提交生活习惯

• POST /api/survey/lifestyle
• 需要认证

请求体：

{
  "sleep_time": "23:00",
  "wake_time": "07:00",
  "sleep_quality": "normal",      // good/normal/poor
  "meal_regularity": "regular",   // regular/irregular
  "diet_preference": "清淡",
  "daily_water_ml": 2000,
  "exercise_frequency": "sometimes", // never/sometimes/often/daily
  "exercise_type": "跑步",
  "exercise_duration_min": 30,
  "is_smoker": false,
  "alcohol_frequency": "never"    // never/sometimes/often
}

3.4 提交病史

• POST /api/survey/medical-history
• 需要认证

请求体：

{
  "disease_name": "高血压",
  "disease_type": "chronic",     // chronic/surgery/other
  "diagnosed_date": "2020-01",
  "status": "controlled",        // cured/treating/controlled
  "notes": "备注信息"
}

3.5 批量提交病史（覆盖式）

• POST /api/survey/medical-history/batch
• 需要认证

请求体：

{
  "histories": [
    {
      "disease_name": "高血压",
      "disease_type": "chronic",
      "diagnosed_date": "2020-01",
      "status": "controlled",
      "notes": ""
    }
  ]
}

3.6 提交家族病史

• POST /api/survey/family-history
• 需要认证

请求体：

{
  "relation": "father",          // father/mother/grandparent
  "disease_name": "糖尿病",
  "notes": ""
}

3.7 提交过敏信息

• POST /api/survey/allergy
• 需要认证

请求体：

{
  "allergy_type": "drug",        // drug/food/other
  "allergen": "青霉素",
  "severity": "moderate",        // mild/moderate/severe
  "reaction_desc": "皮疹"
}

3.8 完成调查

• POST /api/survey/complete
• 需要认证

---

四、体质辨识接口

4.1 获取问卷题目

• GET /api/constitution/questions
• 需要认证

响应：

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": 1,
      "constitution_type": "pinghe",
      "question_text": "您精力充沛吗？",
      "options": "[\"没有\",\"很少\",\"有时\",\"经常\",\"总是\"]",
      "order_num": 1
    }
  ]
}

4.2 获取分组的问卷题目

• GET /api/constitution/questions/grouped
• 需要认证

4.3 提交测评

• POST /api/constitution/submit
• 需要认证

请求体：

{
  "answers": [
    {"question_id": 1, "score": 3},
    {"question_id": 2, "score": 2}
    // ... 所有题目的答案，score: 1-5 对应选项
  ]
}

响应：

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1,
    "primary_constitution": {
      "type": "qixu",
      "name": "气虚质",
      "score": 65.5,
      "description": "元气不足，容易疲劳..."
    },
    "secondary_constitutions": [],
    "all_scores": [
      {"type": "qixu", "name": "气虚质", "score": 65.5, "description": "..."},
      {"type": "yangxu", "name": "阳虚质", "score": 45.2, "description": "..."}
    ],
    "recommendations": {
      "qixu": {
        "diet": "宜食益气健脾食物...",
        "lifestyle": "避免劳累...",
        "exercise": "宜柔和运动...",
        "emotion": "避免过度思虑"
      }
    },
    "assessed_at": "2026-02-01T16:30:00Z"
  }
}

4.4 获取最新测评结果

• GET /api/constitution/result
• 需要认证

4.5 获取测评历史

• GET /api/constitution/history?limit=10
• 需要认证

4.6 获取调养建议

• GET /api/constitution/recommendations
• 需要认证

---

五、AI对话接口

5.1 获取对话列表

• GET /api/conversations
• 需要认证

响应：

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": 1,
      "title": "新对话 02-01 16:30",
      "created_at": "2026-02-01T16:30:00Z",
      "updated_at": "2026-02-01T16:35:00Z"
    }
  ]
}

5.2 创建新对话

• POST /api/conversations
• 需要认证

请求体：

{
  "title": "对话标题"  // 可选
}

5.3 获取对话详情

• GET /api/conversations/:id
• 需要认证

响应：

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1,
    "title": "最近总是感觉疲劳...",
    "messages": [
      {
        "id": 1,
        "role": "user",
        "content": "最近总是感觉疲劳怎么办？",
        "created_at": "2026-02-01T16:30:00Z"
      },
      {
        "id": 2,
        "role": "assistant",
        "content": "【情况分析】...",
        "created_at": "2026-02-01T16:30:05Z"
      }
    ],
    "created_at": "2026-02-01T16:30:00Z",
    "updated_at": "2026-02-01T16:30:05Z"
  }
}

5.4 删除对话

• DELETE /api/conversations/:id
• 需要认证

5.5 发送消息

• POST /api/conversations/:id/messages
• 需要认证

请求体：

{
  "content": "我最近总是感觉疲劳怎么办？"
}

响应：

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 2,
    "role": "assistant",
    "content": "【情况分析】根据您的描述...\n【建议】\n1. 保证充足睡眠...",
    "created_at": "2026-02-01T16:30:05Z"
  }
}

---

六、健康档案接口

6.1 获取完整健康档案

• GET /api/user/health-profile
• 需要认证

6.2 获取基础档案

• GET /api/user/basic-profile
• 需要认证

6.3 获取生活习惯

• GET /api/user/lifestyle
• 需要认证

6.4 获取病史列表

• GET /api/user/medical-history
• 需要认证

6.5 删除病史记录

• DELETE /api/user/medical-history/:id
• 需要认证

6.6 获取家族病史

• GET /api/user/family-history
• 需要认证

6.7 获取过敏记录

• GET /api/user/allergy-records
• 需要认证

---

七、产品接口

7.1 获取产品列表

• GET /api/products?page=1&page_size=20

7.2 获取产品详情

• GET /api/products/:id

7.3 按分类获取产品

• GET /api/products/category?category=补气类

7.4 搜索产品

• GET /api/products/search?keyword=疲劳

7.5 获取推荐产品（基于用户体质）

• GET /api/products/recommend
• 需要认证

7.6 获取购买历史

• GET /api/user/purchase-history
• 需要认证

---

八、商城同步接口

8.1 同步购买记录

• POST /api/sync/purchase

请求体：

{
  "user_id": 1,
  "order_no": "ORDER123456",
  "products": [
    {"id": 1, "name": "黄芪精"},
    {"id": 2, "name": "人参蜂王浆"}
  ],
  "created_at": "2026-02-01T16:00:00Z"
}

---

九、错误码说明

Code	说明
0	成功
400	参数错误
401	未授权/Token无效
403	禁止访问
404	资源不存在
500	服务器错误

---

十、体质类型对照

类型代码	中文名称
pinghe	平和质
qixu	气虚质
yangxu	阳虚质
yinxu	阴虚质
tanshi	痰湿质
shire	湿热质
xueyu	血瘀质
qiyu	气郁质
tebing	特禀质

---

十一、配置说明

后端配置文件 config.yaml：

server:
  port: 8080
  mode: debug

database:
  driver: sqlite
  sqlite:
    path: ./data/health.db

jwt:
  secret: your-secret-key
  expire_hours: 24

ai:
  provider: aliyun  # 或 openai
  max_history_messages: 10
  aliyun:
    api_key: "您的阿里云DashScope API Key"
    model: "qwen-turbo"

---

联系方式

如有接口问题，请创建 Issue 或联系后端开发团队。