RecoReco/Model/RecoRecoModel.php

<?php

namespace Kanboard\Plugin\RecoReco\Model;

use Kanboard\Core\Base;
use Kanboard\Model\TaskModel;

/**
 * The RecoReco engine: find enabled templates and spawn their due occurrences.
 *
 * Called by the recoreco:run CLI command. v0.3 handles monthly-by-day and fires everything whose
 * fire time has arrived (fire time = occurrence - days_before); v1.0 adds the 4-window cron horizon.
 *
 * Per template: the native-recurrence yield (decision 13), first-run init / manual-edit re-anchor,
 * then a catch-up loop that duplicates the card into the target column and advances the cursor.
 */
class RecoRecoModel extends Base
{
    const CATCHUP_CAP = 24;

    private $calc;

    public function run($now = null)
    {
        $now = $now ?: time();
        $spawned = 0;

        $task_ids = $this->db->table('task_has_metadata')
            ->eq('name', 'recoreco_enabled')
            ->eq('value', '1')
            ->findAllByColumn('task_id');

        foreach ($task_ids as $task_id) {
            $spawned += $this->processTemplate((int) $task_id, $now);
        }

        return $spawned;
    }

    public function processTemplate($task_id, $now)
    {
        $task = $this->taskFinderModel->getById($task_id);

        if (empty($task)) {
            return 0;
        }

        // Native wins: if the card became native-recurring, RecoReco yields (decision 13).
        if ($task['recurrence_status'] != TaskModel::RECURRING_STATUS_NONE) {
            $this->taskMetadataModel->save($task_id, array('recoreco_enabled' => 0));
            $this->logger->info('RecoReco: disabled on task '.$task_id.' (now native-recurring)');
            return 0;
        }

        $meta = $this->taskMetadataModel->getAll($task_id);
        $frequency = isset($meta['recoreco_frequency']) ? $meta['recoreco_frequency'] : '';

        // v0.3 handles monthly-by-day only; the rest arrive in v1.1.
        if ($frequency !== 'monthly_day') {
            return 0;
        }

        $anchor = isset($meta['recoreco_anchor']) ? (int) $meta['recoreco_anchor'] : 0;

        if ($anchor <= 0) {
            return 0;
        }

        $lastDay = isset($meta['recoreco_last_day']) && $meta['recoreco_last_day'] == 1;
        $daysBefore = isset($meta['recoreco_days_before']) ? (int) $meta['recoreco_days_before'] : 0;
        $targetColumn = isset($meta['recoreco_target_column']) ? (int) $meta['recoreco_target_column'] : (int) $task['column_id'];

        $cursor = (int) $task['date_due'];
        $synced = isset($meta['recoreco_synced_due']) ? (int) $meta['recoreco_synced_due'] : null;

        if ($synced === null) {
            // First run after enabling: place the cursor on the first occurrence.
            $cursor = $this->firstCursor($anchor, $frequency, $lastDay, $now);
            $this->setDue($task_id, $cursor);
        } elseif ($cursor !== $synced) {
            // The user hand-edited the due date -> re-anchor to it (a reschedule).
            $anchor = $cursor;
            $this->taskMetadataModel->save($task_id, array('recoreco_anchor' => $anchor));
            $this->setDue($task_id, $cursor);
        }

        // Fire every occurrence whose fire time has arrived, advancing the cursor each time.
        $spawned = 0;
        $fireTime = $cursor - $daysBefore * 86400;

        while ($fireTime <= $now && $spawned < self::CATCHUP_CAP) {
            $this->spawn($task, $targetColumn);

            $next = $this->calculator()->occurrenceFrom($anchor, $frequency, $lastDay, $cursor, false);

            if ($next === null || $next <= $cursor) {
                break;
            }

            $cursor = $next;
            $this->setDue($task_id, $cursor);
            $fireTime = $cursor - $daysBefore * 86400;
            $spawned++;
        }

        return $spawned;
    }

    /**
     * The first occurrence: respect an explicitly future anchor (the due date the user set) as the
     * first one; otherwise jump to the next occurrence on/after now.
     */
    private function firstCursor($anchor, $frequency, $lastDay, $now)
    {
        if ($anchor >= $now) {
            return $anchor;
        }

        return $this->calculator()->occurrenceFrom($anchor, $frequency, $lastDay, $now, true);
    }

    private function setDue($task_id, $cursor)
    {
        // Advance the template's due date directly (no task events) + mirror it for edit detection.
        $this->db->table(TaskModel::TABLE)->eq('id', $task_id)->update(array('date_due' => $cursor));
        $this->taskMetadataModel->save($task_id, array('recoreco_synced_due' => $cursor));
    }

    private function spawn(array $template, $targetColumn)
    {
        // The template's date_due is already the occurrence (setDue), so duplicate() copies it onto
        // the clone. duplicate() copies fields + tags + links + subtasks, but NO metadata, so the
        // clone is not a template.
        $newId = $this->taskDuplicationModel->duplicate($template['id']);

        if ($newId === false) {
            $this->logger->error('RecoReco: duplicate failed for task '.$template['id']);
            return false;
        }

        // duplicate() lands the clone in the source column; move it to the chosen target (top).
        if ($targetColumn > 0 && $targetColumn != $template['column_id']) {
            $this->taskPositionModel->movePosition($template['project_id'], $newId, $targetColumn, 1, $template['swimlane_id']);
        }

        // Reset the "[DUPLICATE]" prefix back to the source title (no events).
        $this->taskModificationModel->update(array('id' => $newId, 'title' => $template['title']), false);

        // Mark the clone: white icon + cannot itself be made recurring; record its source template.
        $this->taskMetadataModel->save($newId, array(
            'recoreco_clone' => 1,
            'recoreco_source' => $template['id'],
        ));

        // Signal FinanceBuddy (advance the installment). Harmless no-op if nothing listens.
        $payload = array('source_task_id' => (int) $template['id'], 'new_task_id' => (int) $newId);
        $this->hook->reference('recoreco:task:spawned', $payload);

        return $newId;
    }

    private function calculator()
    {
        if ($this->calc === null) {
            $this->calc = new OccurrenceCalculator();
        }

        return $this->calc;
    }
}