344 lines
13 KiB
Markdown
344 lines
13 KiB
Markdown
# Design Document: Call List Feature
|
|
|
|
## Overview
|
|
|
|
The Call List feature adds a dedicated phone-call tracking system to OrgMyLife. It introduces a new `CallItem` model, a CRUD REST API at `/api/calls`, a phone number extraction service for German formats, a new "📞 Calls" frontend tab, and integration with the existing Daily Digest.
|
|
|
|
The design follows existing OrgMyLife patterns: SQLAlchemy model in `app/models.py`, FastAPI routes in `app/main.py`, service logic in `app/services/`, and vanilla JS frontend in `frontend/js/app.js`.
|
|
|
|
## Architecture
|
|
|
|
```mermaid
|
|
graph TD
|
|
subgraph Frontend
|
|
A[Task List View] -->|📞 button click| B[POST /api/calls]
|
|
C[Calls Tab] -->|load| D[GET /api/calls]
|
|
C -->|mark done| E[PUT /api/calls/:id]
|
|
C -->|delete| F[DELETE /api/calls/:id]
|
|
end
|
|
|
|
subgraph Backend API
|
|
B --> G[Call List Service]
|
|
D --> G
|
|
E --> G
|
|
F --> G
|
|
end
|
|
|
|
subgraph Services
|
|
G --> H[Phone Extractor]
|
|
G --> I[Task Completion Flow]
|
|
J[Daily Digest Service] --> G
|
|
end
|
|
|
|
subgraph Database
|
|
G --> K[(call_items table)]
|
|
I --> L[(tasks table)]
|
|
end
|
|
```
|
|
|
|
### Request Flow: Create Call from Task
|
|
|
|
1. User clicks 📞 on a task in the Task List
|
|
2. Frontend sends `POST /api/calls` with `{ task_id: <id> }`
|
|
3. Backend loads the task, extracts sender name from description
|
|
4. Phone Extractor scans the task description for German phone numbers
|
|
5. CallItem is created with person, reason, phone_number, original_task_id
|
|
6. Response returns the created CallItem
|
|
|
|
### Request Flow: Complete Call with Task Resolution
|
|
|
|
1. User clicks "Done" on a call item that has `original_task_id`
|
|
2. Frontend sends `PUT /api/calls/:id` with `{ status: "done", resolve_task: true }`
|
|
3. Backend marks CallItem as done
|
|
4. If `resolve_task` is true, backend marks the original task as "completed" and triggers existing side effects (email archiving, Nextcloud sync)
|
|
|
|
## Components and Interfaces
|
|
|
|
### 1. CallItem Model (`app/models.py`)
|
|
|
|
New SQLAlchemy model added to the existing models file:
|
|
|
|
```python
|
|
class CallItem(Base):
|
|
__tablename__ = "call_items"
|
|
|
|
id = Column(Integer, primary_key=True, index=True)
|
|
person = Column(String(200), nullable=False)
|
|
reason = Column(String(500), nullable=False)
|
|
phone_number = Column(String(30), nullable=True)
|
|
original_task_id = Column(Integer, ForeignKey("tasks.id"), nullable=True)
|
|
priority = Column(Integer, default=3) # 1=Very High, 2=High, 3=Medium, 4=Low
|
|
status = Column(String, default="pending") # "pending" or "done"
|
|
created_at = Column(DateTime(timezone=True), server_default=func.now())
|
|
```
|
|
|
|
### 2. Phone Extractor Service (`app/services/phone_extractor.py`)
|
|
|
|
Pure function module with no external dependencies:
|
|
|
|
```python
|
|
def extract_phone_number(text: str) -> str | None:
|
|
"""Extract the first German phone number from text.
|
|
|
|
Supports formats:
|
|
- +49 xxx xxxx xxxx (international)
|
|
- 0xxx xxxxxxx (domestic with area code)
|
|
- (0xxx) xxxxxxx (domestic with parenthesized area code)
|
|
|
|
Returns the first match or None.
|
|
"""
|
|
|
|
def normalize_phone_number(raw: str) -> str:
|
|
"""Normalize a phone number string by removing separators and standardizing format."""
|
|
|
|
def parse_phone_number(text: str) -> dict | None:
|
|
"""Parse a phone number string into components: country_code, area_code, subscriber."""
|
|
```
|
|
|
|
### 3. Call List API Routes (`app/main.py`)
|
|
|
|
New endpoints following existing patterns (session auth, Pydantic models):
|
|
|
|
| Method | Path | Description |
|
|
|--------|------|-------------|
|
|
| POST | `/api/calls` | Create call item (from task or manual) |
|
|
| GET | `/api/calls` | List pending call items |
|
|
| PUT | `/api/calls/{id}` | Update call item (status, phone, priority) |
|
|
| DELETE | `/api/calls/{id}` | Remove call item |
|
|
|
|
### 4. Pydantic Request/Response Models
|
|
|
|
```python
|
|
class CallItemCreate(BaseModel):
|
|
task_id: Optional[int] = None # Create from existing task
|
|
person: Optional[str] = None # Required if no task_id
|
|
reason: Optional[str] = None # Required if no task_id
|
|
phone_number: Optional[str] = None
|
|
priority: Optional[int] = 3
|
|
|
|
class CallItemUpdate(BaseModel):
|
|
phone_number: Optional[str] = None
|
|
priority: Optional[int] = None
|
|
status: Optional[str] = None # "pending" or "done"
|
|
resolve_task: Optional[bool] = False # Also complete original task?
|
|
|
|
class CallItemResponse(BaseModel):
|
|
id: int
|
|
person: str
|
|
reason: str
|
|
phone_number: Optional[str]
|
|
original_task_id: Optional[int]
|
|
priority: int
|
|
status: str
|
|
created_at: str
|
|
```
|
|
|
|
### 5. Daily Digest Integration
|
|
|
|
Extend `generate_daily_digest()` in `app/services/digest.py` to query pending CallItems and include a `"pending_calls"` section in the response dict.
|
|
|
|
### 6. Frontend Components
|
|
|
|
- **Navigation**: Add "📞 Calls" button between "Projects" and "Daily Digest"
|
|
- **Calls View** (`#calls-view`): New section with call item list, inline phone edit
|
|
- **Task Item**: Add 📞 button to existing task action buttons
|
|
- **Digest View**: Render the `pending_calls` section when present
|
|
|
|
## Data Models
|
|
|
|
### CallItem Table Schema
|
|
|
|
| Column | Type | Constraints | Default |
|
|
|--------|------|-------------|---------|
|
|
| id | INTEGER | PRIMARY KEY, INDEX | auto |
|
|
| person | VARCHAR(200) | NOT NULL | — |
|
|
| reason | VARCHAR(500) | NOT NULL | — |
|
|
| phone_number | VARCHAR(30) | NULLABLE | NULL |
|
|
| original_task_id | INTEGER | FK → tasks.id, NULLABLE | NULL |
|
|
| priority | INTEGER | — | 3 |
|
|
| status | VARCHAR | — | "pending" |
|
|
| created_at | DATETIME(tz) | — | CURRENT_TIMESTAMP |
|
|
|
|
### Alembic Migration
|
|
|
|
New migration file `005_add_call_items.py`:
|
|
|
|
```python
|
|
def upgrade() -> None:
|
|
op.create_table('call_items',
|
|
sa.Column('id', sa.Integer(), nullable=False),
|
|
sa.Column('person', sa.String(200), nullable=False),
|
|
sa.Column('reason', sa.String(500), nullable=False),
|
|
sa.Column('phone_number', sa.String(30), nullable=True),
|
|
sa.Column('original_task_id', sa.Integer(), nullable=True),
|
|
sa.Column('priority', sa.Integer(), server_default='3'),
|
|
sa.Column('status', sa.String(), server_default="'pending'"),
|
|
sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.text('(CURRENT_TIMESTAMP)')),
|
|
sa.ForeignKeyConstraint(['original_task_id'], ['tasks.id']),
|
|
sa.PrimaryKeyConstraint('id')
|
|
)
|
|
op.create_index(op.f('ix_call_items_id'), 'call_items', ['id'], unique=False)
|
|
op.create_index(op.f('ix_call_items_status'), 'call_items', ['status'], unique=False)
|
|
|
|
def downgrade() -> None:
|
|
op.drop_index(op.f('ix_call_items_status'), table_name='call_items')
|
|
op.drop_index(op.f('ix_call_items_id'), table_name='call_items')
|
|
op.drop_table('call_items')
|
|
```
|
|
|
|
### Relationship to Existing Models
|
|
|
|
```mermaid
|
|
erDiagram
|
|
tasks {
|
|
int id PK
|
|
string title
|
|
text description
|
|
int priority
|
|
string status
|
|
string origin
|
|
string source_id
|
|
}
|
|
call_items {
|
|
int id PK
|
|
string person
|
|
string reason
|
|
string phone_number
|
|
int original_task_id FK
|
|
int priority
|
|
string status
|
|
datetime created_at
|
|
}
|
|
tasks ||--o{ call_items : "original_task_id"
|
|
```
|
|
|
|
## Correctness Properties
|
|
|
|
*A property is a characteristic or behavior that should hold true across all valid executions of a system — essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.*
|
|
|
|
### Property 1: Create-from-task field mapping
|
|
|
|
*For any* valid Task with origin "gmail" or "dhive_email" and a description starting with "From: {name}", creating a CallItem from that task SHALL produce a CallItem where: person equals the extracted sender name, reason equals the task title, original_task_id equals the task ID, priority is 3, and status is "pending".
|
|
|
|
**Validates: Requirements 1.1, 1.2, 1.3, 1.5**
|
|
|
|
### Property 2: Phone number extraction from German formats
|
|
|
|
*For any* text string containing a valid German phone number (in +49, 0xxx, or (0xxx) format), the Phone_Extractor SHALL return a non-null result matching the first phone number occurrence in the text.
|
|
|
|
**Validates: Requirements 4.1, 4.2, 4.3, 4.4**
|
|
|
|
### Property 3: Phone number parse-format round-trip
|
|
|
|
*For any* valid German phone number string, parsing then formatting then parsing again SHALL produce an equivalent normalized result to parsing once.
|
|
|
|
**Validates: Requirements 4.6**
|
|
|
|
### Property 4: Call list ordering
|
|
|
|
*For any* set of pending CallItems with varying priorities and creation dates, the GET /api/calls response SHALL return items sorted by priority ascending, then by created_at ascending within the same priority.
|
|
|
|
**Validates: Requirements 2.2**
|
|
|
|
### Property 5: Field length truncation
|
|
|
|
*For any* string input to person (>200 chars), reason (>500 chars), or phone_number (>30 chars) fields, the stored value SHALL be truncated to the respective maximum length, and the stored value SHALL equal the first N characters of the input.
|
|
|
|
**Validates: Requirements 9.1, 9.2, 9.3**
|
|
|
|
### Property 6: Priority clamping
|
|
|
|
*For any* integer value provided as priority, the stored priority SHALL be clamped to the range [1, 4] — values below 1 become 1, values above 4 become 4.
|
|
|
|
**Validates: Requirements 9.4**
|
|
|
|
### Property 7: Status constraint
|
|
|
|
*For any* status value provided to a CallItem update, only "pending" and "done" SHALL be accepted; any other value SHALL be rejected or ignored.
|
|
|
|
**Validates: Requirements 3.3**
|
|
|
|
### Property 8: Digest includes all pending calls
|
|
|
|
*For any* non-empty set of CallItems with status "pending", the generated daily digest SHALL include a "pending_calls" section containing an entry for each pending item with its person name and reason.
|
|
|
|
**Validates: Requirements 7.1, 7.2**
|
|
|
|
### Property 9: Call completion without task resolution
|
|
|
|
*For any* CallItem with an original_task_id, marking it as "done" with resolve_task=false SHALL update only the CallItem status to "done" without modifying the Original_Task status.
|
|
|
|
**Validates: Requirements 8.3**
|
|
|
|
## Error Handling
|
|
|
|
### API Error Responses
|
|
|
|
| Scenario | HTTP Status | Response Body |
|
|
|----------|-------------|---------------|
|
|
| Unauthenticated request | 401 | `{"detail": "Not authenticated"}` |
|
|
| CallItem not found | 404 | `{"detail": "Call item not found"}` |
|
|
| Missing required field (person/reason) | 422 | Pydantic validation error |
|
|
| Invalid status value | 400 | `{"detail": "Status must be 'pending' or 'done'"}` |
|
|
| Referenced task_id not found | 404 | `{"detail": "Task not found"}` |
|
|
|
|
### Phone Extractor Error Handling
|
|
|
|
- Empty or None input → returns None (no exception)
|
|
- Text with no phone numbers → returns None
|
|
- Malformed numbers (too short/long) → skipped by regex, not returned
|
|
- Non-string input → TypeError raised (caller responsibility)
|
|
|
|
### Task Resolution Errors
|
|
|
|
When completing a call with `resolve_task=true`:
|
|
- If the original task no longer exists → log warning, complete call item only
|
|
- If email archiving fails → log error, still mark task as completed locally
|
|
- Follows the same error handling pattern as existing `update_task` endpoint
|
|
|
|
## Testing Strategy
|
|
|
|
### Property-Based Tests (using Hypothesis)
|
|
|
|
The project uses Python, so **Hypothesis** is the property-based testing library. Each property test runs a minimum of 100 iterations.
|
|
|
|
Tests will be placed in `OrgMyLife/tests/test_call_list.py` and `OrgMyLife/tests/test_phone_extractor.py`.
|
|
|
|
**Property tests cover:**
|
|
- Phone number extraction (Properties 2, 3)
|
|
- Field truncation and priority clamping (Properties 5, 6)
|
|
- Status constraint validation (Property 7)
|
|
- Create-from-task field mapping (Property 1)
|
|
- Call list ordering (Property 4)
|
|
- Digest integration (Property 8)
|
|
- Completion without resolution (Property 9)
|
|
|
|
Each test is tagged with: `# Feature: call-list, Property {N}: {description}`
|
|
|
|
Configuration: `@settings(max_examples=100)`
|
|
|
|
### Unit Tests (example-based)
|
|
|
|
- Authentication enforcement (401 for all endpoints)
|
|
- 404 for non-existent IDs
|
|
- DELETE removes item from database
|
|
- POST without person/reason returns 422
|
|
- Phone extractor returns None for text without numbers
|
|
- Digest omits calls section when no pending items exist
|
|
- Frontend renders tel: link for items with phone numbers
|
|
|
|
### Integration Tests
|
|
|
|
- Create call from task → verify task side effects (email archiving) on completion
|
|
- Full flow: create from task → mark done with resolve_task=true → verify original task completed
|
|
- Alembic migration up/down cycle
|
|
|
|
### Test File Structure
|
|
|
|
```
|
|
OrgMyLife/tests/
|
|
├── test_phone_extractor.py # Property tests for extraction + round-trip
|
|
├── test_call_list.py # Property + unit tests for API and service logic
|
|
└── test_call_digest.py # Property tests for digest integration
|
|
```
|