first commit

TUICallKit-Vue3/training/static/README.md

@@ -0,0 +1,215 @@
+# 训练模块静态资源
+
+本目录用于存放"练一练"功能的所有音频素材。
+
+## 目录结构
+
+```
+training/static/
+├── audio/                      # 当前为空 —— 节拍器音频已全部迁移到 COS CDN
+├── voice/                      # (规划中) TTS 语音教练
+│   ├── numbers/                  数字报数 1~30
+│   └── prompts/                  开始/休息/再来 等口令
+├── bgm/                        # (规划中) 训练/休息背景乐
+└── footprint.svg               # 脚印图标(早期方案残留,可保留作为备用素材)
+```
+
+> 节拍器音频已完全走 CDN（`gz-1349751149.cos.ap-guangzhou.myqcloud.com`），减少小程序包体积约 210 KB。`useMetronomeBg.ts` / `useMetronome.ts` 中的 URL 即源信息，更换音色只需改 hook 里的常量。
+
+## 准备步骤
+
+### 1. 语音素材（小米 MiMo TTS 自动生成）
+
+需要 Node 18+（用内置 `fetch`）。先准备小米 MiMo API Key：
+
+- 文档: https://platform.xiaomimimo.com/
+- API Key 形如 `sk-xxxxxxxx`
+
+```bash
+export MIMO_API_KEY=sk-your-key-here
+
+cd uniapp
+node scripts/generate-voice.mjs
+```
+
+会自动调用 `mimo-v2.5-tts` 模型生成 39 个 mp3（30 个数字 + 9 个口令）到 `voice/` 目录。
+
+**可选参数**：
+
+```bash
+# 换音色（默认 冰糖；可选：冰糖/茉莉/苏打/白桦/Mia/Chloe/Milo/Dean）
+node scripts/generate-voice.mjs --voice 茉莉
+
+# 换格式（默认 mp3，需要跟 hooks/useVoiceCoach.ts 里的 .mp3 后缀对应）
+node scripts/generate-voice.mjs --format wav
+
+# 强制重新生成（默认存在则跳过）
+node scripts/generate-voice.mjs --force
+```
+
+**音色推荐**（中文女声更适合健身教练）：
+- `冰糖`：温柔甜美，亲和力强（默认）
+- `茉莉`：清爽利落，有"运动博主"感
+- `苏打`：年轻男声，有力量感
+- `白桦`：成熟男声，沉稳
+
+### 2. 节拍器 click / 循环音轨
+
+**全部托管在腾讯云 COS（2026-05-26 上传）**，本地不再保留：
+
+| 用途 | 文件 | 大小 | 引擎 |
+|---|---|---|---|
+| 单拍 click（基础） | `click.mp3` | 3.4 KB | InnerAudio |
+| 单拍 click（木鱼，推荐） | `click-wood.mp3` | 4.6 KB | InnerAudio (custom 模式) |
+| 循环音轨 慢走 80 BPM | `loop_80bpm_2.mp3` | 71 KB | BgAudio (preset) |
+| 循环音轨 健走 110 BPM | `loop_110bpm_2.mp3` | 65 KB | BgAudio (preset) |
+| 循环音轨 快走 130 BPM | `loop_130bpm_2.mp3` | 66 KB | BgAudio (preset) |
+
+> 微信 `BackgroundAudioManager.src` 只接受 https URL,不支持包内资源,所以必须走 CDN。
+> COS 域名已加入小程序后台 `downloadFile 合法域名`,跑步视频也走同一域名。
+
+更换音色：去 [pixabay.com/sound-effects](https://pixabay.com/sound-effects/) 找新素材 → 上传到 COS → 在 `useMetronomeBg.ts` / `useMetronome.ts` 里替换 URL 即可。
+
+### 3. 背景音乐
+
+每首 30 秒~2 分钟即可（loop 后听不出接缝）。
+
+推荐来源（免费可商用）：
+- [pixabay.com/music](https://pixabay.com/music) 搜 "calm" / "meditation" / "lofi"
+- [freemusicarchive.org](https://freemusicarchive.org)
+- [bensound.com](https://bensound.com)（含署名）
+
+文件大小建议 < 1MB（mp3 128kbps 单声道即可）。
+
+## 在代码里被引用的位置
+
+- `training/hooks/useMetronome.ts` → `DEFAULT_CLICK_SRC` (CDN: click.mp3)
+- `training/hooks/useMetronomeBg.ts` → `LOOP_PRESETS[*].src` (CDN: loop_*.mp3)
+- `training/pages/metronome.vue` → `CLICK_WOOD_URL` (CDN: click-wood.mp3, custom 模式)
+- `training/hooks/useVoiceCoach.ts` → `voice/numbers/*.mp3`、`voice/prompts/*.mp3` (规划中)
+- `training/hooks/useTrainingBgm.ts` → `bgm/*.mp3` (规划中)
+
+如需修改路径，修改对应 hook 文件里的常量即可。
+
+## 注意事项
+
+- 微信小程序对单个文件大小有 10MB 上限，本目录所有文件加起来建议控制在 5MB 以内。
+- 小程序整包大小限制（主包 2MB / 总包 20MB），如果资源较大建议放 CDN 而非本地 static。
+  - 把 `useVoiceCoach.ts` 里的 `VOICE_BASE` 改成 CDN URL 即可。
+
+---
+
+## 后台/锁屏播放设计备忘（未来健身模块用）
+
+> 节拍器目前用 `InnerAudioContext` + `requiredBackgroundModes:["audio"]` 已能覆盖 5~10 分钟健走场景。
+> 真要做长时间训练 BGM、锁屏控制条等高级能力，参考下面的 `BackgroundAudioManager` 方案。
+
+### 引擎选择对照表
+
+健身模块的音频天然分两类，配两套引擎不冲突：
+
+| 音频类型 | 时长 | 推荐引擎 | 理由 |
+|---|---|---|---|
+| 训练/休息 BGM | 30s~2min 循环 | **BackgroundAudioManager** | 长流、需要后台/锁屏不停 |
+| 语音教练（"开始/休息/再来"） | 1~3s 单句 | InnerAudioContext | 短促，前台用即可 |
+| 报数（1, 2, 3...） | 0.5~1s | InnerAudioContext + 池子 | 高频短促 |
+| 节拍器 click | 50~150ms | InnerAudioContext + 池子 | 极短，BgAudio 不接受 |
+
+**关键约束：BgAudio 是全局单例，一次只能播 1 个音频**。所以让它专门播 BGM 这类"长流"，其他短音用 InnerAudio 配合，互不打架。
+
+### BackgroundAudioManager 限制清单（踩坑预警）
+
+1. **全局单例**：整个小程序同一时刻只能播一个，多场景要协调切换
+2. **音频时长 ≥ 1 秒**：太短的 click 会被微信判定异常忽略
+3. **必填 metadata**：`title` / `coverImgUrl` / `singer` / `epname` / `webUrl` 缺一会报错
+4. **切 src 有延迟**：200~500ms 初始化抖动，频繁切换会卡顿
+5. **必须声明 `requiredBackgroundModes:["audio"]`** 才能后台播放
+6. **iOS 锁屏豁免**：声明后能锁屏继续播，无 5 分钟时长限制（vs InnerAudio 的 5min）
+7. **会显示系统控制条**：锁屏/通知栏出现带封面+暂停按钮的控制条
+
+### 推荐架构（健身模块上线时）
+
+```
+training/hooks/
+├── useTrainingBgm.ts    → BackgroundAudioManager (后台/锁屏继续放音乐)
+├── useVoiceCoach.ts     → InnerAudioContext     (语音指导,前台用)
+└── useMetronome.ts      → InnerAudioContext     (节拍器,池子方案,保持现状)
+```
+
+页面 `pages.json` 声明：
+
+```json
+{
+    "path": "pages/index",
+    "style": {
+        "navigationBarTitleText": "练一练",
+        "requiredBackgroundModes": ["audio"]
+    }
+}
+```
+
+锁屏会显示 BGM 控制条，老人能直接在锁屏点暂停。训练页面通过 `bgm.onPause()` 监听同步暂停训练，体验连贯。
+
+### 必备资产清单
+
+到时候要准备的文件：
+
+- **BGM 2 首**：`bgm/train-light.mp3`（训练）、`bgm/rest-meditation.mp3`（休息）
+  - 每个 30s~1min，128kbps 单声道，30~80KB
+  - 推荐来源：[pixabay.com/music](https://pixabay.com/music) 搜 "calm" / "meditation" / "lofi"
+- **锁屏封面**：`audio/cover.jpg` 200×200
+  - 简洁绿色背景 + 训练 emoji 即可
+
+### BackgroundAudioManager API 速查
+
+```ts
+const bgm = uni.getBackgroundAudioManager()
+
+/* 必填 metadata,缺一会报错 */
+bgm.title       = '健走训练中'
+bgm.coverImgUrl = '/training/static/audio/cover.jpg'
+bgm.epname      = '甄养堂'
+bgm.singer      = '健走节拍'
+bgm.webUrl      = ''   // 必填,空字符串可
+
+/* src 一旦赋值会自动播放 */
+bgm.src = '/training/static/audio/bgm/train-light.mp3'
+
+/* 控制 */
+bgm.pause()    // 暂停 (锁屏控制条仍在)
+bgm.play()     // 继续
+bgm.stop()     // 真停 + 隐藏控制条
+bgm.seek(30)   // 跳到 30s
+
+/* 事件监听 — 用户从锁屏点暂停时会触发 */
+bgm.onPause(() => { /* 同步训练 UI 状态 */ })
+bgm.onPlay(()  => {})
+bgm.onStop(()  => {})
+bgm.onEnded(() => { /* 不 loop 时触发,可手动接下一首 */ })
+bgm.onError((err) => { console.error(err) })
+```
+
+### 切换不同场景音乐的模式
+
+```ts
+function switchBgm(scene: 'training' | 'resting' | 'none') {
+    if (scene === 'none') {
+        bgm.stop()
+        return
+    }
+    bgm.title = scene === 'training' ? '健走训练中' : '休息恢复中'
+    bgm.src = scene === 'training'
+        ? '/training/static/audio/bgm/train-light.mp3'
+        : '/training/static/audio/bgm/rest-meditation.mp3'
+    /* 注:setSrc 会自动播放,有 200~500ms 切换延迟 */
+}
+```
+
+### 节拍器要不要也升级到 BgAudio?
+
+**目前不需要**。节拍器升级 BgAudio 的代价：
+- 需要预合成 3 个档位的循环 mp3（80/110/130 BPM × 2 拍）
+- 必须砍掉右下角微调按钮（预合成 mp3 改不了 BPM）
+- 切档位有 200~500ms 卡顿
+
+如果未来发现"健走 30 分钟以上锁屏会停"才考虑改。当前 5~10 分钟场景 InnerAudio + `requiredBackgroundModes` 够用。

TUICallKit-Vue3/training/static/footprint.svg

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 150">
+  <g fill="#e2e8f0" fill-opacity="0.92">
+    <path d="M 50,30 C 38,30 28,32 24,40 C 19,50 18,60 22,70 C 26,82 26,92 28,102 C 30,122 40,140 50,140 C 60,140 70,122 72,102 C 74,92 74,82 78,70 C 82,60 81,50 76,40 C 72,32 62,30 50,30 Z"/>
+    <ellipse cx="30" cy="20" rx="6.5" ry="8" transform="rotate(-18 30 20)"/>
+    <ellipse cx="43" cy="11" rx="5" ry="6.8" transform="rotate(-6 43 11)"/>
+    <ellipse cx="55" cy="9" rx="4.5" ry="6.2" transform="rotate(4 55 9)"/>
+    <ellipse cx="66" cy="13" rx="4" ry="5.5" transform="rotate(13 66 13)"/>
+    <ellipse cx="76" cy="20" rx="3.5" ry="5" transform="rotate(22 76 20)"/>
+  </g>
+</svg>

TUICallKit-Vue3/training/static/grip-ring-audio-shopping-list.md

@@ -0,0 +1,276 @@
+# 握力环训练音效采集清单
+
+> 更新日期: 2026-05-28
+> 用途: 为握力环训练页面添加完整音效体系
+
+---
+
+## 📋 总体规划
+
+| 类型 | 数量 | 单文件大小 | 总大小预算 | 优先级 |
+|------|------|-----------|-----------|--------|
+| 节拍音效 | 1-3 个音色 | 5-10 KB | < 30 KB | P0 |
+| 捏碎音效 | 4 个 | 20-50 KB | < 200 KB | P0 |
+| 背景音乐 | 1-2 首 | 200-500 KB | < 1 MB | P1 |
+| 语音鼓励 | 4-8 句 | 10-30 KB | < 200 KB | P1 |
+
+**总计预算**: < 1.5 MB(都放 CDN,不影响小程序包体积)
+
+---
+
+## 🥁 一、节拍音效 (P0 - 必需)
+
+### 用途
+训练时按 BPM 节奏播放,引导用户握紧/松开。
+
+### 推荐音色 (任选 1-3 个)
+
+| 音色 | 推荐度 | 描述 | Pixabay 搜索词 |
+|------|--------|------|---------------|
+| 木鱼 | ⭐⭐⭐⭐⭐ | 温暖、东方意境,适合养生主题 | `wood block`, `wooden tap`, `muyu` |
+| 心跳 | ⭐⭐⭐⭐ | 有运动感,代入感强 | `heart beat`, `heartbeat single` |
+| 轻柔敲击 | ⭐⭐⭐⭐ | 不刺耳,适合长时间训练 | `soft tap`, `gentle knock` |
+| 竹片声 | ⭐⭐⭐ | 清脆,有节奏感 | `bamboo tap`, `bamboo click` |
+| 鼓点 | ⭐⭐⭐ | 有力量感,适合"重度"档位 | `kick drum soft`, `tom drum tap` |
+
+### 技术要求
+- **格式**: mp3
+- **时长**: 50-150ms (不能太长,会重叠)
+- **采样率**: 22050Hz 或 44100Hz
+- **声道**: 单声道
+- **大小**: < 10 KB
+
+### 命名规范
+```
+grip-tick-wood.mp3      # 木鱼
+grip-tick-heart.mp3     # 心跳
+grip-tick-soft.mp3      # 轻柔
+grip-tick-bamboo.mp3    # 竹片
+```
+
+---
+
+## 💥 二、捏碎音效 (P0 - 必需)
+
+### 用途
+达成奖励里程碑时播放,与粒子特效同步。
+
+### 音效清单
+
+| 奖励 | 触发次数 | Pixabay 搜索词 | 时长 | 备注 |
+|------|---------|---------------|------|------|
+| 🥚 鸡蛋 | 8-12 | `egg crack`, `eggshell break`, `crack sound` | 0.5-1s | 清脆短促 |
+| 🥜 核桃 | 15-20 | `nut crack`, `walnut break`, `wood snap` | 0.5-1s | 木质爆裂感 |
+| 🥫 易拉罐 | 25-30 | `can crush`, `aluminum crush`, `metal crunch` | 1-2s | 金属挤压 |
+| 🎈 气球 | 40-50 | `balloon pop`, `pop burst`, `balloon explosion` | 0.3-0.5s | 短促爆裂 |
+
+### 技术要求
+- **格式**: mp3
+- **时长**: 0.3-2s
+- **大小**: < 50 KB
+- **音量**: 适中(避免突然吓到用户)
+
+### 命名规范
+```
+crush-egg.mp3
+crush-walnut.mp3
+crush-can.mp3
+crush-balloon.mp3
+```
+
+### 试听建议
+下载前一定要试听,优先选择:
+- ✅ 干净,无杂音
+- ✅ 中等音量(峰值不爆音)
+- ✅ 短促有力(不拖沓)
+- ❌ 避免: 太长、太尖锐、有人声
+
+---
+
+## 🎵 三、背景音乐 BGM (P1 - 推荐)
+
+### 用途
+训练时持续播放,营造轻松氛围,缓解握力训练的枯燥感。
+
+### 风格推荐
+
+| 风格 | 描述 | Pixabay 搜索词 | 适合人群 |
+|------|------|---------------|---------|
+| **Lo-Fi** | 慵懒电子,流行选择 | `lofi calm`, `lofi study`, `lofi chill` | 年轻人 |
+| **冥想轻音乐** | 钢琴 + 自然音,放松 | `meditation`, `calm piano`, `relaxing` | 中老年 |
+| **轻爵士** | 优雅放松,有质感 | `light jazz`, `cafe jazz`, `bossa nova` | 通用 |
+| **自然环境音** | 鸟叫/流水/雨声 | `nature ambient`, `forest sounds`, `rain bgm` | 喜欢自然的用户 |
+| **东方禅意** | 古筝/笛子,养生 | `chinese zen`, `oriental calm`, `guqin` | 养生主题契合 |
+
+### 推荐场景搭配
+- **轻度档位 (60 BPM)**: 冥想轻音乐 (节奏舒缓)
+- **中度档位 (80 BPM)**: 轻爵士 / Lo-Fi (适中)
+- **重度档位 (100 BPM)**: 轻快电子 / 健身流行
+
+### 技术要求
+- **格式**: mp3
+- **时长**: 30s - 2min (循环播放)
+- **比特率**: 128 kbps (单声道 64 kbps 也可)
+- **大小**: < 500 KB
+- **循环点**: 选择起止点接近的片段,避免明显接缝
+
+### 命名规范
+```
+bgm-grip-light.mp3       # 轻度档位 BGM
+bgm-grip-medium.mp3      # 中度档位 BGM (可选)
+bgm-grip-heavy.mp3       # 重度档位 BGM (可选)
+```
+
+或简化:
+```
+bgm-grip-default.mp3     # 默认 BGM (所有档位通用)
+```
+
+---
+
+## 🎙️ 四、语音鼓励 (P1 - 推荐)
+
+### 用途
+达成奖励时播放鼓励语音,增强成就感。
+
+### 两种方案
+
+#### 方案 A: 小米 MiMo TTS 自动生成 (推荐)
+
+项目已有 `useVoiceCoach.ts` + `generate-voice.mjs` 脚本支持。
+
+**操作步骤**:
+1. 申请小米 MiMo API Key: https://platform.xiaomimimo.com/
+2. 配置环境变量: `export MIMO_API_KEY=sk-xxx`
+3. 在 `generate-voice.mjs` 添加握力环话术
+4. 运行脚本自动生成
+
+**话术清单**:
+```javascript
+const gripPrompts = [
+    { id: 'grip-egg', text: '握力不错！' },
+    { id: 'grip-walnut', text: '力量惊人！' },
+    { id: 'grip-can', text: '太强了！' },
+    { id: 'grip-balloon', text: '完美！继续保持！' },
+    { id: 'grip-start', text: '开始训练！' },
+    { id: 'grip-pause', text: '休息一下！' },
+    { id: 'grip-encourage-1', text: '加油，再来！' },
+    { id: 'grip-encourage-2', text: '坚持住！' },
+]
+```
+
+**音色推荐**: `茉莉` (清爽利落,有"运动博主"感)
+
+#### 方案 B: 手工录制
+
+如果不想用 TTS,可以自己录制(质感更好,但费时):
+- 工具: 手机录音 / Audacity
+- 环境: 安静的房间,距离麦克风 15-30cm
+- 后期: 去噪 + 标准化音量
+
+---
+
+## 🛠️ 五、采集工具推荐
+
+### 在线裁剪
+- [audiotrimmer.com](https://audiotrimmer.com) - 简单的 mp3 裁剪
+- [mp3cut.net](https://mp3cut.net) - 功能更全
+
+### 桌面工具(免费)
+- **Audacity** (Mac/Windows/Linux) - 专业级,可以剪辑、降噪、标准化
+- **Logic Pro** (Mac, 付费) - 更专业的音频处理
+
+### 音量标准化
+统一音量(避免有的太响有的太轻):
+```bash
+# 使用 ffmpeg (Mac: brew install ffmpeg)
+ffmpeg -i input.mp3 -af "loudnorm=I=-16:LRA=11:TP=-1.5" output.mp3
+```
+
+或在 Audacity 里: Effect → Normalize (峰值 -3dB)
+
+---
+
+## ☁️ 六、上传到 CDN
+
+### 项目使用的 COS 信息
+- **域名**: `gz-1349751149.cos.ap-guangzhou.myqcloud.com`
+- **目录建议**: `uploads/training/grip-ring/`
+
+### 上传途径
+1. **腾讯云控制台**: https://console.cloud.tencent.com/cos
+2. **管理后台** (如果项目有上传入口)
+3. **找团队 COS 管理员上传**
+
+### 上传后获得的 URL 格式
+```
+https://gz-1349751149.cos.ap-guangzhou.myqcloud.com/uploads/training/grip-ring/crush-egg.mp3
+```
+
+---
+
+## 📝 七、最终采集清单 (一次性收齐)
+
+### 最小可行版本 (MVP) - 4 个文件
+```
+☐ grip-tick-wood.mp3       # 节拍音 - 木鱼
+☐ crush-egg.mp3            # 鸡蛋
+☐ crush-walnut.mp3         # 核桃
+☐ crush-can.mp3            # 易拉罐
+☐ crush-balloon.mp3        # 气球
+```
+
+### 完整版本 - 10 个文件
+```
+节拍音 (3 选 1 或全部):
+☐ grip-tick-wood.mp3
+☐ grip-tick-heart.mp3
+☐ grip-tick-soft.mp3
+
+捏碎音效 (必需 4 个):
+☐ crush-egg.mp3
+☐ crush-walnut.mp3
+☐ crush-can.mp3
+☐ crush-balloon.mp3
+
+BGM (1-3 首):
+☐ bgm-grip-default.mp3
+☐ bgm-grip-meditation.mp3 (可选)
+☐ bgm-grip-lofi.mp3 (可选)
+
+语音鼓励 (TTS 自动生成,8 个):
+☐ grip-egg.mp3
+☐ grip-walnut.mp3
+☐ grip-can.mp3
+☐ grip-balloon.mp3
+☐ grip-start.mp3
+☐ grip-pause.mp3
+☐ grip-encourage-1.mp3
+☐ grip-encourage-2.mp3
+```
+
+---
+
+## ✅ 八、采集完成后
+
+把所有 URL 整理给我,我会:
+1. 更新 `grip-ring.vue` 中的 REWARDS 配置 (替换捏碎音效 URL)
+2. 创建/更新 `useMetronome.ts` 的音色配置 (支持切换节拍音色)
+3. 在 `grip-ring.vue` 集成 `useTrainingBgm` (添加 BGM)
+4. 在 `grip-ring.vue` 集成 `useVoiceCoach` (添加语音鼓励)
+5. 在 UI 上添加音色/BGM 切换选项 (可选)
+
+预计代码改动: 50-100 行,1-2 小时工作量。
+
+---
+
+## 📚 参考链接
+
+- [Pixabay 音效](https://pixabay.com/sound-effects/) - 免费可商用
+- [Pixabay 音乐](https://pixabay.com/music/) - 免费可商用
+- [Freesound](https://freesound.org) - 大量音效,部分需署名
+- [Mixkit](https://mixkit.co/free-sound-effects/) - 免费音效库
+- [Bensound](https://bensound.com) - 免费音乐(需署名)
+- [Free Music Archive](https://freemusicarchive.org) - 免费音乐
+
+**版权提示**: 务必确认音效/音乐是"免费商用"(Public Domain 或 CC0),避免侵权风险。