# 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` — 完整档首页个性化区视觉线框
- 本文件 — 整合实施方案 + 架构补齐 + 路线图 + 待定项