リビジョンファイルの生成

design_versions.jsonとは？

design_versions.jsonは、デザインバージョンオブジェクトの配列を含むJSONファイルです。各オブジェクトはチャンクIDとそのリビジョンカウント値を持ちます。

データ構造

[
  { "chunk_id": <デザインバージョンのchunk_id>, "revision_count": <現在のデザインバージョンのrevision_count値> },
  { "chunk_id": <デザインバージョンのchunk_id>, "revision_count": <現在のデザインバージョンのrevision_count値> },
  ...
]

例:

[
  { "chunk_id": 12345, "revision_count": 5 },
  { "chunk_id": 67890, "revision_count": 12 },
  { "chunk_id": 11223, "revision_count": 3 }
]

各配列アイテムには以下が含まれます：

• chunk_id: データベースからのデザインバージョンのchunk_idフィールド
• revision_count: データベースからの現在のデザインバージョンのrevision_count値

なぜ必要なのか？

3Dデスクトップアプリは、このファイルを使用してローカルキャッシュを管理し、デザインバージョンを再ダウンロードするタイミングを判断します。

キャッシュ管理フロー

1. 初回: 3Dアプリがデザインバージョンをダウンロードし、ローカルにキャッシュします
2. 2回目以降の起動: 3Dアプリがdesign_versions.jsonをチェックします
3. revision_countが変更された場合: アプリがデザインバージョンを再ダウンロードします（新しい変更が利用可能）
4. revision_countが変更されていない場合: アプリがキャッシュ版を使用します（より高速な読み込み）

どこでアクセスできるか？

直接S3 URL

https://app-catalog-rdesign.s3.amazonaws.com/design_versions.json

このURLにブラウザから直接アクセスして、現在のファイル内容を確認できます。

AppVersion APIレスポンス

ファイルのURLはAppVersion APIレスポンスでも提供されます：

{
  "design_versions_url": "https://app-catalog-rdesign.s3.amazonaws.com/design_versions.json",
  ...
}

3DアプリはこのAPIフィールドからURLを動的に取得します。

いつファイルが生成されるのか？

再生成が必要なタイミング

以下の場合にdesign_versions.jsonを再生成してください：

• 新しいデザインバージョンが公開されたとき
• 既存のデザインバージョンが更新されたとき（revision_countが変更された）
• デザインバージョンがアクティブ化/非アクティブ化されたとき
• デザインバージョンの一括更新後

ファイルの生成方法

管理設定ページへのアクセス

1. 管理ダッシュボードにログインします
2. **管理設定（Admin Settings）**に移動します
3. **「design_versions.jsonを生成」**ボタンを見つけます

生成プロセス

生成ボタンをクリックすると、システムは以下を実行します：

1. 取得: revision_countがNULLでないすべてのアクティブなデザインバージョンを取得
2. 抽出: 各デザインバージョンからchunk_idフィールドを抽出
3. 構築: JSONデータ構造を構築（chunk_id → revision_countのマッピング）
4. アップロード: 生成されたファイルをAWS S3にアップロード
5. 公開: S3 URLで利用可能にする

データのフィルタリングルール

システムは、以下のすべての条件を満たすデザインバージョンのみを含めます：

• ✅ ステータスがアクティブ
• ✅ revision_countフィールドがNULLでない
• ✅ chunk_idフィールドが存在する

技術仕様

ファイル形式

• 形式: JSON
• Content-Type: application/json
• エンコーディング: UTF-8
• 構造: chunk_idとrevision_countフィールドを持つオブジェクトの配列

S3ストレージの詳細

• バケット: app-catalog-rdesign
• オブジェクトキー: design_versions.json
• アクセス: パブリック読み取り
• CDN: CloudFront経由で配信（設定されている場合）

データベースクエリロジック

生成プロセスは以下のようなクエリを実行します：

SELECT chunk_id, revision_count 
FROM design_versions 
WHERE status = 'active' 
  AND revision_count IS NOT NULL
  AND chunk_id IS NOT NULL

トラブルシューティング

問題：3Dアプリが更新されたデザインバージョンをダウンロードしない

考えられる原因:

1. 更新後にdesign_versions.jsonが再生成されていない
2. データベースでrevision_countがインクリメントされていない
3. S3ファイルのアップロードに失敗した
4. CDNキャッシュがクリアされていない（CloudFrontを使用している場合）

解決方法:

1. データベースでrevision_countがインクリメントされていることを確認
2. 管理設定からdesign_versions.jsonを再生成
3. S3を確認してファイルがアップロードされたことを確認
4. 該当する場合はCDNキャッシュをクリア
5. S3 URLを直接ダウンロードしてテスト

問題：ファイル生成に失敗する

考えられる原因:

1. AWS S3認証情報が無効または期限切れ
2. S3バケットの権限が不足している
3. データベース接続の問題

解決方法:

1. HerokuのAWS認証情報の環境変数を確認
2. S3バケットの権限（PutObject）を確認
3. アプリケーションログでエラーメッセージを確認
4. 問題が解決しない場合はバックエンドチームに連絡

関連システム

デザインバージョン管理

• デザインバージョンはdesign_versionsテーブルで管理されます
• 各更新時にrevision_countフィールドをインクリメントする必要があります
• アクティブで、revision_countがNULLでないデザインバージョンのみが含まれます

3Dデスクトップアプリとの連携

• アプリは起動時にAppVersion APIからdesign_versions_urlを取得
• JSONファイルをダウンロードして解析
• ローカルキャッシュのrevision_countとファイルの値を比較
• 変更されたデザインバージョンのみを再ダウンロード

AWS S3

• ファイルはapp-catalog-rdesignバケットに保存されます
• 3Dアプリのダウンロードにはパブリック読み取りアクセスが必要です
• アップロードは生成ボタンによって自動的に処理されます

ベストプラクティス

1. 定期的な更新

2. 生成後の検証

ファイルを生成した後：

1. S3 URLから直接ダウンロード
2. ファイルが有効なJSONであることを確認
3. 更新されたデザインバージョンが含まれていることを確認
4. revision_countがデータベースと一致することを確認

3. コミュニケーション

ファイルを再生成する際：

• 関連するSlackチャネルでチームに通知
• 含まれる変更を文書化
• 参照用にタイムスタンプを記録

4. モニタリング

定期的に以下を監視してください：

• ファイルのアクセス可能性（S3 URLが200 OKを返す）
• ファイルサイズ（急激な変化は問題を示す可能性）
• 最終更新日（最後の生成と一致するはず）

今後の改善予定

関連ドキュメント

内部ドキュメント

• システムアーキテクチャ概要
• メンバー・プラン体系

外部ドキュメント

• AWS S3ドキュメント
• デザインバージョン管理ガイド（作成予定）

更新履歴

• 2026年1月5日: 初版作成