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

基于 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. 启动后端

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，代码/数据基于 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/。