healthapp

12 KiB

Raw Blame History

后端 API 接口清单

本文档整理了健康 AI 问询助手项目需要后端配合实现的所有 API 接口

一、接口概览

模块	接口数量	优先级	说明
认证模块	4	P0	用户注册、登录、Token管理
用户模块	6	P0	用户信息、健康档案管理
健康调查模块	6	P1	新用户健康调查问卷
体质辨识模块	5	P0	体质问卷、结果计算
AI对话模块	5	P0	对话管理、消息发送
产品模块	4	P2	保健品推荐、搜索
数据同步模块	1	P2	商城购买记录同步
合计	31	-	-

二、详细接口列表

2.1 认证模块（Auth）

方法	接口路径	说明	请求参数	响应数据
POST	`/api/auth/register`	用户注册	phone, password, code	user, token
POST	`/api/auth/login`	用户登录	phone, password/code	user, token
POST	`/api/auth/refresh`	刷新Token	refresh_token	access_token, refresh_token
POST	`/api/auth/send-code`	发送验证码	phone, type(register/login)	success

注册接口详情

// POST /api/auth/register
// Request
{
  "phone": "13800138000",
  "password": "password123",
  "code": "123456"
}

// Response
{
  "code": 0,
  "data": {
    "user": {
      "id": 1,
      "phone": "13800138000",
      "nickname": "用户138****8000",
      "avatar": "",
      "survey_completed": false
    },
    "token": {
      "access_token": "eyJhbGciOiJIUzI1...",
      "refresh_token": "eyJhbGciOiJIUzI1...",
      "expires_in": 7200
    }
  }
}

2.2 用户模块（User）

方法	接口路径	说明	请求参数	响应数据
GET	`/api/user/profile`	获取用户信息	-	user
PUT	`/api/user/profile`	更新用户信息	nickname, avatar	user
GET	`/api/user/health-profile`	获取健康档案	-	health_profile
PUT	`/api/user/health-profile`	更新健康档案	name, birth_date, gender...	health_profile
GET	`/api/user/lifestyle`	获取生活习惯	-	lifestyle
PUT	`/api/user/lifestyle`	更新生活习惯	sleep_time, diet_preference...	lifestyle

健康档案详情

// GET /api/user/health-profile
// Response
{
  "code": 0,
  "data": {
    "id": 1,
    "user_id": 1,
    "name": "张三",
    "birth_date": "1980-01-15",
    "gender": "male",
    "height": 175.0,
    "weight": 70.5,
    "bmi": 23.02,
    "blood_type": "A",
    "occupation": "工程师",
    "marital_status": "已婚",
    "region": "北京市",
    "medical_histories": [...],
    "allergy_records": [...],
    "family_histories": [...]
  }
}

2.3 健康调查模块（Survey）

方法	接口路径	说明	请求参数	响应数据
GET	`/api/survey/status`	获取调查完成状态	-	completed, steps
POST	`/api/survey/basic-info`	提交基础信息	name, gender, birth_date...	success
POST	`/api/survey/lifestyle`	提交生活习惯	sleep_time, diet_preference...	success
POST	`/api/survey/medical-history`	提交病史信息	diseases[]	success
POST	`/api/survey/family-history`	提交家族病史	histories[]	success
POST	`/api/survey/allergy`	提交过敏信息	allergies[]	success

调查状态详情

// GET /api/survey/status
// Response
{
  "code": 0,
  "data": {
    "completed": false,
    "steps": {
      "basic_info": true,
      "lifestyle": true,
      "medical_history": false,
      "family_history": false,
      "allergy": false,
      "constitution": false
    }
  }
}

2.4 体质辨识模块（Constitution）

方法	接口路径	说明	请求参数	响应数据
GET	`/api/constitution/questions`	获取问卷题目	-	questions[]
POST	`/api/constitution/submit`	提交答案并计算	answers[]	result
GET	`/api/constitution/result`	获取最新结果	-	result
GET	`/api/constitution/history`	获取历史记录	-	results[]
GET	`/api/constitution/recommendations`	获取调养建议	-	recommendations

问卷题目详情

// GET /api/constitution/questions
// Response
{
  "code": 0,
  "data": {
    "total": 60,
    "questions": [
      {
        "id": 1,
        "constitution_type": "qi_deficiency",
        "question": "您容易疲乏吗？",
        "options": [
          {"value": 1, "label": "从不"},
          {"value": 2, "label": "很少"},
          {"value": 3, "label": "有时"},
          {"value": 4, "label": "经常"},
          {"value": 5, "label": "总是"}
        ],
        "order_num": 1
      }
      // ...更多题目
    ]
  }
}

提交答案详情

// POST /api/constitution/submit
// Request
{
  "answers": [
    {"question_id": 1, "score": 3},
    {"question_id": 2, "score": 4},
    // ...共60个答案
  ]
}

// Response
{
  "code": 0,
  "data": {
    "id": 1,
    "assessed_at": "2026-02-01T10:30:00Z",
    "primary_type": "qi_deficiency",
    "scores": {
      "balanced": 45,
      "qi_deficiency": 72,
      "yang_deficiency": 38,
      "yin_deficiency": 42,
      "phlegm_dampness": 35,
      "damp_heat": 30,
      "blood_stasis": 28,
      "qi_stagnation": 40,
      "special": 25
    },
    "secondary_types": ["qi_stagnation"],
    "recommendations": {
      "diet": ["多吃黄芪、人参等补气食物..."],
      "lifestyle": ["保证充足睡眠..."],
      "exercise": ["太极拳、八段锦..."],
      "emotion": ["保持乐观心态..."]
    }
  }
}

2.5 AI对话模块（Conversation）

方法	接口路径	说明	请求参数	响应数据
GET	`/api/conversations`	获取对话列表	page, limit	conversations[]
POST	`/api/conversations`	创建新对话	title?	conversation
GET	`/api/conversations/{id}`	获取对话详情	-	conversation, messages[]
DELETE	`/api/conversations/{id}`	删除对话	-	success
POST	`/api/conversations/{id}/messages`	发送消息	content	message, ai_reply

发送消息详情（流式响应）

// POST /api/conversations/{id}/messages
// Request
{
  "content": "我最近总是感觉疲劳，有什么建议吗？"
}

// Response (SSE 流式)
// Content-Type: text/event-stream

data: {"type": "start"}

data: {"type": "content", "content": "【情况分析】"}
data: {"type": "content", "content": "根据您的气虚体质..."}
data: {"type": "content", "content": "\n【建议】\n1. 饮食方面..."}

data: {"type": "end", "message_id": 123}

AI 上下文数据（后端组装）

后端在调用 AI 时需要自动注入以下上下文：

{
  "user_profile": "性别：男，年龄：45岁，BMI：23.5",
  "constitution_info": "主体质：气虚质（72分），次体质：气郁质（40分）",
  "medication_history": "近期用药：黄芪精（补气），阿莫西林（已停）",
  "purchase_history": "近期购买：人参蜂王浆、氨糖软骨素",
  "product_list": "[气虚质推荐] 黄芪精 ¥68, 人参蜂王浆 ¥128..."
}

2.6 产品模块（Product）

方法	接口路径	说明	请求参数	响应数据
GET	`/api/products`	获取产品列表	category?, page, limit	products[]
GET	`/api/products/{id}`	获取产品详情	-	product
GET	`/api/products/recommend`	体质推荐产品	constitution_type?	products[]
GET	`/api/products/search`	症状搜索产品	keyword	products[]

体质推荐产品详情

// GET /api/products/recommend?constitution_type=qi_deficiency
// Response
{
  "code": 0,
  "data": {
    "constitution_type": "qi_deficiency",
    "constitution_name": "气虚质",
    "products": [
      {
        "id": 1,
        "name": "黄芪精口服液",
        "category": "补气类",
        "efficacy": "补气固表，增强免疫力",
        "suitable": "气虚质人群",
        "price": 68.00,
        "image_url": "https://...",
        "mall_url": "https://mall.example.com/product/1",
        "priority": 1,
        "reason": "黄芪是补气第一要药，特别适合气虚体质"
      }
      // ...更多产品
    ]
  }
}

2.7 数据同步模块（Sync）

方法	接口路径	说明	请求参数	响应数据
POST	`/api/sync/purchase`	商城购买记录同步	user_id, order_no, products[]	success

购买记录同步详情

// POST /api/sync/purchase
// Header: X-Sync-Key: {sync_secret_key}
// Request
{
  "user_id": 1,
  "order_no": "MALL20260201001",
  "products": [
    {"id": 5, "name": "氨糖软骨素"},
    {"id": 12, "name": "深海鱼油"}
  ],
  "created_at": "2026-02-01T10:30:00Z"
}

// Response
{
  "code": 0,
  "message": "同步成功"
}

三、通用响应格式

成功响应

{
  "code": 0,
  "message": "success",
  "data": { ... }
}

错误响应

{
  "code": 40001,
  "message": "手机号已注册",
  "data": null
}

错误码定义

错误码	说明
0	成功
40001	参数错误
40002	验证码错误
40003	用户已存在
40101	未登录
40102	Token过期
40103	Token无效
40301	无权限
40401	资源不存在
50001	服务器错误
50002	AI服务异常

四、认证机制

JWT Token

所有非认证接口需要在 Header 中携带 Token
格式：Authorization: Bearer {access_token}
access_token 有效期：2小时
refresh_token 有效期：7天

接口权限

类型	接口前缀	认证要求
公开	`/api/auth/*`	无需认证
用户	`/api/user/`, `/api/conversations/`	需要登录
同步	`/api/sync/*`	需要同步密钥

五、开发优先级

P0 - 核心功能（首批开发）

用户认证（注册/登录/Token）
体质辨识（问卷/计算/结果）
AI对话（对话管理/消息发送）
用户信息（档案管理）

P1 - 重要功能（二批开发）

健康调查问卷
用药记录管理
对话历史管理

P2 - 扩展功能（三批开发）

产品推荐
商城数据同步
体质历史追踪

六、数据库表对照

接口模块	关联数据表
认证模块	User
用户模块	User, HealthProfile, LifestyleInfo
健康调查	HealthProfile, MedicalHistory, FamilyHistory, AllergyRecord
体质辨识	ConstitutionAssessment, AssessmentAnswer, QuestionBank
AI对话	Conversation, Message
产品模块	Product, ConstitutionProduct, SymptomProduct
数据同步	PurchaseHistory

七、前端对接清单

前端当前使用模拟数据，需要替换为真实 API 的文件：

APP (React Native)

文件路径	需对接接口
`app/src/mock/user.ts`	认证、用户模块
`app/src/mock/constitution.ts`	体质辨识模块
`app/src/mock/chat.ts`	AI对话模块
`app/src/mock/products.ts`	产品模块
`app/src/mock/medication.ts`	用药记录（用户模块）
`app/src/mock/news.ts`	健康资讯（可选后端或静态）

Web (Vue 3)

文件路径	需对接接口
`web/src/mock/user.ts`	认证、用户模块
`web/src/mock/constitution.ts`	体质辨识模块
`web/src/mock/chat.ts`	AI对话模块
`web/src/mock/products.ts`	产品模块

文档生成时间：2026-02-01

12 KiB Raw Blame History

后端 API 接口清单

一、接口概览

二、详细接口列表

2.1 认证模块（Auth）

注册接口详情

2.2 用户模块（User）

健康档案详情

2.3 健康调查模块（Survey）

调查状态详情

2.4 体质辨识模块（Constitution）

问卷题目详情

提交答案详情

2.5 AI对话模块（Conversation）

发送消息详情（流式响应）

AI 上下文数据（后端组装）

2.6 产品模块（Product）

体质推荐产品详情

2.7 数据同步模块（Sync）

购买记录同步详情

三、通用响应格式

成功响应

错误响应

错误码定义

四、认证机制

JWT Token

接口权限

五、开发优先级

P0 - 核心功能（首批开发）

P1 - 重要功能（二批开发）

P2 - 扩展功能（三批开发）

六、数据库表对照

七、前端对接清单

APP (React Native)

Web (Vue 3)

12 KiB

Raw Blame History