Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
0.00%
0 / 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\Core\Engine\Domain\Repository;
8
9defined('AMMONLY_APP') || exit('Direct script access is forbidden.');
10
11use App\Core\Engine\Domain\Model\PermissionContext;
12
13/**
14 * Audit Repository Interface.
15 *
16 * Defines the contract for writing audit log entries to persistent storage.
17 * Implemented by SqlAuditRepository (Infrastructure).
18 * Called by audit event listeners registered with Yii3 EventDispatcher.
19 *
20 * @package App\Core\Engine\Domain\Repository
21 */
22interface AuditRepositoryInterface
23{
24    /**
25     * Logs a record creation operation.
26     *
27     * @param string               $moduleName Module where the record was created.
28     * @param int                  $recordId   Primary key of the new record.
29     * @param array<string, mixed> $payload    Full snapshot of the created data.
30     * @param PermissionContext     $context    Security context of the actor.
31     */
32    public function logCreate(
33        string            $moduleName,
34        int               $recordId,
35        array             $payload,
36        PermissionContext  $context,
37    ): void;
38
39    /**
40     * Logs a record read or list operation.
41     *
42     * @param string                    $moduleName Module where records were read.
43     * @param int|null                  $recordId   Single record ID or null for list.
44     * @param array<string, mixed>|null $filters    Active filters snapshot.
45     * @param PermissionContext          $context    Security context of the actor.
46     */
47    public function logRead(
48        string            $moduleName,
49        ?int              $recordId,
50        ?array            $filters,
51        PermissionContext  $context,
52    ): void;
53
54    /**
55     * Logs a field-level diff for a record update operation.
56     *
57     * @param string               $moduleName Module where the record was updated.
58     * @param int                  $recordId   Primary key of the updated record.
59     * @param array<string, array{old: mixed, new: mixed}> $diff Field diff map.
60     * @param PermissionContext     $context    Security context of the actor.
61     */
62    public function logUpdate(
63        string            $moduleName,
64        int               $recordId,
65        array             $diff,
66        PermissionContext  $context,
67    ): void;
68
69    /**
70     * Logs a record deletion with a full snapshot of the deleted data.
71     *
72     * @param string               $moduleName Module where the record was deleted.
73     * @param int                  $recordId   Primary key of the deleted record.
74     * @param array<string, mixed> $snapshot   Full snapshot before deletion.
75     * @param PermissionContext     $context    Security context of the actor.
76     */
77    public function logDelete(
78        string            $moduleName,
79        int               $recordId,
80        array             $snapshot,
81        PermissionContext  $context,
82    ): void;
83
84    /**
85     * Retrieves unified chronological audit timeline events for a specific record.
86     *
87     * @param string $moduleName Module machine name.
88     * @param int    $recordId   Record primary key.
89     * @return list<array<string, mixed>> Chronologically sorted timeline events (newest first).
90     */
91    public function getTimeline(string $moduleName, int $recordId): array;
92}
93