Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
100.00%
1 / 1
n/a
0 / 0
 CRAP
n/a
0 / 0
1<?php
2
3declare(strict_types=1);
4
5/** @license For full copyright and license information, please see the LICENSE.md file. */
6
7namespace App\Modules\Automation\Domain\Repository;
8
9defined('AMMONLY_APP') || exit('Direct script access is forbidden.');
10
11use App\Modules\Automation\Domain\Model\Workflow;
12
13/**
14 * Workflow Repository Contract.
15 *
16 * Provides persistence and execution audit tracking for automation workflows.
17 *
18 * @package App\Modules\Automation\Domain\Repository
19 */
20interface WorkflowRepositoryInterface
21{
22    /**
23     * Finds a workflow by its primary key.
24     *
25     * @param int $id Primary key.
26     * @return Workflow|null Entity instance or null.
27     */
28    public function findById(int $id): ?Workflow;
29
30    /**
31     * Finds all active workflows matching a specific module and trigger stage.
32     *
33     * @param string $moduleName  Module machine name.
34     * @param string $triggerType Trigger type (e.g. before_create, after_update).
35     * @return list<Workflow> List of active workflows.
36     */
37    public function findActiveByTrigger(string $moduleName, string $triggerType): array;
38
39    /**
40     * Persists updated Drawflow graph JSON and compiled DAG execution tree.
41     *
42     * @param int    $id           Workflow ID.
43     * @param string $graphData    Raw Drawflow JSON.
44     * @param string $compiledFlow Optimized execution tree JSON.
45     */
46    public function saveGraph(int $id, string $graphData, string $compiledFlow): void;
47
48    /**
49     * Increments the total execution counter and updates last_run_at timestamp.
50     *
51     * @param int $id Workflow ID.
52     */
53    public function incrementRuns(int $id): void;
54
55    /**
56     * Checks if a workflow has already executed for a specific record (idempotency check).
57     *
58     * @param int $workflowId Workflow ID.
59     * @param int $recordId   Record ID.
60     * @return bool True if already executed.
61     */
62    public function hasRunForRecord(int $workflowId, int $recordId): bool;
63
64    /**
65     * Logs an execution run into a_mod_workflow_runs_records.
66     *
67     * @param int                       $workflowId      Workflow ID.
68     * @param int|null                  $recordId        Record primary key.
69     * @param string                    $triggerType     Trigger name.
70     * @param string                    $status          Status ('success', 'failed', 'blocked_by_guard').
71     * @param int                       $executionTimeMs Execution duration in milliseconds.
72     * @param string|null               $errorMessage    Optional error trace.
73     * @param array<string, mixed>|null $contextSnapshot Debug snapshot.
74     */
75    public function recordRun(
76        int     $workflowId,
77        ?int    $recordId,
78        string  $triggerType,
79        string  $status,
80        int     $executionTimeMs,
81        ?string $errorMessage = null,
82        ?array  $contextSnapshot = null
83    ): void;
84}