healthapp/backend/BACKEND.md

健康 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	发送短信/邮箱验证码

请求/响应示例：

// 注册请求
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 用户相关

-- 用户表
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 健康记录

-- 病史表
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 体质辨识

-- 体质测评表
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 对话

-- 对话表
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 产品

-- 产品表
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 服务配置

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 阶段一：基础框架 ✅ 已完成

• 创建 backend 目录
• 使用 mcp-zero 创建 API 服务结构
• 定义 .api 文件（46 个 API 端点）
• 生成基础代码（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