Data Model
drop.mov API のコアとなるデータ構造と、それらの関係性について説明します。
Entity Relationship
Core Entities
Media Group
メディアファイルをまとめるコンテナです。
| Field | Type | Description |
|---|---|---|
id | UUID | 一意識別子 |
name | string? | グループ名（任意） |
created_by | UUID | 作成者のユーザーID |
created_at | timestamp | 作成日時 |
updated_at | timestamp | 更新日時 |
deleted_at | timestamp? | 削除日時（ソフトデリート） |
特徴:
- 1つ以上の Media Source を含む
- Manager Token で管理操作を行う
- Share (Viewer Token) を通じて共有
Media Source
アップロードされた元のメディアファイルを表します。
| Field | Type | Description |
|---|---|---|
id | UUID | 一意識別子 |
group_id | UUID | 所属する Media Group |
original_name | string | 元のファイル名 |
content_type | string | MIMEタイプ |
size | number | ファイルサイズ（バイト） |
extension | string | ファイル拡張子 |
status | enum | 処理状態 |
expires_at | timestamp | 有効期限 |
created_by | UUID | アップロードしたユーザー |
Status の遷移:
| Status | Description |
|---|---|
uploading | アップロード中 |
uploaded | アップロード完了、処理待ち |
processing | メディア処理中（トランスコード等） |
completed | 処理完了、再生可能 |
failed | 処理失敗 |
Media Output
Media Source から生成された出力ファイル（トランスコード済み動画、サムネイルなど）。
| Field | Type | Description |
|---|---|---|
id | UUID | 一意識別子 |
source_id | UUID | 元の Media Source |
kind | enum | 出力の種類 |
path | string | S3 上のパス |
content_type | string | MIMEタイプ |
metadata | object | 追加メタデータ |
Output Kind:
| Kind | Description |
|---|---|
hls_master | HLS マスタープレイリスト |
hls_variant | HLS バリアント（解像度別） |
thumbnail | 代表サムネイル |
thumbnail_start | 開始時点のサムネイル |
thumbnail_end | 終了時点のサムネイル |
waveform | 音声波形データ |
Share (Viewer Token)
メディアグループへのアクセス権を表す共有リンク。
| Field | Type | Description |
|---|---|---|
id | UUID | 一意識別子 |
group_id | UUID | 対象の Media Group |
viewer_token | string | アクセストークン |
name | string? | 共有リンクの名前 |
can_download | boolean | ダウンロード許可 |
can_view_comment | boolean | コメント閲覧許可 |
can_post_comment | boolean | コメント投稿許可 |
expires_at | timestamp? | 有効期限 |
revoked_at | timestamp? | 無効化日時 |
Comment
メディアに対するコメント。タイムスタンプ付きコメントやスレッド形式に対応。
| Field | Type | Description |
|---|---|---|
id | UUID | 一意識別子 |
source_id | UUID | 対象の Media Source |
user_id | UUID | 投稿者 |
content | string | コメント本文 |
timestamp_seconds | number? | 動画内のタイムスタンプ（秒） |
parent_comment_id | UUID? | 親コメント（返信の場合） |
関連エンティティ:
- Reaction: コメントへのリアクション（emoji）
- Attachment: コメントに添付された画像やスクリーンショット
Access Control
Manager Token
Media Group に対する完全な管理権限を持つトークン。
Manager Token → Media Group (1:1)できること:
- グループ情報の取得・更新・削除
- Share の作成・更新・無効化
- Media Source の削除
- すべてのコメント操作
Viewer Token
共有リンクを通じたアクセス権限。権限は設定可能。
Viewer Token → Media Group (N:1)権限マトリクス:
| 操作 | 基本 | can_download | can_view_comment | can_post_comment |
|---|---|---|---|---|
| グループ情報取得 | ✓ | |||
| メディア再生 | ✓ | |||
| ダウンロード | ✓ | |||
| コメント閲覧 | ✓ | |||
| コメント投稿 | ✓ |
Lifecycle
メディアのライフサイクル
コメントのライフサイクル
API Endpoint Mapping
| Entity | Create | Read | Update | Delete |
|---|---|---|---|---|
| Media Group | POST /user/groups | GET /manager | PATCH /manager | DELETE /manager |
| Media Source | POST /user/upload/* | (via Group) | - | DELETE /manager/source/{id} |
| Share | POST /manager/share | GET /manager/shares | PATCH /manager/share/{id} | DELETE /manager/share/{id} |
| Comment | POST /viewer/{id}/comment | GET /viewer/{id}/comment | PATCH /viewer/{id}/comment/{cid} | DELETE /viewer/{id}/comment/{cid} |