From e45de7fefe35f9e09214b3a31881003724db2e3b Mon Sep 17 00:00:00 2001
From: KremeCN <3265494849@qq.com>
Date: Sat, 22 Aug 2026 22:29:25 +0800
Subject: [PATCH] docs: define ABSDK device name identity

---
 docs/architecture.md                                        | 2 +-
 .../kotlin/com/flagship/abox/manager/domain/Gateways.kt     | 1 +
 .../main/kotlin/com/flagship/abox/manager/domain/Models.kt  | 6 ++++++
 3 files changed, 8 insertions(+), 1 deletion(-)

diff --git a/docs/architecture.md b/docs/architecture.md
index 67ca28b..0b60a23 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -54,7 +54,7 @@ domain ────────────────────────>
 - `TemperatureHumidityGateway`：读取温度和湿度；
 - `InfraredGateway`：发送、学习和下载红外码。
 
-端口只覆盖需求和 ABSDK 0630 文档已经确认的行为。设备目录的增删改与二维码导入、遥控器布局、情景动作和持久化模型将在对应模块提出后增量加入，不在公共层提前假定。
+端口只覆盖需求和 ABSDK 0630 文档已经确认的行为。`DeviceId` 是 App 本地目录中的稳定记录标识；设备操作必须使用 ABSDK 0630 实际接受的 `DeviceName`。同一提供方配置和设备类型内，`DeviceName` 必须唯一，设备目录在添加、编辑和导入时负责强制该约束。设备目录的增删改与二维码导入、遥控器布局、情景动作和持久化模型将在对应模块提出后增量加入，不在公共层提前假定。
 
 ## 5. 结果与错误边界
 
diff --git a/domain/src/main/kotlin/com/flagship/abox/manager/domain/Gateways.kt b/domain/src/main/kotlin/com/flagship/abox/manager/domain/Gateways.kt
index c388d62..6fe9ee7 100644
--- a/domain/src/main/kotlin/com/flagship/abox/manager/domain/Gateways.kt
+++ b/domain/src/main/kotlin/com/flagship/abox/manager/domain/Gateways.kt
@@ -21,6 +21,7 @@ interface DeviceCatalog {
     ): Flow<DomainResult<List<DeviceDescriptor>>>
 }
 
+/** Operates vendor devices by [DeviceName], the identifier accepted by ABSDK 0630. */
 interface SocketGateway {
     suspend fun getStatus(
         profileId: ProviderProfileId,
diff --git a/domain/src/main/kotlin/com/flagship/abox/manager/domain/Models.kt b/domain/src/main/kotlin/com/flagship/abox/manager/domain/Models.kt
index 5b282fe..fe0828d 100644
--- a/domain/src/main/kotlin/com/flagship/abox/manager/domain/Models.kt
+++ b/domain/src/main/kotlin/com/flagship/abox/manager/domain/Models.kt
@@ -6,6 +6,12 @@ value class ProviderProfileId(val value: String)
 @JvmInline
 value class DeviceId(val value: String)
 
+/**
+ * Vendor-facing device identifier.
+ *
+ * Device names must be unique within the same provider profile and device type because
+ * ABSDK 0630 addresses devices by name rather than by the app's local [DeviceId].
+ */
 @JvmInline
 value class DeviceName(val value: String)