松葉 / Matsuba ・ 開発過程資料
用語集/ Glossary
本文の用語と、動いているものの名前
前半がこの資料の言葉と技術用語、後半が実際に稼働しているリソースの名前です。本文では初出のときに短い注釈を付けていますが、途中から読んだ場合はこちらを参照してください。
技術用語Terms
はじめにこの資料の言葉、続いて技術の正式名です。正式名は本文で初出のときにも 1 行の説明を添えています。
- BoxBox
- 案件や取引先ごとの共有単位。メンバーとロール（Viewer / Uploader / Editor / Owner）を持ちます。ファイルもフォルダも必ずどれかの Box に属し、Box の外へは出ません。
- 監査ログAudit Log
- 「誰が・いつ・何をしたか」を 1 行ずつ残した記録。追加しかできず、更新も削除もできません。この資料で扱う 3 つの読み口（全社の監査ログ・Box のアクティビティ・退避分の取り出し）は、すべてこの 1 本を読んでいます。
- アクティビティActivity
- Box のメンバーが見る業務の履歴。監査ログのうち、その Box に関係し、かつ出してよいと決めた項目だけを日本語の文にして見せたものです。
- アラートAlert
- アプリ自身の判定で「これは異常だ」と決めた事象の 1 行。29 種あり、重大度（重大 / 警告）と状態（未対応 / 対応中 / 解決済み / 無視）を持ちます。
- 起票Raise
- アラートの行を新しく作ること。同じ事象が続いている間は起票しないので、行が立つのは「新しく起きた」または「規模が増えた」ときです。
- 検知器Detector
- 5 分ごとに決まった数を数え、しきい値を超えていればアラートを起票する処理。6 本あり、互いに独立して動きます。「起きたこと」ではなく「起きていないこと」を見つけるのが役割です。
- しきい値Threshold
- 異常と判定する境目の数値。「30 分超」「80% 超」のように種別ごとに決まっており、判定の材料になった実測値はアラートの自由項目に残ります。
- システム管理者System Admin
- 全社の管理画面を開ける役割。Box のロールとは別の軸で、Box の中身に対する権限を自動的に得るわけではありません。
- 伏せ字Masking
- メールアドレスの一部を隠して表示すること。画面にも CSV にも同じ規則を通すので、どちらか片方だけ生のまま出ることがありません。
- PostgreSQLPostgreSQL
- データベース管理システム。記録もアラートも取り出しの台帳も、すべてここに入ります。
- Row Level Security行レベルのアクセス制御
- 「どの行を読めるか・書けるか」を、テーブル単位ではなく行ごとにデータベース自身が判定する仕組み。アプリケーションの側で条件を書き忘れても、範囲外の行は返りません。
- SECURITY DEFINERSECURITY DEFINER
- 呼び出した人ではなく定義した人の権限で動く関数。呼び出す側に直接の読み取り権限を与えずに、関数が許した形の結果だけを返せます。
- パーティションPartition
- 1 つの大きなテーブルを、条件で分けた複数の小さなテーブルとして持つ仕組み。監査ログは月ごとに分けており、書き込みは最新の月にだけ当たります。
- pg_partmanpg_partman
- パーティションの作成と切り離しを自動化する拡張機能。先の月を前もって作り、古い月を別のスキーマへ移します。移すだけで、消しません。
- pg_cronpg_cron
- データベースの中で定期処理を回す拡張機能。この資料では、週次のパーティション整備を起動する 1 本だけが登録されています。
- COPY ... TO STDOUTCOPY ... TO STDOUT
- 問い合わせの結果を CSV などの形で流し出す PostgreSQL の命令。アプリケーションが全行を抱えずに済むため、行数が増えても使うメモリが変わりません。
- cursor ページングKeyset Pagination
- 「何件目から」ではなく「この行の次から」で続きを取る方式。読んでいる間に行が増えても、重複や取りこぼしが起きません。続きの位置は、中身の読めない印として渡します。
- gzipgzip
- データを圧縮する方式。取り出した CSV も、退避する月の記録も、この形で保管します。
- crc32ccrc32c
- データから短い検査値を計算する方式。保管先が返す値と手元の値を突き合わせることで、途中で壊れていないことを確かめられます。
- Cloud StorageObject Storage
- ファイルを置くためのクラウドの保管先。置き場（バケット）ごとに保管の性質と寿命の規則を設定します。
- Archive クラス ／ Standard クラスStorage Class
- Cloud Storage の保管の種類。Archive は長く安く置く代わりに取り出しに費用がかかり、Standard はすぐ読み書きする用途向けです。退避した月は Archive、取り出した CSV は Standard に置きます。
- オブジェクトライフサイクルLifecycle Rules
- 置き場ごとに「何日経ったら消す」を設定する仕組み。消す処理をアプリケーション側に持たせません。
- 署名付き URL（V4）Signed URL
- 期限つきで 1 つのファイルだけを取れる URL。API はファイルの中身を通さず、この URL を発行するだけです。V4 は署名の方式の版を指します。
- Cloud RunCloud Run
- コンテナを要求に応じて起動・増減させる実行環境。API と画面のアプリケーションがここで動きます。
- Cloud Run JobsCloud Run Jobs
- 要求を待たずに、決められた処理を最後まで走らせて終わる実行環境。定期処理はここで動きます。
- Cloud SchedulerCloud Scheduler
- 指定した時刻や間隔で処理を起動する仕組み。5 分ごとの検知や、月次の退避を起動します。
- Cloud MonitoringCloud Monitoring
- クラウド側の数値を観測して記録・通知する仕組み。6 つの検知器のうち 1 つは、ここから配信できなかったメッセージの数を読みます。
- Cloud LoggingCloud Logging
- ログを集約し、内容に一致したときに通知する仕組み。アプリのログは重大度を独自の欄に入れているため、絞り込みの条件は本文の側で書きます。
- Pub/SubPub/Sub
- 処理のきっかけを非同期に運ぶ仕組み。送る側は宛先を知らず、トピックへ載せるだけです。
- デッドレターDead Letter
- 受け取り側が繰り返し処理に失敗したメッセージの退避先。ここに溜まっている数が、検知の対象になります。溜めておける期間には上限があります。
- Next.jsNext.js
- 画面を作るためのフレームワーク。Box の画面も管理画面もここで動きます。
- HonoHono
- API を作るための軽量なフレームワーク。経路ごとに、ログイン確認や権限確認を通す配線を組み立てます。
- PrismaPrisma
- データベースの定義と変更手順を管理する仕組み。月ごとの分割・条件つきの索引・行レベルのアクセス制御は表現できないため、その部分は手書きの SQL で補います。
- ZodZod
- 入力と出力の形を定義して検証する仕組み。同じ定義を画面と API の両方から参照します。
- TanStack QueryTanStack Query
- 画面からのデータ取得と、その結果の保持・再取得を扱う仕組み。自動更新や、操作後に必要な範囲だけを取り直す動きを担います。
- nuqsnuqs
- 画面の状態（絞り込みやページ）を URL に持たせる仕組み。URL を渡せば同じ表示を再現できます。
- GoGo
- プログラミング言語。日次で Drive とアプリの状態を突き合わせる処理と、ファイルの検査サービスがこの言語で書かれています。
- ResendResend
- メールの配送サービス。届かなかった通知（バウンス）の記録も返ってくるので、その率が検知の材料になります。
- RFC4180RFC4180
- CSV の書式を定めた標準。区切り記号や引用符の扱い、改行を含む値の書き方が決まっています。
- UTF-8 BOMByte Order Mark
- ファイルの先頭に付ける短い印。これがあると、表計算ソフトが文字コードを取り違えずに開けます。
- VitestVitest
- 自動テストの実行環境。純粋な関数の単体テストと、実際のデータベースを使った結合テストの両方をここで回します。
- PlaywrightPlaywright
- ブラウザを実際に操作して確認する自動テストの仕組み。画面の表示と操作を通しで確かめます。
稼働リソースRunning Resources
本文に名前で出てくるもののうち、実際に動いているサービス・ジョブ・保管先・テーブル・関数です。
- matsuba-apiCloud Run
- API のアプリケーション。業務の処理と同じ流れの中で記録を書き、監査ログ・アクティビティ・アラートの読み出しもここが返します。
- matsuba-webCloud Run
- 画面のアプリケーション。Box のアクティビティタブも、アラートの運用画面もここが返します。
- matsuba-batchCloud Run Jobs
- 定期処理の実行環境。1 つの実行ファイルに処理を束ね、起動時の引数で振り分けます。この資料に出てくる処理はいずれもこの中にあります。
- dlq-monitorWorker
- 5 分ごとに動く検知の処理。6 つの検知器と、アラートのメール配送のレーンを持ちます。6 つは互いに独立して動き、1 つの失敗で残りが止まりません。
- audit-log-exportWorker
- 大きい CSV の取り出しを引き受ける処理。台帳に積まれた依頼を取り、データベースに CSV を組み立てさせて圧縮し、保管先へ置きます。
- audit-log-partition-rotatorWorker
- 月次で動く退避の処理。切り離された月を CSV にして保管先へ置き、行数と検査値を突き合わせてから元の月を捨てます。突き合わせに失敗したものは捨てません。
- matsuba-sync-batchCloud Run Jobs（Go）
- 日次で Drive とアプリの状態を突き合わせる処理と、週次の存否確認。ここで気づいた異常も、同じ 1 つのアラートのテーブルへ書きます。
- scannerCloud Run（Go）
- アップロードされたファイルを検査するサービス。ウイルスの検出・内容の不一致・整合性のエラーは、この処理の中でその場でアラートになります。
- matsuba-batch-dlq-monitorCloud Scheduler
- 検知の処理を 5 分ごとに起動する登録。
- matsuba-batch-audit-log-partition-rotatorCloud Scheduler
- 退避の処理を月次で起動する登録。週次のパーティション整備と重ならないよう、起動の時刻をずらしています。
- 監査エクスポートバケットBucket
- 記録に関わるファイルの保管先。既定は Archive クラスで、用途ごとに 2 つのプレフィクスに分かれています。
- exports/Prefix
- 取り出した CSV の置き場。Standard クラスを指定し、7 日で自動的に消えます。
- audit-archive/Prefix
- 退避した月の記録の置き場。Archive クラスで無期限に残ります。
- audit_logsTable
- 監査ログの本体。月ごとのパーティションで持ち、追加しかできません。
- audit_archiveSchema
- 25 ヶ月を超えて切り離された月の置き場。同じデータベースの中の別の区画で、ここに移っただけでは消えていません。退避が済んで突き合わせが取れた月だけが、ここから捨てられます。
- audit_partition_archivesTable
- 退避の台帳。どの月を・いつ・どこへ置き、行数と検査値がいくつだったかを 1 行ずつ残します。
- app_alertsTable
- アプリ独自のアラートの本体。種別・重大度・状態・説明文・自由項目・発生回数を持ち、4 系統すべての起票元がここへ書きます。
- box_activity_for_memberFunction
- Box のメンバー向けにアクティビティを返す関数。閲覧者を引数に取らず接続情報から判定し、出してよい項目だけに絞った結果を返します。メンバーが監査ログを直接読む経路はありません。