本文へ移動
Wagby11
マニュアルのグループを選ぶ

WAGBY11 MANUAL / 31

ファイル型の詳細

ファイル型のDB構造、実ファイルの保存先と命名方式、再生成で保持される外部設定、更新・削除時の扱いを説明します。

最終更新日:

補足・参考資料の小目次へ

1. このページで伝える機能

ファイル型は、業務データに添付資料や画像を持たせる項目です。DBには元ファイル名などの参照情報を保存し、ファイル本体はREST APIサーバーから読み書きできるファイルシステムへ保存します。ファイル項目の基本的な使い方は、ファイルを扱うも参照してください。

このページでは、DBと実ファイルの対応、保存先の変更方法、コード再生成後も保持する設定の置き場所を説明します。

2. Wagby11で実現できること

2.1 DBで管理する情報

1つのtype: file項目は、JavaではFileReferenceとして扱われ、DBでは4列に展開されます。ファイル本体をDBのBLOBへ格納する方式ではありません。DB物理名がATTACHMENTの場合の例です。

DB列内容型
ATTACHMENT保存ルートからの相対パス(relativePath)VARCHAR(1024)
ATTACHMENT_ORIGINAL_NAMEアップロード時の元ファイル名(originalFilename)VARCHAR(512)
ATTACHMENT_CONTENT_TYPEContent-Type(contentType)VARCHAR(255)
ATTACHMENT_SIZEバイト単位のサイズ(size)BIGINT

元ファイル名と保存ファイル名は別に扱います。画面表示やダウンロード名には元ファイル名を使い、DBには保存ルートの絶対パスやダウンロードURLを保持しません。

2.2 実ファイルの保存先

保存ルートを指定する設定はapp.storage.root-directoryです。これはSpring Bootの外部設定プロパティで、AppSchemaの構文ではありません。省略時は./data/filesで、REST APIアプリケーションの実行時カレントディレクトリを基準に解決します。

保存ルートの設定:/srv/wagby/files
DBの相対パス:dailyreport/quotationfile1/2026/11/abc123.pdf
実ファイル:/srv/wagby/files/dailyreport/quotationfile1/2026/11/abc123.pdf

必要なディレクトリは保存時に自動作成します。実行ユーザーが保存先を読み書きできるようにしてください。項目別に設定するfile_storageは、命名方式や容量・形式の制約を指定するもので、保存ルートの指定ではありません。

2.3 再生成で保持される外部設定

保存先の変更は、製品ルートのconfig/application.ymlへ記述します。この利用者設定ファイルはコード再生成の対象外です。restapi/src/main/resources/application.ymlを直接編集する必要はありません。

製品ルート/
├── config/
│   └── application.yml  ← 利用者設定
└── restapi/
    └── src/main/resources/application.yml

config/application.ymlに次を記述します。既に設定がある場合は、既存の内容を残して追加します。同じappキーがある場合は、その配下にまとめてください。

app:
  storage:
    root-directory: /srv/wagby/files

REST API側には、次の外部設定読み込みがあらかじめ用意されています。

spring:
  config:
    import: optional:file:${WAGBY_CONFIG_DIR:../config}/application.yml

標準起動スクリプトはrestapiをカレントディレクトリにするため、既定で隣のconfig/application.ymlを読み込みます。設定フォルダを別の場所に置く場合は、環境変数WAGBY_CONFIG_DIRにフォルダの絶対パスを指定します。環境変数の一覧は設定する環境変数を参照してください。

変更後はREST APIを再起動します。外部設定の変更だけなら、コード再生成や再ビルドは不要です。同じ項目を起動時のコマンドライン引数で指定している場合は、そちらが優先されます。保存ルートには絶対パスを指定すると、起動場所による違いを避けられます。

相対パスの保存ルートは、外部設定ファイルの置き場所ではなくREST APIの実行時カレントディレクトリが基準です。また、項目単位のマージはリストを要素ごとに追加する意味ではありません。このページの例は単一の保存先プロパティを上書きします。

2.4 保存ファイル名の方式

項目のfile_storage.filename_strategyで保存ファイル名の方式を選べます。省略時はgeneratedです。通常の生成コードでは、分類にモデルと項目を表すdailyreport/quotationfile1などを使い、保存時の日付による年月の下へ配置します。

方式保存ルート配下の構造特徴
generated{分類}/{年}/{月}/{UUID}{拡張子}元ファイル名の拡張子を引き継ぎ、本体の名前を生成します。
sanitized_original{分類}/{年}/{月}/{UUID}/{安全化した元ファイル名}禁止文字などを置換した名前を使い、一意のディレクトリで同名衝突を避けます。

安全化では、パス部分の除去、UnicodeのNFC正規化、禁止文字・制御文字の置換、末尾の空白・ピリオドの除去、Windows予約名の回避などを行います。いずれの方式も、表示用の元ファイル名は別途DBに保持します。

2.5 登録・取得・更新・削除

登録・更新ではmultipart/form-dataで業務JSONとファイルを送信します。元ファイル名はmultipartのfilenameから取得します。通常の一覧・詳細レスポンスは元ファイル名、Content-Type、サイズを返し、内部の相対パスは公開しません。

ファイルはGET /dailyreports/{id}/files/quotationfile1のような項目別APIから取得します。元ファイル名をダウンロード名に使い、通常のEntity参照と同じ認証・モデル権限・行権限を適用します。Entity、ファイル参照、実ファイルが見つからない場合は404として扱います。

操作扱い
登録新ファイルを保存し、参照情報をDBに登録します。
更新でファイル未送信、削除指定なし既存ファイルを維持します。
更新で新ファイル送信新ファイルへ置換し、旧ファイルはDBコミット後に削除します。
removeXxx: trueファイル参照をnullにし、旧ファイルはDBコミット後に削除します。
Entityの物理削除参照していた添付ファイルもDBコミット後に削除します。
Entityの論理削除DBの参照情報と添付ファイルを保持します。

置換ファイルと削除フラグの同時指定はエラーです。not_null: trueの必須ファイルも削除できません。更新で既存ファイルを維持する場合は再送不要です。

DBとファイルシステムは同じトランザクションへ参加しないため、補償処理で整合性を保ちます。DBがロールバックした場合は新ファイルを削除し、旧ファイルは残します。コミット後の削除がI/Oエラーになった場合はログへ記録されるため、孤立ファイルの確認・保守も必要です。

2.6 バックアップと配備環境

保存先の変更だけでは既存ファイルを移動しません。停止などで更新を止め、相対ディレクトリ構造を保って新しい保存ルートへファイルを移してから設定を変更します。DBの相対パスを書き換える必要はありません。

DBと実ファイルの両方を対応する時点でバックアップ・復元します。DBだけを復元しても添付ファイル本体は戻りません。保存先の容量とinodeも監視します。

AWS標準配備では、H2テスト構成は/opt/wagby/restapi/data/filesの一時領域、本番構成は既定で/mnt/wagby/filesのEFS領域へ保存します。本番ではEFSの/wagbyを/mnt/wagbyへマウントするため、EFS側の保存先は/wagby/files配下に対応します。

AWS配備では保存先を起動時に管理しており、利用者設定のapp.storage.root-directoryによる任意変更は制限されます。通常起動の外部設定例を、そのままAWS配備へ適用しないでください。H2テスト構成の更新では添付ファイルも初期化されるため、永続的な保管には本番構成を使います。

3. AIへの指示例

最小限の指示例

受付情報に添付資料のファイル項目を追加してください。実ファイルは /srv/wagby/files に保存し、保存先の設定は再生成後も保持してください。

AIは項目の英語識別名、画面上の配置、保存ファイル名の方式など、未指定の仕様を類推して補います。許可形式や容量、必須かどうかに条件がある場合は追加で伝えてください。最小限の指示だけで、次の詳細例と同じ仕様になるとは限りません。

より詳細な指示例

既存の受付情報モデルに、任意入力の「添付資料」(attachment)をファイル型で追加してください。
保存名はgenerated、最大10 MiB、許可するContent-Typeはapplication/pdfとします。
製品ルートのconfig/application.ymlへapp.storage.root-directory: /srv/wagby/filesを設定してください。
既存の外部設定は保持し、生成ソース内のapplication.ymlは直接編集しないでください。
登録・表示・取得、ほかの項目だけを更新した場合のファイル維持、置換・削除を確認してください。
DBには保存ルートからの相対パスと元ファイル名などが保存されること、コード再生成後も外部設定が保持されることを確認してください。

4. 編集されるAppSchemaの例

ファイル項目の定義例です。

entity:
  attributes:
    - name: 添付資料
      name_en: attachment
      type: file
      file_storage:
        filename_strategy: generated
        max_size_bytes: 10485760
        allowed_content_types:
          - application/pdf

file_storage自体の省略時も保存名はgeneratedです。max_size_bytesとallowed_content_typesの省略時は項目単位では制限しませんが、Spring Bootやリバースプロキシのリクエスト容量制限は別に適用されます。Content-Typeはmultipartの申告値で検証し、ファイル内容の形式判定やウイルススキャンは別途追加します。

保存先を指定するapp.storage.root-directoryはこのAppSchemaへ追加せず、前述のconfig/application.ymlへ記述します。

5. 参考資料

guide:エンティティ属性タイプ
designer/docs/appschema/markdown/guide/03-model/02-fields.md
reference:entity
designer/docs/appschema/markdown/reference/06-entity.md
AWS:Pipelineによるアプリ配置
aws-deployer/docs/deployment.md