# 健康 AI 助手 - 后端服务文档

> 基于 go-zero 微服务框架重构

---

## 一、服务概述

### 1.1 原架构（Gin）

```
server/
├── cmd/server/main.go       # 入口
├── internal/
│   ├── api/handler/         # HTTP 处理器
│   ├── api/middleware/      # 中间件
│   ├── api/router.go        # 路由定义
│   ├── config/              # 配置
│   ├── database/            # 数据库初始化
│   ├── model/               # GORM 模型
│   ├── repository/          # 数据访问层
│   └── service/             # 业务逻辑层
└── pkg/                     # 公共包
```

### 1.2 目标架构（go-zero）

```
backend/
├── health-api/              # REST API 服务
│   ├── etc/config.yaml      # 配置
│   ├── health.api           # API 定义
│   ├── internal/
│   │   ├── config/          # 配置结构
│   │   ├── handler/         # Handler 层
│   │   ├── logic/           # Logic 业务层
│   │   ├── svc/             # ServiceContext
│   │   └── types/           # 请求/响应类型
│   └── health.go            # 入口
├── health-rpc/              # RPC 服务（可选）
└── model/                   # 数据模型
```

---

## 二、功能模块

### 2.1 认证模块 (Auth)

| API        | 方法 | 路径                | 描述                |
| ---------- | ---- | ------------------- | ------------------- |
| 注册       | POST | /api/auth/register  | 手机号/邮箱注册     |
| 登录       | POST | /api/auth/login     | 登录获取 Token      |
| 刷新 Token | POST | /api/auth/refresh   | 刷新 JWT Token      |
| 发送验证码 | POST | /api/auth/send-code | 发送短信/邮箱验证码 |

**请求/响应示例：**

```go
// 注册请求
type RegisterReq struct {
    Phone    string `json:"phone,optional"`
    Email    string `json:"email,optional"`
    Password string `json:"password"`
    Code     string `json:"code,optional"`
}

// 登录响应
type LoginResp struct {
    Token     string `json:"token"`
    ExpiresAt int64  `json:"expires_at"`
    User      UserInfo `json:"user"`
}
```

### 2.2 用户模块 (User)

| API      | 方法 | 路径              | 描述             | 认证 |
| -------- | ---- | ----------------- | ---------------- | ---- |
| 获取信息 | GET  | /api/user/profile | 获取用户基本信息 | ✅   |
| 更新资料 | PUT  | /api/user/profile | 更新昵称/头像    | ✅   |

### 2.3 健康档案模块 (Health)

| API          | 方法   | 路径                          | 描述               | 认证 |
| ------------ | ------ | ----------------------------- | ------------------ | ---- |
| 获取完整档案 | GET    | /api/user/health-profile      | 获取所有健康信息   | ✅   |
| 更新档案     | PUT    | /api/user/health-profile      | 更新健康档案       | ✅   |
| 获取基础档案 | GET    | /api/user/basic-profile       | 获取基础信息       | ✅   |
| 获取生活习惯 | GET    | /api/user/lifestyle           | 获取生活习惯       | ✅   |
| 更新生活习惯 | PUT    | /api/user/lifestyle           | 更新生活习惯       | ✅   |
| 获取病史     | GET    | /api/user/medical-history     | 获取病史列表       | ✅   |
| 删除病史     | DELETE | /api/user/medical-history/:id | 删除单条病史       | ✅   |
| 获取家族史   | GET    | /api/user/family-history      | 获取家族病史       | ✅   |
| 删除家族史   | DELETE | /api/user/family-history/:id  | 删除单条家族史     | ✅   |
| 获取过敏记录 | GET    | /api/user/allergy-records     | 获取过敏记录       | ✅   |
| 删除过敏记录 | DELETE | /api/user/allergy-records/:id | 删除单条过敏记录   | ✅   |
| 获取购买历史 | GET    | /api/user/purchase-history    | 获取保健品购买记录 | ✅   |

### 2.4 健康调查模块 (Survey)

| API            | 方法 | 路径                              | 描述             | 认证 |
| -------------- | ---- | --------------------------------- | ---------------- | ---- |
| 获取状态       | GET  | /api/survey/status                | 获取调查完成状态 | ✅   |
| 提交基础信息   | POST | /api/survey/basic-info            | 提交基础健康信息 | ✅   |
| 提交生活习惯   | POST | /api/survey/lifestyle             | 提交生活习惯     | ✅   |
| 提交病史       | POST | /api/survey/medical-history       | 提交单条病史     | ✅   |
| 批量提交病史   | POST | /api/survey/medical-history/batch | 批量提交病史     | ✅   |
| 提交家族史     | POST | /api/survey/family-history        | 提交单条家族史   | ✅   |
| 批量提交家族史 | POST | /api/survey/family-history/batch  | 批量提交家族史   | ✅   |
| 提交过敏信息   | POST | /api/survey/allergy               | 提交单条过敏信息 | ✅   |
| 批量提交过敏   | POST | /api/survey/allergy/batch         | 批量提交过敏信息 | ✅   |
| 完成调查       | POST | /api/survey/complete              | 标记调查完成     | ✅   |

### 2.5 体质辨识模块 (Constitution)

| API          | 方法 | 路径                                | 描述             | 认证 |
| ------------ | ---- | ----------------------------------- | ---------------- | ---- |
| 获取问卷     | GET  | /api/constitution/questions         | 获取所有题目     | ✅   |
| 获取分组问卷 | GET  | /api/constitution/questions/grouped | 按体质分组获取   | ✅   |
| 提交测评     | POST | /api/constitution/submit            | 提交问卷答案     | ✅   |
| 获取结果     | GET  | /api/constitution/result            | 获取最新测评结果 | ✅   |
| 获取历史     | GET  | /api/constitution/history           | 获取测评历史     | ✅   |
| 获取建议     | GET  | /api/constitution/recommendations   | 获取调养建议     | ✅   |

**体质类型：**

- pinghe (平和质)
- qixu (气虚质)
- yangxu (阳虚质)
- yinxu (阴虚质)
- tanshi (痰湿质)
- shire (湿热质)
- xueyu (血瘀质)
- qiyu (气郁质)
- tebing (特禀质)

### 2.6 AI 对话模块 (Conversation)

| API            | 方法   | 路径                                   | 描述                 | 认证 |
| -------------- | ------ | -------------------------------------- | -------------------- | ---- |
| 获取列表       | GET    | /api/conversations                     | 获取对话列表         | ✅   |
| 创建对话       | POST   | /api/conversations                     | 创建新对话           | ✅   |
| 获取详情       | GET    | /api/conversations/:id                 | 获取对话消息         | ✅   |
| 删除对话       | DELETE | /api/conversations/:id                 | 删除对话             | ✅   |
| 发送消息       | POST   | /api/conversations/:id/messages        | 发送消息（非流式）   | ✅   |
| 发送消息(流式) | POST   | /api/conversations/:id/messages/stream | 发送消息（SSE 流式） | ✅   |

**AI 服务配置：**

- 阿里云通义千问（主要）
- OpenAI 兼容接口（备选）

### 2.7 产品模块 (Product)

| API        | 方法 | 路径                    | 描述             | 认证    |
| ---------- | ---- | ----------------------- | ---------------- | ------- |
| 获取列表   | GET  | /api/products           | 分页获取产品     | ❌      |
| 获取详情   | GET  | /api/products/:id       | 获取产品详情     | ❌      |
| 按分类获取 | GET  | /api/products/category  | 按分类筛选       | ❌      |
| 搜索产品   | GET  | /api/products/search    | 关键词搜索       | ❌      |
| 获取推荐   | GET  | /api/products/recommend | 基于体质推荐     | ✅      |
| 同步购买   | POST | /api/sync/purchase      | 商城同步购买记录 | API Key |

---

## 三、数据模型

### 3.1 用户相关

```sql
-- 用户表
CREATE TABLE users (
    id BIGINT PRIMARY KEY,
    phone VARCHAR(20) UNIQUE,
    email VARCHAR(100) UNIQUE,
    password_hash VARCHAR(255) NOT NULL,
    nickname VARCHAR(50),
    avatar VARCHAR(255),
    survey_completed BOOLEAN DEFAULT FALSE,
    created_at TIMESTAMP,
    updated_at TIMESTAMP,
    deleted_at TIMESTAMP
);

-- 健康档案表
CREATE TABLE health_profiles (
    id BIGINT PRIMARY KEY,
    user_id BIGINT UNIQUE NOT NULL,
    name VARCHAR(50),
    birth_date DATE,
    gender VARCHAR(10),
    height DECIMAL(5,2),
    weight DECIMAL(5,2),
    bmi DECIMAL(4,2),
    blood_type VARCHAR(10),
    occupation VARCHAR(50),
    marital_status VARCHAR(20),
    region VARCHAR(100)
);

-- 生活习惯表
CREATE TABLE lifestyle_infos (
    id BIGINT PRIMARY KEY,
    user_id BIGINT UNIQUE NOT NULL,
    sleep_time TIME,
    wake_time TIME,
    sleep_quality VARCHAR(20),
    meal_regularity VARCHAR(20),
    diet_preference VARCHAR(20),
    daily_water_ml INT,
    exercise_frequency VARCHAR(20),
    exercise_type VARCHAR(50),
    exercise_duration_min INT,
    is_smoker BOOLEAN,
    alcohol_frequency VARCHAR(20)
);
```

### 3.2 健康记录

```sql
-- 病史表
CREATE TABLE medical_histories (
    id BIGINT PRIMARY KEY,
    health_profile_id BIGINT NOT NULL,
    disease_name VARCHAR(100) NOT NULL,
    disease_type VARCHAR(50),
    diagnosed_date DATE,
    status VARCHAR(20),
    notes TEXT
);

-- 家族病史表
CREATE TABLE family_histories (
    id BIGINT PRIMARY KEY,
    health_profile_id BIGINT NOT NULL,
    relation VARCHAR(20) NOT NULL,
    disease_name VARCHAR(100) NOT NULL,
    notes TEXT
);

-- 过敏记录表
CREATE TABLE allergy_records (
    id BIGINT PRIMARY KEY,
    health_profile_id BIGINT NOT NULL,
    allergy_type VARCHAR(50) NOT NULL,
    allergen VARCHAR(100) NOT NULL,
    severity VARCHAR(20),
    reaction_desc TEXT
);
```

### 3.3 体质辨识

```sql
-- 体质测评表
CREATE TABLE constitution_assessments (
    id BIGINT PRIMARY KEY,
    user_id BIGINT NOT NULL,
    assessed_at TIMESTAMP NOT NULL,
    scores JSON,                    -- 各体质得分
    primary_constitution VARCHAR(20),
    secondary_constitutions JSON,   -- 兼夹体质
    recommendations JSON            -- 调养建议
);

-- 测评答案表
CREATE TABLE assessment_answers (
    id BIGINT PRIMARY KEY,
    assessment_id BIGINT NOT NULL,
    question_id INT NOT NULL,
    score INT CHECK (score >= 1 AND score <= 5)
);

-- 问卷题库表
CREATE TABLE question_banks (
    id INT PRIMARY KEY,
    constitution_type VARCHAR(20) NOT NULL,
    question_text TEXT NOT NULL,
    options JSON,
    order_num INT
);
```

### 3.4 对话

```sql
-- 对话表
CREATE TABLE conversations (
    id BIGINT PRIMARY KEY,
    user_id BIGINT NOT NULL,
    title VARCHAR(200),
    created_at TIMESTAMP,
    updated_at TIMESTAMP,
    deleted_at TIMESTAMP
);

-- 消息表
CREATE TABLE messages (
    id BIGINT PRIMARY KEY,
    conversation_id BIGINT NOT NULL,
    role VARCHAR(20) NOT NULL,      -- user/assistant/system
    content TEXT NOT NULL,
    created_at TIMESTAMP
);
```

### 3.5 产品

```sql
-- 产品表
CREATE TABLE products (
    id BIGINT PRIMARY KEY,
    name VARCHAR(200) NOT NULL,
    category VARCHAR(50),
    description TEXT,
    efficacy TEXT,
    suitable TEXT,
    price DECIMAL(10,2),
    image_url VARCHAR(500),
    mall_url VARCHAR(500),
    is_active BOOLEAN DEFAULT TRUE
);

-- 体质-产品关联表
CREATE TABLE constitution_products (
    id BIGINT PRIMARY KEY,
    constitution_type VARCHAR(20) NOT NULL,
    product_id BIGINT NOT NULL,
    priority INT DEFAULT 0,
    reason TEXT
);

-- 购买历史表
CREATE TABLE purchase_histories (
    id BIGINT PRIMARY KEY,
    user_id BIGINT NOT NULL,
    order_no VARCHAR(50),
    product_id BIGINT,
    product_name VARCHAR(200),
    purchased_at TIMESTAMP,
    source VARCHAR(50)
);
```

---

## 四、配置说明

### 4.1 服务配置

```yaml
Name: health-api
Host: 0.0.0.0
Port: 8080
Mode: dev

# JWT 认证
Auth:
  AccessSecret: health-ai-secret-key-change-in-production
  AccessExpire: 86400 # 24小时

# 数据库
Database:
  Driver: sqlite
  DataSource: ./data/health.db
  # PostgreSQL
  # Driver: postgres
  # DataSource: host=localhost port=5432 user=postgres password=xxx dbname=health_app sslmode=disable

# AI 服务
AI:
  Provider: aliyun
  MaxHistoryMessages: 10
  MaxTokens: 2000
  Aliyun:
    ApiKey: sk-xxx
    Model: qwen-plus
  OpenAI:
    ApiKey: sk-xxx
    BaseUrl: https://api.openai.com/v1
    Model: gpt-3.5-turbo
```

### 4.2 中间件

1. **JWT 认证中间件**

   - 验证 Authorization Header
   - 解析 Token 获取 userID
   - 注入上下文

2. **CORS 中间件**

   - 允许跨域请求
   - 配置允许的方法和头部

3. **日志中间件**
   - 请求日志记录
   - 响应时间统计

---

## 五、API 统计

| 模块     | API 数量 | 需认证 | 说明                  |
| -------- | -------- | ------ | --------------------- |
| 认证     | 4        | 0      | 注册/登录/刷新/验证码 |
| 用户     | 2        | 2      | 获取/更新资料         |
| 健康档案 | 12       | 12     | 完整健康信息 CRUD     |
| 健康调查 | 10       | 10     | 分步提交流程          |
| 体质辨识 | 6        | 6      | 问卷/测评/结果        |
| AI 对话  | 6        | 6      | 对话管理/消息         |
| 产品     | 6        | 1      | 产品查询/推荐         |
| **总计** | **46**   | **37** |                       |

---

## 六、迁移计划

### 6.1 阶段一：基础框架 ✅ 已完成

- [x] 创建 backend 目录
- [x] 使用 mcp-zero 创建 API 服务结构
- [x] 定义 .api 文件（46 个 API 端点）
- [x] 生成基础代码（47 个 Handler + 47 个 Logic）

### 6.2 阶段二：核心功能

- [ ] 迁移认证模块
- [ ] 迁移用户模块
- [ ] 迁移健康档案模块

### 6.3 阶段三：业务功能

- [ ] 迁移体质辨识模块
- [ ] 迁移 AI 对话模块
- [ ] 迁移产品模块

### 6.4 阶段四：优化完善

- [ ] 添加弹性模式（熔断/限流）
- [ ] 优化数据库访问
- [ ] 添加监控和日志

---

## 七、技术栈对比

| 项目     | 原架构 (Gin)               | 目标架构 (go-zero)  |
| -------- | -------------------------- | ------------------- |
| Web 框架 | Gin                        | go-zero rest        |
| ORM      | GORM                       | sqlx / goctl model  |
| 配置     | Viper                      | go-zero conf        |
| 路由     | Gin Router                 | .api 文件生成       |
| 中间件   | Gin Middleware             | go-zero Middleware  |
| 依赖注入 | 手动                       | ServiceContext      |
| 代码生成 | 无                         | goctl               |
| 分层架构 | Handler/Service/Repository | Handler/Logic/Model |