勉強ごほうびアプリ

勉強時間や成果をポイント（1pt＝1円）に換算し、本人と親が成長を見える化する Web アプリです。 ポイントは本人がいつでも交換を請求でき、親が「渡した✅」を付けた時点で交換完了になり、ポイントが消費されます。 Z会の教材ごとのチェックリスト（学年×教科×月）もあり、チェックするとポイントがもらえます。

仕様書: https://claude.ai/artifact/6gpy8NfGy9TgzVhytTUrqn （v0.1）

技術構成

• Next.js 16（App Router / Server Actions、スマホ優先のレスポンシブ）
• Supabase（Auth / Postgres）。家族ごとのデータ分離は Row Level Security
• Tailwind CSS 4
• ホスティング: Vercel

セットアップ

1. Supabase でプロジェクトを作成する
2. supabase/migrations/ の SQL を番号順に実行する（手順は下の「データベースの更新手順」）
   • 0001_init.sql：初期スキーマ
   • 0002_v1_1_changes.sql：v1.1 の変更（既存データも引き継ぐ）
   • 0003_zkai_and_exchange.sql：Z会チェックリストと、交換の「渡した」で完了する変更
   • 0004_zkai_items.sql：親が Z会の教材（6教科以外の行）を追加できるようにする変更
   • 0005_performance.sql：表示の高速化（残高の集計ビュー、インデックス、権限チェックの軽量化）
3. .env.example を .env.local にコピーして値を入れる
   • NEXT_PUBLIC_SUPABASE_URL / NEXT_PUBLIC_SUPABASE_ANON_KEY
   • SUPABASE_SERVICE_ROLE_KEY（サーバー側のみで使用）
4. 起動

npm install
npm run dev     # http://localhost:3000
npm test        # ポイント計算ルールのテスト
npm run lint    # 型チェック

Vercel では同じ環境変数を Project Settings > Environment Variables に設定します。

速さについて

• Supabase のリージョン（Project Settings > General）と、Vercel の関数のリージョン（Project Settings > Functions > Function Region）を 同じ地域にする。Supabase が東京（ap-northeast-1）なら Vercel は Tokyo（hnd1）。離れていると、DB への通信1回ごとに往復の時間がかかる
• Supabase の JWT 署名鍵を非対称鍵（Authentication > JWT Keys / Signing Keys で ECC など）にすると、 画面ごとのログイン確認がサーバー内で済み、Supabase Auth への通信がなくなる（旧来の共有鍵のままでも動く）
• 環境変数 SUPABASE_TIMING=1 を付けると、Supabase への通信ごとの時間がサーバーのログ（Vercel の Logs）に出る （例：[supabase] 132ms GET /rest/v1/users）。確認が終わったら外す

データベースの更新手順（Supabase の画面で行う）

SQL ファイルは「どこかに置く」ものではなく、中身をコピーして Supabase の SQL Editor に貼り付けて実行します。

1. いまの状態を確認する
   1. Supabase でプロジェクトを開き、左のメニューから SQL Editor を開く
   2. 右上の ＋（New query） で新しいクエリを作る
   3. supabase/check_schema.sql の中身を全部コピーして貼り付け、Run を押す
   4. 結果の表で、0001〜0005 のファイルがそれぞれ「実行済み」か「未実行」かを見る
2. 「未実行」のファイルを番号の小さい順に実行する
   1. GitHub でファイルを開き、右上のコピーボタン（Copy raw file）で中身を全部コピーする
   2. SQL Editor で新しいクエリを作って貼り付け（前の内容は消しておく）、Run を押す
   3. 「destructive operation（元に戻せない操作）」の確認が出たら、そのまま実行してよい（制約を作り直しているため）
   4. 「Success. No rows returned」と出れば完了
3. もう一度 check_schema.sql を実行し、すべて「実行済み」になっていることを確かめる

注意

• 0001_init.sql は最初の1回だけ実行する。もう一度実行すると「already exists」のエラーになる（データは壊れない）
• 0002 以降は何度実行しても大丈夫。途中で失敗しても何も変更されないので、エラーを直してからもう一度実行すればよい
• 「relation "families" already exists」と出たら、0001_init.sql はもう実行済み。次の番号のファイルに進む
• 「relation "tasks" does not exist」と出たら、先に 0001_init.sql を実行する

使い方

1. 親が /signup で家族を登録する（初期科目：国語・数学・英語・理科・社会）
2. 「家族・アカウント」で子どもを追加する。子どもは発行したログインIDとパスワードでログインする。 同じ画面で学年（Z会の表で使う）を設定する
3. 「ルール設定」でレート・ボーナスと、Z会の教科ごとのポイントを決める。テスト目標とそのポイントは子どもが作る

設計メモ

• 書き込みはすべてサーバー経由: 読み取りは RLS（can_view_child など）で家族ごとに分離し、 書き込みは Server Action で権限を確認してから service role で行う。 authenticated ロールには書き込みポリシーがないため、子どもが自分でポイントを付与することはできない。
• 残高は point_ledger の合計で求め、直接書き換えない。合計は集計ビュー point_balances で DB 側で計算する。(child_id, kind, ref_id) の一意制約で 同じボーナスの二重付与を防ぐ。
• 日付は日本時間。タイマー記録は開始時刻の日付で、平日／休日（土日・祝日）レートと 1日23時間の上限を判定する。 祝日判定は @holiday-jp/holiday_jp。
• ポイント計算は src/lib/points.ts の純粋関数にまとめ、src/lib/points.test.ts でテストしている。
• ログイン確認: proxy.ts はセッションの有無の確認と期限切れのリフレッシュだけを行う（通常は通信しない）。 ユーザーの確認（JWT の検証）と役割の取得は lib/auth.ts で、React の cache() により1回のリクエストで1回だけ行う。
• 画面の読み取り: 家族の範囲のデータ（ルール・科目・家族のメンバーなど）は RLS で絞り、ログイン確認と同時に取得する。 これらの関数はログイン中ユーザー用のクライアント（UserClient 型）しか受け取らず、RLS を通らない管理用クライアントは渡せない。

仕様書で決まっていなかった点の扱い

項目	この実装での扱い
連続記録ボーナス	連続日数が設定日数の倍数（7日、14日…）に達するたびに付与
記録の削除・却下	親は手入力の記録を「却下」、タイマーの記録を「削除」できる（どちらも理由必須・本人に通知）。取り消すのはその記録のポイントのみで、付与済みの連続・週ボーナスは残す
記録の編集	本人が時間・教材・科目・ページ・メモを編集できる（日付は不可）。時間を変えたら保存時のレートで再計算し、差分を「記録の修正」として台帳に残す。タイマー記録の時間を変えると手入力扱いになり、親が却下できる。教材の進捗は戻さない
ポイント交換	親の承認はなし。請求で親に通知。親が「渡した」を付けた時点で完了・消費し、本人に通知。「渡した」前なら本人が請求を取り消せる。以前「渡した」だけ付いていた交換は 0003 の実行時に完了にする
タスクの名前	任意。空なら「教材名 p.○-○」→ 教材名 → 科目名の順で表示。名前・教材・科目のどれか1つは必要
テスト目標	目標と達成ポイントを子どもが目標ごとに決める（0〜1,000,000pt）。1つの目標につき達成は1回。点数目標は「○点以上」、英検などは合格／不合格で判定。未達成の目標は本人・親が取り下げ可
Z会の学年	親が子どもごとに中学1〜3年を設定し、毎年3月（Z会の新年度）に自動で1つ上がる。表は学年に関係なく1〜3年のどれでも見られ、どのマスもいつでもチェックできる。学年が未設定のときは、選んだ学年を今年度の学年として記録する
Z会のチェック	子どもが付け外しする。どの学年・どの月のマスもいつでもチェックできる（先の月も可）。付けたときのポイントを記録し、外したとき・親が取り消したときはその額を戻す（kind='zkai'）。親が取り消したマスにはそのことを表示するが、子どもはもう一度チェックできる（記録の却下と同じく、新しい行になる）
Z会の教材の追加	親が子どもごとに、6教科以外の行（例：プラス 数学）を名前と1回分のポイント（50pt単位）で追加できる。表では6教科のあとに並び、チェック・ポイント・取り消しは教科と同じ。表から外しても、付け済みのチェックとポイントは残る。今月の進み具合とホームの「あと○教科」にも含める
Z会のポイント設定	教科ごとに親が50pt単位で設定（初期値 300pt、作文 500pt）。変更はこれから付けるチェックから反映
ワーク1周	最終ページ到達で1周ボーナスを付与。2周目は本人が「○周目を始める」で開始
1周ボーナスの額	教材ごとに親が子どもの詳細画面で設定（初期値 2,000pt）
今日のタスク	完了の取り消しはなし。前日以前の未完了タスクはホームで「持ち越す／やめる」を選ぶ
子どものログイン	親が発行するログインID＋パスワード（内部的には CHILD_EMAIL_DOMAIN のメールアドレスに変換）
「今月のポイント」	今月増えたポイント（取り消しを含み、交換での消費は含めない）

v1 の既知の制約

• 記録の保存・編集や交換の完了は複数のクエリで行っており、DB トランザクションではない。 二重処理は条件付き更新と一意制約で防いでいる。請求額は請求時に残高から確保するが、 その後に親が記録を取り消すと、交換完了時に残高がマイナスになることがある。
• テスト結果は本人の自己申告で、目標とポイントも本人が作る。不自然な目標は親が子どもの詳細画面で取り下げる。
• 写真添付・外部決済・プッシュ通知・ネイティブアプリは v1 の対象外（仕様書 7章）。