Add task progress tracking methods and enhance UI components
- Introduced a comprehensive guide for users on task progress tracking methods, including manual, weighted, and time-based progress. - Implemented backend support for progress calculations, including SQL functions and migrations to accommodate new progress features. - Enhanced frontend components to support progress input and display, including updates to task and project drawers. - Added localization for new progress-related terms and validation messages. - Integrated real-time updates for task progress and weight changes through socket events.
This commit is contained in:
chamiakJ
173
docs/task-progress-guide-for-users.md
Normal file
173
docs/task-progress-guide-for-users.md
Normal file
@@ -0,0 +1,173 @@
|
||||
# WorkLenz Task Progress Guide for Users
|
||||
|
||||
## Introduction
|
||||
|
||||
WorkLenz offers three different ways to track and calculate task progress, each designed for different project management needs. This guide explains how each method works and when to use them.
|
||||
|
||||
## Available Progress Tracking Methods
|
||||
|
||||
WorkLenz provides these progress tracking methods:
|
||||
|
||||
1. **Manual Progress** - Directly input progress percentages for tasks
|
||||
2. **Weighted Progress** - Assign importance levels (weights) to tasks
|
||||
3. **Time-based Progress** - Calculate progress based on estimated time
|
||||
|
||||
Only one method can be enabled at a time for a project. If none are enabled, progress will be calculated based on task completion status.
|
||||
|
||||
## How to Select a Progress Method
|
||||
|
||||
1. Open the project drawer by clicking on the project settings icon or creating a new project
|
||||
2. In the project settings, find the "Progress Calculation Method" section
|
||||
3. Select your preferred method
|
||||
4. Save your changes
|
||||
|
||||
## Manual Progress Method
|
||||
|
||||
### How It Works
|
||||
|
||||
- You directly enter progress percentages (0-100%) for tasks without subtasks
|
||||
- Parent task progress is calculated as the average of all subtask progress values
|
||||
- Progress is updated in real-time as you adjust values
|
||||
|
||||
### When to Use Manual Progress
|
||||
|
||||
- For creative or subjective work where completion can't be measured objectively
|
||||
- When task progress doesn't follow a linear path
|
||||
- For projects where team members need flexibility in reporting progress
|
||||
|
||||
### Example
|
||||
|
||||
If you have a parent task with three subtasks:
|
||||
- Subtask A: 30% complete
|
||||
- Subtask B: 60% complete
|
||||
- Subtask C: 90% complete
|
||||
|
||||
The parent task will show as 60% complete (average of 30%, 60%, and 90%).
|
||||
|
||||
## Weighted Progress Method
|
||||
|
||||
### How It Works
|
||||
|
||||
- You assign "weight" values to tasks to indicate their importance
|
||||
- More important tasks have higher weights and influence the overall progress more
|
||||
- You still enter manual progress percentages for tasks without subtasks
|
||||
- Parent task progress is calculated using a weighted average
|
||||
|
||||
### When to Use Weighted Progress
|
||||
|
||||
- When some tasks are more important or time-consuming than others
|
||||
- For projects where all tasks aren't equal
|
||||
- When you want key deliverables to have more impact on overall progress
|
||||
|
||||
### Example
|
||||
|
||||
If you have a parent task with three subtasks:
|
||||
- Subtask A: 50% complete, Weight 200 (critical task)
|
||||
- Subtask B: 75% complete, Weight 100 (standard task)
|
||||
- Subtask C: 25% complete, Weight 300 (major task)
|
||||
|
||||
The parent task will be approximately 42% complete, with Subtask C having the greatest impact due to its higher weight.
|
||||
|
||||
### Important Notes About Weights
|
||||
|
||||
- Default weight is 100 if not specified
|
||||
- You can set weights from 0 to any reasonable number (typically 1-1000)
|
||||
- Setting a weight to 0 removes that task from progress calculations
|
||||
- Only explicitly set weights for tasks that should have different importance
|
||||
- Weights are only relevant for subtasks, not for independent tasks
|
||||
|
||||
## Time-based Progress Method
|
||||
|
||||
### How It Works
|
||||
|
||||
- Use the task's time estimate as its "weight" in the progress calculation
|
||||
- You still enter manual progress percentages for tasks without subtasks
|
||||
- Tasks with longer time estimates have more influence on overall progress
|
||||
- Parent task progress is calculated based on time-weighted averages
|
||||
|
||||
### When to Use Time-based Progress
|
||||
|
||||
- For projects with well-defined time estimates
|
||||
- When task importance correlates with its duration
|
||||
- For billing or time-tracking focused projects
|
||||
- When you already maintain accurate time estimates
|
||||
|
||||
### Example
|
||||
|
||||
If you have a parent task with three subtasks:
|
||||
- Subtask A: 40% complete, Estimated Time 2.5 hours
|
||||
- Subtask B: 80% complete, Estimated Time 1 hour
|
||||
- Subtask C: 10% complete, Estimated Time 4 hours
|
||||
|
||||
The parent task will be approximately 29% complete, with the lengthy Subtask C pulling down the overall progress despite Subtask B being mostly complete.
|
||||
|
||||
### Important Notes About Time Estimates
|
||||
|
||||
- Tasks without time estimates don't influence progress calculations
|
||||
- Time is converted to minutes internally (a 2-hour task = 120 minutes)
|
||||
- Setting a time estimate to 0 removes that task from progress calculations
|
||||
- Time estimates serve dual purposes: scheduling/resource planning and progress weighting
|
||||
|
||||
## Default Progress Method
|
||||
|
||||
If none of the special progress methods are enabled, WorkLenz uses a simple completion-based approach:
|
||||
|
||||
### How It Works
|
||||
|
||||
- Tasks are either 0% (not done) or 100% (done)
|
||||
- Parent task progress = (completed tasks / total tasks) × 100%
|
||||
- Both the parent task and all subtasks count in this calculation
|
||||
|
||||
### When to Use Default Progress
|
||||
|
||||
- For simple projects with clear task completion criteria
|
||||
- When binary task status (done/not done) is sufficient
|
||||
- For teams new to project management who want simplicity
|
||||
|
||||
### Example
|
||||
|
||||
If you have a parent task with four subtasks and two of the subtasks are marked complete:
|
||||
- Parent task: Not done
|
||||
- 2 subtasks: Done
|
||||
- 2 subtasks: Not done
|
||||
|
||||
The parent task will show as 40% complete (2 completed out of 5 total tasks).
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Choose the Right Method for Your Project**
|
||||
- Consider your team's workflow and reporting needs
|
||||
- Match the method to your project's complexity
|
||||
|
||||
2. **Be Consistent**
|
||||
- Stick with one method throughout the project
|
||||
- Changing methods mid-project can cause confusion
|
||||
|
||||
3. **For Manual Progress**
|
||||
- Update progress regularly
|
||||
- Establish guidelines for progress reporting
|
||||
|
||||
4. **For Weighted Progress**
|
||||
- Assign weights based on objective criteria
|
||||
- Don't overuse extreme weights
|
||||
|
||||
5. **For Time-based Progress**
|
||||
- Keep time estimates accurate and up to date
|
||||
- Consider using time tracking to validate estimates
|
||||
|
||||
## Frequently Asked Questions
|
||||
|
||||
**Q: Can I change the progress method mid-project?**
|
||||
A: Yes, but it may cause progress values to change significantly. It's best to select a method at the project start.
|
||||
|
||||
**Q: What happens to task progress when I mark a task complete?**
|
||||
A: When a task is marked complete, its progress automatically becomes 100%, regardless of the progress method.
|
||||
|
||||
**Q: How do I enter progress for a task?**
|
||||
A: Open the task drawer, go to the Info tab, and use the progress slider for tasks without subtasks.
|
||||
|
||||
**Q: Can different projects use different progress methods?**
|
||||
A: Yes, each project can have its own progress method.
|
||||
|
||||
**Q: What if I don't see progress fields in my task drawer?**
|
||||
A: Progress input is only visible for tasks without subtasks. Parent tasks' progress is automatically calculated.
|
||||
550
docs/task-progress-methods.md
Normal file
550
docs/task-progress-methods.md
Normal file
@@ -0,0 +1,550 @@
|
||||
# Task Progress Tracking Methods in WorkLenz
|
||||
|
||||
## Overview
|
||||
WorkLenz supports three different methods for tracking task progress, each suitable for different project management approaches:
|
||||
|
||||
1. **Manual Progress** - Direct input of progress percentages
|
||||
2. **Weighted Progress** - Tasks have weights that affect overall progress calculation
|
||||
3. **Time-based Progress** - Progress calculated based on estimated time vs. time spent
|
||||
|
||||
These modes can be selected when creating or editing a project in the project drawer. Only one progress method can be enabled at a time. If none of these methods are enabled, progress will be calculated based on task completion status as described in the "Default Progress Tracking" section below.
|
||||
|
||||
## 1. Manual Progress Mode
|
||||
|
||||
This mode allows direct input of progress percentages for individual tasks without subtasks.
|
||||
|
||||
**Implementation:**
|
||||
- Enabled by setting `use_manual_progress` to true in the project settings
|
||||
- Progress is updated through the `on-update-task-progress.ts` socket event handler
|
||||
- The UI shows a manual progress input slider in the task drawer for tasks without subtasks
|
||||
- Updates the database with `progress_value` and sets `manual_progress` flag to true
|
||||
|
||||
**Calculation Logic:**
|
||||
- For tasks without subtasks: Uses the manually set progress value
|
||||
- For parent tasks: Calculates the average of all subtask progress values
|
||||
- Subtask progress comes from either manual values or completion status (0% or 100%)
|
||||
|
||||
**Code Example:**
|
||||
```typescript
|
||||
// Manual progress update via socket.io
|
||||
socket?.emit(SocketEvents.UPDATE_TASK_PROGRESS.toString(), JSON.stringify({
|
||||
task_id: task.id,
|
||||
progress_value: value,
|
||||
parent_task_id: task.parent_task_id
|
||||
}));
|
||||
```
|
||||
|
||||
## 2. Weighted Progress Mode
|
||||
|
||||
This mode allows assigning different weights to subtasks to reflect their relative importance in the overall task or project progress.
|
||||
|
||||
**Implementation:**
|
||||
- Enabled by setting `use_weighted_progress` to true in the project settings
|
||||
- Weights are updated through the `on-update-task-weight.ts` socket event handler
|
||||
- The UI shows a weight input for subtasks in the task drawer
|
||||
- Manual progress input is still required for tasks without subtasks
|
||||
- Default weight is 100 if not specified
|
||||
|
||||
**Calculation Logic:**
|
||||
- For tasks without subtasks: Uses the manually entered progress value
|
||||
- Progress is calculated using a weighted average: `SUM(progress_value * weight) / SUM(weight)`
|
||||
- This gives more influence to tasks with higher weights
|
||||
- A parent task's progress is the weighted average of its subtasks' progress values
|
||||
|
||||
**Code Example:**
|
||||
```typescript
|
||||
// Weight update via socket.io
|
||||
socket?.emit(SocketEvents.UPDATE_TASK_WEIGHT.toString(), JSON.stringify({
|
||||
task_id: task.id,
|
||||
weight: value,
|
||||
parent_task_id: task.parent_task_id
|
||||
}));
|
||||
```
|
||||
|
||||
## 3. Time-based Progress Mode
|
||||
|
||||
This mode calculates progress based on estimated time vs. actual time spent.
|
||||
|
||||
**Implementation:**
|
||||
- Enabled by setting `use_time_progress` to true in the project settings
|
||||
- Uses task time estimates (hours and minutes) for calculation
|
||||
- Manual progress input is still required for tasks without subtasks
|
||||
- No separate socket handler needed as it's calculated automatically
|
||||
|
||||
**Calculation Logic:**
|
||||
- For tasks without subtasks: Uses the manually entered progress value
|
||||
- Progress is calculated using time as the weight: `SUM(progress_value * estimated_minutes) / SUM(estimated_minutes)`
|
||||
- For tasks with time tracking, estimated vs. actual time can be factored in
|
||||
- Parent task progress is weighted by the estimated time of each subtask
|
||||
|
||||
**SQL Example:**
|
||||
```sql
|
||||
WITH subtask_progress AS (
|
||||
SELECT
|
||||
CASE
|
||||
WHEN manual_progress IS TRUE AND progress_value IS NOT NULL THEN
|
||||
progress_value
|
||||
ELSE
|
||||
CASE
|
||||
WHEN EXISTS(
|
||||
SELECT 1
|
||||
FROM tasks_with_status_view
|
||||
WHERE tasks_with_status_view.task_id = t.id
|
||||
AND is_done IS TRUE
|
||||
) THEN 100
|
||||
ELSE 0
|
||||
END
|
||||
END AS progress_value,
|
||||
COALESCE(total_hours * 60 + total_minutes, 0) AS estimated_minutes
|
||||
FROM tasks t
|
||||
WHERE t.parent_task_id = _task_id
|
||||
AND t.archived IS FALSE
|
||||
)
|
||||
SELECT COALESCE(
|
||||
SUM(progress_value * estimated_minutes) / NULLIF(SUM(estimated_minutes), 0),
|
||||
0
|
||||
)
|
||||
FROM subtask_progress
|
||||
INTO _ratio;
|
||||
```
|
||||
|
||||
## Default Progress Tracking (when no special mode is selected)
|
||||
|
||||
If no specific progress mode is enabled, the system falls back to a traditional completion-based calculation:
|
||||
|
||||
**Implementation:**
|
||||
- Default mode when all three special modes are disabled
|
||||
- Based on task completion status only
|
||||
|
||||
**Calculation Logic:**
|
||||
- For tasks without subtasks: 0% if not done, 100% if done
|
||||
- For parent tasks: `(completed_tasks / total_tasks) * 100`
|
||||
- Counts both the parent and all subtasks in the calculation
|
||||
|
||||
**SQL Example:**
|
||||
```sql
|
||||
-- Traditional calculation based on completion status
|
||||
SELECT (CASE
|
||||
WHEN EXISTS(SELECT 1
|
||||
FROM tasks_with_status_view
|
||||
WHERE tasks_with_status_view.task_id = _task_id
|
||||
AND is_done IS TRUE) THEN 1
|
||||
ELSE 0 END)
|
||||
INTO _parent_task_done;
|
||||
|
||||
SELECT COUNT(*)
|
||||
FROM tasks_with_status_view
|
||||
WHERE parent_task_id = _task_id
|
||||
AND is_done IS TRUE
|
||||
INTO _sub_tasks_done;
|
||||
|
||||
_total_completed = _parent_task_done + _sub_tasks_done;
|
||||
_total_tasks = _sub_tasks_count + 1; -- +1 for the parent task
|
||||
|
||||
IF _total_tasks = 0 THEN
|
||||
_ratio = 0;
|
||||
ELSE
|
||||
_ratio = (_total_completed / _total_tasks) * 100;
|
||||
END IF;
|
||||
```
|
||||
|
||||
## Technical Implementation Details
|
||||
|
||||
The progress calculation logic is implemented in PostgreSQL functions, primarily in the `get_task_complete_ratio` function. Progress updates flow through the system as follows:
|
||||
|
||||
1. **User Action**: User updates task progress or weight in the UI
|
||||
2. **Socket Event**: Client emits socket event (UPDATE_TASK_PROGRESS or UPDATE_TASK_WEIGHT)
|
||||
3. **Server Handler**: Server processes the event in the respective handler function
|
||||
4. **Database Update**: Progress/weight value is updated in the database
|
||||
5. **Recalculation**: If needed, parent task progress is recalculated
|
||||
6. **Broadcast**: Changes are broadcast to all clients in the project room
|
||||
7. **UI Update**: Client UI updates to reflect the new progress values
|
||||
|
||||
This architecture allows for real-time updates and consistent progress calculation across all clients.
|
||||
|
||||
## Manual Progress Input Implementation
|
||||
|
||||
Regardless of which progress tracking method is selected for a project, tasks without subtasks (leaf tasks) require manual progress input. This section details how manual progress input is implemented and used across all progress tracking methods.
|
||||
|
||||
### UI Component
|
||||
|
||||
The manual progress input component is implemented in `worklenz-frontend/src/components/task-drawer/shared/info-tab/details/task-drawer-progress/task-drawer-progress.tsx` and includes:
|
||||
|
||||
1. **Progress Slider**: A slider UI control that allows users to set progress values from 0% to 100%
|
||||
2. **Progress Input Field**: A numeric input field that accepts direct entry of progress percentage
|
||||
3. **Progress Display**: Visual representation of the current progress value
|
||||
|
||||
The component is conditionally rendered in the task drawer for tasks that don't have subtasks.
|
||||
|
||||
**Usage Across Progress Methods:**
|
||||
- In **Manual Progress Mode**: Only the progress slider/input is shown
|
||||
- In **Weighted Progress Mode**: Both the progress slider/input and weight input are shown
|
||||
- In **Time-based Progress Mode**: The progress slider/input is shown alongside time estimate fields
|
||||
|
||||
### Progress Update Flow
|
||||
|
||||
When a user updates a task's progress manually, the following process occurs:
|
||||
|
||||
1. **User Input**: User adjusts the progress slider or enters a value in the input field
|
||||
2. **UI Event Handler**: The UI component captures the change event and validates the input
|
||||
3. **Socket Event Emission**: The component emits a `UPDATE_TASK_PROGRESS` socket event with:
|
||||
```typescript
|
||||
{
|
||||
task_id: task.id,
|
||||
progress_value: value, // The new progress value (0-100)
|
||||
parent_task_id: task.parent_task_id // For recalculation
|
||||
}
|
||||
```
|
||||
4. **Server Processing**: The socket event handler on the server:
|
||||
- Updates the task's `progress_value` in the database
|
||||
- Sets the `manual_progress` flag to true
|
||||
- Triggers recalculation of parent task progress
|
||||
|
||||
### Progress Calculation Across Methods
|
||||
|
||||
The calculation of progress differs based on the active progress method:
|
||||
|
||||
1. **For Leaf Tasks (no subtasks)** in all methods:
|
||||
- Progress is always the manually entered value (`progress_value`)
|
||||
- If the task is marked as completed, progress is automatically set to 100%
|
||||
|
||||
2. **For Parent Tasks**:
|
||||
- **Manual Progress Mode**: Simple average of all subtask progress values
|
||||
- **Weighted Progress Mode**: Weighted average where each subtask's progress is multiplied by its weight
|
||||
- **Time-based Progress Mode**: Weighted average where each subtask's progress is multiplied by its estimated time
|
||||
- **Default Mode**: Percentage of completed tasks (including parent) vs. total tasks
|
||||
|
||||
### Detailed Calculation for Weighted Progress Method
|
||||
|
||||
In Weighted Progress mode, both the manual progress input and weight assignment are critical components:
|
||||
|
||||
1. **Manual Progress Input**:
|
||||
- For leaf tasks (without subtasks), users must manually input progress percentages (0-100%)
|
||||
- If a leaf task is marked as complete, its progress is automatically set to 100%
|
||||
- If a leaf task's progress is not manually set, it defaults to 0% (or 100% if completed)
|
||||
|
||||
2. **Weight Assignment**:
|
||||
- Each task can be assigned a weight value (default 100 if not specified)
|
||||
- Higher weight values give tasks more influence in parent task progress calculations
|
||||
- Weight values are typically whole numbers between 0 and 1000
|
||||
- A weight of 0 means the task doesn't contribute to the parent's progress calculation
|
||||
|
||||
3. **Parent Task Calculation**:
|
||||
The weighted progress formula is:
|
||||
```
|
||||
ParentProgress = ∑(SubtaskProgress * SubtaskWeight) / ∑(SubtaskWeight)
|
||||
```
|
||||
|
||||
**Example Calculation**:
|
||||
Consider a parent task with three subtasks:
|
||||
- Subtask A: Progress 50%, Weight 200
|
||||
- Subtask B: Progress 75%, Weight 100
|
||||
- Subtask C: Progress 25%, Weight 300
|
||||
|
||||
Calculation:
|
||||
```
|
||||
ParentProgress = ((50 * 200) + (75 * 100) + (25 * 300)) / (200 + 100 + 300)
|
||||
ParentProgress = (10000 + 7500 + 7500) / 600
|
||||
ParentProgress = 25000 / 600
|
||||
ParentProgress = 41.67%
|
||||
```
|
||||
|
||||
Notice that Subtask C, despite having the lowest progress, has a significant impact on the parent task progress due to its higher weight.
|
||||
|
||||
4. **Zero Weight Handling**:
|
||||
Tasks with zero weight are excluded from the calculation:
|
||||
- Subtask A: Progress 40%, Weight 50
|
||||
- Subtask B: Progress 80%, Weight 0
|
||||
|
||||
Calculation:
|
||||
```
|
||||
ParentProgress = ((40 * 50) + (80 * 0)) / (50 + 0)
|
||||
ParentProgress = 2000 / 50
|
||||
ParentProgress = 40%
|
||||
```
|
||||
|
||||
In this case, only Subtask A influences the parent task progress because Subtask B has a weight of 0.
|
||||
|
||||
5. **Default Weight Behavior**:
|
||||
When weights aren't explicitly assigned to some tasks:
|
||||
- Subtask A: Progress 30%, Weight 60 (explicitly set)
|
||||
- Subtask B: Progress 70%, Weight not set (defaults to 100)
|
||||
- Subtask C: Progress 90%, Weight not set (defaults to 100)
|
||||
|
||||
Calculation:
|
||||
```
|
||||
ParentProgress = ((30 * 60) + (70 * 100) + (90 * 100)) / (60 + 100 + 100)
|
||||
ParentProgress = (1800 + 7000 + 9000) / 260
|
||||
ParentProgress = 17800 / 260
|
||||
ParentProgress = 68.46%
|
||||
```
|
||||
|
||||
Note that Subtasks B and C have more influence than Subtask A because they have higher default weights.
|
||||
|
||||
6. **All Zero Weights Edge Case**:
|
||||
If all subtasks have zero weight, the progress is calculated as 0%:
|
||||
```
|
||||
ParentProgress = SUM(progress_value * 0) / SUM(0) = 0 / 0 = undefined
|
||||
```
|
||||
|
||||
The SQL implementation handles this with `NULLIF` and `COALESCE` to return 0% in this case.
|
||||
|
||||
4. **Actual SQL Implementation**:
|
||||
The database function implements the weighted calculation as follows:
|
||||
```sql
|
||||
WITH subtask_progress AS (
|
||||
SELECT
|
||||
CASE
|
||||
-- If subtask has manual progress, use that value
|
||||
WHEN manual_progress IS TRUE AND progress_value IS NOT NULL THEN
|
||||
progress_value
|
||||
-- Otherwise use completion status (0 or 100)
|
||||
ELSE
|
||||
CASE
|
||||
WHEN EXISTS(
|
||||
SELECT 1
|
||||
FROM tasks_with_status_view
|
||||
WHERE tasks_with_status_view.task_id = t.id
|
||||
AND is_done IS TRUE
|
||||
) THEN 100
|
||||
ELSE 0
|
||||
END
|
||||
END AS progress_value,
|
||||
COALESCE(weight, 100) AS weight
|
||||
FROM tasks t
|
||||
WHERE t.parent_task_id = _task_id
|
||||
AND t.archived IS FALSE
|
||||
)
|
||||
SELECT COALESCE(
|
||||
SUM(progress_value * weight) / NULLIF(SUM(weight), 0),
|
||||
0
|
||||
)
|
||||
FROM subtask_progress
|
||||
INTO _ratio;
|
||||
```
|
||||
|
||||
This SQL implementation:
|
||||
- Gets all non-archived subtasks of the parent task
|
||||
- For each subtask, determines its progress value:
|
||||
- If manual progress is set, uses that value
|
||||
- Otherwise, uses 100% if the task is done or 0% if not done
|
||||
- Uses COALESCE to default weight to 100 if not specified
|
||||
- Calculates the weighted average, handling the case where sum of weights might be zero
|
||||
- Returns 0 if there are no subtasks with weights
|
||||
|
||||
### Detailed Calculation for Time-based Progress Method
|
||||
|
||||
In Time-based Progress mode, the task's estimated time serves as its weight in progress calculations:
|
||||
|
||||
1. **Manual Progress Input**:
|
||||
- As with weighted progress, leaf tasks require manual progress input
|
||||
- Progress is entered as a percentage (0-100%)
|
||||
- Completed tasks are automatically set to 100% progress
|
||||
|
||||
2. **Time Estimation**:
|
||||
- Each task has an estimated time in hours and minutes
|
||||
- These values are stored in `total_hours` and `total_minutes` fields
|
||||
- Time estimates effectively function as weights in progress calculations
|
||||
- Tasks with longer estimated durations have more influence on parent task progress
|
||||
- Tasks with zero or no time estimate don't contribute to the parent's progress calculation
|
||||
|
||||
3. **Parent Task Calculation**:
|
||||
The time-based progress formula is:
|
||||
```
|
||||
ParentProgress = ∑(SubtaskProgress * SubtaskEstimatedMinutes) / ∑(SubtaskEstimatedMinutes)
|
||||
```
|
||||
where `SubtaskEstimatedMinutes = (SubtaskHours * 60) + SubtaskMinutes`
|
||||
|
||||
**Example Calculation**:
|
||||
Consider a parent task with three subtasks:
|
||||
- Subtask A: Progress 40%, Estimated Time 2h 30m (150 minutes)
|
||||
- Subtask B: Progress 80%, Estimated Time 1h (60 minutes)
|
||||
- Subtask C: Progress 10%, Estimated Time 4h (240 minutes)
|
||||
|
||||
Calculation:
|
||||
```
|
||||
ParentProgress = ((40 * 150) + (80 * 60) + (10 * 240)) / (150 + 60 + 240)
|
||||
ParentProgress = (6000 + 4800 + 2400) / 450
|
||||
ParentProgress = 13200 / 450
|
||||
ParentProgress = 29.33%
|
||||
```
|
||||
|
||||
Note how Subtask C, with its large time estimate, significantly pulls down the overall progress despite Subtask B being mostly complete.
|
||||
|
||||
4. **Zero Time Estimate Handling**:
|
||||
Tasks with zero time estimate are excluded from the calculation:
|
||||
- Subtask A: Progress 40%, Estimated Time 3h (180 minutes)
|
||||
- Subtask B: Progress 80%, Estimated Time 0h (0 minutes)
|
||||
|
||||
Calculation:
|
||||
```
|
||||
ParentProgress = ((40 * 180) + (80 * 0)) / (180 + 0)
|
||||
ParentProgress = 7200 / 180
|
||||
ParentProgress = 40%
|
||||
```
|
||||
|
||||
In this case, only Subtask A influences the parent task progress because Subtask B has no time estimate.
|
||||
|
||||
5. **All Zero Time Estimates Edge Case**:
|
||||
If all subtasks have zero time estimates, the progress is calculated as 0%:
|
||||
```
|
||||
ParentProgress = SUM(progress_value * 0) / SUM(0) = 0 / 0 = undefined
|
||||
```
|
||||
|
||||
The SQL implementation handles this with `NULLIF` and `COALESCE` to return 0% in this case.
|
||||
|
||||
6. **Actual SQL Implementation**:
|
||||
The SQL function for this calculation first converts hours to minutes for consistent measurement:
|
||||
```sql
|
||||
WITH subtask_progress AS (
|
||||
SELECT
|
||||
CASE
|
||||
-- If subtask has manual progress, use that value
|
||||
WHEN manual_progress IS TRUE AND progress_value IS NOT NULL THEN
|
||||
progress_value
|
||||
-- Otherwise use completion status (0 or 100)
|
||||
ELSE
|
||||
CASE
|
||||
WHEN EXISTS(
|
||||
SELECT 1
|
||||
FROM tasks_with_status_view
|
||||
WHERE tasks_with_status_view.task_id = t.id
|
||||
AND is_done IS TRUE
|
||||
) THEN 100
|
||||
ELSE 0
|
||||
END
|
||||
END AS progress_value,
|
||||
COALESCE(total_hours * 60 + total_minutes, 0) AS estimated_minutes
|
||||
FROM tasks t
|
||||
WHERE t.parent_task_id = _task_id
|
||||
AND t.archived IS FALSE
|
||||
)
|
||||
SELECT COALESCE(
|
||||
SUM(progress_value * estimated_minutes) / NULLIF(SUM(estimated_minutes), 0),
|
||||
0
|
||||
)
|
||||
FROM subtask_progress
|
||||
INTO _ratio;
|
||||
```
|
||||
|
||||
This implementation:
|
||||
- Gets all non-archived subtasks of the parent task
|
||||
- Determines each subtask's progress value (manual or completion-based)
|
||||
- Calculates total minutes by converting hours to minutes and adding them together
|
||||
- Uses COALESCE to treat NULL time estimates as 0 minutes
|
||||
- Uses NULLIF to handle cases where all time estimates are zero
|
||||
- Returns 0% progress if there are no subtasks with time estimates
|
||||
|
||||
### Common Implementation Considerations
|
||||
|
||||
For both weighted and time-based progress calculation:
|
||||
|
||||
1. **Null Handling**:
|
||||
- Tasks with NULL progress values are treated as 0% progress (unless completed)
|
||||
- Tasks with NULL weights default to 100 in weighted mode
|
||||
- Tasks with NULL time estimates are treated as 0 minutes in time-based mode
|
||||
|
||||
2. **Progress Propagation**:
|
||||
- When a leaf task's progress changes, all ancestor tasks are recalculated
|
||||
- Progress updates are propagated through socket events to all connected clients
|
||||
- The recalculation happens server-side to ensure consistency
|
||||
|
||||
3. **Edge Cases**:
|
||||
- If all subtasks have zero weight/time, the system falls back to a simple average
|
||||
- If a parent task has no subtasks, its own manual progress value is used
|
||||
- If a task is archived, it's excluded from parent task calculations
|
||||
|
||||
### Database Implementation
|
||||
|
||||
The manual progress value is stored in the `tasks` table with these relevant fields:
|
||||
|
||||
```sql
|
||||
tasks (
|
||||
-- other fields
|
||||
progress_value FLOAT, -- The manually entered progress value (0-100)
|
||||
manual_progress BOOLEAN, -- Flag indicating if progress was manually set
|
||||
weight INTEGER DEFAULT 100, -- For weighted progress calculation
|
||||
total_hours INTEGER, -- For time-based progress calculation
|
||||
total_minutes INTEGER -- For time-based progress calculation
|
||||
)
|
||||
```
|
||||
|
||||
### Integration with Parent Task Calculation
|
||||
|
||||
When a subtask's progress is updated manually, the parent task's progress is automatically recalculated based on the active progress method:
|
||||
|
||||
```typescript
|
||||
// Pseudocode for parent task recalculation
|
||||
function recalculateParentTaskProgress(taskId, parentTaskId) {
|
||||
if (!parentTaskId) return;
|
||||
|
||||
// Get project settings to determine active progress method
|
||||
const project = getProjectByTaskId(taskId);
|
||||
|
||||
if (project.use_manual_progress) {
|
||||
// Calculate average of all subtask progress values
|
||||
updateParentProgress(parentTaskId, calculateAverageProgress(parentTaskId));
|
||||
}
|
||||
else if (project.use_weighted_progress) {
|
||||
// Calculate weighted average using subtask weights
|
||||
updateParentProgress(parentTaskId, calculateWeightedProgress(parentTaskId));
|
||||
}
|
||||
else if (project.use_time_progress) {
|
||||
// Calculate weighted average using time estimates
|
||||
updateParentProgress(parentTaskId, calculateTimeBasedProgress(parentTaskId));
|
||||
}
|
||||
else {
|
||||
// Default: Calculate based on task completion
|
||||
updateParentProgress(parentTaskId, calculateCompletionBasedProgress(parentTaskId));
|
||||
}
|
||||
|
||||
// If this parent has a parent, continue recalculation up the tree
|
||||
const grandparentId = getParentTaskId(parentTaskId);
|
||||
if (grandparentId) {
|
||||
recalculateParentTaskProgress(parentTaskId, grandparentId);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This recursive approach ensures that changes to any task's progress are properly propagated up the task hierarchy.
|
||||
|
||||
## Associated Files and Components
|
||||
|
||||
### Backend Files
|
||||
|
||||
1. **Socket Event Handlers**:
|
||||
- `worklenz-backend/src/socket.io/commands/on-update-task-progress.ts` - Handles manual progress updates
|
||||
- `worklenz-backend/src/socket.io/commands/on-update-task-weight.ts` - Handles task weight updates
|
||||
|
||||
2. **Database Functions**:
|
||||
- `worklenz-backend/database/migrations/20250423000000-subtask-manual-progress.sql` - Contains the `get_task_complete_ratio` function that calculates progress based on the selected method
|
||||
- Functions that support project creation/updates with progress mode settings:
|
||||
- `create_project`
|
||||
- `update_project`
|
||||
|
||||
3. **Controllers**:
|
||||
- `worklenz-backend/src/controllers/project-workload/workload-gannt-base.ts` - Contains the `calculateTaskCompleteRatio` method
|
||||
- `worklenz-backend/src/controllers/projects-controller.ts` - Handles project-level progress calculations
|
||||
|
||||
### Frontend Files
|
||||
|
||||
1. **Project Configuration**:
|
||||
- `worklenz-frontend/src/components/projects/project-drawer/project-drawer.tsx` - Contains UI for selecting progress method when creating/editing projects
|
||||
|
||||
2. **Progress Visualization Components**:
|
||||
- `worklenz-frontend/src/components/project-list/project-list-table/project-list-progress/progress-list-progress.tsx` - Displays project progress
|
||||
- `worklenz-frontend/src/pages/projects/project-view-1/taskList/taskListTable/taskListTableCells/TaskProgress.tsx` - Displays task progress
|
||||
- `worklenz-frontend/src/pages/projects/projectView/taskList/task-list-table/task-list-table-cells/task-list-progress-cell/task-list-progress-cell.tsx` - Alternative task progress cell
|
||||
|
||||
3. **Progress Input Components**:
|
||||
- `worklenz-frontend/src/components/task-drawer/shared/info-tab/details/task-drawer-progress/task-drawer-progress.tsx` - Component for inputting task progress/weight
|
||||
|
||||
## Choosing the Right Progress Method
|
||||
|
||||
Each progress method is suitable for different types of projects:
|
||||
|
||||
- **Manual Progress**: Best for creative work where progress is subjective
|
||||
- **Weighted Progress**: Ideal for projects where some tasks are more significant than others
|
||||
- **Time-based Progress**: Perfect for projects where time estimates are reliable and important
|
||||
|
||||
Project managers can choose the appropriate method when creating or editing a project in the project drawer, based on their team's workflow and project requirements.
|
||||
Reference in New Issue
Block a user