chore: 提交高层 xiaomi 封装库及示例

- 新增 xiaomi/examples/ 下 8 个示例程序（用户/家庭查询、设备列表、开关/灯光/空调控制、属性订阅、高级过滤分类、SPEC 解析） - miot_client_sub.go: 重构 SubProp/SubEvent，使用 buildPropTopic/buildEventTopic 支持通配符订阅（siid/piid=0 → +），并修复锁顺序问题（将 RequestRefreshProp 移到 Lock 外） - spec_parser.go: 新增 downloadSpecFile 方法，本地 SPEC 文件缺失时自动从 miot-spec.org 下载 - ARCH_PLAN.md: 架构设计从 Proposed 更新为 Accepted（v1.0→v1.1），补充设备分类/工厂/SPEC 映射等模块设计 - xiaomi/: 新增 miot 上层强类型封装模块，包含 Client 主入口、用户/家庭/设备 API、属性读写、动作调用、订阅通知，以及 devices/ 设备控制抽象（Switch/Light/AirConditioner/Fan/Cover/Humidifier/Vacuum/WaterHeater/Thermostat）和 specs/ SPEC 查询辅助 - 更多 xiaomi 示例（风扇/窗帘/传感器控制）
2026-06-29 08:51:21 +08:00
parent 35efed7d15
commit a3d94c4b9f
93 changed files with 7582 additions and 157 deletions
@@ -0,0 +1,115 @@
+package devices
+
+import (
+	"xiaomihome/xiaomi"
+)
+
+// Create creates the appropriate device control interface for the given device.
+// It uses the device's URN (SPEC type) to determine which control interface to return.
+//
+// Returns:
+//   - Switch, Light, AirConditioner, Fan, Cover, Humidifier, Vacuum,
+//     WaterHeater, or Thermostat depending on the device type
+//   - nil, nil if the device type is not recognized (no error, just unsupported)
+//   - an error if there was a problem creating the control
+//
+// Usage:
+//
+//	info, _ := client.GetDevice(ctx, "some-did")
+//	ctrl, err := devices.Create(client, info)
+//	switch d := ctrl.(type) {
+//	case devices.Switch:
+//	    d.TurnOn(ctx)
+//	case devices.Light:
+//	    d.SetBrightness(ctx, 80)
+//	}
+func Create(client *xiaomi.Client, info *xiaomi.DeviceInfo) (interface{}, error) {
+	return createImpl(client, info)
+}
+
+// NewDevice creates the appropriate device control interface, returning the
+// common Device interface. Use type switch to access type-specific methods:
+//
+//	dev, err := devices.NewDevice(client, info)
+//	switch d := dev.(type) {
+//	case devices.Switch:
+//	    d.TurnOn(ctx)
+//	case devices.Light:
+//	    d.SetBrightness(ctx, 80)
+//	}
+func NewDevice(client *xiaomi.Client, info *xiaomi.DeviceInfo) (Device, error) {
+	ctrl, err := createImpl(client, info)
+	if err != nil {
+		return nil, err
+	}
+	if ctrl == nil {
+		return nil, nil
+	}
+	return ctrl.(Device), nil
+}
+
+// createImpl is the internal implementation shared by Create and NewDevice.
+func createImpl(client *xiaomi.Client, info *xiaomi.DeviceInfo) (interface{}, error) {
+	if info == nil {
+		return nil, xiaomi.ErrDeviceNotFound
+	}
+
+	urn := info.URN
+
+	// Determine device type from URN and try constructors in order
+	var ctrl interface{}
+	var err error
+
+	// URN-based routing
+	// miot-spec-v2: air-conditioner → urn:miot-spec-v2:device:air-conditioner:...
+	// miot-spec-v2: light → urn:miot-spec-v2:device:light:...
+	// etc.
+	switch {
+	case matchURN(urn, "air-conditioner", "airer", "air-condition-outlet", "air-condition-eco", "ac-partner"):
+		ctrl, err = NewAirConditioner(client, info)
+	case matchURN(urn, "light", "lightbulb", "night-light", "ceiling-light"):
+		ctrl, err = NewLight(client, info)
+	case matchURN(urn, "switch", "outlet", "powerstrip", "toggle-switch", "wireless-switch", "curtain-switch"):
+		ctrl, err = NewSwitch(client, info)
+	case matchURN(urn, "fan", "ceiling-fan", "ventilator", "air-fresh", "air-purifier"):
+		ctrl, err = NewFan(client, info)
+	case matchURN(urn, "curtain", "airer-rack", "airer"):
+		ctrl, err = NewCover(client, info)
+	case matchURN(urn, "humidifier", "dehumidifier", "humidifier-dehumidifier"):
+		ctrl, err = NewHumidifier(client, info)
+	case matchURN(urn, "vacuum", "sweeper", "robot-cleaner"):
+		ctrl, err = NewVacuum(client, info)
+	case matchURN(urn, "water-heater", "water-cooler", "kettle"):
+		ctrl, err = NewWaterHeater(client, info)
+	case matchURN(urn, "heater", "electric-blanket", "thermostat"):
+		ctrl, err = NewThermostat(client, info)
+	case matchURN(urn, "sensor-occupy", "motion-sensor", "magnet"):
+		ctrl, err = NewOccupancySensor(client, info)
+	case matchURN(urn, "sensor-temp", "sensor-humidity", "sensor-ht", "sensor-smoke", "sensor-gasm", "illumination"):
+		ctrl, err = NewTempHumiditySensor(client, info)
+	default:
+		// Not a supported device type — not an error, just returns nil
+		return nil, nil
+	}
+
+	if err != nil {
+		return nil, err
+	}
+
+	return ctrl, nil
+}
+
+// matchURN checks if the device URN contains any of the given type strings.
+func matchURN(urn string, types ...string) bool {
+	for _, t := range types {
+		if len(urn) >= len(t) {
+			// Simple substring match — URN format: urn:miot-spec-v2:device:TYPE:...
+			for i := 0; i <= len(urn)-len(t); i++ {
+				if urn[i:i+len(t)] == t {
+					return true
+				}
+			}
+		}
+	}
+	return false
+}