yms-daemon/internal/daemonapi/protocol.go

// Package daemonapi 定义了守护进程服务与命令行客户端之间通过本地 Unix Socket 传输的请求与响应协议。
// 该包只承载协议相关的常量与数据结构，不包含任何网络收发逻辑，
// 供 daemonclient 与 daemonserver 双方共同引用，从而保证两侧对操作类型、输入类型以及响应类型的理解保持一致。
package daemonapi

const (
	// OperationUpdate 表示更新操作，即用新的后端制品替换当前运行的后端。
	OperationUpdate = "update"
	// OperationRestart 表示重启操作，即不更换制品、仅重启当前后端服务。
	OperationRestart = "restart"
	// OperationStatus 表示状态查询操作，读取 SQLite 并校验外部系统与活动槽位是否一致。
	OperationStatus = "status"
	// OperationDoctor 表示只读诊断操作，输出全部漂移项与建议动作。
	OperationDoctor = "doctor"
	// OperationReconcile 表示对账操作，只读生成修复计划；携带 Apply 时执行自动修复。
	OperationReconcile = "reconcile"
	// InputTypeRepackZIP 表示输入类型为重新打包后的 ZIP 包。
	InputTypeRepackZIP = "repack-zip"
	// InputTypeNativeJAR 表示输入类型为原生后端 JAR 文件。
	InputTypeNativeJAR = "native-jar"
	// InputTypeContainerImage 表示输入类型为容器镜像引用。
	InputTypeContainerImage = "container-image"
	// ResponseProgress 表示响应为进度事件，用于在操作过程中向客户端流式推送中间状态。
	ResponseProgress = "progress"
	// ResponseResult 表示响应为最终结果，代表一次操作已经结束，并携带终态与错误信息。
	ResponseResult = "result"
)

// 诊断项级别的稳定取值，用于 status/doctor/reconcile 的结果展示。
const (
	// DiagnosisLevelOK 表示该项与 SQLite 事实来源一致，无需处理。
	DiagnosisLevelOK = "ok"
	// DiagnosisLevelFixable 表示该项不一致，但可由 reconcile --apply 自动修复。
	DiagnosisLevelFixable = "fixable"
	// DiagnosisLevelDrift 表示该项不一致且无法自动修复，需要人工确认。
	DiagnosisLevelDrift = "drift"
)

// Request 表示客户端通过 Unix Socket 提交给守护进程的一次请求。
// 各字段按操作类型选择性填充，未使用的字段保持空值。
type Request struct {
	// Operation 表示要执行的操作，取值为 OperationUpdate 或 OperationRestart。
	Operation string `json:"operation"`
	// Service 表示操作作用的目标服务，当前仅接受 backend。
	Service string `json:"service"`
	// InputType 表示更新操作的输入类型，仅在 Operation 为 OperationUpdate 时有意义。
	InputType string `json:"inputType"`
	// File 表示更新制品的本地绝对路径，输入类型为 InputTypeRepackZIP 或 InputTypeNativeJAR 时使用。
	File string `json:"file"`
	// ImageReference 表示容器镜像引用，输入类型为 InputTypeContainerImage 时使用。
	ImageReference string `json:"imageReference"`
	// StartLog 表示容器更新完成后是否输出容器启动日志，仅对容器镜像输入生效。
	StartLog bool `json:"startLog"`
	// Apply 仅用于 OperationReconcile：为 true 时执行自动修复动作，否则只生成修复计划。
	Apply bool `json:"apply"`
}

// Response 表示守护进程返回给客户端的一次响应。
// 响应分为进度事件与最终结果两类，由 Kind 字段区分。
type Response struct {
	// Kind 表示响应类型，取值为 ResponseProgress 或 ResponseResult。
	Kind string `json:"kind"`
	// TransactionID 表示本次操作对应的事务标识，仅在已创建事务后返回。
	TransactionID string `json:"transactionId,omitempty"`
	// State 表示事务当前所处状态，用于进度事件与最终结果的展示。
	State string `json:"state,omitempty"`
	// Message 表示进度事件的描述信息，最终结果通常不携带该字段。
	Message string `json:"message,omitempty"`
	// Error 表示操作失败时的错误信息，为空说明操作执行成功。
	Error string `json:"error,omitempty"`
	// Diagnosis 表示 status/doctor/reconcile 的结构化诊断结果，仅在对应操作成功时返回。
	Diagnosis *Diagnosis `json:"diagnosis,omitempty"`
}

// Diagnosis status/doctor/reconcile 的结构化诊断结果，由守护进程生成并通过结果响应返回。
type Diagnosis struct {
	// Service 诊断的目标服务名。
	Service string `json:"service"`
	// Type 组件运行类型，取值 native 或 container。
	Type string `json:"type"`
	// Healthy 表示是否存在需要人工处理的漂移项（drift）；只有 ok 与 fixable 项时为 true。
	Healthy bool `json:"healthy"`
	// Items 按诊断顺序排列的诊断项列表。
	Items []DiagnosisItem `json:"items"`
	// RepairApplied 表示本次请求是否实际执行了 reconcile --apply 修复动作。
	RepairApplied bool `json:"repairApplied,omitempty"`
	// RepairTransactionID 表示本次对账修复事务标识，仅在 RepairApplied 为 true 时返回。
	RepairTransactionID string `json:"repairTransactionId,omitempty"`
}

// DiagnosisItem 单条诊断结论，说明某项现场状态与 SQLite 事实来源是否一致。
type DiagnosisItem struct {
	// Level 诊断级别，取值 DiagnosisLevelOK / DiagnosisLevelFixable / DiagnosisLevelDrift。
	Level string `json:"level"`
	// Code 稳定标识，供程序与测试识别，不参与展示。
	Code string `json:"code"`
	// Message 对该诊断项的人类可读描述。
	Message string `json:"message"`
	// Action 仅在 Level 为 fixable 时给出建议的修复动作描述。
	Action string `json:"action,omitempty"`
}