docs(iot): 存量英文注释中文化（仅注释，代码零字节改动）
- 5 个文件：123 行英文注释 → 99 行中文注释（中文更紧凑，内容无删减）。 - 机械校验（git diff -U0 去掉 // 行与空行）输出为空；gofmt -l 干净（改动前亦干净）。 - 验收：go build/vet/test ./internal/iot/... 全绿。
This commit is contained in:
AskaEth committed
1 parent
127c32b440
commit
2593765add
5 files changed
+99
-123
No files matched your search
+39
-50
@@ -1,72 +1,62 @@
|
||||
// Package iot provides the IoT device source abstraction for Cyrene v2.
|
||||
// Package iot 提供 Cyrene v2 的 IoT 设备来源抽象。
|
||||
//
|
||||
// It models smart-home devices (light, AC, curtain, sensor, lock) as typed
|
||||
// devices managed by pluggable providers. A Provider is a device source; the
|
||||
// Manager selects a provider from configuration, exposes List/Control/Status,
|
||||
// and publishes device state transitions as events on the in-process bus so
|
||||
// other subsystems (frontend, memory, push) observe changes without polling
|
||||
// (DevDocs/02-development-constraints.md "IoT 设备状态 bus 事件驱动").
|
||||
// 它把智能家居设备（灯、空调、窗帘、传感器、门锁）建模为强类型设备，交由可插拔的
|
||||
// Provider 管理。Provider 即设备来源；Manager 依据配置选定 Provider，对外提供
|
||||
// List/Control/Status，并把设备状态跃迁作为事件发布到进程内 bus，使其他子系统
|
||||
// （前端、记忆、推送）无需轮询即可感知设备变化（对照
|
||||
// DevDocs/02-development-constraints.md "IoT 设备状态 bus 事件驱动"）。
|
||||
//
|
||||
// Milestone M5 delivers the pluggable provider skeleton plus a mock provider
|
||||
// with eight simulated devices and the control_rules that bound what each device
|
||||
// type supports. Real provider integrations (MQTT, Home Assistant) plug in later
|
||||
// through the same Provider interface.
|
||||
// 里程碑 M5 交付可插拔 Provider 骨架，外加一个 mock Provider：内置八台模拟设备，
|
||||
// 以及界定每种设备类型支持范围的 control_rules。真实 Provider 集成（MQTT、
|
||||
// Home Assistant）后续通过同一套 Provider 接口接入。
|
||||
package iot
|
||||
|
||||
import "errors"
|
||||
|
||||
// DeviceUpdateSubject is the bus subject on which device state transitions are
|
||||
// published. Subscribers use this subject (or "iot.>") to observe device
|
||||
// changes.
|
||||
// DeviceUpdateSubject 是设备状态跃迁事件发布所用的 bus 主题。订阅方使用该主题
|
||||
// （或 "iot.>"）观察设备变化。
|
||||
const DeviceUpdateSubject = "iot.device_update"
|
||||
|
||||
// Sentinel errors returned by the iot subsystem. Use errors.Is to test for them.
|
||||
// iot 子系统返回的哨兵错误，判定时请用 errors.Is。
|
||||
var (
|
||||
// ErrDeviceNotFound is returned when a device ID is unknown to every
|
||||
// registered provider.
|
||||
// ErrDeviceNotFound 表示该设备 ID 对全部已注册 Provider 均未知。
|
||||
ErrDeviceNotFound = errors.New("iot: device not found")
|
||||
// ErrUnsupported is returned when an action is not supported for a device's
|
||||
// type (the device type's capability constraint), or when an action
|
||||
// parameter value is outside the type's rule set.
|
||||
// ErrUnsupported 表示某动作不被该设备类型支持（受该类型的 capability 约束），
|
||||
// 或动作参数取值超出该类型的规则集合。
|
||||
ErrUnsupported = errors.New("iot: unsupported action")
|
||||
// ErrOffline is returned when a Control call targets an offline device.
|
||||
// ErrOffline 表示 Control 调用指向了离线设备。
|
||||
ErrOffline = errors.New("iot: device offline")
|
||||
// ErrInvalidParam is returned when an action parameter is missing or has the
|
||||
// wrong type.
|
||||
// ErrInvalidParam 表示动作参数缺失或类型错误。
|
||||
ErrInvalidParam = errors.New("iot: invalid parameter")
|
||||
// ErrUnknownProvider is returned when configuration names an unknown
|
||||
// provider.
|
||||
// ErrUnknownProvider 表示配置指定了未知的 Provider。
|
||||
ErrUnknownProvider = errors.New("iot: unknown provider")
|
||||
// ErrProviderNotRegistered is returned when a device operation is attempted
|
||||
// but no provider is registered (for example the "none" provider).
|
||||
// ErrProviderNotRegistered 表示尝试执行设备操作，但没有任何已注册的 Provider
|
||||
// （例如 "none" Provider）。
|
||||
ErrProviderNotRegistered = errors.New("iot: no provider registered")
|
||||
// ErrInvalidArgument is returned when an argument is nil or empty.
|
||||
// ErrInvalidArgument 表示传入参数为 nil 或空。
|
||||
ErrInvalidArgument = errors.New("iot: invalid argument")
|
||||
// ErrDuplicate is returned when a provider with the same name is registered
|
||||
// twice.
|
||||
// ErrDuplicate 表示同名 Provider 被注册了两次。
|
||||
ErrDuplicate = errors.New("iot: provider already registered")
|
||||
)
|
||||
|
||||
// Device is a single smart-home device exposed by a Provider.
|
||||
// Device 是由某个 Provider 暴露的单台智能家居设备。
|
||||
type Device struct {
|
||||
// ID is the globally unique device identifier used to target Control and
|
||||
// Status calls.
|
||||
// ID 是设备全局唯一标识，Control 与 Status 调用据此定位设备。
|
||||
ID string `json:"id"`
|
||||
// Name is the human-readable device label.
|
||||
// Name 是供人阅读的设备名称。
|
||||
Name string `json:"name"`
|
||||
// Type is the device kind, for example "light", "ac", "curtain", "sensor" or
|
||||
// "lock". The type determines the control_rules a Provider enforces.
|
||||
// Type 是设备种类，例如 "light"、"ac"、"curtain"、"sensor"、"lock"；
|
||||
// 类型决定 Provider 施加的 control_rules。
|
||||
Type string `json:"type"`
|
||||
// State holds the device's current key/value state; the keys depend on the
|
||||
// device Type.
|
||||
// State 保存设备当前的键值状态；具体键取决于设备的 Type。
|
||||
State map[string]any `json:"state"`
|
||||
// Online reports whether the device is currently reachable.
|
||||
// Online 表示设备当前是否可达。
|
||||
Online bool `json:"online"`
|
||||
}
|
||||
|
||||
// Clone returns a copy of d with an independent State map, so callers can mutate
|
||||
// the returned device without affecting the provider's internal state. Values in
|
||||
// State are copied by reference; the mock provider stores only primitives.
|
||||
// Clone 返回 d 的副本，其中 State 为独立 map，因此调用方可以随意修改返回的设备
|
||||
// 而不影响 Provider 的内部状态。State 中的值按引用复制；mock Provider 只存放
|
||||
// 基本类型值。
|
||||
func (d Device) Clone() Device {
|
||||
cp := d
|
||||
if d.State != nil {
|
||||
@@ -78,18 +68,17 @@ func (d Device) Clone() Device {
|
||||
return cp
|
||||
}
|
||||
|
||||
// DeviceUpdate is the payload published to DeviceUpdateSubject when a device
|
||||
// state transitions, typically as the result of a Control call.
|
||||
// DeviceUpdate 是设备状态跃迁时发布到 DeviceUpdateSubject 的载荷，通常由一次
|
||||
// Control 调用产生。
|
||||
type DeviceUpdate struct {
|
||||
// Provider is the name of the provider that owns the device.
|
||||
// Provider 是拥有该设备的 Provider 名称。
|
||||
Provider string `json:"provider"`
|
||||
// Device is the post-transition device snapshot.
|
||||
// Device 是跃迁后的设备快照。
|
||||
Device Device `json:"device"`
|
||||
// Action is the control action that produced the transition.
|
||||
// Action 是触发该次跃迁的控制动作。
|
||||
Action string `json:"action"`
|
||||
// Params are the optional control parameters.
|
||||
// Params 是可选的控制参数。
|
||||
Params map[string]any `json:"params,omitempty"`
|
||||
// Message is a human-readable summary of the transition, surfaced to the
|
||||
// frontend device_update feed.
|
||||
// Message 是跃迁的可读摘要，会呈现到前端的 device_update 信息流中。
|
||||
Message string `json:"message,omitempty"`
|
||||
}
|
||||
Reference in new issue
Block a user