本文へ移動
Matsuba Inside

2026-05-01 時点の資料です。読みやすさのために、一部の文字の色を濃くしています。

開発計画と工数/ Phases & effort

松葉 / Matsuba は 9 つのフェーズで構築します。延べ作業日は約 129 営業日、実工期は約 108 営業日（クリティカルパス、Phase 5 / 6 / 8 の並行作業を考慮）です。想定工数は、経験者がフルタイムで進める前提では約 6.5 人月、これに対し一人のエンジニアが生成 AI を使わずに進める（初見技術のキャッチアップ時間を含む）前提では約 10〜13 人月と見立てています。

01

フェーズ依存関係Phase dependencies

基盤と認証を直列で固め、コア機能の上に信頼性レイヤと公開ページ、保持・アーカイブを並行で重ねます。最後に管理画面を集約してリリース準備へ進みます。

図 01 · フェーズの依存と並行関係
PHASE 1基盤構築14 日PHASE 2認証基盤14 日PHASE 3コア基盤21 日PHASE 4コア運用機能14 日PHASE 5信頼性レイヤ28 日PHASE 6保持・アーカイブ14 日PHASE 8公開・システム画面7 日PHASE 7管理画面14 日PH 9準備3 日

Phase 5（信頼性）と Phase 6（保持）、Phase 8（公開画面）は Phase 4 完了後に並行で進められます。Phase 7（管理画面）は Phase 5 で蓄積されるデータに依存するため、Phase 5 完了が前提です。Phase 9 のリリース準備は監視・アラートの最終設定のみで、コード作業はほぼ発生しません。

02

フェーズ一覧Phase summary

9 つのフェーズの担当範囲と想定期間、主な構築物（機能カテゴリと画面数の目安）を表にまとめます。「想定期間」は経験者がそのフェーズに集中して取り組んだ場合の営業日数で、フェーズ単独の所要を表します（並行作業は加味していません）。

Phase担当範囲主な構築物想定期間
Phase 1
基盤構築		Google Cloud / Supabase / Resend / Workspace / モノレポ / DB / Pub/Sub の土台GUI 操作手順 12 本 + 共通基盤タスク 11 本 / 5 バケット + Pub/Sub 13 トピック + WIF14 日
Phase 2
認証基盤		Better Auth + メール OTP MFA + 4 ロール + RLS（行レベルセキュリティ）機能 4 / 画面 8（サインイン入口分岐 / 社内 / 社外 / OTP / 招待 / 初回 MFA 等）14 日
Phase 3
コア基盤		Box CRUD + メンバー + フォルダ + UL / DL / 差し替え / 世代管理 / 可視性 3 段階機能 11 / 画面 6（ホーム / Box 新規作成 / Box 詳細ファイル・メンバー・設定 / ゴミ箱）21 日
Phase 4
コア運用機能		プレビュー 4 種 / Box 内検索 / メタ拡張 / タグナビ / 一括 DL / コメント機能 5 / 画面 3 + ホーム差分（最近のファイル）14 日
Phase 5
信頼性レイヤ		ウイルススキャン / Drive 同期 / 通知 / 共有リンク / 監査 / 関連 admin機能 7 / 画面 4 + 管理画面 7（最も重いフェーズ）28 日
Phase 6
保持・アーカイブ		保持期間 + Hold + ローリングウィンドウ + Drive アーカイブ参照機能 4 / 画面 1（Phase 5 と並行可）14 日
Phase 7
管理画面		/admin 残ページ + 監査 UI + admin_metrics 集計バッチ + 長期運用バッチ群機能 2 / 画面 10 + 18 種のバッチ統合14 日
Phase 8
公開・システム画面		ブランド LP / 利用規約 / プライバシー / お問い合わせ / メンテナンス / エラー / オフライン画面 7（業務ロジックなし、Phase 5 と並行可）7 日
Phase 9
リリース準備		監視・アラートの最終設定（しきい値再評価・到達確認・Billing アラート）タスク 1 本（コード作業なし）3 日
合計機能 33 / 画面 39 / バッチ 18 種延べ 約 129 日
実工期 約 108 日（並行考慮）
03

各フェーズの詳細Per-phase scope & DoD

フェーズごとに目的・主な構築物・完了条件（DoD）・注目ポイントを示します。注目ポイントは、本サービスがプロダクション運用を前提に組み込んでいる設計の所在です。

Phase 1 — Foundation14 日

基盤構築

クラウド / ローカル / モノレポ / DB / Pub/Sub / 共通基盤を整備し、後続フェーズが「DB がある・認証ライブラリが入っている・Pub/Sub が動く・ファイル UL 可能」の状態を作ります。

主な構築物

  • Google Cloud プロジェクト + 10 種の API 有効化
  • 5 バケット（未検査 / 検査済み / 隔離 / ミラー〔ウイルス定義〕 / 共有 ZIP）
  • Pub/Sub 13 トピック + DLQ（配信失敗キュー）
  • WIF（Workload Identity Federation、鍵不要のクラウド権限委譲）
  • 4 サービス（web / api / sync / scanner）の Docker Compose 起動

完了条件

  • 追記専用 RLS + SECURITY DEFINER 書き込み関数で監査ログが動く
  • Outbox テーブル + Dispatcher Worker で DB ↔ Pub/Sub が整合

注目: 鍵レスデプロイ（WIF）と 5 バケット分離 + Eventarc 連動を最初に固めることで、後続のすべてのファイル処理が「責務分離 + 鍵漏洩リスクなし」で組み上がります。

Phase 2 — Authentication14 日

認証基盤

Better Auth 1.3+ を中核に、社内 SSO / 社外メール+パス + メール OTP MFA / 4 ロール認可 / RLS を完成させます。

主な構築物

  • 社内 Google SSO（hd=example.com 強制 + サーバ側ドメイン再検証）
  • 社外メール OTP 必須（信頼デバイス 30 日 / バックアップコード 10 個）
  • organization の additionalFields で Box を単一テーブル管理
  • 4 ロール（Viewer / Uploader / Editor / Owner）の accessControl

完了条件

  • 三層認可（プロキシ / ルート / DB-RLS）の経路がすべて通る
  • 認証イベント全件が audit_logs に追記される

注目: 「セッション検証はプロキシ層、ロール判定はルート層、データ可視範囲は DB の RLS」と三層に分解された認可を初回から組み込みます。

Phase 3 — Core base21 日

コア（Box・ファイル基盤）

Box CRUD + メンバー + フォルダ階層 + UL / DL / 差し替え / 世代管理を完成させ、業務の中核を動かします。

主な構築物

  • Box 可視性 3 段階（members / internal_searchable / internal_open）と参加申請
  • tus-js-client + GCS Resumable Upload で 200 MB UL
  • 世代管理（最新 + 10 世代、Box 単位設定可）
  • 論理削除 → 30 日ゴミ箱 → 物理削除

完了条件

  • 未検査バケット → スタブ scanner → 検査済みバケットへの rewrite の動線がスタブで通る
  • マクロ Office と古い Office 形式が拡張子レベルで拒否される

注目: 「Box 可視性 3 段階 + 参加申請」は本サービス独自の業務概念で、社内非メンバーを擬似ロール internal_viewer で RLS が read-only に縛ります。

Phase 4 — Core ops14 日

コア（ファイル運用機能）

UX を支える周辺機能を一通り揃えます。プレビュー 4 種、Box 内検索、ファイルメタ拡張、タグナビ、一括 DL、コメント、最近のファイル。

主な構築物

  • PDF / 動画 / 音声 / 画像 / Office（Drive Viewer）のプレビュー
  • Box 内検索（pg_trgm + ILIKE、ファイル名 / フォルダ名 / タグ / 説明 / UL者）
  • ファイルメタ拡張（description 1000 字 + tags text[]）
  • nuqs（URL 状態管理ライブラリ）でタグナビ ?tag=...

完了条件

  • 一括 DL の ZIP しきい値（200 MB / 10 ファイル）で個別 DL 誘導が動く
  • 「最近のファイル」ウィジェットが直近の上位 10 件を返す

注目: URL 状態管理を nuqs に集約することで、検索条件・タグ絞り込みをそのまま URL として共有・ブックマーク可能にします。

Phase 5 — Reliability28 日 · 最長

信頼性レイヤ

業務利用に耐える信頼性レイヤを全方位で構築します。ウイルススキャン / Drive 同期 / 通知 / 共有リンク / 監査 / 関連管理画面。

主な構築物

  • ClamAV 1.4 + freshclam 6 時間ごと + 月次 EICAR テスト
  • apps/sync（Go）= Pub/Sub Push + Drive Resumable Upload + appProperties
  • 指数バックオフ（回数を限って再試行） + DLQ + processed_events による冪等性
  • 日次の補修バッチ（Box 単位の並列）
  • Resend + react-email で 16 種テンプレ + 30 分間隔の digest worker
  • 共有リンク（期限・パスワード・回数・受取人 OTP・メール送信）
  • 監査ログ閲覧 UI + CSV エクスポート + アプリ層アラート 7 種

完了条件

  • 感染検出 → 即時メール（system_admin + UL者 + Box Owner）の経路が動く
  • Drive 直接アップロード検知 / Drive 側削除検知が日次で記録される

注目: 多層ウイルススキャン + Outbox + DLQ + 冪等性キーを組み合わせたイベント駆動アーキテクチャを、Go と TypeScript の型を protobuf で共有しながら構築します。

Phase 6 — Retention14 日（並行可）

保持・アーカイブ

ストレージの無制限増加を防ぎつつ、「ある日突然消える」を絶対に回避するための保持期間運用を組み立てます。

主な構築物

  • 全社デフォルト 180 日 + Box デフォルト + 個別 Hold（理由必須）
  • ローリングウィンドウ（アクセスで last_accessed_at 更新 → 期限延長）
  • 凍結期間 30 日（UL 直後の最低保持）
  • 削除当日メール通知（immediate 強制、Owner + UL者 + 最終アクセス者）
  • 影響シミュレーション（全社デフォルト変更時に「N ファイル / X GB」を即表示）
  • Drive アーカイブ参照タブ（read-only）

完了条件

  • 共有リンク有効ファイルは「失効 + 7 日」まで削除延期される
  • Hold 合計が一定容量以上の Box は 3 箇所にバッジ常時表示される

注目: 削除予告 → 当日通知 → 実削除 → Drive アーカイブ参照という 4 段階の安全網を機能群として独立させた、保持期間設計です。

Phase 7 — Admin14 日

管理画面

/admin の運用ダッシュボード本体、監査閲覧、設定 UI、長期運用バッチ群を仕上げます。

主な構築物

  • ダッシュボード（信号機方式のヘルスインジケータ 6 観点 + KPI 6 種）
  • ストレージ / ユーザ / Box / 保持 / 監査 / 設定 各画面
  • 重大操作の理由必須 + 即時メール通知 + 監査記録
  • 長期運用バッチ 10 種以上を docshare-batch に統合
  • JWKS（JWT 鍵セット）の年次自動ローテ、旧鍵の一定期間の並行公開

完了条件

  • 監査ログ CSV エクスポートが「直近 1 ヶ月オンライン + それ以前 GCS 退避」の二段で取れる
  • メンテナンスモード ON で全リクエスト 503 + 告知バナー表示

注目: 長期運用バッチ 18 種を単一 Cloud Run Jobs サービスに統合し、20 年運用を見据えた監査ログ月次パーティション + GCS 退避を組み込みます。

Phase 8 — Public7 日（並行可）

公開・システム画面

非認証ユーザ向けの最小 LP、法務ページ、お問い合わせ、メンテナンス / エラー / オフライン画面を整えます。

主な構築物

  • 未認証 / はミニマム LP、認証済みは /boxes へリダイレクト
  • 利用規約・プライバシーポリシー（章立てのみ、本文は法務確定後）
  • お問い合わせ（フォームなし、メール窓口 + FAQ）
  • PWA 最小対応（マニフェスト + apple-touch-icon + 専用オフライン画面）
  • 404 / 500 / 403 の共通エラー画面（unDraw イラスト + Teal 配色）

完了条件

  • proxy.ts の matcher で認証要否が URL ごとに正しく分岐する
  • OnlineWatcher が navigator.onLine === false 検知時に /offline へ遷移

注目: Service Worker やキャッシュ戦略といった過剰機能を意図的に省き、「最小限の見た目だけインストール可能」な PWA に絞った判断。

Phase 9 — Pre-release3 日

リリース準備

監視・アラート最終設定のみを行います。コード作業は基本発生せず、しきい値の再評価とアラート到達確認、Billing 予算アラートの最終調整に集中します。

主な構築物

  • app_alerts 13 種の実機シミュレーション
  • 通知到達確認（Resend + メール）
  • Cloud Billing 予算アラート（段階的な割合）

完了条件

  • すべての critical アラートが system_admin 全員に到達する
  • 感染検出のシミュレーションで即時メールが配信される

注目: 「リリース後の活動」は本ロードマップ外として明確に分離し、別に扱う設計です。

04

工数の見立てPerson-month estimates

各フェーズの想定人月を 2 つの前提で並列に示します。経験者前提は、採用技術に習熟したエンジニアがフルタイムで進めた場合の純作業量（1 人月 = 20 営業日換算）です。ソロ + キャッチアップ込みは、一人のエンジニアが生成 AI を使わずに進める前提で、Next.js 16 / Better Auth / Go / protobuf / WIF / Cloud Run / RLS / Pub/Sub / ClamAV など初見技術の学習時間を含めた想定（経験者前提の 1.5〜2.0 倍）です。

Phase主な技術領域経験者前提ソロ + キャッチアップ込み
Phase 1 基盤構築Google Cloud（Cloud Run / GCS / Pub/Sub / Eventarc / WIF） / Terraform / Docker Compose / モノレポ0.71.0〜1.4
Phase 2 認証基盤Better Auth + organization / admin / jwt / twoFactor / emailOTP / RLS 設計0.71.0〜1.4
Phase 3 コア基盤Box + 可視性 3 段階 + tus UL + 世代管理 + RLS ポリシー1.051.6〜2.1
Phase 4 コア運用機能プレビュー 4 種 + pg_trgm + nuqs + 一括 ZIP + コメント0.71.0〜1.4
Phase 5 信頼性レイヤClamAV + Drive 同期 Go + Resend テンプレ + 共有リンク + 監査 UI1.42.1〜2.8
Phase 6 保持・アーカイブ保持期間 + Hold + ローリング + Drive アーカイブ + 影響シミュレーション0.71.0〜1.4
Phase 7 管理画面/admin 10 画面 + 長期運用バッチ 12 種0.71.0〜1.4
Phase 8 公開画面公開ページ + PWA 最小 + エラー画面0.350.5〜0.7
Phase 9 準備監視・アラート最終確認0.150.2〜0.3
合計約 6.5 人月約 10〜13 人月

工期と工数の関係: 工数（人月）は純粋な作業量を、工期（営業日）はカレンダー上の経過日数を表します。延べ作業日 約 129 営業日（÷ 20 ≒ 6.5 人月）は経験者前提の純作業量と一致します。実工期はクリティカルパスで 約 108 営業日（Phase 5 / 6 / 8 の並行作業を考慮）です。ソロ + 生成 AI 不使用 + 初見技術キャッチアップ込み（約 10〜13 人月）は、同じ作業範囲を一人で担う場合の学習・試行錯誤を含む見積りで、純作業量 6.5 人月との差分（約 3.5〜6.5 人月）が学習コスト相当です。

05

設計難易度・実装難易度Difficulty assessment

本サービスの開発難易度を、設計と実装の 2 軸で評価します。

Design difficulty

設計難易度

★★★★★ 5 / 5
  1. 社内 SSO / 社外メール OTP / 共有リンク受取という 3 経路の認証認可を、Better Auth 上で破綻なく組み立てる必要があります。
  2. 三層認可（プロキシ層のセッション / ルート層の accessControl / DB 層の RLS）の責務分離と漏れ防止を要求します。
  3. Outbox パターン + Pub/Sub + DLQ + 冪等性キーを破綻なく組み合わせるイベント駆動の整合性設計が必要です。
  4. 監査ログ月次パーティション + GCS 退避、JWKS 年次ローテ、disabled-user 5 年消去など、20 年運用を見据えた長期設計が要ります。
  5. Box 可視性 3 段階 + 参加申請という、本サービス独自の業務概念を扱います。
  6. Drive 同期 ON / OFF の途中切替で、既存ファイルの初期同期・orphan 検知・削除検知の整合性を保つ必要があります。
  7. 多層ウイルススキャン（クライアント / ClamAV / Drive / エンドポイント）の責務分担と、scan_status による DB 二重防御を設計します。
Implementation difficulty

実装難易度

★★★★★ 4 / 5
  1. 採用技術の幅が広いです。Next.js 16（Cache Components / PPR）+ Hono RPC + Better Auth + Prisma 7 Driver Adapter + Go + ClamAV + tus + Cloud Run × 4 + Jobs + Cloud Tasks + Cloud Scheduler + Eventarc + Pub/Sub + buf/protobuf + Turborepo + pnpm workspace + go workspace。
  2. TypeScript と Go を横断し、Pub/Sub メッセージスキーマを protobuf + buf で TS / Go の両方に生成して型共有します。
  3. クリーンアーキテクチャ 4 層（Domain / Application / Infrastructure / Presentation）の徹底と、UseCase から Prisma 直接利用を禁止する依存方向の徹底が必要です。
  4. モック原則禁止のテスト戦略で、Vitest + Playwright + go testing + 実 Postgres + fake-gcs-server + Pub/Sub emulator + Resend dev mode を組み合わせます。
  5. CI/CD は GitHub Actions + Workload Identity Federation + Turborepo 差分ビルド + Docker マルチステージで、paths-filter による該当サービスのみの自動デプロイを組みます。
  6. 減点要因: 設計が固まっていれば、各層単体の実装は標準的なパターンを踏襲できます（Resumable Upload・Pub/Sub Push・RLS は Google Cloud と Supabase の公式パターンに沿って書ける）。
06

本サービスを支える本格的な仕組みProduction-grade foundations

本サービスが備える 10 の仕組みを整理します。それぞれの詳細は他のページでも取り上げています。

No.要素所在
014 サービス分離デプロイweb / api / sync / scanner を Cloud Run 上の独立サービスとして配備
025 バケット + Eventarc + ClamAV未検査バケット → 検査済み / 隔離バケットへの rewrite で多層ウイルススキャン
03追記専用 RLS + 月次パーティション + GCS 退避監査ログの UPDATE と DELETE を DB で拒否し、20 年運用に耐える設計
04Outbox + DLQ + 冪等性DB 書き込みと Pub/Sub publish のトランザクション整合性
05三層認可プロキシ / ロール / DB-RLS の三段重ねがけ
0620 年運用バッチ 18 種JWKS 年次ローテ / 無効化 5 年消去 / EICAR 月次テストなど
07Hold + ローリングウィンドウ + 凍結期間 + 影響シミュレーション保持期間運用の安全網を 4 段階で構成
08共有リンク多層認証パスワード + OTP + 回数制限 + ブルートフォース検知 + レート制限
09Go × TS 型共有 protobufPub/Sub メッセージスキーマを buf で両言語生成
10WIF 鍵レスデプロイGitHub Actions にサービスアカウントキーを発行しない CI/CD