参照先から取得する値を保存する・保存しない

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

参照先の商品名などについて、取引時点の値を残すか、最新の値をその都度表示するかを選べます。同じ参照先から両方の項目を用意することもできます。

DBへ保存する場合も、取得した値そのものを残す方法と、取得先のレコードを指すキーを残し、その現在値を表示する方法を選べます。

使える関数の一覧、演算子、未設定値や丸めの規則、用途ごとの制約は関数と式の仕様を参照してください。

2. Wagby11で実現できること

2.1 取得時点の値と現在の値を比較する

商品「機材セットA」を選んで計算見積を保存します。「取得時の商品名」と「現在の商品名」は、どちらも機材セットAです。

計算商品の名称を「機材セットA 改訂版」へ変更して見積を開き直すと、取得時の商品名は以前の名称を残し、現在の商品名だけ変更後の名称になります。

参照する商品を変えずに見積を更新しても、保存用の名称は取り直しません。別の商品へ参照キーを変更した場合は、その商品の名称を新たに保存します。同じ参照先のまま更新のたびに同期したい場合は、追加の業務処理として指示します。

2.2 値を保存する・キーを保存する

ルックアップ項目をDBへ保存する場合、lookup.storeで保存内容を選べます。value（省略時）は商品名などの値そのものを、keyは取得先レコードの主キーを保存します。どちらも画面へ表示する項目は、lookup.fieldで指定します。

取引時点の名称や単価を記録として残したい場合は値保存、取得先を固定しながらその現在の名称を表示したい場合はキー保存が向いています。キー保存は、キーの数字をそのまま商品名欄に表示する設定ではありません。

2.3 保存内容と、保存の有無を分けて選ぶ

storeは「何を保存するか」、transientは「DBへ保存するか」を決めます。用途は次のように分けられます。

単に参照先の名称を表示したい場合は、非保存の表示用項目を使えます。非保存の場合はstoreの指定は不要で、指定してもDBにキーや値を保存するようにはなりません。

2.4 多段参照で保存したキーと、設定変更時の扱い

キー保存が保持するのは、最終取得先の主キーです。例えば、案件から顧客C001を選び、その会社ORG100を経由して会社名を取得する場合、キー保存の項目は会社のキーORG100を保持します。最初の顧客キーC001とは別です。

その後、同じ顧客C001の所属会社がORG200へ変わっても、保存済みの会社キーは標準処理ではORG100のままです。表示はORG100の現在の会社名を使います。一方、非保存の表示用項目は現在の経路をたどるため、ORG200の会社名を表示します。参照経路の指定は参照を複数段たどって値を取得するを参照してください。

保存用ルックアップは、値保存・キー保存とも、登録時と最初の連動元キーが変わったときに再取得します。同じ連動元キーのまま中間の参照先が変わっても、保存内容は自動で同期されません。保存済みキーの参照先が削除されると、表示値は空になります。

既存の保存項目をvalueからkeyへ変更する場合は、設定の変更だけでは済みません。保存済みの名称や金額を正しい参照キーへ変換し、DB列の型も合わせる必要があります。数値が保存されていても、それが参照キーと同じ意味とは限りません。変更前に、既存項目の変更とDB移行を確認します。

3. AIへの指示例

最小限の指示例

見積時点の商品名を残し、最新の商品名も別に表示してください。

AIは参照する商品、値を取得する項目、保存時点と再取得のタイミングを類推して補います。名称をマスター変更へ追従させるか、取引時の記録として残すかを分けて伝えると、保存方法を明確にできます。この短い指示だけで、次の詳細例と同じ仕様になるとは限りません。

より詳細な指示例

CalcQuote.itemIdからCalcItem.itemNameを参照してください。storedItemNameはreference-lookupのtransient:false、currentItemNameは同じlookupでtransient:trueにします。商品を機材セットAとして見積を保存し、商品名を機材セットA 改訂版へ変更して見積を再取得したとき、保存用は旧名、非保存は新名となることを確認します。同じ商品IDのまま見積を更新しても保存名を保持してください。
既存のモデル・主キー・項目・データ・権限を保持し、Wagby11のguide・referenceを確認してください。新規モデルには自動採番の主キーと予約属性version、必要なG_ADMINのCRUD権限を用意します。メニューと一般利用者向け操作マニュアルを更新し、設計情報の検証・コード生成・ビルドを完了してから起動し、画面と保存結果を確認してください。

参照先キーを保存する指示

最小限の指示例

見積には取得先の商品キーを保存し、そのキーに対応する現在の商品名を表示する項目も追加してください。

AIは商品を選ぶ項目と取得先、追加する項目名などを既存の定義から類推して補います。取得時点の商品名も残すか、現在の商品名だけが必要かを伝えます。この短い指示だけで、次の詳細例と同じ項目構成になるとは限りません。

より詳細な指示例

既存の計算見積CalcQuoteに、取得先キーを保持して現在の商品名を表示する項目を追加してください。
・出発点はitemId、取得先はCalcItem.itemNameとしてください。
・追加項目名は「キーで取得する商品名」、英語識別名はkeyedItemNameとしてください。
・lookup.storeをkey、transientをfalseとし、取得先商品の主キーを保存してください。画面にはitemNameの現在値を表示してください。
・既存の取得時点の商品名storedItemNameと、非保存の現在の商品名currentItemNameは保持してください。
・既存の保存項目を置き換えず、新しい項目として追加してください。
・登録時と商品キー変更時にキーを取得し、同じ商品キーのまま参照先名称を変えた場合は、値保存の項目は旧名、キー保存と非保存の項目は現在名になることを確認してください。
・既存の主キー、migration_id、権限、データを保持し、追加した列の型と表示値の違いを説明してください。
必要なguide・referenceを確認し、変更内容と確認結果を示してください。

4. 編集されるAppSchemaの例

以下は関連する定義の抜粋です。構文を覚えなくても、何から・いつ値を求め、保存するかをAIへ伝えられます。

entity:
  attributes:
    - name: 商品
      name_en: itemId
      type: reference
      fk: { entity: CalcItem, field: itemId }
    - name: 取得時の商品名
      name_en: storedItemName
      type: reference-lookup
      lookup: { source: itemId, field: itemName, store: value }
      transient: false
    - name: 現在の商品名
      name_en: currentItemName
      type: reference-lookup
      lookup: { source: itemId, field: itemName }
      transient: true
    - name: キーで取得する商品名
      name_en: keyedItemName
      type: reference-lookup
      lookup: { source: itemId, field: itemName, store: key }
      transient: false

標準の保存用ルックアップは、登録時と連動元の参照キー変更時に取得値を保存します。非保存のルックアップは表示時の現在値を取得します。値取得元は参照先のDB保存項目にします。

上の画面例は値保存と非保存の比較です。定義例では、それに加えてキー保存の項目も示しています。storeを省略した保存項目はvalueとして扱います。viaで会社へたどる場合も、同じlookupにstoreを指定し、最終取得先の値かキーかを選べます。

5. 参考資料

guide：ルックアップ

designer/docs/appschema/html/guide/08-rules/06-reference-lookup.html

guide：エンティティ属性タイプ

designer/docs/appschema/html/guide/03-model/02-fields.html

reference：entity（ルックアップ）

designer/docs/appschema/html/reference/06-entity.html