115 lines
2.7 KiB
Markdown
115 lines
2.7 KiB
Markdown
# Calendar Specification
|
|
|
|
## Job to Be Done
|
|
|
|
When I want to plan ahead, I want to view my cycle phases on a calendar, so that I can schedule training and rest days appropriately.
|
|
|
|
## ICS Feed
|
|
|
|
### Endpoint: GET `/api/calendar/[userId]/[token].ics`
|
|
|
|
Returns ICS calendar feed for subscription in external apps.
|
|
|
|
**URL Format:**
|
|
```
|
|
https://phaseflow.app/api/calendar/user123/abc123token.ics
|
|
```
|
|
|
|
**Security:**
|
|
- `token` is a random 32-character secret per user
|
|
- Token stored in `user.calendarToken`
|
|
- No authentication required (token IS authentication)
|
|
|
|
### ICS Events
|
|
|
|
Generate events for the next 90 days:
|
|
|
|
**Phase Events (all-day):**
|
|
```ics
|
|
BEGIN:VEVENT
|
|
SUMMARY:🩸 Menstrual (Days 1-3)
|
|
DTSTART;VALUE=DATE:20240110
|
|
DTEND;VALUE=DATE:20240113
|
|
DESCRIPTION:Gentle rebounding only. Weekly limit: 30 min.
|
|
END:VEVENT
|
|
```
|
|
|
|
**Color Coding (via categories):**
|
|
- MENSTRUAL: Red
|
|
- FOLLICULAR: Green
|
|
- OVULATION: Pink
|
|
- EARLY_LUTEAL: Yellow
|
|
- LATE_LUTEAL: Orange
|
|
|
|
### Token Regeneration
|
|
|
|
POST `/api/calendar/regenerate-token`
|
|
|
|
Generates new `calendarToken`, invalidating previous subscriptions.
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"token": "newRandomToken123...",
|
|
"url": "https://phaseflow.app/api/calendar/user123/newRandomToken123.ics"
|
|
}
|
|
```
|
|
|
|
## In-App Calendar
|
|
|
|
### Month View (`/calendar`)
|
|
|
|
Full-page calendar showing current month with phase visualization.
|
|
|
|
**Components:**
|
|
- `month-view.tsx` - Main calendar grid
|
|
- `day-cell.tsx` - Individual day cell
|
|
|
|
**Day Cell Contents:**
|
|
- Date number
|
|
- Phase color background
|
|
- Period indicator (if day 1-3)
|
|
- Today highlight
|
|
- Training decision icon (for today only)
|
|
|
|
### Navigation
|
|
|
|
- Previous/Next month buttons
|
|
- "Today" button to jump to current date
|
|
- Month/Year header
|
|
|
|
### Phase Legend
|
|
|
|
Below calendar:
|
|
```
|
|
🩸 Menstrual | 🌱 Follicular | 🌸 Ovulation | 🌙 Early Luteal | 🌑 Late Luteal
|
|
```
|
|
|
|
## ICS Utilities (`src/lib/ics.ts`)
|
|
|
|
**Functions:**
|
|
- `generateCalendarFeed(user, startDate, endDate)` - Create ICS string
|
|
- `generatePhaseEvents(lastPeriodDate, cycleLength, range)` - Create phase events
|
|
|
|
**Dependencies:**
|
|
- `ics` npm package for ICS generation
|
|
|
|
## Success Criteria
|
|
|
|
1. ICS feed subscribable in Google Calendar, Apple Calendar, Outlook
|
|
2. Phase colors render correctly in calendar apps
|
|
3. In-app calendar responsive on mobile
|
|
4. Token regeneration immediately invalidates old URLs
|
|
|
|
## Acceptance Tests
|
|
|
|
- [ ] ICS endpoint returns valid ICS format
|
|
- [ ] ICS contains events for next 90 days
|
|
- [ ] Invalid token returns 401
|
|
- [ ] Regenerate token creates new unique token
|
|
- [ ] Month view renders all days in month
|
|
- [ ] Day cells show correct phase colors
|
|
- [ ] Today is visually highlighted
|
|
- [ ] Navigation between months works
|
|
- [ ] Phase legend displays correctly
|