exportcodec

type Codec interface {
	// Version 返回该策略对应的文件格式版本，等于产物顶层 version 字段的取值，
	// 同时是它在 Registry 里的键（Registry.Get(Version()) 必须命中自己）。
	//
	// 同一个版本号必须既能写出、也能读回，因此 WriteXxxFiles 生成的 payload
	// 的 Version 字段必须由 Version() 赋值。
	Version() string

	// WriteScriptFiles 按该版本格式生成脚本导出内容并落盘到 req.ScriptDir
	// （文件名、是否附带 container_templates 等由版本决定），返回写入的 payload，
	// 其 Version 必须等于 Version()。
	//
	// 只落盘、不提交 git：SaveScript 用它把导出文件与数据库保持一致，写完目录即处于
	// dirty 状态；需要产出带提交的版本产物时，由调用方再调 WriteCommitScriptFiles。
	//
	// 实现需保证 req.ScriptDir 存在（不存在则创建）。
	WriteScriptFiles(ctx context.Context, req ScriptWriteRequest) (*types.ScriptJSONExportResponse, error)

	// WriteWorkflowFiles 按该版本格式生成工作流导出内容并落盘到 req.WorkflowDir，
	// 同时按该版本的目录布局把工作流引用的脚本快照到 req.WorkflowDir 下，
	// 返回写入的 payload，其 Version 必须等于 Version()。
	//
	// 与 WriteScriptFiles 一样只落盘、不提交 git（SaveWorkflow 使用它）。
	//
	// 实现需保证 req.WorkflowDir 存在（不存在则创建）。
	WriteWorkflowFiles(ctx context.Context, req WorkflowWriteRequest) (*types.WorkflowJSONExportResponse, error)

	// WriteCommitScriptFiles 在 WriteScriptFiles 的基础上，把 req.ScriptDir 的目录改动
	// 提交为一个 git commit（见 utils.CommitDirChanges，提交身份由装配时注入）。
	//
	// 调用方：SaveScriptFiles / PublishScript（保存或发布必须产出带提交的完整产物）。
	WriteCommitScriptFiles(ctx context.Context, req ScriptWriteRequest) (*types.ScriptJSONExportResponse, error)

	// WriteCommitWorkflowFiles 在 WriteWorkflowFiles 的基础上，把 req.WorkflowDir 的目录改动
	// 提交为一个 git commit（见 utils.CommitDirChanges，提交身份由装配时注入）。
	//
	// 调用方：SaveWorkflowFiles / PublishWorkflow。
	WriteCommitWorkflowFiles(ctx context.Context, req WorkflowWriteRequest) (*types.WorkflowJSONExportResponse, error)

	// DecodeScript 解析 script.json 的内容（raw 为文件字节），返回带 Version 的 payload。
	//
	// 只做解析与该版本特有的字段规整，不负责业务字段覆盖
	// （ID/ProjectID/StoreID/URL/Message/创建更新时间由 handler 决定）。
	// ScriptID 非空等校验同样由 handler 负责，便于统一转 400。
	DecodeScript(raw []byte) (*types.ScriptJSONExportResponse, error)

	// DecodeWorkflow 解析 workflow.json 的内容（raw 为文件字节），返回带 Version 的 payload。
	//
	// 该方法的职责边界与 DecodeScript 一致；v1 会在这里把 workflow.dag_definition
	// 从对象规整成字符串（等价原先 handler 内的 normalizeInstalledWorkflowMap），
	// 因为 dag_definition 落库是字符串列。
	DecodeWorkflow(raw []byte) (*types.WorkflowJSONExportResponse, error)

	// InstallScript 解析 req.Raw（内部调用本 Codec 的 DecodeScript）并把导出内容持久化：
	// 先按主键 upsert 容器镜像 / 运行配置 / 绑定行，再按 script_id upsert script 行。
	//
	// 与 DecodeScript 的分工：DecodeScript 只负责解析，本方法负责落库与安装特有的校验
	// （script.json 缺少 script_id 时返回 ErrScriptIDRequired，调用方据此转 400）。
	InstallScript(ctx context.Context, req ScriptInstallRequest) (*ScriptInstallResult, error)

	// InstallWorkflow 解析 req.Raw（内部调用本 Codec 的 DecodeWorkflow）并把导出内容持久化：
	// 先按主键 upsert 容器资产，再 upsert workflow 行与它引用的 script 行，
	// 最后把 workflow 目录里的脚本快照（见 ScriptSnapshotDir）还原到本地脚本目录。
	//
	// workflow.json 缺少 workflow_id 时返回 ErrWorkflowIDRequired，调用方据此转 400。
	InstallWorkflow(ctx context.Context, req WorkflowInstallRequest) (*WorkflowInstallResult, error)

	// ScriptSnapshotDir 返回该版本布局下 workflow 目录内承载某个脚本快照的目录。
	//
	// 写侧（WriteWorkflowFiles）把脚本快照进去，安装侧（InstallWorkflow）从同一位置
	// 还原到脚本目录，两边都通过本方法取路径，避免各自写死字面量。
	ScriptSnapshotDir(workflowDir, scriptID string) string

	// ScriptIDFromExportScript 从 workflow.json 的脚本条目里取脚本 ID（component_id）。
	//
	// 条目在 payload 里是 map（不是强类型），字段名属于该版本的格式知识，
	// 因此由 Codec 解释；取不到时返回空字符串，由调用方决定是跳过还是报错。
	ScriptIDFromExportScript(item map[string]any) string
}

type Registry struct {
	// contains filtered or unexported fields
}

type ScriptInstallRequest struct {
	// Raw 是 script.json 文件内容（与 DecodeScript 的入参一致）。
	Raw []byte
	// ProjectID 是安装到的目标 project 主键（project.ID）。
	ProjectID int64
	// StoreID 是发布来源 store 主键（写入 script.store_id）。
	StoreID int64
	// StoreMessage 非空时覆盖 script.message。
	StoreMessage string
	// ScriptID 是安装后的 script_id：create=true 时调用方已生成新 uuid，
	// 否则沿用导出文件/发布方记录的 script_id。
	ScriptID string
	// CreateMode 为 true 时作为副本新增，而不是按 script_id upsert 原脚本。
	CreateMode bool
}

type ScriptInstallResult struct {
	// ScriptID 是落库后的 script_id；InstalledScriptID 是 script 表主键。
	ScriptID          string
	InstalledScriptID int64
	// ContainerImageCount / ContainerTemplateSpecCount / ContainerTemplateDefinitionCount
	// 分别是本次按主键 upsert 的镜像、运行配置与绑定行数量（导出文件没有对应列表时为 0）。
	ContainerImageCount              int
	ContainerTemplateSpecCount       int
	ContainerTemplateDefinitionCount int
}

type ScriptWriteRequest struct {
	ScriptPK      int64
	ScriptDir     string
	CommitMessage string
}

type WorkflowInstallRequest struct {
	// Raw 是 workflow.json 文件内容（与 DecodeWorkflow 的入参一致）。
	Raw []byte
	// ProjectID 是安装到的目标 project 主键（project.ID）。
	ProjectID int64
	// ProjectCode 是 project.project_id（字符串），仅用于推导本地目录。
	ProjectCode string
	// StoreID 是发布来源 store 主键。
	StoreID int64
	// StoreMessage 非空时覆盖 workflow / script 行的 message。
	StoreMessage string
	// BaseDir 是 storage.base_dir。
	BaseDir string
	// WorkflowDir 是已同步出的 workflow 目录（脚本快照的父目录）。
	WorkflowDir string
}

type WorkflowInstallResult struct {
	// WorkflowID 是导出文件里的 workflow_id；InstalledWorkflowID 是 workflow 表主键。
	WorkflowID          string
	InstalledWorkflowID int64
	// InstalledScriptCount 是本次安装（新增或更新）的 script 行数。
	InstalledScriptCount int
	// ContainerImageCount / ContainerTemplateSpecCount / ContainerTemplateDefinitionCount
	// 分别是本次按主键 upsert 的镜像、运行配置与绑定行数量。
	ContainerImageCount              int
	ContainerTemplateSpecCount       int
	ContainerTemplateDefinitionCount int
}

type WorkflowWriteRequest struct {
	WorkflowPK    int64
	ProjectID     string
	BaseDir       string
	WorkflowDir   string
	CommitMessage string
}