package transaction

import (
	"context"
	"encoding/json"
	"errors"
	"fmt"
	"log/slog"
)

// InspectionStatus 表示外部系统中某一步的实际结果。
//
// 它是 Operation.Inspect 的核对结论，Coordinator 据此判断副作用是否真实发生，
// 从而决定步骤的最终状态。UNKNOWN 表示暂时无法确认，必须保留意图等待恢复。
type InspectionStatus string

const (
	InspectionApplied    InspectionStatus = "APPLIED"     // 外部副作用已确认发生。
	InspectionNotApplied InspectionStatus = "NOT_APPLIED" // 外部副作用已确认未发生。
	InspectionUnknown    InspectionStatus = "UNKNOWN"     // 无法确认副作用是否发生。
)

// Inspection 执行器通过 inspect、摘要、健康检查等方式得到的实际状态。
//
// 它把对外的状态核对结果封装为统一结构：Status 给出确定/不确定的结论，Result
// 保存核对得到的原始证据，用于在步骤成功时持久化。
type Inspection struct {
	Status InspectionStatus // 核对结论。
	Result json.RawMessage  // 核对得到的原始结果载荷，可为空。
}

// Operation 一个可核对实际结果的外部副作用。
//
// 实现者负责实际执行外部操作（Apply）并提供事后核对（Inspect）。Apply 返回
// 成功只代表调用完成，副作用是否真正生效必须由 Inspect 确认，因此调用方在
// Apply 之后无论成功与否都要再次 Inspect，以精确判定外部状态。
type Operation interface {
	Apply(context.Context) error
	Inspect(context.Context) (Inspection, error)
}

// UncertainStepError 表示当前无法确认外部副作用是否已经发生。
//
// 这种错误必须保留 INTENT_RECORDED，等待恢复流程再次核对。它携带事务与步骤
// 定位信息及根本原因（Cause），并通过 Unwrap 暴露 Cause 供调用方溯源。
type UncertainStepError struct {
	TransactionID string // 所属事务 ID。
	StepKey       string // 关联步骤键。
	Cause         error  // 导致无法确认的根本原因。
}

// Error 返回带事务、步骤与原因的无法确认错误描述。
func (e *UncertainStepError) Error() string {
	return fmt.Sprintf("external step result is uncertain: transaction=%s step=%s: %v", e.TransactionID, e.StepKey, e.Cause)
}

// Unwrap 返回根本原因 Cause，支持 errors.Is/errors.As 溯源。
func (e *UncertainStepError) Unwrap() error {
	return e.Cause
}

// Coordinator 串行化单机更新，并实现“先记录意图、再执行、最后 inspect”的步骤协议。
//
// 它通过容量为 1 的 permit 通道保证同一时刻进程内最多只有一个完整更新流程在
// 执行区运行，从而简化外部副作用与数据库状态的一致性推理。所有对外部副作用的
// 操作都必须经过 ExecuteStep，以确保意图先落库、结果可核对、崩溃可恢复。
type Coordinator struct {
	store  *Store        // 持久化存储，记录事务、步骤与事件。
	logger *slog.Logger  // 结构化日志记录器。
	permit chan struct{} // 容量为 1 的信号量，串行化进入执行区。
}

// NewCoordinator 创建并初始化事务协调器。
//
// 参数 store 为必填的事务存储，logger 可选，传入 nil 时回退到 slog.Default。
// 初始化时向 permit 通道放入一个令牌，表示执行区当前空闲。返回错误仅发生在
// store 为 nil 时。
func NewCoordinator(store *Store, logger *slog.Logger) (*Coordinator, error) {
	if store == nil {
		return nil, errors.New("transaction store is required")
	}
	if logger == nil {
		logger = slog.Default()
	}
	permit := make(chan struct{}, 1)
	permit <- struct{}{}
	return &Coordinator{store: store, logger: logger, permit: permit}, nil
}

// RunExclusive 在一个进程内只允许一个完整更新流程进入执行区。
//
// 参数 run 是独占执行的更新函数，返回其执行结果；若 run 为 nil 或 ctx 在获得
// 执行令牌前已取消，则直接返回相应错误。该方法通过 acquire 令牌、defer 释放
// 令牌实现互斥，释放与获取均不阻塞超过令牌容量，因此不存在死锁。返回值为
// run 的返回值，或在等待令牌时 ctx 取消导致的错误。
func (c *Coordinator) RunExclusive(ctx context.Context, run func(context.Context) error) error {
	if run == nil {
		return errors.New("exclusive update function is required")
	}
	select {
	case <-ctx.Done():
		return ctx.Err()
	case <-c.permit:
	}
	defer func() { c.permit <- struct{}{} }()
	return run(ctx)
}

// ExecuteStep 执行或恢复一个外部步骤。
//
// 参数 transactionID 是所属事务，intent 描述要执行的外部副作用，operation 提供
// 实际执行与核对能力。返回值为该步骤的最终持久化快照以及可能的错误。协议要点：
// 相同 step key 再次调用时先核对现场，禁止直接重复 Apply；若意图已成功则直接
// 返回；若已失败则依据 inspect 结论决定补记成功或重新打开；若为未执行过的新
// 意图，则先记录意图、Apply 后再 Inspect，依据核对结果落库成功或失败。当核对
// 结果为 UNKNOWN 或 Inspect 本身出错时，返回 UncertainStepError 并保留
// INTENT_RECORDED 等待后续恢复。
func (c *Coordinator) ExecuteStep(ctx context.Context, transactionID string, intent StepIntent, operation Operation) (Step, error) {
	if operation == nil {
		return Step{}, errors.New("external operation is required")
	}
	step, created, err := c.store.RecordStepIntent(ctx, transactionID, intent)
	if err != nil {
		return Step{}, err
	}
	if step.Status == StepSucceeded {
		return step, nil
	}
	if step.Status == StepFailed {
		inspection, inspectErr := operation.Inspect(ctx)
		if inspectErr != nil {
			return step, c.uncertain(ctx, transactionID, intent.Key, fmt.Errorf("inspect failed step: %w", inspectErr))
		}
		switch inspection.Status {
		case InspectionApplied:
			if _, err := c.store.ReopenFailedStep(ctx, transactionID, intent.Key, "manual resume found failed step applied"); err != nil {
				return step, err
			}
			return c.completeApplied(ctx, transactionID, intent.Key, inspection)
		case InspectionNotApplied:
			reopened, err := c.store.ReopenFailedStep(ctx, transactionID, intent.Key, "manual resume found failed step not applied")
			if err != nil {
				return step, err
			}
			step = reopened
			created = true
		case InspectionUnknown:
			return step, c.uncertain(ctx, transactionID, intent.Key, errors.New("inspect failed step returned UNKNOWN"))
		default:
			return step, c.uncertain(ctx, transactionID, intent.Key, fmt.Errorf("inspect failed step returned invalid status %q", inspection.Status))
		}
	}

	if !created {
		inspection, err := operation.Inspect(ctx)
		if err != nil {
			return step, c.uncertain(ctx, transactionID, intent.Key, err)
		}
		switch inspection.Status {
		case InspectionApplied:
			return c.completeApplied(ctx, transactionID, intent.Key, inspection)
		case InspectionUnknown:
			return step, c.uncertain(ctx, transactionID, intent.Key, errors.New("inspect returned UNKNOWN"))
		case InspectionNotApplied:
			// 现场明确未发生副作用后，才允许恢复流程重新 Apply。
		default:
			return step, c.uncertain(ctx, transactionID, intent.Key, fmt.Errorf("inspect returned invalid status %q", inspection.Status))
		}
	}

	c.logger.InfoContext(ctx, "external step apply started",
		"transaction_id", transactionID,
		"step_key", intent.Key,
		"step_name", intent.Name,
	)
	applyErr := operation.Apply(ctx)
	inspection, inspectErr := operation.Inspect(ctx)
	if inspectErr != nil {
		return step, c.uncertain(ctx, transactionID, intent.Key, errors.Join(applyErr, inspectErr))
	}
	switch inspection.Status {
	case InspectionApplied:
		completed, err := c.completeApplied(ctx, transactionID, intent.Key, inspection)
		if err == nil {
			c.logger.InfoContext(ctx, "external step applied",
				"transaction_id", transactionID,
				"step_key", intent.Key,
			)
		}
		return completed, err
	case InspectionUnknown:
		return step, c.uncertain(ctx, transactionID, intent.Key, errors.Join(applyErr, errors.New("inspect returned UNKNOWN")))
	case InspectionNotApplied:
		failure := applyErr
		if failure == nil {
			failure = errors.New("operation completed without reaching the expected external state")
		}
		completed, err := c.store.CompleteStep(ctx, transactionID, intent.Key, StepFailed, inspection.Result, failure.Error())
		if err != nil {
			return Step{}, errors.Join(failure, err)
		}
		c.logger.ErrorContext(ctx, "external step failed",
			"transaction_id", transactionID,
			"step_key", intent.Key,
			"error", failure,
		)
		return completed, failure
	default:
		return step, c.uncertain(ctx, transactionID, intent.Key, fmt.Errorf("inspect returned invalid status %q", inspection.Status))
	}
}

// completeApplied 将已确认生效的步骤原子落库为 SUCCEEDED。
//
// 参数 transactionID 与 stepKey 定位目标步骤，inspection.Result 作为成功结果
// 写入。返回更新后的步骤快照及可能的存储错误。
func (c *Coordinator) completeApplied(ctx context.Context, transactionID, stepKey string, inspection Inspection) (Step, error) {
	return c.store.CompleteStep(ctx, transactionID, stepKey, StepSucceeded, inspection.Result, "")
}

// uncertain 记录无法确认外部副作用结果的告警日志并构造 UncertainStepError。
//
// 参数 transactionID 与 stepKey 用于定位，cause 为根本原因。该方法不改变存储
// 状态，仅记录日志并返回错误，交由上层决定是否保留意图等待恢复。
func (c *Coordinator) uncertain(ctx context.Context, transactionID, stepKey string, cause error) error {
	c.logger.WarnContext(ctx, "external step result is uncertain",
		"transaction_id", transactionID,
		"step_key", stepKey,
		"error", cause,
	)
	return &UncertainStepError{TransactionID: transactionID, StepKey: stepKey, Cause: cause}
}