[Ken] デザインバージョン

デザインバージョンは、デザインファミリーの特定の構成または状態を表します。各バージョンには、デザインの視覚的表現を構成する3Dジオメトリ（メッシュ）とマテリアルエレメントが含まれています。

🔄

キーコンセプト

デザインファミリーが全体的な「製品」を表すのに対し、デザインバージョンは特定の実装を表します - その製品の異なる反復、更新、または構成のようなものです。

デザインバージョンとは？

デザインバージョンは、以下を含むデザインファミリー内の特定の構成です：

3Dジオメトリ - 実際の3Dメッシュアセットに関連付け
マテリアルエレメント - 実際のマテリアルアセットに関連付け
バージョン状態 - アクティブバージョンは現在使用可能なもの
デバッグモード - カタログで使用できない場合、バージョンはデバッグモード
マテリアルデフォルト構成 - これらのバージョンは、ルーム内でデフォルトマテリアル構成なしでアイテムをスポーンする際のデフォルトマテリアル構成として使用されます
リビジョン番号 - リビジョン番号はデザインバージョンのバージョン番号で、メッシュやマテリアルが更新されると増加します
チャンクシステム - デザインバージョンのチャンクIDとチャンクサイズ

現時点では、デザインファミリーごとに1つのアクティブバージョンのみが許可されています。

属性とメタデータ

デザインバージョンには、その利用可能性、アセット管理、デフォルトマテリアル構成を制御するメタデータが含まれています。

コア識別情報

デザインバージョンの基本識別子：

属性	タイプ	説明
`id`	文字列（18文字）	プライマリキー、Salesforce ID形式
`name`	文字列	バージョン名/識別子
`design_family_id`	外部キー	親デザインファミリーへの参照

例:

id: a40OQ000001Q78XYAS
name: "0.0"
design_family_id: a4fOQ000000g8yrYAA（MALAGAデザインファミリー）

バージョン状態

このバージョンの可用性と使用を制御：

属性	タイプ	説明
`active`	ブール値	このバージョンが現在アクティブかどうか
`debug`	ブール値	開発/テスト用のデバッグモードフラグ

アクティブバージョンの動作:

✅ デザインファミリーごとに一度に1つのアクティブバージョンのみ許可
✅ ルーム内にアイテムを配置する際にアクティブバージョンが使用される
✅ カタログと検索結果に表示

デバッグモード:

🔧 debug: true → バージョンはデバッグ/開発モードでのみ表示
🔧 debug: false → バージョンは本番環境で利用可能

🔄

単一アクティブバージョン

任意の時点で、デザインファミリーごとに1つのデザインバージョンのみがactiveとしてマークできます。これにより一貫したユーザーエクスペリエンスが確保され、どのバージョンを使用するかについての混乱が防止されます。

バージョン状態シナリオ:

シナリオ	active	debug	design_family.released_on_production	利用可能な対象
本番	`true`	`false`	`true`	すべてのユーザー
テスト	`true`	`true`	`false`	開発者のみ

チャンクシステム

アセットパッケージングと配信管理：

属性	タイプ	説明
`chunk_id`	文字列/整数	ロード用のアセットチャンクを識別
`chunk_size`	整数	チャンクのサイズ（バイト単位）
`revision_count`	整数	リビジョン/更新の数

目的:

チャンクシステムは以下によってアセット配信を最適化します：

関連アセットをまとめてグループ化
プログレッシブローディングを有効化
デルタ更新をサポート
帯域幅を効率的に管理

動作方法:

チャンクID: アセットをダウンロード可能なパッケージにグループ化
- 例：chunk_id: 1234 → チャンク1234内のすべてのメッシュとマテリアル
チャンクサイズ: 総アセットサイズを追跡
- ダウンロード進捗インジケーターに使用
- 帯域幅要件の見積もりに役立つ
- 例：chunk_size: 52428800（50MB）
リビジョンカウント: バージョン更新を追跡
- メッシュやマテリアルが更新されると増加
- Salesforceによるトリガー
- 例：revision_count: 5（5回目のリビジョン）

📦

アセットキャッシング

チャンクシステムはローカルキャッシングと連携します。revision_countが変更されると、アプリはキャッシュされたバージョンを使用する代わりに更新されたアセットをダウンロードすることを認識します。

デフォルトマテリアル構成

このバージョンが提供するデフォルトマテリアルを示すフラグ：

属性	タイプ	説明
`default_fabric`	ブール値	デフォルトファブリックマテリアルを提供
`default_paint`	ブール値	デフォルトペイントカラーを提供
`default_leather`	ブール値	デフォルトレザーマテリアルを提供
`default_wood`	ブール値	デフォルトウッド仕上げを提供
`default_metal`	ブール値	デフォルトメタル仕上げを提供
`default_glass`	ブール値	デフォルトガラスマテリアルを提供

目的:

これらのフラグは、明示的なマテリアル選択なしでルーム内にアイテムをスポーンする際に使用されるマテリアル構成を決定します。デザインバージョンに特定のデフォルトマテリアルフラグがtrueに設定されていない場合、システムは同じデザインファミリー内でそのフラグが有効になっている他のデザインバージョンを検索し、それらのマテリアルをデフォルトとして使用します。

例: マテリアルルックアップを持つソファ

デザインファミリー「MODULAR SOFA」に2つのバージョンがあるとします：

バージョンA: ベース構成

デザインバージョンA（id: a40OQ000001Q78XYAS）
├── default_fabric: false     ← デフォルトファブリック未構成
├── default_wood: true         ← 脚用のデフォルトウッドあり
├── default_leather: false
└── デザインバージョンエレメント:
    ├── オークナチュラル（wood）
    └── ウォールナットダーク（wood）

バージョンB: マテリアルライブラリ

デザインバージョンB（id: a40OQ000001Q78XYZB）
├── default_fabric: true       ← デフォルトファブリックを提供
├── default_wood: false
├── default_leather: false
└── デザインバージョンエレメント:
    ├── ベージュリネン（fabric）
    ├── グレーベルベット（fabric）
    └── ネイビーコットン（fabric）

マテリアル適用フロー:

バージョンAからソファをスポーンする場合：

脚: バージョンAはdefault_wood: true
- ✅ バージョンAのエレメントからマテリアルを使用
- 脚に「オークナチュラル」を適用
座面クッション: バージョンAはdefault_fabric: false
- 🔍 システムはdefault_fabric: trueのデザインバージョンを検索
- ✅ バージョンBを発見
- バージョンBのエレメントからマテリアルを取得
- 座面クッションに「ベージュリネン」（最初のファブリック）を適用

構成シナリオ:

すべてのデフォルトを持つ単一バージョン:

デザインバージョン: 完全構成
├── default_fabric: true
├── default_wood: true
├── default_leather: false
└── default_metal: false

結果: すべてのマテリアルがこのバージョンから提供される

分割構成（マテリアルルックアップ）:

デザインバージョン1: ジオメトリバリアント
├── default_fabric: false      → バージョン2を検索
├── default_wood: true          → 自身のマテリアルを使用
└── default_metal: false

デザインバージョン2: マテリアルライブラリ
├── default_fabric: true        → バージョン1にファブリックを提供
├── default_wood: false
└── default_leather: true       → レザーオプションを提供

結果: バージョン1はバージョン2のファブリック、自身のウッドマテリアルを使用

🔍

マテリアルルックアップメカニズム

デザインバージョンにデフォルトマテリアル構成が欠けている場合（default_*: false）、システムは同じデザインファミリー内でそのフラグがtrueである別のデザインバージョンを自動的に検索します。これにより以下が可能になります：

複数のジオメトリバリアント間での共有マテリアルライブラリ
集中マテリアル管理
バージョン間で一貫したデフォルトマテリアル

関係

関係	タイプ	説明
デザインファミリー	親	このバージョンが属するデザインファミリー
デザインバージョンメッシュ	子	関連3Dメッシュアセット
デザインバージョンエレメント	子	関連マテリアル/テクスチャアセット

システムメタデータ

監査証跡とシステム情報：

属性	タイプ	説明
`created_at`	タイムスタンプ	バージョン作成日時
`updated_at`	タイムスタンプ	最終変更日時

使用:

バージョンライフサイクルの追跡
キャッシュ無効化トリガー
アセットパイプラインとの同期
監査ログ

バージョンライフサイクル

バージョンの経時的な進化の理解：

新しいバージョンの作成

初期作成
- active: false、debug: true
- アセットがチャンクにアップロード
- revision_count: 1
テストフェーズ
- active: true、debug: true
- 開発者がテストに利用可能
- マテリアルデフォルトが構成される
本番リリース
- 以前のアクティブバージョンがactive: falseに設定
- 新しいバージョンがactive: true、debug: falseに設定
- デザインファミリーのreleased_on_productionフラグがtrueに設定、設定されていない場合、デザインファミリーはカタログに表示されません
- すべてのユーザーが利用可能に

バージョンの更新

メッシュやマテリアルが更新される場合：

リビジョンの増加
- revision_countが増加（例：5 → 6）
- updated_atタイムスタンプが更新
- リビジョンカウントファイルは手動トリガーまたは0時UTCに自動トリガーで更新
チャンク更新
- 同じchunk_idに新しいアセットがアップロード
- アセットが増減するとchunk_sizeが変更される可能性
キャッシュ無効化
- アプリがrevision_countの変更を検出
- 更新されたアセットを再ダウンロード
- キャッシュされたバージョンをクリア

⚠️

破壊的変更

マテリアルスロットやメッシュ構造を変更する主要な更新は、revision_countを更新するのではなく、新しいデザインバージョンを作成する必要があります。

重要: 新しいデザインバージョンがアクティブ化（activeに設定）されると、以前のデザインバージョンは非アクティブ化されます。古いバージョンは：

❌ カタログに表示されなくなります
❌ 新しいルームで使用できなくなります
❌ それを使用していた既存のルームから削除されます

これにより、すべてのルームが最新バージョンを使用することが保証されますが、互換性の問題が発生する可能性があります。新しいバージョンをアクティブ化する前に徹底的にテストしてください。