# 后端 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 |

#### 注册接口详情
```json
// 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 |

#### 健康档案详情
```json
// 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 |

#### 调查状态详情
```json
// 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 |

#### 问卷题目详情
```json
// 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
      }
      // ...更多题目
    ]
  }
}
```

#### 提交答案详情
```json
// 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 |

#### 发送消息详情（流式响应）
```json
// 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 时需要自动注入以下上下文：

```json
{
  "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[] |

#### 体质推荐产品详情
```json
// 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 |

#### 购买记录同步详情
```json
// 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": "同步成功"
}
```

---

## 三、通用响应格式

### 成功响应
```json
{
  "code": 0,
  "message": "success",
  "data": { ... }
}
```

### 错误响应
```json
{
  "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 - 核心功能（首批开发）
1. 用户认证（注册/登录/Token）
2. 体质辨识（问卷/计算/结果）
3. AI对话（对话管理/消息发送）
4. 用户信息（档案管理）

### P1 - 重要功能（二批开发）
1. 健康调查问卷
2. 用药记录管理
3. 对话历史管理

### P2 - 扩展功能（三批开发）
1. 产品推荐
2. 商城数据同步
3. 体质历史追踪

---

## 六、数据库表对照

| 接口模块 | 关联数据表 |
|----------|-----------|
| 认证模块 | 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*