Help us shape the future of Go! Take the 2026 Go Developer Survey

model

package
v0.2.43 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 10, 2026 License: Apache-2.0 Imports: 4 Imported by: 0

Documentation

Overview

Package model 定义 CloudPath 的设备无关领域模型：Device / Entity / Capability / Observation / Event / Command / Descriptor，并负责对冻结契约 spec/descriptor.schema.json 与 spec/capability.schema.json 的校验。

本包是公共 SDK 的单一实现；internal/model 只做类型别名，禁止复制结构。

语义定义以 docs/architecture/capability-model.md 为准。本包只使用标准库， 不引入第三方 JSON Schema 依赖；校验器是两份 schema 的忠实 Go 实现。

Index

Constants

View Source 
const (
	// DescriptorSchemaID 是 spec/descriptor.schema.json 的 $id。
	DescriptorSchemaID = "cloudpath.dev/descriptor/v1"
	// CapabilityAPIVersion 是 capability.schema.json 中 apiVersion 的唯一合法值。
	CapabilityAPIVersion = "capabilities.cloudpath.dev/v1alpha1"
	// CapabilityKind 是 capability.schema.json 中 kind 的唯一合法值。
	CapabilityKind = "Capability"
)

冻结契约中的 schema 标识。

Variables

This section is empty.

Functions

This section is empty.

Types

type ActionDecl 

type ActionDecl struct {
	Title       string         `json:"title,omitempty"`
	Description string         `json:"description,omitempty"`
	I18n        I18n           `json:"i18n,omitempty"`
	InputSchema map[string]any `json:"inputSchema,omitempty"`
	// Destructive 和 Confirmation 必须跨 Driver/Edge/Server 转发，不能在 UI 前丢失。
	// 它们驱动操作确认，不替代服务端权限或设备侧校验。
	Destructive  bool   `json:"destructive,omitempty"`
	Confirmation string `json:"confirmation,omitempty"`
}

ActionDecl 声明一个动作及可选 title/description/inputSchema 与交互安全提示。 title/description 是纯呈现提示（schema-driven UI 用它们渲染说明与参数控件）， 不是语义真相；前端不得因其缺失而存不到可下发命令（命令集仍以 action 键为准）。

type Capability 

type Capability struct {
	APIVersion string             `json:"apiVersion"`
	Kind       string             `json:"kind"`
	Metadata   CapabilityMetadata `json:"metadata"`
	Spec       CapabilitySpec     `json:"spec"`
}

Capability 描述 Entity「能做什么」，由稳定 ID 与独立版本标识， 对应 spec/capability.schema.json。未知 Capability 仍可保存和转发， 只是 Core UI 回落为通用 JSON/表格视图。

func (Capability) Validate 

func (c Capability) Validate() error

Validate 按 capability.schema.json 校验 Capability： apiVersion / kind 常量、metadata.id pattern、version 非负， property access / quality 枚举合法。

type CapabilityMetadata 

type CapabilityMetadata struct {
	ID      string `json:"id"`
	Version int    `json:"version"`
	Title   string `json:"title,omitempty"`
	I18n    I18n   `json:"i18n,omitempty"`
}

CapabilityMetadata 是 Capability 的标识元数据。机器 ID 不得本地化， 破坏性变化发布 @2 而不是原地改语义。

type CapabilitySpec 

type CapabilitySpec struct {
	Properties   map[string]Property   `json:"properties,omitempty"`
	Events       map[string]EventDecl  `json:"events,omitempty"`
	Actions      map[string]ActionDecl `json:"actions,omitempty"`
	Presentation map[string]any        `json:"presentation,omitempty"`
}

CapabilitySpec 声明 Properties / Events / Actions 与 UI Hints。 presentation 只是渲染提示，不是语义真相。

type Command 

type Command struct {
	CommandID      string         `json:"command_id"`
	IdempotencyKey string         `json:"idempotency_key"`
	EntityID       string         `json:"entity_id"`
	Action         string         `json:"action"`
	Args           map[string]any `json:"args,omitempty"`
	Deadline       time.Time      `json:"deadline"`
	Actor          string         `json:"actor"`
	Status         CommandStatus  `json:"status"`
	Result         any            `json:"result,omitempty"`
	Error          string         `json:"error,omitempty"`
	CreatedAt      time.Time      `json:"created_at,omitempty"`
	UpdatedAt      time.Time      `json:"updated_at,omitempty"`
}

Command 是有生命周期、幂等键和超时语义的动作请求。

action 指向 Capability 声明的 Action；args 是 JSON 对象参数。 idempotency_key 保证同一逻辑命令重复下发只执行一次。

func NewCommand 

func NewCommand(commandID, idempotencyKey, entityID, action string, args map[string]any, deadline time.Time, actor string) Command

NewCommand 构造一条 CREATED 状态的 Command。

func (*Command) Transition 

func (c *Command) Transition(next CommandStatus) error

Transition 把命令推进到 next。只有契约状态机允许的相邻转移才会成功； 非法状态、同态空转与从终态出发都会返回错误且不修改 Status。

func (Command) Validate 

func (c Command) Validate() error

Validate 校验 Command：必需字段非空、deadline 存在、状态合法。

type CommandStatus 

type CommandStatus string

CommandStatus 是 Command 生命周期状态。

状态机（docs/architecture/capability-model.md §4）： 

CREATED → DISPATCHED → ACCEPTED → RUNNING
                                └→ SUCCEEDED / FAILED / TIMED_OUT / CANCELLED

const (
	CommandCreated    CommandStatus = "CREATED"
	CommandDispatched CommandStatus = "DISPATCHED"
	CommandAccepted   CommandStatus = "ACCEPTED"
	CommandRunning    CommandStatus = "RUNNING"
	CommandSucceeded  CommandStatus = "SUCCEEDED"
	CommandFailed     CommandStatus = "FAILED"
	CommandTimedOut   CommandStatus = "TIMED_OUT"
	CommandCancelled  CommandStatus = "CANCELLED"
)

func (CommandStatus) Terminal 

func (s CommandStatus) Terminal() bool

Terminal 报告 s 是否为终态。

func (CommandStatus) Valid 

func (s CommandStatus) Valid() bool

Valid 报告 s 是否为合法状态。

type Descriptor 

type Descriptor struct {
	DeviceID     string       `json:"device_id"`
	ExternalID   string       `json:"external_id"`
	Manufacturer string       `json:"manufacturer,omitempty"`
	Model        string       `json:"model,omitempty"`
	Status       DeviceStatus `json:"status"`
	Entities     []Entity     `json:"entities"`
}

Descriptor 是 Edge/Adapter 上报给 Core 与前端 SchemaRenderer 的设备描述， 与 spec/descriptor.schema.json 一一对应（A1 生产、A2 消费）。

Descriptor 是 State.Raw 到 typed 模型的迁移载体：Adapter 同时发布 Raw 与 Descriptor，Core 从 Descriptor 建立 Entity/Capability 注册表，旧 Raw 保留 在诊断字段，二者并存。

func (Descriptor) Validate 

func (d Descriptor) Validate() error

Validate 按 descriptor.schema.json 校验 Descriptor： device_id / external_id / status / entities 必填且语义合法， entity_id 在设备内唯一，嵌套 Entity / Observation 递归校验。

type Device 

type Device struct {
	DeviceID         string       `json:"device_id"`
	ExternalID       string       `json:"external_id"`
	PluginInstanceID string       `json:"plugin_instance_id,omitempty"`
	TenantID         string       `json:"tenant_id,omitempty"`
	EdgeID           string       `json:"edge_id,omitempty"`
	Manufacturer     string       `json:"manufacturer,omitempty"`
	Model            string       `json:"model,omitempty"`
	Status           DeviceStatus `json:"status"`
	Entities         []Entity     `json:"entities,omitempty"`
}

Device 是一台物理或虚拟设备，由 Driver 发现和维护。

device_id 是 Core 内稳定 ID，不得使用串口名（COM3 / /dev/ttyUSB0 会漂移， 只能作为当前连接属性）。external_id 是 Driver 范围内不可变 ID。

func (Device) Validate 

func (d Device) Validate() error

Validate 校验 Device：必需标识非空、状态合法，并递归校验每个 Entity。 与 Descriptor 不同，Entities 在完整模型中允许暂缺（发现流程可先建 Device）。

type DeviceStatus 

type DeviceStatus string

DeviceStatus 是设备在线状态（descriptor.schema.json status 枚举）。 

const (
	DeviceOnline      DeviceStatus = "online"
	DeviceOffline     DeviceStatus = "offline"
	DeviceUnavailable DeviceStatus = "unavailable"
	DeviceDegraded    DeviceStatus = "degraded"
)

func (DeviceStatus) Valid 

func (s DeviceStatus) Valid() bool

Valid 报告 s 是否为契约允许的设备状态。

type Entity 

type Entity struct {
	EntityID     string                 `json:"entity_id"`
	UniqueKey    string                 `json:"unique_key"`
	Name         string                 `json:"name,omitempty"`
	I18n         I18n                   `json:"i18n,omitempty"`
	Category     EntityCategory         `json:"category"`
	Capabilities []string               `json:"capabilities"`
	Observations map[string]Observation `json:"observations,omitempty"`
}

Entity 是 Device 下可独立观察、控制、命名和授权的逻辑单元。

unique_key 由 Driver 生成，用户不可修改；entity_id 是平台稳定 ID， 端口/Edge 重连与 Driver 重启都不应改变。

func (Entity) Validate 

func (e Entity) Validate() error

Validate 校验 Entity：必需标识非空、分类合法、capability 引用非空， 并递归校验内嵌 Observation。

type EntityCategory 

type EntityCategory string

EntityCategory 是 Entity 的分类。 

const (
	EntitySensor     EntityCategory = "sensor"
	EntityActuator   EntityCategory = "actuator"
	EntityDiagnostic EntityCategory = "diagnostic"
	EntityConfig     EntityCategory = "config"
)

func (EntityCategory) Valid 

func (c EntityCategory) Valid() bool

Valid 报告 c 是否为契约允许的 Entity 分类。

type Event 

type Event struct {
	EntityID   string         `json:"entity_id,omitempty"`
	Type       string         `json:"type"`
	OccurredAt time.Time      `json:"occurred_at"`
	ReceivedAt time.Time      `json:"received_at,omitempty"`
	Payload    map[string]any `json:"payload,omitempty"`
}

Event 是不可覆盖的时间点事实（如 opened、alarm-fired、device-booted）。

Type 属于 Capability 或 Application 命名空间（例如 cloudpath.dev/capability/contact@1/opened），不维护平台级业务事件枚举。 EntityID 对设备级事件（device-booted）可省略。

func (Event) Validate 

func (e Event) Validate() error

Validate 校验 Event：type 非空、occurred_at 必须存在。

type EventDecl 

type EventDecl struct {
	PayloadSchema map[string]any `json:"payloadSchema,omitempty"`
}

EventDecl 声明一个事件及可选 payloadSchema（JSON Schema 可表达子集）。

type I18n added in v0.2.23 

type I18n map[string]string

I18n 是插件声明文本的可选 locale -> 文本映射。键为 locale（如 zh-CN）， 值为展示文本；机器 ID、URI 和 property key 永远不进入本映射。 Action 同时需要 title/description 时，description 使用 "<locale>.description" 键。

type Observation 

type Observation struct {
	EntityID   string    `json:"entity_id,omitempty"`
	Capability string    `json:"capability"`
	Property   string    `json:"property"`
	Value      any       `json:"value"`
	Unit       string    `json:"unit,omitempty"`
	Quality    Quality   `json:"quality,omitempty"`
	ObservedAt time.Time `json:"observed_at,omitempty"`
	ReceivedAt time.Time `json:"received_at,omitempty"`
	Sequence   int64     `json:"sequence,omitempty"`
}

Observation 是可形成当前状态的观测值（数据三分法之一）。

observed_at 可来自设备；received_at 必须由可信的 Edge/Core 生成。 设备时钟不可信时以 received_at 为准并标注质量。sequence 是单调递增序号， 供乱序检测与去重。

func (Observation) Validate 

func (o Observation) Validate() error

Validate 按 descriptor.schema.json 的 Observation 定义校验。 value 为必填键：JSON null 视同缺失并拒绝（调用方应以真实数据构造）。 observed_at / received_at 的 RFC3339 合法性在 JSON 解码时由 time.Time 保证。

type Property 

type Property struct {
	Type    string         `json:"type,omitempty"`
	Unit    string         `json:"unit,omitempty"` // 统一单位代码，不得用本地化文本
	Access  PropertyAccess `json:"access,omitempty"`
	Quality []Quality      `json:"quality,omitempty"`
}

Property 是一个数据点声明。

type PropertyAccess 

type PropertyAccess string

PropertyAccess 是 Property 的读写权限。 

const (
	PropertyRead      PropertyAccess = "read"
	PropertyWrite     PropertyAccess = "write"
	PropertyReadWrite PropertyAccess = "readwrite"
)

func (PropertyAccess) Valid 

func (a PropertyAccess) Valid() bool

Valid 报告 a 是否为契约允许的访问模式。空值表示未声明（可选缺省）。

type Quality 

type Quality string

Quality 是观测质量等级（Observation 与 Property 共用）。 

const (
	QualityGood        Quality = "good"
	QualityUncertain   Quality = "uncertain"
	QualityBad         Quality = "bad"
	QualityUnavailable Quality = "unavailable"
)

func (Quality) Valid 

func (q Quality) Valid() bool

Valid 报告 q 是否为契约允许的质量等级。

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.