id: proj:sailvlog
type: project
name: sailvlog（反省会リプレイ）
aliases: [反省会リプレイ・デバッガ, 反省会リプレイ, セイルブイログ]
summary: ヨット部の反省会のために、複数艇の GPX を同じ時間軸で再生し、タイムラインに注釈を残して部内・部外へ共有する Web アプリ
status: active
part_of: area:dev
uses: ['tool:nextjs', 'tool:vercel', 'tool:render', 'tool:neon', 'tool:express', 'tool:prisma', 'tool:postgresql', 'tool:docker', 'tool:github-actions', 'tool:codex-cli', 'tool:claude-code']
provides:
- {id: 'cap:multi-boat-gpx-replay', name: 複数艇の GPX のリプレイ, summary: 複数艇の GPX を検証して同じ時間軸に正規化し、Canvas で重ねて再生する（時計・投影・ズーム・ピンチ・タッチでの移動）, entry: frontend/src/lib/replay, check: cd frontend && npm test, maturity: production}
- id: cap:codex-delegation-script
name: Codex への作業の委譲
aliases: [codex-task.sh, codex exec の委譲]
summary: audit・impl・research の3つの型で codex exec に作業を渡し、守る境界をプロンプトに自動で前置して、報告を .codex-reports/ に必ず残す
entry: scripts/codex-task.sh
maturity: working
built_with: ['tool:codex-cli', 'tool:claude-code']
- id: cap:production-watchdog
name: 本番の死活とデプロイ漏れの監視
summary: GitHub Actions が30分ごとに Render と Vercel の本番を叩き、死活とデプロイ漏れを調べて Issue を自動で起票・クローズする
entry: .github/workflows/production-watchdog.yml
maturity: working
built_with: ['tool:github-actions']
sailvlog — 反省会リプレイ・デバッガ
大学ヨット部の反省会を、記憶とホワイトボードから「航跡データ」へ置き換える。
複数艇のGPXを取り込み、同じ時間軸で再生し、気づいた瞬間にタイムラインへ注釈を残して部内で共有する。
[ここにデモGIF/スクリーンショットが入ります — demo-director 作業待ち。挿入までは /sessions/[id] を実際に開いて確認してください]
なぜ作ったか
このリポジトリはもともと「セーラー向けナレッジシェアSNS」（記事・Q&A・フィード・学習コース）として作られていましたが、**「機能を寄せ集めただけで、誰の何の課題を解いているか説明できない」**という自己診断（v1批判）を経て、v3としてピボットしました。
v3が解くのは1つだけです。大学ヨット部の週次反省会で、艇のGPS航跡を並べて見ながら「あのタックはどうだった」を議論し、その気づきを次の代へ引き継ぐこと。機能を足すより、この1本の体験を最後まで太くすることを優先しています。
ピボットの意思決定の経緯は以下に記録されています。
主な機能
- GPX取込＆複数艇同時再生 — 練習・レースで複数艇が記録したGPXをまとめてアップロードすると、同じ時間軸に正規化して重ね描き再生できる（
/sessions/new → /sessions/[id]）
- タイムライン注釈 — 再生中の任意の瞬間に気づきをピン留めでき、後からクリックしてその時刻へシークし直せる
- 部内URL共有 — 再生位置・表示艇の状態をURLに埋め込んで共有し、同じチームの別メンバーが同じ画面を開ける
- 収録ハンドブック — GPSロガー（Geo Tracker等）の設定手順・出艇前チェックリスト・取込手順をログイン不要で読めるページ（
/handbook）
- 部外向け公開ビュー — セッション所有者・Team adminが「学びの要約」を添えて昇格すると、認証不要で開ける読み取り専用ページ
/p/[slug] が発行される。非公開の注釈・編集UIは一切露出せず、OGP（unlistedはnoindex）にも対応（本番は稼働中だが、/p/[slug]の公開URLは当面部内限定の運用としており外部へは配布していない — 詳細は下記「デプロイについて」）
部外向け共有（公開ビュー）の使い方
/sessions/[id] の再生画面で「公開する」ボタン（uploader本人 または Team adminにのみ表示）を押す- ダイアログで「学びの要約」を入力する（必須。空または空白のみでは確定できない）
- 公開してよい注釈にチェックを入れる（既定では全ての注釈が非公開。反省会のメモを誤って公開しない設計）
- 公開範囲を選ぶ（「リンクを知っている人は誰でも見られる」= unlisted / 検索エンジンにも出す = public）。「航跡の先頭・末尾に陸上の移動が含まれていないか確認してください」の注意書きが出るので、GPS収録の前後がログの取り忘れで陸上を含んでいないか確認してから確定する
- 確定すると公開URL（
/p/[slug]）が発行され、ヘッダのボタンが「公開URLをコピー」に切り替わる。/sessions 一覧・再生画面には「公開中」（public）/「リンク限定」（unlisted）のチップが表示される
- コピーしたURLはログアウト状態でも開ける。学びの要約→航跡再生→公開注釈のみのタイムライン→「sailvlogとは」の順で表示され、編集系UI（メモ追加・削除・公開ボタン）は出ない
- 「公開をやめる」を押すと同じURLは以後404になる。再度公開すると別の新しいURLが発行される（旧URLは復活しない）
技術スタック
| 領域 | 技術 | 選定理由 |
|---|
| Frontend | Next.js 14 (App Router) / React / TypeScript | 型安全なままSSR/CSRを使い分けられ、部内限定〜将来の公開ページ追加まで1リポジトリで完結させたかった |
| 描画 | Canvas（命令的描画・自前実装） | 複数艇×数千点のリプレイをフレーム落ちなく描く要件に対し、汎用地図ライブラリより制御しやすいと判断（docs/dev-org/ARCH.md のADR参照） |
| Backend | Node.js / Express / TypeScript | 認証・チーム管理などv1の基盤をそのまま引き継げる構成 |
| DB | PostgreSQL / Prisma ORM | GPX由来の時系列データ（JSONB）とリレーショナルなチーム/権限モデルを1つのDBで両立 |
| 開発環境 | Docker / Docker Compose | 「新規メンバーが docker compose up だけで動かせる」を優先し、ローカルのNode/PostgreSQLバージョン差異を吸収 |
| CI | GitHub Actions | pushのたびにbackend/frontendのテスト・型チェック・ビルドを自動実行（後述） |
| 新規依存 | ゼロ（GPXパース・リプレイエンジンとも自前実装） | 「新技術予算を将来のPhaseのために温存する」という設計方針（ARCH.md §1） |
セットアップ（ローカル開発）
前提: Docker / Docker Compose が使えること。
git clone https://github.com/happiitsumo-bit/sailvlog.git
cd sailvlog
cp .env.example .env # 値はローカル用のデフォルトのままでOK
docker compose up -d
起動後:
ポート番号に注意: docker-compose.yml はホスト側を 3001/8001/5433 にマッピングしています（コンテナ内部はそれぞれ 3000/8000/5432）。.env.example の NEXT_PUBLIC_API_URL も 8001 前提です。
初回のみ、コンテナ内の依存関係が package.json と食い違っていることがあります（下記Q&A参照）。その場合は:
docker compose exec backend npm install
動作確認:
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:3001/login # → 200
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8001/api/health # → 200
/api/teams は 2026-07-26 から認証必須になったため、未認証の curl では 401 が返ります（死活の確認には本番監視と同じ /api/health を使います）。
テストの実行
重要（2026-07-28 更新）: backendのテストは ホスト側から実行します。docker compose exec backend npm test は意図的に失敗する設計になりました（理由は下の「テスト運用のルール」参照）。
# backend（Jest。DBはdocker-composeのdbサービスをホストの5433経由で使用）
cd backend && npm test
# frontend（Vitest。GPX/リプレイエンジンの純関数テスト）
cd frontend && npm test
# frontendの型チェック・ビルド確認
cd frontend && npx tsc --noEmit && npm run build
通る条件は、型チェック（npx tsc --noEmit）がエラー0、テストが全件成功、npm run build が成功です（2026-10-02 の CI では10ルート = /, /handbook, /login, /register, /sessions, /sessions/[id], /sessions/new, /p/[slug], /teams, /_not-found）。
テストの件数のベースライン（下回ったら未完成）は AGENTS.md の「検証コマンドとベースライン」を正本とし、README には書きません。
This is the beginning of the README. Read the rest at the original. Read the full README ↗
