FocusFlow α Sprint Blog Series (Part 3) - Focus Mode & Focus Time Count

[FOCUS_2025_SE]

目录

• 1. Overview
• 2. Function Realization Demonstration
• 2.1 Focus Mode
• 2.2 Countdown
• 2.3 Total Learning Time
• 3. Code Check-in Records (GitHub Commits)
• 4. Core Code Analysis
• 4.1 Task CRUD and Status Update (app.py)
• 4.2 Marking Tasks as Completed
• 4.3 Tag-Based Categorization During Task Creation/Editing
• 5. Sprint Summary

1. Overview

Item	Details
Course	2025 Fall - Software Engineering Class
Assignment Requirement	Team Project - Alpha Sprint Blog
Team Name	FocusFlow
Author	Shengpeng Yang (FZU: 832301120, MU: 23126434)
Goal of this Assignment	Showcase the Alpha Sprint progress, including Focus Mode implementation, Timer logic, and Total Study Time tracking.
Other References	IEEE Std 830-1998, GB/T 8567-2006

Sprint Burndown Chart
We tracked our progress meticulously throughout the sprint. The chart below illustrates our team's velocity in completing the task management user stories against our estimated timeline.

---

2. Function Realization Demonstration

We have successfully implemented the core interfaces for managing learning tasks.

2.1 Focus Mode

We offer a Focus Mode for users to choose from, suitable for times when concentration is needed.

2.2 Countdown

For different learning tasks or personal preferences, we provide various countdown durations to choose from.

2.3 Total Learning Time

In the personal feedback module, users can also view their total learning time.

---

3. Code Check-in Records (GitHub Commits)

Our development process is backed by regular code commits ensuring version control and collaboration.

---

4. Core Code Analysis

The backend logic is powered by Flask and SQLite. Below is an analysis of the key functions in app.py that drive the task management features.

4.1 Task CRUD and Status Update (app.py)

Task Listing with Tags
The /tasks route handles the display of tasks. It fetches tasks specific to the logged-in user and retrieves associated tags for each task to ensure the frontend displays all relevant categorization data.

# app.py
@app.route('/tasks')
@login_required
def tasks():
    # ...
    # Fetch tasks sorted by due date
    tasks = conn.execute('SELECT * FROM tasks WHERE user_id = ? ORDER BY due_date ASC', (user_id,)).fetchall()

    tasks_with_tags = []
    for task in tasks:
        # Fetch tags for each specific task
        tags = conn.execute('SELECT tag FROM task_tags WHERE task_id = ?', (task['id'],)).fetchall()
        task_dict = dict(task)
        task_dict['tags'] = [tag['tag'] for tag in tags]
        # ... (Date formatting logic)
        tasks_with_tags.append(task_dict)
    # ...

Creating and Editing Tasks
We streamlined the creation and editing process into a single route /tasks/add. This function checks if a task_id is present in the form data. If it is, the system performs an UPDATE; otherwise, it performs an INSERT.

# app.py
@app.route('/tasks/add', methods=['POST'])
@login_required
def add_task():
    # ... (Data retrieval from request.form)
    
    if task_id:
        # Edit Mode: Update existing task
        conn.execute('''
            UPDATE tasks 
            SET title = ?, description = ?, course = ?, priority = ?, 
                due_date = ?, repeat = ?, status = ?, updated_at = CURRENT_TIMESTAMP 
            WHERE id = ? 
        ''', (title, description, course, priority, due_date, repeat, status, task_id))
        
        # Clear old tags to re-insert new ones
        conn.execute('DELETE FROM task_tags WHERE task_id = ?', (task_id,))
    else:
        # Create Mode: Insert new task
        cursor = conn.cursor()
        cursor.execute('''
            INSERT INTO tasks (user_id, title, description, course, priority, due_date, repeat, status)
            VALUES (?, ?, ?, ?, ?, ?, ?, ?)
        ''', (user_id, title, description, course, priority, due_date, repeat, status))
        task_id = cursor.lastrowid
    # ...

4.2 Marking Tasks as Completed

To allow for asynchronous status updates (e.g., via AJAX), we implemented a dedicated API endpoint /tasks/update_status/<int:task_id>. This verifies task ownership before updating the status to prevent unauthorized modifications.

# app.py
@app.route('/tasks/update_status/<int:task_id>', methods=['POST'])
@login_required
def update_task_status(task_id):
    # ...
    # Verification: Ensure task belongs to current user
    task = conn.execute('SELECT * FROM tasks WHERE id = ? AND user_id = ?', (task_id, user_id)).fetchone()
    
    # Update status
    conn.execute('UPDATE tasks SET status = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?', (new_status, task_id))
    # ...
    return jsonify({'success': True, 'message': 'Task status updated successfully!'})

4.3 Tag-Based Categorization During Task Creation/Editing

Handling tags requires parsing a comma-separated string from the frontend and creating associations in the task_tags table. This logic is embedded within the add_task route.

# app.py - Inside add_task function
    # ...
    if tags:
        # Split string by comma and strip whitespace
        tag_list = [tag.strip() for tag in tags.split(',') if tag.strip()]

        for tag in tag_list:
            # Insert individual tags into the association table
            conn.execute(
                'INSERT INTO task_tags (task_id, tag) VALUES (?, ?)',
                (task_id, tag)
            )
    # ...

---

5. Sprint Summary

• Completed Deliverables

  • Distraction-Free Focus Interface: A specialized UI that isolates the user by displaying only pending tasks and the active timer, filtering out completed items to reduce cognitive load.
  • Pomodoro State Machine: A robust JavaScript timer (FocusTimer) that automatically manages transitions between "Focus" and "Break" states and handles audio notifications.
  • Session Data Persistence: Backend logic to securely validate and record completed focus durations into the SQLite database via asynchronous API calls.
  • Global Study Statistics: Implementation of a site-wide tracker that calculates and displays the user's total study hours on the navigation bar of every page.

• Technical Challenges and Resolutions:

  • Conditional Data Saving: One major challenge was ensuring that the application only recorded "Focus" time and ignored "Break" time in the database. We resolved this by implementing a state flag (isFocusMode) within the FocusTimer class. The saveFocusSession function is strictly gated behind this flag in the handleTimerComplete method, ensuring only valid learning data is committed.
  • Global Data Accessibility: Displaying the "Total Study Time" on the dashboard and sidebar required access to database statistics across every route. Instead of repeating the query code in every view function, we utilized Flask's @app.before_request decorator. This allows us to calculate the aggregate time once and inject it into the global g object, making it accessible to the base template and all child pages automatically.