{"id":47935571,"url":"https://github.com/ddthien-coder/hskdolien","last_synced_at":"2026-04-04T07:42:06.182Z","repository":{"id":321703528,"uuid":"1086849456","full_name":"ddthien-coder/hskdolien","owner":"ddthien-coder","description":null,"archived":false,"fork":false,"pushed_at":"2025-10-31T03:50:58.000Z","size":204,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"Deploy","last_synced_at":"2025-10-31T04:23:14.010Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ddthien-coder.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-31T02:04:07.000Z","updated_at":"2025-10-31T03:32:42.000Z","dependencies_parsed_at":"2025-10-31T04:23:16.366Z","dependency_job_id":"165dd64c-7cf0-4229-a955-bfa16fad1c45","html_url":"https://github.com/ddthien-coder/hskdolien","commit_stats":null,"previous_names":["ddthien-coder/hskdolien"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ddthien-coder/hskdolien","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddthien-coder%2Fhskdolien","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddthien-coder%2Fhskdolien/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddthien-coder%2Fhskdolien/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddthien-coder%2Fhskdolien/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ddthien-coder","download_url":"https://codeload.github.com/ddthien-coder/hskdolien/tar.gz/refs/heads/Deploy","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddthien-coder%2Fhskdolien/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31392186,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T04:26:24.776Z","status":"ssl_error","status_checked_at":"2026-04-04T04:23:34.147Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-04T07:42:05.796Z","updated_at":"2026-04-04T07:42:06.166Z","avatar_url":"https://github.com/ddthien-coder.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HSK Dolien - Chinese Proficiency Exam System\n\nA comprehensive HSK (Hanyu Shuiping Kaoshi) examination platform built with Next.js 15, TypeScript, PostgreSQL, and Redis.\n\n## Features\n\n- 🔐 **Authentication \u0026 Security**: JWT + Refresh tokens, RBAC (5 roles), rate limiting\n- 📚 **Question Bank**: Multi-language support (zh-CN, zh-TW, pinyin, Vietnamese), 7 question types\n- 🎯 **Exam Generation**: Manual creation + intelligent auto-generation with balancing algorithm\n- ✍️ **Exam Taking**: Real-time autosave, progress tracking, resume capability\n- 🤖 **Auto-Grading**: Fuzzy matching for fill-in-blank, exact match for MCQ, partial credit system\n- 👨‍🏫 **Manual Grading**: Queue management for essays, rubric-based scoring\n- 🛡️ **Anti-Cheating**: Proctor sessions, violation tracking, suspicious activity detection\n- 📈 **Analytics**: Performance tracking, skill breakdown, system-wide reporting with Recharts\n- 🎓 **Certificates**: Auto-generated HTML certificates for passed exams\n- 📋 **Exam Templates**: Reusable exam configurations for quick exam creation\n- 💾 **Media Library \u0026 Document Storage**: Centralized file management with upload, download, and organization for images, audio, and documents (PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT, CSV)\n- ⚡ **Job Queue**: Background processing for grading, certificates, and cleanup tasks\n- 👤 **Admin Panel**: Complete management UI for users, exams, question banks, and system monitoring\n\n## Tech Stack\n\n- **Framework**: Next.js 16.0.1 (App Router)\n- **Language**: TypeScript 5 (strict mode, zero `any` types)\n- **Database**: PostgreSQL 17 with Prisma ORM\n- **Cache**: Redis 7\n- **Authentication**: JWT with httpOnly cookies\n- **Validation**: Zod v4\n- **Charts**: Recharts 3\n- **Styling**: Tailwind CSS 4\n- **Deployment**: Docker + PM2 cluster mode\n\n## Getting Started\n\n### Prerequisites\n\n- Node.js 20+\n- PostgreSQL 17\n- Redis 7\n\n### Installation\n\n```bash\n# Install dependencies\nnpm install\n\n# Set up environment variables\ncp .env.example .env\n# Edit .env with your database and Redis credentials\n\n# Generate Prisma client\nnpm run db:generate\n\n# Push schema to database\nnpm run db:push\n\n# Seed demo data\nnpm run db:seed\n```\n\n### Development\n\n```bash\nnpm run dev\n```\n\nOpen [http://localhost:3000](http://localhost:3000)\n\n### Demo Accounts\n\n- **Admin**: admin@hsk.com / Admin123!\n- **Teacher**: teacher@hsk.com / Teacher123!\n- **Candidate**: candidate@hsk.com / Candidate123!\n\n## Docker Deployment\n\n```bash\n# Build and run with Docker Compose\ndocker-compose up -d\n\n# View logs\ndocker-compose logs -f app\n\n# Stop services\ndocker-compose down\n```\n\n## PM2 Deployment\n\n```bash\n# Build for production\nnpm run build\n\n# Start with PM2\npm2 start ecosystem.config.js\n\n# Monitor\npm2 monit\n```\n\n## API Endpoints\n\n### Authentication\n- `POST /api/auth/register` - Register new user\n- `POST /api/auth/login` - Login\n- `POST /api/auth/logout` - Logout\n- `POST /api/auth/refresh` - Refresh access token\n- `GET /api/auth/me` - Get current user\n\n### Question Banks\n- `GET /api/banks` - List banks\n- `POST /api/banks` - Create bank\n- `GET /api/banks/[id]` - Get bank details\n- `PATCH /api/banks/[id]` - Update bank\n- `DELETE /api/banks/[id]` - Delete bank\n\n### Questions\n- `GET /api/questions` - List questions\n- `POST /api/questions` - Create question\n- `PATCH /api/questions/[id]` - Update question\n- `DELETE /api/questions/[id]` - Delete question\n\n### Exams\n- `GET /api/exams` - List exams\n- `POST /api/exams` - Create exam\n- `POST /api/exams/generate` - Auto-generate exam\n- `GET /api/exams/[id]` - Get exam details\n- `POST /api/exams/[id]/publish` - Publish exam\n- `POST /api/exams/[id]/questions` - Add questions\n\n### Attempts\n- `GET /api/attempts` - List user attempts\n- `POST /api/attempts` - Start attempt\n- `POST /api/attempts/[id]/answer` - Save answer (autosave)\n- `POST /api/attempts/[id]/submit` - Submit attempt\n- `POST /api/attempts/[id]/grade` - Auto-grade attempt\n\n### Grading\n- `GET /api/grading/manual` - Get manual grading queue\n- `POST /api/grading/manual` - Submit manual grade\n\n### Proctor\n- `POST /api/proctor/[attemptId]` - Initialize session\n- `POST /api/proctor/[attemptId]/flag` - Record violation\n- `GET /api/proctor/[attemptId]/analysis` - Analyze suspicious activity\n\n### Analytics\n- `GET /api/analytics/user` - User performance\n- `GET /api/analytics/exam/[id]` - Exam statistics\n- `GET /api/analytics/system` - System-wide analytics\n\n### Admin\n- `GET /api/admin/dashboard` - Admin dashboard data\n- `GET /api/admin/users` - List users\n- `PATCH /api/admin/users/[id]` - Update user\n- `DELETE /api/admin/users/[id]` - Delete user\n- `GET /api/admin/exams` - List all exams\n- `PATCH /api/admin/exams/[id]` - Update exam\n- `DELETE /api/admin/exams/[id]` - Delete exam\n- `GET /api/admin/banks` - List all banks\n- `DELETE /api/admin/banks/[id]` - Delete bank\n- `POST /api/admin/banks/[id]/transfer` - Transfer ownership\n- `GET /api/admin/activity` - Activity logs\n\n### Templates\n- `GET /api/templates` - List exam templates\n- `POST /api/templates` - Create template\n- `GET /api/templates/[id]` - Get template details\n- `PATCH /api/templates/[id]` - Update template\n- `DELETE /api/templates/[id]` - Delete template\n\n### Media \u0026 Document Storage\n- `GET /api/media` - List all media files (with filtering and search)\n- `POST /api/upload` - Upload file (image, audio, document)\n- `GET /api/media/[id]` - Get media details\n- `PATCH /api/media/[id]` - Update media metadata (description, tags)\n- `DELETE /api/media/[id]` - Delete media file\n- `POST /api/media/bulk` - Bulk delete media files\n\n### Certificates\n- `GET /api/certificates/[attemptId]` - Generate certificate HTML\n\n### Job Queue\n- `GET /api/jobs` - List jobs (admin only)\n- `POST /api/jobs` - Create job\n- `GET /api/jobs/[id]` - Get job status\n\n## Database Schema\n\n14 models: User, RefreshToken, PasswordReset, Bank, Question, QuestionTranslation, ExamTemplate, Exam, ExamQuestion, Attempt, Answer, GradeRecord, ProctorSession, AuditLog, JobQueue\n\n## Scripts\n\n```bash\nnpm run dev          # Start development server\nnpm run build        # Build for production\nnpm run start        # Start production server\nnpm run lint         # Run ESLint\nnpm run db:generate  # Generate Prisma client\nnpm run db:push      # Push schema to database\nnpm run db:migrate   # Run migrations\nnpm run db:seed      # Seed demo data\nnpm run db:studio    # Open Prisma Studio\n```\n\n## Background Worker\n\nRun the background job processor for auto-grading, certificate generation, and cleanup:\n\n```bash\n# Development\nts-node scripts/worker.ts\n\n# Production (with PM2)\npm2 start scripts/worker.ts --name hsk-worker --interpreter ts-node\n```\n\n## Admin Panel\n\nAccess the admin panel at [http://localhost:3000/admin](http://localhost:3000/admin)\n\nFeatures:\n- Dashboard with real-time metrics\n- User management (roles, activation)\n- Exam management (publish/unpublish)\n- Question bank management\n- **Media library \u0026 document storage** (upload, download, organize files)\n- Activity audit logs\n- System health monitoring\n\n### Question Type Distribution System:\n    The distribution system supports all 6 HSK question types:\n    MCQ - Multiple Choice Questions\n    FILL_BLANK - Fill in the Blank\n    LISTENING - Listening Comprehension\n    WRITING - Written Essays\n    MATCHING - Match Items\n    DICTATION - Listen and Write\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fddthien-coder%2Fhskdolien","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fddthien-coder%2Fhskdolien","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fddthien-coder%2Fhskdolien/lists"}