59 lines
6.6 KiB
Markdown
59 lines
6.6 KiB
Markdown
# 移动端协作指南
|
||
|
||
先读根 `AGENTS.md`，再读本目录 README、开发要求和 Android 详细设计。当前为用户明确授权的首版开发；未来仅在用户明确要求移动端迭代时更新，不因设备端更新而自动修改或发布 App。
|
||
|
||
## 变更顺序
|
||
|
||
1. 修改稳定需求编号及兼容记录。
|
||
2. 协议变化先修改通信契约与跨语言测试向量，再分别修改必要端。
|
||
3. 修改源码、自动测试、构建说明；记录真实验证结果，未运行不得写通过。
|
||
4. 设备侧依赖增删同步离线依赖和 SHA-256；部署沿用根目录门禁与生命周期规则。
|
||
|
||
## 工程边界
|
||
|
||
- Kotlin Multiplatform + Compose Multiplatform，Android 入口、共享业务、共享界面分模块；Android API 不得泄露到 commonMain。
|
||
- 首版 Android minSdk 26；iOS 暂不实现，不声称 Windows 上完成 iOS 编译或蓝牙验收。
|
||
- 设备持久 ID、协议能力和业务命令是连接契约，不依赖蓝牙 MAC、网页布局或私有驱动调用。
|
||
- 只产出 debug APK，正式签名必须有用户明确指令；调试密钥也不进入 Git。
|
||
- 源码、测试、发布说明都在安卓app下；构建缓存、SDK、密钥、真实设备登记不进 Git。
|
||
- Android Studio 属于正常安装软件：下载官方安装包、校验、交给用户安装后停下等待，不安装进 Codex 工具目录。
|
||
- 不擅自关闭 VPN、不自动修改系统设置以修复下载。版本、依赖和 Wrapper 必须锁定并可复建。
|
||
|
||
## 测试手机与秘密
|
||
|
||
真实登记唯一位置为 `安卓app/如何安卓测试/测试设备登记/测试设备.local.json`，提交空白 `测试设备.example.json` 和检查脚本。现有登记不覆盖、不重建。自动选择手机必须使用有效登记，多个设备时不能默认取第一台。设备标识不写日志、报告、示例或提交，报告使用 `android-test-a` 等代号。
|
||
|
||
用户已授权主测试机为专用测试设备，可安装覆盖本 App、清理其测试数据、操作相关权限与蓝牙。授权记录保存在真实登记；不需要常规 root 操作。首次第二台手机互斥验收由用户安装交付 APK 协助，以后相关连接机制改动才要求重测。
|
||
|
||
用户补充要求：手机调试确需 root 时，先停止对话并说明准备请求的权限和用途，等待用户回复开始授权，再发起请求，由用户点击手机授权弹窗。本轮已明确授权用 root 为本 App 授予蓝牙扫描和连接权限；同一授权范围内不重复询问。新用途重新按此步骤处理，不将 root 授权等同于视觉检查授权。
|
||
|
||
## 视觉和物理操作门禁
|
||
|
||
2026-09-25 用户另已明确授权：使用 root 关闭并恢复专用测试手机蓝牙，以验证异常连接恢复。本用途与此前本 App 蓝牙权限授予均可继续，不扩展到其他系统修改；机器重启后须重新检查 ADB、登记身份与设备服务，不沿用旧进程状态。
|
||
|
||
2026-09-25 用户随后明确回复“开始授权，自动点击 App”：允许 root 根据本 App 当前语义控件位置执行点击，以及使用 Home 键测试前后台；不扩展到其他 App、系统安全开关或视觉检查。该用途不再重复询问，真实执行结果分别归档。
|
||
|
||
2026-09-26 用户为 `ANDROID-TEST-WIFI` 另行明确授权 root 完成所需测试：在本 App 设置页按语义识别的可见列表区域滚动，以操作 WiFi 表单。此授权限本次 WiFi 专项，不扩展到其他 App、系统页面或视觉检查。
|
||
|
||
普通前端、手机界面、BLE 控制入口开发未改驱动或显示输出实现时，不新增实屏视觉验收。优先协议、状态、输出帧和驱动统计。只有驱动、扫描时序、底层输出改变或具体显示异常确需视觉证据时才提出。
|
||
|
||
**每次需要视觉检查，必须先停止相关步骤，说明原因，询问用户下一步如何启动，等待明确指示。** 不自动启动 DroidCam、摄像头、采集程序或视觉测试程序，也不主动切换实屏测试图案。专用手机的一般自动化授权不替代本次视觉授权。不需要视觉检查时记录“不适用”，不阻塞交付。
|
||
|
||
断电、接线、拔插、调压仍逐阶段等待用户确认。没有物理结果不得记为实屏通过。
|
||
|
||
## 2026-09-26 用户最新 root 测试授权（替代前述按用途重复询问规则）
|
||
本软件调试所需各种测试权限可直接通过登记测试手机的 ADB root 获取，无需询问。所有自动测试点击一律使用 root，根据本 App 实时语义控件位置定位；滚动同样使用 root。不得通过无障碍或普通注入绕过 MIUI。测试前验证登记、ADB 和 root；权限不足或特殊情况必须停止聊天等待用户，不继续不完整测试。授权仅限调试本软件所需操作，不扩大到其他应用数据，视觉与物理操作门禁继续有效。
|
||
ANDROID-TEST-UI 增加四栏、三点菜单、昵称、长按保存设备、WiFi折叠／DHCP／确认；ANDROID-TEST-STATE 增加记忆迁移、忘记、连接中扫描、切换；ANDROID-TEST-WIFI 增加结构化失败文案；ANDROID-TEST-CONTROL 增加设备混合内容顺序。
|
||
|
||
## 测试经验沉淀与完成反馈
|
||
|
||
- 每轮测试前读 `安卓app/如何安卓测试/常见问题与排障.md`；遇到已有症状先沿用已验证方法，不从头试错。
|
||
- 测试中出现失败、临时修正或恢复操作，完成后必须复盘。可复用的已验证解法更新对应测试流程、排障或构建文档；单次日志、耗时和重测结果写测试归档，未知根因明确保留，不把重测通过当作根因证明。
|
||
- 最终反馈须说明经验已写入哪些文档及未解决项；无新增经验时不重复造条目。不仅在聊天里解释，也不能只留一次性报告。遵守根目录秘密与文档路径规则。
|
||
|
||
## Android 按影响选测（当前规则）
|
||
|
||
每轮先评估直接和共享依赖影响，记录选测理由；测试矩阵不是每轮全量清单。未改且不受影响的页面/设置不跑真机回归。纯逻辑优先 JVM，普通 UI 优先独立模拟器；BLE、实际权限/后台厂商差异等才做必要的定向真机验证。root 授权不代表真机必测；root 输入规则仅适用于登记真机，模拟器使用标准 Compose 测试 API。必要但没做的验证不能写成不适用。切网、长轮询、性能、生命周期和全量验收均需具体影响理由，不能顺带执行。
|
||
|
||
具体触发条件、命令和证据格式见 [按影响选测](安卓app/如何安卓测试/按影响选测.md)。该规则替代历史专项“每轮执行”要求，视觉/物理操作、凭据和真机登记门禁不变。
|