Refactor: Localization singleton, Gen3 BLE handshake, error handling & docs#1
Open
dallascyclist wants to merge 8 commits into
Conversation
Add project guidance file (CLAUDE.md) with architecture docs, build instructions, and git identity config. Include 18 API documentation PDFs in Docs/. Refactored BLE manager, home controller, and Bluetooth list controller with bilingual logging and cleaner structure.
Ignore xcuserdata/ directories. Document SSH remote alias and key configuration in CLAUDE.md.
Comprehensive architecture reference covering all 18 QIUI API endpoints, BLE protocol details, app workflow sequence diagrams, source file function maps with line numbers, and 9 known issues identified during analysis.
- Add complete Gen3 BLE challenge-response handshake protocol: write device token to BLE, read device response, validate via decryBluetoothCommand API before lock/unlock commands - Fix CellMate API endpoints (was using KeyPod URLs) - Fix BLE UUIDs for Gen3: FEE7/36F5/36F6 (was FFF0/FFF1/FFF2) - Add hex-to-data conversion for proper BLE byte transmission - Add prerequisite validation with alert feedback on all buttons - Fix API error extraction: check both 'message' and 'msg' keys - Fix typeId/expiresTime NSNumber-to-NSString conversion - Add progress HUD with status updates during BLE handshake - Number buttons 1-8 with bilingual Chinese/English labels in XIB - Add showAlert helper to reduce UIAlertController duplication - Add detailed debug logging for lock/unlock request/response
Document the challenge-response handshake flow, CellMate endpoint table, BLE UUID differences between Gen2/Gen3, error response format inconsistency, XIB outlet mismatch warning, and developer portal link.
Consolidate three per-file localization dictionaries into a single QIUILocalization singleton with 47 keys organized by prefix (ble.*, scan.*, api.*, step.*, cmd.*, hud.*). Language detection runs once at launch; fallback chain: detected → zh-Hans → raw key. - Fix 3 swallowed network errors in selectorBtn1/3/4 (missing if-error guards) - Fix 5 missing scan keys that logged (null) during device testing - Replace ~30 hardcoded English alert/HUD strings with L() calls - Remove inline LocalizedMessages() from all three source files
Add Localization section covering singleton usage, L() macro, key prefix conventions, fallback chain, and how to add strings or new languages.
CLAUDE.md contains local development config (git identity, SSH aliases) not relevant to the upstream project.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary / 摘要
This PR refactors the QIUI-API demo app to improve developer experience, fix bugs found during live device testing, and add comprehensive documentation.
本PR重构了QIUI-API示例应用，改善了开发者体验，修复了真机测试中发现的Bug，并添加了完整的文档。
Changes / 变更内容
1. Centralized Localization / 统一本地化
Before / 之前: Three separate inline
LocalizedMessages()dictionaries scattered acrossHKBabyBluetoothManager.m,APIBuletoothListViewController.m, andAPIHomeViewController.m.After / 之后: Single
QIUILocalizationsingleton (QIUILocalization.h/.m) withL()macro. 47 bilingual keys (zh-Hans + en) organized by prefix (ble.*,scan.*,api.*,step.*,cmd.*,hud.*). Language detected once at startup. Fallback chain: detected language → zh-Hans → raw key.之前: 三个独立的
LocalizedMessages()字典分散在HKBabyBluetoothManager.m、APIBuletoothListViewController.m和APIHomeViewController.m中。之后: 统一的
QIUILocalization单例类，使用L()宏。47个中英双语键值，按前缀分类。启动时检测语言，回退链：检测语言 → zh-Hans → 原始键名。2. Gen3 BLE Handshake Protocol / 三代BLE握手协议
Implemented the complete challenge-response handshake required by Gen3 (Cag Ink III / typeId 10) devices:
buildCellMatePro4GTokenCmdAPI36F536F6notificationdecryBluetoothCommandAPIBLEPendingOperationenum) routes BLE responses correctly实现了三代设备（Cag Ink III / typeId 10）所需的完整挑战-响应握手：
buildCellMatePro4GTokenCmdAPI获取Token命令36F536F6通知读取设备响应decryBluetoothCommandAPI验证会话BLEPendingOperation枚举）正确路由BLE响应3. Error Handling Fixes / 错误处理修复
Swallowed network errors: Added
if (error)guards to 3 AFNetworking completion handlers that were silently failing (Btn1/Btn3/Btn4).API error key mismatch: API returns
"msg"on errors but code only checked"message". Now checks both:json[@"message"] ?: json[@"msg"].User-facing alerts: Prerequisite validation (buttons pressed out of order) now shows
UIAlertControlleralerts instead of only logging to console.网络错误被吞没: 为3个AFNetworking回调添加了
if (error)错误守卫（按钮1/3/4）。API错误键不匹配: API错误返回
"msg"但代码只检查"message"，现在两个都检查。用户提示: 前置步骤验证现在显示
UIAlertController提示，而不是仅打印日志。4. Documentation / 文档
ARCHITECTURE.md: Complete technical reference with API endpoints, BLE protocol, and data flow diagrams.
Bilingual button labels: XIB updated with English subtitles on all 8 workflow buttons.
ARCHITECTURE.md: 完整技术参考，包含API端点、BLE协议、数据流图。
双语按钮标签: XIB已更新，8个工作流按钮添加了英文副标题。
5. Minor Fixes / 其他修复
Fixed 5 missing localization keys that logged
(null)during BLE scanning.Switched from KeyPod API endpoints to CellMate Pro 4G endpoints for Gen3 devices.
Added
.gitignoreforxcuserdata/.Added Xcode shared scheme for CI builds.
修复了BLE扫描时打印
(null)的5个缺失本地化键。将KeyPod API端点切换为CellMate Pro 4G端点以支持三代设备。
添加
.gitignore排除xcuserdata/。添加Xcode共享Scheme支持CI构建。
Files Changed / 修改的文件
QIUILocalization.h/.mAPIHomeViewController.mAPIHomeViewController.xibAPIBuletoothListViewController.mHKBabyBluetoothManager.mproject.pbxprojARCHITECTURE.md.gitignoreTest Plan / 测试计划
xcodebuildclean build)