共有クラス / Forms SDK

MintJams Commerce は、サーバーサイドの共有クラス（Groovy）と、フォーム用のForms SDK（クライアント JS）を提供します。繰り返し現れる処理を 1 箇所に集約し、各スクリプト・各フォームは自分の業務ロジックに集中できます。

共有クラス（commerce.*）

  • 配置: content/WEB-INF/classes/commerce/<Name>.groovy（package commerce）
  • 取り込み: import commerce.Money のように import
  • 呼び出し: すべて静的メソッド（状態を持たない）。例 Money.format(total)
  • 方針: クラス内ではスクリプトのグローバルを使わず、session / log / config を引数で受け取る。エラー方針は「純粋（呼び出し側が処理）」か「防御的（捕捉してログ）」を明示

変更したクラスはワークスペースのデプロイで反映されます。

主なクラス（抜粋）

クラス 役割
Money 金額の解析・整形（toNumber / format）
Jcr JSON ドキュメントの読み書き（getOrCreateFile / readMap / toJson）
SimpleYaml 依存なしの簡易 YAML 読み取り（parse）
Notifications / NotificationMessage / NotificationChannel 多チャネル通知（Slack/Discord/Teams/LINE/Webhook/Email）。チャネル非依存のメッセージを構築して配信
ReviewReasons 注文・返金スクリーニングの「レビュー理由」記述子（render は通知用、フォームは i18n で描画）
Orders / Refunds 注文・返金ペイロードの解釈
ShopifyAdmin / ShopifyWrite Shopify Admin API（トークン・GraphQL）と書き戻し（在庫・価格・公開・メタフィールド）
Pim 商品情報のオーバーレイ（多言語・リッチ説明・メタフィールド）
Reconciliation CMS↔Shopify のドリフト検出と修復
Inventory / InventoryRules / SalesVelocity / Replenishment 在庫しきい値・販売速度・自動発注
Locations / Allocation 多拠点在庫と引当計画
Backorders / Events / Customers / Checkouts 入荷待ち・イベント取り込み・CRM・カゴ落ち
Catalog / Pages Storefront 向けの公開投影
Health / Alerts / TaskSla / WorkflowStatus / Reports / Dashboard 監視・アラート・SLA・状態書き込み・レポート・集計

例

import commerce.Jcr
import commerce.Money

def order = Jcr.readMap(repositorySession, "/content/commerce/orders/raw/2026/06/order_123.json")
def total = Money.format(Money.toNumber(order.total_price))

Forms SDK（forms-sdk.js）

Shopify のタスクフォームが共有するクライアント側 SDK です。フォームとホスト（Webtop）間の通信、i18n、テーマ/ロケール処理、ライフサイクルを引き受け、フォームは業務ロジックだけを書きます。

読み込みと初期化

<script src="./forms-sdk.js?v=1"></script>

const sdk = window.createTasksForm();
  • グローバルに window.createTasksForm と window.TasksFormSDK を公開
  • ICU エンジン（intl-messageformat）は SDK 内で動的 import され、translate() / formatMessage() から利用
  • フォーム iframe は allow-same-origin なしで動くため、classic <script> で読み込みます（ESM import は CORS で阻まれるため）

ライフサイクルとイベント

  • sdk.start() / sdk.stop() — 開始 / 後始末
  • sdk.on(type, fn) — 'context' / 'localization' / 'theme' / 'standalone' / 'ready' を購読
  • sdk.whenReady() — ICU エンジンの準備完了
sdk.on('context', p => this.handleContext(p))
   .on('localization', loc => this.applyLocalization(loc))
   .on('ready', () => { this.i18n.revision++; })
   .start();

RPC（ホスト操作）

postMessage の詳細は隠蔽され、名前付きメソッドで呼び出します（抜粋）。

  • ユーザー: getCurrentUser() / getUser(username)
  • 開始モード: getProcessDefinition() / startProcess({ variables, businessKey })
  • タスク: getTask() / getTaskWithVariables() / setTaskVariables(...) / completeTask(variables?)
  • 割り当て: claimTask() / unclaimTask() / setAssignee(assignee)
  • CMS: getNode(path) / listChildren(path, {first, after}) / setNodeProperty(path, name, value) / readNodeText(path)
  • i18n: getI18nMessages(prefix?)

i18n と整形（純粋）

  • translate(messages, locale, id, params, fallback) / formatMessage(template, locale, params)
  • formatNumber(value, localization) / formatMoney(value, localization) / formatDate(value, localization)
  • ノード読み取り補助: getProp(node, name) / getStringProp(node, name) / readYamlScalar(yamlText, key)

SDK は UI のリアクティブ状態を持ちません。localization と i18n はフォーム側の data() に保持し、'ready' で再描画します。