Engineer Skill Sheet Viewer
エンジニアのスキルシートを 閲覧・編集・PDF 出力 するための Web アプリケーションです。
スキルシートの正本（データの源）は Neon Postgres に保存します。1 枚のスキルシートは順序付きの「ブロック」の集まりとして持ち、表示時に Markdown へ組み立てて描画します。
主な機能
- 閲覧（Viewer）: スキルシートを Markdown として整形表示。目次（TOC）・アクティブ見出し追従つき
- 編集（Builder）: 編集者がブロック単位でスキルシートを作成・更新（Better Auth ログインが必要）
- PDF 出力（Export）: 表示中のスキルシートを PDF として書き出す
技術スタック
- 構成: リポジトリルート1本の Next.js アプリ（DB 層は
src/db）
- 言語: TypeScript
- フレームワーク: Next.js 16（App Router / React Server Components）
- UI: Tailwind CSS v4 + shadcn/ui（Radix UI）
- Markdown レンダリング: react-markdown（remark-gfm / remark-breaks → rehype-raw → rehype-sanitize → rehype-slug）
- PDF: @react-pdf/renderer（クライアント側で動的 import）
- DB / ORM: Drizzle ORM + Neon serverless Postgres（正本データ源）
- 認証: Better Auth（編集者ログイン）+ HMAC 署名の閲覧コード（
VIEWER_CODE）
- Lint / Format: Biome
- テスト: Vitest
- ランタイム / パッケージ管理: mise（Node 22.x）/ pnpm
プロジェクト構成
リポジトリルートがそのまま Next.js のプロジェクトルート（パッケージは 1 つだけ）。
.
├── app/ # ルーティング（App Router: page.tsx / layout.tsx / route.ts）
├── src/
│ ├── component/ # コンポーネント（Markdown ビューア・PDF・UI 部品）
│ ├── context/ # React Context
│ ├── db/ # Drizzle ORM + Neon（スキルシートの正本 / Better Auth テーブル）
│ ├── hook/ # カスタムフック
│ ├── lib/ # 認証クライアント・tRPC クライアント・環境変数検証など
│ ├── server/ # サーバー専用ロジック（認証ゲート・セッション・tRPC router）
│ └── util/ # ユーティリティ関数
├── drizzle/ # マイグレーション（drizzle.config.ts はルート）
├── e2e/ # Playwright の E2E
├── script/ # CLI スクリプトと CI 用チェッカー
└── public/ # 静的ファイル（フォント等）
クイックスタート
すべてのコマンドはリポジトリルートで実行します。
# 1. ランタイムの用意（mise で Node 22.x と pnpm を固定）
mise install
# 2. 依存インストール
pnpm install
# 3. DB を用意する（下の A または B。詳細は setup.md）
# 4. 開発サーバー起動（http://localhost:3000）
pnpm dev
3. DB の用意
A. ローカル PostgreSQL（外部接続不要）
手元に PostgreSQL 16+ がある環境では、ローカルスタックが DB 構築から権限付与まで全て行います。
sudo ./script/dev-local-stack.sh up
# PostgreSQL 起動 → drizzle migrations → 文書境界（skillsheet_private の関数群）の
# install → 接続 role への EXECUTE + principals 登録 → .env.local の生成まで行う。
NODE_EXTRA_CA_CERTS=$(./script/dev-local-stack.sh env | cut -d= -f2-) pnpm dev
B. 共有 DB（Neon）を使う
cp .env.example .env # DATABASE_URL などを埋める
pnpm db:migrate
スキルシートの閲覧・編集は skillsheet_private スキーマの文書境界
（SECURITY DEFINER 関数群）を経由します。境界は pnpm db:migrate の対象外で、
未 install または権限不足のままだと /view が ACCESS_DENIED / 設定不備バナーになります
（Issue #373）。共有 DB では管理者側で次を適用してもらってください。
# 境界本体（未適用の DB のみ。詳細は doc/05-toc-and-deploy.md の「適用順序」）
psql "$ADMIN_DATABASE_URL" -X -v ON_ERROR_STOP=1 -f script/sql/install-skillsheet-read-boundary.sql
psql "$ADMIN_DATABASE_URL" -X -v ON_ERROR_STOP=1 -f script/sql/install-skillsheet-write-boundary.sql
# あなたの接続 role へ EXECUTE + principals 写像を付与（値は管理者が発行する）
psql "$ADMIN_DATABASE_URL" -X -v ON_ERROR_STOP=1 \
-v runtime_role='<接続 role 名>' \
-v runtime_password='<生成したパスワード>' \
-v owner_id='<SKILLSHEET_OWNER_ID>' \
-f script/sql/install-runtime-role.sql
詳細な手順・環境変数・デプロイは setup.md を参照してください。
アクセス経路
- 閲覧のみ:
/viewer-auth で閲覧コード（VIEWER_CODE）を入力
- 編集:
/login で編集者（Better Auth）ログイン → /builder
主要コマンド
| コマンド | 説明 |
|---|
pnpm dev | 開発サーバー起動 |
pnpm build | 本番ビルド |
pnpm start | ビルド後のサーバー起動 |
pnpm lint | Biome でチェック（biome check .） |
pnpm format | Biome でフォーマット（biome format --write .） |
pnpm type-check | TypeScript 型チェック |
pnpm test | 全テスト（Vitest） |
pnpm test:e2e:local | 使い捨ての隔離 DB を立てて、Playwright と本番ビルドの Chrome/Chromium 検証を通す（pnpm test:e2e 単体は隔離 DB の外では起動しない）。test-results/e2e/ に証跡を保存 |
pnpm db:generate | スキーマからマイグレーション生成（Drizzle） |
pnpm db:migrate | マイグレーション適用 |
ドキュメント
新メンバー向け
実装解説
検証
ライセンス
UNLICENSED
