# 数智健调系统 - 后端API ## 项目简介 数智健调系统后端API,基于Node.js + Express + TypeORM + MySQL开发,为体重管理模块提供完整的RESTful API服务。 ## 技术栈 - **框架**: Express 4.18+ - **语言**: TypeScript 5.3+ - **ORM**: TypeORM 0.3+ - **数据库**: MySQL 8.0+ - **验证**: class-validator - **其他**: Redis(可选)、Winston(日志) ## 项目结构 ``` backend/ ├── database/ # 数据库脚本 │ ├── schema.sql # 表结构定义 │ ├── init.sql # 数据库初始化 │ ├── seed.sql # 测试数据 │ └── README.md # 数据库文档 ├── src/ # 源代码 │ ├── config/ # 配置文件 │ │ └── database.ts # 数据库配置 │ ├── controllers/ # 控制器层 │ │ └── WeightController.ts │ ├── dto/ # 数据传输对象 │ │ ├── weight-record.dto.ts │ │ ├── weight-goal.dto.ts │ │ └── tag.dto.ts │ ├── entities/ # ORM实体模型 │ │ ├── User.ts │ │ ├── WeightRecord.ts │ │ ├── WeightGoal.ts │ │ ├── Tag.ts │ │ ├── WeightRecordTag.ts │ │ └── AnomalyLog.ts │ ├── middlewares/ # 中间件 │ │ ├── auth.middleware.ts │ │ ├── error.middleware.ts │ │ └── logger.middleware.ts │ ├── routes/ # 路由定义 │ │ ├── index.ts │ │ └── weight.routes.ts │ ├── services/ # 服务层 │ │ ├── WeightRecordService.ts │ │ ├── WeightGoalService.ts │ │ ├── TagService.ts │ │ └── StatsService.ts │ └── server.ts # 服务器入口 ├── .env.example # 环境变量示例 ├── .gitignore # Git忽略文件 ├── package.json # 项目依赖 ├── tsconfig.json # TypeScript配置 └── README.md # 本文档 ``` ## 快速开始 ### 1. 环境要求 - Node.js >= 18.0.0 - npm >= 9.0.0 - MySQL >= 8.0 ### 2. 安装依赖 ```bash cd campus_health_app/backend npm install ``` ### 3. 配置环境变量 复制环境变量示例文件并修改配置: ```bash cp .env.example .env ``` 编辑 `.env` 文件,配置数据库连接: ```env NODE_ENV=development PORT=3000 API_PREFIX=/api DB_TYPE=mysql DB_HOST=localhost DB_PORT=3306 DB_USERNAME=root DB_PASSWORD=your_password DB_DATABASE=campus_health DB_SYNCHRONIZE=false DB_LOGGING=true CORS_ORIGIN=http://localhost:4200 ``` ### 4. 初始化数据库 ```bash # 创建数据库 mysql -u root -p < database/init.sql # 创建表结构 mysql -u root -p campus_health < database/schema.sql # (可选)插入测试数据 mysql -u root -p campus_health < database/seed.sql ``` ### 5. 启动开发服务器 ```bash npm run dev ``` 服务器将在 `http://localhost:3000` 启动。 ### 6. 构建生产版本 ```bash # 编译TypeScript npm run build # 启动生产服务器 npm start ``` ## API文档 ### 基础信息 - **Base URL**: `http://localhost:3000/api` - **认证方式**: 请求头 `x-user-id`(临时方案) - **响应格式**: JSON ### 通用响应格式 **成功响应**: ```json { "success": true, "data": { ... }, "message": "操作成功" } ``` **错误响应**: ```json { "success": false, "message": "错误信息", "errors": ["详细错误1", "详细错误2"] } ``` ### API端点 #### 1. 体重记录相关 ##### 获取体重记录列表 ```http GET /api/weight/records Headers: x-user-id: test-user-001 Query Parameters: - from: string (YYYY-MM-DD, optional) - to: string (YYYY-MM-DD, optional) - condition: string (fasting|after_meal, optional) - tags: string[] (optional) - page: number (default: 1) - limit: number (default: 100) Response 200: { "success": true, "data": { "records": [...], "total": 90, "page": 1, "limit": 100 } } ``` ##### 添加体重记录 ```http POST /api/weight/records Headers: x-user-id: test-user-001 Content-Type: application/json Body: { "date": "2025-10-22", "measurementTime": "08:00", "weight": 65.5, "bodyFat": 22.3, "muscleMass": 28.5, "measurementCondition": "fasting", "notes": "早晨测量", "tags": ["开始运动"] } Response 201: { "success": true, "data": { ... }, "message": "体重记录添加成功" } ``` ##### 更新体重记录 ```http PUT /api/weight/records/:id Headers: x-user-id: test-user-001 Content-Type: application/json Body: { "weight": 65.3, "notes": "更新备注" } Response 200: { "success": true, "data": { ... }, "message": "更新成功" } ``` ##### 删除体重记录 ```http DELETE /api/weight/records/:id Headers: x-user-id: test-user-001 Response 200: { "success": true, "message": "删除成功" } ``` #### 2. 目标管理相关 ##### 获取当前目标 ```http GET /api/weight/goal Headers: x-user-id: test-user-001 Response 200: { "success": true, "data": { "id": "...", "targetWeight": 65.0, "targetBodyFat": 18.0, "targetDate": "2025-12-31", ... } } ``` ##### 设置目标 ```http POST /api/weight/goal Headers: x-user-id: test-user-001 Content-Type: application/json Body: { "targetWeight": 65.0, "targetBodyFat": 18.0, "targetDate": "2025-12-31" } Response 201: { "success": true, "data": { ... }, "message": "目标设置成功" } ``` ##### 更新目标 ```http PUT /api/weight/goal Headers: x-user-id: test-user-001 Content-Type: application/json Body: { "targetWeight": 63.0 } Response 200: { "success": true, "data": { ... }, "message": "目标更新成功" } ``` #### 3. 标签相关 ##### 获取标签列表 ```http GET /api/weight/tags Headers: x-user-id: test-user-001 Response 200: { "success": true, "data": [ { "id": "...", "name": "开始运动", "type": "system", "color": "#3b82f6" }, ... ] } ``` ##### 创建自定义标签 ```http POST /api/weight/tags Headers: x-user-id: test-user-001 Content-Type: application/json Body: { "name": "新标签", "color": "#f59e0b" } Response 201: { "success": true, "data": { ... }, "message": "标签创建成功" } ``` #### 4. 统计分析 ##### 获取统计数据 ```http GET /api/weight/stats Headers: x-user-id: test-user-001 Query Parameters: - from: string (YYYY-MM-DD, optional) - to: string (YYYY-MM-DD, optional) Response 200: { "success": true, "data": { "currentWeight": 65.5, "weightChange": -4.5, "daysTracked": 60, "avgWeeklyChange": -0.75, "bodyFatChange": -2.8, "goalProgress": 75.0, "goalETA": "2025-11-15" } } ``` ## 测试 ### 使用curl测试 ```bash # 健康检查 curl http://localhost:3000/api/health # 获取体重记录 curl -H "x-user-id: test-user-001" \ http://localhost:3000/api/weight/records # 添加体重记录 curl -X POST http://localhost:3000/api/weight/records \ -H "x-user-id: test-user-001" \ -H "Content-Type: application/json" \ -d '{ "date": "2025-10-22", "weight": 65.5, "bodyFat": 22.3, "muscleMass": 28.5 }' # 获取当前目标 curl -H "x-user-id: test-user-001" \ http://localhost:3000/api/weight/goal # 获取统计数据 curl -H "x-user-id: test-user-001" \ http://localhost:3000/api/weight/stats ``` ### 使用Postman测试 1. 导入 Postman Collection(待创建) 2. 设置环境变量 `base_url = http://localhost:3000/api` 3. 设置全局请求头 `x-user-id = test-user-001` ## 部署 ### Docker部署(推荐) (待补充) ### 传统部署 1. 安装Node.js和MySQL 2. 克隆代码并安装依赖 3. 配置环境变量 4. 初始化数据库 5. 编译并启动服务 ```bash npm run build npm start ``` ### 使用PM2管理 ```bash # 安装PM2 npm install -g pm2 # 启动服务 pm2 start dist/server.js --name campus-health-api # 查看日志 pm2 logs campus-health-api # 重启服务 pm2 restart campus-health-api ``` ## 开发指南 ### 添加新API接口 1. 在 `src/dto/` 创建DTO 2. 在 `src/services/` 创建服务 3. 在 `src/controllers/` 创建控制器方法 4. 在 `src/routes/` 添加路由 ### 代码规范 ```bash # 运行ESLint npm run lint # 格式化代码 npm run format ``` ## 常见问题 ### 1. 数据库连接失败 检查 `.env` 文件中的数据库配置是否正确,确保MySQL服务已启动。 ### 2. 端口被占用 修改 `.env` 中的 `PORT` 配置,或停止占用3000端口的进程。 ### 3. TypeORM同步错误 确保 `DB_SYNCHRONIZE=false`,使用SQL脚本管理数据库结构。 ## 后续开发计划 - [ ] 实现JWT认证 - [ ] 添加异常检测API - [ ] 实现Redis缓存 - [ ] 添加单元测试 - [ ] 完善API文档 - [ ] Docker容器化 - [ ] 性能优化和监控 ## 许可证 MIT ## 联系方式 如有问题或建议,请联系开发团队。