Todo System Documentation

Overview

The Todo System is a comprehensive task management module within the Comserv application that allows administrators to create, manage, and track tasks with advanced filtering, time tracking, and project integration capabilities.

System Architecture

Controller: Comserv::Controller::Todo

Location: /home/shanta/PycharmProjects/comserv2/Comserv/lib/Comserv/Controller/Todo.pm

The Todo controller handles all HTTP requests related to todo management and implements the following key features:

• Access Control: Admin-only access with session validation (Legacy authentication - needs AdminAuth migration)
• CRUD Operations: Create, Read, Update, Delete functionality
• Advanced Filtering: Date-based, project-based, and status-based filtering
• Time Tracking Integration: Integration with the logging system for time accumulation
• Enhanced Logging: Uses Comserv::Util::Logging for detailed operation tracking

Model: Comserv::Model::Todo

Location: /home/shanta/PycharmProjects/comserv2/Comserv/lib/Comserv/Model/Todo.pm

The Todo model provides business logic for:

• Fetching todos with role-based access control
• Date-based todo retrieval
• Individual todo record fetching

Database Schema: Comserv::Model::Schema::Ency::Result::Todo

Location: /home/shanta/PycharmProjects/comserv2/Comserv/lib/Comserv/Model/Schema/Ency/Result/Todo.pm

Database Structure

The todo table contains the following fields:

Relationships

• User Relationship: belongs_to user => 'Comserv::Model::Schema::Ency::Result::User'
• Project Relationship: belongs_to project => 'Comserv::Model::Schema::Ency::Result::Project'
• Log Relationship: has_many logs => 'Comserv::Model::Schema::Ency::Result::Log'

Available Routes and Actions

Main Todo Management

/todo - Main Todo List

• Method: GET
• Access: Admin only
• Features:
  • Displays all todos for the current site
  • Advanced filtering by date, project, status, and search terms
  • Pagination and sorting by priority and start date
  • Status filtering (new, in progress, completed, all)
  • Project-based filtering with dropdown
  • Search functionality across subject, description, and comments

Query Parameters:

• filter: Date filter (all, day, today, week, month)
• search: Search term for subject/description/comments
• project_id: Filter by specific project
• status: Filter by status (new, in_progress, completed, all)

/todo/details - Todo Details View

• Method: GET
• Parameters: record_id (query parameter)
• Features:
  • Displays detailed todo information
  • Shows accumulated time from log entries
  • Formatted time display (HH:MM format)

/todo/addtodo - Add New Todo Form

• Method: GET
• Features:
  • Form for creating new todos
  • Project dropdown with hierarchical display
  • User selection dropdown
  • Pre-population from query parameters

/todo/edit/{record_id} - Edit Todo Form

• Method: GET
• Parameters: record_id (URL parameter)
• Features:
  • Pre-populated form with existing todo data
  • Project and user dropdowns
  • Accumulated time display
  • Error handling for invalid record IDs

/todo/modify/{record_id} - Update Todo

• Method: POST
• Parameters: record_id (URL parameter)
• Features:
  • Updates existing todo records
  • Form validation
  • Error handling and user feedback
  • Automatic last modification tracking

/todo/create - Create New Todo

• Method: POST
• Features:
  • Creates new todo records
  • Handles manual project ID input
  • Automatic project code resolution
  • Default value assignment
  • Session-based user tracking

Time-Based Views

/todo/day/{date} - Daily Todo View

• Method: GET
• Parameters: date (optional, ISO format)
• Features:
  • Shows todos due or starting on specific date
  • Navigation to previous/next day
  • Defaults to current date if none specified
  • Date validation with fallback

/todo/week/{date} - Weekly Todo View

• Method: GET
• Parameters: date (optional, ISO format)
• Features:
  • Shows todos for the current week
  • Includes overdue but incomplete todos
  • Week navigation (previous/next)
  • Automatic week boundary calculation

/todo/month/{date} - Monthly Todo View

• Method: GET
• Parameters: date (optional, ISO format)
• Features:
  • Calendar-style monthly view
  • Todos organized by day
  • Month navigation
  • Visual calendar layout with todo counts per day

Utility Routes

/todo/debug - Debug Information

• Method: GET
• Access: Admin only
• Features:
  • Displays system debugging information
  • Template plugin availability checking
  • INC path information

Status Values

The system uses the following status values:

• 1: New
• 2: In Progress
• 3: Completed

Status 3 (Completed) todos are excluded from most views by default unless explicitly requested.

Priority System

Todos are sorted by priority (ascending) where lower numbers indicate higher priority.

Integration Features

Project Integration

• Full integration with the Project management system
• Hierarchical project display in dropdowns
• Automatic project code resolution
• Project-based filtering and reporting

User Management Integration

• User assignment and tracking
• Session-based user identification
• Role-based access control (admin only)

Time Tracking Integration

• Integration with the Log system for time tracking
• Automatic accumulative time calculation
• Time display in HH:MM format
• Historical time tracking through log entries

Logging Integration

• Comprehensive logging using log_with_details method
• Action tracking and debugging information
• Error logging and user feedback
• Performance monitoring

Security Features

Access Control

• Admin-only access: All todo operations require admin role
• Session validation: Comprehensive session checking in begin and auto methods
• Role verification: Multiple layers of role checking
• Site isolation: Todos are filtered by site name from session

Data Validation

• Record ID validation: Proper handling of missing or invalid IDs
• Form validation: Required field checking (e.g., sitename)
• Date validation: ISO8601 date format validation with fallbacks
• Input sanitization: Proper parameter handling and validation

Error Handling

The system implements comprehensive error handling:

• Database errors: Try/catch blocks with user-friendly error messages
• Missing records: Graceful handling of non-existent todos
• Invalid parameters: Validation with appropriate error responses
• Session issues: Automatic redirect to login for session problems
• Permission errors: Clear messaging for unauthorized access

Templates and UI

The system expects the following template files:

• todo/todo.tt - Main todo list view
• todo/details.tt - Todo details and edit form
• todo/addtodo.tt - New todo creation form
• todo/edit.tt - Todo editing form
• todo/day.tt - Daily todo view
• todo/week.tt - Weekly todo view
• todo/month.tt - Monthly calendar view

CSS Styling

• CSS File: /static/css/todo.css
• Conditional Loading: CSS is loaded only for todo-related pages
• Responsive Design: Templates support responsive layouts

Configuration

Session Requirements

• username: Current user identification
• roles: User roles (must include 'admin')
• SiteName: Site context for todo filtering
• user_id: User ID for todo assignment
• debug_mode: Controls debug information display

Default Values

• Due Date: 7 days from creation if not specified
• Status: Configurable default status
• Priority: Configurable default priority
• Share: Defaults to 0 (not shared)
• Accumulative Time: Defaults to 0

Performance Considerations

Database Optimization

• Indexed Fields: Primary key and foreign key indexing
• Query Optimization: Efficient filtering and sorting queries
• Result Limiting: Top 10 todos in model methods
• Site-based Filtering: Reduces query scope

Caching

• Session Caching: Todo data cached in session where appropriate
• Template Caching: Template Toolkit caching for performance

Maintenance and Monitoring

Logging

All todo operations are logged with detailed information including:

• User actions and access attempts
• Database operations and errors
• Performance metrics
• Security events

Debugging

• Debug Mode: Comprehensive debugging information available
• Error Tracking: Detailed error logging and user feedback
• Performance Monitoring: Action timing and resource usage

Authentication Migration Status

Current Status: The Todo controller uses legacy authentication patterns and needs migration to the centralized AdminAuth system.

Required Migration Steps

1. Add AdminAuth Import: use Comserv::Util::AdminAuth;
2. Add admin_auth Method:

   sub admin_auth {
       my ($self) = @_;
       return Comserv::Util::AdminAuth->new();
   }

3. Replace begin Method: Replace custom authentication logic with:

   sub begin :Private {
       my ($self, $c) = @_;
       return unless $self->admin_auth->require_admin_access($c, 'todo_access');
   }

4. Update auto Method: Simplify authentication checks using centralized utility
5. Remove Custom Logic: Remove manual role checking and session validation code

Benefits of Migration

• Consistent Authentication: Same authentication logic as other admin controllers
• Enhanced Session Validation: Multi-source username checking and fallback handling
• Better Debugging: Centralized authentication logging and error handling
• CSC Admin Support: Proper support for CSC admin users
• Reduced Code: Elimination of duplicate authentication code

Future Enhancements

Potential areas for system enhancement:

1. Authentication Migration: Migrate to centralized AdminAuth system (Priority 1)
2. Notification System: Email/SMS notifications for due dates
3. Attachment Support: File attachments to todos
4. Subtask Management: Hierarchical todo relationships
5. Reporting Dashboard: Analytics and reporting features
6. API Integration: REST API for external integrations
7. Mobile Optimization: Enhanced mobile interface
8. Collaboration Features: Comments and collaboration tools
9. Workflow Management: Custom workflow states and transitions

Troubleshooting

Common Issues

1. Access Denied: Ensure user has admin role in session
2. Session Expired: Check session validity and re-login
3. Missing Todos: Verify site name in session matches todo records
4. Date Format Errors: Ensure dates are in ISO8601 format (YYYY-MM-DD)
5. Project Integration: Verify project controller availability

Debug Mode

Enable debug mode in session to see:

• Detailed logging information
• Template debugging data
• Database query information
• Performance metrics

Related Documentation

• Logging Best Practices
• Project Management System
• User Management Documentation
• Database Schema Documentation

This documentation reflects the current state of the Todo system as of January 20, 2025. For the most up-to-date information, refer to the source code and changelog.