TimeTracker/docs/TASK_MANAGEMENT_README.md

Task Management Feature

Overview

The Task Management feature allows you to break down projects into manageable tasks, track their progress, assign them to team members, and monitor time spent on each task.

Features

Core Functionality

• Task Creation: Create tasks within projects with names, descriptions, and priorities

Markdown Support

Task and project descriptions support Markdown formatting with a rich editor:

• Editing: Task create/edit and Project create/edit pages include a Markdown editor with dark-mode and image uploads

• Rendering: View pages render Markdown via the markdown Jinja filter (app/utils/template_filters.py), sanitized with Bleach

• Supported: headings, emphasis, lists, links, code blocks, tables, images

• Status Tracking: Monitor task progress through different states (To Do, In Progress, Review, Done)

• Priority Management: Set and track task priorities (Low, Medium, High, Urgent)

• Time Estimation: Estimate and track actual time for tasks

• Task Assignment: Assign tasks to team members

• Due Date Tracking: Set deadlines with overdue notifications

Integration

• Project Integration: Tasks are linked to projects and visible in project views
• Time Tracking: Start timers and log time directly to specific tasks
• User Management: Tasks respect user roles and permissions
• Reporting: Include task data in time reports and analytics

Automatic Database Migration

No manual setup required! The Task Management feature automatically creates the necessary database tables and columns when you first start the application.

What Happens Automatically

1. On Application Startup: The system checks if the tasks table exists
2. Table Creation: If missing, the tasks table is automatically created with all required columns
3. Column Addition: The system checks if the task_id column exists in the time_entries table
4. Schema Updates: Any missing database elements are automatically added

Migration Process

The migration runs automatically in these scenarios:

• First Application Startup: When the app starts for the first time
• Database Initialization: During the init_database() process
• Runtime Checks: When the database is accessed for the first time

Migration Logging

The system provides clear feedback during migration:

Task Management: Creating tasks table...
✓ Tasks table created successfully
Task Management: Adding task_id column to time_entries table...
✓ task_id column added to time_entries table
Task Management migration check completed

Usage

Creating Tasks

1. Navigate to Tasks → Create Task
2. Select a project
3. Enter task details (name, description, priority, due date)
4. Optionally assign to a team member
5. Save the task

Managing Task Status

• To Do: New tasks start in this state
• In Progress: Mark when work begins
• Review: Mark when ready for review
• Done: Mark when completed

Time Tracking

• Start Timer: Begin timing work on a specific task
• Manual Entry: Log time spent on tasks with start/end times
• Task View: See total time spent and estimated vs. actual time

Task Views

• All Tasks: Complete list with filtering and search
• My Tasks: Tasks assigned to or created by the current user
• Project Tasks: Tasks within a specific project
• Overdue Tasks: Admin view of all overdue tasks

Filters UI

• The All Tasks page includes a filter panel that is collapsible.
• Use the chevron button near "Filter Tasks" to show/hide the filters.
• Your preference is remembered using localStorage so the panel stays collapsed or expanded across visits.

Inline Client Creation (Quality of Life)

When creating a new project on Projects → Create, you can now create a new client without losing your filled-in project data:

• Click "Create new client" under the Client dropdown to open a modal
• Fill in the minimal client details and submit
• The newly created client is selected automatically and the default hourly rate is prefilled if available

This flow uses an AJAX request to POST /clients/create and updates the client select dynamically, preserving the current project form state.

Database Schema

Tasks Table

CREATE TABLE tasks (
    id INTEGER PRIMARY KEY,
    project_id INTEGER NOT NULL REFERENCES projects(id),
    name VARCHAR(200) NOT NULL,
    description TEXT,
    status VARCHAR(20) DEFAULT 'todo' NOT NULL,
    priority VARCHAR(20) DEFAULT 'medium' NOT NULL,
    estimated_hours FLOAT,
    due_date DATE,
    assigned_to INTEGER REFERENCES users(id),
    created_by INTEGER NOT NULL REFERENCES users(id),
    created_at TIMESTAMP NOT NULL,
    updated_at TIMESTAMP NOT NULL,
    started_at TIMESTAMP,
    completed_at TIMESTAMP
);

Time Entries Table (Updated)

The time_entries table now includes a task_id column:

ALTER TABLE time_entries ADD COLUMN task_id INTEGER REFERENCES tasks(id);

API Endpoints

Task Management

• GET /tasks - List all tasks with filtering
• POST /tasks/create - Create a new task
• GET /tasks/<id> - View task details
• POST /tasks/<id>/edit - Edit task
• POST /tasks/<id>/status - Update task status
• POST /tasks/<id>/priority - Update task priority
• POST /tasks/<id>/assign - Assign task to user
• POST /tasks/<id>/delete - Delete task

API Access

• GET /api/tasks/<id> - Get task data in JSON format
• PUT /api/tasks/<id>/status - Update task status via API

User Roles and Permissions

Regular Users

• Create tasks in projects they have access to
• Update status and priority of their own tasks
• View tasks they're assigned to or created
• Start timers and log time for tasks

Admin Users

• All regular user permissions
• View and manage all tasks across all projects
• Access overdue tasks report
• Assign tasks to any user
• Delete any task

Troubleshooting

Migration Issues

If you encounter migration problems:

1. Check Application Logs: Look for migration-related messages
2. Manual Migration: Use the migration script: python docker/migrate-add-tasks.py
3. Database Reset: As a last resort, recreate the database (data will be lost)

Common Issues

• Missing Tables: Ensure the application has database write permissions
• Column Errors: Check if the time_entries table exists and is accessible
• Permission Errors: Verify database user has ALTER TABLE permissions

Getting Help

• Check the application logs for detailed error messages
• Verify database connectivity and permissions
• Ensure all required Python packages are installed

Development

Adding New Features

The Task Management system is designed to be extensible:

• Add new task statuses in the Task model
• Extend priority levels as needed
• Add custom fields to the task schema
• Create new API endpoints for additional functionality

Testing

• Run the migration test: python docker/migrate-add-tasks.py
• Test task creation and management workflows
• Verify time tracking integration
• Check user permission enforcement