fitness-coach/FITCOACH-OPTIMIZATION-PLAN.md

FITCOACH 系统优化 · 整合实施方案（待确认）

整合自三份调研：PM《优化 PRD》(PRD-FITCOACH优化方案.md)、设计师《动能暗色提案》(FITCOACH-DESIGN-PROPOSAL.md + design-system/design-tokens.json)、架构师技术方案（本文件第 2 节，由团队负责人据代码实测补齐）。 已确认方向（用户 2026-07-22 拍板）：① 先出方案文档、确认后再开发；② 首页个性化两档都要（先轻量后完整）；③ UI 重塑设计语言。 P0 红线：禁止 emoji 当功能图标（统一 Lucide SVG iconfont）、禁止紫粉渐变、禁止硬编码颜色（一律走 Token）。

---

1. 现状诊断（代码实测结论）

问题	证据	影响
首页零个性化	pages/index/index.js loadData() 只拉全局 stats/featured/collections，无 openid 维度；"今天，练点什么？"写死	登录与不登录完全一致，无归属感
emoji 图标系统性违规	首页 🔍✨💪🏋️📋🗂️👤、底部导航 🏠📚📋👤、profile ❤️🗂️⭐📋💪、各空态、占位 🏋️；后端 users.service.ts 默认 avatar=🏃、plans.service.ts 默认 emoji=📋	触发 P0-1 红线，全站廉价感
加载/错误态缺失	首页 loading 是死代码（wxml 未引用）首屏空白；request.js 失败只 toast，网络失败与无数据无区分、无重试	弱网下体验差、无兜底
响应速度	request.js 无 timeout（wx.request 默认不强制超时）；首页 Promise.all 无缓存；底部导航 reLaunch 重置栈→切 tab 重拉	弱网挂起、切 tab 白屏
硬编码颜色散落	13 个 wxss 裸写 #0E1110(8+处)、#E5544B/rgba(229,84,75,…)；app.wxss Token 命名偏金、缺语义色/字号阶梯/字距	改主题要改 N 处
设计令牌基础尚在	app.wxss 已定义 --bg/--surface/--gold/--text/--line/--radius	重塑改一处 + 组件局部即可，不动业务

关键利好：个性化所需接口其实已就绪——planSvc.listMine()→GET /api/plans（按 openid 隔离，已验证 plans.controller.ts:35）、favSvc.listExercises()→GET /api/favorites/exercises（已验证 favorites.controller.ts:26）、auth 登录态。轻量档零后端改动即可上线。

---

2. 架构技术方案（补齐）

2.1 轻量档（P0，纯前端，零后端改动）

• 首页 index.js onLoad：若已登录（wx.getStorageSync('access_token') 存在且有效），并行拉：
  • planSvc.listMine() → 我的计划列表
  • favSvc.listExercises() → 我的收藏动作
  • 今日推荐（前端推导）：取 GET /api/plans/official 分级 + 用户收藏/浏览，按"未练过/匹配目标"排序取 top3（复用推荐页现有推导逻辑，无需新接口）
  • 用户资料：auth.getProfile() 或本地 userInfo
• 渲染：isLogin 为真 → 在 Hero 后插入"为你准备"区（时段问候 + 我的计划卡 + 收藏横滑 + 今日推荐）；否则保留原通用内容 + 轻引导登录。
• 缓存：用 wx.setStorageSync 缓存 listMine/favorites（key 带 openid）；切 tab(onShow) 优先读缓存、后台静默刷新，避免 reLaunch 重拉白屏。
• 工作量：前端 2-3 人日。

2.2 完整档（P1，新增后端数据）

沿用现有 common/store.ts 的 JsonStore 单例模式（已验证：getStore(name) 进程内单例、整体落盘 data-store/<name>.json）。

新集合 checkins（data-store/checkins.json）：

{ id, openid, date(YYYY-MM-DD, openid+date 唯一), planId?, exerciseIds[], durationMin?, completed(bool), createdAt }

users 扩展字段：fitnessGoal(减脂/增肌/塑形/保持健康)、level(beginner/intermediate/advanced)、trainFreq(每周次数)、onboarded、avatar(改 Lucide 图标名/URL，去掉 emoji)。

打卡触发点：plan-detail「完成训练」按钮 / 首页「今日打卡」按钮 → POST /api/checkins。

派生计算（无需单独存储，由 checkins 实时算）：

• streak：按 date 倒序，从今天/昨天起连续有 checkin 的天数
• summary(range=7|30)：训练次数、总时长、动作分布、完成率
• 历史曲线：近 14 日每日 checkin 数/时长 → 前端 SVG 面积图

新增 API（均 @UseGuards(AuthGuard) + CurrentUser 取 openid，沿用 plans/favorites 模式）：

方法	路径	说明
POST	/api/checkins	创建/更新当日打卡
GET	/api/checkins/streak	{ streak, lastCheckinDate }
GET	/api/checkins/summary?range=7|30	{ count, totalDuration, byExercise[], byDay[] }
PATCH	/api/users/me	扩展画像字段

• 工作量：后端 3-4 人日 + 前端 4-5 人日。需新建 checkins.module/controller/service/(entity+dto) + users.service 扩展。

2.3 UI Token 化改造（P0）

• 以 design-system/design-tokens.json 为唯一真源，整体替换 app.wxss 的 page 变量：冷中性底(#0B0F0E/#141A18/#1C2421) + 珊瑚橙 accent(#FF6A3D) + 语义色(success/warn/danger/info) + 字号阶梯(22-72rpx) + 间距尺度(4px 网格) + 圆角(16/24/32) + 阴影(Hairline First) + 动效(150/200/300ms)。
• 13 个页面/组件 wxss：把裸写 #0E1110/#E5544B/大阴影改为引用新 Token。
• 图标落地：编译 Lucide 子集（约 30-40 个图标）为 miniprogram/assets/fonts/fc-icon.ttf，app.wxss @font-face 声明 fc-icon；提供 emoji→Lucide name→codepoint 映射表，全站 <text class="fc-icon"> 替换 emoji 文本节点。
• 风险：主包体积（iconfont ttf <50KB 可控）；个别 wxml 用 emoji 字符作图标需逐个替换；微信支持本地 ttf 自定义字体。

2.4 综合 UX 技术支撑（P0/P1）

• 请求治理：request.js 加 timeout: 8000 + 失败类型区分(网络/业务/无数据) + 重试一次 + 可选缓存层，弱网不再挂起。
• 骨架屏：首页/列表页加 skeleton 占位（token 色块），替代当前首屏空白；接上原 index.wxml 死代码 loading 或换 skeleton。
• 错误重试：request 失败提供"重试"按钮（error 态），替代纯 toast。
• tab 保活：bottom-nav reLaunch 重置栈→改 switchTab + 首页数据缓存 + onShow 静默刷新，切 tab 不白屏。
• 常驻搜索：首页 search-pill 换成 SVG 图标（或 navbar 常驻）。

2.5 技术约束与风险

• JsonStore 单进程单例、整体落盘——打卡高频写 flush 阻塞；demo 量级 OK，生产前置足够。
• 主包 2MB 限制：iconfont ttf <50KB 可控；不打包 CJK 字体（用系统字体，已确认）。
• 图标库：锁定 Lucide（MIT），与设计师提案一致 ✅；尺寸 16/20/24rpx；编译为 iconfont 子集。

---

3. 实施路线图（优先级）

优先级	项	档位	后端	前端	依赖
P0	emoji→Lucide SVG 图标替换（全站 18+ 处 + 后端默认 avatar/emoji）	UI	小	中	无
P0	Design Token 重塑（Kinetic Dark，app.wxss + 13 wxss）	UI	无	中	无
P0	首页轻量个性化（问候+我的计划+收藏+今日推荐）	个性化·轻	无	2-3人日	现有 API
P0	骨架屏 + 错误重试 + 请求 timeout	UX	无	2-3人日	无
P1	完整个性化后端（checkins store + 3 接口 + users 扩展）	个性化·全	3-4人日	—	轻量档先上
P1	首页完整档区块（进度环+连续天数+历史曲线）	个性化·全	—	4-5人日	后端接口
P1	导航重构 + 常驻搜索 + tab 保活 + 缓存	UX	无	中	请求治理
P2	下拉刷新 / 长按手势 / 进入动画	UX	无	小	无

MVP 切割：P0 四项先上（验证假设、零风险、零后端）→ P1 完整档跟进（需打卡数据沉淀）→ P2 打磨。 上线顺序：UI 重塑 + 轻量个性化 + 骨架屏 同批（都在前端，互不阻塞）；完整档独立一批（需后端发布）。

---

4. 已锁定决策（2026-07-22 用户确认）

1. 强调色 accent = Volt 荧光绿 #B6F24E（用户选，非设计师默认珊瑚橙）。设计 Token 中 accent 系列全部替换为该绿：accent:#B6F24E / accent-hover:#C7F56E / accent-active:#9EDB3A / accent-on:#0E1A05(深绿字，对比>7:1) / accent-soft:rgba(182,242,78,.12) / accent_ring:rgba(182,242,78,.38) / glow:0 8rpx 24rpx rgba(182,242,78,.28)。每屏≤2处。
2. UGC emoji 选择器 → 现在就迁 Lucide 运动子集图标选择器（dumbbell/run/bike/heart/flame/target/yoga/medal/trophy 等），不保留 emoji 入口。plan-edit/profile 的计划图标与用户头像图标均走 Lucide。

---

5. Out-of-Scope（本期不做）

社交/社区、商城电商、课程直播跟练、饮食营养、硬件联动、i18n、SQL 迁移、生成式 AI 文案、付费会员。

---

附：交付物索引

• PRD-FITCOACH优化方案.md — PM 优化 PRD（现状/竞品/三块方案/RICE/验收标准）
• FITCOACH-DESIGN-PROPOSAL.md — 设计师动能暗色提案（审计/Token/图标/视觉草案）
• design-system/design-tokens.json — 机读 Design Token 草案（唯一真源）
• home-personalization-mockup.svg — 完整档首页个性化区视觉线框
• 本文件 — 整合实施方案 + 架构补齐 + 路线图 + 待定项