zsb-study-tracker

## プロジェクト概要 専升本学習助手は、専升本（大学編入）受験生向けの学習チェック・管理アプリケーションであり、Web版（PWA）およびWindows/macOSデスクトップ版を提供します。Cloudflare Workers + D1データベース + R2ストレージによるクラウド上のアカウントとデータ同期機能を備え、登録・ログイン後にWebとデスクトップの間で一貫した学習記録を維持できます。 コアコンセプト：「記録 → 集中 → モチベーション → 振り返り」を繋いだ完全な学習の循環。 ### このプロジェクトを選ぶ理由 - **一気通貫の学習ループ**：毎日のチェックイン、ポモドーロ集中、問題演習と間違え問題の整理、夜のまとめと振り返りまで、受験勉強の全プロセスを1つのツールで完結させ、複数のアプリを行き来する必要がありません。 - **クラウドでのマルチデバイス同期**：アカウント登録により、データはすべてクラウド（Cloudflare D1）に同期され、Webとデスクトップでいつでも学習を続けられます。PWAによりデータがキャッシュされ、オフライン時でも直近の内容を確認できます。 - **ゲーム化による継続の促進**：ブロンズからチャレンジャー（王者）までのランク昇格、バッジウォール、ポイント履歴、連続学習日数により、退屈な長期受験勉強をゲームのステージクリアのような体験に変えます。 - **数学・英語の特化型強化**：試験範囲の章ツリー、Markdown+LaTeX数公式ノート、「墨墨背单词」アプリと連携した単語チェック、穴埋め・リーディング・リスニング・作文テンプレートの多角的記録。 - **タスク説明付きポモドーロ**：正方向タイマーとカウントダウンの2つのモード。開始前に今回の集中タスクを記入可能。「最近完了したタスク」セクションで、今日の各ポモドーロの時刻、所要時間、タスクを個別に記録します。 - **コミュニティ広場と学習仲間**：投稿によるディスカッション、サークル、プライベートメッセージ、通知機能。仲間を見つけて一緒に自習したり、チームでのチャレンジ、協力して行う学習計画や振り返りの招待など。 - **一目でわかるグラフ**：ECharts駆動による学習時間の分布、各科目の正答率の傾向、集中の分析。 - **デスクトップ版 + PWA**：Windows/macOSのネイティブクライアント、システムトレイ、ネイティブ通知、自動更新。Web版はPWAとしてインストール可能で、オフラインキャッシュにも対応。 ### 機能特性 | カテゴリ | 機能 | | :--- | :--- | | 学習記録 | 科目・章のツリーと習得度、学習時間の記録、問題演習セッション、間違えノート、模擬試験の記録、毎日のToDo | | ノートと資料 | Markdown+KaTeX公式ノート、資料庫、PDFのアップロードと分割閲覧 | | 英語特化 | 単語チェック（墨墨背单词と連携）、穴埋め、リーディング、リスニング、作文テンプレート、毎日の目標 | | ポモドーロ集中 | 正方向タイマー / カウントダウン、タスク説明、最近完了した詳細な履歴、中断理由の記録、集中用壁紙 | | 習慣と振り返り | 習慣チェックと統計、毎日のまとめ（感情 ＋ 3段階の振り返り ＋ 明日の計画）、シェアカード | | 実績とモチベーション | ポイントと履歴、6段階のランク、バッジウォール、連続学習日数 | | コミュニティ | 投稿とコメント、いいね、トピックサークル、知識点のディスカッション、プライベートメッセージ、フォロー、通知センター | | 協力 | チームでのチャレンジと進捗、学習の相棒、自習室、協力型学習計画、週間レポートのプッシュ通知 | | アカウントとセキュリティ | 登録とログイン（bcryptパスワード + JWT HttpOnly Cookie）、Cloudflare Turnstileによるボット対策、レートリミット、ローカルの機微ワード辞書 + Workers AIによる再審査 | | パーソナライズ | 試験日までのカウントダウン、テーマとダークモード、リモート通知とサイレントモード、アバターの切り抜き、ゲスト閲覧モード | ### 技術アーキテクチャ | 階層 | 技術選定 | | :--- | :--- | | フロントエンド | Vue 3（`<script setup>`）、TypeScript、Vite 5、Vue Router 4、Pinia 2、Tailwind CSS 3 | | 可視化 / リッチコンテンツ | ECharts 5、KaTeX 0.16、markdown-it、pdfjs-dist | | デスクトップ | Electron 43、electron-builder、electron-updater | | PWA | vite-plugin-pwa（インストール可能 ＋ Service Workerによるオフラインキャッシュ） | | バックエンド | Cloudflare Workers（TypeScript）、bcryptjs、joseによるJWT署名 | | データ | Cloudflare D1（50以上の業務テーブル）、R2（コミュニティ用画像ストレージ） | | エンジニアリング | ESLint、tsc --noEmit、GitHub Actionsによるデュアルパイプライン | ### クイックスタート **動作環境**：Node.js 18 以降 ```bash git clone https://github.com/Han050912/zsb-study-tracker.git cd zsb-study-tracker npm install npm run dev ``` **バックエンドWorkerの起動（ローカル開発に必須）**： ```bash cd worker npm install npm run init:local npx wrangler dev ``` **デスクトップクライアント**： ```bash npm run electron:dev ``` **ビルド・パッケージング**： ```bash npm run dist:win # Windows npm run dist:mac # Mac ``` ### デプロイ プロジェクトには2つのGitHub Actionsパイプラインがあり、masterブランチを監視し、それぞれフロントエンドをGitHub Pagesへ、バックエンドをCloudflare Workersへデプロイします。CLOUDFLARE_API_TOKEN、CLOUDFLARE_ACCOUNT_IDなどのシークレットの設定が必要です。 ### 貢献ガイドライン いかなる形式の貢献も歓迎します！フロー：Fork → 新しいブランチを作成（feat/xxx または fix/xxx） → コーディングと検証 → developmentブランチへPRを提出。TypeScript、Tailwind CSSを使用し、アイコンはSVGコンポーネント（Lucide）を使用し、Conventional Commits規約に従ってください。 ### ライセンス 当プロジェクトはMITライセンスの下でオープンソース化されています。