model

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Sep 3, 2026 License: MIT 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 {
	InputSchema map[string]any `json:"inputSchema,omitempty"`
}

ActionDecl 声明一个动作及可选 inputSchema（JSON Schema 可表达子集）。

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"`
}

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"`
	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 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.