shardegger/memohanzi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

intialization

Browse Source
This commit is contained in:
Stefan Hardegger
2025-11-21 13:27:37 +01:00
parent 8a03edbb88
commit 33377009d0
9 changed files with 178062 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files

151
README.md
View File

@@ -112,19 +112,144 @@ Implement ALL models exactly as specified in the Prisma schema.
## 📊 Development Milestones
| Week | Milestone | Focus |
|------|-----------|-------|
| 1 | Foundation | Setup project, Docker, Prisma schema |
| 2 | Authentication | User registration, login, preferences |
| 3-4 | Data Import | Admin imports HSK data (JSON/CSV) |
| 5 | Collections | User collections + global HSK collections |
| 5 | Hanzi Search | Search interface and detail views |
| 6 | SM-2 Algorithm | Core learning algorithm + tests |
| 7-8 | Learning UI | Learning session interface |
| 9 | Dashboard | Progress tracking and visualizations |
| 10 | UI Polish | Responsive design, dark mode |
| 11 | Testing & Docs | Complete test coverage |
| 12 | Deployment | Production deployment + data import |
| Week | Milestone | Focus | Status |
|------|-----------|-------|--------|
| 1 | Foundation | Setup project, Docker, Prisma schema | ✅ Complete |
| 2 | Authentication | User registration, login, preferences | ✅ Complete |
| 3-4 | Data Import | Admin imports HSK data (JSON/CSV) | ✅ Complete |
| 5 | Collections | User collections + global HSK collections | ✅ Complete |
| 5 | Hanzi Search | Search interface and detail views | ✅ Complete |
| 6 | SM-2 Algorithm | Core learning algorithm + tests | ✅ Complete |
| 7-8 | Learning UI | Learning session interface | 🔄 Next |
| 9 | Dashboard | Progress tracking and visualizations | |
| 10 | UI Polish | Responsive design, dark mode | |
| 11 | Testing & Docs | Complete test coverage | |
| 12 | Deployment | Production deployment + data import | |
### ✅ Milestone 3 Completed Features
**Data Import System:**
- ✅ HSK JSON parser supporting complete-hsk-vocabulary format
- ✅ CSV parser with flexible column mapping
- ✅ Admin import page with file upload and paste functionality
- ✅ Update existing entries or skip duplicates option
- ✅ Detailed import results with success/failure counts and line-level errors
- ✅ Format validation and error reporting
- ✅ Support for multi-character hanzi (words like 中国)
- ✅ All transcription types (pinyin, numeric, wade-giles, zhuyin, ipa)
- ✅ 14 passing integration tests for both JSON and CSV parsers
**Database Initialization System:**
- ✅ Multi-file selection for batch initialization
- ✅ Real-time progress updates via Server-Sent Events (SSE)
- ✅ Progress bar showing current operation and percentage
- ✅ Automatic HSK level collection creation
- ✅ Auto-populate collections with hanzi based on level attribute
- ✅ Optional clean data mode (delete all existing data before import)
- ✅ Comprehensive statistics: hanzi imported, collections created, items added
- ✅ Admin initialization page at /admin/initialize
- ✅ SSE API route at /api/admin/initialize for long-running operations
**Files Created:**
- `src/lib/import/json-parser.ts` - HSK JSON format parser
- `src/lib/import/csv-parser.ts` - CSV format parser
- `src/lib/import/json-parser.test.ts` - JSON parser tests
- `src/lib/import/csv-parser.test.ts` - CSV parser tests
- `src/actions/admin.ts` - Admin-only import and initialization actions
- `src/actions/admin.integration.test.ts` - Admin action tests
- `src/app/(admin)/admin/import/page.tsx` - Import UI
- `src/app/(admin)/admin/initialize/page.tsx` - Initialization UI with SSE progress
- `src/app/api/admin/initialize/route.ts` - SSE API endpoint for real-time progress
### ✅ Milestone 4 Completed Features
**Collections Management:**
- ✅ Complete CRUD operations for collections (create, read, update, delete)
- ✅ Global HSK collections (admin-created, read-only for users)
- ✅ User personal collections (full control)
- ✅ Add hanzi to collections via:
- Search & multi-select with checkboxes
- Paste list (comma, space, or newline separated)
- Create collection with hanzi list
- ✅ Remove hanzi (individual and bulk selection)
- ✅ Collection detail view with hanzi list
- ✅ Order preservation for added hanzi
- ✅ Duplicate detection and validation
- ✅ 21 passing integration tests
**Files Created:**
- `src/actions/collections.ts` - Collection Server Actions
- `src/actions/collections.integration.test.ts` - Complete test suite
- `src/app/(app)/collections/page.tsx` - Collections list page
- `src/app/(app)/collections/[id]/page.tsx` - Collection detail page
- `src/app/(app)/collections/new/page.tsx` - Create collection page
### ✅ Milestone 5 Completed Features
**Hanzi Search & Detail Views:**
- ✅ Public hanzi search (no authentication required)
- ✅ Search by simplified, traditional, pinyin, or meaning
- ✅ HSK level filtering (12 levels: new-1 through new-6, old-1 through old-6)
- ✅ Pagination with hasMore indicator (20 results per page)
- ✅ Comprehensive detail view showing:
- All forms (simplified, traditional with isDefault indicator)
- All transcriptions (pinyin, numeric, wade-giles, etc.)
- All meanings with language codes
- HSK level badges
- Parts of speech
- Classifiers, radical, frequency
- ✅ Add to collection from detail page
- ✅ 16 passing integration tests
**Files Created:**
- `src/actions/hanzi.ts` - Public hanzi search actions
- `src/app/(app)/hanzi/page.tsx` - Search page with filters
- `src/app/(app)/hanzi/[id]/page.tsx` - Detail page with all data
- `src/actions/hanzi.integration.test.ts` - Complete test suite
**Key Features:**
- searchHanzi(): Fuzzy search across simplified, traditional, pinyin, and meanings
- HSK level filtering for targeted vocabulary
- Pagination with hasMore indicator for infinite scroll support
- Complete hanzi data display including rare transcription types
- Direct integration with collections (add from detail page)
### ✅ Milestone 6 Completed Features
**SM-2 Algorithm Implementation:**
- ✅ Core SM-2 spaced repetition algorithm following SuperMemo specification
- ✅ Exact formulas for correct and incorrect answer calculations
- ✅ Initial values: easeFactor=2.5, interval=1, consecutiveCorrect=0
- ✅ Correct answer logic:
- First correct: interval = 1 day
- Second correct: interval = 6 days
- Third+ correct: interval = Math.round(interval × easeFactor)
- Increase easeFactor by 0.1 with each correct answer
- ✅ Incorrect answer logic:
- Reset interval to 1 day
- Reset consecutiveCorrect to 0
- Decrease easeFactor by 0.2 (minimum 1.3)
- Increment incorrectCount
- ✅ Card selection algorithm:
- Filter out SUSPENDED cards
- Select due cards (nextReviewDate ≤ now)
- Priority: HARD > NORMAL > EASY
- Sort by: nextReviewDate ASC, incorrectCount DESC, consecutiveCorrect ASC
- Limit to cardsPerSession
- ✅ Wrong answer generation with Fisher-Yates shuffle
- ✅ 38 passing unit tests with 100% statement and line coverage
- ✅ 94.11% branch coverage (exceeds 90% requirement)
**Files Created:**
- `src/lib/learning/sm2.ts` - Core algorithm implementation
- `src/lib/learning/sm2.test.ts` - Comprehensive unit tests
**Functions Implemented:**
- `calculateCorrectAnswer()` - Update progress for correct answers
- `calculateIncorrectAnswer()` - Update progress for incorrect answers
- `selectCardsForSession()` - Select due cards with priority sorting
- `generateWrongAnswers()` - Generate 3 incorrect options from same HSK level
- `shuffleOptions()` - Fisher-Yates shuffle for randomizing answer positions
## 🎨 Naming Conventions