<?php

namespace App\Module\Task\Contracts;

/**
 * 任务条件处理器接口
 * 
 * 定义任务条件处理器必须实现的方法
 */
interface ConditionHandlerInterface
{
    /**
     * 验证用户是否满足条件（用于前置条件检查）
     *
     * @param int $userId 用户ID
     * @param array $params 条件参数
     * @return bool 是否满足条件
     */
    public function validate(int $userId, array $params): bool;

    /**
     * 检查事件参数是否匹配条件（用于进度更新）
     *
     * @param array $eventParams 事件参数
     * @param array $conditionParams 条件参数
     * @return bool 是否匹配
     */
    public function isMatch(array $eventParams, array $conditionParams): bool;

    /**
     * 计算事件对条件进度的贡献值
     *
     * @param array $eventParams 事件参数
     * @param array $conditionParams 条件参数
     * @return int 进度增量
     */
    public function calculateProgress(array $eventParams, array $conditionParams): int;

    /**
     * 检查条件是否已完成
     *
     * @param int $currentValue 当前值
     * @param int $targetValue 目标值
     * @param string $operator 运算符
     * @return bool 是否已完成
     */
    public function isCompleted(int $currentValue, int $targetValue, string $operator = '>='): bool;
}