42 lines
2.3 KiB
Markdown
42 lines
2.3 KiB
Markdown
# 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. 全部跑通后系统化检查报告（哪些严格对齐、哪些平台惯例偏离）
|