用語集/ Glossary of terms
本資料に登場する専門用語を、初見の方でも理解できる粒度で解説します。インフラ・クラウド / 認証・セキュリティ / データ・ファイル / 開発・運用の 4 カテゴリに整理しています。用語の選定は、本資料中で 1 回以上登場し、なおかつ業務外の読者には自明でないものに絞りました。
インフラ・クラウドInfrastructure & Cloud
松葉 / Matsuba のホスティング・実行基盤・非同期処理に関わる用語です。
| 用語 | 解説 |
|---|---|
| Cloud RunGoogle Cloud | コンテナを HTTP リクエストごとに起動する、Google Cloud のサーバレス基盤です。アイドル時はインスタンスがゼロまで縮退するためコストが低く、リクエスト到着時に自動で起動します。松葉では web / api / sync / scanner の 4 サービスを分離して配備します。 |
| Cloud Run Jobsbatch service | Cloud Run のジョブ版で、HTTP リクエストではなく「一度きりの実行」用です。バッチ処理に向きます。松葉では 18 種のバッチを単一の docshare-batch サービスに統合し、--args で振り分けます。 |
| Cloud Pub/Submessaging | Google Cloud のメッセージング基盤で、非同期処理のハブとして使います。Publish（送出）と Subscribe（受信）のモデルで疎結合な連携が可能です。回数を限ったリトライ + DLQ（後述）が標準で備わります。 |
| Cloud Tasksdeferred HTTP | 遅延実行 + リトライ付きの HTTP コールを発行できる仕組みです。Cloud Scheduler（cron 相当）よりも柔軟で、ユーザ単位・時刻単位のタスクキューを扱いやすいです。松葉では通知配信ワーカーの起動に使います。 |
| Cloud Schedulermanaged cron | Google Cloud 上の cron（定期実行）相当です。タイムゾーン指定や HTTP / Pub/Sub 起動が可能で、松葉の 18 種バッチはここから起動されます。 |
| Eventarcevent hub | Cloud Storage のオブジェクト作成・更新・削除など、Google Cloud の各種イベントを Cloud Run へ Push 配信するイベントハブです。松葉ではファイル UL を検知して ClamAV スキャナを起動するのに使います。 |
| GCSGoogle Cloud Storage | Google Cloud のオブジェクトストレージで、バケットという単位でファイルを格納します。松葉では用途別に 5 バケットを分離（未検査 / 検査済み / 隔離 / ミラー〔ウイルス定義〕 / 共有 ZIP）し、責務を明確化しています。 |
| Resumable Uploadresumable upload | GCS の「中断・再開可能なアップロード方式」です。途中で回線が切れても、続きから再送できます。クライアント側ライブラリは tus-js-client を採用し、1 ファイル最大 200 MB の UL を安定的に処理します。 |
| Signed URLsigned URL | 有効期限つきの一時的な GCS アクセス URL です。期限が切れると無効化されるため、URL を誰かに渡してしまっても永続的なアクセス権にはなりません。松葉では DL 用・UL 用とも短時間だけ有効な URL を発行します。 |
| Cloud ArmorWAF | Google Cloud のマネージド WAF（Web Application Firewall、ウェブアプリケーション防火壁）です。OWASP Top10 ルール、IP レート制限、地理ブロックを提供します。松葉では Cloud Load Balancer の前段に配置します。 |
| WIFWorkload Identity Federation | サービスアカウントの JSON キー（永続的な秘密鍵）を発行せず、GitHub Actions などの外部ワークロードに OIDC（後述）で GCP リソース権限を委譲する仕組みです。鍵漏洩リスクをそもそも作らないのが利点で、松葉の CI/CD はすべて WIF で構成します。 |
| DLQDead Letter Queue | 「死信キュー」と訳されます。Pub/Sub などのメッセージングでリトライが上限に達した失敗メッセージを隔離するキューです。松葉では dlq-monitor ジョブが 5 分間隔で件数を監視し、しきい値超過で critical アラートを発します。 |
認証・セキュリティAuth & Security
ユーザのサインインから認可（誰が何にアクセスできるか）、データ層の防御までの用語です。
| 用語 | 解説 |
|---|---|
| SSOSingle Sign-On | 単一のサインインで複数のサービスを利用できる仕組みです。松葉では社内ユーザを Google Workspace の SSO 経由でサインインさせ、社員の追加・削除を Workspace 側の運用に一元化します。 |
| OAuthdelegated auth | サービス間の認可委譲プロトコルです。「あるサービスのユーザを別サービスが代理で扱う」ための業界標準で、「Google でサインイン」の裏側で動いています。 |
| OIDCOpenID Connect | OAuth の上に「誰が認証されたか」の情報層を載せた、認証用プロトコルです。Google SSO や WIF（前述）で利用されています。 |
| hd 強制hosted domain | Google OAuth で「特定の Workspace ドメインのアカウントだけを許可する」パラメータです。松葉では hd=example.com を強制し、さらにサーバ側でドメインを再検証することで、社内 SSO ルートが社外アカウントで通過しないようにします。 |
| MFAMulti-Factor Authentication | パスワードに加えて 2 つ目の要素（知識・所持・生体）で認証する仕組みです。松葉は社外ユーザに対して「メール OTP」を MFA の所持要素として全員必須にしています。 |
| OTPOne-Time Password | 1 回限りのワンタイムパスワードです。松葉では 6 桁の数字、有効期限 5 分、続けて失敗すると 15 分ロック、というルールで運用します。 |
| 信頼デバイスtrusted device | 「このブラウザでは OTP を一定期間スキップしてよい」と記憶する仕組みです。HttpOnly + Secure + SameSite=Lax の Cookie でトークンを保管し、サーバ側はそのハッシュを trusted_devices テーブルに保持します。期間は 30 日（環境変数 TRUSTED_DEVICE_DAYS で変更可）。 |
| パスキーPasskey | パスワードの代わりに端末の生体認証や PIN を使う、WebAuthn ベースの認証方式です。松葉では初期未採用ですが、Better Auth の passkey プラグインを用いた将来拡張を見据えています。 |
| RLSRow-Level Security | PostgreSQL の「行レベルアクセス制御」機能です。テーブル全体ではなく、各行ごとに「誰が読めるか / 書けるか」を SQL のポリシーとして書けます。松葉ではアプリ層のすり抜けに備えた最終防壁として、ほぼ全テーブルに RLS を適用します。 |
| 追記専用 RLSappend-only RLS | RLS のポリシーで「INSERT は許可、UPDATE と DELETE は拒否」と設定する書き方です。audit_logs（監査ログ）テーブルに適用することで、アプリの経路からログを書き換えられないようにします。 |
| SECURITY DEFINERfunction privilege | PostgreSQL の関数権限指定です。通常は「呼び出し元」の権限で関数が実行されますが、SECURITY DEFINER を付けると「関数を定義した人」の権限で実行されます。RLS のヘルパ関数で「アプリ全体としては読めないが、特定の集計だけ許可」する用途に使います。 |
| JWTJSON Web Token | 署名つきの JSON クレーム（claim、主張）を含むトークンです。松葉では Better Auth が EdDSA 署名の短命 JWT（TTL は短時間）を発行し、Postgres の RLS が SET LOCAL request.jwt.claims でその内容を読み取ってポリシー判定に使います。 |
| JWKSJSON Web Key Set | JWT の検証に使う公開鍵のセットです。松葉では年次で自動ローテし、旧鍵を一定期間並行で公開することで、署名済みトークンの突然の無効化を避けます。 |
| CSRFCross-Site Request Forgery | 他サイトに仕込まれたフォーム経由で、サインイン済みユーザの認証情報を勝手に使われる攻撃です。松葉では Better Auth の trustedOrigins 設定と API 側の Origin チェックで防ぎます。 |
| XSSCross-Site Scripting | 攻撃者のスクリプトを表示画面に注入する攻撃です。React の自動エスケープが基本対策で、dangerouslySetInnerHTML はリント禁止としています。 |
| IDORInsecure Direct Object Reference | URL の ID を書き換えるだけで、本来見られないはずの他人のデータを覗ける脆弱性です。松葉では RLS + アプリ層チェックの二重防御で構造的に防ぎます。 |
データ・ファイルData & Files
松葉固有の業務概念と、ファイルの状態管理・保持・ウイルススキャンに関わる用語です。
| 用語 | 解説 |
|---|---|
| Boxtenant boundary | 松葉の中心概念で、ファイルとメンバーをまとめる共有箱です。認可の単位（テナント境界）でもあります。Better Auth の organization プラグインの「1 organization = 1 Box」としてマッピングし、独立した boxes テーブルは作りません。 |
| Box 可視性 3 段階visibility tiers | Box の公開範囲を 3 段階で選べます。members（既定、メンバーのみ）/ internal_searchable（社内非メンバーは検索可・参加申請可、中身不可）/ internal_open（社内非メンバーが read-only 閲覧可）。社外ユーザに対しては可視性問わずメンバーのみです。 |
| 世代管理versioning | 同名ファイルを再アップロードしたとき、上書きせず「新世代」として保持する仕組みです。松葉は最新 + 10 世代を保持（Box ごとに数を設定可）し、過去版へのロールバックを可能にします。 |
| 保持期間retention period | ファイルが自動削除されるまでの日数です。松葉では「全社デフォルト 180 日 → Box デフォルト → 個別 Hold」の三層階層で決まります。デフォルトは system_settings.retention.default_days に保持されます。 |
| Holdlegal hold | 「リーガルホールド」とも呼ばれ、自動削除の対象から外す個別フラグです。Editor 以上が理由テキスト必須で設定でき、Box 内合計が一定容量を超えると 3 箇所にバッジが常時表示されます。濫用を防ぐ仕組みです。 |
| ローリングウィンドウrolling window | アクセスがあるたびに保持期限を再延長する方式です。ダウンロード・プレビュー・差し替え・コメント・共有リンク発行で retention_expires_at = now() + 保持期間 に更新します。利用されているファイルは消えにくくなります。 |
| 凍結期間freeze period | ファイルがアップロード直後に消えないよう、UL 直後 30 日間は強制的に保持期限を伸ばす期間です。retention_expires_at = max(retention_expires_at, created_at + 30d) で実装します。 |
| Drive アーカイブ参照Drive archive | アプリ側で削除されたあとも、Google Drive 側に残っているファイルを Box の「Drive アーカイブ」タブで read-only 参照する機能です。Drive 同期 ON の Box でのみ表示され、週次バッチで exists_in_drive を更新します。 |
| appPropertiesDrive metadata | Google Drive のファイルに付けられる「カスタムキー・値」のメタデータです。松葉では docshare_box_id、docshare_file_id、docshare_version_id などを付与し、ファイル名ではなくこのキーで Drive 側と DB を突合します。 |
| ClamAVvirus scanner | オープンソースのウイルスチェックエンジンです。松葉では Go + ClamAV 1.4 を apps/scanner として Cloud Run（min=1、大きめのメモリ）で常駐させ、Eventarc 経由で UL ファイルを自動スキャンします。 |
| freshclamsignature update | ClamAV のウイルス定義データベース（シグネチャ）を自動更新するコマンドです。松葉では 6 時間ごとに自動実行し、連続して失敗すると system_admin にメール通知します。 |
| EICAREICAR test file | ウイルス対策ソフトの動作確認用に標準化された、無害なテスト文字列です。松葉では月次の clamav-eicar-test ジョブで自動 UL し、検出経路が常時生きていることを確認します。 |
開発・運用Development & Operations
リポジトリ構成・フレームワーク・分散システムのパターン・テストに関わる用語です。
| 用語 | 解説 |
|---|---|
| モノレポmonorepo | 複数のアプリ・ライブラリを 1 つの Git リポジトリで管理する構成です。松葉では apps/{web,api,sync,scanner} + packages/{database,shared,auth,events,...} を単一リポジトリで管理し、共通スキーマと型の重複を防ぎます。 |
| pnpm workspaceTS package manager | TypeScript パッケージ群を高速・省領域で管理するパッケージマネージャです。pnpm-workspace.yaml で対象を指定し、ハードリンクで重複を排除します。 |
| go workspaceGo modules | Go の go.work ファイルで複数の Go モジュール（apps/sync / apps/scanner）をローカル参照で繋ぐ仕組みです。pnpm workspace の Go 版とお考えください。 |
| Turborepobuild orchestrator | モノレポ向けのビルドキャッシュ + タスクオーケストレータです。前回と同じ入力なら結果をキャッシュから返し、CI 時間を大幅短縮します。 |
| Bufprotobuf tooling | Protocol Buffers の lint・互換性チェック・コード生成を統合した CLI ツールです。松葉では packages/events/proto/*.proto から TypeScript と Go の両方のコードを一括生成し、Pub/Sub メッセージの型を共有します。 |
| Cache ComponentsNext.js 16 feature | Next.js 16 で導入された、静的シェルと動的部分を組み合わせる新機能です。動的部分は <Suspense> で囲み、'use cache' で個別にキャッシュ戦略を指定できます。 |
| PPRPartial Prerendering | 「部分プリレンダリング」と訳されます。ページ全体ではなく一部だけを静的化し、動的部分はリクエスト時にレンダリングする戦略です。Cache Components と組み合わせて使います。 |
| Server ComponentsRSC | React のサーバ側でのみレンダリングされるコンポーネントです。データ取得をサーバ側で完結させ、ブラウザに送る JavaScript を減らせます。松葉は「Server Components ファースト」で構成します。 |
| Hono RPCtype sharing | Hono（軽量 Web フレームワーク）の機能で、hc<AppType>() を使うとサーバ側 API の型をクライアント側で完全に共有できます。ランタイム依存がなく、型推論だけで実現します。 |
| Outbox パターンtransactional outbox | DB トランザクション内でメッセージを outbox_events テーブルに書き込み、別プロセス（outbox-dispatcher）がそれを Pub/Sub に publish する設計パターンです。DB 書き込みとメッセージ送出のトランザクション整合性を保ちます。 |
| 冪等性idempotency | 同じ操作を何度実行しても同じ結果になる性質です。Pub/Sub は「at-least-once」配送のため、同じメッセージが複数回届く前提で受信側を作る必要があります。松葉では event_id（UUIDv7）+ processed_events テーブルで重複処理を防ぎます。 |
| クリーンアーキテクチャClean Architecture | ロバート・C・マーティン提唱の 4 層構造（Domain / Application / Infrastructure / Presentation）です。依存は外側から内側のみで、Domain（ビジネスルール）は他層に依存しません。松葉ではこの方針を厳格に適用します。 |
| bulletproof-reactReact reference | React 大規模アプリの参照設計です。features/{entity} と features/pages/{page} の 2 軸でディレクトリを切り、早すぎる抽象化を避ける流派です。松葉のフロントエンドはこれをベースにしています。 |
| shadcn/uicomponent collection | Radix UI ベースの React コンポーネント集です。npm パッケージではなく「コピー＆ペーストして自分のリポジトリで管理する」流派で、Tailwind v4 と相性が良いです。 |
| tus-js-clientresumable upload client | tus.io プロトコル準拠の Resumable Upload クライアントライブラリです。GCS の Resumable Upload と組み合わせて、大容量ファイルの安定 UL を実現します。 |
| Resendtransactional email | トランザクションメール送信サービスです。DMARC / SPF / DKIM の標準対応、Webhook での配信状態（delivered / bounced / complained）取得、React Email でのテンプレ記述が可能です。松葉のメール送信はすべて Resend 経由です。 |
| WebAuthnpasskey standard | パスキー（前述）の規格です。ブラウザの API として標準化されており、Better Auth の passkey プラグインで対応可能です。リリース後の拡張で導入を検討します。 |
本資料の表記ルールDocument conventions
用語 ID（F-* / FE-* / P-*）: 設計書での参照キーです。F-* は要件 ID（例 F-ACC-05、メール OTP MFA 必須）、FE-* は業務処理単位の機能 ID（例 FE-FILE-VIRUS-SCAN）、P-* は画面 ID（例 P-BOX-DETAIL-FILES）。三者は相互にトレース可能で、機能カタログ・画面カタログ・要件定義書を一意に紐付けます。
「松葉」と「Matsuba」の使い分け: 日本語 UI 内の主表記は 松葉（Shippori Mincho B1、letter-spacing 0.18em）、英語・ASCII 文脈では Matsuba（Inter italic）です。メール件名は「【松葉】Box〇〇への招待」/「【Matsuba】Box invitation」のように使い分けます。
敬体（です・ます調）の統一: 本資料の本文はすべて敬体で記述しています。命令形は最小限とし、エラー文言は「具体的な状況 + 解決手段」の組で書きます。