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

monthly-by-day engine + recoreco:run (v0.3)

Browse Source
This commit is contained in:
Ruben Carlo Benante
2026-07-07 22:05:55 -03:00
parent 5bcaea3022
commit dc63a031e1
6 changed files with 383 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

70
Model/OccurrenceCalculator.php Normal file
View File

@@ -0,0 +1,70 @@
<?php
namespace Kanboard\Plugin\RecoReco\Model;
/**
* Pure calendar math for RecoReco.
*
* Given an anchor due date (the drift-free pattern: day-of-month + time), a frequency, and the
* "last day" flag, it computes occurrence datetimes. It has NO container dependencies, so it is
* unit-testable in isolation (see Test/OccurrenceCalculatorTest.php).
*
* Occurrences are always computed from the anchor's day, never by marching a clamped date forward,
* so a "30th" schedule goes 30, 28/29, 30, 30... and never drifts to the 28th.
*
* v0.3 implements monthly-by-day; the other frequencies arrive in v1.1 (occurrenceFrom returns null
* for them until then).
*/
class OccurrenceCalculator
{
const MAX_MONTHS = 120;
/**
* The earliest occurrence at/after $reference (when $inclusive) or strictly after it.
*
* @param int $anchor Unix timestamp: the pattern (day-of-month + time).
* @param string $frequency
* @param bool $lastDay
* @param int $reference Unix timestamp.
* @param bool $inclusive
* @return int|null Occurrence timestamp, or null if the frequency is not yet supported.
*/
public function occurrenceFrom($anchor, $frequency, $lastDay, $reference, $inclusive = false)
{
switch ($frequency) {
case 'monthly_day':
return $this->monthlyByDay((int) $anchor, (bool) $lastDay, (int) $reference, (bool) $inclusive);
default:
return null;
}
}
private function monthlyByDay($anchor, $lastDay, $reference, $inclusive)
{
$anchorDay = (int) date('j', $anchor);
$h = (int) date('G', $anchor);
$i = (int) date('i', $anchor);
$s = (int) date('s', $anchor);
$y = (int) date('Y', $reference);
$m = (int) date('n', $reference);
for ($k = 0; $k < self::MAX_MONTHS; $k++) {
$lastDom = (int) date('t', mktime(0, 0, 0, $m, 1, $y));
$day = $lastDay ? $lastDom : min($anchorDay, $lastDom);
$occurrence = mktime($h, $i, $s, $m, $day, $y);
if ($inclusive ? $occurrence >= $reference : $occurrence > $reference) {
return $occurrence;
}
$m++;
if ($m > 12) {
$m = 1;
$y++;
}
}
return null;
}
}

170
Model/RecoRecoModel.php Normal file
View File

@@ -0,0 +1,170 @@
<?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;
}
}