Headless Commerce Orchestration · for MintJams CMS

在庫も、注文も、返金も。
自動で回して、
必要な時だけ、
そっと人へ。

MintJams Commerce は、Shopify の Webhook を受け取り、リポジトリに正規化し、BPMN ワークフローで処理する——ヘッドレスコマースのオーケストレーション層。しきい値を割った在庫、レビューが必要な注文、監査したい返金だけを、担当者のタスクと通知に変えます。MintJams CMS と同じ Docker イメージに同梱、あとは設定するだけ。

Dockerで起動する GitHub を見る →
✓ MIT License ✓ cms0 に同梱 ✓ Shopify 連携
⌁ localhost:8080/desktop
⋯
MintJams 仮想デスクトップ — BPMN Modeler・Tasks・BPM Console による在庫レビューワークフロー
⌁ localhost:8080/desktop
⋯
MintJams 仮想デスクトップ — EIP Modeler・EIP Console による Shopify データ連携
⌁ localhost:8080/desktop
⋯
MintJams 仮想デスクトップ — Commerce Dashboard の KPI カードとストアフロントプレビュー
Webhook 検証済み HMAC-SHA256
Manual Inventory Check · unassigned
オープンな標準と、実証された実装の上に
Docker
Shopify Webhooks
BPMN 2.0
EIP Routes
JCR 2.0
GraphQL Admin API
仕組み

ひとつの経路に、すべてが流れる。

Shopify からのイベントは、検証され、正規化され、ワークフローに乗り、必要なときだけ人へ。受け取りから通知まで、ひと続きのパイプラインで動きます。

SHOPIFY

イベント発生

商品更新・注文確定・返金など。Webhook が飛ぶ。

ENDPOINT

受信 & 署名検証

Groovy エンドポイントが HMAC-SHA256 で検証。

EIP ROUTE

取り込み & 正規化

共通の取り込み核へ。生ペイロードを保存。

JCR

現在状態として保存

版管理・全文検索・ACL を備えたリポジトリへ。

BPMN

ワークフロー判定

しきい値・スクリーニングを評価。自動か、人か。

HUMAN + NOTIFY

人のタスク & 通知

担当者へタスクを起票し、各チャネルへ通知。

全トピックを第一級イベントとして捕捉 失敗はバウンド付き自動リトライ + 手動リプレイ 同一対象の二重ワークフローは再入ガードで防止
プラットフォーム

受け取る・回す・知らせる。
運用の三拍子を、ひとつの基盤で。

外部 EC との接続も、業務プロセスも、人への引き渡しも。これまで別々だった仕掛けを、MintJams CMS の同じデスクトップの上に揃えます。

受け取る — イベント取り込み

すべてのトピックを単一の取り込み核へ。生ペイロードは保存され、いつでも再処理できます。

  • 署名検証付き Webhook 受信（HMAC-SHA256）
  • 多バックエンド対応 — 同じ封筒を投げれば下流は不変
  • イベントログ & リプレイ（重複ではなく再処理）

回す — 業務ワークフロー

BPMN 2.0 準拠のプロセスで在庫・注文・返金を判定。ルールに当たらないものは自動で通します。

  • 在庫アラート / 注文レビュー / 返金レビュー
  • 設定可能なスクリーニング（fail-open で安全に既定承認）
  • BPM Console と BPMN Modeler でライブ監視・即デプロイ

知らせる — 人のタスク & 通知

判断が必要なときだけ、担当者のタスクに。誰が引き取ったかまで追跡し、各チャネルへ通知します。

  • Tasks アプリで受け取り / チームへ割り当て / 完了
  • Slack・Discord・Teams・LINE・Email・汎用 Webhook
  • best-effort 配信 — 通知失敗は業務を止めない
01 — 在庫アラートツール

在庫が割れたら、
人の手に渡す。

Shopify の在庫がバリアントごとのしきい値を下回ると、手動レビュータスクを起票し、設定済みのチャネルへ通知。撃ちっぱなしのアラートではなく、誰がフォローを担うかまで追跡します。

01
しきい値設定タスク

初めて見る商品には、バリアント単位で「何個を切ったら警告するか」を担当者が決定。

02
Manual Inventory Check

在庫割れを検知して起票。担当者が状況をレビューし、対応済みにマーク。

03
再入ガード

処理中の商品が二重にワークフローを起動しないよう抑止。最新データは保存され続けるので取りこぼしなし。

⌁ localhost:8080/desktop
⋯
Tasks・BPMN Modeler・BPM Console による在庫レビューワークフローのスクリーンショット
02 — Shopify データ連携 & リプレイ

連携の中身を、
見える形で動かす。

取り込みは EIP ルートとして設計・デプロイ。生ペイロードを durable なイベントログに残すから、失敗イベントは自動リトライされ、どのイベントも手動でリプレイできます。書き戻しは Admin API でゲート付き。

01
source-agnostic な取り込み核

Shopify 固有はトピック→ルートの小さな表だけ。新しいバックエンドはアダプタを足すだけ。

02
EIP Console でライブ監視

ルートごとの成功 / エラー / 遅延を交換履歴とメトリクスで可視化。ボトルネックも一目で。

03
双方向同期（CMS → Shopify）

在庫・価格・公開状態を Admin API で書き戻し。dryRun と監査証跡付きで安全に。

⌁ localhost:8080/desktop
⋯
EIP Modeler・EIP Console による Shopify 連携ルートと交換履歴のスクリーンショット
03 — 運用監視 & ダッシュボード

プラットフォーム自身が、
自分を見張る。

業務ワークフローの外側で、Webhook 受信・ルート処理・Admin API 呼び出しを観測。KPI を 1 画面に束ね、劣化や滞留を検知したら同じ通知チャネルへ知らせます。

01
Commerce Dashboard

売上・在庫・予測・発注・タスク・連携健全性まで、リアルタイムの読み取り専用 KPI カード。

02
Integration Health Monitor

トピック別の成功 / エラー / レイテンシを観測し、劣化時にアラート。

03
Task SLA Monitor

滞留したレビュータスクを定期スキャンでエスカレーション。優先度を上げて通知。

⌁ localhost:8080/desktop
⋯
Commerce Dashboard — 売上・在庫・予測・連携健全性の KPI カード
04 — 設定 & 通知

設定は画面で、
保存は YAML で。

すべての設定は管理者専用の Commerce アプリから。Connection / Intake & sync / Inventory / Workflows / Storefront / Monitoring のグループ化されたサイドバーで編集し、ひとつの Save でまとめて永続化。接続情報と通知先は別ファイルに分けてあるので、API シークレットに触れずに通知先だけを管理できます。

01
グループ化された設定

各セクションが未保存マーカーを持ち、まとめて 1 つの Save で反映。

02
6 つ以上の通知チャネル

Slack・Discord・Teams・LINE・Email・汎用 Webhook を、それぞれ独立して有効化。

03
秘密と通知の分離

notifications.yml と shopify.yml を別管理。安全に運用を委譲。

⌁ localhost:8080/desktop
⋯
Commerce 設定コンソール — グループ化されたサイドバーと通知チャネル設定のスクリーンショット
05 — PIM / データプラットフォーム

商品情報を、CMS 側で
豊かに上書きする。

Shopify の商品に、多言語タイトル・リッチな説明・カスタム属性・メタフィールドを CMS 権威のオーバーレイとして付与。商品ノードに保存されるので、JCR の版管理・全文検索・ACL をそのまま継承します。Shopify ベース＋メタフィールド＋オーバーレイを合成した統一ビューで編集し、CMS 由来のメタフィールドは同期エンドポイント経由で書き戻し。

01
ローカライズドコンテンツ

ロケール別のタイトルと HTML 説明を、商品ごとに作り込み。

02
版管理つきオーバーレイ

商品ノードに保存し、履歴・全文検索・ACL を継承。安全に編集。

03
突合 & 帳票へ

同じミラーが、ドリフト突合や売上・監査エクスポートの土台にもなる。

⌁ localhost:8080/desktop
⋯
Commerce PIM — 商品のローカライズドコンテンツ編集と、結果が反映されるストアフロントプレビューのスクリーンショット
機能モジュール

はじめから、これだけ揃っています。

各機能は独立して設定でき、入力が無ければ穏やかに縮退します。必要な分だけ採用してください。

在庫アラート

しきい値割れを検知し、Manual Inventory Check を起票・通知。

注文レビュー

高額・リスク決済・大量数量などを審査し、要審査だけ人へ。

返金レビュー

金は動かさない監査 / 不正監視。注文の返金サマリも更新。

在庫インテリジェンス

動的しきい値・需要予測・自動発注で在庫切れを先回り。

バックオーダー

行単位の入荷待ちを FIFO で追跡し、入荷時に解放タスク。

PIM

多言語タイトル・説明・メタフィールドを版管理付きで上書き。

突合（Reconciliation）

CMS ミラーと Shopify を定期比較。ドリフトを検出・報告・自己修復。

帳票 & 監査エクスポート

売上と書き出し監査を JSON / CSV で。JCR の証跡から生成。

顧客 CRM

購入履歴から new / repeat / vip / at_risk / dormant に分類。

Commerce Dashboard

売上・在庫・予測・連携健全性を束ねる読み取り専用 KPI。

Integration Health

受信・処理・API 呼び出しを観測し、劣化時にアラート。

新しいバックエンドも

楽天 / BASE / 自社EC / ERP。同じ封筒を投げるアダプタを足すだけ。

背景

なぜ "オーケストレーション層" なのか?

EC 運用は、全部自動化すると取りこぼしが怖い。かといって全部手作業では回らない。MintJams Commerce は、その境界を設計可能にするために生まれました。

これまで

自動化か、手作業か

  • アラートは飛ぶが、誰が対応したかは追えない
  • 在庫・注文・返金の判断ルールがスクリプトに散らばる
  • 連携が落ちても、気づくのは問い合わせが来てから
  • バックエンドを変えると、配管をまるごと作り直し
MintJams Commerce で

自動で回し、必要な時だけ人へ

  • 判断が必要な瞬間だけタスク化し、担当者まで追跡
  • スクリーニングは YAML 設定。fail-open で安全に既定承認
  • 受信・処理・API を共通ダッシュボードで監視・アラート
  • 取り込み核は source-agnostic。新バックエンドはアダプタだけ
アイデンティティ & アクセス

admin では、動きません。

統合処理は無制限のスーパーユーザーではなく、専用のアイデンティティ・グループ・ACL を初回起動時に付与された、リポジトリ ACL に従う通常のプリンシパルとして動きます。書き込みは、プラットフォームが所有するパスにだけ追加されます。

SU
commerce-service-user
サインインできないサービスアカウント。EIP ルートや BPMN サービスタスクを runAs で実行する非対話の主体。
G
commerce-service-group
サービスユーザーが必要とする書き込み権限を束ねるグループ。
OP
commerce-operators
非 admin の運用担当へコマース管理を委譲。Identity Manager から実オペレーターを追加。
クイックスタート

Docker が動けば、
もう同梱されています。

Commerce 専用のイメージはありません。資産は mintjams/cms イメージに同梱済み。CMS を起動すれば、Commerce ツールも一緒に立ち上がります。

  • 01
    CMS コンテナを起動

    Commerce の資産は同じイメージに同梱。追加インストールは不要です。

  • 02
    ブラウザでアクセス

    http://localhost:8080 を開き、admin でサインイン。

  • 03
    Commerce アプリを開く

    Webtop メニューから Commerce を開いて連携を設定。

  • 04
    shopify.yml を設定

    Webhook の共有シークレットを登録。Admin API は任意で有効化。

bash — run MintJams CMS (Commerce bundled) 
docker run --rm \
  -p 8080:8080 \
  -e CMS_PUBLIC_BASE_URL=http://localhost:8080 \
  -v cms-repository:/data/repository \
  -v cms-secrets:/data/secrets \
  --tmpfs /opt/felix/tmp:size=512m,mode=0700 \
  mintjams/cms:latest

# → http://localhost:8080/ を開き、admin でサインイン
# → Webtop メニューから「Commerce」を開いて設定
commerce · bundled in mintjams/cms ● ready

Shopify から、その先へ。

取り込み核は Shopify を知りません。知っているのは小さなトピック→ルートの表だけ。新しいバックエンドは、同じ封筒（event_source / event_topic / event_id ＋ ペイロード）を核へ投げるアダプタを足すだけで、下流はそのまま動きます。

  • 楽天 / BASE / 自社EC / ERP — アダプタ 1 つで接続
  • 共有 Groovy クラス層に再利用ロジックを集約
  • 独自の通知チャネルや業務プロセスも追加可能
// backend adapters
Shopify
楽天
BASE
ERP
↓   同じ封筒を投げる   ↓
⌁
direct:commerce-ingest

source-agnostic な取り込み核 — 下流のワークフローは不変

FAQ

よくある質問

Shopify 以外のバックエンドでも使えますか?
はい。取り込み核 direct:commerce-ingest は source-agnostic です。event_source / event_topic / event_id ＋ペイロードという同じ封筒を投げるアダプタを足せば、楽天・BASE・自社EC・ERP などを下流変更なしで接続できます。現在同梱の実装は Shopify です。
導入に別途インストールは必要ですか?
不要です。Commerce の資産は cms0 と同じ mintjams/cms Docker イメージに事前デプロイ済み。CMS を起動すれば Commerce ツールも一緒に立ち上がり、あとは設定するだけです。
admin 権限で動くのですか?
いいえ。統合は commerce-service-user という専用の非対話プリンシパルとして動き、リポジトリ ACL に完全に従います。書き込みは /content/commerce など、プラットフォームが所有するパスにだけ追加されます。
通知はどこに送れますか?
Slack・Discord・Microsoft Teams・LINE・Email（SMTP）・汎用 Webhook に対応。各タスクが 1 つのメッセージを作り、有効な全チャネルへそれぞれの形式で配信します。配信は best-effort で、失敗しても業務プロセスは止めません。
Shopify Admin API は必須ですか?
Webhook の署名検証用シークレットは必須ですが、Admin API は任意です。有効化すると商品 Webhook のメタフィールド補完や、完了した Fulfill Order タスクの Shopify への書き戻しが行われます。無効なら Admin API 呼び出しは一切行いません。
ライセンスは?
MIT ライセンスです。ソースは github.com/mintjamsinc/commerce、ランタイム基盤は cms0、UI フレームワークは ichigo.js。なお本プロダクトは public preview 段階で、1.0 までに API や設定キーが変わる可能性があります。
クイックスタート

ECの運用を、
人の判断ごとデスクトップへ。

Docker ひとつで、Shopify 連携も業務ワークフローも、もう手の中に。

Dockerで起動する GitHub を見る →
docker run mintjams/cms:latest · MIT License · public preview