Add aggregate field crackingTime to AgentAssignment

[novasam23]

Fixes #2297

[novasam23]

A few things to add:

• For the AgentAssignment I suggest to call the aggregate crackingTime instead of timeSpent in order to be consistent with how it's called on the Agent model

• A similar calculation is also done in TaskUtils called getTimeSpentOnTask. However, since this involves potentially multiple agents which results in parallel time spans, the calculation is more complex and hence done entirely in the API layer. A future enhancement might be, to move this to the DB for performance reasons, but I think that would require making the DB access classes capable of DB window functions. Definitely something for the future, if at all.

• As for the existing aggregate on the Agent, currently crackingTime is implemented in the AgentAPI. One benefit of having that in a utilities class (similar to getTimeSpentOnTask) would be to better test the "business logic" of correctly calculating the time values via PHP tests. Another benefit would be reducing the occurrences of duplicate code, since we now have almost identical calculations for the Agent and AgentAssignment.

• In short, I'm proposing to move this calculation to TaskUtils and consolidate existing occurrences accordingly.

• With window functions in the DB access layer, this could be further consolidated into a single generic time span (i.e. solveTime minus dispatchTime) aggregating function, to be used even by the Task entity.

Tests

• Talking about tests, I did implement a Pytest, but chunk creation and manipulation is very restricted via API, hence it's difficult to create meaningful test cases that cover all sorts of chunk processing constellations.

• The more relevant test I think is the PHP test, that creates different chunks with different timing constellations, assigned to multiple agents, etc.

[Copilot]

Pull request overview

Adds a reusable “aggregate cracking time” computation and exposes it as an aggregate field on AgentAssignment (and refactors Agent’s existing aggregate to use the shared implementation), aligning with the enhancement request to aggregate time spent on a specific task by an agent.

Changes:

• Introduces TaskUtils::getAggregateCrackingTime(agentId, taskId?) to compute summed cracking time from chunk timestamps.
• Adds an assignment.crackingTime aggregate fieldset to AgentAssignmentAPI.
• Adds/updates PHPUnit and API tests to validate the new aggregation behavior.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
src/inc/utils/TaskUtils.php	Adds shared aggregate cracking-time helper (agent-wide or agent+task).
src/inc/apiv2/model/AgentAssignmentAPI.php	Exposes cracking-time aggregation on AgentAssignment via aggregate fieldsets.
src/inc/apiv2/model/AgentAPI.php	Refactors Agent crackingTime aggregation to call the shared TaskUtils helper.
ci/phpunit/inc/utils/TaskUtilsTest.php	Adds PHPUnit coverage for the new aggregate cracking-time helper.
ci/apiv2/test_agentassignment.py	Adds API-level test for AgentAssignment crackingTime aggregation.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[s3inlc]

I agree with your consolidation, but I think it would be better to move it to AgentUtils and not TaskUtils, as it's agent dependent (and Task only in certain cases). Especially, as this way of do the diff of the sums only works when calculating for one agent, but not if for example we calculate the time which has been spent on task (wall clock time).

[novasam23]

@s3inlc I moved the code for the cracking time aggregation to the AgentUtils as you suggested, I agree that this class is a better fit.

I also refactored the PHP unit test code accordingly to correspond with this change.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.