Orchestrator/.kiro/specs/call-list/requirements.md

Requirements Document

Introduction

The Call List feature adds a dedicated "📞 Calls" tab to OrgMyLife that acts as a separate funnel for phone-call tasks. Users can promote any existing task to the Call List, where it is tracked with call-specific metadata (person, phone number, reason). Phone numbers are auto-extracted from email bodies using German format patterns. The Call List integrates with the Daily Digest to surface pending calls.

Glossary

• Call_List_Service: The backend service responsible for managing call items, including creation, retrieval, updates, and deletion via the REST API.
• Call_Item: A database entity representing a phone call to be made, containing person name, reason, phone number, priority, status, and a reference to the originating task.
• Phone_Extractor: The component that scans email body text and extracts phone numbers matching German telephone formats.
• Frontend_Call_View: The UI tab ("📞 Calls") that displays pending and completed call items with sorting and action controls.
• Task_List_View: The existing "All Tasks" UI view showing open tasks with action buttons.
• Daily_Digest_Service: The existing service that generates the daily summary of overdue tasks, priorities, and schedule.
• Original_Task: The existing Task entity from which a Call_Item is derived.

Requirements

Requirement 1: Create Call Item from Task

User Story: As a user, I want to move a task to the Call List by clicking a phone icon, so that I can track phone calls separately from regular tasks.

Acceptance Criteria

1. WHEN the user clicks the phone icon button on a task in the Task_List_View, THE Call_List_Service SHALL create a new Call_Item linked to the Original_Task.
2. WHEN a Call_Item is created from an Original_Task, THE Call_List_Service SHALL populate the Call_Item person field with the task sender name if the origin is "gmail" or "dhive_email".
3. WHEN a Call_Item is created from an Original_Task, THE Call_List_Service SHALL populate the Call_Item reason field with the Original_Task title.
4. WHEN a Call_Item is created from an Original_Task that has an email body, THE Phone_Extractor SHALL scan the email body and populate the Call_Item phone_number field with the first extracted number.
5. WHEN a Call_Item is created, THE Call_List_Service SHALL assign a default priority of 3 (Medium) and a status of "pending".

Requirement 2: Call List REST API

User Story: As a developer, I want a complete CRUD API for call items, so that the frontend and external integrations can manage the Call List.

Acceptance Criteria

1. WHEN a POST request is sent to /api/calls with valid call item data, THE Call_List_Service SHALL create a new Call_Item and return the created item with its ID.
2. WHEN a GET request is sent to /api/calls, THE Call_List_Service SHALL return all Call_Items with status "pending" ordered by priority then creation date.
3. WHEN a PUT request is sent to /api/calls/{id} with update data, THE Call_List_Service SHALL update the specified Call_Item fields and return the updated item.
4. WHEN a DELETE request is sent to /api/calls/{id}, THE Call_List_Service SHALL remove the specified Call_Item from the database.
5. WHEN an unauthenticated request is sent to any /api/calls endpoint, THE Call_List_Service SHALL return HTTP 401.
6. WHEN a request references a non-existent Call_Item ID, THE Call_List_Service SHALL return HTTP 404.

Requirement 3: Call Item Data Model

User Story: As a developer, I want a dedicated CallItem model with call-specific fields, so that call metadata is stored separately from general tasks.

Acceptance Criteria

1. THE Call_Item SHALL store the following fields: id (integer, primary key), person (string, required), reason (string, required), phone_number (string, nullable), original_task_id (integer, nullable foreign key to tasks), priority (integer, default 3), status (string, default "pending"), created_at (timestamp with timezone).
2. WHEN a Call_Item references an Original_Task, THE Call_Item original_task_id SHALL be a valid foreign key to the tasks table.
3. THE Call_Item status field SHALL accept only the values "pending" and "done".

Requirement 4: Phone Number Extraction from Email

User Story: As a user, I want phone numbers automatically extracted from email bodies, so that I do not have to manually look up contact numbers.

Acceptance Criteria

1. WHEN an email body is provided, THE Phone_Extractor SHALL identify phone numbers in the format +49 followed by 9 to 12 digits with optional spaces or hyphens.
2. WHEN an email body is provided, THE Phone_Extractor SHALL identify phone numbers in the format 0 followed by 3 to 5 digit area code and 4 to 8 digit subscriber number with optional separators.
3. WHEN an email body is provided, THE Phone_Extractor SHALL identify phone numbers in the format (0xxx) followed by subscriber digits with optional separators.
4. WHEN multiple phone numbers are found in an email body, THE Phone_Extractor SHALL return the first match.
5. WHEN no phone number is found in an email body, THE Phone_Extractor SHALL return null.
6. FOR ALL valid German phone number strings, parsing then formatting then parsing SHALL produce an equivalent normalized result (round-trip property).

Requirement 5: Call List Frontend Tab

User Story: As a user, I want a dedicated "📞 Calls" tab in the navigation, so that I can view and manage my pending calls in one place.

Acceptance Criteria

1. THE Frontend_Call_View SHALL display a "📞 Calls" navigation button in the top navigation bar between "Projects" and "Daily Digest".
2. WHEN the user navigates to the Calls tab, THE Frontend_Call_View SHALL display all pending Call_Items showing person name, reason, phone number, and priority.
3. WHEN a Call_Item has a phone_number, THE Frontend_Call_View SHALL display the phone number as a clickable tel: link.
4. THE Frontend_Call_View SHALL provide a button to mark a Call_Item as done.
5. THE Frontend_Call_View SHALL provide a button to delete a Call_Item.
6. THE Frontend_Call_View SHALL allow editing the phone_number field inline.
7. THE Frontend_Call_View SHALL order Call_Items by priority (ascending) then by creation date (ascending).

Requirement 6: Phone Icon on Task Items

User Story: As a user, I want a phone icon button on each task, so that I can quickly send any task to the Call List.

Acceptance Criteria

1. THE Task_List_View SHALL display a 📞 icon button on each task item alongside the existing action buttons.
2. WHEN the user clicks the 📞 button on a task, THE Frontend_Call_View SHALL send a POST request to /api/calls with the task data.
3. WHEN the Call_Item is successfully created from a task, THE Frontend_Call_View SHALL display a confirmation indicator to the user.

Requirement 7: Daily Digest Integration

User Story: As a user, I want to see pending calls in my Daily Digest, so that I am reminded of calls I need to make today.

Acceptance Criteria

1. WHEN the Daily Digest is generated, THE Daily_Digest_Service SHALL include a "📞 Calls to make" section listing all Call_Items with status "pending".
2. WHEN there are pending Call_Items, THE Daily_Digest_Service SHALL display each item with person name and reason.
3. WHEN there are no pending Call_Items, THE Daily_Digest_Service SHALL omit the calls section from the digest.

Requirement 8: Complete Call and Resolve Original Task

User Story: As a user, I want the option to mark the original task as done when I complete a call, so that I do not have to update both items manually.

Acceptance Criteria

1. WHEN a Call_Item is marked as done and the Call_Item has an original_task_id, THE Call_List_Service SHALL offer the option to also mark the Original_Task as "completed".
2. WHEN the user confirms marking the Original_Task as completed, THE Call_List_Service SHALL update the Original_Task status to "completed" and trigger the same side effects as the existing task completion flow (email archiving, Nextcloud sync).
3. WHEN the user declines marking the Original_Task as completed, THE Call_List_Service SHALL only update the Call_Item status to "done" without modifying the Original_Task.

Requirement 9: Input Validation

User Story: As a developer, I want call item inputs validated, so that the database contains only well-formed data.

Acceptance Criteria

1. WHEN a POST or PUT request is sent with a person field exceeding 200 characters, THE Call_List_Service SHALL truncate the value to 200 characters.
2. WHEN a POST or PUT request is sent with a reason field exceeding 500 characters, THE Call_List_Service SHALL truncate the value to 500 characters.
3. WHEN a POST or PUT request is sent with a phone_number field exceeding 30 characters, THE Call_List_Service SHALL truncate the value to 30 characters.
4. WHEN a POST or PUT request is sent with a priority value outside the range 1 to 4, THE Call_List_Service SHALL clamp the value to the nearest valid bound.
5. WHEN a POST request is sent without a person field, THE Call_List_Service SHALL return HTTP 422 with a validation error.
6. WHEN a POST request is sent without a reason field, THE Call_List_Service SHALL return HTTP 422 with a validation error.