docs/architecture.md

@@ -54,7 +54,7 @@ domain ────────────────────────>
 - `TemperatureHumidityGateway`：读取温度和湿度；
 - `InfraredGateway`：发送、学习和下载红外码。
 
-端口只覆盖需求和 ABSDK 0630 文档已经确认的行为。设备目录的增删改与二维码导入、遥控器布局、情景动作和持久化模型将在对应模块提出后增量加入，不在公共层提前假定。
+端口只覆盖需求和 ABSDK 0630 文档已经确认的行为。`DeviceId` 是 App 本地目录中的稳定记录标识；设备操作必须使用 ABSDK 0630 实际接受的 `DeviceName`。同一提供方配置和设备类型内，`DeviceName` 必须唯一，设备目录在添加、编辑和导入时负责强制该约束。设备目录的增删改与二维码导入、遥控器布局、情景动作和持久化模型将在对应模块提出后增量加入，不在公共层提前假定。
 
 ## 5. 结果与错误边界
 

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,

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)