共有アプリのUI・API・テスト・デプロイ準備を崩さず進める
2026年05月18日から2026年05月24日までのワークログを見返すと、この事例の実装テーマは「共有アプリの体験を、画面・API・テスト・デプロイ準備まで一気通貫で整える」ことだった。中心になったのは shared-shopping-app という共有買い物リストアプリで、モバイル UI の刷新、招待リンク API の運用耐性向上、E2E テストの追従、Cloudflare 移行準備が同時に進んでいる。
あわせて、kakei-balance-app という共有家計アプリでは、ゲスト利用中心の MVP を Supabase 連携の共有家計構成へ広げる改修が進み、product-service という Spring Boot API では OpenAPI / Swagger UI の導入が進んだ。この事例では別々のリポジトリを触っているようでいて、実際には「状態管理を分離しながら、利用者向け導線と運用者向け確認手段を厚くする」という共通の流れが見えていた。
この記事で解決すること
共有アプリは UI だけを変えると、招待 API、並び順、テスト、デプロイ準備のどこかに歪みが出やすい。この記事では、次の悩みを解く。
- 共有アプリの画面改善を、API とテストの変更から切り離さず進めたい。
- Cloudflare 移行前に、どの層の責務を整理すべきか見たい。
- 複数リポジトリの作業を、ひとつの設計判断として読み解きたい。
実施した改善
週の前半では、kakei-balance-app に認証・世帯共有・クラウド保存を足し、IndexedDB に閉じた家計管理から、Supabase を使った共有家計アプリへ拡張する流れが見えた。product-service では、Spring Boot アプリに Springdoc を導入し、Swagger UI と API Docs の公開経路を追加して、利用者が仕様確認しやすい状態を作っている。
週の後半で比重が大きかったのは shared-shopping-app だった。モバイル向けのリスト切り替え UI をカルーセル風に作り直し、設定画面やテーマ切り替えも含めて見た目と操作モデルを更新したうえで、招待リンク API のエラーハンドリング、リスト並び順ロジックの共通化、E2E テストの追従、Cloudflare へのデプロイ移行準備までをまとめて進めている。
確認できた成果
この事例の成果は、単なる UI 改修ではなく、共有アプリを長く運用するための土台を複数層で固めたことにある。
| リポジトリ | 主な変更 | 成果 |
|---|---|---|
shared-shopping-app |
モバイル UI 刷新、招待 API 改善、E2E 更新、Cloudflare 移行整理 | 体験改善と運用移行の論点が一つの流れで見える状態になった |
kakei-balance-app |
Supabase 認証、世帯共有、クラウド保存、ダッシュボード拡張 | ゲスト MVP から共有家計アプリへ広げる構造が見えた |
product-service |
Springdoc 導入、Swagger UI / API Docs 設定 | API 利用者が仕様確認しやすい入口を追加できた |
特に shared-shopping-app では、UI だけを先に派手に変えるのではなく、並び順ロジックを純関数へ切り出し、招待テーブル未反映時のエラーを API で吸収し、Playwright テストまで追従させている点が良かった。これにより、「見た目が変わった」よりも「変更が継続運用に耐える形になった」と言いやすい。
判断と進め方
この事例の流れは、ドキュメント整理から始めて API と UI の責務をそろえ、最後にテストとデプロイ準備を合わせる順番だった。shared-shopping-app では、まず Cloudflare 移行メモと公開準備を整理し、その後にリスト並び順と招待リンク API を固め、さらにモバイル UI を刷新し、その変化に合わせて E2E を更新している。
この順番が効いているのは、見た目と運用を別物として扱っていないからだ。招待リンク API のエラー整形や Cloudflare 移行手順の明文化が先にあることで、フロントエンドの見た目改善が「運用時に壊れやすい派手な変更」で終わらず、実際に公開まで持っていきやすい状態になっている。
flowchart LR
A["shared-shopping-app UI刷新"] --> B["並び順ロジック共通化"]
B --> C["招待リンクAPIの運用耐性向上"]
C --> D["Playwright E2E追従"]
D --> E["Cloudflare移行準備"]
E --> F["公開前の受け入れ確認"]使った技術
主役だった shared-shopping-app の技術スタックは、Next.js 15 と React 19 を土台に、TypeScript、Supabase、Playwright、Vitest、OpenNext for Cloudflare、Wrangler を組み合わせる構成だった。画面側では Client Component を中心にリスト詳細、設定画面、テーマ切り替えを実装し、API 側では Supabase を前提に招待リンクやリスト取得を扱っている。
kakei-balance-app では Next.js App Router と React Context によるセッション管理、Supabase Auth / Database、IndexedDB ベースのゲスト保存を組み合わせ、ログイン前後で保存先を切り替える二層構成を採っていた。product-service は Java の Spring Boot 3 と Maven、そして springdoc-openapi による API ドキュメント生成が中心で、こちらは UI ではなく API 自己記述性の改善がテーマだった。
技術の使い方を見ると、この事例では新技術を増やす週というより、「既存スタックの責務を整理して、ユーザー導線と運用導線を足す週」だったと言える。特にテストとデプロイ関連は、実装そのものと同じくらい重要な層として扱われていた。
構成
shared-shopping-app の変更は、UI、API、テスト、デプロイ準備の 4 層がきれいに分かれていた。
| 層 | 役割 | この事例の変更 |
|---|---|---|
| UI | リスト閲覧・設定・テーマ切り替え | カルーセル型のリスト切り替え、プレビュー表示、設定画面整理 |
| API | 共有リンク発行・一覧取得 | 招待テーブル未反映時のエラー整形、並び順ロジックの共通化 |
| Test | 変更の回帰検知 | Vitest で並び順を固定化、Playwright でゲスト導線と公開ページを検証 |
| Deploy | ビルド・プレビュー・本番移行準備 | OpenNext / Wrangler 前提の Cloudflare 移行メモと受け入れ条件整理 |
flowchart TD
UI["Next.js UI<br/>list-detail / settings / nav"] --> API["API Routes<br/>invite / lists"]
API --> DB["Supabase<br/>lists / invites / auth"]
UI --> TEST["Playwright / Vitest"]
API --> TEST
UI --> DEPLOY["OpenNext + Cloudflare Workers"]
API --> DEPLOYこの構成の良い点は、変更の責務が明確なことだ。並び順のような判断は lib/list-order.ts に切り出し、UI の見た目変更と API の取得順序が同じルールを共有する。招待テーブル未反映のような運用差分は API 境界で吸収し、Playwright はユーザー操作の全体像を、Vitest は小さなロジックの正しさをそれぞれ受け持つ。
採用理由と代替案
この事例の選定は、どれも「見た目を作るため」より「運用で破綻しにくくするため」の理由が強い。
| 選択 | 代替案 | 採用理由 |
|---|---|---|
リスト順を created_at 基準に統一 |
updated_at 順にする |
モバイルの横スクロール UI で位置が跳ねにくく、認知負荷を下げられる |
| 招待エラーを API で専用メッセージ化 | Supabase の生エラーをそのまま返す | スキーマ未反映時の切り分けがしやすく、利用者に不要な内部情報を見せずに済む |
| 並び順ロジックを純関数化してテスト | UI 内に埋め込む | UI と API で同じ規則を再利用しやすく、回帰を小さく検知できる |
| Cloudflare 移行を OpenNext 前提で整理 | ホスティングを現状維持する | App Router 構成を大きく壊さず、Cron や Preview の整理まで視野に入れやすい |
kakei-balance-app でゲスト保存とクラウド保存を併存 |
すぐ全面クラウド移行する | MVP 利用者を壊さずに共有機能を足せる |
product-service に Springdoc を導入 |
README 手書き運用を続ける | API 実装とのズレを減らし、利用者の確認コストを下げられる |
この週の判断はどれも保守性寄りだ。新しい基盤へ飛び移る前に、既存コードの責務分離と確認方法を先に作っているので、変更の速度と安全性の両立を狙いやすい。
検証結果
確認した観点は、UI、API、テスト、移行準備を同じ共有アプリの変更として扱い、各層の確認方法を分けた点にある。確認した主な観点は次の通り。
npm test
npm run build
npm run test:e2e
# Vitest: 並び順ロジック
# Playwright: ゲスト導線と公開ページAPI のエラー整形、並び順ロジック、モバイル UI、Cloudflare 移行メモを別々の成果ではなく、公開前の受け入れ条件としてまとめて確認した。
導入手順
この事例の作業から再利用しやすい導入手順を抜くと、共有アプリ改修は次の順序が扱いやすい。
- 対象リポジトリの既存構成を確認し、UI、API、データ、デプロイのどこを変えるかを切り分ける。
- UI を先に触る場合でも、共有リンクや並び順のような基礎ルールは API または純関数へ寄せて、複数画面で共有できる形にする。
- 共有機能では、未反映スキーマや権限不足のような運用エラーを API で説明可能なレスポンスへ変換する。
- UI の刷新後は、Vitest のような小さなテストでロジックを固定し、Playwright のようなブラウザテストでゲスト導線、設定画面、公開ページの振る舞いを確認する。
- デプロイ先を変える場合は、コード変更と同時に build、preview、deploy の順序、Secrets、OAuth 設定、Cron の移し替え先まで文書化する。
- 本番公開前には、
build、test、test:e2e、プレビュー環境確認、共有機能の実機確認を最低ラインとして並べる。
この事例のワークログでは、テストとビルドのコード追加や運用メモは確認できた一方で、実際の npm run build や playwright test の実行完了までは確定していない箇所もあった。つまり、導入手順はかなり明確になったが、最終の受け入れ確認は次週の実行タスクとして残っている。
制約と残課題
一番大きい課題は、UI 改修と運用差分が連動していることだった。shared-shopping-app では、見た目の刷新だけならフロントエンドで閉じられるが、招待リンクは Supabase のテーブル反映状況に依存し、Cloudflare 移行は Cron、OAuth、Secret の設定まで巻き込む。そのため、コードができても運用が揃わないと完成しない。
もう一つの課題は、モバイル最適化された UI の保守だ。カルーセルやテーマ切り替えは体験としては強いが、アクセシビリティ、キーボード操作、E2E の安定性まで考えると、実装直後より運用フェーズの方が難しくなる。kakei-balance-app のゲスト保存とクラウド保存の併存も同じで、段階移行は安全だが、分岐が増えるぶんテスト観点は広がる。
product-service も小さな変更に見えて、実際には「OpenAPI を出せる」だけでは十分ではない。コントローラ単位の説明やエラーモデルが薄いままだと、Swagger UI があっても利用者体験は半端になる。導入の初期コストより、その後の情報更新をどう続けるかが重要になる。
次の改善候補
shared-shopping-app では、まず Cloudflare での cf:build と cf:preview を実際に通し、Supabase / OAuth / Secret / Cron の設定差分を実環境でつぶすべきだと思う。あわせて、招待リンク生成、2 アカウントでの共有参加、公開ページ閲覧、設定画面操作を E2E シナリオとして固定すると、移行後の回帰監視がしやすい。
kakei-balance-app では、ゲストデータからクラウド世帯への移行導線をどう作るかが次の論点になる。保存先を二層にしている設計は現実的だが、利用者が切り替えを意識しなくて済む導線がないと、共有家計アプリとしての完成度が上がりにくい。
product-service では、Swagger UI を入口にとどめず、エンドポイント説明、レスポンス例、エラー仕様まで育てると、外部利用者にとっての価値が一段上がる。この事例では「見える化」の入口ができた段階なので、次は「使える仕様書」に寄せるのが自然だ。