social-app/docs/plans/2026-03-11-calendar-reminder-metadata-impl.md

# Calendar Reminder Metadata Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** Add `metadata.reminder_minutes` end-to-end (frontend/backend/AgentScope), fix detail-page field rendering, and enable local system reminders.

**Architecture:** Keep calendar schema additive via `metadata` JSON (no new DB columns). Backend validates and persists `reminder_minutes`; AgentScope tools accept and pass reminder values; frontend parses/edits/displays reminder and schedules local notifications based on event time.

**Tech Stack:** Flutter, FastAPI, Pydantic v2, AgentScope toolkit, pytest, flutter_test.

---

### Task 1: Backend metadata schema tests first

**Files:**
- Test: `backend/tests/unit/v1/schedule_items/test_schemas.py`
- Modify: `backend/src/v1/schedule_items/schemas.py`

**Step 1: Write failing tests**
- Add tests for `reminder_minutes` accepted values (`None`, `0`, `15`, `10080`)
- Add tests for invalid values (`-1`, `10081`)

**Step 2: Run tests to verify RED**
Run: `uv run pytest backend/tests/unit/v1/schedule_items/test_schemas.py -q`
Expected: FAIL for missing/invalid field support.

**Step 3: Minimal implementation**
- Add `reminder_minutes: int | None = Field(default=None, ge=0, le=10080)` to `ScheduleItemMetadata`

**Step 4: Verify GREEN**
Run: `uv run pytest backend/tests/unit/v1/schedule_items/test_schemas.py -q`
Expected: PASS.

### Task 2: Backend service mapping tests first

**Files:**
- Test: `backend/tests/unit/v1/schedule_items/test_service.py`
- Modify: `backend/src/v1/schedule_items/service.py`

**Step 1: Write failing tests**
- Assert create/update `extra_metadata` includes `reminder_minutes`

**Step 2: Run RED**
Run: `uv run pytest backend/tests/unit/v1/schedule_items/test_service.py -q`

**Step 3: Minimal implementation**
- Ensure model_dump path includes new field naturally, no special-case stripping

**Step 4: Verify GREEN**
Run: `uv run pytest backend/tests/unit/v1/schedule_items/test_service.py -q`

### Task 3: AgentScope custom tool tests first

**Files:**
- Test: `backend/tests/unit/core/agentscope/test_calendar_tools.py`
- Modify: `backend/src/core/agentscope/tools/custom/calendar.py`

**Step 1: Write failing tests**
- `calendar_write` maps `reminder_minutes` to tool args `reminderMinutes`
- rejects out-of-range reminder values

**Step 2: Run RED**
Run: `uv run pytest backend/tests/unit/core/agentscope/test_calendar_tools.py -q`

**Step 3: Minimal implementation**
- Add `reminder_minutes` parameter and validation in `calendar_write`
- Add mapping into `tool_args`

**Step 4: Verify GREEN**
Run: `uv run pytest backend/tests/unit/core/agentscope/test_calendar_tools.py -q`

### Task 4: CrewAI calendar bridge tests first

**Files:**
- Test: `backend/tests/unit/core/agent/test_mutate_calendar_event_tool.py`
- Modify: `backend/src/core/agent/infrastructure/crewai/tools/create_calendar_event_tool.py`

**Step 1: Write failing tests**
- create path maps `reminderMinutes -> metadata.reminder_minutes`
- update path can patch `reminder_minutes`

**Step 2: Run RED**
Run: `uv run pytest backend/tests/unit/core/agent/test_mutate_calendar_event_tool.py -q`

**Step 3: Minimal implementation**
- Extend `_resolve_metadata`, `_execute_update`, and `_event_payload`

**Step 4: Verify GREEN**
Run: `uv run pytest backend/tests/unit/core/agent/test_mutate_calendar_event_tool.py -q`

### Task 5: Frontend model/API tests first

**Files:**
- Test: `apps/test/features/calendar/data/calendar_api_test.dart`
- Modify: `apps/lib/features/calendar/data/models/schedule_item_model.dart`

**Step 1: Write failing tests**
- parse `metadata.reminder_minutes`
- serialize `metadata.reminder_minutes` in create/update payload

**Step 2: Run RED**
Run: `cd apps && flutter test test/features/calendar/data/calendar_api_test.dart`

**Step 3: Minimal implementation**
- add `reminderMinutes` in model + json mapping

**Step 4: Verify GREEN**
Run: `cd apps && flutter test test/features/calendar/data/calendar_api_test.dart`

### Task 6: Detail UI rendering fix tests first

**Files:**
- Create/Test: `apps/test/features/calendar/ui/screens/calendar_event_detail_screen_test.dart`
- Modify: `apps/lib/features/calendar/ui/screens/calendar_event_detail_screen.dart`

**Step 1: Write failing widget tests**
- reminder text for null/0/15
- metadata raw block no longer visible

**Step 2: Run RED**
Run: `cd apps && flutter test test/features/calendar/ui/screens/calendar_event_detail_screen_test.dart`

**Step 3: Minimal implementation**
- remove raw metadata section
- render structured reminder text

**Step 4: Verify GREEN**
Run: `cd apps && flutter test test/features/calendar/ui/screens/calendar_event_detail_screen_test.dart`

### Task 7: Local notification service integration

**Files:**
- Create: `apps/lib/core/notifications/local_notification_service.dart`
- Modify: `apps/lib/core/di/injection.dart`
- Modify: `apps/lib/main.dart`
- Modify: `apps/lib/features/calendar/data/services/mock_calendar_service.dart`
- Modify: `apps/lib/features/calendar/ui/widgets/create_event_sheet.dart`

**Step 1: Add local notification dependencies**
- Update `apps/pubspec.yaml` with `flutter_local_notifications`

**Step 2: Implement scheduling API**
- init permissions
- schedule/update/cancel by event id
- vibration enabled for Android notification details

**Step 3: Integrate into calendar flow**
- create/update/delete hooks call notification service
- startup rebuild for future events

**Step 4: Verify manually**
- create reminder 1-2 min event and verify system notification + vibration

### Task 8: Full verification

**Step 1: Backend checks**
Run:
- `uv run pytest backend/tests/unit/v1/schedule_items/test_schemas.py -q`
- `uv run pytest backend/tests/unit/v1/schedule_items/test_service.py -q`
- `uv run pytest backend/tests/unit/core/agentscope/test_calendar_tools.py -q`
- `uv run pytest backend/tests/unit/core/agent/test_mutate_calendar_event_tool.py -q`

**Step 2: Frontend checks**
Run:
- `cd apps && flutter test test/features/calendar/data/calendar_api_test.dart`
- `cd apps && flutter test test/features/calendar/ui/screens/calendar_event_detail_screen_test.dart`
- `cd apps && flutter analyze lib/features/calendar lib/core/notifications`

**Step 3: Manual verification evidence**
- create/update/delete reminder event and capture observed notification behavior.