モダンECプラットフォーム「ec-plus1」構造完全ガイド

このドキュメントでは、最新のECプラットフォーム「ec-plus1」がどのような設計思想で構築され、膨大なデータや金流をどのように制御しているのかを解き明かします。エンジニアリングの複雑さをビジネス価値へと変換する、本システムの心臓部を詳しく見ていきましょう。

1. プラットフォームの全体像：マルチテナントという設計思想

「ec-plus1」の根幹にあるのは、「マルチテナント方式」という考え方です。これは1つのシステム基盤を共有しながら、数多くの独立したブランド（事業者）がそれぞれの店を運営する構造を指します。

効率と独立性の両立

この方式の最大のメリットは、システムのアップデートを一度行うだけで全テナントに最新機能を提供できる効率性と、ブランド間のデータが完全に分離されている安全性にあります。ブランドAの顧客データがブランドBに漏れることは構造上あり得ません。

ユーザー体験を最大化する「入り口」の使い分け

本プラットフォームは、URLルーティングによって技術スタックを明確に使い分けています。

• 購入者用フロントポータル（Next.js）
  • URL: www.cocotown.jp
  • 役割: 高速なSSR（サーバーサイドレンダリング）やSSG（静的サイト生成）を駆使し、購入者のUXを最優先します。ここでの「表示の速さ」は、直接的にコンバージョン率（購入率）の向上に直結するビジネス上の生命線です。
• 出店者・管理者用画面（Laravel Blade）
  • URL: {brand}.cocotown.jp
  • 役割: 複雑な在庫操作や売上集計を、サーバーサイドで確実に処理します。保守性とデータ整合性の安定を重視し、ブランドごとのドメイン解決を行うことでセキュアな運営環境を提供します。

このように、パフォーマンスが求められる「表舞台」と、堅牢性が求められる「舞台裏」を分けることで、ブランドごとの資産を守りつつ、最高の買い物体験を実現しています。

--------------------------------------------------------------------------------

2. 3つの立場から見る「利用目的」と「機能」の対比

システムを正しく理解するには、「誰が何のために使うのか」という視点が不可欠です。ec-plus1では、主に以下の3つの役割が定義されています。

各アクターに見える世界（権限）を厳格に分離することは、単なる機能制限ではありません。それは、出店者が誤って他店の情報を操作したり、一般ユーザーが管理機能に触れたりするリスクを排除し、プラットフォーム全体の信頼性を担保するための防波堤なのです。

--------------------------------------------------------------------------------

3. 商品モデルの核心：「商品（Product）」と「SKU」の使い分け

データの階層構造を理解することは、ECシステムの心臓部を理解することと同義です。ec-plus1では、情報を「コンセプト」と「実体」に切り分けて管理しています。

データの定義と責務

• 商品（Product）: 「コンセプト」としての存在。名前、説明文、カテゴリ、メイン画像など、消費者が抱くブランドイメージを司ります。
• SKU（ProductSku）: 「販売の最小単位」。価格、原価、在庫数、バリエーション（色・サイズ）など、商取引に必要な実数データを保持します。

「真実」はどこにあるのか

この構造において、在庫や価格の**「真実」は常にSKU側にのみ存在します。** 例えば、Tシャツという「商品」に対して「ホワイト/Mサイズ」や「ブラック/Lサイズ」という複数の「SKU」が紐付きます。在庫管理を正確に行うためには、この最小単位でのデータ保持が絶対条件となります。

過去と現在を繋ぐ「Bridge for the Past」

システム内部には、products.price や products.stock というカラムが存在しますが、これらはあくまで表示速度を稼ぐための**「レガシー・キャッシュ（写し）」**です。

• 厳格なルール: これらのキャッシュカラムを UPDATE 文などで直接書き換えることは厳禁です。
• syncLegacySkuSnapshot() の役割: このメソッドは、最新のSKUデータ（真実）を古いUIや高速表示用のキャッシュへと翻訳して届ける「架け橋」として機能します。

この「SKU正本主義」を徹底することで、どれほど複雑なバリエーション展開を行っても、在庫の不整合や価格の誤表示を防ぐことができるのです。

--------------------------------------------------------------------------------

4. 注文から入金まで：データのジャーニー

1つの注文が発生した瞬間から、データは「お金」と「モノ」の流れを記録するために姿を変えていきます。

1. Checkout: Stripe連携による決済。この時点で在庫の「引き当て」が行われ、商品が確保されます。
2. Order Sync: 決済成功後、注文データから「売上・手数料・返金」を自動計算。
3. Finance Record: transactions テーブルへの記帳。ここでは「EC売上（Income）」だけでなく「決済手数料（Expense）」や「EC返金（Expense）」が即座に分離して記録されます。
4. Reconciliation（消込）: 入金見込み額と、実際に銀行へ振り込まれた額を突き合わせるプロセス。

経営判断を支える「Net売上の定義」

ec-plus1において、経営の羅針盤となる指標は「Net売上」です。

• 定義: Net Sales = 注文合計(total) - 返金累計(refund_amount)
• 精度: 平均客単価（AOV）の算出において、Net売上が0円以下の注文は除外されます。

また、消込作業においては、振込手数料などの影響で発生する微差を「入金差額調整（Income Variance Adjustment）」として記録する仕組みが備わっています。このように、決済から記帳、消込までが自動連携されることで、経営者は常に「手元に残る真実の利益」を把握できるのです。

--------------------------------------------------------------------------------

5. プラットフォームの信頼を守る：監査ログと権限管理

大規模なシステムを安全に運用するためには、透明性の高い「証跡」と、緻密な「守り」の設計が不可欠です。

業務監査ログ（Audit Log）の設計

ec-plus1では、単なるシステムログとは別に、業務上の重要操作をすべて記録します。

• 5つの必須要素: 「誰が（Actor）」「いつ（Happened At）」「何を変えたか（Action: order.status_changed 等）」「どの経路で（Source: web, api, job, console）」「どの一連の処理で（Request ID）」を記録します。 これにより、万が一の数値不整合や誤操作が発生した際も、before/after の差分を比較して即座に原因を特定することが可能です。

厳格な権限マトリクス（RBAC）

スタッフの役割に応じ、実行可能なアクションを最小限に制限しています。

特に「商品の削除」や「ブランド設定の変更」などの取り返しのつかない操作は、オーナー（Owner）のみに限定されています。こうした「守り」の構造があるからこそ、事業者は安心してビジネスの拡大に集中できるのです。

--------------------------------------------------------------------------------

6. まとめ：学習者のための重要チェックリスト

ec-plus1の構造を理解するための最重要ポイントを振り返りましょう。

1. 多層構造の理解: 「メインドメイン（購入者）」と「サブドメイン（運営者）」の責務の違いを意識すること。
2. SKU正本主義の徹底: 在庫や価格の真実は常にSKUにある。products テーブルの数値はあくまでキャッシュである。
3. 一貫性と証跡: 決済からNet売上の算出、入金消込までが連動し、すべての変更は request_id と共に監査ログに刻まれる。

この構造をさらに深く学ぶためには、以下の詳細仕様書を確認することをお勧めします。

• product-model-spec.md：SKUと属性拡張の詳細設計。
• sales-operations-spec.md：売上定義と財務運用の詳細ルール。
• audit-log-spec.md：証跡記録の技術的実装方針。

「ec-plus1」は、これらの緻密な設計の積み重ねによって、信頼性の高いECビジネスの基盤を提供しています。