TimeTracker/docs/features/TIME_ENTRY_TEMPLATES.md

# Time Entry Templates Feature

## Overview

Time Entry Templates is a productivity feature that allows users to create reusable templates for frequently logged activities. This feature saves time and ensures consistency when tracking recurring tasks.

## Implementation Status

✅ **Complete** - Fully implemented and tested

## Features

### Core Functionality
- ✅ Create, read, update, and delete templates
- ✅ Template includes project, task, duration, notes, tags, and billable settings
- ✅ Usage tracking (count and last used timestamp)
- ✅ One-click start timer from template
- ✅ Template selector in dashboard timer modal
- ✅ Pre-fill manual time entries from templates
- ✅ API endpoints for programmatic access

### User Interface
- ✅ Template management page with grid layout
- ✅ Create and edit forms with project/task selectors
- ✅ Template cards showing usage statistics
- ✅ Dashboard integration for quick access
- ✅ Most recently used templates prioritized

### Backend
- ✅ TimeEntryTemplate model with full relationships
- ✅ CRUD routes with validation
- ✅ Usage tracking and analytics events
- ✅ Integration with existing timer and time entry systems
- ✅ User-scoped templates (privacy)

## Technical Details

### Database Schema

```python
class TimeEntryTemplate(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    user_id = db.Column(db.Integer, db.ForeignKey('users.id'))
    name = db.Column(db.String(200), nullable=False)
    description = db.Column(db.Text)
    project_id = db.Column(db.Integer, db.ForeignKey('projects.id'))
    task_id = db.Column(db.Integer, db.ForeignKey('tasks.id'))
    default_duration_minutes = db.Column(db.Integer)
    default_notes = db.Column(db.Text)
    tags = db.Column(db.String(500))
    billable = db.Column(db.Boolean, default=True)
    usage_count = db.Column(db.Integer, default=0)
    last_used_at = db.Column(db.DateTime)
    created_at = db.Column(db.DateTime)
    updated_at = db.Column(db.DateTime)
```

### Routes

- `GET /templates` - List all templates
- `GET /templates/create` - Create template form
- `POST /templates/create` - Create new template
- `GET /templates/<id>` - View template details
- `GET /templates/<id>/edit` - Edit template form
- `POST /templates/<id>/edit` - Update template
- `POST /templates/<id>/delete` - Delete template

### API Endpoints

- `GET /api/templates` - Get all templates (JSON)
- `GET /api/templates/<id>` - Get single template (JSON)
- `POST /api/templates/<id>/use` - Mark template as used

### Timer Integration

- `GET /timer/start/from-template/<id>` - Start timer directly from template
- `GET /timer/manual?template=<id>` - Pre-fill manual entry form
- Template selector in dashboard start timer modal

## Testing

Comprehensive test suite includes:
- ✅ Model tests (creation, properties, relationships)
- ✅ Route tests (CRUD operations, validation)
- ✅ API tests (endpoints, responses)
- ✅ Integration tests (timer start, usage tracking)
- ✅ Smoke tests (page rendering, workflows)

Test file: `tests/test_time_entry_templates.py` (599 lines)

## Usage Examples

### Creating a Template

```python
template = TimeEntryTemplate(
    user_id=current_user.id,
    name="Daily Standup",
    project_id=project.id,
    task_id=task.id,
    default_duration_minutes=15,
    default_notes="Discussed progress and blockers",
    tags="meeting,standup",
    billable=False
)
db.session.add(template)
db.session.commit()
```

### Starting Timer from Template

```python
# In routes/timer.py
@timer_bp.route('/timer/start/from-template/<int:template_id>')
@login_required
def start_timer_from_template(template_id):
    template = TimeEntryTemplate.query.get_or_404(template_id)
    # Create timer with template data
    new_timer = TimeEntry(
        user_id=current_user.id,
        project_id=template.project_id,
        task_id=template.task_id,
        notes=template.default_notes,
        tags=template.tags,
        billable=template.billable
    )
    template.record_usage()
    db.session.commit()
```

### API Usage

```javascript
// Fetch templates
fetch('/api/templates')
  .then(res => res.json())
  .then(data => {
    data.templates.forEach(template => {
      console.log(template.name, template.usage_count);
    });
  });

// Use template
fetch(`/api/templates/${templateId}/use`, {
  method: 'POST',
  headers: { 'X-CSRFToken': csrfToken }
});
```

## Migration

No database migration required for existing installations - the feature is additive:

```bash
# Run migrations to create time_entry_templates table
flask db upgrade
```

Or for Alembic-based migrations:
```bash
alembic upgrade head
```

## User Documentation

See [Time Entry Templates User Guide](../TIME_ENTRY_TEMPLATES.md) for:
- Step-by-step usage instructions
- Best practices and tips
- Troubleshooting guide
- API reference

## Related Features

- **Time Tracking**: Core time entry and timer functionality
- **Projects**: Template organization by project
- **Tasks**: Template organization by task
- **Reports**: Template usage analytics (future enhancement)

## Future Enhancements

Potential improvements:
- [ ] Template sharing between team members
- [ ] Template categories/folders
- [ ] Template suggestions based on usage patterns
- [ ] Bulk operations on templates
- [ ] Template import/export
- [ ] Template analytics dashboard

## Maintenance

### Database Cleanup

Templates can be cleaned up periodically:

```python
# Delete templates not used in 6+ months
from datetime import datetime, timedelta
cutoff = datetime.utcnow() - timedelta(days=180)
TimeEntryTemplate.query.filter(
    TimeEntryTemplate.last_used_at < cutoff
).delete()
```

### Monitoring

Key metrics to track:
- Template creation rate
- Template usage rate
- Most popular templates
- Templates never used
- Average templates per user

## Support

For issues or questions:
- Check the [User Guide](../TIME_ENTRY_TEMPLATES.md)
- Review [Project Structure](../PROJECT_STRUCTURE.md)
- See [Testing Guide](../TESTING_COVERAGE_GUIDE.md)
- Open an issue on GitHub

## Changelog

### v1.0.0 (Initial Release)
- Complete CRUD operations for templates
- Dashboard integration
- Timer integration
- API endpoints
- Comprehensive test suite
- User documentation