427 lines
18 KiB
PHP
427 lines
18 KiB
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 (from cron, or from the identical "Run now" button). One
|
|
* run is one pass over every enabled template; running it five times a day instead of four is
|
|
* harmless -- see the idempotency note below.
|
|
*
|
|
* Per template there is a SINGLE algorithm (no first-run vs catch-up split):
|
|
*
|
|
* 1. Yield to native recurrence if the card became native-recurring (decision 13).
|
|
* 2. Walk occurrences forward from the cursor (the template due date), collecting every one whose
|
|
* fire time (occurrence - days_before) has arrived (before this run's horizon). The first
|
|
* occurrence still ahead of the horizon is the "next future" one.
|
|
* 3. Cap to the most recent MAX_BACKFILL: if more than that are due (a template set far in the
|
|
* past), skip the OLDEST overflow and keep the newest ones -- contiguous, no gap.
|
|
* 4. Spawn each kept occurrence into the target column, dated to that occurrence.
|
|
* 5. Park the cursor on the next future occurrence and stop.
|
|
*
|
|
* Idempotency: after a run the cursor sits on a future occurrence, so a second run the same day
|
|
* collects nothing. As a belt-and-suspenders guard against a run overlapping cron on the same
|
|
* occurrence, spawn() is skipped when a clone for that (template, due) already exists (cloneExists).
|
|
*/
|
|
class RecoRecoModel extends Base
|
|
{
|
|
// Most recent occurrences to actually spawn in one run. A template set far in the past spawns
|
|
// these newest ones and skips the older overflow (no gap), rather than flooding the board.
|
|
const MAX_BACKFILL = 12;
|
|
|
|
// Safety bound on the occurrence walk so a misbehaving calculator can never loop forever
|
|
// (1200 monthly steps is a century).
|
|
const MAX_ITERATIONS = 1200;
|
|
|
|
private $calc;
|
|
|
|
public function run($now = null)
|
|
{
|
|
$now = $now ?: time();
|
|
$horizon = $this->horizon($now);
|
|
$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, $horizon);
|
|
}
|
|
|
|
return $spawned;
|
|
}
|
|
|
|
/**
|
|
* The look-ahead horizon for this run: fire everything whose fire time is before it. Computed as
|
|
* "ceil now to the next 6h boundary, then +12h", which lands on the four daily runs:
|
|
* 05:58 -> 18:00, 11:58 -> 00:00, 17:58 -> 06:00, 23:58 -> 12:00. Gives a 12h look-ahead with a
|
|
* 6h overlap between runs, so a missed run is covered by its neighbour. Past-due occurrences are
|
|
* naturally included (their fire time is < now < horizon) -- that is the back-fill.
|
|
*
|
|
* @param int $now
|
|
* @return int
|
|
*/
|
|
private function horizon($now)
|
|
{
|
|
$startOfDay = mktime(0, 0, 0, (int) date('n', $now), (int) date('j', $now), (int) date('Y', $now));
|
|
$boundaryHour = (intdiv((int) date('G', $now), 6) + 1) * 6;
|
|
|
|
return $startOfDay + $boundaryHour * 3600 + 12 * 3600;
|
|
}
|
|
|
|
public function processTemplate($task_id, $now, $horizon)
|
|
{
|
|
$task = $this->taskFinderModel->getById($task_id);
|
|
|
|
if (empty($task)) {
|
|
return 0;
|
|
}
|
|
|
|
// Native wins: if the card became native-recurring, RecoReco yields (decision 13). Leave a
|
|
// visible trail in the task's activity stream, attributed to the card's owner (creator_id has
|
|
// a FK to users, so a system id like 0 would make the insert fail silently -- no user 0).
|
|
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)');
|
|
$this->projectActivityModel->createEvent(
|
|
(int) $task['project_id'],
|
|
$task_id,
|
|
(int) $task['creator_id'],
|
|
'recoreco.task.disable',
|
|
array('task' => array('id' => $task_id, 'title' => $task['title']))
|
|
);
|
|
return 0;
|
|
}
|
|
|
|
$meta = $this->taskMetadataModel->getAll($task_id);
|
|
$frequency = isset($meta['recoreco_frequency']) ? $meta['recoreco_frequency'] : '';
|
|
|
|
// All five frequencies are supported since v1.1; skip anything unknown.
|
|
if (! in_array($frequency, array('daily', 'weekly', 'monthly_day', 'monthly_dow', 'yearly'), true)) {
|
|
return 0;
|
|
}
|
|
|
|
// The anchor defines the recurrence PATTERN (which day-of-month, which weekday ordinal); the
|
|
// cursor (the template due date) is our POSITION in that pattern.
|
|
$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'];
|
|
// Default off: only keep the duplicate link when explicitly turned on.
|
|
$linkCopies = isset($meta['recoreco_link_copies']) && $meta['recoreco_link_copies'] == 1;
|
|
|
|
// Finite-plan stop. RecoReco caps its own recurrence, either by its own limit (standalone) or
|
|
// by following FinanceBuddy. When follow is on, FinanceBuddy governs: the plan is finite only
|
|
// if the card has a numeric installment total, so an ordinary recurring bill (money but no
|
|
// installments) recurs forever -- and any stale standalone limit is ignored. In follow mode
|
|
// the numbers are read LIVE from FinanceBuddy (never copied), so a mid-plan start, a
|
|
// re-purchase, or an extend all just work by editing FinanceBuddy. A blank/0 limit means
|
|
// recur forever. The spawn loop below stops when counter > limit (1-based; counter ends on
|
|
// limit+1).
|
|
$followIntent = isset($meta['recoreco_follow_finance']) && $meta['recoreco_follow_finance'] == 1;
|
|
$fbTotal = isset($meta['financebuddy_installment_total']) ? (string) $meta['financebuddy_installment_total'] : '';
|
|
$fbHasTotal = $fbTotal !== '' && ctype_digit($fbTotal);
|
|
$follow = $followIntent && $fbHasTotal;
|
|
|
|
if ($followIntent) {
|
|
$limit = $fbHasTotal ? (int) $fbTotal : 0; // following FinanceBuddy; no total => forever
|
|
} else {
|
|
$limitRaw = isset($meta['recoreco_limit']) ? (string) $meta['recoreco_limit'] : '';
|
|
$limit = ($limitRaw !== '' && ctype_digit($limitRaw)) ? (int) $limitRaw : 0;
|
|
}
|
|
|
|
// Standalone progress counter (1-based "next occurrence"). Unused in follow mode, where the
|
|
// counter is FinanceBuddy's live installment_current instead.
|
|
$count = isset($meta['recoreco_count']) && ctype_digit((string) $meta['recoreco_count']) ? (int) $meta['recoreco_count'] : 1;
|
|
|
|
// Trigger gate (cross-cutting, both modes): fire only while the card is in a triggering column,
|
|
// and never while it sits in the target (Gate 2, uniform).
|
|
$col = (int) $task['column_id'];
|
|
$trig = isset($meta['recoreco_trigger_column']) ? $meta['recoreco_trigger_column'] : 'any';
|
|
$invert = isset($meta['recoreco_trigger_invert']) && $meta['recoreco_trigger_invert'] == 1;
|
|
$base = ($trig === 'any') ? true : ($invert ? ($col !== (int) $trig) : ($col === (int) $trig));
|
|
|
|
if (! ($base && $col !== $targetColumn)) {
|
|
return 0;
|
|
}
|
|
|
|
// Move-mode: relocate the single card to the target instead of spawning a clone. No back-fill,
|
|
// no clone metadata. Honors the standalone limit (save() forced follow=0, so $limit is it).
|
|
if (isset($meta['recoreco_move']) && $meta['recoreco_move'] == 1) {
|
|
$cursor = (int) $task['date_due'];
|
|
|
|
if ($cursor - $daysBefore * 86400 >= $horizon) {
|
|
return 0; // not due yet
|
|
}
|
|
|
|
if ($limit > 0 && $count > $limit) {
|
|
$this->completePlan($task, $task_id); // safety: re-armed after completion
|
|
return 0;
|
|
}
|
|
|
|
$this->taskPositionModel->movePosition($task['project_id'], $task_id, $targetColumn, 1, $task['swimlane_id'], false);
|
|
|
|
$next = $this->calculator()->occurrenceFrom($anchor, $frequency, $lastDay, $cursor, false);
|
|
if ($next !== null && $next > $cursor) {
|
|
$this->setDue($task_id, $next); // advance one period
|
|
}
|
|
|
|
if ($limit > 0) {
|
|
$count++;
|
|
$this->setCount($task_id, $count);
|
|
if ($count > $limit) {
|
|
$this->completePlan($task, $task_id);
|
|
}
|
|
}
|
|
|
|
return 1;
|
|
}
|
|
|
|
// Phase 1 -- walk forward from the cursor, collecting every occurrence whose fire time has
|
|
// arrived. The loop exits on the first occurrence still ahead of the horizon, which is then
|
|
// the "next future" one to park on.
|
|
$cursor = (int) $task['date_due'];
|
|
$due = array();
|
|
$iterations = 0;
|
|
|
|
while ($cursor - $daysBefore * 86400 < $horizon && $iterations < self::MAX_ITERATIONS) {
|
|
$due[] = $cursor;
|
|
|
|
$next = $this->calculator()->occurrenceFrom($anchor, $frequency, $lastDay, $cursor, false);
|
|
|
|
if ($next === null || $next <= $cursor) {
|
|
break; // calculator cannot advance -- stop rather than loop
|
|
}
|
|
|
|
$cursor = $next;
|
|
$iterations++;
|
|
}
|
|
|
|
$nextFuture = $cursor;
|
|
|
|
// Phase 2 -- cap to the most recent MAX_BACKFILL, skipping the oldest overflow (no gap).
|
|
$skip = max(0, count($due) - self::MAX_BACKFILL);
|
|
$toSpawn = array_slice($due, $skip);
|
|
|
|
// Phase 3 -- spawn each kept occurrence, dated to that occurrence. Idempotent: skip any that
|
|
// this template has already spawned (survives a run overlapping cron on the same occurrence).
|
|
// Two guards enforce the finite-plan limit: the leading one catches an already-complete plan
|
|
// (a re-enabled done template, or a back-fill overshoot); the trailing one disables the
|
|
// instant this run's spawn completes the plan.
|
|
$spawned = 0;
|
|
$completed = false;
|
|
|
|
foreach ($toSpawn as $occurrence) {
|
|
$counter = $follow ? $this->financeCurrent($task_id) : $count;
|
|
|
|
if ($limit > 0 && $counter > $limit) {
|
|
$completed = true;
|
|
break;
|
|
}
|
|
|
|
if ($this->cloneExists($task_id, $occurrence)) {
|
|
continue;
|
|
}
|
|
|
|
// duplicate() copies the template's date_due onto the clone, so set it to this occurrence
|
|
// first, then spawn. spawn() fires the hook that lets FinanceBuddy advance its installment.
|
|
$this->setDue($task_id, $occurrence);
|
|
$this->spawn($task, $targetColumn);
|
|
$spawned++;
|
|
|
|
// Standalone advances its own counter (only meaningful with a limit set); follow mode
|
|
// relies on FinanceBuddy having advanced its installment during spawn().
|
|
if (! $follow && $limit > 0) {
|
|
$count++;
|
|
$this->setCount($task_id, $count);
|
|
}
|
|
|
|
$counter = $follow ? $this->financeCurrent($task_id) : $count;
|
|
|
|
if ($limit > 0 && $counter > $limit) {
|
|
$completed = true;
|
|
break;
|
|
}
|
|
}
|
|
|
|
// Phase 4 -- park the cursor on the next future occurrence. When the plan just completed,
|
|
// disable the template (its p(total+1) tombstone is already in place) and log it.
|
|
$this->setDue($task_id, $nextFuture);
|
|
|
|
if ($completed) {
|
|
$this->completePlan($task, $task_id);
|
|
}
|
|
|
|
// Reconcile the duplicate links with the setting (removes both new and old ones when off).
|
|
$this->syncCloneLinks($task_id, $linkCopies);
|
|
|
|
return $spawned;
|
|
}
|
|
|
|
/**
|
|
* Has this template already spawned a clone for the given occurrence? A clone records its source
|
|
* template (recoreco_source) and carries the occurrence as its due date, so the pair identifies
|
|
* it. This makes a repeated or overlapping run idempotent -- an occurrence is never spawned twice.
|
|
*
|
|
* @param int $template_id
|
|
* @param int $due
|
|
* @return bool
|
|
*/
|
|
private function cloneExists($template_id, $due)
|
|
{
|
|
$clone_ids = $this->db->table('task_has_metadata')
|
|
->eq('name', 'recoreco_source')
|
|
->eq('value', (string) $template_id)
|
|
->findAllByColumn('task_id');
|
|
|
|
if (empty($clone_ids)) {
|
|
return false;
|
|
}
|
|
|
|
return $this->db->table(TaskModel::TABLE)
|
|
->in('id', $clone_ids)
|
|
->eq('date_due', $due)
|
|
->exists();
|
|
}
|
|
|
|
/**
|
|
* Reconcile a template's "is a duplicate of" links with the link-copies setting. When off, remove
|
|
* the links to THIS template's own RecoReco clones (identified by recoreco_source, so manual
|
|
* links are left untouched). When on, do nothing -- new spawns already carry the link.
|
|
*
|
|
* @param int $template_id
|
|
* @param bool $linkCopies
|
|
*/
|
|
public function syncCloneLinks($template_id, $linkCopies)
|
|
{
|
|
if ($linkCopies) {
|
|
return;
|
|
}
|
|
|
|
foreach ($this->taskLinkModel->getAll($template_id) as $link) {
|
|
$opposite = (int) $link['task_id'];
|
|
|
|
if ((int) $this->taskMetadataModel->get($opposite, 'recoreco_source', 0) === (int) $template_id) {
|
|
$this->taskLinkModel->remove($link['id']);
|
|
}
|
|
}
|
|
}
|
|
|
|
private function setDue($task_id, $due)
|
|
{
|
|
// Move the template's due date directly (no task events fired). This is the cursor.
|
|
$this->db->table(TaskModel::TABLE)->eq('id', $task_id)->update(array('date_due' => $due));
|
|
}
|
|
|
|
/**
|
|
* FinanceBuddy's live "next installment to spawn" for a task (1-based), read fresh because
|
|
* FinanceBuddy advances it on every spawn. Defaults to 1 when absent or non-numeric. RecoReco
|
|
* only reads this key -- it never writes FinanceBuddy metadata.
|
|
*
|
|
* @param int $task_id
|
|
* @return int
|
|
*/
|
|
private function financeCurrent($task_id)
|
|
{
|
|
$current = $this->taskMetadataModel->get($task_id, 'financebuddy_installment_current', 1);
|
|
|
|
return ctype_digit((string) $current) ? (int) $current : 1;
|
|
}
|
|
|
|
private function setCount($task_id, $count)
|
|
{
|
|
$this->taskMetadataModel->save($task_id, array('recoreco_count' => (int) $count));
|
|
}
|
|
|
|
/**
|
|
* A finite plan reached its limit: disable the template and record it in the activity stream,
|
|
* attributed to the card owner (creator_id has a FK to users, so a system id would fail silently).
|
|
*
|
|
* @param array $task
|
|
* @param int $task_id
|
|
*/
|
|
private function completePlan(array $task, $task_id)
|
|
{
|
|
$this->taskMetadataModel->save($task_id, array('recoreco_enabled' => 0));
|
|
$this->logger->info('RecoReco: plan complete on task '.$task_id.' (recurrence disabled)');
|
|
$this->projectActivityModel->createEvent(
|
|
(int) $task['project_id'],
|
|
$task_id,
|
|
(int) $task['creator_id'],
|
|
'recoreco.task.complete',
|
|
array('task' => array('id' => $task_id, 'title' => $task['title']))
|
|
);
|
|
}
|
|
|
|
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);
|
|
|
|
// Kanboard's duplicate() adds an "is a duplicate of" task link between the template and the
|
|
// clone. It is reconciled with the recoreco_link_copies setting by syncCloneLinks() after
|
|
// the spawn loop (kept when on, removed when off).
|
|
|
|
// 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);
|
|
|
|
// Record the spawn in the clone's activity stream, attributed to the template's owner
|
|
// (creator_id has a FK to users, so a system id like 0 would silently fail the insert).
|
|
$this->projectActivityModel->createEvent(
|
|
(int) $template['project_id'],
|
|
$newId,
|
|
(int) $template['creator_id'],
|
|
'recoreco.task.spawn',
|
|
array(
|
|
'task' => array('id' => $newId, 'title' => $template['title']),
|
|
'template_id' => (int) $template['id'],
|
|
'template_title' => $template['title'],
|
|
)
|
|
);
|
|
|
|
return $newId;
|
|
}
|
|
|
|
private function calculator()
|
|
{
|
|
if ($this->calc === null) {
|
|
$this->calc = new OccurrenceCalculator();
|
|
}
|
|
|
|
return $this->calc;
|
|
}
|
|
}
|