duooomi-android-sdk/CLAUDE.md

duooomi-android-sdk · 项目级指引

Android 版 Duooomi BLE SDK，与 iOS / expo 版业务行为 1:1 对齐。

上游参照

仓库	路径	关系
duooomi-ios-sdk	/Users/cchis/Documents/ship/bw/duooomi-ios-sdk	业务行为权威。HEAD 是 1:1 复刻目标，发现偏差以 iOS 为准
expo-duooomi-app	/Users/cchis/Documents/ship/bw/expo-duooomi-app	OTA 编排原型（bindDeviceWithOrchestration）
duooomi-harmony-sdk	/Users/cchis/Documents/ship/bw/duooomi-harmony-sdk	平级复刻，可对照实现

修改前必读

改 SDK 业务行为前 → 先读对应 iOS 实现，1:1 严格对齐，偏离要有理由（详见 跨平台 SDK 复刻方法论）。

改 BLE 协议层（帧格式 / discoverServices）→ 先看全局 lessons-learned 中的 BLE 章节。

项目 Wiki 索引

Wiki	内容
tech-architecture	项目分层 / OTA 三段式编排 / 状态清理时机表 / sn 级互斥 / BeijingTime 三级 fallback / Demo Reload 机制
product-decisions	owner 必填 / bind 改瘦 / disconnect 不清 sn / UpgradeRecord 4 状态 / scanNamePrefix 必填

关键约束

• SDK 公开 API 改动 = 破坏性。改前看 iOS HEAD 是不是也这样；不是 → 不要改
• 状态清理时机 改前查 tech-architecture 表格，与 iOS 对照
• HTTP path / header / body 字段名 必须 1:1 与 iOS / expo 一致
• JSON payload 可选字段 nil 时省略 key（不是 null），bind/setPlayMode 的 loop 字段必须遵守
• Demo 秘钥：demo/.../DemoSecrets.kt 是 gitignored 真实文件；模板放 docs/DemoSecrets.template.kt（不要放 demo/src/，会 redeclare 冲突）

复刻 iOS 新功能时的标准工作流

1. git -C ../duooomi-ios-sdk log <last-aligned>..HEAD --oneline 圈 gap
2. 按依赖关系重排 commit 顺序（基础设施合并到第一个 feature）
3. 先做 SDK 改动 → debug + release 都编译过
4. 写完后对照 iOS 状态清理表逐字段核
5. 改 demo / README 跟随
6. 全部跑通后系统化检查报告（哪些严格对齐、哪些平台惯例偏离）