refactor: use nginx -s reload instead of systemd

- doc: add comment

internal/backendupdate/model.go

@@ -2,57 +2,106 @@ package backendupdate
 
 import "yms-daemon/internal/filestore"
 
+// updateInput 一次原生后端更新（或重启）在进入事务前的内存态输入，由上层
+// 入口（UpdateRepack、UpdateNativeJAR、Restart）组装后交给 Updater.update 执行。
+// 其中持久化相关字段最终会编码进 persistedRequest 存入事务存储。
 type updateInput struct {
-	IdempotencyKey   string
-	InputType        string
-	SourcePath       string
-	SourceSHA256     string
-	CustomerCode     string
-	VersionID        string
-	ArtifactID       int64
+	// IdempotencyKey 本次更新的幂等键，用于跨进程/跨调用识别同一逻辑更新。
+	IdempotencyKey string
+	// InputType 标识本次输入的来源类型，取值为 daemonapi 中定义的输入类型常量。
+	InputType string
+	// SourcePath 待部署构件在宿主机上的源路径。
+	SourcePath string
+	// SourceSHA256 源构件的 SHA-256 摘要，参与幂等识别与一致性校验。
+	SourceSHA256 string
+	// CustomerCode 构件所属客户编码，仅 repack 输入携带。
+	CustomerCode string
+	// VersionID 构件所属版本标识，仅 repack 输入携带。
+	VersionID string
+	// ArtifactID 构件标识，仅 repack 输入携带。
+	ArtifactID int64
+	// ArtifactFileName 构件文件名。
 	ArtifactFileName string
+	// ArtifactIdentity 构件的尺寸与摘要身份信息，用于校验落盘结果。
 	ArtifactIdentity filestore.Identity
-	ReleasePath      string
-	Materialize      func(string) error
+	// ReleasePath 构件在 release 目录下的相对安装路径。
+	ReleasePath string
+	// Materialize 将构件物化到指定目标路径，通常为解压或复制实现。
+	Materialize func(string) error
 }
 
+// persistedRequest 原生后端更新请求的持久化形态，以 JSON 存入事务记录。
+// 事务在提交、重试或补偿时都依赖这些字段重建执行所需的完整上下文。
 type persistedRequest struct {
-	InputType            string             `json:"inputType"`
-	SourcePath           string             `json:"sourcePath"`
-	SourceSHA256         string             `json:"sourceSHA256"`
-	CustomerCode         string             `json:"customerCode,omitempty"`
-	VersionID            string             `json:"versionId,omitempty"`
-	ArtifactID           int64              `json:"artifactId,omitempty"`
-	ArtifactFileName     string             `json:"artifactFileName"`
-	ArtifactPath         string             `json:"artifactPath"`
-	ArtifactIdentity     filestore.Identity `json:"artifactIdentity"`
-	ReleasePath          string             `json:"releasePath"`
-	TargetPort           int                `json:"targetPort"`
-	TargetUnit           string             `json:"targetUnit"`
-	TargetSlotJAR        string             `json:"targetSlotJar"`
-	TargetHealthEndpoint string             `json:"targetHealthEndpoint"`
-	PreviousSlotTarget   string             `json:"previousSlotTarget"`
-	PreviousGatewayPort  int                `json:"previousGatewayPort"`
-	PreviousUnit         string             `json:"previousUnit"`
-	GatewayBeforePath    string             `json:"gatewayBeforePath"`
-	GatewayAfterPath     string             `json:"gatewayAfterPath"`
-	GatewayReceiptPath   string             `json:"gatewayReceiptPath"`
-	ActiveJARPath        string             `json:"activeJarPath"`
-	ActiveJARBefore      pathState          `json:"activeJarBefore"`
+	// InputType 标识输入来源类型。
+	InputType string `json:"inputType"`
+	// SourcePath 构件源路径。
+	SourcePath string `json:"sourcePath"`
+	// SourceSHA256 构件 SHA-256 摘要。
+	SourceSHA256 string `json:"sourceSHA256"`
+	// CustomerCode 客户编码，为空时省略。
+	CustomerCode string `json:"customerCode,omitempty"`
+	// VersionID 版本标识，为空时省略。
+	VersionID string `json:"versionId,omitempty"`
+	// ArtifactID 构件标识，为零时省略。
+	ArtifactID int64 `json:"artifactId,omitempty"`
+	// ArtifactFileName 构件文件名。
+	ArtifactFileName string `json:"artifactFileName"`
+	// ArtifactPath 构件在事务工作目录中的物化路径。
+	ArtifactPath string `json:"artifactPath"`
+	// ArtifactIdentity 构件尺寸与摘要身份信息。
+	ArtifactIdentity filestore.Identity `json:"artifactIdentity"`
+	// ReleasePath 构件在 release 目录下的相对安装路径。
+	ReleasePath string `json:"releasePath"`
+	// TargetPort 本次更新要切换到的目标后端端口。
+	TargetPort int `json:"targetPort"`
+	// TargetUnit 目标端口对应的 systemd 单元名。
+	TargetUnit string `json:"targetUnit"`
+	// TargetSlotJAR 目标槽位的 JAR 链接路径。
+	TargetSlotJAR string `json:"targetSlotJar"`
+	// TargetHealthEndpoint 目标槽位的健康检查端点。
+	TargetHealthEndpoint string `json:"targetHealthEndpoint"`
+	// PreviousSlotTarget 目标槽位链接在更新前指向的目标，用于补偿恢复。
+	PreviousSlotTarget string `json:"previousSlotTarget"`
+	// PreviousGatewayPort 更新前 Nginx 上游指向的端口。
+	PreviousGatewayPort int `json:"previousGatewayPort"`
+	// PreviousUnit 更新前实际运行的后端单元名。
+	PreviousUnit string `json:"previousUnit"`
+	// GatewayBeforePath 切换前 Nginx 配置快照的文件路径。
+	GatewayBeforePath string `json:"gatewayBeforePath"`
+	// GatewayAfterPath 切换后 Nginx 配置快照的文件路径。
+	GatewayAfterPath string `json:"gatewayAfterPath"`
+	// GatewayReceiptPath Nginx 切换成功后的回执文件路径。
+	GatewayReceiptPath string `json:"gatewayReceiptPath"`
+	// ActiveJARPath 兼容性 JAR 链接路径。
+	ActiveJARPath string `json:"activeJarPath"`
+	// ActiveJARBefore 兼容性 JAR 链接更新前的状态快照，用于补偿恢复。
+	ActiveJARBefore pathState `json:"activeJarBefore"`
 }
 
+// pathKind 描述文件系统路径的状态种类。
 type pathKind string
 
 const (
-	pathKindAbsent  pathKind = "absent"
+	// pathKindAbsent 表示路径应不存在。
+	pathKindAbsent pathKind = "absent"
+	// pathKindRegular 表示路径应是普通文件。
 	pathKindRegular pathKind = "regular"
+	// pathKindSymlink 表示路径应是符号链接。
 	pathKindSymlink pathKind = "symlink"
 )
 
+// pathState 文件系统路径在某个时刻的状态快照，同时作为“期望状态”与
+// “历史状态”使用。applyPathState 依据 Kind 决定如何把路径调整到该状态。
 type pathState struct {
-	Kind       pathKind           `json:"kind"`
-	Target     string             `json:"target,omitempty"`
-	BackupPath string             `json:"backupPath,omitempty"`
-	Identity   filestore.Identity `json:"identity,omitempty"`
-	Mode       uint32             `json:"mode,omitempty"`
+	// Kind 路径状态种类，决定其它字段的取值。
+	Kind pathKind `json:"kind"`
+	// Target 符号链接目标路径，仅 Kind 为 pathKindSymlink 时有效。
+	Target string `json:"target,omitempty"`
+	// BackupPath 普通文件快照的备份路径，仅 Kind 为 pathKindRegular 时有效。
+	BackupPath string `json:"backupPath,omitempty"`
+	// Identity 普通文件快照的尺寸与摘要身份信息。
+	Identity filestore.Identity `json:"identity,omitempty"`
+	// Mode 普通文件的权限位，仅 Kind 为 pathKindRegular 时有效。
+	Mode uint32 `json:"mode,omitempty"`
 }