微信小程序 · 吉他练习节拍器

用于木吉他和电吉他练习。已实现普通节拍器和预设鼓伴奏，采用“前台生成本地 WAV → 微信后台播放器”的播放方式，无需服务端生成音频。

• 40–240 BPM：加减按钮每次调整 5，滑条支持逐 1 调整；点击数字输入，右上角“保存”和下方“确定”均可保存。
• 2/4、3/4、4/4，以四分音符计拍；可开关首拍重音。
• 普通节拍器提供电子、柔和、人声报拍、美式英语女声四种音色；人声按拍号循环报数，首拍重音开启时第 1 拍更响。手机音量键控制音量。
• 首页可切换鼓伴奏：基础八分、慢速抒情、摇滚三个鼓点预设；提供声学鼓、808 电子鼓两组音色，使用本地准备的 99Sounds 采样（仓库不分发音频文件，见下方说明）。
• 两个模式都支持修改 2/4、3/4、4/4，Tab 同步显示当前拍号，切换模式保留拍号。鼓点在 2/4、3/4 时取原 4/4 预设的前 2、3 拍，再按小节循环；不做速度拉伸。
• 1、5、10 分钟练习，默认 10 分钟；支持暂停、继续、结束。
• 设置提供保持浅色、保持深色、跟随系统三种外观，默认跟随系统并本地记住选择；切换外观不中断音频。
• 结束按钮与主播放按钮同尺寸，使用红色。
• 本地记住上次设置。播放或暂停期间修改参数，需要确认结束当前练习；下一次开始会重新生成并从头播放完整时长。
• 首页底部显示 Author: Steven · © 年份，年份读取用户设备的本地系统时间，每次进入前台更新。
• 生成期间保持前台；完成后可以锁屏练习。绿色大点表示首拍（普通节拍器开启重音时），灰色小点表示其余拍；金色外圈标记当前播放拍。暂停、结束或进入后台时清除外圈，回到前台按音频进度重新对齐。动画仅作辅助，以声音为准。

功能拆解、UI 布局和鼓伴奏范围见 功能与UI规划.md；最初的验证方案见 方案.md。

运行

1. 微信开发者工具导入仓库根目录，小程序目录为 miniprogram/。仓库中的 AppID 使用 touristappid 占位；真机预览和后台音频验证前，在本地将 project.config.json 的 appid 替换为自己的小程序 AppID，并使用有开发权限的微信账号。
2. 编译后，在模拟器检查设置、底部选择面板与错误提示；使用真机预览检查声音和后台播放。
3. 开始前选好 BPM、拍号、音色和时长，等待音频准备完成。切后台会中止尚未完成的生成，可回到前台重试。
4. 设置 → 查看诊断信息，可反复展开、收起；点击信息区域或“复制全部诊断信息”可复制到剪贴板。“停止并清理全部运行数据”会停止播放并清除音频、日志和运行缓存，保留用户输入与设置。

本地配置与第三方素材

• project.config.json 提交时必须保留 touristappid 占位值；本地填写真实 AppID 后，提交前恢复该字段并检查 git diff --cached。不要在文档中写入真实 AppID、AppSecret 或令牌。
• project.private.config.json、环境变量文件、私钥、日志和系统缓存已在 .gitignore 中排除；开发者工具可自行生成私有配置。
• 仓库不分发 99Sounds 的 6 个 WAV 文件。普通节拍器无需额外素材；使用鼓伴奏或运行完整测试前，请按鼓采样说明自行下载并转换素材。已有本地采样可以继续使用。
• 人声采样来自用户提供的 练习曲（1）伴奏.wav 开头四个报拍，已替换旧英语与日语素材，四个数字采样随项目提供，无需额外下载；来源与处理方式见人声采样说明。
• 美式英语女声采用 tim.kahn 的 countdown.wav（CC BY 4.0），保留来源署名，并提供随速度选择的采样版本；详见人声采样说明。
• 历史提交中的 AppID、私有配置和第三方采样不会因为当前文件脱敏或新增忽略规则而消失；彻底移除需要另行清理 Git 历史，并同步远端及协作者克隆。

生成文件清理

递归清理本小程序专用目录 USER_DATA_PATH/metronome-probe 内的所有文件与子目录，不区分扩展名，包括未生成完整的音频、日志文件和其他残留；保留专用目录用于后续练习，不删除用户输入、设置记忆或包内鼓采样。

• 新启动先清理历史残留，每次生成前再清理旧文件；清理失败时不继续生成新音频。
• 使用 open → write（指定位置分块写入）→ close 生成单个文件，绕开已在开发者工具复现配额错误的逐秒 appendFile 路径。写入不足时补齐，播放前校验完整大小；失败时先关闭文件再清理，关闭失败则保留状态供下次重试。
• 一次只保留当前练习文件。1、5、10 分钟分别为 2,646,044、13,230,044、26,460,044 字节；反复练习不会增加保留文件数量。
• 手动结束、系统播放器停止、自然结束或播放错误时立即尝试清理，后台事件也会发起清理。
• 生成期间离开页面会中止本次生成，在生成任务释放后清理半成品；快速返回也不会继续该任务。
• 页面进入、隐藏、卸载时，若没有正在播放、加载或暂停的会话，检查并清理残留。播放和暂停保留当前音频，供息屏播放或继续练习。
• 某个文件删除失败时继续清理其他文件，显示失败状态；下次进入自动重试，也可在诊断面板手动清理。
• 系统挂起后台 JavaScript 或强制关闭微信时，无法保证退出瞬间完成删除；残留在下次进入时清理。

删除后重新列目录，确认没有残留才显示清理完成。诊断面板显示生成文件数量、字节数与用户目录总占用（不包括代码包和微信内部临时缓存），生成失败日志保留预计大小、进度和错误原因。用户目录中其他文件只统计，不删除。日志仅保留内存中的最近 20 条，不写入磁盘。手动停止清理还会清空历史日志、解码后的鼓采样缓存与生成进度；下一次播放按需重新加载采样。清理失败时显示本次失败原因，允许重试；自动错误清理保留诊断日志用于排查。

验证状态

用户已确认第一阶段普通节拍器版本的真机验证通过，包括息屏播放。本次新增鼓伴奏和播放圆点，仍需针对新增部分做真机回归；正式版后台播放还需审核。

微信开发者工具已编译通过。模拟器检查了首页布局、BPM 顶部保存按钮、每次加减 5、鼓组与预设面板；声学鼓基础八分与 808 摇滚均已生成播放，确认当前拍外圈显示及结束清理。暂停继续、修改参数确认流程也已验证。本次还检查了浅色/深色/跟随系统选项、导航栏与面板配色、播放中切换深色、同尺寸红色结束按钮，以及停止后的“生成文件已清理”诊断状态。模拟器曾出现存储配额错误，重新打开项目后播放恢复。此次改用文件描述符写入后，已在开发者工具生成并播放十分钟音频，结束后确认生成文件为 0 个 / 0 字节；已检查深色浮窗层级和两个 Tab 的动态拍号。在同一个模拟器做旧流程对照：每次追加 44,100 字节，第 50 次 appendFile 报 fs_appendFile:fail the maximum size of the file storage limit is exceeded，此前文件仅约 2.1 MiB；测试文件已删除。新版描述符写入完成十分钟普通节拍器与 3/4 鼓伴奏生成、播放和结束清理。这个结果说明旧追加接口的配额路径是问题来源之一，不能把报错直接解释为磁盘残留；真机仍需反复练习和异常退出回归。

按鼓采样说明准备好本地采样后，运行完整测试：

node --test tests/*.test.js

当前 46 项测试通过，覆盖 WAV 头、可变速度的拍点与重音、暂停继续、参数修改确认、本地设置、页面重进、生成中切后台、错误重试、文件清理、BPM 保存与步长、播放拍进度同步、鼓伴奏混音与采样加载、后台结束清理、删除失败重试与隔离、进出页面清理、快速前后台切换取消生成，以及主题跟随、固定、保存恢复和切换不中断音频。新增覆盖不同鼓拍号的实际鼓点位置与跨小节尾音、诊断复制、四次十分钟生成/清理的占用上限、短写补齐、文件关闭失败重试和删除后复查，以及诊断反复展开/收起、递归清理残留与日志/采样缓存、保留用户输入设置、跨年更新版权年份。微信接口使用模拟对象，不代替真机测试。

真机回归建议：

1. 先用 1 分钟，分别试电子/柔和/人声报拍/美式英语女声、2/4/3/4/4/4、首拍重音开关，确认实际声音与设置一致。
2. 测试 40、137、240 BPM；录制声音检查拍点，不以界面刷新时间判断精度。
3. 测试暂停/继续、取消与确认修改参数，确认恢复不重新开始，修改后重新开始按完整时长播放。
4. 用 5、10 分钟测试锁屏、切微信聊天与返回前台；检查声音连续性、生成耗时和结束后清理。
5. 单独测试来电、其他音频中断、生成期间切后台、重新进入页面和异常退出后重开。

本次新增功能回归

• 使用中文键盘输入 BPM，检查顶部“保存”和下方“确定”都能保存；超出范围时保留输入面板并提示。
• 检查加减每次调整 5 BPM，在 40、240 处正确限制。
• 检查金色外圈随当前拍移动，暂停时消失；继续、锁屏返回、系统播放器跳转后重新对齐。
• 检查红色结束按钮与主按钮同尺寸；结束后在诊断面板确认“生成文件已清理”。
• 外观分别选保持浅色、保持深色、跟随系统；重开后检查记忆，跟随系统时切换手机外观并检查导航栏、首页、输入与选择面板。
• 两组鼓色、三个预设分别试听，检查快慢速度下的声音与拍号；至少做一次 10 分钟锁屏播放和结束清理。

鼓采样来源、文件选择与转换方法见 鼓采样说明。

人声报拍已通过自动化验证（拍号循环、跨秒拍点、首拍重音、设置恢复、采样加载失败重试），微信模拟器试听与真机锁屏回归尚待完成。