fitness-coach/OVERVIEW.md

FITCOACH 健身动作推荐小程序系统 — 交付总览

基于 GitHub hasaneyldrm/exercises-dataset（1324 条动作，含中英文动作说明与分步指引）构建的完整体育健身小程序系统，包含 NestJS 后端代理/数据层 + 微信小程序前端。

系统架构

fitness-coach/
├── backend/          NestJS 10 后端（唯一数据源 + API 代理层）
│   ├── src/exercises/  查询 / 多维筛选 / 智能推荐 / 官方训练组合（含 level 分级）
│   ├── src/common/    store(文件持久化) / token / auth.guard / current-user
│   ├── src/auth users favorites plans   用户体系四模块
│   ├── data/store/   运行时用户数据（users / favorites / plans *.json）
│   └── scripts/   ensure-data / copy-data / sync-media
└── miniprogram/     微信小程序前端（深色金质「高端大气」设计）
    ├── pages/   index / recommend / category / detail / collection / collection-detail
    │            / search / profile(我的) / favorites(收藏动作) / my-plans(我的计划)
    │            / plan-edit / plan-detail / plan-favorites(收藏计划)
    ├── components/  exercise-card / chip / navbar / bottom-nav / section-header / level-tag / avatar / plan-card
    ├── services/  exercise / user / favorite / plan
    └── utils/  request(Bearer+401自动重登) / auth(登录态) / format

核心功能实现

需求	实现
动作分类体系（多维）	5 个分类元数据接口：部位(10) / 器械(28) / 目标肌肉(19) / 肌群 / 类型(力量·有氧·柔韧)
按器械筛选	GET /api/exercises?equipment=dumbbell + 前端器械 chip 筛选
按肌肉群筛选	GET /api/exercises?bodyPart=chest + ?target=biceps
核心推荐	GET /api/recommend?target=biceps&equipment=barbell — 评分排序（主训+100 / 协同+40 / 器械匹配+30）+ 中文推荐理由
发散功能	8 个智能训练组合 + 7 个按水平分级的官方推荐计划（新手七天/新手燃脂/进阶增肌/进阶力量/高级竞技/舒展放松/女子塑形）、搜索、统计、按类型筛选
优雅首页	渐变 hero + 问候 + 智能推荐 CTA + 2×3 快捷入口 + 精选动作轮播 + 官方计划分级入口 + 按部位浏览 + 热门器械
用户体系	微信登录（开发降级模式）+ 个人中心 + 收藏动作 + 我的计划（组建/编辑/导入官方计划）+ 收藏官方计划，数据文件持久化
数据来源	数据集导入后端内存，统一经 NestJS 对外提供（含 GIF 演示，CDN 直链）

已验证（curl 全通过）

• 列表分页与多维筛选、分类元数据（target 含 bodyPart 分组）、详情（含中文步骤）
• 推荐逻辑修复后 total 一致（装备仅作加分排序，不再虚增无关动作）
• 用户体系：登录（开发降级返回虚拟 openid）→ 个人资料读写 → 动作收藏增删查与状态 → 我的计划 CRUD / 增删动作 / 从官方计划一键导入 → 官方计划按 4 级分组下发（共 15 个计划）→ 收藏官方计划；401 未登录拦截、用户数据隔离均正确
• 错误码：坏 id → 404；recommend 缺 target → 400；未登录访问受保护接口 → 401
• 前端 30 个 JS 文件 node --check 语法全部通过；所有页面 usingComponents 与实际使用的组件一致

运行方式

# 后端
cd fitness-coach/backend
npm install            # 弱网下用 --prefer-offline（本机有 3.1G npm 缓存，秒装）
npm run build
PORT=3000 node dist/main.js        # http://localhost:3000

# 小程序
微信开发者工具「导入项目」选择 fitness-coach/miniprogram/
（appid 已设为 touristappid，urlCheck:false，免账号即可预览）

生产发布需：① config.js 的 BASE_URL 改为 HTTPS 域名；② 在小程序后台配置 request/downloadFile 合法域名（媒体默认用 cdn.jsdelivr.net，建议换自有 CDN）。

备注

• 媒体（GIF/图）默认经 jsDelivr CDN 直链加载，无需本地下载；亦可改 MEDIA_BASE_URL 指向自有 CDN 后执行 npm run sync:media 同步到 backend/media/。
• 单文件 JSON 数据集在内存中查询，接口响应快；小程序侧仅取轻量 summary，保证首屏性能。