zrd-nb666/campus_health_app/backend

数智健调系统 - 后端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. 安装依赖

cd campus_health_app/backend
npm install

3. 配置环境变量

复制环境变量示例文件并修改配置：

cp .env.example .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. 初始化数据库

# 创建数据库
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. 启动开发服务器

npm run dev

服务器将在 http://localhost:3000 启动。

6. 构建生产版本

# 编译TypeScript
npm run build

# 启动生产服务器
npm start

API文档

基础信息

• Base URL: http://localhost:3000/api
• 认证方式: 请求头 x-user-id（临时方案）
• 响应格式: JSON

通用响应格式

成功响应：

{
  "success": true,
  "data": { ... },
  "message": "操作成功"
}

错误响应：

{
  "success": false,
  "message": "错误信息",
  "errors": ["详细错误1", "详细错误2"]
}

API端点

1. 体重记录相关

获取体重记录列表

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
  }
}

添加体重记录

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": "体重记录添加成功"
}

更新体重记录

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": "更新成功"
}

删除体重记录

DELETE /api/weight/records/:id
Headers:
  x-user-id: test-user-001

Response 200:
{
  "success": true,
  "message": "删除成功"
}

2. 目标管理相关

获取当前目标

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",
    ...
  }
}

设置目标

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": "目标设置成功"
}

更新目标

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. 标签相关

获取标签列表

GET /api/weight/tags
Headers:
  x-user-id: test-user-001

Response 200:
{
  "success": true,
  "data": [
    {
      "id": "...",
      "name": "开始运动",
      "type": "system",
      "color": "#3b82f6"
    },
    ...
  ]
}

创建自定义标签

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. 统计分析

获取统计数据

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测试

# 健康检查
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. 编译并启动服务

   npm run build
   npm start
   

使用PM2管理

# 安装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/ 添加路由

代码规范

# 运行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

联系方式

如有问题或建议，请联系开发团队。