About this project

## Project Intro The Zhuanshenben Study Assistant is a preparation check-in management app for Zhuanshenben candidates, available as a Web version (PWA) and Windows/macOS desktop clients. Using Cloudflare Workers + D1 database + R2 storage for cloud accounts and data sync, it keeps your study records consistent across Web and desktop after login. Core positioning: connect 'Record → Focus → Motivate → Review' into a complete learning loop. ### Why Choose This Project - **All-in-one learning loop**: Daily check-in, Pomodoro focus, practice and mistake collection, evening review --- the whole prep process in one tool, no switching between apps. - **Cloud multi-device sync**: After registering, data is fully synced to the cloud (Cloudflare D1); Web and desktop can continue anytime; PWA caches data so you can view the latest content offline. - **Gamification keeps you going**: Rank progression from Bronze to Silver to Gold to Platinum to Diamond to King, badge wall, points ledger, and consecutive study days turn boring long-term prep into a leveling-up experience. - **Advanced Math and English focus**: Syllabus chapter tree, Markdown+LaTeX formula notes, daily word check-in with the Maimemo app, and multi-dimensional records for cloze tests, reading, listening, and writing templates. - **Pomodoro with task description**: Count-up and countdown modes; you can enter the current focus task before starting; a dedicated 'Recently Completed' section records the time, duration, and task of each Pomodoro today. - **Community plaza and study buddies**: Posts, circles, DMs, and notifications; find buddies for 'study together', team challenges, collaborative study plans, and review invitations. - **Clear charts**: ECharts-driven study duration distribution, accuracy trends by subject, and focus analytics. - **Desktop + PWA**: Native Windows/macOS clients with system tray, native notifications, and auto-updates; the Web version can be installed as a PWA with offline caching. ### Feature Overview | Category | Features | | :--- | :--- | | Study Records | Subject chapter tree and mastery, study duration records, practice sessions, mistake notebook, mock exam records, daily to-dos | | Notes & Materials | Markdown+KaTeX formula notes, material library, PDF upload and segmented reading | | English Specialized | Word check-in (via Maimemo), cloze, reading, listening, writing templates, and daily goals | | Pomodoro Focus | Count-up/countdown, task description, recent completion details, interruption reason logging, focus wallpapers | | Habits & Review | Habit check-in and statistics, daily summary (mood + three-section reflection + tomorrow's plan), share cards | | Achievement & Motivation | Points and ledger, six-rank level system, badge wall, consecutive study days | | Community | Posts and comments, likes, topic circles, knowledge discussions, DMs, following, and notification center | | Collaboration | Team challenges and progress, study buddies, co-study rooms, collaborative prep plans, weekly report push | | Account & Security | Register/login (bcrypt password + JWT HttpOnly Cookie), Cloudflare Turnstile CAPTCHA, rate limiting, local sensitive-word dictionary + Workers AI review | | Personalization | Exam countdown, themes and dark mode, reminders and do-not-disturb, avatar cropping, visitor browsing mode | ### Tech Architecture | Layer | Technology | | :--- | :--- | | Frontend | Vue 3 (script setup), TypeScript, Vite 5, Vue Router 4, Pinia 2, Tailwind CSS 3 | | Visualization / Rich Content | ECharts 5, KaTeX 0.16, markdown-it, pdfjs-dist | | Desktop | Electron 43, electron-builder, electron-updater | | PWA | vite-plugin-pwa (installable + Service Worker offline caching) | | Backend | Cloudflare Workers (TypeScript), bcryptjs, jose for JWT issuance | | Data | Cloudflare D1 (50+ business tables), R2 (community image storage) | | Engineering | ESLint, tsc --noEmit, GitHub Actions dual pipelines | ### Quick Start **Requirements**: Node.js 18 or higher ```bash git clone https://github.com/Han050912/zsb-study-tracker.git cd zsb-study-tracker npm install npm run dev ``` **Start the backend Worker (required for local development)**: ```bash cd worker npm install npm run init:local npx wrangler dev ``` **Desktop client**: ```bash npm run electron:dev ``` **Build**: ```bash npm run dist:win # Windows npm run dist:mac # Mac ``` ### Deployment The project has two GitHub Actions pipelines listening on the master branch, deploying the frontend to GitHub Pages and the backend to Cloudflare Workers. You need to configure secrets such as CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID. ### Contribution Guide Any contribution is welcome! Process: Fork → create a new branch (feat/xxx or fix/xxx) → code and verify → submit a PR to the development branch. Use TypeScript and Tailwind CSS, use SVG components for icons (Lucide), and follow the Conventional Commits spec. ### License This project is open-sourced under the MIT License.