251 lines
43 KiB
Markdown
251 lines
43 KiB
Markdown
# NESLite V1.0 待办事项
|
||
|
||
依据:[开发计划 V1.0](docs/development_plan_V1.0.md)。编制日期:2026-09-12。所有开发任务初始状态为未开始,本文不表示任何工程或实机验收已经完成。
|
||
|
||
## 1. 执行与勾选规则
|
||
|
||
1. **一个实现项交付一项可独立验证的能力或一份完整材料。** 任务通常控制在约半天至一天半;不把编码、编译、补测试分别拆成待办,也不把整个模块塞进一个实现项。阶段验收与发布材料单列,不按实现项工期衡量。
|
||
2. **编号对应开发计划。** 例如 `M2-02a`、`M2-02b` 均属于计划的 `M2-02`;后缀只拆分工作,不改变所属阶段。每项均写明阶段内前置条件、交付结果和验收级别。
|
||
3. **阶段依赖是共同前置条件。** M0 无阶段前置;M1~M9 依次依赖上一阶段门槛 G0~G8 通过,等价于计划中的累计依赖。条目内“无”仅表示没有额外的阶段内前置条件。列表顺序已按实际依赖排列,不要求父编号严格递增。
|
||
4. **完成实现项不等于阶段通过。** 实现、对应局部验收及必要文档更新完成后才能勾选实现项;阶段 G 项还需满足明确的集成/实机门槛。设备缺失时保留 G 项未勾选,不能以编译成功或模拟输入替代真实手柄验收。
|
||
5. **等待不阻止独立工作。** 前置未通过时,只能推进不依赖其结果的草稿或隔离实现;不能提交依赖未知接口的完成结论,也不能勾选依赖阶段的门槛。
|
||
6. **状态与证据只记一次。** 未勾选项默认“未开始”;进行中、待实机或失败时在条目末附状态和原因。通过后附源码提交及报告位置;阶段报告引用这些记录,不复制同一测试。尚未建立的文档路径是交付目标。
|
||
7. **范围和参数不暗改。** 保留计划的 F01~F14、M0~M9 及 0.1.x~1.0.0 路线。新需求另列后续版本;快进倍率、存档周期等计划允许校准的参数,在指定阶段形成记录并同步两份文档。
|
||
8. **未定参数也有明确交付要求。** 计划未给数值的 ROM/存档包大小上限、轴阈值、连发频率、缓冲/日志容量,由对应实现项确定并记录数值、单位、默认值及超限行为;配置、文档和验收一致后才算完成,不用“适当”“合理”等词代替实际参数。
|
||
|
||
## 2. 分级验收与重跑规则
|
||
|
||
### 2.1 验收等级
|
||
|
||
等级表示验证范围,不是每项任务必须从 L0 到 L4 全部重跑。高等级可直接引用仍有效的低等级结果。每项中的完成标准定义最小必要行为;只有失败、未知影响或下表所列变更才扩大范围。
|
||
|
||
| 等级 | 使用场景 | 要做的验证 | 不自动包含 |
|
||
| --- | --- | --- | --- |
|
||
| L0 文档/材料检查 | 文档、清单、版本说明或材料整理 | 核对内容、编号、链接、版本与文件对应关系 | 编译、运行、游戏回归 |
|
||
| L1 局部验证 | 单一逻辑、构建配置、解析器或映射规则 | 受影响目标的编译/静态检查;用最少的正常和必要边界用例验证本项行为 | 全部单元测试、整应用实机流程、耐久测试 |
|
||
| L2 模块集成 | JNI、设备、文件系统、UI 或两个模块交接 | 受影响模块及直接相邻接口;一个代表样本的正常流程,加本次涉及的失败/取消分支 | 全 ROM 集、30 分钟运行、100 次存读档、20 轮循环 |
|
||
| L3 阶段验收 | G1~G7 的阶段出口;G0 为构建基线检查 | 本阶段新增能力的连贯路径,以及分配到该阶段的专项指标 | 其他已通过阶段的全部测试、发布全量回归 |
|
||
| L4 发布验收 | M8 的候选发布版与 G8 | 核对 F01~F14,执行冻结的兼容集和候选包关键流程,补齐缺失/失效的专项证据 | 不分影响地重复所有历史用例、设备和长测 |
|
||
|
||
纯文案或排版改动用 L0;布局和焦点改动用对应页面的 L2;不为低影响改动编写仅重复实现的测试。新增或修复有状态逻辑时优先增加可复现行为测试,避免每个页面各写一套相同底层测试。
|
||
|
||
### 2.2 改动到验证范围的映射
|
||
|
||
本表的“重跑”针对已经实现并验收过的能力。首次开发按当前任务的 L1/L2 验证,完整 H 项到指定节点执行,不提前要求测试尚未实现的后续功能。同一轮连续修改先用局部验证排错,修改稳定后在阶段/发布门槛统一执行所需专项;不为每个函数或每次提交各跑一次长测。
|
||
|
||
| 改动 | 默认选择 | 扩大范围的条件 |
|
||
| --- | --- | --- |
|
||
| 文档、注释、无运行影响的说明 | L0 | 文档同时变更了产品行为时,转入对应实现项验收 |
|
||
| 游戏库/设置界面 | 对应 L1 或 L2;只跑改动页面和直接调用链 | 触及共享焦点、输入分发或会话控制时,补对应模块路径 |
|
||
| 映射、死区、来源合成、连发 | 输入 L1+改动链的 L2 | 改变断柄清理或设备识别时重跑 H-HOT;改变采样链时重跑 H-INPUT |
|
||
| 音频缓冲、重采样、时钟、快进 | 音频/时钟 L1+切换 L2 | 时钟或持续流行为变更,重跑完整 H-AV 及对应模式切换;不自动重跑游戏库或存档包测试 |
|
||
| 存档格式、提交/备份/恢复、序列化逻辑 | 存档 L1+集成 L2 | 重跑完整 H-SAVE;触及升级兼容时补 H-UPGRADE;槽位文案改动不触发 100 次循环 |
|
||
| 生命周期、Surface/音频重建、异步退出 | 受影响转换的 L2 | 改变后台/锁屏恢复时重跑 H-LIFE;改变资源释放或产生内存疑点时重跑 H-LONG |
|
||
| FCEUmm 提交、内核编译选项、libretro 宿主行为 | 内核对应完整集:冻结 ROM 集、H-AV、H-SAVE 和内核控制路径 | 改动涉及原生打包则补 H-NATIVE;影响无法界定时进入 L4 |
|
||
| 工具链、ABI、链接/原生依赖、APK 打包 | 受影响构建+H-NATIVE+实际包短路径 | 若改变运行库/优化行为,补受影响音频、状态或长时指标;仅重新签名不自动重跑 2 小时测试 |
|
||
| RC 后缺陷修复 | 复现用例、受影响模块及实际新包短路径 | 多模块影响无法界定或出现广泛回归时重跑 L4 |
|
||
|
||
**停止规则:** 本次选定范围通过且没有新增失败、未解释的统计异常或影响疑点,就结束验证并继续下一项;不以“再保险”为理由重复同一范围。
|
||
|
||
### 2.3 专项验收只在指定节点执行
|
||
|
||
H 编号是可复用的验收记录,不是额外实现任务。L1/L2 用例覆盖到同一场景时可合并执行;同一长时间会话可同时采集速度、音频、内存等指标。使用同一结果覆盖多个指标时,必须满足各自样本、时长和环境要求。
|
||
|
||
| 专项 | 首次完整执行节点 | 固定口径 |
|
||
| --- | --- | --- |
|
||
| H-AV 音画与速度 | G3 | NTSC、PAL 各连续至少 30 分钟;每个连续 60 秒窗口和全程速度均为 99.5%~100.5%;以实际模拟时间/有效单调时间计算,排除加载、暂停、快进。预热后的正常前台段欠载目标为 0,无持续爆音及累积偏移;模式/设备切换另做短路径 |
|
||
| H-HOT 插拔 | G4 | 目标手机+X5 Lite,20 轮按住方向及 A/B 时断开再重连;每轮确认暂停、状态清空、配置匹配和用户继续后输入正常 |
|
||
| H-SAVE 存档 | G5 | 同一锁定内核完成总计 100 次手动存读档循环,10 个槽各 10 次,每次对照预定状态和校验值确认恢复;同时安排自动恢复点轮换、电池存档重载、导出再导入的必要分支验证,不对每种类型再各做 100 次。截断、校验错、哈希/版本错、空间不足以及临时写入/替换前/替换后终止各覆盖对应失败路径,有效提交和备份保持可恢复 |
|
||
| H-LIFE 后台/锁屏 | G7 | 后台切换 20 轮、锁屏/解锁 20 轮;无后台声音、黑屏或残留键。Surface/Activity 重建、音频路由变化及异常启动另按不同状态转换覆盖,不再各做 20 轮 |
|
||
| H-LONG 长时稳定性 | M8-02a | 至少两个代表样本,分别覆盖动作/滚屏与电池存档,每个 2 小时;无崩溃、ANR 或持续内存增长;每分钟记录 Java/native 内存和 PSS,检查预热后趋势 |
|
||
| H-INPUT 软件输入延迟 | M8-02b | 正常负载下至少 1,000 次事件,以同一单调时间域记录应用接收到首次内核采样;P95 ≤ 1 个实际模拟帧,排除暂停/绑定界面,不作为按键到屏幕总延迟 |
|
||
| H-NATIVE 原生兼容 | M8-03a、M8-03b 合并记录 | 最终包的每个原生库通过 ELF 和 APK 16 KB 对齐检查;4 KB/16 KB 环境均完成加载、运行、声音和保存恢复。记录实际 ABI/页大小,x86_64 运行不替代 arm64 发布库检查 |
|
||
| H-UPGRADE 安装升级 | M8-04a | 新安装和至少一个旧测试版本的同 ID/同签名覆盖升级;ROM 关联、收藏、设置、游戏存档均保留,即时存档按兼容策略恢复或保留并提示 |
|
||
|
||
H-SAVE 的故障注入按不同失败路径选择代表样本;共用同一提交器的所有槽位不重复相同故障矩阵。需要触发自动周期时使用可控测试时钟验证状态转换,不靠重复等待增加测试时长;周期对真实帧时间的影响另在 M5 实测。
|
||
|
||
**证据复用条件:** 报告必须标明源码/内核提交、相关模块及依赖配置、设备系统、ROM 哈希、参数、结果和日志。M8 逐项记录自该报告后有哪些改动、为什么未影响该指标;模块、配置或环境已变或无法证明未受影响时,重跑对应 H 项。不能仅因“以前通过”就复用,也不能为每个新提交自动使全部证据失效。
|
||
|
||
**发布全量的含义:** G8 必须覆盖计划全部发布要求;冻结兼容集与候选包关键路径在 RC 上执行,长测和计数型测试可引用符合上述条件的证据。M9 的最终包必须再做一次短路径,但相同代码和配置的签名/版本元数据变化不自动触发全部长测。
|
||
|
||
## 3. 全程保持一致的行为约定
|
||
|
||
| 主题 | 固定约定 |
|
||
| --- | --- |
|
||
| 工程 | NESLite;单 `app`、Kotlin+原生 View;minSdk 28,compileSdk/targetSdk 36;AGP 8.13.2、Gradle 8.13、JDK 17;NDK r28 起选精确版本;发布 arm64-v8a |
|
||
| 内核与线程 | 固定 FCEUmm;单 ROM、单实例、玩家一;改变内核状态的操作全部在模拟线程;音频回调不执行内核或阻塞 I/O |
|
||
| 导入与身份 | 只导入 `.nes`;识别 iNES/NES 2.0;完整文件字节 SHA-256 作为身份;内部正式 ROM 位于 files 而非 cache |
|
||
| 显示与时钟 | 默认 4:3、最近邻;原始像素整数缩放独立;模拟速度读取内核时序,与手机刷新率解耦 |
|
||
| 快进 | M3 引擎支持、M4 绑定 RB、M6 提供设置;初始按住 2 倍且静音,松开/失焦/暂停/断柄取消;最终倍率在 G3 冻结 |
|
||
| 输入 | A/B 对应 NES A/B,X/Y 对应 A/B 连发,菜单/视图为 Start/Select,右摇杆按下为暂停菜单;键码来自 M1 实测;不占用视图+菜单长按;快读档不默认绑定易误触单键 |
|
||
| 存档阶段 | M2 只交付基础电池存档;M5 才承诺完整备份、即时存档和故障恢复;M4 不验收尚未实现的存档导航 |
|
||
| 存档规则 | 手动 10 槽、自动最近 3 份;变化电池存档初始每 10 秒提交、自动恢复点初始每 60 秒生成,M5 按实测冻结;暂停/退出补充提交;成功落盘才显示保存成功 |
|
||
| 读档与恢复 | 读档先备份当前状态及游戏存档;失败回滚,回滚失败安全重载;不同内核提交默认不自动读入;回前台/重连后由用户继续 |
|
||
| 游戏库 | M2 最小列表、M4 焦点导航、M6 完整列表;从列表移除只隐藏并保留存档,再导入同哈希恢复关联 |
|
||
| 后台与范围 | 后台不继续模拟;V1.0 不含联网、云存档、FDS、第二手柄完整体验、回溯、run-ahead 或切换内核;不增加商店上架工作 |
|
||
|
||
## 4. 实现待办与阶段门槛
|
||
|
||
条目中的 **前置** 仅列阶段内依赖;共同阶段依赖见第 1 节。**完成** 同时限定交付内容和可观察结果。所有任务保留计划原父编号,便于回填进度。
|
||
|
||
G1~G8 的共同交付物为对应阶段 APK、源码提交、构建说明、验收记录和已知问题清单。构建说明等未变化时引用现有文件及版本即可,不另写重复副本;以下 G 项只补充各阶段特有的材料。
|
||
|
||
### M0:工程准备
|
||
|
||
- [x] **M0-02a 锁定本机构建环境**。前置:无。完成:核对 JDK/SDK/NDK/CMake,记录精确版本、安装位置和缺口;形成工具链及应用依赖版本清单。验收:L1,工具可调用且版本符合计划,清单无动态版本。证据:`docs/toolchain.md`、`docs/reports/m0-baseline.md`;Gradle 构建和原生链均已实际调用。
|
||
- [x] **M0-01a 建立可构建的应用骨架**。前置:M0-02a。完成:初始化 Git、Wrapper、单 app、Kotlin/View 页面、CMake 和 JNI 空入口,将锁定版本写入工程配置,生成 arm64 调试 APK。验收:L1,目标构建成功且 APK 包含预期原生库。证据:`app/build/outputs/apk/debug/app-debug.apk`;确认包含 `lib/arm64-v8a/libneslite_jni.so`。
|
||
- [x] **M0-01b 固定应用与数据身份**。前置:M0-01a。完成:确定显示名、applicationId、版本号/versionCode 规则、长期测试与发布签名延续策略;在需求文档登记数据目录约定。验收:L0+受影响配置的 L1,构建配置与记录相符。证据:`docs/identity.md`;APK 为 `org.neslite.app.debug`、`0.0.1-dev-debug`、min/target SDK 28/36。
|
||
- [x] **M0-03a 固定上游来源**。前置:M0-01a。完成:登记 FCEUmm 完整提交、libretro 头文件及 Oboe 固定版本,建立依赖获取方式和本地补丁清单。验收:L1,按记录可取得对应源码;此项不要求内核已编译。证据:`third_party/manifest.json`;三个固定提交已由 `tools/fetch-third-party.ps1` 检出。
|
||
- [x] **M0-03b 建立许可证清单**。前置:M0-03a。完成:逐项记录依赖来源、版本、许可证和待交付材料,建立 LICENSE/THIRD_PARTY_NOTICES 基线。验收:L0,已引入依赖无遗漏、记录与选定源码一致。证据:`LICENSE`、`THIRD_PARTY_NOTICES.md`、`docs/dependencies.md`。
|
||
- [x] **M0-02b 编写可复现构建说明**。前置:M0-01b、M0-03a。完成:docs/build.md 记录从检出到 APK 的步骤、精确工具版本、ABI 和依赖获取;不依赖手工复制未知库。验收:L0;干净检出实际构建统一放在 G0,不在此重复。证据:`docs/build.md`;调试 APK 已构建。
|
||
- [x] **M0-04a 建立需求与验收资源表**。前置:M0-01b。完成:docs/requirements.md 映射 F01~F14;列出设备待测参数和 ROM 来源/哈希/区域/Mapper/存档类型;登记 M2 至少 3 个样本的获取安排,其中一个有电池存档。验收:L0,已取得样本有使用依据,未齐资源列明缺口和取得办法,G2 前须齐备。证据:`docs/requirements.md`、`docs/reports/rom-inventory.md`。
|
||
- [x] **M0-04b 建立按范围执行的检查入口**。前置:M0-01a、M0-04a。完成:本地入口可选择构建、局部测试、模块集成和阶段检查;原生测试接入可运行目标;docs/acceptance.md 和报告模板使用 L/H 编号。验收:L1,执行一个最小目标可获得结果,默认命令不启动全部耐久测试。证据:`tools/check.ps1`;固定 CTest 的原生 smoke target 通过。
|
||
|
||
- [x] **G0 工程门槛**。前置:本阶段全部实现项。验收:L3 构建基线;从干净检出按说明构建调试 APK 一次,核对依赖可追溯、无未知库;记录资源缺口与取得办法。此处不要求产品级界面或实机运行报告。证据:提交 `8fde6e1c8854930298135ab1ba3199ecc54e89d7` 的干净克隆执行 `tools/check.ps1 -Scope Stage`,APK 构建、原生 smoke 与 Kotlin 单测全部通过;详见 `docs/reports/m0-baseline.md`。
|
||
|
||
### M1/0.1.x:设备与手柄诊断
|
||
|
||
- [ ] **M1-01a 完成安装和 JNI 自检**。前置:无。完成:诊断页展示原生调用结果与库加载错误;应用可在目标手机启动。验收:L2,一次安装启动和一次 JNI 调用成功,错误可定位。
|
||
- [ ] **M1-01b 展示真实设备基线**。前置:M1-01a。完成:读取机型、系统 API、ABI、页大小、屏幕尺寸和可用刷新率;未知值明确标记。验收:L2,与设备可读取信息核对,不按 MagicOS 名称推断硬件。
|
||
- [ ] **M1-02a 枚举控制器能力**。前置:M1-01a。完成:展示名称、描述符、厂商/产品标识、输入源和轴范围;连接/移除时更新列表。验收:L2,一次接入和移除可观察,设备临时编号不作持久身份。
|
||
- [ ] **M1-03a 建立实时按钮状态页**。前置:M1-02a。完成:显示 KeyEvent 按下/松开及组合状态,保留事件时间与来源。验收:L2,方向和 A/B 可同时按下,全部松开后状态清零。
|
||
- [ ] **M1-03b 展示轴与重复上报**。前置:M1-03a。完成:展示 HAT、摇杆、扳机值,能辨认同一操作的按键/轴两种上报。验收:L2,各实际可用轴的往返变化可观察,未上报的能力不伪造。
|
||
- [ ] **M1-03c 记录可回放输入序列**。前置:M1-03b。完成:按统一事件结构保存来源、时间、动作和值,记录有界;提供供后续逻辑测试读取的格式。验收:L1,一段组合输入记录读取后事件顺序和数值一致。
|
||
- [ ] **M1-04a 清理异常输入状态**。前置:M1-03b。完成:失焦、设备移除时清空相应状态;重连创建新的会话关联。验收:L2,按住后拔出、失焦、重连各一条代表路径无残留;此时不做 20 轮插拔。
|
||
- [ ] **M1-04b 导出诊断和实测键位表**。前置:M1-01b、M1-03c、M1-04a。完成:通过系统选择器导出设备与事件 JSON,写入 docs/controller-x5lite.md,记录安卓模式、硬件连发状态和厂商保留组合。验收:L2,导出可读且键位表对应实测事件。
|
||
|
||
- [ ] **G1 诊断门槛**。前置:本阶段全部实现项。验收:L3;在真实目标手机和 X5 Lite 完成“连接 → 组合输入 → 松开 → 按住拔出 → 重连”一次连贯检查,可复用本阶段有效实机记录。交付 0.1.x APK、源码提交、构建说明、设备 JSON、键位表和未覆盖项;重估后续工期。
|
||
|
||
### M2/0.2.x:内核、画面与基础操作
|
||
|
||
- [ ] **M2-01a 编译固定内核**。前置:无。完成:FCEUmm 链接到原生宿主,记录构建选项/补丁并冻结实际编译通过的提交。验收:L1,arm64 目标链接成功、导出入口与 API 版本可检查。
|
||
- [ ] **M2-04a 建立单线程会话执行器**。前置:M2-01a。完成:单内核线程、有界命令队列、会话编号及 Idle/Loading/Paused/Running/Pausing/Stopping/Error 状态;定义命令完成通知。验收:L1,状态转换和重复/迟到命令用最小序列验证,旧会话不能被重新激活。
|
||
- [ ] **M2-01b 实现环境协商**。前置:M2-04a。完成:按内核要求注册回调、目录、配置和玩家一设备;不支持请求返回失败,必要能力缺失阻止加载;形成支持清单。验收:L1,支持、不支持和缺少必要能力各验证一条不同分支。
|
||
- [ ] **M2-01c 接通内核生命周期与 AV 信息**。前置:M2-01b。完成:在模拟线程初始化、加载、读取时序、运行、卸载和销毁;正确消费音频回调但暂不发声,使用单调时钟控制速度。验收:L2,由测试入口提供已准备的样本路径,验证加载、卸载及失败后重载;不依赖尚未完成的导入 UI。
|
||
- [ ] **M2-02a 实现 ROM 流式导入**。前置:M2-04a。完成:SAF 读取、大小上限、iNES/NES 2.0 头校验、内部临时副本和完整文件 SHA-256;取消/读取失败清理临时文件。验收:L1+SAF 的 L2,正常头、损坏头、中文文件名和取消覆盖不同路径。
|
||
- [ ] **M2-02b 提交内部文件与最小游戏索引**。前置:M2-02a。完成:正式 ROM 存在 files,Room 以哈希关联;重复内容去重、同名不同内容分开;最小列表能选择加载。验收:L2,两种重复场景不串档,content URI 不被当作原生路径。
|
||
- [ ] **M2-02c 恢复导入中断的不一致数据**。前置:M2-02b。完成:启动时核对临时/未登记文件和缺失文件记录,提供恢复或明确失败状态,不误删有效数据。验收:L2,在文件提交后数据库登记前中断、正式文件缺失各注入一次。
|
||
- [ ] **M2-03a 实现原生视频缓冲交接**。前置:M2-01c。完成:处理协商像素格式、宽高、pitch、重复帧和有界缓冲所有权,不保存失效指针。验收:L1,选择覆盖非紧密行跨度、重复帧和缓冲切换的最小输入集。
|
||
- [ ] **M2-03b 显示保持比例的游戏画面**。前置:M2-03a。完成:GL 线程显示最新完整帧,默认 4:3/最近邻,支持原始像素整数缩放;丢显示帧不跳模拟帧。验收:L2,一个样本切换两种缩放,比例和缓冲复用正确。
|
||
- [ ] **M2-04b 将基础手柄快照送入内核**。前置:M2-01c、M2-03b。完成:使用 M1 实测键码映射方向、A/B、Start/Select,按状态采样,跨 JNI 不逐帧搬图像。验收:L2,代表游戏可组合操作且松开生效;自定义映射留给 M4。
|
||
- [ ] **M2-04c 接通控制命令和基础生命周期**。前置:M2-04b、M2-02b。完成:UI 通过队列启动/暂停/继续/重置/退出;后台、锁屏、失焦、断柄及 Surface 丢失暂停清理;重建只重接会话;前台资源就绪后由用户继续。验收:L2,正常控制流程和相关状态转换各覆盖一次,不做 20 轮循环。
|
||
- [ ] **M2-04d 读取并提交基础电池存档**。前置:M2-04c。完成:按 ROM 哈希读取保存内存,在模拟线程取快照、文件线程写入;暂停/正常退出提交;成功写入后报告成功。验收:L2,一个电池存档样本退出再载入保留进度,另一个 ROM 不共享文件;不声明 M5 的完整故障保证。
|
||
|
||
- [ ] **G2 基础运行门槛**。前置:本阶段全部实现项。验收:L3;至少 3 个合法样本运行,其中一个支持电池存档;代表样本完成“加载 → 运行 → 暂停 → 继续 → 重置 → 退出 → 重载”,电池进度可恢复,损坏导入不影响现有数据。复用同轮样本检查,不对每个样本重复全部生命周期;交付 0.2.x APK、内核记录、docs/architecture.md 和兼容结果。
|
||
|
||
### M3/0.3.x:音频、时钟与快进
|
||
|
||
- [ ] **M3-01a 打开并管理 Oboe 流**。前置:无。完成:请求低延迟输出,检查实际参数,失败时按能力回退,停止时释放流。验收:L2,一次成功输出和一次受控回退,错误不导致内核无限运行。
|
||
- [ ] **M3-01b 接入有界音频环形缓冲**。前置:M3-01a。完成:生产/消费解耦、欠载补静音和计数;回调使用预分配内存,不阻塞或做文件操作。验收:L1,环绕、空/满边界各覆盖,运行时确认回调只消费数据。
|
||
- [ ] **M3-02a 完成采样率与格式适配**。前置:M3-01b。完成:按内核和设备实际采样率重采样,完成声道/格式转换,跨批次保持连续。验收:L1,不同采样率代表输入输出长度与连续性正确;无需枚举所有可能采样率。
|
||
- [ ] **M3-02b 展示音频诊断参数**。前置:M3-02a。完成:记录内核/设备采样率、回调帧数、缓冲水位、欠载及重建次数,诊断采集有界。验收:L2,实际流参数与展示一致,欠载注入使对应计数变化。
|
||
- [ ] **M3-03a 实现正常运行调度**。前置:M3-02a。完成:以单调时钟、内核时序和音频消费/水位调节推进;显示独立,无音频时切换时钟策略;静音不改变速度。验收:L1+L2,正常、无音频及静音各短路径,无挂起或失控追帧。
|
||
- [ ] **M3-03b 采集速度与帧时间指标**。前置:M3-03a、M3-02b。完成:按实际时序累计模拟时间,分离加载/暂停/快进时间,输出窗口统计和帧时间记录。验收:L1,受控时间序列的计数和排除区间正确;30 分钟测量留给 G3。
|
||
- [ ] **M3-04a 接入音量与静音控制**。前置:M3-03a。完成:UI 命令调整增益/静音,暂停停止输出,恢复不播放旧缓冲。验收:L2,一次音量、静音、暂停与恢复的组合路径,声音和速度符合状态。
|
||
- [ ] **M3-04b 处理音频焦点变化**。前置:M3-04a。完成:失去焦点按策略暂停、清理输入并停止声音;重新获得焦点不自行继续游戏。验收:L2,一次失去/恢复焦点及退出竞态,旧会话无回调复活。
|
||
- [ ] **M3-04c 重建音频设备输出**。前置:M3-04b。完成:路由/流断开后释放并重开,重新读取参数,清空旧音频并重建时间基线,失败时可留在安全暂停状态。验收:L2,可用路由切换和一次受控重开失败后可恢复。
|
||
- [ ] **M3-04d 实现按住快进模式**。前置:M3-03b、M3-04c。完成:支持初始 2 倍静音快进;释放、暂停、失焦、断柄和退出均取消,恢复正常时重建音频与时钟基线。验收:L1+L2,以控制命令验证切换;正式 RB 绑定在 M4,不作为本项前置。
|
||
|
||
- [ ] **G3 可玩音画门槛**。前置:本阶段全部实现项。验收:L3+H-AV;同一批 NTSC/PAL 会话同时记录速度、声音、水位和帧时间,再做受影响模式/路由的短切换。冻结实测可用快进倍率,交付 0.3.x APK 及性能基线;重估剩余工期。
|
||
|
||
### M4/0.4.x:完整手柄操作
|
||
|
||
- [ ] **M4-01a 建立默认与通用映射**。前置:无。完成:把 M1 档案转为 X5 Lite 默认配置,标准 Android 手柄使用通用映射;支持 A/B 交换并保留厂商组合。验收:L1,档案匹配和默认动作正确;未知设备不套用错误专属配置。
|
||
- [ ] **M4-01b 实现自定义绑定页面**。前置:M4-01a。完成:捕获待绑定输入、提示冲突、保存或取消、恢复默认;菜单始终保留可达入口。验收:L2,一个绑定、冲突、取消和恢复流程可完成,退出绑定模式不残留按键。
|
||
- [ ] **M4-02a 合成独立来源并去重**。前置:M4-01a。完成:分别维护设备/轴/按键/触屏来源状态;相同动作重复上报不会重复触发菜单,释放一个来源不清除其他来源。验收:L1,用覆盖双来源按住/释放和轴键重复的最小事件序列;此阶段触屏来源可用测试输入。
|
||
- [ ] **M4-02b 实现死区和方向规则**。前置:M4-02a。完成:轴按下/释放使用不同阈值,支持死区设置;左右或上下冲突时相应方向归零。验收:L1,阈值边界往返和相反方向序列结果确定,无边界抖动。
|
||
- [ ] **M4-03a 实现 A/B 软件连发**。前置:M4-02b。完成:X/Y 对应 A/B 连发,周期按模拟时间推进,退出运行状态清理连发。验收:L1+L2,NTSC/PAL 时间口径一致;关闭硬件连发验证软件行为,再记录硬件连发单独表现。
|
||
- [ ] **M4-03b 绑定暂停与快进动作**。前置:M4-01b、M4-03a。完成:右摇杆按下切换暂停菜单,RB 控制快进;单次命令按边沿触发,菜单键/视图键仍为 Start/Select,默认无易误触快速读档键。验收:L2,长按不重复开关菜单,RB 松开和断柄均结束快进。
|
||
- [ ] **M4-04a 接通列表与菜单焦点导航**。前置:M4-03b。完成:最小游戏列表、暂停菜单和已存在设置页可用手柄移动、确认和返回;焦点不丢失。验收:L2,仅用手柄启动、暂停、继续、重置和退出;本项不要求尚未实现的存档 UI。
|
||
- [ ] **M4-04b 持久化并恢复控制器档案**。前置:M4-01b、M4-04a。完成:DataStore 保存映射/死区等配置,以设备特征匹配,临时 deviceId 只在当前连接使用。验收:L2,一次重启和一次重连恢复配置,设备变号后仍正确关联。
|
||
|
||
- [ ] **G4 手柄门槛**。前置:本阶段全部实现项。验收:L3+H-HOT;引用输入回放结果,执行 20 轮真实插拔及全手柄运行路径,记录残留键/重复动作数为 0。交付 0.4.x APK、配置和操作说明;存档选择/读档导航延至 G5。
|
||
|
||
### M5/0.5.x:可靠存档与恢复
|
||
|
||
- [ ] **M5-01a 建立统一安全提交器**。前置:无。完成:不可变快照按 ROM 串行写入,同目录临时文件、刷新、校验、原子替换和有效备份;旧任务不能覆盖新版本。验收:L1+L2,一次提交、替换失败和乱序任务验证;完整故障矩阵集中在 G5。
|
||
- [ ] **M5-01b 完善电池存档提交策略**。前置:M5-01a。完成:检测内容变化,按初始 10 秒周期及暂停/退出请求提交;无变化不重复写,成功落盘才通知成功。验收:L1+L2,可控时钟覆盖周期和无变化分支,实机测一次保存前后帧时间以冻结周期。
|
||
- [ ] **M5-02a 定义并实现即时存档封装**。前置:M5-01a。完成:保存 ROM 哈希、内核名称/提交、格式版本、配置、时间、长度和校验值;在模拟线程帧边界序列化。验收:L1,封装往返和长度/校验异常可识别;更新 docs/save-format.md。
|
||
- [ ] **M5-02b 实现 10 槽和缩略图快照**。前置:M5-02a。完成:10 个固定手动槽记录时间/缩略图,内容与元数据关联一致;覆盖使用安全提交器;暂停菜单提供基本槽位入口。验收:L2,首次保存和覆盖一个槽位结果正确,失败不显示新存档成功。
|
||
- [ ] **M5-03a 实现自动恢复点轮换**。前置:M5-02b、M5-01b。完成:初始每 60 秒及暂停/退出请求自动快照,独立于手动槽,最多保留最近 3 份有效记录;新提交失败不挤掉旧记录。验收:L1+L2,可控时钟产生 4 份并核对轮换,实机测一次帧时间以冻结周期。
|
||
- [ ] **M5-03b 记录异常会话与恢复候选**。前置:M5-03a。完成:启动/正常结束会话有持久标记,异常重启时列出有效恢复点而不自动运行游戏。验收:L2,一次正常退出及一次进程终止后,提示与候选状态不同且正确;连续崩溃保护在 M7 完善。
|
||
- [ ] **M5-04a 校验读档并保护当前进度**。前置:M5-02b。完成:读档前检查哈希、内核提交、格式、配置和完整性,备份当前状态及电池存档;不同内核提交默认拒绝自动恢复并保留原件。验收:L1+L2,正确档及各不同拒绝分支不串档、不覆盖现有进度。
|
||
- [ ] **M5-04b 完成读档失败回滚**。前置:M5-04a。完成:暂停后在模拟线程反序列化;失败恢复读档前快照,回滚也失败则安全重载有效电池存档;清空旧音视频、重建时钟。验收:L2,成功、反序列化失败和回滚失败各覆盖一次,内核未知状态不可继续运行。
|
||
- [ ] **M5-04c 导出独立存档包**。前置:M5-03b、M5-04b。完成:通过 SAF 导出已提交存档及必要元数据,默认不含 ROM;明确导出失败和取消状态。验收:L2,一次成功导出及取消;包内容与选定游戏对应。
|
||
- [ ] **M5-04d 校验并导入存档包**。前置:M5-04c。完成:限制路径、单项/总大小及格式,校验匹配后安全提交;替换前保留有效版本,失败不留下可误用记录。验收:L1+L2,导出包往返一次,越界路径和无效包被拒绝。
|
||
|
||
- [ ] **G5 存档门槛**。前置:本阶段全部实现项。验收:L3+H-SAVE;100 次循环和故障路径只按第 2 节总口径执行,引用已覆盖的有效分支结果。仅靠手柄完成“选择槽 → 保存 → 读档 → 继续 → 退出”;交付 0.5.x APK、存档格式、已冻结周期及恢复报告。
|
||
|
||
### M6/0.6.x:日常使用界面
|
||
|
||
- [ ] **M6-01a 完善游戏库查询和状态**。前置:无。完成:列表显示元数据,支持搜索、收藏和最近游玩;状态写入 Room 并在重启后恢复。验收:L2,一个包含中文长文件名的混合列表验证查询、收藏和最近记录。
|
||
- [ ] **M6-01b 完成列表移除与重新关联**。前置:M6-01a。完成:移除仅隐藏条目并保留存档;重导入同哈希恢复原关联,同名不同内容仍独立。验收:L2,一次隐藏与重新导入后可找到原存档,无数据删除。
|
||
- [ ] **M6-02a 提供显示设置页面**。前置:无。完成:可选择保持比例/原始整数缩放、最近邻/线性过滤;设置持久化并作用于游戏显示。验收:L2,一个样本逐项切换并重启确认,不重跑 ROM 兼容集。
|
||
- [ ] **M6-02b 整合音频与手柄设置**。前置:M6-02a。完成:音量、静音、映射、死区、连发相关偏好和快进开关统一可访问;复用 M3/M4 实现,不重复建立状态来源。验收:L2,改动设置在当前会话和重启后生效,快进关闭后 RB 不加速。
|
||
- [ ] **M6-03a 完善存档管理页面**。前置:无。完成:展示手动槽、自动恢复点、时间/缩略图、导入导出入口;手柄和触屏都能完成既有存档操作。验收:L2,一个游戏的管理流程与原存档服务结果一致;不重跑 H-SAVE。
|
||
- [ ] **M6-03b 统一页面状态与错误反馈**。前置:M6-01b、M6-02b、M6-03a。完成:游戏信息及相关页面覆盖空、加载、失败、无手柄、长中文名;保存成功/失败与实际提交一致,有可用返回或重试入口。验收:L2,按不同页面状态选代表路径,共用组件只验一次。
|
||
- [ ] **M6-04a 实现基础虚拟按键**。前置:无。完成:方向、A/B、Start/Select 支持多点触控、滑出/取消和与手柄来源合成;触屏暂停入口可达。验收:L1+L2,方向+动作、取消、触屏与手柄先后释放各一条路径,无残留。
|
||
- [ ] **M6-04b 完成首次使用引导**。前置:M6-03b、M6-04a。完成:首次安装可理解如何导入、连接/测试手柄、开始、保存和退出;无手柄时可走纯触屏路径。验收:L2,清空测试应用数据后完成一次引导,不使用用户真实存档作清理对象。
|
||
|
||
- [ ] **G6 日常使用门槛**。前置:本阶段全部实现项。验收:L3;全手柄与纯触屏各完成一次“导入 → 开始 → 保存 → 退出 → 恢复”,可引用本阶段已录制的完整路径。验收新增页面和输入交接;H-HOT/H-SAVE 仍有效时不重复,失效时按第 2 节补测。交付 0.6.x Beta 与使用说明。
|
||
|
||
### M7/0.7.x:系统专项适配
|
||
|
||
- [ ] **M7-01a 统一系统返回处理**。前置:无。完成:采用 AndroidX 返回处理,运行中返回打开暂停菜单、菜单返回继续、设置返回上级、列表返回退出。验收:L2,每种页面状态各一次,系统手势和应用入口结果一致。
|
||
- [ ] **M7-01b 处理返回与游戏状态交接**。前置:M7-01a。完成:返回/菜单动作与暂停确认、加载中、退出中协调,不重复执行或跳回已退出会话。验收:L1+L2,代表重复动作及加载/退出竞态无双会话或错误继续。
|
||
- [ ] **M7-02a 适配横屏安全区域**。前置:无。完成:画面、菜单及虚拟键分别处理挖孔、系统栏和手势边缘,关键按钮可触达。验收:L2,目标设备实际布局下检查一次各不同布局,不改变模拟比例。
|
||
- [ ] **M7-02b 验证设备可用刷新率**。前置:M7-02a。完成:记录每个可用刷新率模式的显示与模拟速度短样本,切换后仍按内核时序运行。验收:L2,各实际模式一条短路径;只有时钟/音频指标异常才触发 H-AV 重跑。
|
||
- [ ] **M7-03a 完善后台与锁屏资源协调**。前置:M7-01b。完成:后台、锁屏、通知/来电导致焦点变化时暂停、静音、清输入并请求保存;回来先准备资源,由用户继续。验收:L2,不同原因各一条状态路径;20 轮循环统一在 G7。
|
||
- [ ] **M7-03b 完善 Surface/Activity 与路由重建**。前置:M7-03a。完成:重建时重绑资源而不新增内核线程,处理音频重开与退出交错;不持有已销毁界面。验收:L2,各不同重建路径与一次退出竞态,无持续黑屏、旧声音或多线程实例。
|
||
- [ ] **M7-04a 阻断异常启动循环**。前置:M7-03b。完成:进程重建从磁盘会话记录恢复选择,同一 ROM/状态连续异常时回列表,不自动重复加载故障内容。验收:L2,受控连续失败后仍可进入列表并启动另一有效游戏。
|
||
- [ ] **M7-04b 完成限额诊断导出**。前置:M7-04a、M7-02b。完成:整合版本、设备、输入、帧率、音频、存档及原生错误记录;日志轮换有上限,导出不包含 ROM。验收:L1+L2,超限轮换和一次导出可读,日志能对应当前会话。
|
||
|
||
- [ ] **G7 系统门槛**。前置:本阶段全部实现项。验收:L3+H-LIFE;后台和锁屏分别 20 轮,其他重建/异常启动引用有效分支记录。若 M7 修改使 H-HOT、H-AV 或 H-SAVE 失效,只补对应专项;交付 0.7.x APK、MagicOS 10 兼容报告与未覆盖条件。
|
||
|
||
### M8/0.9.x:候选发布与覆盖核对
|
||
|
||
- [ ] **M8-01a 冻结候选版和验收集合**。前置:无。完成:固定功能、源码、内核、依赖和配置;建立 F01~F14 到有效证据的索引,列出需重跑项目;冻结至少 12 个有权使用的代表样本,覆盖计划指定 Mapper/区域/文件头/电池存档维度。验收:L0,记录完整且不移除失败样本规避门槛。
|
||
- [ ] **M8-01b 执行 RC 兼容集与关键路径**。前置:M8-01a。完成:在候选包运行冻结样本的预定步骤/自检,覆盖输入、音频、暂停、保存恢复、退出等产品主链;H-SAVE/H-HOT/H-LIFE 仅补 M8-01a 标记失效或缺失的项目。验收:L4 的兼容/功能部分,结果可定位到 ROM 和版本,不对每个 ROM 重复全部专项矩阵。
|
||
- [ ] **M8-02a 完成长时稳定性验收**。前置:M8-01a。完成:执行 H-LONG 并分析崩溃、ANR、内存趋势;已有满足同样口径且仍有效的记录可引用。验收:L4 的 H-LONG;如需补 H-AV,可选满足区域要求的同一会话合并采集。
|
||
- [ ] **M8-02b 完成软件输入延迟验收**。前置:M8-01a。完成:执行 H-INPUT,记录时间域、样本来源、P95 与帧时长;汇总速度/音频统计的有效性。验收:L4 的 H-INPUT 及 H-AV 证据核对,只补失效或缺失部分。
|
||
- [ ] **M8-03a 检查发布原生库与打包对齐**。前置:M8-01a。完成:清点候选 APK 中 FCEUmm/JNI/音频及运行库,逐库检查 ELF 和最终 APK 16 KB 对齐,记录工具版本。验收:L4 的 H-NATIVE 静态部分,无遗漏库或不合格结果。
|
||
- [ ] **M8-03b 验证页大小与最低系统环境**。前置:M8-03a。完成:在实际 4 KB/16 KB 环境做原生运行、声音、保存恢复;API 28 做安装、导入、运行和保存冒烟,记录 ABI 与环境限制。验收:L4 的 H-NATIVE 运行部分+API 28 短路径,不扩展到每个 Android 版本。
|
||
- [ ] **M8-04a 验证新安装与覆盖升级**。前置:M8-01a。完成:执行 H-UPGRADE,核对 Room/设置迁移和存档兼容;保留至少一个可复用旧版本数据集。验收:L4 的 H-UPGRADE,签名/ID/版本记录与实际包一致。
|
||
- [ ] **M8-04b 准备候选交付材料**。前置:M8-01b、M8-02a、M8-02b、M8-03b、M8-04a。完成:整理对应源码、依赖/补丁、许可证、原生符号、构建及使用说明、报告和已知问题;引用前述任务汇总后的有效专项结果。验收:L0,材料版本和测试证据一致,不在材料整理项中重跑测试。
|
||
|
||
- [ ] **G8 发布候选门槛**。前置:本阶段全部实现项。验收:L4 汇总;F01~F14、全部 H 项、环境和发布材料均有有效结果,无阻断/高优先级缺陷,其他问题逐项记录处理结论。门槛只审查并合并证据,不再启动第二轮相同全量测试;有修复时按第 2 节确定重跑范围。
|
||
|
||
### M9/1.0.0:正式交付
|
||
|
||
- [ ] **M9-01a 核对范围与正式版本信息**。前置:无。完成:确认 G8 结论、已知问题和交付范围,设置 1.0.0 与递增 versionCode,保持 applicationId 和签名策略。验收:L0+受影响版本配置的 L1。
|
||
- [ ] **M9-01b 固定发布源码版本**。前置:M9-01a。完成:建立发布源码标记,记录与 RC 的全部差异;依赖、内核和构建配置均可追溯。验收:L0,差异若影响行为则先按第 2 节更新 G8 证据。
|
||
- [ ] **M9-02a 生成正式签名交付包**。前置:M9-01b。完成:生成 NESLite-1.0.0-arm64-v8a.apk、SHA-256、源码包、对应符号及必要混淆映射;私钥不进入仓库或源码包。验收:L1,校验和、签名、ABI、版本和符号对应;正式包对齐检查因产物变化重新执行。
|
||
- [ ] **M9-02b 完成交付说明与许可证材料**。前置:M9-02a。完成:最终说明涵盖构建、导入、手柄、保存/导出/恢复、兼容性及已知问题;源码和依赖许可证材料对应正式版本。验收:L0,交付文件齐全且不存在失效引用。
|
||
- [ ] **M9-03a 验证正式 APK 短路径**。前置:M9-02b。完成:在目标设备实际正式包上完成安装、导入/加载、输入、声音、暂停、保存恢复和退出。验收:L2,每条主链一次;若仅签名/版本元数据变化,不自动重复全部 H 项。
|
||
- [ ] **M9-03b 归档交付证据**。前置:M9-03a。完成:归档正式 APK 校验和、源码标记、工具链、报告、符号和后续问题清单,检查与实际交付文件对应。验收:L0,不重新执行已经通过的运行测试。
|
||
|
||
- [ ] **G9 正式交付门槛**。前置:本阶段全部实现项。验收:L0 交付核对;G8 结果仍有效、最终包短路径通过、计划第 9 节全部材料齐备,才记录应用 1.0.0 完成。任何必需实机/发布指标缺失均保留未完成状态。
|
||
|
||
## 5. 需求完成位置速查
|
||
|
||
此表是索引,不形成第二套待办或重复验收。具体行为与数量以上文条目和专项口径为准。
|
||
|
||
| 计划需求 | 实现位置 | 功能完成门槛 |
|
||
| --- | --- | --- |
|
||
| F01 导入与文件识别 | M2-02a~M2-02c | G2 |
|
||
| F02 游戏库 | M2-02b、M6-01a~M6-01b | G6 |
|
||
| F03 游戏控制 | M2-01c、M2-04a~M2-04d | G2 |
|
||
| F04 显示与过滤 | M2-03a~M2-03b、M6-02a | G6 |
|
||
| F05 音频与时序 | M3 全部,M7 的系统联调 | G3;系统联调 G7 |
|
||
| F06 映射与标准手柄 | M1 诊断、M4-01a~M4-01b、M4-04b | G4 |
|
||
| F07 输入细节与手柄导航 | M4-02a~M4-04b、M5 槽位联验 | G4;存档导航 G5 |
|
||
| F08 快进 | M3-04d、M4-03b、M6-02b | G4;设置入口 G6 |
|
||
| F09 游戏/即时/自动存档 | M2-04d、M5-01a~M5-03b | G5 |
|
||
| F10 存档导入导出与恢复 | M5-04a~M5-04d | G5 |
|
||
| F11 生命周期与异常恢复 | M2-04c、M3-04b~M3-04c、M5-03b、M7 | G7 |
|
||
| F12 虚拟按键 | M6-04a~M6-04b | G6 |
|
||
| F13 诊断 | M1、M3-02b/M3-03b、M7-04b | G7 |
|
||
| F14 原生兼容与交付 | M0 基线、M8-03a~M8-04b、M9 | G8;最终交付 G9 |
|
||
|
||
所有需求在功能阶段通过后,仍须进入 G8 的发布覆盖核对;核对复用有效证据,不等于把每项的全部历史测试重新执行一遍。
|