feat: establish Orbit models, migrations and development baseline

platform/model/application.go

@@ -0,0 +1,26 @@
+package model
+
+import (
+	"time"
+
+	core "git.yuntuo.hk/k2safe/orbit/model"
+)
+
+// Application 表示接入应用，承载通用应用身份与启停配置。
+// 对应表 orbit_applications；这是服务端持久化模型，不直接作为 API 响应。
+type Application struct {
+	// ID 应用标识，全局唯一。
+	ID core.ID `db:"id"`
+	// Revision 乐观并发版本，从 1 开始；更新时必须核对预期版本。
+	Revision uint64 `db:"revision"`
+	// CreatedAt 创建时间，统一 UTC，数据库精度为微秒。
+	CreatedAt time.Time `db:"created_at"`
+	// UpdatedAt 最后写入时间，统一 UTC；不能代替并发版本。
+	UpdatedAt time.Time `db:"updated_at"`
+	// Name 可读名称，唯一性范围由对应数据表约束。
+	Name string `db:"name"`
+	// Enabled 是否启用；关闭后拒绝相应的新接入或新操作。
+	Enabled bool `db:"enabled"`
+}
+
+func (Application) TableName() string { return "orbit_applications" }

platform/model/audit_event.go

@@ -0,0 +1,32 @@
+package model
+
+import (
+	core "git.yuntuo.hk/k2safe/orbit/model"
+)
+
+// AuditEvent 表示不可改写的管理审计，保留操作身份、原因和变更摘要。
+// 对应表 orbit_audit_events；这是服务端持久化模型，不直接作为 API 响应。
+type AuditEvent struct {
+	// Record 包含命名空间、记录标识、并发版本和 UTC 时间。
+	core.Record
+	// OperationID 管理操作的稳定身份，重复操作必须保留同一身份。
+	OperationID core.ID `db:"operation_id"`
+	// ActorID 经认证的操作主体标识，不能直接信任请求自报值。
+	ActorID string `db:"actor_id"`
+	// Action 执行的管理动作，例如暂停、取消或核查。
+	Action string `db:"action"`
+	// ResourceKind 关联资源类型；多态关联需要服务层额外校验。
+	ResourceKind string `db:"resource_kind"`
+	// ResourceID 关联资源标识，不能单独作为访问授权依据。
+	ResourceID core.ID `db:"resource_id"`
+	// Reason 操作原因或处理说明，需要保留审计信息。
+	Reason string `db:"reason"`
+	// Before 操作前的受控摘要 JSON，须脱敏。
+	Before core.JSON `db:"before"`
+	// After 操作后的受控摘要 JSON，须脱敏。
+	After core.JSON `db:"after"`
+	// EvidenceRef 业务核查证据的引用；为空表示没有附加引用。
+	EvidenceRef *string `db:"evidence_ref"`
+}
+
+func (AuditEvent) TableName() string { return "orbit_audit_events" }

platform/model/credential.go

@@ -0,0 +1,26 @@
+package model
+
+import (
+	"time"
+
+	core "git.yuntuo.hk/k2safe/orbit/model"
+)
+
+// Credential 表示命名空间凭据，只保存秘密摘要和授权范围。
+// 对应表 orbit_credentials；这是服务端持久化模型，不直接作为 API 响应。
+type Credential struct {
+	// Record 包含命名空间、记录标识、并发版本和 UTC 时间。
+	core.Record
+	// Name 可读名称，唯一性范围由对应数据表约束。
+	Name string `db:"name"`
+	// SecretDigest 凭据秘密的 SHA-256 摘要，不保存或输出原文。
+	SecretDigest core.Digest `db:"secret_digest"`
+	// Permissions 授权范围的 JSON 快照，必须由服务端解释和校验。
+	Permissions core.JSON `db:"permissions"`
+	// ExpiresAt 凭据过期时间，统一 UTC；为空表示没有配置到期时间。
+	ExpiresAt *time.Time `db:"expires_at"`
+	// RevokedAt 撤销时间；为空表示尚未撤销。
+	RevokedAt *time.Time `db:"revoked_at"`
+}
+
+func (Credential) TableName() string { return "orbit_credentials" }

platform/model/delivery.go

@@ -0,0 +1,34 @@
+package model
+
+import (
+	"time"
+
+	core "git.yuntuo.hk/k2safe/orbit/model"
+)
+
+// Delivery 表示单个事件向一个订阅的可靠交付记录。
+// 对应表 orbit_deliveries；这是服务端持久化模型，不直接作为 API 响应。
+type Delivery struct {
+	// Record 包含命名空间、记录标识、并发版本和 UTC 时间。
+	core.Record
+	// SubscriptionID 目标订阅标识。
+	SubscriptionID core.ID `db:"subscription_id"`
+	// EventID 来源持久化事件标识，用于消费去重。
+	EventID core.ID `db:"event_id"`
+	// State 当前状态；只允许定义的状态转换并配合事务校验。
+	State DeliveryState `db:"state"`
+	// AvailableAt 该事件最早允许再次交付的时间，统一 UTC。
+	AvailableAt time.Time `db:"available_at"`
+	// LeaseOwner 租约持有者标识；未持有租约时为空。
+	LeaseOwner *core.ID `db:"lease_owner"`
+	// LeaseEpoch 递增的执行或消费代次，用于隔离旧授权。
+	LeaseEpoch uint64 `db:"lease_epoch"`
+	// LeaseUntil 交付租约截止时间；没有交付租约时为空。
+	LeaseUntil *time.Time `db:"lease_until"`
+	// Attempts 已产生的交付尝试次数，不等同于业务执行次数。
+	Attempts uint32 `db:"attempts"`
+	// AcknowledgedAt 接收方可靠处理后的确认时间；未确认时为空。
+	AcknowledgedAt *time.Time `db:"acknowledged_at"`
+}
+
+func (Delivery) TableName() string { return "orbit_deliveries" }

platform/model/event.go

@@ -0,0 +1,28 @@
+package model
+
+import (
+	"time"
+
+	core "git.yuntuo.hk/k2safe/orbit/model"
+)
+
+// Event 表示追加保存的状态事件，供外部订阅或内部流程接续。
+// 对应表 orbit_events；这是服务端持久化模型，不直接作为 API 响应。
+type Event struct {
+	// Record 包含命名空间、记录标识、并发版本和 UTC 时间。
+	core.Record
+	// AggregateKind 产生事件的聚合类型，例如任务或流程。
+	AggregateKind string `db:"aggregate_kind"`
+	// AggregateID 产生事件的聚合标识。
+	AggregateID core.ID `db:"aggregate_id"`
+	// AggregateRevision 来源聚合的状态版本，用于去重与迟到事件判断。
+	AggregateRevision uint64 `db:"aggregate_revision"`
+	// Type 事件或信号的稳定类型标识。
+	Type string `db:"type"`
+	// Payload 版本化输入或事件内容；仅承载通用 JSON，不解释行业规则。
+	Payload core.JSON `db:"payload"`
+	// OccurredAt 事件发生时间，统一 UTC。
+	OccurredAt time.Time `db:"occurred_at"`
+}
+
+func (Event) TableName() string { return "orbit_events" }

platform/model/idempotency_key.go

@@ -0,0 +1,32 @@
+package model
+
+import (
+	"time"
+
+	core "git.yuntuo.hk/k2safe/orbit/model"
+)
+
+// IdempotencyKey 表示请求幂等记录，关联语义摘要与首次受理响应。
+// 对应表 orbit_idempotency_keys；这是服务端持久化模型，不直接作为 API 响应。
+type IdempotencyKey struct {
+	// Record 包含命名空间、记录标识、并发版本和 UTC 时间。
+	core.Record
+	// Operation 稳定操作类型，用于区分不同接口的幂等作用域。
+	Operation string `db:"operation"`
+	// ScopeKey 资源作用域标识；空字符串表示当前操作的默认作用域。
+	ScopeKey string `db:"scope_key"`
+	// KeyDigest 稳定幂等键或资源键的 SHA-256 摘要。
+	KeyDigest core.Digest `db:"key_digest"`
+	// RequestDigest 规范化请求语义的 SHA-256 摘要，用于识别同键不同内容。
+	RequestDigest core.Digest `db:"request_digest"`
+	// ResourceKind 关联资源类型；多态关联需要服务层额外校验。
+	ResourceKind string `db:"resource_kind"`
+	// ResourceID 关联资源标识，不能单独作为访问授权依据。
+	ResourceID core.ID `db:"resource_id"`
+	// Response 首次可靠提交后的响应 JSON，供重复请求补取确认。
+	Response core.JSON `db:"response"`
+	// ExpiresAt 幂等保留截止时间，不应短于约定的重发与恢复窗口。
+	ExpiresAt time.Time `db:"expires_at"`
+}
+
+func (IdempotencyKey) TableName() string { return "orbit_idempotency_keys" }

platform/model/namespace.go

@@ -0,0 +1,30 @@
+package model
+
+import (
+	"time"
+
+	core "git.yuntuo.hk/k2safe/orbit/model"
+)
+
+// Namespace 表示应用在指定环境中的资源隔离边界。
+// 对应表 orbit_namespaces；这是服务端持久化模型，不直接作为 API 响应。
+type Namespace struct {
+	// ID 命名空间标识，全局唯一。
+	ID core.ID `db:"id"`
+	// Revision 乐观并发版本，从 1 开始；更新时必须核对预期版本。
+	Revision uint64 `db:"revision"`
+	// CreatedAt 创建时间，统一 UTC，数据库精度为微秒。
+	CreatedAt time.Time `db:"created_at"`
+	// UpdatedAt 最后写入时间，统一 UTC；不能代替并发版本。
+	UpdatedAt time.Time `db:"updated_at"`
+	// ApplicationID 所属应用标识。
+	ApplicationID core.ID `db:"application_id"`
+	// Name 可读名称，唯一性范围由对应数据表约束。
+	Name string `db:"name"`
+	// Environment 环境标识，用于区分开发、测试和生产等隔离范围。
+	Environment string `db:"environment"`
+	// Enabled 是否启用；关闭后拒绝相应的新接入或新操作。
+	Enabled bool `db:"enabled"`
+}
+
+func (Namespace) TableName() string { return "orbit_namespaces" }

platform/model/state.go

@@ -0,0 +1,10 @@
+package model
+
+type DeliveryState string
+
+const (
+	DeliveryPending DeliveryState = "PENDING"
+	DeliveryLeased  DeliveryState = "LEASED"
+	DeliveryAcked   DeliveryState = "ACKED"
+	DeliveryExpired DeliveryState = "EXPIRED"
+)

platform/model/subscription.go

@@ -0,0 +1,22 @@
+package model
+
+import (
+	core "git.yuntuo.hk/k2safe/orbit/model"
+)
+
+// Subscription 表示事件订阅配置，绑定授权凭据及过滤规则。
+// 对应表 orbit_subscriptions；这是服务端持久化模型，不直接作为 API 响应。
+type Subscription struct {
+	// Record 包含命名空间、记录标识、并发版本和 UTC 时间。
+	core.Record
+	// Name 可读名称，唯一性范围由对应数据表约束。
+	Name string `db:"name"`
+	// CredentialID 关联的命名空间凭据标识。
+	CredentialID core.ID `db:"credential_id"`
+	// Filter 订阅过滤规则的 JSON 文档。
+	Filter core.JSON `db:"filter"`
+	// Enabled 是否启用；关闭后拒绝相应的新接入或新操作。
+	Enabled bool `db:"enabled"`
+}
+
+func (Subscription) TableName() string { return "orbit_subscriptions" }