// Package converter 定義與 kneron_model_converter 服務互動的 client 介面。
//
// 對齊 TDD §2.7 與 api/api-converter-contract.md。
// 雛形以 StubClient 實作所有方法回 ErrNotImplemented（部分關鍵方法可給假資料讓前端走通 UI）；
// Phase 2 以 HTTPClient 實作同 interface 呼叫真實 converter。
package converter

import (
	"context"
	"errors"
	"io"
	"time"
)

// ==========================================================================
// Errors
// ==========================================================================

var (
	// ErrNotImplemented 表示雛形尚未實作此方法。
	ErrNotImplemented = errors.New("converter: not implemented in phase 0")

	// ErrJobNotFound 表示指定 jobID 不存在。
	ErrJobNotFound = errors.New("converter: job not found")
)

// ==========================================================================
// Domain types（對齊 database.md §2.6）
// ==========================================================================

// Job 是轉檔任務的狀態快照。
type Job struct {
	ID          string         `json:"id"`
	OwnerUserID string         `json:"ownerUserId"`
	Status      string         `json:"status"` // queued / running / succeeded / failed
	SourceKey   string         `json:"sourceKey"`
	ResultKey   string         `json:"resultKey,omitempty"`
	TargetChip  string         `json:"targetChip"`
	Params      map[string]any `json:"params,omitempty"`

	ErrorCode string `json:"errorCode,omitempty"`
	ErrorMsg  string `json:"errorMsg,omitempty"`

	CreatedAt   time.Time  `json:"createdAt"`
	UpdatedAt   time.Time  `json:"updatedAt"`
	StartedAt   *time.Time `json:"startedAt,omitempty"`
	CompletedAt *time.Time `json:"completedAt,omitempty"`
}

// ConvertRequest 是提交轉檔任務時的輸入參數。
type ConvertRequest struct {
	OwnerUserID string         `json:"ownerUserId"`
	SourceKey   string         `json:"sourceKey"` // 已上傳到 Storage 的來源檔 key
	TargetChip  string         `json:"targetChip"`
	Params      map[string]any `json:"params,omitempty"`
}

// ==========================================================================
// Client interface
// ==========================================================================

// Client 抽象 converter 服務。
//
// 對齊 PRD interface-contracts.md §8.5 與 api-converter-contract.md。
type Client interface {
	// SubmitConvert 提交一個新的轉檔任務；回傳 jobID。
	SubmitConvert(ctx context.Context, req *ConvertRequest) (jobID string, err error)

	// GetJob 查詢任務狀態；不存在回 ErrJobNotFound。
	GetJob(ctx context.Context, jobID string) (*Job, error)

	// ListJobs 列出使用者的所有轉檔任務。
	ListJobs(ctx context.Context, userID string) ([]*Job, error)

	// DownloadResult 下載任務產物（.nef）。
	// 未完成或失敗時回錯；caller 必須 Close reader。
	DownloadResult(ctx context.Context, jobID string) (io.ReadCloser, error)

	// CancelJob 取消任務。
	CancelJob(ctx context.Context, jobID string) error
}