03. 実装仕様ポータル¶
Vendureバックエンドと Storefront の実装ドキュメントを横断的に参照できるハブです。開発フェーズで迷いがちな導線をカード形式で整理しました。
🚀 クイックリンク¶
| 🎯 目的 | 🔗 ドキュメント | 📝 補足 |
|---|---|---|
| Vendureの基本を理解したい | vendure-development-guide.md | GraphQL API、プラグイン、設定、開発環境 |
| Vendureの深い知識を得たい | vendure-handbook.md | アーキテクチャ、コアコンセプト、実践パターン |
| Vendure Money の単位を確認したい | vendure-money-units.md | 円単位と Vendure Money 値の変換ルール |
| Vendureのコアコンセプトを理解したい | vendure-core-concepts.md | ゾーン、チャネル、税・配送システムの技術詳細 |
| Vendure Dashboard の不具合を切り分けたい | vendure-dashboard-troubleshooting.md | 在庫欄など Dashboard 表示不整合の調査手順 |
| Vendureプラグインを実装したい | vendure-plugins/index.md | 掛率、割戻金、キャンペーン等の拡張仕様 |
| 商品の用途分類と通常カート追加可否を確認したい | ../specifications/2026-05-product-variant-role-and-customer-addability.md | ギフト・サンプル・内部調整 SKU の制御 |
| SMILE連携のマスタデータを確認したい | smile/smile-master-data-reference.md | フィクスチャのヘッダー・用途対応表 |
| SMILE原本の全列定義を確認したい | smile/smile-master-xlsx-field-catalog.md | SMILEマスタ.xlsx の全項目（型・桁数・備考） |
| Vendureシードを安全に投入したい | vendure-seed-data-guide.md | InitialData/CSV整合性ルールと検証スクリプト |
| 受注番号の採番ルールを確認したい | order/order-code-generation.md | NetB2B/Direct プレフィックスと連動フロー |
| 価格計算ロジックを確認したい | pricing/price-calculation.md | 5軸/3段モデル・SMILE specificity・直送加算 |
| 設定ミスによる顧客不利益を検査したい | vendure-plugins/diagnostics.md | 0件可視顧客・0円販売・上代超えの運用診断 |
| システム構成を確認したい | infrastructure/system-architecture.md | Fly.io / Cloudflare / R2 / Redis の全体構成 |
| キャッシュ方針を確認したい | infrastructure/cache-strategy.md | local / preview / staging / production の差分 |
| Storefront 商品一覧の 500 / 遅延を切り分けたい | infrastructure/storefront-products-performance-troubleshooting.md | /commerce/shop-api 500 と HardenPlugin 確認 |
| 決済仕様を確認したい | payments/payment-handlers.md | 利用可能な決済方法とハンドラーの責務 |
| フロントエンドの設計指針を確認 | frontend/index.md | UI構造・状態管理・GraphQL連携 |
| WordPress CMS統合を理解したい | integration/index.md | CMS統合、GraphQL API、コンテンツ管理 |
| カスタム商品リストの正本と shortcode を確認したい | ../specifications/2026-06-custom-product-lists.md | Vendure 管理の商品リスト、ホーム表示、記事埋め込み |
| インフラ設定を行いたい | infrastructure/index.md | Fly.io、Redis、DevContainer |
| contract generated の現行運用を確認したい | infrastructure/contract-generated-migration-plan.md | source alias 縮退の実施内容と現行運用 |
| AI 作業の入口を揃えたい | infrastructure/ai-agent-operations.md | 探索、develop 同期、CI 一次情報確認 |
| observability 相関を辿りたい | infrastructure/observability-correlation.md | trace / log / artifact の join 手順 |
| 実装例から着想を得たい | implementation-examples/index.md | コードスニペットとベストプラクティス |
flowchart LR
plan[Vendure拡張設計] --> pluginDoc[vendure-plugins/index.md]
pluginDoc -->|GraphQL拡張| implExamples
plan --> storeDoc[frontend/index.md]
storeDoc -->|UI実装| implExamples[implementation-examples/index.md]
infra[infrastructure/index.md] -->|CI/CD| implExamples
infra -->|ローカル環境| devEnv[DevContainer Guide]
subgraph Vendure
pluginDoc
end
subgraph Storefront
storeDoc
end
subgraph Cross
infra
implExamples
devEnv
end
設計ドキュメントと実装例の行き来を示した図です。Vendure／Storefrontで分担しながらも、Infrastructure と Implementation Examples で横串管理します。
🧩 セクション概要¶
Vendure Plugins¶
- 主なテーマ: 顧客別掛率、直送モード10%サーチャージ、月次割戻金、キャンペーン6種
- 確認ポイント: GraphQL拡張、Webhook、スケジュールバッチ、テスト戦略、Vendure Money 単位運用
- 推奨フロー: プラグイン開発の基礎で実装手順を確認 → 仕様確認 → プラグインテンプレート参照 → 実装サンプルで検証
Frontend (Storefront)¶
| サブカテゴリ | 内容 |
|---|---|
| コンポーネント設計 | Atomic Designベースのモジュール構成 |
| 状態管理 | React Query＋GraphQL Code Generatorの利用方針 |
| ルーティング | B2B固有の購入制限に合わせた保護ルート |
| UI/UXガイド | デザインワークショップの成果物へのリンク |
WordPress CMS統合¶
WordPress 関連の文書は目的別に4階層に分かれています。
| 🎯 目的 | 🔗 文書 | 📝 役割 |
|---|---|---|
| コンテンツ操作（運用者向け・推奨入り口） | 操作マニュアル | 日常操作の正本。お知らせ・キャンペーン・メインバナー・メニューの操作手順。 |
| 統合アーキテクチャ（開発者向け） | 統合ガイド | Storefront連携・キャッシュ戦略・エラーハンドリングの実装パターン。 |
| 運用ルール・ACF補足 | コンテンツ管理ガイド | 各コンテンツタイプの設計方針・運用ルール。操作手順は操作マニュアルが正本。 |
| GraphQLクエリ確認 | APIリファレンス | エンドポイント・クエリ例・パフォーマンス最適化。 |
まずは目的に合った文書を選んでください。コンテンツ操作が目的なら 操作マニュアル を、開発連携の理解が目的なら 統合ガイド を開いてください。
Infrastructure & Operations¶
- Fly.io 本番環境構成、ステージング環境、専用 Redis 運用の利用方法
- DevContainer/ローカル開発環境構築手順、CI/CDタスク一覧
- 監視（Logtail, Better Stack）とエラーハンドリングの運用ルール
- AI エージェント向けの探索除外、develop 同期、worktree 衛生の標準手順
Implementation Examples¶
- GraphQLクエリ/ミューテーションの利用例
- Vendureプラグインのテストコード例
- E2Eテストシナリオ（Playwright）とデータフィクスチャ
data-testid 運用ルール（Storefront E2E）¶
- 命名規約:
画面プレフィックス-コンポーネント-役割（例:home-hero-slide,cart-line-quantity-input）。英小文字・ケバブケースで統一。 - 用途: E2Eテスト専用。スタイル・計測・DOM操作（本番機能）への流用は禁止。
- 付与対象: 主要導線（ログイン→検索→商品詳細→カート→チェックアウト→注文履歴）と共通UI（フォーム、モーダル、トーストなど）で識別に必要な最小限の要素。
- 実装方針: コンポーネントは
testIdprops やbuildTestId()を介してdata-testidを透過・委譲する。shadcn/ui 純正コンポーネントは直接編集しない。 - レビュー観点: 命名規約準拠、重複/曖昧なIDの排除、意味のある粒度（テキスト依存や階層依存のセレクタを排除）。
🧭 作業時のガードレール¶
- 型安全性: TypeScriptとGraphQL Code Generatorで型を担保し、API変更時に検出できるようにする。
- 自動化優先: oxlint/oxfmt/knip/typecheckを定期実行し、CIとローカルのルールを揃える。
- ドキュメント同期: 実装変更が生じた場合は、関連セクション（plugins/frontend/infrastructure）の記述を即時更新する。
✅ 更新チェックリスト¶
- 新規プラグインやAPIを追加したら、対応するセクションと実装例にリンクを追加した。
- コード例は最新のフォルダ構成と一致しているか確認した。
- インフラ構成の変更があれば、設計側（02-design）との整合も更新した。