Twitter クローン（オンボーディング課題）

Next.js App Router の教材をベースにした Twitter（X）風アプリ。要件は docs/functions.md、画面遷移は docs/front_design.md を参照。

構成

層	場所	役割
shared	shared/	UUID正規化など業務知識を含まない処理。他の層をimportしない
domain	domain/	entities/（ユーザーの型）、value_objects/（入力ルール・画像の状態）、repository_ifs/（永続化の契約）、external_service_ifs/（パスワードハッシュ・セッション終了・ストレージ・画像検査の契約）。フレームワークやDB、上位層に依存しない
application	application/	usecases/<機能>/（登録・投稿などの処理）、dtos/<機能>/（一覧型・結果型）、query_service_ifs/<機能>/（タイムライン・プロフィール・お気に入りの読み取り契約）。Next.jsや具体実装に依存しない
infra	infra/	persistence/postgres/（接続・マイグレーション・repositories/・query_services/）と external_services/（scrypt・Vercel Blob・sharp）。domain/applicationの契約を実装する
main	main/container/	具体実装の組み立て（DI）。Web用は機能別ファイルで server-only・遅延初期化、CLI用は cli/ に置き server-only を使わない
app	app/	画面、Server Action、Route Handler、Auth.js の設定。サーバー側の処理は main/container/ の取得関数だけを呼び、クライアントコンポーネントからは import しない

セットアップ（Vercel + Postgres）

DB は Vercel の Storage から作成する Postgres（Neon）を使う。

1. Vercel にプロジェクトを作成（GitHub リポジトリを Import するか、pnpm dlx vercel link）。
2. Vercel ダッシュボードの Storage → Create Database → Neon (Postgres) で DB を作成し、プロジェクトに接続する。POSTGRES_URL などの環境変数が自動で登録される。
3. Settings → Environment Variables に AUTH_SECRET（openssl rand -base64 32 の値）を追加する。AUTH_URL は Vercel 上では設定しない。
4. ローカルに接続情報を取得してマイグレーションを適用する。

pnpm install
pnpm dlx vercel env pull .env.local   # POSTGRES_URL などを .env.local に保存
pnpm db:migrate                       # POSTGRES_URL_NON_POOLING（なければ POSTGRES_URL）に適用
pnpm dev

• .env.local が .env より優先される。ローカル専用の AUTH_URL などは .env に書く（.env.example 参照）。
• vercel env pull で取得するDBは本番と同じ。開発で分けたい場合は Neon で開発用ブランチを作り、その接続URLを .env.development.local の POSTGRES_URL（プール経由）と POSTGRES_URL_NON_POOLING（プールなし）に書く。pnpm dev と pnpm db:migrate はこちらを優先する。
• Twitter 用のテーブルは PostgreSQL schema twitter に作成する。
• マイグレーションはリクエスト処理やビルドからは実行しない。スキーマを変えたらデプロイ前に pnpm db:migrate を実行する。

テスト用DB

結合テストと E2E はデータを書き込むため、本番・開発とは別の DB を TEST_POSTGRES_URL に指定する。Neon コンソールでテスト用のブランチ（または別の database）を作り、その接続URLを .env に書く。Vercel の環境変数には登録しない。

pnpm db:migrate --test で TEST_POSTGRES_URL 側にも適用できる（テストは自動で適用する）。

テスト

コマンド	内容
pnpm test:unit	domain・ユースケース・Server Action・UI の単体テスト（DB不要）
pnpm test:integration	実 PostgreSQL の Repository と実 scrypt のテスト
pnpm test:e2e	Playwright。テストDBに向けた本番ビルドを port 3100 で起動して検証
pnpm typecheck	型チェック

• 結合テストと E2E は TEST_POSTGRES_URL が必須。未設定、またはアプリ用の URL（Neon のプール経由・プールなしを含む）と同じ DB なら実行前に失敗する。
• テストは自分で作成した行だけを削除し、DB全体の drop・truncate は行わない。
• E2E 初回は pnpm exec playwright install chromium でブラウザを取得する。

アカウント作成の仕様メモ

• 登録画面ではユーザーID・名前・パスワードだけを入力する。自己紹介は空で登録し、プロフィール編集から設定できる。
• ユーザーIDは大文字小文字を区別せず一意（表示は登録時の綴りを保持）。文字数は Unicode コードポイント数で数える。
• パスワードは Node.js 標準の scrypt（N=2^17, r=8, p=1）でハッシュ化して保存する。bcrypt の72バイト制限を避けるため。
• 認証は Auth.js の Credentials + JWT セッション（7日）。セッションには内部 UUID だけを入れる。
• 登録直後の自動ログインだけが失敗した場合は、作成済みのアカウントを削除せず、ログイン画面へ案内する。

ログインの仕様メモ

• /login は登録時と同じ形式ルールでID・パスワードを検証してから認証する。形式違反はAuth.jsへの直接リクエストでも認証ユースケースで拒否する。
• 未登録IDと誤パスワードは同じメッセージ、DB障害などは別のメッセージで区別する。失敗時はIDだけを保持する。
• ログイン済みでセッションのUUIDに対応する利用者がDBに存在する場合、/login は / に移動する。Cookieの有無だけでは判断しない。

メイン画面（タイムライン）の仕様メモ

• 投稿（twitter.tweets）・フォロー（twitter.follows）・リツイート（twitter.retweets）は 002-create-timeline.sql で作成する。利用者を削除すると関連行もcascadeで削除される。
• 一覧は投稿とリツイートを1本のSQL（UNION ALL）で取得し、(出来事の日時, 種類, ID) のキーセットで20件ずつページングする。OFFSETは使わない。
• カーソルの日時はDBのマイクロ秒精度を保つ文字列のまま扱う。postgres.js は timestamptz 型のパラメータを Date（ミリ秒）に変換するため、SQLでは ::text::timestamptz で渡している。
• 投稿の作成・編集・削除（画像付き）・お気に入り・いいね・リツイート・フォローは画面から操作できる。テストのデータはSQLで直接入れる（test/support/timeline-fixtures.ts）。

プロフィール画面の仕様メモ

• /profile/{ユーザーID} は未ログインでも閲覧できる。自分かどうかはDBの対象UUIDとセッションのUUIDで判断する。
• フォロー数は follower_id = 本人、フォロワー数は follow_id = 本人 の件数。向きごとの独立したサブクエリで数える。
• 投稿・リツイート・フォロー・フォロワーの一覧は、それぞれ1回のSQLでキーセット方式（20件）で取得する。カーソルには対象者とタブを含め、他の画面・他人のページへ持ち込まれた場合は不正として扱う。
• 新しいテーブル・マイグレーションはない（002 までを使う）。

プロフィール編集の仕様メモ

• /profile/{ユーザーID}/edit は本人だけが使える。画面の表示時に加え、保存のたびにServer Actionでセッションと利用者を確認し、actorId === targetId のときだけ更新する（フォームの値や previousState は権限判断に使わない）。
• 更新は名前・ユーザーID・bioの3列だけを1つのUPDATEで行う。ID重複は一意インデックス users_display_id_ci_unique の違反だけを競合として扱い、部分的な更新は起きない。
• 保存後は revalidatePath でメイン・プロフィール・編集画面の表示を無効化し、表示用Cookie flash_profile で更新通知を出す（登録通知の flash とは別）。
• textarea の改行はブラウザがCRLFで送るため、自己紹介はサーバーでLFに揃えてから検証・保存する。
• 新しいマイグレーションはない。

アカウント削除の仕様メモ

• 削除画面への導線は、ログイン中のサイドバー（左ナビ）の一番下に置く。プロフィール画面には置かない。
• /profile/{ユーザーID}/delete は本人だけが使える。ページ表示（GET）では削除せず、Server Actionで毎回セッションのUUIDを確認し、actorId === targetId かつ現在のパスワードが一致したときだけ削除する。
• 削除は DELETE FROM twitter.users WHERE id = ... の1文だけで行い、投稿・フォロー・リツイートは既存FKのON DELETE CASCADEで消える（論理削除・復元はなし）。
• 削除後は表示を revalidatePath で無効化し、Auth.jsの signOut({ redirect: false }) で認証Cookieを無効化してから /login へ移動する。通知は表示用Cookie flash_account（deleted / signout-failed / account-missing）で出す。
• DB削除とCookieの変更は1つのトランザクションにできないため、signOutに失敗しても削除は戻さず、その旨をログイン画面に固定表示する。他のブラウザに残ったセッションは、利用者の実在確認で未ログインとして扱われる。
• 新しいマイグレーションはない。

ツイート作成ダイアログ・画像の仕様メモ

環境

• 画像は Vercel Blob の非公開ストアに保存する。開発・本番・テストで別のストアを用意し、アプリ用は BLOB_READ_WRITE_TOKEN / BLOB_STORE_ID（開発は .env.development.local）、テスト用は TEST_BLOB_READ_WRITE_TOKEN / TEST_BLOB_STORE_ID（.env）に書く。
• 結合テスト・E2Eは、実体を作る前にテスト用トークンが宣言したテスト用ストアを指し、アプリ用ストアと別であることを確認する。資格情報がなければskipせず失敗する。
• 003-create-tweet-media.sql を pnpm db:migrate（開発）・pnpm db:migrate --test（テスト）で適用する。既存データの移行は不要。
• Vercel には CRON_SECRET を登録する。vercel.json のCronが毎日 18:00 UTC（日本時間3:00）に回収を実行する（Hobbyプランの日次制約に合わせている）。

This is the beginning of the README. Read the rest at the original. Read the full README ↗