feat(dev): update roadmap

1 files changed, 405 insertions, 0 deletions

diff --git a/docs/dev/roadmap.md b/docs/dev/roadmap.md
new file mode 100644
index 0000000..e868ab7
--- /dev/null
+++ b/docs/dev/roadmap.md
@@ -0,0 +1,405 @@
+# Note Feature Implementation Roadmap
+
+This document outlines the implementation plan for adding Anki-compatible "Note" concept to Kioku.
+
+## Overview
+
+Currently, Kioku uses a simple Card model with `front` and `back` text fields. To improve Anki interoperability, we will introduce:
+
+1. **Note** - A container for field values (similar to Anki's Note)
+2. **NoteType** - Defines the structure of notes (fields and card templates)
+3. **Card** - Generated from Notes, holds FSRS scheduling state
+
+### Key Concepts
+
+- **One Note → Multiple Cards**: A "Basic (and reversed)" note type creates 2 cards (front→back, back→front)
+- **One Note → One Card**: A "Basic" note type creates 1 card
+- **Shared Content**: When note content is edited, all generated cards reflect the change
+- **Independent Scheduling**: Each card has its own FSRS state (due date, stability, etc.)
+
+## Data Model Design
+
+### New Entities
+
+```
+NoteType
+├── id: UUID
+├── user_id: UUID (FK → users)
+├── name: string
+├── front_template: string (mustache template, e.g., "{{Front}}")
+├── back_template: string (mustache template, e.g., "{{Back}}")
+├── is_reversible: boolean (if true, creates reversed card too)
+├── created_at: timestamp
+├── updated_at: timestamp
+├── deleted_at: timestamp (soft delete)
+└── sync_version: number
+
+NoteFieldType
+├── id: UUID
+├── note_type_id: UUID (FK → note_types)
+├── name: string (e.g., "Front", "Back")
+├── order: number (display order)
+├── field_type: enum ("text") // Fixed to "text" for now
+├── created_at: timestamp
+├── updated_at: timestamp
+├── deleted_at: timestamp
+└── sync_version: number
+
+Note
+├── id: UUID
+├── deck_id: UUID (FK → decks)
+├── note_type_id: UUID (FK → note_types)
+├── created_at: timestamp
+├── updated_at: timestamp
+├── deleted_at: timestamp
+└── sync_version: number
+
+NoteFieldValue
+├── id: UUID
+├── note_id: UUID (FK → notes)
+├── note_field_type_id: UUID (FK → note_field_types)
+├── value: text
+├── created_at: timestamp
+├── updated_at: timestamp
+└── sync_version: number
+
+Card (modified)
+├── id: UUID
+├── deck_id: UUID (FK → decks)
+├── note_id: UUID (FK → notes) [NEW]
+├── is_reversed: boolean [NEW] (false=normal, true=reversed)
+├── front: text [DEPRECATED - kept for backward compat during migration]
+├── back: text [DEPRECATED - kept for backward compat during migration]
+├── (FSRS fields unchanged)
+├── created_at: timestamp
+├── updated_at: timestamp
+├── deleted_at: timestamp
+└── sync_version: number
+```
+
+### Card Display Logic
+
+Template rendering uses a custom mustache-like renderer (no external dependencies).
+
+Syntax: `{{FieldName}}` is replaced with the field value.
+
+When displaying a card:
+- **Normal card** (`is_reversed = false`): Render `front_template` on front, `back_template` on back
+- **Reversed card** (`is_reversed = true`): Render `back_template` on front, `front_template` on back
+
+Example templates:
+- Simple: `{{Front}}`
+- With text: `Q: {{Front}}`
+- Multiple fields: `{{Word}} - {{Reading}}`
+
+### Built-in Note Types
+
+Create these as default note types for each user:
+
+1. **Basic**
+   - Fields: Front, Back
+   - front_template: `{{Front}}`, back_template: `{{Back}}`
+   - is_reversible: false
+
+2. **Basic (and reversed card)**
+   - Fields: Front, Back
+   - front_template: `{{Front}}`, back_template: `{{Back}}`
+   - is_reversible: true
+
+### Behavior Rules
+
+**Updating `is_reversible`:**
+- Changing `is_reversible` does NOT affect existing cards
+- Only affects new note creation (whether to create 1 or 2 cards)
+- Existing reversed cards remain even if `is_reversible` is set to `false`
+
+**Deletion Constraints (enforced by FK constraints + application logic):**
+- **NoteType**: Cannot delete if any Notes reference it
+- **NoteFieldType**: Cannot delete if any NoteFieldValues reference it
+- **Note**: Deleting a Note cascades soft-delete to all its Cards
+- **Card**: Deleting a Card also deletes its Note (and all sibling Cards via cascade)
+
+**Required Tests for Deletion:**
+- [ ] Attempt to delete NoteType with existing Notes → should fail
+- [ ] Attempt to delete NoteFieldType with existing NoteFieldValues → should fail
+- [ ] Delete Note → verify all related Cards are soft-deleted
+- [ ] Delete Card → verify Note and all sibling Cards are soft-deleted
+
+## Implementation Phases
+
+### Phase 1: Database Schema
+
+**Tasks:**
+- [ ] Add `note_types` table schema (Drizzle)
+- [ ] Add `note_field_types` table schema
+- [ ] Add `notes` table schema
+- [ ] Add `note_field_values` table schema
+- [ ] Modify `cards` table: add `note_id`, `is_reversed` columns (nullable initially)
+- [ ] Create migration file
+- [ ] Add Zod validation schemas
+
+**Files to modify:**
+- `src/server/db/schema.ts`
+- `src/server/schemas/index.ts`
+- `drizzle/` (new migration)
+
+### Phase 2: Server Repositories
+
+**Tasks:**
+- [ ] Create `NoteTypeRepository`
+  - CRUD operations
+  - Include fields when fetching
+- [ ] Create `NoteTypeFieldRepository`
+  - CRUD operations
+  - Reorder fields
+- [ ] Create `NoteRepository`
+  - Create note with field values (auto-generate cards based on `is_reversible`)
+  - Update note (updates field values)
+  - Delete note (cascade soft-delete to cards)
+- [ ] Modify `CardRepository`
+  - Fetch card with note data for display
+  - Support note-based card creation
+
+**Files to create/modify:**
+- `src/server/repositories/noteType.ts` (new)
+- `src/server/repositories/note.ts` (new)
+- `src/server/repositories/card.ts` (modify)
+- `src/server/repositories/types.ts` (modify)
+
+### Phase 3: Server API Routes
+
+**Tasks:**
+- [ ] Add NoteType routes
+  - `GET /api/note-types` - List user's note types
+  - `POST /api/note-types` - Create note type
+  - `GET /api/note-types/:id` - Get note type with fields
+  - `PUT /api/note-types/:id` - Update note type (name, front_template, back_template, is_reversible)
+  - `DELETE /api/note-types/:id` - Soft delete
+- [ ] Add NoteFieldType routes (nested under note-types)
+  - `POST /api/note-types/:id/fields` - Add field
+  - `PUT /api/note-types/:id/fields/:fieldId` - Update field
+  - `DELETE /api/note-types/:id/fields/:fieldId` - Remove field
+  - `PUT /api/note-types/:id/fields/reorder` - Reorder fields
+- [ ] Add Note routes
+  - `GET /api/decks/:deckId/notes` - List notes in deck
+  - `POST /api/decks/:deckId/notes` - Create note (auto-generates cards)
+  - `GET /api/decks/:deckId/notes/:noteId` - Get note with field values
+  - `PUT /api/decks/:deckId/notes/:noteId` - Update note field values
+  - `DELETE /api/decks/:deckId/notes/:noteId` - Delete note and its cards
+- [ ] Modify Card routes
+  - Update GET to include note data when available
+- [ ] Modify Study routes
+  - Fetch note/field data for card display
+
+**Files to create/modify:**
+- `src/server/routes/noteTypes.ts` (new)
+- `src/server/routes/notes.ts` (new)
+- `src/server/routes/cards.ts` (modify)
+- `src/server/routes/study.ts` (modify)
+- `src/server/index.ts` (register new routes)
+
+### Phase 4: Client Database (Dexie)
+
+**Tasks:**
+- [ ] Add `LocalNoteType` interface and table
+- [ ] Add `LocalNoteTypeField` interface and table
+- [ ] Add `LocalNote` interface and table
+- [ ] Add `LocalNoteFieldValue` interface and table
+- [ ] Modify `LocalCard` interface: add `noteId`, `isReversed`
+- [ ] Update Dexie schema version and upgrade handler
+- [ ] Create client repositories for new entities
+
+**Files to modify:**
+- `src/client/db/index.ts`
+- `src/client/db/repositories.ts`
+
+### Phase 5: Sync Logic
+
+**Tasks:**
+- [ ] Add sync for NoteType, NoteFieldType
+- [ ] Add sync for Note, NoteFieldValue
+- [ ] Update Card sync to include `noteId`, `isReversed`
+- [ ] Define sync order (NoteTypes → Notes → Cards)
+- [ ] Update pull/push sync handlers
+
+**Files to modify:**
+- `src/server/routes/sync.ts`
+- `src/server/repositories/sync.ts`
+- `src/client/sync/push.ts`
+- `src/client/sync/pull.ts`
+
+### Phase 6: Frontend - Note Type Management
+
+**Tasks:**
+- [ ] Create NoteType list page (`/note-types`)
+- [ ] Create NoteType editor component
+  - Edit name
+  - Manage fields (add/remove/reorder)
+  - Edit front/back templates (mustache syntax)
+  - Toggle `is_reversible` option
+- [ ] Add navigation to note type management
+
+**Files to create:**
+- `src/client/pages/NoteTypesPage.tsx`
+- `src/client/components/NoteTypeEditor.tsx`
+- `src/client/components/FieldEditor.tsx`
+
+### Phase 7: Frontend - Note CRUD
+
+**Tasks:**
+- [ ] Update CreateCardModal → CreateNoteModal
+  - Select note type
+  - Dynamic field inputs based on note type
+  - Preview generated cards
+- [ ] Update EditCardModal → EditNoteModal
+  - Load note and field values
+  - Update all generated cards on save
+- [ ] Update DeckDetailPage
+  - Group cards by note
+  - Show note-level actions (edit note, delete note)
+  - Display whether card is normal or reversed
+
+**Files to modify:**
+- `src/client/components/CreateCardModal.tsx` → `CreateNoteModal.tsx`
+- `src/client/components/EditCardModal.tsx` → `EditNoteModal.tsx`
+- `src/client/pages/DeckDetailPage.tsx`
+
+### Phase 8: Frontend - Study Page
+
+**Tasks:**
+- [ ] Create custom template renderer utility
+- [ ] Update StudyPage to render cards based on note data
+  - Fetch note field values
+  - Use `isReversed` to determine which template to use for front/back
+  - Render templates with custom renderer
+  - Maintain front/back flip behavior
+- [ ] Handle both legacy cards (direct front/back) and new note-based cards
+
+**Files to modify/create:**
+- `src/client/utils/templateRenderer.ts` (new)
+- `src/client/pages/StudyPage.tsx`
+
+### Phase 9: Data Migration
+
+**Tasks:**
+- [ ] Create migration script for existing data
+  - Create "Basic" note type for each user
+  - For each existing card:
+    - Create a Note with Front/Back field values
+    - Update Card to reference the Note
+- [ ] Test migration with backup/restore capability
+- [ ] Add migration endpoint or CLI command
+
+**Files to create:**
+- `src/server/scripts/migrate-to-notes.ts`
+
+### Phase 10: Cleanup
+
+**Tasks:**
+- [ ] Remove deprecated `front`/`back` columns from Card (after migration)
+- [ ] Update all tests
+- [ ] Update API documentation
+- [ ] Performance testing with multiple cards per note
+
+## Migration Strategy
+
+### Backward Compatibility
+
+During migration period:
+1. Card retains `front`/`back` fields (nullable)
+2. Card gains `noteId`/`isReversed` fields (nullable)
+3. Display logic checks: if `noteId` exists, use note data; else use legacy `front`/`back`
+4. New cards always created via Note
+5. After full migration, remove legacy fields
+
+### Data Migration Steps
+
+1. **Preparation**
+   - Backup database
+   - Create default note types for all users
+
+2. **Card Migration**
+   - For each user's cards:
+     - Group by deck
+     - Create Note with "Basic" type
+     - Set Front/Back field values from card
+     - Link card to note
+
+3. **Verification**
+   - Compare card counts
+   - Verify field values match
+   - Test study flow
+
+4. **Cleanup**
+   - Remove legacy columns
+   - Update indexes
+
+## API Examples
+
+### Create Note
+
+```http
+POST /api/decks/:deckId/notes
+Content-Type: application/json
+
+{
+  "noteTypeId": "uuid-of-basic-reversed",
+  "fields": {
+    "field-uuid-front": "What is the capital of Japan?",
+    "field-uuid-back": "Tokyo"
+  }
+}
+```
+
+Response:
+```json
+{
+  "note": {
+    "id": "note-uuid",
+    "noteTypeId": "...",
+    "deckId": "...",
+    "fieldValues": [...]
+  },
+  "cards": [
+    { "id": "card-1-uuid", "isReversed": false },
+    { "id": "card-2-uuid", "isReversed": true }
+  ]
+}
+```
+
+### Get Cards for Study
+
+```http
+GET /api/decks/:deckId/study
+```
+
+Response:
+```json
+{
+  "cards": [
+    {
+      "id": "card-uuid",
+      "noteId": "note-uuid",
+      "isReversed": false,
+      "fieldValues": {
+        "Front": "What is the capital of Japan?",
+        "Back": "Tokyo"
+      },
+      "state": 0,
+      "due": "2024-01-15T00:00:00Z",
+      ...
+    }
+  ]
+}
+```
+
+Note: Templates (`front_template`, `back_template`) are fetched separately via NoteType API and cached on the client. The client renders the card display using the template and field values.
+
+## Testing Checklist
+
+- [ ] Unit tests for all new repositories
+- [ ] Integration tests for note CRUD
+- [ ] Test card generation from different note types
+- [ ] Test sync with note data
+- [ ] Test migration script
+- [ ] E2E tests for study flow with note-based cards