# 健康AI问询助手 - 后端API文档 > 后端服务地址: `http://localhost:8080` > > 所有需要认证的接口，请在Header中添加: `Authorization: Bearer ` --- ## 一、认证接口 ### 1.1 用户注册 - **POST** `/api/auth/register` **请求体：** ```json { "phone": "13800138000", "password": "123456", "nickname": "用户昵称" // 可选 } ``` **响应：** ```json { "code": 0, "message": "success", "data": { "token": "eyJhbGc...", "user_id": 1, "nickname": "用户昵称", "avatar": "", "survey_completed": false } } ``` ### 1.2 用户登录 - **POST** `/api/auth/login` **请求体：** ```json { "phone": "13800138000", "password": "123456" } ``` **响应：** 同注册接口 ### 1.3 刷新Token - **POST** `/api/auth/refresh` - **需要认证** **响应：** ```json { "code": 0, "message": "success", "data": { "token": "新的token" } } ``` ### 1.4 发送验证码 - **POST** `/api/auth/send-code` **请求体：** ```json { "phone": "13800138000", "type": "register" // register/login/reset } ``` **响应：** ```json { "code": 0, "message": "验证码已发送", "data": { "phone": "138****8000", "expires_in": 300, "demo_code": "123456" // 演示环境，正式环境无此字段 } } ``` > **注意**: 当前为演示版本，验证码固定为 `123456`。正式环境需要接入短信服务。 --- ## 二、用户接口 ### 2.1 获取用户信息 - **GET** `/api/user/profile` - **需要认证** **响应：** ```json { "code": 0, "message": "success", "data": { "user_id": 1, "phone": "13800138000", "email": "", "nickname": "用户昵称", "avatar": "", "survey_completed": false } } ``` ### 2.2 更新用户资料 - **PUT** `/api/user/profile` - **需要认证** **请求体：** ```json { "nickname": "新昵称", "avatar": "头像URL" } ``` --- ## 三、健康调查接口 ### 3.1 获取调查状态 - **GET** `/api/survey/status` - **需要认证** **响应：** ```json { "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` - **需要认证** **请求体：** ```json { "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` - **需要认证** **请求体：** ```json { "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` - **需要认证** **请求体：** ```json { "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` - **需要认证** **请求体：** ```json { "histories": [ { "disease_name": "高血压", "disease_type": "chronic", "diagnosed_date": "2020-01", "status": "controlled", "notes": "" } ] } ``` ### 3.6 提交家族病史 - **POST** `/api/survey/family-history` - **需要认证** **请求体：** ```json { "relation": "father", // father/mother/grandparent "disease_name": "糖尿病", "notes": "" } ``` ### 3.7 提交过敏信息 - **POST** `/api/survey/allergy` - **需要认证** **请求体：** ```json { "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` - **需要认证** **响应：** ```json { "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` - **需要认证** **请求体：** ```json { "answers": [ {"question_id": 1, "score": 3}, {"question_id": 2, "score": 2} // ... 所有题目的答案，score: 1-5 对应选项 ] } ``` **响应：** ```json { "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` - **需要认证** **响应：** ```json { "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` - **需要认证** **请求体：** ```json { "title": "对话标题" // 可选 } ``` ### 5.3 获取对话详情 - **GET** `/api/conversations/:id` - **需要认证** **响应：** ```json { "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` - **需要认证** **请求体：** ```json { "content": "我最近总是感觉疲劳怎么办？" } ``` **响应：** ```json { "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 更新健康档案 - **PUT** `/api/user/health-profile` - **需要认证** **请求体：** ```json { "name": "张三", "birth_date": "1990-05-15", "gender": "male", "height": 175, "weight": 70, "blood_type": "A", "occupation": "工程师", "marital_status": "married", "region": "北京" } ``` **响应：** ```json { "code": 0, "message": "success", "data": { "id": 1, "user_id": 1, "name": "张三", "birth_date": "1990-05-15T00:00:00Z", "gender": "male", "height": 175, "weight": 70, "bmi": 22.86, "blood_type": "A", "occupation": "工程师", "marital_status": "married", "region": "北京" } } ``` ### 6.3 获取基础档案 - **GET** `/api/user/basic-profile` - **需要认证** ### 6.4 获取生活习惯 - **GET** `/api/user/lifestyle` - **需要认证** ### 6.5 更新生活习惯 - **PUT** `/api/user/lifestyle` - **需要认证** **请求体：** ```json { "sleep_time": "23:00", "wake_time": "07:00", "sleep_quality": "normal", "meal_regularity": "regular", "diet_preference": "清淡", "daily_water_ml": 2000, "exercise_frequency": "sometimes", "exercise_type": "跑步", "exercise_duration_min": 30, "is_smoker": false, "alcohol_frequency": "never" } ``` **响应：** ```json { "code": 0, "message": "success", "data": { "id": 1, "user_id": 1, "sleep_time": "23:00", "wake_time": "07:00", "sleep_quality": "normal", "meal_regularity": "regular", "diet_preference": "清淡", "daily_water_ml": 2000, "exercise_frequency": "sometimes", "exercise_type": "跑步", "exercise_duration_min": 30, "is_smoker": false, "alcohol_frequency": "never" } } ``` ### 6.6 获取病史列表 - **GET** `/api/user/medical-history` - **需要认证** ### 6.7 删除病史记录 - **DELETE** `/api/user/medical-history/:id` - **需要认证** ### 6.8 获取家族病史 - **GET** `/api/user/family-history` - **需要认证** ### 6.9 获取过敏记录 - **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` **请求体：** ```json { "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`： ```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 或联系后端开发团队。