beco/RecoReco
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v1.4 backfill-to-today algorithm, 12-card cap, idempotent spawns; drop dual-path

Browse Source
This commit is contained in:
Ruben Carlo Benante
2026-07-08 19:24:42 -03:00
parent c74a52346c
commit bc982536f1
4 changed files with 106 additions and 53 deletions
Download Patch File Download Diff File Expand all files Collapse all files

134
Model/RecoRecoModel.php
View File

@@ -8,15 +8,34 @@ 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.
* 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: 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.
* 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
{
const CATCHUP_CAP = 24;
// 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;
@@ -43,7 +62,7 @@ class RecoRecoModel extends Base
* "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 catch-up.
* naturally included (their fire time is < now < horizon) -- that is the back-fill.
*
* @param int $now
* @return int
@@ -79,6 +98,8 @@ class RecoRecoModel extends Base
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) {
@@ -91,46 +112,83 @@ class RecoRecoModel extends Base
// Default off: only keep the duplicate link when explicitly turned on.
$linkCopies = isset($meta['recoreco_link_copies']) && $meta['recoreco_link_copies'] == 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'];
$synced = isset($meta['recoreco_synced_due']) ? (int) $meta['recoreco_synced_due'] : null;
$due = array();
$iterations = 0;
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 is before this run's horizon (this includes
// past-due ones -> catch-up), advancing the cursor each time.
$spawned = 0;
$fireTime = $cursor - $daysBefore * 86400;
while ($fireTime < $horizon && $spawned < self::CATCHUP_CAP) {
$this->spawn($task, $targetColumn);
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;
break; // calculator cannot advance -- stop rather than loop
}
$cursor = $next;
$this->setDue($task_id, $cursor);
$fireTime = $cursor - $daysBefore * 86400;
$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).
$spawned = 0;
foreach ($toSpawn as $occurrence) {
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.
$this->setDue($task_id, $occurrence);
$this->spawn($task, $targetColumn);
$spawned++;
}
// Phase 4 -- park the cursor on the next future occurrence and stop.
$this->setDue($task_id, $nextFuture);
// 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
@@ -154,24 +212,10 @@ class RecoRecoModel extends Base
}
}
/**
* 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)
private function setDue($task_id, $due)
{
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));
// 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));
}
private function spawn(array $template, $targetColumn)

2
Plugin.php
View File

@@ -55,7 +55,7 @@ class Plugin extends Base
public function getPluginVersion()
{
return '1.3.0';
return '1.4.0';
}
public function getPluginHomepage()

21
README.md
View File

@@ -31,15 +31,24 @@ The engine runs from the CLI command `recoreco:run`. Add it to cron **four times
```
(Point the path at your install and run it as the user that owns Kanboard's data.) Each run looks
ahead 12 hours; the runs overlap by 6 hours, so a single missed run is covered by the next one, and
any occurrence whose time is already past is still caught up. `days before` shifts a copy earlier
within that lead. You can also run it by hand any time: `php cli recoreco:run`.
ahead 12 hours; the runs overlap by 6 hours, so a single missed run is covered by the next one.
Each run walks a template forward from its current due date and spawns **every** occurrence whose
fire time has arrived -- so occurrences already in the past are backfilled, not skipped. To avoid
flooding the board when a template was set far in the past, a single run spawns at most the **12
most recent** due occurrences; any older overflow is skipped (contiguous, no gap) and the template
advances straight to the next future occurrence. `days before` shifts a copy earlier within the
lead. Runs are idempotent: an occurrence is never spawned twice, so running an extra time is safe.
You can trigger the exact same pass by hand -- either on the CLI (`php cli recoreco:run`) or with
the **Run now** button under **Settings -> RecoReco** (admin only). The button and cron do the
identical thing.
## Status
Working for **monthly by day** (with the last-day rule), driven by cron. The remaining frequencies
(yearly, weekly, daily, monthly by weekday), the recurrence icons, and the FinanceBuddy
installment hand-off arrive in the following versions.
All five frequencies work (yearly, monthly by day, monthly by weekday, weekly, daily) with the
last-day rule, board recurrence icons, backfill with the 12-occurrence cap, the Run-now button, and
the FinanceBuddy installment hand-off.
## Requirements

2
VERSION
View File

@@ -1 +1 @@
RecoReco v1.3
RecoReco v1.4