機能
@nocobase/app-plugin-file は、アプリのデータベースと Drive を基盤にした、ファイルの Repository、アップロードのルートのヘルパー、クライアントのサービスを提供します。アバター、添付ファイル、ドキュメントのライブラリーに使います。
ファイルのテーブル、業務との関連、ディスク、画面はアプリが用意し、再利用できるファイルの操作はプラグインが提供します。
シナリオと例
例：注文の添付ファイル
添付ファイルのコレクションを作成し、アップロードと照会の操作を公開し、それらを注文の詳細に接続して、業務との関連を保ちます。編集できるアップロード、一覧、サムネイル、プレビューのコンポーネントには、UI Library の component-ui のソースをインストールします。
DOCX、XLSX、PPTX はブラウザーでローカルにレンダリングできます。古い Office や OpenDocument のプレビューのフォールバックには、インターネットからアクセスできる URL が必要で、アプリのセッションを使って非公開のファイルを開くことはできません。
開発用のプロンプト（アプリのディレクトリで作業するコーディングエージェント向け）：
Files を使って、注文の非公開の添付ファイルを追加してください：アップロード、一覧、プレビュー。
マイグレーションでコレクションを作成し、Drive のディスクを設定し、操作とポリシーを宣言してください。
メタデータとファイルの中身の両方を、注文のアクセスのチェックで保護してください。既定の公開の
コンテンツのルートは非公開のダウンロードではありません。メタデータとオブジェクトの後片付けは
別に定め、拒否されるアップロード、認可されていないダウンロード、失敗したプレビューをテストしてください。完了の条件認可されたユーザーが注文の添付ファイルをアップロードして読み取れ、拒否されたユーザーはメタデータの照会もファイルの中身のダウンロードもできないこと。
主な仕組みと実装
以下は、この例での組み込みの領域と、想定される画面の変化です。開発作業を記述したもので、実際のファイル構成はアプリに合わせてください。
| 組み込みの領域 | コードまたは設定の変更 | 画面と動作の変化 |
|---|---|---|
| データベースのマイグレーションと Drive の設定 | 添付ファイルのフィールドとストレージを定義する | メタデータとストレージの所有を保存する |
| ファイルのルートと注文との関連 | 操作、ポリシー、保護された非公開のコンテンツを宣言する | 一覧とダウンロードに業務上のアクセスを適用する |
| 注文の詳細の画面 | アップロード、一覧、プレビュー、エラーを組み込む | 操作のフィードバックとともに添付ファイルを追加する |
前提条件
両方のランタイムを登録したあと、アプリは次のことを行う必要があります。
- Drive のディスクを設定します。ファイルストレージ を参照してください。
- マイグレーションで業務のファイルのコレクションを作成します。
/serverのdefineFileRepositoryApiRoutes()を使い、リソース名、コレクション、ディスク、コンテンツのパス、操作、policyを宣言します。
プラグインは、ファイルのテーブルも管理ページも作成しません。必須のフィールドは、id、disk、key、filename、ext、mimeType、size、createdAt、updatedAt です。contentUrl はレスポンスで導き出されます。
アップロードとアクセス
アプリが宣言した attachments リソースの場合：
| 機能 | 宣言されるエンドポイント |
|---|---|
| 1 件をアップロードする | POST /api/attachments/uploadOne |
| 複数をアップロードする | POST /api/attachments/uploadMany |
| メタデータを照会する | POST /api/attachments/findMany などの宣言した Repository の操作 |
| 内容を読み取る | 設定した accessPath。たとえば /uploads/attachments/<uuid>.<ext> |
公開されるのは、列挙した actions だけです。アップロードは policy.create に従い、create: false では拒否されます。アップロードのリクエストは任意の業務のフィールドを受け付けません。必要な値は、サーバー側のポリシーの既定値や、同等のアプリの処理で用意してください。
/client から clientFileRepositoryManagerToken を解決し、manager.repository('attachments') を呼び出します。サーバー側の対応するものは、/server の serverFileRepositoryManagerToken です。
AI 開発の制約と検証
プラグイン固有の開発の制約
- コンテンツのルートとメタデータの認可は別々に確認してください。既定の accessPath は Repository のポリシーの外にあります。
- 宣言したアップロードのフィールドだけを受け付け、業務上の所有は、クライアントが送った任意の注文 ID からではなく、サーバーで解決してください。
- サイズの上限、失敗後のメタデータとオブジェクトの状態、非公開のダウンロード、削除の方針を検証してください。deleteOne はオブジェクトの後片付けではありません。
内容と削除の境界
ヘルパーが生成する accessPath のコンテンツのルートには認証がなく、Repository の policy の外にあります。非公開の添付ファイルには、アプリが所有する保護されたコンテンツのパスが必要です。メタデータの照会を制限するだけでは、ファイルの中身は保護されません。
stream は内容を返し、redirect にはストレージが公開または署名付きの URL に対応している必要があります。既定のディスクを変えても、既存のファイルは移動しません。deleteOne はメタデータを削除しますが、物理的なオブジェクトは削除しません。
アップロードの上限、拒否される書き込み、メタデータとオブジェクトの整合性、内容へのアクセス、プレビューのフォールバックを検証します。関連：Repository のデータ API、プラグインを管理する。
これらはあなたの組み込みの検収の要件であり、実機での検証が完了したことを示すものではありません。実際の変更、実行したチェック、未検証の項目をエージェントに報告させてください。プロジェクトのガイダンス、スキル、共通のチェックについては アプリの開発を続ける と テスト を参照してください。
出典：公開のプラグインの入口と実装。