# 健康 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. 克隆仓库 ```bash git clone <仓库地址> healthApps cd healthApps ``` ### 2. 后端启动 ```bash 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 前端启动 ```bash cd web # 创建环境变量（从模板复制，通常不需要修改） cp .env.example .env # 安装依赖 npm install # 启动开发服务 npm run dev ``` 打开 http://localhost:5173 ### 4. 商城前端启动 ```bash cd mall # 创建环境变量 cp .env.example .env # 安装依赖 npm install # 启动开发服务 npm run dev ``` 打开 http://localhost:5174 ### 5. APP 前端启动 ```bash cd app # 安装依赖 npm install # 启动 Expo 开发服务 npx expo start # 或直接启动 Web 版 npx expo start --web ``` > APP 默认连接 `http://localhost:8080` 后端，配置在 `app/src/api/config.ts` 中。 --- ## 一键启动（推荐） 使用根目录提供的启动脚本，自动处理端口占用和依赖安装。 ### Windows ```cmd start.bat ``` ### Linux / macOS / Git Bash ```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 脚本 ```bash npm run dev # 同时启动 Web + Mall npm run dev:web # 仅启动 Web npm run dev:mall # 仅启动 Mall npm run dev:kill # 关闭占用端口的进程 ``` --- ## 环境变量配置 ### Web (`web/.env`) ```ini VITE_API_BASE_URL=http://localhost:8080 # 后端 API VITE_MALL_URL=http://localhost:5174 # 商城地址（跳转用） ``` ### Mall (`mall/.env`) ```ini VITE_API_BASE_URL=http://localhost:8080 # 后端 API VITE_HEALTH_AI_URL=http://localhost:5173 # 健康助手地址（跳转用） ``` ### 后端 (`backend/healthapi/etc/healthapi-api.yaml`) ```yaml Port: 8080 Auth: AccessSecret: health-ai-secret-key-change-in-production Database: Driver: sqlite DataSource: ./data/health.db AI: Provider: aliyun Aliyun: ApiKey: # 阿里云百炼 API Key Model: qwen-plus ``` > 生产环境请务必修改 `AccessSecret` 和 `ApiKey`。 --- ## 测试账号 | 字段 | 值 | |------|---| | 手机号 | `13800138000` | | 密码 / 验证码 | `123456` | > 后端首次启动会自动创建此测试用户。 --- ## 功能模块 ### 健康 AI 助手 (Web) - 手机号登录（验证码 / 密码） - 体质辨识测评（9 种中医体质，27 道问卷） - AI 智能问答（流式输出，支持思考过程展示） - 多轮对话管理（创建/删除/历史记录） - 个人中心（健康档案、用药记录、体质报告） ### 健康商城 (Mall) - 商品浏览（首页推荐、分类、搜索、详情） - 按需登录（浏览免登录，下单/支付时登录） - 购物车（增删改、批量操作、清空） - 订单流程（预览 → 创建 → 支付 → 收货） - 收货地址管理 - 会员中心（积分、订单状态、退出登录） - 体质推荐商品（基于测评结果） ### APP (React Native) - 与 Web 端相同的核心功能 - 原生移动端交互体验 - Expo Web 兼容（可在浏览器预览） --- ## E2E 自动化测试 ```bash # 安装测试依赖（仅首次） 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`](tests/README.md) --- ## 常见问题 ### Q: 克隆后前端启动报错 "Cannot find module" 确保在对应目录执行了 `npm install`： ```bash cd web && npm install cd ../mall && npm install cd ../app && npm install ``` ### Q: 前端启动后页面空白或接口报错 检查 `.env` 文件是否存在。若不存在，从模板创建： ```bash cp web/.env.example web/.env cp mall/.env.example mall/.env ``` ### Q: 后端启动报 "cannot open database" 手动创建 `data` 目录： ```bash mkdir -p backend/healthapi/data ``` ### Q: 端口被占用 ```bash npm run dev:kill # 自动清理 5173 / 5174 端口 ``` 或手动： ```bash # Windows netstat -ano | findstr :8080 taskkill /PID /F # Linux / macOS lsof -i :8080 kill -9 ``` ### 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`](agents.md) | 开发规范、API 约定、测试规范、变更记录 | | [`design.md`](design.md) | 项目总体设计文档 | | [`mall-design.md`](mall-design.md) | 商城功能设计文档 | | [`backend/BACKEND.md`](backend/BACKEND.md) | 后端开发文档 | | [`tests/README.md`](tests/README.md) | 测试使用说明 | | [`TODOS/`](TODOS/) | 开发任务与规划 |