Relevant source files

The following files were used as context for generating this wiki page: - [src/main/java/com/example/demo/services/TaskService.java](https://github.com/adiletsaparbev/dash_bord/blob/main/src/main/java/com/example/demo/services/TaskService.java) - [src/main/java/com/example/demo/controllers/AnalyticsController.java](https://github.com/adiletsaparbev/dash_bord/blob/main/src/main/java/com/example/demo/controllers/AnalyticsController.java) - [src/main/java/com/example/demo/entity/Task.java](https://github.com/adiletsaparbev/dash_bord/blob/main/src/main/java/com/example/demo/entity/Task.java) - [src/main/resources/templates/task-detail.html](https://github.com/adiletsaparbev/dash_bord/blob/main/src/main/resources/templates/task-detail.html) - [src/main/resources/static/css/task-detail.css](https://github.com/adiletsaparbev/dash_bord/blob/main/src/main/resources/static/css/task-detail.css) - [README.md](https://github.com/adiletsaparbev/dash_bord/blob/main/README.md)

# Audit Logs & Task History ## Introduction The Audit Logs & Task History system is a core feature of the Dashboard Task Management (DTM) application designed to provide transparency and accountability throughout the task lifecycle. It systematically records every significant change made to a task—including creation, status transitions, field updates, and assignment changes—ensuring that project managers and administrators can track the evolution of work items. This system serves as a chronological ledger of activity, allowing users to view who changed what and when. It integrates directly with the Analytics module to provide a historical overview of task modifications, which is essential for performance auditing and project post-mortems. ## Data Architecture & Storage Task history is captured through a specialized entity that links individual modification events to specific tasks and users. ### The TaskHistory Entity The system relies on a dedicated repository (`TaskHistoryRepository`) and entity to persist changes. Every entry in the history log captures the field that was modified, the previous value, and the new value. | Field | Description | |---|---| | `task` | The parent Task entity being modified. | | `changedBy` | The User who performed the update. | | `fieldName` | The specific attribute changed (e.g., "status", "priority", "assignees"). | | `oldValue` | The value before the modification. | | `newValue` | The value after the modification. | | `createdAt` | Timestamp of when the change occurred. | Sources: [src/main/java/com/example/demo/services/TaskService.java:31](), [src/main/java/com/example/demo/services/TaskService.java:324-335](), [README.md:173]() ### Entity Relationships The relationship between tasks and their history is managed through the `TaskService`, which acts as the orchestrator for recording these events during update operations. ```mermaid erDiagram TASK ||--o{ TASK_HISTORY : "has" USER ||--o{ TASK_HISTORY : "records" TASK { Long id String title TaskStatus status } TASK_HISTORY { Long id String fieldName String oldValue String newValue LocalDateTime createdAt } USER { Long id String fullName } ``` *The diagram illustrates the relationship where a single task can have multiple history entries, each linked to the user who performed the change.* Sources: [src/main/java/com/example/demo/services/TaskService.java:324-335](), [src/main/java/com/example/demo/entity/Task.java:19-54]() ## Change Tracking Logic History recording is primarily triggered within the `TaskService.updateTask` method. The system employs a "compare-and-record" strategy to ensure only actual changes are logged. ### Modification Detection When a task is updated, the service compares the requested changes against the current state of the database entity. If a difference is detected, the `recordHistory` private method is invoked. ```mermaid flowchart TD Start[Update Request Received] --> Compare[Compare old value vs new value] Compare --> Decision{Values differ?} Decision -- No --> End[Process next field] Decision -- Yes --> Save[Create TaskHistory record] Save --> Persist[Save to TaskHistoryRepository] Persist --> End ``` *Logic flow for recording individual field changes during a task update.* Sources: [src/main/java/com/example/demo/services/TaskService.java:166-267](), [src/main/java/com/example/demo/services/TaskService.java:324-335]() ### Tracked Operations The following events are explicitly logged by the system: 1. **Creation:** Logged as a "created" event with a descriptive message. 2. **Field Updates:** Changes to `title`, `description`, `priority`, `startDate`, and `dueDate`. 3. **Status Transitions:** Records the old status and the new status (e.g., `NEW` → `IN_PROGRESS`). 4. **Assignment Changes:** Captures the full list of assignees before and after the change to track team composition. Sources: [src/main/java/com/example/demo/services/TaskService.java:136-138](), [src/main/java/com/example/demo/services/TaskService.java:171](), [src/main/java/com/example/demo/services/TaskService.java:204](), [src/main/java/com/example/demo/services/TaskService.java:252]() ## API and Visualization The history data is exposed via a dedicated analytics endpoint and rendered in the user interface to provide immediate context to team members. ### Analytics Endpoint The `AnalyticsController` provides an endpoint to retrieve the full history of a specific task. Access to this history is restricted to users who have permission to view the task itself (ADMIN, MANAGER, PM, and assigned TEAM members). | Method | Endpoint | Description | |---|---|---| | `GET` | `/api/analytics/tasks/{taskId}/history` | Returns a list of all historical changes for the specified task. | Sources: [src/main/java/com/example/demo/controllers/AnalyticsController.java:95-103](), [README.md:173]() ### Frontend Integration The task detail view (`task-detail.html`) includes a sidebar section dedicated to displaying the "History of Changes" (`История изменений`). ```html ``` Sources: [src/main/resources/templates/task-detail.html:151-158]() Changes are styled using a vertical timeline approach in the UI: - **Visual Markers:** Each history item is marked with a dot (`.history-dot`). - **Typography:** The person who made the change is highlighted in bold, with the description of the change provided in a dimmed text style. Sources: [src/main/resources/static/css/task-detail.css:122-137]() ## Implementation Details ### Automated Metadata The `Task` entity uses JPA lifecycle hooks (`@PrePersist`, `@PreUpdate`) to maintain `createdAt` and `updatedAt` timestamps automatically, ensuring the base entity always reflects its most recent modification time independent of the audit logs. Sources: [src/main/java/com/example/demo/entity/Task.java:70-85]() ### Status Update Sequence When a status change occurs, the system not only records the history but also triggers secondary logic, such as updating the `completedAt` timestamp and clearing the `overdue` flag if the status is set to `DONE`. ```mermaid sequenceDiagram participant U as User participant TS as TaskService participant THR as TaskHistoryRepository participant NS as NotificationService U->>TS: updateTask(status: DONE) TS->>TS: Compare status TS->>THR: save(TaskHistory: status change) TS->>TS: setCompletedAt(now) TS->>NS: notifyTaskParticipants("STATUS_CHANGED") TS-->>U: TaskResponse ``` *Sequence of events when a task's status is updated to 'DONE'.* Sources: [src/main/java/com/example/demo/services/TaskService.java:204-222]() ## Conclusion The Audit Logs & Task History system is an integral part of the Dashboard Task Management architecture. By capturing granular changes at the service layer and exposing them through the Analytics API, the project provides a robust trail of activity. This not only aids in project management oversight but also enhances team communication by providing a clear record of task status evolution and assignment history.