# 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 复刻方法论](~/.claude/wiki/cross-platform-sdk-port.md)）。

改 BLE 协议层（帧格式 / discoverServices）→ 先看全局 [lessons-learned](~/.claude/wiki/lessons-learned.md) 中的 BLE 章节。

## 项目 Wiki 索引

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

## 关键约束

- **SDK 公开 API 改动 = 破坏性**。改前看 iOS HEAD 是不是也这样；不是 → 不要改
- **状态清理时机** 改前查 [tech-architecture](.wiki/tech-architecture.md) 表格，与 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. 全部跑通后系统化检查报告（哪些严格对齐、哪些平台惯例偏离）