健康 AI 助手 — Health AI Assistant

基于中医体质辨识理论的智能健康管理平台，包含 Web 端、H5 商城、React Native APP 三个前端和统一 Go 后端。

---

项目结构

healthApps/
├── backend/                # 后端服务
│   ├── BACKEND.md          # 后端开发文档
│   └── healthapi/          # Go-Zero API 服务
│       ├── etc/            #   配置文件
│       ├── internal/       #   业务代码 (handler / logic / model / svc / config)
│       ├── pkg/            #   公共包 (ai / jwt / errorx / response)
│       ├── tests/          #   后端集成测试
│       ├── healthapi.go    #   入口文件
│       ├── healthapi.api   #   API 定义文件
│       ├── go.mod / go.sum #   Go 依赖管理
│       └── data/           #   SQLite 数据库文件（自动生成，已 gitignore）
├── web/                    # 健康 AI 助手前端 (Vue 3)
├── mall/                   # 健康商城前端 (Vue 3)
├── app/                    # React Native APP (Expo)
├── scripts/                # 启动辅助脚本
│   ├── dev.js              #   统一前端启动脚本
│   ├── start-web.bat       #   单独启动 Web
│   ├── start-app.bat       #   单独启动 APP
│   └── start-all.bat       #   同时启动 Web + APP
├── tests/                  # E2E 自动化测试 (Playwright)
├── TODOS/                  # 开发任务文档
├── start.bat               # Windows 启动入口
├── start.sh                # Linux / macOS / Git Bash 启动入口
├── agents.md               # Agents 开发规范与记录
├── design.md               # 项目设计文档
├── mall-design.md          # 商城设计文档
└── package.json            # 根目录脚本 & 测试依赖

---

技术栈总览

模块	技术	端口	说明
后端 API	Go 1.22+ · Go-Zero · GORM · SQLite	8080	统一后端，JWT 认证
Web 前端	Vue 3 · TypeScript · Vite · Element Plus · Pinia	5173	健康 AI 助手
商城前端	Vue 3 · TypeScript · Vite · Element Plus · Pinia	5174	健康商城 H5
APP 前端	React Native · Expo 54 · React Navigation · Zustand	8081	移动端 APP
E2E 测试	Playwright · Chromium	-	自动化功能测试

---

环境要求

工具	最低版本	用途
Node.js	v18+ (推荐 v22)	Web / Mall / APP 前端 & 测试
npm	v9+	包管理
Go	1.22+	后端编译运行
Git	2.30+	版本管理

APP 开发还需要 Expo CLI（随项目依赖安装），真机调试需 Expo Go 客户端。

---

快速上手（从零开始）

新机器一键部署（复制即用）

# 1. 克隆仓库
git clone https://gitea.gxxhygroup.com/dark/healthapp.git healthApps
cd healthApps

# 2. 启动后端（新开终端）
cd backend/healthapi
go mod download
mkdir -p data
go run healthapi.go
# 等待出现 "Starting server at 0.0.0.0:8080..." 后继续

# 3. 启动 Web 前端（新开终端）
cd web
cp .env.example .env
npm install
npm run dev
# 访问 http://localhost:5173

# 4. 启动商城前端（新开终端）
cd mall
cp .env.example .env
npm install
npm run dev
# 访问 http://localhost:5174

# 5. 启动 APP（可选，新开终端）
cd app
npm install
npx expo start --web
# 访问 http://localhost:8081

测试账号：手机号 13800138000，密码/验证码 123456（后端首次启动自动创建）

---

以下是每个步骤的详细说明。

1. 克隆仓库

git clone https://gitea.gxxhygroup.com/dark/healthapp.git healthApps
cd healthApps

2. 后端启动

cd backend/healthapi

# 安装 Go 依赖
go mod download

# 首次需要创建 data 目录
mkdir -p data

# 直接运行（开发模式）
go run healthapi.go

# 或编译后运行
go build -o healthapi .
./healthapi                           # 默认读取 etc/healthapi-api.yaml
# ./healthapi -f etc/healthapi-api.yaml  # 显式指定配置

后端启动后会自动完成：

• SQLite 数据库创建与表结构迁移（data/health.db）
• 体质测评问卷题库初始化（27 题）
• 测试用户创建

访问 http://localhost:8080/api/health 验证是否正常。

3. Web 前端启动

cd web

# 创建环境变量（从模板复制，通常不需要修改）
cp .env.example .env

# 安装依赖
npm install

# 启动开发服务
npm run dev

打开 http://localhost:5173

4. 商城前端启动

cd mall

# 创建环境变量
cp .env.example .env

# 安装依赖
npm install

# 启动开发服务
npm run dev

打开 http://localhost:5174

5. APP 前端启动

cd app

# 安装依赖
npm install

# 启动 Expo 开发服务
npx expo start

# 或直接启动 Web 版
npx expo start --web

APP 默认连接 http://localhost:8080 后端，配置在 app/src/api/config.ts 中。

---

一键启动（推荐）

使用根目录提供的启动脚本，自动处理端口占用和依赖安装。

Windows

start.bat

Linux / macOS / Git Bash

chmod +x start.sh
./start.sh

启动菜单：

[1] Start Web (Vue 3 - 5173)
[2] Start Mall (Vue 3 - 5174)
[3] Start APP (React Native)
[4] Start Web + Mall
[5] Start Web + APP       (仅 Windows)
[6] Exit

npm 脚本

npm run dev           # 同时启动 Web + Mall
npm run dev:web       # 仅启动 Web
npm run dev:mall      # 仅启动 Mall
npm run dev:kill      # 关闭占用端口的进程

---

环境变量配置

Web (web/.env)

VITE_API_BASE_URL=http://localhost:8080     # 后端 API
VITE_MALL_URL=http://localhost:5174         # 商城地址（跳转用）

Mall (mall/.env)

VITE_API_BASE_URL=http://localhost:8080     # 后端 API
VITE_HEALTH_AI_URL=http://localhost:5173    # 健康助手地址（跳转用）

后端 (backend/healthapi/etc/healthapi-api.yaml)

Port: 8080
Auth:
  AccessSecret: health-ai-secret-key-change-in-production
Database:
  Driver: sqlite
  DataSource: ./data/health.db
AI:
  Provider: aliyun
  Aliyun:
    ApiKey: <your-api-key>      # 阿里云百炼 API Key
    Model: qwen-plus

生产环境请务必修改 AccessSecret 和 ApiKey。

---

测试账号

字段	值
手机号	13800138000
密码 / 验证码	123456

后端首次启动会自动创建此测试用户。

---

功能模块

健康 AI 助手 (Web)

• 手机号登录（验证码 / 密码）
• 体质辨识测评（9 种中医体质，27 道问卷）
• AI 智能问答（流式输出，支持思考过程展示）
• 多轮对话管理（创建/删除/历史记录）
• 个人中心（健康档案、用药记录、体质报告）

健康商城 (Mall)

• 商品浏览（首页推荐、分类、搜索、详情）
• 按需登录（浏览免登录，下单/支付时登录）
• 购物车（增删改、批量操作、清空）
• 订单流程（预览 → 创建 → 支付 → 收货）
• 收货地址管理
• 会员中心（积分、订单状态、退出登录）
• 体质推荐商品（基于测评结果）

APP (React Native)

• 与 Web 端相同的核心功能
• 原生移动端交互体验
• Expo Web 兼容（可在浏览器预览）

---

E2E 自动化测试

# 安装测试依赖（仅首次）
npm install                    # 根目录 — 安装 Playwright
npx playwright install chromium

# 运行测试（需先启动对应前端）
node tests/mall.test.js        # 商城前端 — Mock 数据（53 项）
node tests/mall-real.test.js   # 商城前端 — 真实后端（52 项，需启动后端）
node tests/constitution.test.js        # 体质测评
node tests/health-profile-complete.test.js  # 健康档案
node tests/chat.test.js        # AI 对话
node tests/profile.test.js     # 个人中心

详见 tests/README.md

---

常见问题

Q: 克隆后前端启动报错 "Cannot find module"

确保在对应目录执行了 npm install：

cd web && npm install
cd ../mall && npm install
cd ../app && npm install

Q: 前端启动后页面空白或接口报错

检查 .env 文件是否存在。若不存在，从模板创建：

cp web/.env.example web/.env
cp mall/.env.example mall/.env

Q: 后端启动报 "cannot open database"

手动创建 data 目录：

mkdir -p backend/healthapi/data

Q: 端口被占用

npm run dev:kill    # 自动清理 5173 / 5174 端口

或手动：

# Windows
netstat -ano | findstr :8080
taskkill /PID <pid> /F

# Linux / macOS
lsof -i :8080
kill -9 <pid>

Q: APP 启动后无法连接后端

编辑 app/src/api/config.ts，确保 API_BASE_URL 指向后端地址。 真机调试时不能用 localhost，需改为电脑局域网 IP（如 http://192.168.1.100:8080）。

---

项目关系图

                    ┌─────────────────┐
                    │  后端 API :8080  │
                    │  Go-Zero + GORM │
                    │  SQLite / MySQL │
                    └────────┬────────┘
                             │
            ┌────────────────┼────────────────┐
            │                │                │
   ┌────────▼───────┐ ┌─────▼──────┐ ┌───────▼──────┐
   │  Web :5173     │ │ Mall :5174 │ │  APP :8081   │
   │  Vue 3 + TS   │ │ Vue 3 + TS │ │  RN + Expo   │
   │  健康 AI 助手  │ │ 健康商城    │ │  移动端 APP  │
   └────────┬───────┘ └─────┬──────┘ └──────────────┘
            │               │
            └──── 跨项目跳转 ┘
          (共享 JWT Token via localStorage)

---

开发文档

文档	说明
agents.md	开发规范、API 约定、测试规范、变更记录
design.md	项目总体设计文档
mall-design.md	商城功能设计文档
backend/BACKEND.md	后端开发文档
tests/README.md	测试使用说明
TODOS/	开发任务与规划