# FITCOACH · 健身动作推荐小程序系统

基于 [hasaneyldrm/exercises-dataset](https://github.com/hasaneyldrm/exercises-dataset)（1,324 个健身动作，含中文说明）构建的**健身动作推荐小程序**全栈系统。

- **后端**：NestJS 服务，统一托管全部动作数据，作为小程序的数据代理层（REST API）。
- **前端**：微信小程序，包含首页、多维分类浏览、器械/肌肉群筛选、目标肌群智能推荐、动作详情、智能训练组合、搜索等完整功能。

---

## 系统架构

```
┌─────────────────────┐         HTTPS / wx.request          ┌──────────────────────────┐
│   微信小程序 (MP)     │  ───────────────────────────────▶  │   NestJS 后端 (代理层)      │
│  pages / components  │  ◀───────────────────────────────  │  - 加载并托管数据集         │
│  utils/request.js    │     JSON (筛选/推荐/分类/组合)        │  - 多维筛选 + 智能推荐       │
└─────────────────────┘                                      │  - 静态媒体 /media          │
                                                              └──────────────────────────┘
                                                                     │ 读取
                                                                     ▼
                                                          exercises-dataset (exercises.json)
```

> 所有锻炼动作数据资源**统一存储在后端**，小程序只通过后端 API 获取数据，不直接接触数据源。

---

## 目录结构

```
fitness-coach/
├── backend/                 # NestJS 后端
│   ├── src/exercises/       # 动作模块（service/controller/dto/data）
│   │   ├── data/
│   │   │   ├── exercises.json   # 数据集（构建时由脚本下载，见下）
│   │   │   ├── labels.ts        # 中英文标签映射
│   │   │   └── collections.ts   # 智能训练组合定义
│   │   └── utils/normalize.ts   # 原始数据 → 结构化中文字段
│   ├── scripts/             # ensure-data.mjs(下载数据集) / sync-media.mjs(下载媒体) / analyze.mjs
│   └── README.md
└── miniprogram/             # 微信小程序前端
    ├── pages/               # index / category / recommend / detail / collection / collection-detail / search
    ├── components/          # exercise-card / section-header / chip / navbar / bottom-nav
    ├── services/exercise.js # 接口映射
    ├── utils/request.js     # 统一请求封装
    └── README.md
```

---

## 快速开始

### 1. 启动后端
```bash
cd backend
npm install
npm run build          # prebuild 会自动下载 exercises.json 到 src/exercises/data/
npm run start:prod     # 或 npm run start:dev 开发模式
# 服务默认 http://localhost:3000
# 可选：下载动作图片/动画到 backend/media/（供小程序显示 GIF）
npm run sync:media
```

### 2. 配置并预览小程序
1. 用**微信开发者工具**导入 `miniprogram/` 目录（AppID 可用测试号）。
2. 打开 `miniprogram/config.js`，将 `BASE_URL` 改为后端可达地址：
   - 本地调试：同局域网用电脑 IP，如 `http://192.168.1.10:3000`
   - 真机/发布：**必须**改为已配置 request 合法域名的 HTTPS 地址
3. 编译预览。首页、分类、智能推荐、详情、训练组合、搜索均可使用。

> 小程序要求所有网络请求域名在 **小程序后台 → 开发管理 → 开发设置 → 服务器域名** 中配置（request 合法域名）。本地开发者工具勾选「不校验合法域名」可临时跳过。

---

## 核心功能

| 功能 | 说明 |
|------|------|
| 首页 | 渐变 Hero + 智能推荐 CTA + 快捷入口 + 精选动作轮播 + 训练组合 + 按部位/器械浏览 |
| 多维分类 | 按**身体部位 / 器械 / 目标肌群 / 肌肉群 / 锻炼类型** 浏览 |
| 器械筛选 | 选可用器械，快速过滤适合的动作 |
| 肌肉群筛选 | 按目标肌肉部位浏览相关动作 |
| **智能推荐** | 选择目标肌群（可选器械），按相关性评分推荐动作并给出理由 |
| 训练组合 | 推日/拉日/腿日/核心/上肢/全身/居家无器械/有氧 等主题动作包 |
| 动作详情 | GIF 演示 + 中文分步说明 + 主要/协同肌群 + 相关推荐 + 分享 |
| 搜索 | 按名称/部位/器械/目标模糊搜索 |

---

## 后端 API 速览

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/exercises` | 列表（分页 + bodyPart/equipment/target/type/secondary/q 筛选 + sort） |
| GET | `/api/exercises/:id` | 动作详情（含中文步骤） |
| GET | `/api/categories/body-parts` | 部位分类（含数量） |
| GET | `/api/categories/equipment` | 器械分类 |
| GET | `/api/categories/targets` | 目标肌群分类（含所属部位，用于分组） |
| GET | `/api/categories/muscle-groups` | 肌肉群分类 |
| GET | `/api/categories/types` | 锻炼类型（力量/有氧/柔韧） |
| GET | `/api/recommend?target=&equipment=&limit=` | 目标肌群智能推荐 |
| GET | `/api/collections` | 训练组合列表 |
| GET | `/api/collections/:slug/exercises` | 某组合下的动作 |
| GET | `/api/search?q=` | 搜索 |
| GET | `/api/stats` | 统计概览 |

详见 `backend/README.md` 与 `miniprogram/README.md`。

---

## 数据来源与许可

- 数据集：[hasaneyldrm/exercises-dataset](https://github.com/hasaneyldrm/exercises-dataset)，代码/数据基于 MIT 许可。
- 动作图片与动画 GIF 版权归 **© Gym visual (https://gymvisual.com/)**，需遵守其媒体使用条款；通过 `npm run sync:media` 同步到后端 `media/` 目录后由 `/media` 静态提供。

---

## 备注

- 后端默认在内存中加载数据集（启动快、查询快）；如需持久化可替换为 TypeORM + 数据库，接口层不变。
- 数据集较大（约 17MB），首次 `npm run build` 会自动从 GitHub 下载；也可手动放置 `exercises.json` 到 `backend/src/exercises/data/`。