概要
テナントの利用者が Drive にファイルをアップロードし、一覧・更新・削除・ダウンロードする機能である。Markdown の本文に書いた KEY-N をタスクに結び付け、タスクへ手動で添付することもできる。アクセスの規則とストレージはDrive の概要に書き、判断の理由は Drive の決定の記録に集める。フォルダはフォルダと共有、容量はクォータ、プロジェクトのドキュメント画面はドキュメントに書く。
振る舞い
一覧
GET /v1/tenants/{tenant_id}/drive/files のクエリは次のとおりである。total は絞り込み後の件数である。
| クエリ | 型 | 既定 | 内容 |
|---|---|---|---|
folder_id |
UUID? | フォルダで絞る。省略時はルート | |
mime_type |
string? | MIME タイプの前方一致。text/markdown は text/markdown で始まる MIME(text/markdown; charset=… など)にも一致し、text/ のように末尾 / なら種別全体に一致する |
|
q |
string? | ファイル名の部分一致(ILIKE、大文字小文字を区別しない)。200 文字を超えると 400 |
|
sort |
string | created_at_desc |
created_at_desc / name_asc / updated_at_desc。それ以外は 400。同順位は id 昇順 |
limit |
u32 | 50 | 取得件数。1..=200 に補正する。0 は 1、200 超は 200 になる |
offset |
u32 | 0 | オフセット |
mime_type と q の % _ \ は字義どおりに扱い、LIKE のワイルドカードにしない。
アップロード
POST /v1/tenants/{tenant_id}/drive/files は multipart/form-data を受け取り、作成した DriveFile を 201 Created で返す。
| フィールド | 必須 | 内容 |
|---|---|---|
file |
必須 | ファイルのバイナリ |
name |
任意 | 表示名。省略時は元ファイル名で、どちらも無ければ 400 |
folder_id |
任意 | アップロード先フォルダの UUID |
処理と制限の規則は次のとおりである。
- フィールドの順序は問わない。
fileはストリームのままストレージへ流し、DB への登録は全パートを読み終えてから行う。登録に失敗したらストレージから消す folder_idがfileより前に届いた場合だけ、本文を流す前にフォルダの存在と書き込み権限を確かめて早く落とすmime_typeは、ソースコードの拡張子の上書き表(.tsなど)、申告されたContent-Type、ファイル名からの推定の順で決める- 最大ファイルサイズは
UPLOAD_MAX_SIZE_MB(既定 100 MB)である。ファイル本体に対する上限で、ちょうどのサイズは受理する - リクエスト本文全体には、multipart の境界とヘッダーの分として 64 KiB を足した上限を掛ける
- MIME タイプは全種類を許可する
- 空ファイル、
fileパートなし、fileパートが 2 つ以上は400 Bad Requestを返す
S3 では次の順に処理する。
- クライアントが
POST /v1/tenants/{tenant_id}/drive/files(multipart)を送る - バックエンドが multipart のストリームを受信する
object_storeで単一 PUT または multipart upload を実行する- DB に
drive_filesの行を登録する。storage_keyのみを保持する - 応答に
/v1/drive/files/{id}/contentをurlとして組み立てて返す
名前の変更と移動
PATCH /v1/tenants/{tenant_id}/drive/files/{id} は name で名前を変更し、folder_id に UUID を渡すとそのフォルダへ移動する。folder_id の省略は配置を維持し、明示的な null はドライブ直下へ移動する。移動元・移動先の権限が必要で、移動に合わせて project_id も更新する。
本文の更新
PUT /v1/tenants/{tenant_id}/drive/files/{id}/content は { "content": "更新後の本文" } を受け取り、更新後の DriveFile を 200 OK で返す。
- 対象は
text/*、+json/+xml、JSON・JavaScript・YAML などの許可されたテキスト系 MIME である。対象外は400 Bad Requestを返す - 空文字列は許可する
- UTF-8 のバイト数がファイルサイズ上限を超える場合、または差し替え後のテナント使用量がクォータを超える場合は
413を返す - 新しいストレージキーへ保存してから DB を更新し、成功後に旧キーの削除を試みる
If-Match ヘッダーで楽観ロックできる。
- 値は
DriveFile.etag(ダブルクォート込み)をそのまま渡す - カンマ区切りの複数指定はどれか 1 つの一致で通り、
*は常に一致する - 弱い ETag(
W/"...")はW/を外して比べる(TASK-336) - 一致しなければ
412 Precondition Failed(precondition-failed)を返し、本文は変えない - 比較はファイル行のロック取得後に行うので、同じ ETag を持った並行更新は片方だけが通り、もう片方は
412になる - ヘッダーを省略した場合は無条件に上書きする(後勝ち)
- 応答の
etagは更新後の値である
ETag
DriveFile.etag は全ファイル API の応答に載る本文の ETag である。値はダブルクォート込みで、ETag ヘッダーと同じ文字列である。
| 行の状態 | 値 |
|---|---|
content_hash あり |
"sha256:<content_hash>"(強い ETag)。例は "sha256:2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae" |
content_hash なし(導入前の行) |
"ts:<updated_at の Unix ミリ秒>-<size>" |
本文の更新で updated_at が変わるので、導入前の行も If-Match で楽観ロックできる。本文を一度更新するとハッシュの形式に切り替わる。名前変更・移動では content_hash は変わらず、ハッシュ形式の ETag も変わらない。
配信
GET /v1/drive/files/{id}/content は本文を 200 OK で返す。?token={share_token} を付けると公開リンクのトークンで配信する。誰が取得できるかはDrive の認可の節に書く。
Content-Typeをmime_typeから設定するContent-Disposition: attachmentを常に設定し、ブラウザ上で同一オリジンのコンテンツとして実行させない- API 共通ミドルウェアが
X-Content-Type-Options: nosniffを全応答に設定し、宣言したContent-Type以外への MIME sniffing を禁止する - ストレージバックエンドの
get_stream()でストリーミング配信し、メモリに全展開しない ETag(DriveFile.etagと同じ値)とLast-Modified(updated_atを RFC 7231 の HTTP-date で秒精度)を付けるIf-None-Matchが現在の ETag に一致すれば304 Not Modifiedを本文なしで返し、304にもETagを付ける。ストレージは読まない。カンマ区切りの複数指定と*も可で、弱い ETag はW/を外して比べるIf-Modified-Sinceは解釈しない
タスクへの添付
Drive のファイルは既存のタスクへ添付できる。添付は中間の行の作成・削除で、解除しても Drive のファイル本体は削除しない。
- 添付できるのは同じテナントの一般ファイル、または対象タスクと同じプロジェクトのファイルである。別テナント・別プロジェクトのファイルは
403 Forbiddenを返す - 同じファイルの二重添付は
409 Conflictを返す - 添付の解除は、添付を作成した利用者またはテナントオーナーに限る
- 添付には由来
source(manual/body)があり、応答にも載る - 本文から付いた
bodyの行へPOSTするとmanualに昇格して200 OKを返す bodyの行のDELETEは409 Conflictを返す。本文を編集して参照を外す
規則の全体はタスク拡張のファイル添付に書く。
本文からのタスク参照
mime_type が text/markdown のファイルは、アップロード(POST .../drive/files)と本文の更新(PUT .../drive/files/{id}/content)のたびに本文の KEY-N を拾い、task_attachments へ source = 'body' で結び付ける。DB の更新と同じトランザクションで行う。名前変更・移動では本文を読み直さない。
抽出と結び付け先の規則は次のとおりである。
- 結び付けは
write:taskを持つ場合だけ行う。セッションは常に持つ。write:driveだけの PAT では保存そのものは通し、同期を飛ばして既存のbody行にも触れない - 抽出は GitHub 連携と同じ
service::forge::task_refsを使う。キーは大小文字不問で、Closesなどのキーワードは無視する - 拾う前にフェンスコードブロック(
```/~~~)とインラインコードの中身を落とす。閉じられていないフェンスは末尾まで落とす。インラインコードは行内でだけ対にする - 解決はファイルのテナント内のプロジェクトだけで行う。見つからない参照・削除済みタスクは捨てる
- 結び付け先は手動の添付と同じ範囲である。テナント一般ファイル(
project_idが NULL)はテナント内のどのプロジェクトのタスクにも結ぶ。プロジェクトファイルは同じプロジェクトのタスクにだけ結び、別プロジェクトの参照はリンクにせず黙って捨てる - 結び付けるのは、保存した利用者が入れるプロジェクトのタスクだけである。テナントオーナーは全プロジェクトに入れる。入れないものは黙って捨てる
- 1 ファイルあたり、本文に現れた順で最初の 200 件の一意な参照までとする。解決できない参照も数える。200 件に達した時点で走査を止め、超えた分は捨てる
行の更新の規則は次のとおりである。
- 今回の集合にあって行が無ければ
bodyで作る。manualの行は書き換えない。今回の集合に無いbodyの行は消し、manualの行は残す - 消すのも、保存した利用者が入れるプロジェクトの
body行と削除済みタスクの行だけである。入れないプロジェクトへのbody行は残す - プロジェクトファイルから別プロジェクトのタスクへの
body行は、保存者が入れるかに関わらず消す - ファイルをプロジェクトのフォルダへ移すと、移動と同じトランザクションで、移動先のプロジェクトの外のタスクへの
body行を消す。PATCH .../files/{id}のfolder_idと、フォルダの移動で配下のproject_idが変わる場合の両方が対象である。manualの行と、テナント一般のフォルダへ移した場合の行は残す
GET /v1/tenants/{tenant_id}/drive/files/{id}/tasks は、ファイルに結び付いたタスク(manual と body の両方)を返す。呼び出し側が入れないプロジェクトのタスクと削除済みタスクは含めない。
データ
drive_files の列は次のとおりである。
| 列 | 型 | 制約 | 説明 |
|---|---|---|---|
id |
UUID | PK | |
name |
VARCHAR | NOT NULL | ファイルの表示名(元ファイル名) |
size |
BIGINT | NOT NULL | バイト数 |
mime_type |
VARCHAR | NOT NULL | application/octet-stream など |
storage_type |
VARCHAR(16) | NOT NULL | Rust 側では enum。s3 または local |
storage_key |
VARCHAR | NOT NULL | ストレージ固有のキー(UUID v4)。S3 の key またはローカルの相対パス |
tenant_id |
UUID | NOT NULL, FK tenants CASCADE | |
project_id |
UUID | NULL 可, FK projects CASCADE | フォルダの project_id を非正規化した値。ファイルのフォルダ移動時に再設定する |
uploader_id |
UUID | NOT NULL, FK users | |
folder_id |
UUID | NULL 可, FK drive_folders SET NULL | |
created_at |
TIMESTAMPTZ | NOT NULL DEFAULT now() | |
updated_at |
TIMESTAMPTZ | NOT NULL DEFAULT now() | |
content_hash |
VARCHAR(64) | NULL 可 | 本文の SHA-256(hex)。アップロードと本文の更新で設定し、名前変更・移動では変えない。導入より前の行は backfill せず NULL のまま |
project_id がセットされているときは folder_id も非 NULL でなければならない。DB の CHECK 制約(project_id IS NULL OR folder_id IS NOT NULL)と entity の before_save の両方で強制する。url の列は持たず、API の応答を作るときに URL を組み立てる。
列の定義は m20260520000000_initial_schema.rs、content_hash は m20261016005000_drive_files_content_hash.rs、task_attachments.source は m20261016010000_task_attachments_source.rs にある。
API
ファイルのエンドポイントは次のとおりである。
| メソッド | パス | 説明 |
|---|---|---|
| GET | /v1/tenants/{tenant_id}/drive/files |
ファイルの一覧 |
| POST | /v1/tenants/{tenant_id}/drive/files |
ファイルのアップロード |
| GET | /v1/tenants/{tenant_id}/drive/files/{id} |
ファイルのメタデータの取得 |
| PATCH | /v1/tenants/{tenant_id}/drive/files/{id} |
ファイルの更新(名前・フォルダ移動) |
| PUT | /v1/tenants/{tenant_id}/drive/files/{id}/content |
編集可能なテキストファイルの本文の更新 |
| DELETE | /v1/tenants/{tenant_id}/drive/files/{id} |
ファイルの削除 |
| GET | /v1/tenants/{tenant_id}/drive/files/{id}/tasks |
ファイルに結び付いたタスクの一覧 |
| GET | /v1/drive/files/{id}/content |
ファイルの内容の配信(ローカル・S3 プロキシ) |
| GET | /v1/drive/files/{id}/content?token={token} |
公開リンクのトークンによるファイルの配信 |
タスク添付のエンドポイントは次のとおりである。
| メソッド | パス | スコープ | 説明 |
|---|---|---|---|
| GET | /v1/tenants/{tenant_id}/projects/{project_id}/tasks/{id}/attachments |
read:task |
添付の一覧 |
| POST | /v1/tenants/{tenant_id}/projects/{project_id}/tasks/{id}/attachments |
write:task |
{ "drive_file_id": "uuid" } を添付する |
| DELETE | /v1/tenants/{tenant_id}/projects/{project_id}/tasks/{id}/attachments/{attachment_id} |
write:task |
添付を解除する |
認可
アクセスの規則とエンドポイントごとのスコープはDrive の認可の節に書く。このページに固有の規則は次のとおりである。
| 操作 | 誰が | スコープ |
|---|---|---|
| 添付の解除 | 添付を作成した利用者またはテナントオーナー | write:task |
| 結び付いたタスクの一覧 | メタデータの取得(GET .../drive/files/{id})と同じ判定を通る人。閲覧できなければ 403 / 404 |
read:drive と read:task |
body 行の同期 |
保存した利用者 | write:task がなければ同期を飛ばす |
画面
タスク詳細の添付欄(TaskAttachments.vue)から Drive のファイルを添付する。OpenAPI クライアント用の定義と PAT のスコープ表示がある。
入力欄への貼り付け
本文の入力欄にファイルを貼り付ける(Ctrl+V / ⌘V)と、Drive へアップロードして本文に 1 行を入れる。
| 項目 | 内容 |
|---|---|
| 対象の入力欄 | タスクの説明、タスク作成ダイアログの説明、ドキュメントの本文、コメントの入力欄、コメントの編集 |
| 保存先 | 入力欄があるプロジェクトのルートフォルダ。タスクの添付と同じ場所で、読める人はプロジェクトのメンバーである |
| 上限 | 貼り付け専用の上限は無い。サーバーの UPLOAD_MAX_SIZE_MB と容量に従う |
| 複数のファイル | 1 回の貼り付けのファイルを並行でアップロードし、貼り付けた順に 1 行ずつ入れる |
クリップボードにファイルがあり、text/plain と text/html の少なくとも片方が空のときだけファイルとして扱う。表計算や文書のアプリのように文字と HTML と画像を同時に載せる貼り付けは、文字として貼る。
本文に入る行は次のとおりである。URL は API の相対パス /v1/drive/files/{id}/content で、web は描画するときに /api を前に足す。
| ファイル | 本文に入る行 | 表示 |
|---|---|---|
MIME タイプが image/ で始まる、または拡張子が heic heif |
 |
画像 |
拡張子が mp4 mov webm m4v |
 |
動画のプレイヤー |
拡張子が mp3 wav m4a ogg caf aac |
 |
音声のプレイヤー |
| それ以外 | [名前](URL) |
ダウンロードのリンク |
名前に含まれる Markdown の記号(\ [ ] * ` < & ~ と、語の端の _)は \ を前に付けて入れ、名前が強調・取り消し線・タグとして解釈されないようにする。
描画の規則は次のとおりである。
- 書き換えるのは、URL が
/v1/drive/files/{UUID}/contentに完全一致する画像とリンクだけである。クエリやパスが続くもの、絶対 URL は書き換えない - 動画と音声は、画像の記法の名前(
alt)の拡張子で見分ける。本文の URL には拡張子も MIME タイプも無い。拡張子の大文字と小文字は区別しない。名前から拡張子を消すと画像として描く - プレイヤーは自動再生しない
- ブラウザが画像・動画・音声を読み込めなかったときは、その場でダウンロードのリンクに替える。HEIC は Safari 以外で、
.movは中身のコーデックによって表示できないことがある - リンクの中に置いた画像(
[](リンク先))は URL を替えるだけで、プレイヤーにもダウンロードのリンクにもしない - ダウンロードのリンクには
download属性を付ける
アップロードの間と失敗時の扱いは次のとおりである。
- アップロードの間は、貼り付けた位置に「アップロード中…」とファイル名を表示する。この表示は本文に含まれず、下書きにも保存にも入らない
- アップロードの間は、その入力欄の送信・保存・作成を止める。表示の「取り消し」でアップロードを中断でき、中断すると送信・保存・作成をまた行える
- 終わると、表示があった位置に行を入れる。その間に前後へ文字を入力していても位置は追従する
- 失敗すると、同じ位置に理由と「再試行」「取り消し」を表示する。複数のうち一部だけ失敗したときは、成功した行だけを入れ、失敗したファイルだけを再試行の対象に残す
- 入力欄を閉じる、別のタスクやスレッドへ切り替える、本文が外から差し替わる、表示を含む範囲を消す(元に戻す操作で消える場合を含む)、のいずれかで進行中のアップロードを中断し、結果を捨てる。送信・保存・作成はまた行える
- 行の入れ替え(Alt+↑ / Alt+↓)と前後の字の入れ替え(Ctrl+T)では中断しない。表示は元の行の同じ位置に付いていく
失敗の理由は次の文言で表示する。
| 条件 | 文言 |
|---|---|
| 0 バイトのファイル | 空のファイルは貼り付けできません |
| ルートフォルダの取得に失敗(通信の切断を含む) | 保存先を読み込めませんでした |
| プロジェクトにルートフォルダが無い | プロジェクトの保存先が見つかりません |
413(サイズまたは容量の超過) |
ファイルがサイズ上限または保存容量を超えています |
| それ以外の失敗(通信の切断を含む) | ファイルをアップロードできませんでした |
未実装と既知の制限
- 貼り付けたファイルは、本文から行を消しても、結果を捨てた場合でも Drive に残る
- 貼り付けたファイルはタスクの添付にならない
- アップロードの間に行の入れ替えを元に戻す操作をすると、表示のある行が消されて入れ直され、アップロードを中断することがある
- 配信が Range リクエストに対応していない(TASK-565)。対応するまで、Safari は動画と音声を再生できずダウンロードのリンクに替わり、他のブラウザでも未読み込みの位置へシークできない
- 貼り付けたファイルを変換しない。HEIC の画像や HEVC の動画は、表示できないブラウザではダウンロードのリンクになる
- 画像のサムネイル生成が無い
- ファイルの全文検索が無い
- Drive のページ、ファイルブラウザ、クォータ、共有の画面が無い
- 個別削除は DB の削除後のストレージエラーを無視する。孤児オブジェクトの扱いはDrive の未実装と既知の制限に書く
ファイルブラウザの導入時の設計
ページもコンポーネントもまだ無い。以下は導入時の設計で、URL は URL 仕様に合わせた予定のものである。
| URL | 内容 |
|---|---|
/{tenant}/drive |
ドライブのトップ(ルートフォルダ) |
/{tenant}/drive/{folder_id} |
フォルダ内 |
上部にパンくず、左にフォルダツリーと新規フォルダのボタン、右に検索欄、アップロード、表示切り替え、ファイル一覧を置く。
コンポーネントの構成は次のとおりである。
| コンポーネント | ファイル | 説明 |
|---|---|---|
DrivePage |
src/pages/@tenant/drive/+Page.vue |
ドライブ全体 |
DriveFolderPage |
src/pages/@tenant/drive/@folderId/+Page.vue |
フォルダ内 |
DriveSidebar |
src/components/drive/DriveSidebar.vue |
フォルダツリー |
DriveFileGrid |
src/components/drive/DriveFileGrid.vue |
ファイル一覧(グリッド) |
DriveFileList |
src/components/drive/DriveFileList.vue |
ファイル一覧(リスト) |
DriveUploadButton |
src/components/drive/DriveUploadButton.vue |
ドラッグ&ドロップ対応 |
DriveFileCard |
src/components/drive/DriveFileCard.vue |
ファイルカード(グリッド用) |
DriveFileDetail |
src/components/drive/DriveFileDetail.vue |
詳細パネル(サイドシート) |
主な操作は次のとおりである。
- アップロードは、ボタンのクリックまたはエリアへのドラッグ&ドロップで行い、プログレスバーを表示する
- フォルダの作成は、サイドバーの「+ 新しいフォルダ」ボタンからインラインで入力する
- ファイルの詳細は、ファイルカードのクリックで右サイドシートに表示し、URL をコピーできる
- 削除は、右クリックメニューまたは詳細パネルの削除ボタンから確認ダイアログを経て行う
