npm - @k2works/claude-code-booster - Versions diffs - 3.6.0 → 3.7.0 - Mend

@k2works/claude-code-booster 3.6.0 → 3.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (713) hide show

package/lib/assets/docs/article/practical-database-design/study/study2-4.md CHANGED Viewed

@@ -1,2229 +1,2229 @@
-# 実践データベース設計：販売管理システム 研究 4 - GraphQL サービスの実装
-## はじめに
-本研究では、REST API（第10部-A）や gRPC（研究 3）とは異なるアプローチとして、**GraphQL** による販売管理システムを実装します。クライアントが必要なデータを正確に指定できる柔軟なクエリと、リアルタイム更新を実現する Subscription を活用します。
-研究 1 で構築したヘキサゴナルアーキテクチャ（ドメイン層・アプリケーション層）はそのまま共有し、**Input Adapter として GraphQL リゾルバ層のみを追加**します。
----
-## 第14章：GraphQL サーバーの基礎
-### 14.1 GraphQL とは
-GraphQL は Facebook が開発したクエリ言語および実行エンジンです。クライアントが必要なデータの形状を指定でき、Over-fetching（不要なデータの取得）や Under-fetching（必要なデータの不足）を防ぎます。
-```plantuml
-@startuml graphql_architecture
-!define RECTANGLE class
-skinparam backgroundColor #FEFEFE
-package "GraphQL Architecture (販売管理システム)" {
-  package "Client Side" {
-    RECTANGLE "GraphQL Client\n(Apollo/Relay/urql)" as client {
-      - Query (読み取り)
-      - Mutation (書き込み)
-      - Subscription (リアルタイム)
-    }
-  }
-  package "Server Side" {
-    RECTANGLE "GraphQL Server\n(Spring for GraphQL)" as server {
-      - ProductResolver
-      - PartnerResolver
-      - OrderResolver
-      - InvoiceResolver
-    }
-  }
-  package "Shared" {
-    RECTANGLE "GraphQL Schema\n(.graphqls files)" as schema {
-      - schema.graphqls
-      - product.graphqls
-      - partner.graphqls
-      - order.graphqls
-    }
-  }
-}
-client --> schema : "スキーマに基づいて\nクエリを構築"
-server --> schema : "スキーマに基づいて\nリゾルバを実装"
-client <--> server : "HTTP/WebSocket\n(JSON)"
-note bottom of schema
-  スキーマ駆動開発
-  クライアント主導のデータ取得
-  型安全な API
-end note
-@enduml
-```
-**REST API / gRPC / GraphQL の比較：**
-| 特徴 | REST API | gRPC | GraphQL |
-|------|----------|------|---------|
-| プロトコル | HTTP/1.1 | HTTP/2 | HTTP/1.1 or HTTP/2 |
-| データ形式 | JSON | Protocol Buffers | JSON |
-| スキーマ | OpenAPI (任意) | .proto (必須) | .graphqls (必須) |
-| データ取得 | 固定レスポンス | 固定レスポンス | クライアント指定 |
-| エンドポイント | 複数 | 複数 | 単一 |
-| リアルタイム | WebSocket 別実装 | ストリーミング | Subscription |
-| 主な用途 | 汎用 API | マイクロサービス | フロントエンド向け |
----
-### 14.2 3つの操作タイプ
-GraphQL は 3 つの操作タイプをサポートします：
-```plantuml
-@startuml graphql_operations
-skinparam backgroundColor #FEFEFE
-rectangle "1. Query\n(読み取り)" as query #LightBlue {
-}
-note right of query
-  { products { code name price } }
-  → { products: [...] }
-  データの取得
-  複数リソースを1回で取得可能
-end note
-rectangle "2. Mutation\n(書き込み)" as mutation #LightGreen {
-}
-note right of mutation
-  mutation { createOrder(...) }
-  → { createOrder: {...} }
-  データの作成・更新・削除
-end note
-rectangle "3. Subscription\n(リアルタイム)" as subscription #LightCoral {
-}
-note right of subscription
-  subscription { orderStatusChanged }
-  → (WebSocket でプッシュ通知)
-  リアルタイム更新の受信
-end note
-query -[hidden]-> mutation
-mutation -[hidden]-> subscription
-@enduml
-```
-**用途：**
-1. **Query**: データ取得（商品一覧、受注明細、在庫照会）
-2. **Mutation**: データ更新（受注登録、出荷確定、入金処理）
-3. **Subscription**: リアルタイム通知（受注ステータス変更、在庫変動）
----
-### 14.3 GraphQL におけるヘキサゴナルアーキテクチャ
-GraphQL を導入しても、既存のヘキサゴナルアーキテクチャ（ドメイン層・アプリケーション層）はそのまま共有し、**Input Adapter として GraphQL リゾルバ層のみを追加**します。
-```plantuml
-@startuml hexagonal_graphql
-!define RECTANGLE class
-package "Hexagonal Architecture (GraphQL版)" {
-  RECTANGLE "Application Core\n(Domain + Use Cases)" as core {
-    - Product (商品)
-    - Partner (取引先)
-    - Order (受注)
-    - Shipment (出荷)
-    - Invoice (請求)
-    - ProductUseCase
-    - OrderUseCase
-    - InvoiceUseCase
-  }
-  RECTANGLE "Input Adapters\n(Driving Side)" as input {
-    - REST Controller（既存）
-    - gRPC Service（既存）
-    - GraphQL Resolver（新規追加）
-    - DataFetcher
-    - DataLoader
-  }
-  RECTANGLE "Output Adapters\n(Driven Side)" as output {
-    - MyBatis Repository
-    - Database Access
-    - Entity Mapping
-  }
-}
-input --> core : "Input Ports\n(Use Cases)"
-core --> output : "Output Ports\n(Repository Interfaces)"
-note top of core
-  既存のビジネスロジック
-  REST API / gRPC 版と完全に共有
-  GraphQL 固有のコードは含まない
-end note
-note left of input
-  GraphQL リゾルバを
-  Input Adapter として追加
-  既存の REST/gRPC と共存可能
-end note
-@enduml
-```
-**GraphQL でもヘキサゴナルアーキテクチャを維持する理由：**
-1. **再利用性**: 既存の UseCase/Repository をそのまま活用
-2. **並行運用**: REST API、gRPC、GraphQL を同時提供可能
-3. **テスト容易性**: ドメインロジックは通信プロトコルに依存しない
-4. **移行容易性**: 段階的に API 形式を追加・変更可能
----
-### 14.4 ディレクトリ構成
-既存の構成に `infrastructure/graphql/` を追加するだけです。
-<details>
-<summary>コード例: ディレクトリ構成</summary>
-```
-src/main/java/com/example/sales/
-├── domain/                     # ドメイン層（API版と共通）
-│   ├── model/
-│   │   ├── product/
-│   │   ├── partner/
-│   │   ├── order/
-│   │   ├── shipment/
-│   │   └── invoice/
-│   └── exception/
-│
-├── application/               # アプリケーション層（API版と共通）
-│   ├── port/
-│   │   ├── in/               # Input Port（ユースケース）
-│   │   └── out/              # Output Port（リポジトリ）
-│   └── service/
-│
-├── infrastructure/
-│   ├── persistence/          # Output Adapter（DB実装）- 既存
-│   │   ├── mapper/
-│   │   └── repository/
-│   ├── rest/                 # Input Adapter（REST実装）- 既存
-│   ├── grpc/                 # Input Adapter（gRPC実装）- 既存
-│   └── graphql/              # Input Adapter（GraphQL実装）- 新規追加
-│       ├── resolver/         # Query/Mutation リゾルバ
-│       ├── dataloader/       # N+1 問題対策
-│       ├── scalar/           # カスタムスカラー型
-│       └── subscription/     # Subscription ハンドラ
-│
-├── config/
-│
-└── src/main/resources/
-    └── graphql/              # GraphQL スキーマ定義
-        ├── schema.graphqls
-        ├── product.graphqls
-        ├── partner.graphqls
-        ├── order.graphqls
-        ├── shipment.graphqls
-        └── invoice.graphqls
-```
-</details>
----
-### 14.5 技術スタックの追加
-既存の `build.gradle.kts` に GraphQL 関連の依存関係を追加します。
-#### build.gradle.kts（差分）
-<details>
-<summary>コード例: build.gradle.kts</summary>
-```kotlin
-dependencies {
-    // 既存の依存関係（Spring Boot, MyBatis, PostgreSQL等）はそのまま
-    // GraphQL 関連を追加
-    implementation("org.springframework.boot:spring-boot-starter-graphql")
-    implementation("org.springframework.boot:spring-boot-starter-websocket")  // Subscription 用
-    // GraphQL 拡張
-    implementation("com.graphql-java:graphql-java-extended-scalars:21.0")
-    // Test
-    testImplementation("org.springframework.graphql:spring-graphql-test")
-}
-```
-</details>
-**追加パッケージの説明：**
-| パッケージ | 用途 |
-|-----------|------|
-| spring-boot-starter-graphql | Spring Boot GraphQL 統合 |
-| spring-boot-starter-websocket | Subscription (WebSocket) |
-| graphql-java-extended-scalars | DateTime, BigDecimal 等のスカラー型 |
-| spring-graphql-test | GraphQL テストサポート |
-#### application.yml（差分）
-<details>
-<summary>コード例: application.yml</summary>
-```yaml
-spring:
-  graphql:
-    graphiql:
-      enabled: true
-      path: /graphiql
-    websocket:
-      path: /graphql
-      connection-init-timeout: 60s
-      keep-alive:
-        enabled: true
-        interval: 30s
-    schema:
-      printer:
-        enabled: true
-      locations:
-        - classpath:graphql/
-    cors:
-      allowed-origins: "*"
-      allowed-methods: GET, POST
-```
-</details>
----
-### 14.6 GraphQL 設定クラス
-<details>
-<summary>コード例: GraphQLConfig.java</summary>
-```java
-package com.example.sales.config;
-import graphql.scalars.ExtendedScalars;
-import org.springframework.context.annotation.Bean;
-import org.springframework.context.annotation.Configuration;
-import org.springframework.graphql.execution.RuntimeWiringConfigurer;
-/**
- * GraphQL 設定
- */
-@Configuration
-public class GraphQLConfig {
-    @Bean
-    public RuntimeWiringConfigurer runtimeWiringConfigurer() {
-        return wiringBuilder -> wiringBuilder
-            .scalar(ExtendedScalars.Date)
-            .scalar(ExtendedScalars.DateTime)
-            .scalar(ExtendedScalars.GraphQLBigDecimal)
-            .scalar(ExtendedScalars.GraphQLLong);
-    }
-}
-```
-</details>
----
-### 14.7 GraphQL スキーマ定義
-#### src/main/resources/graphql/schema.graphqls
-<details>
-<summary>コード例: schema.graphqls</summary>
-```graphql
-# ルートスキーマ
-type Query {
-    # 商品
-    product(productCode: ID!): Product
-    products(category: ProductCategory, page: Int, size: Int): ProductConnection!
-    # 取引先
-    partner(partnerCode: ID!): Partner
-    partners(type: PartnerType, page: Int, size: Int): PartnerConnection!
-    # 倉庫
-    warehouse(warehouseCode: ID!): Warehouse
-    warehouses(page: Int, size: Int): WarehouseConnection!
-    # 受注
-    order(orderNumber: ID!): Order
-    orders(status: OrderStatus, partnerCode: ID, page: Int, size: Int): OrderConnection!
-    # 出荷
-    shipment(shipmentNumber: ID!): Shipment
-    shipments(status: ShipmentStatus, page: Int, size: Int): ShipmentConnection!
-    # 請求
-    invoice(invoiceNumber: ID!): Invoice
-    invoices(status: InvoiceStatus, partnerCode: ID, page: Int, size: Int): InvoiceConnection!
-}
-type Mutation {
-    # 商品
-    createProduct(input: CreateProductInput!): Product!
-    updateProduct(input: UpdateProductInput!): Product!
-    deleteProduct(productCode: ID!): Boolean!
-    # 取引先
-    createPartner(input: CreatePartnerInput!): Partner!
-    updatePartner(input: UpdatePartnerInput!): Partner!
-    # 受注
-    createOrder(input: CreateOrderInput!): Order!
-    confirmOrder(orderNumber: ID!): Order!
-    cancelOrder(orderNumber: ID!, reason: String): Order!
-    # 出荷
-    createShipment(input: CreateShipmentInput!): Shipment!
-    startPicking(shipmentNumber: ID!): Shipment!
-    confirmShipment(shipmentNumber: ID!): Shipment!
-    # 請求
-    executeClosing(input: ExecuteClosingInput!): ClosingResult!
-    issueInvoice(invoiceNumber: ID!): Invoice!
-    recordReceipt(input: RecordReceiptInput!): Receipt!
-}
-type Subscription {
-    # 受注ステータス変更
-    orderStatusChanged(orderNumber: ID): OrderStatusChange!
-    # 出荷進捗
-    shipmentProgressUpdated(shipmentNumber: ID): ShipmentProgress!
-    # 在庫変動
-    inventoryChanged(warehouseCode: ID, productCode: ID): InventoryChange!
-    # 締処理進捗
-    closingProgressUpdated(closingId: ID!): ClosingProgress!
-}
-# ページネーション共通型
-type PageInfo {
-    hasNextPage: Boolean!
-    hasPreviousPage: Boolean!
-    totalElements: Int!
-    totalPages: Int!
-    currentPage: Int!
-}
-# カスタムスカラー
-scalar Date
-scalar DateTime
-scalar BigDecimal
-scalar Long
-```
-</details>
-#### src/main/resources/graphql/product.graphqls
-<details>
-<summary>コード例: product.graphqls</summary>
-```graphql
-# 商品区分
-enum ProductCategory {
-    PRODUCT      # 製品
-    MATERIAL     # 原材料
-    PART         # 部品
-}
-# 税区分
-enum TaxCategory {
-    TAXABLE      # 課税
-    TAX_EXEMPT   # 非課税
-    TAX_FREE     # 免税
-}
-# 商品
-type Product {
-    productCode: ID!
-    productName: String!
-    productNameKana: String
-    category: ProductCategory!
-    taxCategory: TaxCategory!
-    unitCode: String
-    sellingPrice: BigDecimal!
-    purchasePrice: BigDecimal
-    costPrice: BigDecimal
-    safetyStock: Int
-    reorderPoint: Int
-    isActive: Boolean!
-    createdAt: DateTime!
-    updatedAt: DateTime!
-    # 関連データ（必要な場合のみ取得）
-    inventories: [Inventory!]!
-    classifications: [ProductClassification!]!
-    customerPrices: [CustomerPrice!]!
-}
-# 商品一覧（ページネーション付き）
-type ProductConnection {
-    edges: [ProductEdge!]!
-    pageInfo: PageInfo!
-}
-type ProductEdge {
-    node: Product!
-    cursor: String!
-}
-# 入力型
-input CreateProductInput {
-    productCode: ID!
-    productName: String!
-    productNameKana: String
-    category: ProductCategory!
-    taxCategory: TaxCategory!
-    unitCode: String
-    sellingPrice: BigDecimal!
-    purchasePrice: BigDecimal
-    costPrice: BigDecimal
-    safetyStock: Int
-    reorderPoint: Int
-}
-input UpdateProductInput {
-    productCode: ID!
-    productName: String
-    category: ProductCategory
-    taxCategory: TaxCategory
-    sellingPrice: BigDecimal
-    isActive: Boolean
-}
-```
-</details>
-#### src/main/resources/graphql/order.graphqls
-<details>
-<summary>コード例: order.graphqls</summary>
-```graphql
-# 受注ステータス
-enum OrderStatus {
-    DRAFT        # 仮登録
-    CONFIRMED    # 確定
-    SHIPPED      # 出荷済
-    CANCELLED    # キャンセル
-}
-# 受注
-type Order {
-    orderNumber: ID!
-    partnerCode: ID!
-    orderDate: Date!
-    deliveryDate: Date!
-    warehouseCode: ID!
-    status: OrderStatus!
-    totalAmount: BigDecimal!
-    taxAmount: BigDecimal!
-    grandTotal: BigDecimal!
-    salesPersonCode: String
-    remarks: String
-    createdAt: DateTime!
-    updatedAt: DateTime!
-    # 関連データ
-    partner: Partner!
-    warehouse: Warehouse!
-    details: [OrderDetail!]!
-    shipments: [Shipment!]!
-}
-# 受注明細
-type OrderDetail {
-    orderNumber: ID!
-    lineNumber: Int!
-    productCode: ID!
-    quantity: Int!
-    unitPrice: BigDecimal!
-    amount: BigDecimal!
-    taxCategory: TaxCategory!
-    deliveryDate: Date
-    remarks: String
-    # 関連データ
-    product: Product!
-}
-# 受注ステータス変更イベント
-type OrderStatusChange {
-    orderNumber: ID!
-    previousStatus: OrderStatus!
-    currentStatus: OrderStatus!
-    changedBy: String
-    changedAt: DateTime!
-    reason: String
-}
-# 入力型
-input CreateOrderInput {
-    partnerCode: ID!
-    orderDate: Date!
-    deliveryDate: Date!
-    warehouseCode: ID!
-    salesPersonCode: String
-    remarks: String
-    details: [OrderDetailInput!]!
-}
-input OrderDetailInput {
-    productCode: ID!
-    quantity: Int!
-    unitPrice: BigDecimal
-    deliveryDate: Date
-    remarks: String
-}
-```
-</details>
----
-### 14.8 基本的なリゾルバの実装
-#### Query リゾルバ
-<details>
-<summary>コード例: QueryResolver.java</summary>
-```java
-package com.example.sales.infrastructure.graphql.resolver;
-import com.example.sales.application.port.in.ProductUseCase;
-import com.example.sales.application.port.in.PartnerUseCase;
-import com.example.sales.domain.model.product.Product;
-import com.example.sales.domain.model.partner.Partner;
-import com.example.sales.infrastructure.graphql.dto.*;
-import org.springframework.graphql.data.method.annotation.Argument;
-import org.springframework.graphql.data.method.annotation.QueryMapping;
-import org.springframework.stereotype.Controller;
-import java.util.List;
-/**
- * GraphQL Query リゾルバ
- */
-@Controller
-public class QueryResolver {
-    private final ProductUseCase productUseCase;
-    private final PartnerUseCase partnerUseCase;
-    public QueryResolver(ProductUseCase productUseCase, PartnerUseCase partnerUseCase) {
-        this.productUseCase = productUseCase;
-        this.partnerUseCase = partnerUseCase;
-    }
-    // === 商品 ===
-    @QueryMapping
-    public Product product(@Argument String productCode) {
-        return productUseCase.findByCode(productCode).orElse(null);
-    }
-    @QueryMapping
-    public ProductConnection products(
-            @Argument String category,
-            @Argument Integer page,
-            @Argument Integer size) {
-        int pageNum = page != null ? page : 0;
-        int pageSize = size != null ? size : 20;
-        List<Product> products = productUseCase.findAll(category, pageNum, pageSize);
-        long totalCount = productUseCase.count(category);
-        return ProductConnection.of(products, pageNum, pageSize, totalCount);
-    }
-    // === 取引先 ===
-    @QueryMapping
-    public Partner partner(@Argument String partnerCode) {
-        return partnerUseCase.findByCode(partnerCode).orElse(null);
-    }
-    @QueryMapping
-    public PartnerConnection partners(
-            @Argument String type,
-            @Argument Integer page,
-            @Argument Integer size) {
-        int pageNum = page != null ? page : 0;
-        int pageSize = size != null ? size : 20;
-        List<Partner> partners = partnerUseCase.findAll(type, pageNum, pageSize);
-        long totalCount = partnerUseCase.count(type);
-        return PartnerConnection.of(partners, pageNum, pageSize, totalCount);
-    }
-}
-```
-</details>
-#### Connection DTO（ページネーション）
-<details>
-<summary>コード例: ProductConnection.java</summary>
-```java
-package com.example.sales.infrastructure.graphql.dto;
-import com.example.sales.domain.model.product.Product;
-import java.util.Base64;
-import java.util.List;
-/**
- * 商品ページネーション結果（Connection パターン）
- */
-public record ProductConnection(
-    List<ProductEdge> edges,
-    PageInfo pageInfo
-) {
-    public static ProductConnection of(
-            List<Product> products,
-            int page,
-            int size,
-            long totalCount) {
-        List<ProductEdge> edges = products.stream()
-            .map(product -> new ProductEdge(
-                product,
-                encodeCursor(product.getProductCode())
-            ))
-            .toList();
-        int totalPages = (int) Math.ceil((double) totalCount / size);
-        PageInfo pageInfo = new PageInfo(
-            page < totalPages - 1,  // hasNextPage
-            page > 0,               // hasPreviousPage
-            totalCount,
-            totalPages,
-            page
-        );
-        return new ProductConnection(edges, pageInfo);
-    }
-    private static String encodeCursor(String productCode) {
-        return Base64.getEncoder().encodeToString(productCode.getBytes());
-    }
-}
-public record ProductEdge(
-    Product node,
-    String cursor
-) {}
-public record PageInfo(
-    boolean hasNextPage,
-    boolean hasPreviousPage,
-    long totalElements,
-    int totalPages,
-    int currentPage
-) {}
-```
-</details>
----
-### 14.9 Spring for GraphQL の統合テスト
-<details>
-<summary>コード例: QueryResolverTest.java</summary>
-```java
-package com.example.sales.infrastructure.graphql;
-import org.junit.jupiter.api.Test;
-import org.springframework.beans.factory.annotation.Autowired;
-import org.springframework.boot.test.autoconfigure.graphql.tester.AutoConfigureHttpGraphQlTester;
-import org.springframework.boot.test.context.SpringBootTest;
-import org.springframework.graphql.test.tester.HttpGraphQlTester;
-import org.springframework.test.context.DynamicPropertyRegistry;
-import org.springframework.test.context.DynamicPropertySource;
-import org.testcontainers.containers.PostgreSQLContainer;
-import org.testcontainers.junit.jupiter.Container;
-import org.testcontainers.junit.jupiter.Testcontainers;
-@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
-@AutoConfigureHttpGraphQlTester
-@Testcontainers
-class QueryResolverTest {
-    @Container
-    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16-alpine");
-    @DynamicPropertySource
-    static void configureProperties(DynamicPropertyRegistry registry) {
-        registry.add("spring.datasource.url", postgres::getJdbcUrl);
-        registry.add("spring.datasource.username", postgres::getUsername);
-        registry.add("spring.datasource.password", postgres::getPassword);
-    }
-    @Autowired
-    private HttpGraphQlTester graphQlTester;
-    @Test
-    void testQueryProduct() {
-        // language=GraphQL
-        String query = """
-            query {
-                product(productCode: "PRD001") {
-                    productCode
-                    productName
-                    sellingPrice
-                    category
-                }
-            }
-            """;
-        graphQlTester.document(query)
-            .execute()
-            .path("product.productCode")
-            .entity(String.class)
-            .isEqualTo("PRD001");
-    }
-    @Test
-    void testQueryProducts() {
-        // language=GraphQL
-        String query = """
-            query {
-                products(category: PRODUCT, page: 0, size: 10) {
-                    edges {
-                        node {
-                            productCode
-                            productName
-                        }
-                        cursor
-                    }
-                    pageInfo {
-                        hasNextPage
-                        totalElements
-                    }
-                }
-            }
-            """;
-        graphQlTester.document(query)
-            .execute()
-            .path("products.edges")
-            .entityList(Object.class)
-            .hasSizeGreaterThan(0);
-    }
-    @Test
-    void testQueryProductWithRelations() {
-        // 関連データも含めて取得
-        // language=GraphQL
-        String query = """
-            query {
-                product(productCode: "PRD001") {
-                    productCode
-                    productName
-                    inventories {
-                        warehouseCode
-                        quantity
-                        availableQuantity
-                    }
-                    classifications {
-                        classificationCode
-                        classificationName
-                    }
-                }
-            }
-            """;
-        graphQlTester.document(query)
-            .execute()
-            .path("product.productCode")
-            .entity(String.class)
-            .isEqualTo("PRD001");
-    }
-}
-```
-</details>
----
-## 第15章：マスタ API の実装
-### 15.1 N+1 問題とは
-GraphQL では、ネストしたデータを取得する際に **N+1 問題** が発生しやすくなります。例えば、10件の商品を取得し、それぞれの在庫情報を取得すると、1回（商品一覧）+ 10回（各商品の在庫）= 11回のクエリが実行されます。
-```plantuml
-@startuml n_plus_1_problem
-title N+1 問題の発生パターン
-participant "GraphQL Client" as client
-participant "ProductResolver" as resolver
-participant "InventoryRepository" as repo
-database "PostgreSQL" as db
-client -> resolver : products(first: 10)
-resolver -> db : SELECT * FROM 商品マスタ LIMIT 10
-db --> resolver : 10件の商品
-loop 各商品に対して（N回）
-  resolver -> repo : findByProductCode(code)
-  repo -> db : SELECT * FROM 在庫データ WHERE 商品コード = ?
-  db --> repo : 在庫データ
-  repo --> resolver : 在庫
-end
-resolver --> client : 商品一覧（在庫付き）
-note right of db
-  合計 11回のクエリ
-  (1 + N = 1 + 10)
-  商品が100件なら101回！
-end note
-@enduml
-```
----
-### 15.2 DataLoader による解決
-**DataLoader** は、複数の個別リクエストをバッチ処理にまとめることで N+1 問題を解決します。
-```plantuml
-@startuml dataloader_solution
-title DataLoader による N+1 問題の解決
-participant "GraphQL Client" as client
-participant "ProductResolver" as resolver
-participant "InventoryDataLoader" as loader
-participant "InventoryRepository" as repo
-database "PostgreSQL" as db
-client -> resolver : products(first: 10)
-resolver -> db : SELECT * FROM 商品マスタ LIMIT 10
-db --> resolver : 10件の商品
-loop 各商品に対して
-  resolver -> loader : load(productCode)
-  note right of loader : キューに追加
-end
-loader -> repo : loadMany([code1, code2, ...code10])
-repo -> db : SELECT * FROM 在庫データ WHERE 商品コード IN (?, ?, ..., ?)
-db --> repo : 10件の在庫データ
-repo --> loader : Map<商品コード, 在庫>
-loader --> resolver : 各商品の在庫
-resolver --> client : 商品一覧（在庫付き）
-note right of db
-  合計 2回のクエリ
-  (1 + 1 = 2)
-  商品が100件でも2回！
-end note
-@enduml
-```
----
-### 15.3 DataLoader の実装
-#### 在庫 DataLoader
-<details>
-<summary>コード例: InventoryDataLoader.java</summary>
-```java
-package com.example.sales.infrastructure.graphql.dataloader;
-import com.example.sales.application.port.out.InventoryRepository;
-import com.example.sales.domain.model.inventory.Inventory;
-import org.dataloader.BatchLoaderEnvironment;
-import org.dataloader.MappedBatchLoader;
-import org.springframework.stereotype.Component;
-import java.util.List;
-import java.util.Map;
-import java.util.Set;
-import java.util.concurrent.CompletableFuture;
-import java.util.concurrent.CompletionStage;
-import java.util.stream.Collectors;
-/**
- * 在庫データの DataLoader
- * 商品コードをキーにバッチ取得
- */
-@Component
-public class InventoryDataLoader implements MappedBatchLoader<String, List<Inventory>> {
-    private final InventoryRepository inventoryRepository;
-    public InventoryDataLoader(InventoryRepository inventoryRepository) {
-        this.inventoryRepository = inventoryRepository;
-    }
-    @Override
-    public CompletionStage<Map<String, List<Inventory>>> load(
-            Set<String> productCodes,
-            BatchLoaderEnvironment environment) {
-        return CompletableFuture.supplyAsync(() -> {
-            // 一括取得
-            List<Inventory> inventories = inventoryRepository
-                .findByProductCodes(productCodes);
-            // 商品コードでグループ化
-            return inventories.stream()
-                .collect(Collectors.groupingBy(Inventory::getProductCode));
-        });
-    }
-}
-```
-</details>
-#### 取引先 DataLoader
-<details>
-<summary>コード例: PartnerDataLoader.java</summary>
-```java
-package com.example.sales.infrastructure.graphql.dataloader;
-import com.example.sales.application.port.out.PartnerRepository;
-import com.example.sales.domain.model.partner.Partner;
-import org.dataloader.BatchLoaderEnvironment;
-import org.dataloader.MappedBatchLoader;
-import org.springframework.stereotype.Component;
-import java.util.Map;
-import java.util.Set;
-import java.util.concurrent.CompletableFuture;
-import java.util.concurrent.CompletionStage;
-import java.util.function.Function;
-import java.util.stream.Collectors;
-/**
- * 取引先データの DataLoader
- */
-@Component
-public class PartnerDataLoader implements MappedBatchLoader<String, Partner> {
-    private final PartnerRepository partnerRepository;
-    public PartnerDataLoader(PartnerRepository partnerRepository) {
-        this.partnerRepository = partnerRepository;
-    }
-    @Override
-    public CompletionStage<Map<String, Partner>> load(
-            Set<String> partnerCodes,
-            BatchLoaderEnvironment environment) {
-        return CompletableFuture.supplyAsync(() -> {
-            return partnerRepository.findByCodes(partnerCodes).stream()
-                .collect(Collectors.toMap(
-                    Partner::getPartnerCode,
-                    Function.identity()
-                ));
-        });
-    }
-}
-```
-</details>
----
-### 15.4 DataLoader の登録
-<details>
-<summary>コード例: DataLoaderConfig.java</summary>
-```java
-package com.example.sales.config;
-import com.example.sales.infrastructure.graphql.dataloader.*;
-import org.dataloader.DataLoader;
-import org.dataloader.DataLoaderOptions;
-import org.dataloader.DataLoaderRegistry;
-import org.springframework.context.annotation.Bean;
-import org.springframework.context.annotation.Configuration;
-import org.springframework.graphql.execution.BatchLoaderRegistry;
-/**
- * DataLoader 設定
- */
-@Configuration
-public class DataLoaderConfig {
-    public static final String INVENTORY_LOADER = "inventoryLoader";
-    public static final String PARTNER_LOADER = "partnerLoader";
-    public static final String PRODUCT_LOADER = "productLoader";
-    public static final String WAREHOUSE_LOADER = "warehouseLoader";
-    private final InventoryDataLoader inventoryDataLoader;
-    private final PartnerDataLoader partnerDataLoader;
-    private final ProductDataLoader productDataLoader;
-    private final WarehouseDataLoader warehouseDataLoader;
-    public DataLoaderConfig(
-            InventoryDataLoader inventoryDataLoader,
-            PartnerDataLoader partnerDataLoader,
-            ProductDataLoader productDataLoader,
-            WarehouseDataLoader warehouseDataLoader) {
-        this.inventoryDataLoader = inventoryDataLoader;
-        this.partnerDataLoader = partnerDataLoader;
-        this.productDataLoader = productDataLoader;
-        this.warehouseDataLoader = warehouseDataLoader;
-    }
-    @Bean
-    public BatchLoaderRegistry batchLoaderRegistry() {
-        return new BatchLoaderRegistry() {
-            @Override
-            public void registerDataLoaders(
-                    DataLoaderRegistry registry,
-                    graphql.GraphQLContext context) {
-                DataLoaderOptions options = DataLoaderOptions.newOptions()
-                    .setCachingEnabled(true)
-                    .setBatchingEnabled(true)
-                    .setMaxBatchSize(100);
-                registry.register(INVENTORY_LOADER,
-                    DataLoader.newMappedDataLoader(inventoryDataLoader, options));
-                registry.register(PARTNER_LOADER,
-                    DataLoader.newMappedDataLoader(partnerDataLoader, options));
-                registry.register(PRODUCT_LOADER,
-                    DataLoader.newMappedDataLoader(productDataLoader, options));
-                registry.register(WAREHOUSE_LOADER,
-                    DataLoader.newMappedDataLoader(warehouseDataLoader, options));
-            }
-        };
-    }
-}
-```
-</details>
----
-### 15.5 商品リゾルバの実装（DataLoader 使用）
-<details>
-<summary>コード例: ProductResolver.java</summary>
-```java
-package com.example.sales.infrastructure.graphql.resolver;
-import com.example.sales.application.port.in.ProductUseCase;
-import com.example.sales.config.DataLoaderConfig;
-import com.example.sales.domain.model.inventory.Inventory;
-import com.example.sales.domain.model.product.Product;
-import com.example.sales.infrastructure.graphql.dto.*;
-import graphql.schema.DataFetchingEnvironment;
-import org.dataloader.DataLoader;
-import org.springframework.graphql.data.method.annotation.*;
-import org.springframework.stereotype.Controller;
-import java.util.List;
-import java.util.concurrent.CompletableFuture;
-/**
- * 商品 GraphQL リゾルバ
- */
-@Controller
-public class ProductResolver {
-    private final ProductUseCase productUseCase;
-    public ProductResolver(ProductUseCase productUseCase) {
-        this.productUseCase = productUseCase;
-    }
-    // === Query ===
-    @QueryMapping
-    public Product product(@Argument String productCode) {
-        return productUseCase.findByCode(productCode).orElse(null);
-    }
-    @QueryMapping
-    public ProductConnection products(
-            @Argument String category,
-            @Argument Integer page,
-            @Argument Integer size) {
-        int pageNum = page != null ? page : 0;
-        int pageSize = size != null ? size : 20;
-        List<Product> products = productUseCase.findAll(category, pageNum, pageSize);
-        long totalCount = productUseCase.count(category);
-        return ProductConnection.of(products, pageNum, pageSize, totalCount);
-    }
-    // === Mutation ===
-    @MutationMapping
-    public Product createProduct(@Argument CreateProductInput input) {
-        Product product = Product.builder()
-            .productCode(input.productCode())
-            .productName(input.productName())
-            .category(input.category())
-            .taxCategory(input.taxCategory())
-            .sellingPrice(input.sellingPrice())
-            .isActive(true)
-            .build();
-        return productUseCase.create(product);
-    }
-    @MutationMapping
-    public Product updateProduct(@Argument UpdateProductInput input) {
-        return productUseCase.update(input.productCode(), product -> {
-            if (input.productName() != null) {
-                product.setProductName(input.productName());
-            }
-            if (input.category() != null) {
-                product.setCategory(input.category());
-            }
-            if (input.sellingPrice() != null) {
-                product.setSellingPrice(input.sellingPrice());
-            }
-            if (input.isActive() != null) {
-                product.setActive(input.isActive());
-            }
-            return product;
-        });
-    }
-    @MutationMapping
-    public boolean deleteProduct(@Argument String productCode) {
-        return productUseCase.delete(productCode);
-    }
-    // === フィールドリゾルバ（DataLoader 使用）===
-    @SchemaMapping(typeName = "Product", field = "inventories")
-    public CompletableFuture<List<Inventory>> inventories(
-            Product product,
-            DataFetchingEnvironment env) {
-        DataLoader<String, List<Inventory>> loader =
-            env.getDataLoader(DataLoaderConfig.INVENTORY_LOADER);
-        return loader.load(product.getProductCode());
-    }
-    @SchemaMapping(typeName = "Product", field = "classifications")
-    public List<ProductClassification> classifications(Product product) {
-        return productUseCase.findClassifications(product.getProductCode());
-    }
-}
-```
-</details>
----
-## 第16章：トランザクション API の実装
-### 16.1 GraphQL Subscription とは
-GraphQL **Subscription** は、サーバーからクライアントへのリアルタイム通知を実現する仕組みです。WebSocket を使用して双方向通信を行い、データの変更をプッシュ通知します。
-```plantuml
-@startuml subscription_flow
-title GraphQL Subscription フロー
-participant "Client" as client
-participant "WebSocket" as ws
-participant "GraphQL Server" as server
-participant "EventPublisher" as publisher
-participant "OrderService" as service
-database "PostgreSQL" as db
-== Subscription 開始 ==
-client -> ws : subscription { orderStatusChanged }
-ws -> server : WebSocket 接続確立
-server -> server : Subscription 登録
-== イベント発生 ==
-service -> db : 受注ステータス更新
-db --> service : 更新完了
-service -> publisher : OrderStatusChangedEvent 発行
-publisher -> server : イベント受信
-server -> ws : { orderStatusChanged: {...} }
-ws -> client : リアルタイム通知
-== 追加イベント ==
-service -> publisher : OrderStatusChangedEvent 発行
-publisher -> server : イベント受信
-server -> ws : { orderStatusChanged: {...} }
-ws -> client : リアルタイム通知
-== 接続終了 ==
-client -> ws : 接続クローズ
-ws -> server : Subscription 解除
-@enduml
-```
----
-### 16.2 イベントクラスの定義
-<details>
-<summary>コード例: OrderStatusChangedEvent.java</summary>
-```java
-package com.example.sales.domain.event;
-import com.example.sales.domain.model.order.OrderStatus;
-import java.time.LocalDateTime;
-/**
- * 受注ステータス変更イベント
- */
-public record OrderStatusChangedEvent(
-    String orderNumber,
-    OrderStatus previousStatus,
-    OrderStatus currentStatus,
-    String changedBy,
-    LocalDateTime changedAt,
-    String reason
-) {
-    public static OrderStatusChangedEvent of(
-            String orderNumber,
-            OrderStatus previousStatus,
-            OrderStatus currentStatus,
-            String changedBy) {
-        return new OrderStatusChangedEvent(
-            orderNumber,
-            previousStatus,
-            currentStatus,
-            changedBy,
-            LocalDateTime.now(),
-            null
-        );
-    }
-}
-```
-</details>
-<details>
-<summary>コード例: InventoryChangedEvent.java</summary>
-```java
-package com.example.sales.domain.event;
-import java.time.LocalDateTime;
-/**
- * 在庫変動イベント
- */
-public record InventoryChangedEvent(
-    String warehouseCode,
-    String productCode,
-    InventoryChangeType changeType,
-    int quantity,
-    int previousQuantity,
-    int currentQuantity,
-    LocalDateTime timestamp
-) {
-    public enum InventoryChangeType {
-        RECEIPT,      // 入庫
-        SHIPMENT,     // 出庫
-        ADJUSTMENT,   // 調整
-        TRANSFER,     // 移動
-        ALLOCATION,   // 引当
-        RELEASE       // 引当解除
-    }
-    public static InventoryChangedEvent of(
-            String warehouseCode,
-            String productCode,
-            InventoryChangeType changeType,
-            int quantity,
-            int previousQuantity,
-            int currentQuantity) {
-        return new InventoryChangedEvent(
-            warehouseCode,
-            productCode,
-            changeType,
-            quantity,
-            previousQuantity,
-            currentQuantity,
-            LocalDateTime.now()
-        );
-    }
-}
-```
-</details>
----
-### 16.3 イベントパブリッシャー（Reactor Sinks）
-<details>
-<summary>コード例: GraphQLEventPublisher.java</summary>
-```java
-package com.example.sales.infrastructure.graphql.subscription;
-import com.example.sales.domain.event.*;
-import org.springframework.stereotype.Component;
-import reactor.core.publisher.Flux;
-import reactor.core.publisher.Sinks;
-/**
- * GraphQL Subscription 用イベントパブリッシャー
- */
-@Component
-public class GraphQLEventPublisher {
-    // 受注ステータス変更
-    private final Sinks.Many<OrderStatusChangedEvent> orderStatusSink =
-        Sinks.many().multicast().onBackpressureBuffer();
-    // 出荷進捗
-    private final Sinks.Many<ShipmentProgressEvent> shipmentProgressSink =
-        Sinks.many().multicast().onBackpressureBuffer();
-    // 在庫変動
-    private final Sinks.Many<InventoryChangedEvent> inventoryChangedSink =
-        Sinks.many().multicast().onBackpressureBuffer();
-    // 締処理進捗
-    private final Sinks.Many<ClosingProgressEvent> closingProgressSink =
-        Sinks.many().multicast().onBackpressureBuffer();
-    // === 発行メソッド ===
-    public void publishOrderStatusChanged(OrderStatusChangedEvent event) {
-        orderStatusSink.tryEmitNext(event);
-    }
-    public void publishShipmentProgress(ShipmentProgressEvent event) {
-        shipmentProgressSink.tryEmitNext(event);
-    }
-    public void publishInventoryChanged(InventoryChangedEvent event) {
-        inventoryChangedSink.tryEmitNext(event);
-    }
-    public void publishClosingProgress(ClosingProgressEvent event) {
-        closingProgressSink.tryEmitNext(event);
-    }
-    // === Flux 取得メソッド ===
-    public Flux<OrderStatusChangedEvent> getOrderStatusChangedFlux() {
-        return orderStatusSink.asFlux();
-    }
-    public Flux<OrderStatusChangedEvent> getOrderStatusChangedFlux(String orderNumber) {
-        return orderStatusSink.asFlux()
-            .filter(event -> orderNumber == null ||
-                             event.orderNumber().equals(orderNumber));
-    }
-    public Flux<ShipmentProgressEvent> getShipmentProgressFlux(String shipmentNumber) {
-        return shipmentProgressSink.asFlux()
-            .filter(event -> shipmentNumber == null ||
-                             event.shipmentNumber().equals(shipmentNumber));
-    }
-    public Flux<InventoryChangedEvent> getInventoryChangedFlux(
-            String warehouseCode, String productCode) {
-        return inventoryChangedSink.asFlux()
-            .filter(event ->
-                (warehouseCode == null || event.warehouseCode().equals(warehouseCode)) &&
-                (productCode == null || event.productCode().equals(productCode))
-            );
-    }
-    public Flux<ClosingProgressEvent> getClosingProgressFlux(String closingId) {
-        return closingProgressSink.asFlux()
-            .filter(event -> event.closingId().equals(closingId));
-    }
-}
-```
-</details>
----
-### 16.4 受注リゾルバの実装（Subscription 対応）
-<details>
-<summary>コード例: OrderResolver.java</summary>
-```java
-package com.example.sales.infrastructure.graphql.resolver;
-import com.example.sales.application.port.in.OrderUseCase;
-import com.example.sales.domain.event.OrderStatusChangedEvent;
-import com.example.sales.domain.model.order.*;
-import com.example.sales.infrastructure.graphql.dto.*;
-import com.example.sales.infrastructure.graphql.subscription.GraphQLEventPublisher;
-import org.springframework.graphql.data.method.annotation.*;
-import org.springframework.stereotype.Controller;
-import reactor.core.publisher.Flux;
-import java.util.List;
-/**
- * 受注 GraphQL リゾルバ
- */
-@Controller
-public class OrderResolver {
-    private final OrderUseCase orderUseCase;
-    private final GraphQLEventPublisher eventPublisher;
-    public OrderResolver(OrderUseCase orderUseCase,
-                         GraphQLEventPublisher eventPublisher) {
-        this.orderUseCase = orderUseCase;
-        this.eventPublisher = eventPublisher;
-    }
-    // === Query ===
-    @QueryMapping
-    public Order order(@Argument String orderNumber) {
-        return orderUseCase.findByNumber(orderNumber).orElse(null);
-    }
-    @QueryMapping
-    public OrderConnection orders(
-            @Argument String status,
-            @Argument String partnerCode,
-            @Argument Integer page,
-            @Argument Integer size) {
-        int pageNum = page != null ? page : 0;
-        int pageSize = size != null ? size : 20;
-        OrderStatus orderStatus = status != null ? OrderStatus.valueOf(status) : null;
-        List<Order> orders = orderUseCase.findAll(orderStatus, partnerCode, pageNum, pageSize);
-        long totalCount = orderUseCase.count(orderStatus, partnerCode);
-        return OrderConnection.of(orders, pageNum, pageSize, totalCount);
-    }
-    // === Mutation ===
-    @MutationMapping
-    public Order createOrder(@Argument CreateOrderInput input) {
-        return orderUseCase.create(
-            input.partnerCode(),
-            input.orderDate(),
-            input.deliveryDate(),
-            input.warehouseCode(),
-            input.salesPersonCode(),
-            input.remarks(),
-            input.details()
-        );
-    }
-    @MutationMapping
-    public Order confirmOrder(@Argument String orderNumber) {
-        Order order = orderUseCase.confirm(orderNumber);
-        // イベント発行
-        eventPublisher.publishOrderStatusChanged(
-            OrderStatusChangedEvent.of(
-                orderNumber,
-                OrderStatus.DRAFT,
-                OrderStatus.CONFIRMED,
-                "system"
-            )
-        );
-        return order;
-    }
-    @MutationMapping
-    public Order cancelOrder(@Argument String orderNumber, @Argument String reason) {
-        Order order = orderUseCase.cancel(orderNumber, reason);
-        // イベント発行
-        eventPublisher.publishOrderStatusChanged(
-            OrderStatusChangedEvent.withReason(
-                orderNumber,
-                order.getStatus(),
-                OrderStatus.CANCELLED,
-                "system",
-                reason
-            )
-        );
-        return order;
-    }
-    // === Subscription ===
-    @SubscriptionMapping
-    public Flux<OrderStatusChangedEvent> orderStatusChanged(
-            @Argument String orderNumber) {
-        return eventPublisher.getOrderStatusChangedFlux(orderNumber);
-    }
-}
-```
-</details>
----
-### 16.5 GraphiQL によるトランザクション操作
-<details>
-<summary>コード例: GraphQL クエリ/ミューテーション/サブスクリプション</summary>
-```graphql
-# 受注登録
-mutation CreateOrder {
-  createOrder(input: {
-    partnerCode: "CUS001"
-    orderDate: "2025-12-29"
-    deliveryDate: "2026-01-05"
-    warehouseCode: "WH001"
-    details: [
-      { productCode: "PRD001", quantity: 10, unitPrice: 1000 }
-      { productCode: "PRD002", quantity: 5, unitPrice: 2000 }
-    ]
-  }) {
-    orderNumber
-    status
-    totalAmount
-    details {
-      productCode
-      quantity
-      amount
-    }
-  }
-}
-# 受注確定
-mutation ConfirmOrder {
-  confirmOrder(orderNumber: "ORD20251229001") {
-    orderNumber
-    status
-    partner {
-      partnerName
-    }
-  }
-}
-# 受注ステータス監視（Subscription）
-subscription WatchOrderStatus {
-  orderStatusChanged(orderNumber: "ORD20251229001") {
-    orderNumber
-    previousStatus
-    currentStatus
-    changedAt
-    changedBy
-    reason
-  }
-}
-# 在庫変動監視
-subscription WatchInventory {
-  inventoryChanged(warehouseCode: "WH001") {
-    warehouseCode
-    productCode
-    changeType
-    quantity
-    previousQuantity
-    currentQuantity
-    timestamp
-  }
-}
-```
-</details>
----
-## 第17章：エラーハンドリングとベストプラクティス
-### 17.1 GraphQL エラーハンドリング
-GraphQL のエラーレスポンスは標準化された構造を持ちます：
-<details>
-<summary>コード例: エラーレスポンス構造</summary>
-```json
-{
-  "errors": [
-    {
-      "message": "商品コードが重複しています",
-      "locations": [{ "line": 2, "column": 3 }],
-      "path": ["createProduct"],
-      "extensions": {
-        "classification": "VALIDATION_ERROR",
-        "code": "PRODUCT_CODE_DUPLICATE",
-        "field": "productCode"
-      }
-    }
-  ],
-  "data": null
-}
-```
-</details>
-#### カスタム例外クラス
-<details>
-<summary>コード例: GraphQLErrorCode.java</summary>
-```java
-package com.example.sales.application.exception;
-public enum GraphQLErrorCode {
-    // バリデーションエラー
-    VALIDATION_ERROR("VALIDATION_ERROR"),
-    REQUIRED_FIELD_MISSING("REQUIRED_FIELD_MISSING"),
-    INVALID_FORMAT("INVALID_FORMAT"),
-    VALUE_OUT_OF_RANGE("VALUE_OUT_OF_RANGE"),
-    DUPLICATE_VALUE("DUPLICATE_VALUE"),
-    // ビジネスロジックエラー
-    BUSINESS_RULE_VIOLATION("BUSINESS_RULE_VIOLATION"),
-    INSUFFICIENT_STOCK("INSUFFICIENT_STOCK"),
-    INVALID_STATUS_TRANSITION("INVALID_STATUS_TRANSITION"),
-    CREDIT_LIMIT_EXCEEDED("CREDIT_LIMIT_EXCEEDED"),
-    // リソースエラー
-    NOT_FOUND("NOT_FOUND"),
-    ALREADY_EXISTS("ALREADY_EXISTS"),
-    CONFLICT("CONFLICT"),
-    // 認証・認可エラー
-    UNAUTHORIZED("UNAUTHORIZED"),
-    FORBIDDEN("FORBIDDEN"),
-    // システムエラー
-    INTERNAL_ERROR("INTERNAL_ERROR"),
-    SERVICE_UNAVAILABLE("SERVICE_UNAVAILABLE");
-    private final String code;
-    GraphQLErrorCode(String code) {
-        this.code = code;
-    }
-    public String getCode() {
-        return code;
-    }
-}
-```
-</details>
-<details>
-<summary>コード例: GraphQLBusinessException.java</summary>
-```java
-package com.example.sales.application.exception;
-import graphql.ErrorClassification;
-import graphql.GraphQLError;
-import graphql.language.SourceLocation;
-import java.util.HashMap;
-import java.util.List;
-import java.util.Map;
-public class GraphQLBusinessException extends RuntimeException implements GraphQLError {
-    private final GraphQLErrorCode errorCode;
-    private final String field;
-    private final Map<String, Object> additionalData;
-    public GraphQLBusinessException(String message, GraphQLErrorCode errorCode) {
-        this(message, errorCode, null, null);
-    }
-    public GraphQLBusinessException(String message, GraphQLErrorCode errorCode, String field) {
-        this(message, errorCode, field, null);
-    }
-    public GraphQLBusinessException(
-            String message,
-            GraphQLErrorCode errorCode,
-            String field,
-            Map<String, Object> additionalData) {
-        super(message);
-        this.errorCode = errorCode;
-        this.field = field;
-        this.additionalData = additionalData != null ? additionalData : new HashMap<>();
-    }
-    @Override
-    public List<SourceLocation> getLocations() {
-        return null;
-    }
-    @Override
-    public ErrorClassification getErrorType() {
-        return CustomErrorClassification.fromCode(errorCode);
-    }
-    @Override
-    public Map<String, Object> getExtensions() {
-        Map<String, Object> extensions = new HashMap<>();
-        extensions.put("code", errorCode.getCode());
-        extensions.put("classification", getErrorType().toString());
-        if (field != null) {
-            extensions.put("field", field);
-        }
-        extensions.putAll(additionalData);
-        return extensions;
-    }
-}
-```
-</details>
----
-### 17.2 例外リゾルバ
-<details>
-<summary>コード例: GraphQLExceptionResolver.java</summary>
-```java
-package com.example.sales.infrastructure.graphql.exception;
-import com.example.sales.application.exception.GraphQLBusinessException;
-import com.example.sales.application.exception.GraphQLErrorCode;
-import graphql.GraphQLError;
-import graphql.schema.DataFetchingEnvironment;
-import org.springframework.graphql.execution.DataFetcherExceptionResolverAdapter;
-import org.springframework.graphql.execution.ErrorType;
-import org.springframework.stereotype.Component;
-@Component
-public class GraphQLExceptionResolver extends DataFetcherExceptionResolverAdapter {
-    @Override
-    protected GraphQLError resolveToSingleError(Throwable ex, DataFetchingEnvironment env) {
-        // カスタムビジネス例外
-        if (ex instanceof GraphQLBusinessException businessEx) {
-            return businessEx;
-        }
-        // ドメイン例外をラップ
-        if (ex instanceof IllegalArgumentException) {
-            return new GraphQLBusinessException(
-                ex.getMessage(),
-                GraphQLErrorCode.VALIDATION_ERROR
-            );
-        }
-        if (ex instanceof IllegalStateException) {
-            return new GraphQLBusinessException(
-                ex.getMessage(),
-                GraphQLErrorCode.BUSINESS_RULE_VIOLATION
-            );
-        }
-        // Jakarta Validation 例外
-        if (ex instanceof jakarta.validation.ConstraintViolationException cve) {
-            var firstViolation = cve.getConstraintViolations().iterator().next();
-            return new GraphQLBusinessException(
-                firstViolation.getMessage(),
-                GraphQLErrorCode.VALIDATION_ERROR,
-                firstViolation.getPropertyPath().toString()
-            );
-        }
-        // 未知の例外はログ出力して汎用メッセージを返す
-        logger.error("Unexpected error in GraphQL resolver", ex);
-        return GraphQLError.newError()
-            .message("システムエラーが発生しました")
-            .errorType(ErrorType.INTERNAL_ERROR)
-            .build();
-    }
-}
-```
-</details>
----
-### 17.3 入力バリデーション
-#### GraphQL ディレクティブによるバリデーション
-<details>
-<summary>コード例: directives.graphqls</summary>
-```graphql
-# schema/directives.graphqls
-directive @NotBlank(message: String = "必須項目です") on INPUT_FIELD_DEFINITION | ARGUMENT_DEFINITION
-directive @Size(min: Int = 0, max: Int = 255, message: String) on INPUT_FIELD_DEFINITION | ARGUMENT_DEFINITION
-directive @Min(value: Int!, message: String) on INPUT_FIELD_DEFINITION | ARGUMENT_DEFINITION
-directive @Pattern(regexp: String!, message: String) on INPUT_FIELD_DEFINITION | ARGUMENT_DEFINITION
-directive @Email(message: String = "有効なメールアドレスを入力してください") on INPUT_FIELD_DEFINITION | ARGUMENT_DEFINITION
-# 使用例
-input CreateProductInput {
-  productCode: String! @NotBlank @Size(min: 1, max: 16, message: "商品コードは16文字以内で入力してください")
-  productName: String! @NotBlank @Size(max: 100)
-  price: BigDecimal! @Min(value: 0, message: "価格は0以上で入力してください")
-}
-input CreatePartnerInput {
-  partnerCode: String! @NotBlank @Pattern(regexp: "^[A-Z0-9]{4,10}$", message: "取引先コードは英大文字と数字4〜10文字で入力してください")
-  partnerName: String! @NotBlank @Size(max: 100)
-  email: String @Email
-  creditLimit: BigDecimal @Min(value: 0)
-}
-```
-</details>
-#### Jakarta Validation との統合
-<details>
-<summary>コード例: CreateProductInputDto.java</summary>
-```java
-package com.example.sales.application.dto;
-import jakarta.validation.constraints.*;
-import java.math.BigDecimal;
-public record CreateProductInputDto(
-    @NotBlank(message = "商品コードは必須です")
-    @Size(max = 16, message = "商品コードは16文字以内で入力してください")
-    @Pattern(regexp = "^[A-Z0-9]+$", message = "商品コードは英大文字と数字のみ使用可能です")
-    String productCode,
-    @NotBlank(message = "商品名は必須です")
-    @Size(max = 100, message = "商品名は100文字以内で入力してください")
-    String productName,
-    @NotNull(message = "価格は必須です")
-    @DecimalMin(value = "0", message = "価格は0以上で入力してください")
-    @Digits(integer = 10, fraction = 2, message = "価格の形式が正しくありません")
-    BigDecimal price,
-    @Min(value = 0, message = "在庫数は0以上で入力してください")
-    Integer stockQuantity,
-    @Size(max = 500, message = "備考は500文字以内で入力してください")
-    String notes
-) {}
-```
-</details>
----
-### 17.4 セキュリティ
-#### 認可ディレクティブ
-<details>
-<summary>コード例: 認可ディレクティブ</summary>
-```graphql
-# スキーマレベルでの認可定義
-directive @auth(
-  roles: [String!]!
-) on FIELD_DEFINITION
-type Mutation {
-  # 管理者のみ
-  deleteProduct(productCode: ID!): Boolean! @auth(roles: ["ADMIN"])
-  # 営業担当と管理者
-  createOrder(input: CreateOrderInput!): Order! @auth(roles: ["SALES", "ADMIN"])
-  # 経理担当と管理者
-  executeClosing(input: ExecuteClosingInput!): ClosingResult! @auth(roles: ["ACCOUNTING", "ADMIN"])
-}
-```
-</details>
-#### クエリ深度制限
-<details>
-<summary>コード例: クエリ深度制限</summary>
-```java
-@Bean
-public Instrumentation maxQueryDepthInstrumentation() {
-    return new MaxQueryDepthInstrumentation(10);
-}
-@Bean
-public Instrumentation maxQueryComplexityInstrumentation() {
-    return new MaxQueryComplexityInstrumentation(100);
-}
-```
-</details>
----
-### 17.5 運用のベストプラクティス
-#### ログインターセプター
-<details>
-<summary>コード例: GraphQLLoggingInterceptor.java</summary>
-```java
-@Component
-public class GraphQLLoggingInterceptor implements WebGraphQlInterceptor {
-    private static final Logger logger = LoggerFactory.getLogger(GraphQLLoggingInterceptor.class);
-    @Override
-    public Mono<WebGraphQlResponse> intercept(WebGraphQlRequest request, Chain chain) {
-        String requestId = UUID.randomUUID().toString().substring(0, 8);
-        String operationName = request.getOperationName();
-        Instant start = Instant.now();
-        MDC.put("requestId", requestId);
-        MDC.put("operationName", operationName);
-        logger.info("GraphQL リクエスト開始: operation={}", operationName);
-        return chain.next(request)
-            .doOnNext(response -> {
-                Duration duration = Duration.between(start, Instant.now());
-                if (response.getErrors().isEmpty()) {
-                    logger.info("GraphQL リクエスト完了: operation={}, duration={}ms",
-                        operationName, duration.toMillis());
-                } else {
-                    logger.warn("GraphQL リクエスト完了（エラーあり）: operation={}, duration={}ms, errors={}",
-                        operationName, duration.toMillis(), response.getErrors().size());
-                }
-            })
-            .doFinally(signalType -> {
-                MDC.remove("requestId");
-                MDC.remove("operationName");
-            });
-    }
-}
-```
-</details>
-#### メトリクス収集
-<details>
-<summary>コード例: GraphQLMetricsCollector.java</summary>
-```java
-@Component
-public class GraphQLMetricsCollector implements WebGraphQlInterceptor {
-    private final Timer queryTimer;
-    private final Timer mutationTimer;
-    private final Counter errorCounter;
-    private final Counter successCounter;
-    public GraphQLMetricsCollector(MeterRegistry registry) {
-        this.queryTimer = Timer.builder("graphql.query.duration")
-            .description("GraphQL クエリ実行時間")
-            .register(registry);
-        this.mutationTimer = Timer.builder("graphql.mutation.duration")
-            .description("GraphQL ミューテーション実行時間")
-            .register(registry);
-        this.errorCounter = Counter.builder("graphql.errors")
-            .description("GraphQL エラー数")
-            .register(registry);
-        this.successCounter = Counter.builder("graphql.success")
-            .description("GraphQL 成功数")
-            .register(registry);
-    }
-    @Override
-    public Mono<WebGraphQlResponse> intercept(WebGraphQlRequest request, Chain chain) {
-        Timer timer = request.getDocument().contains("mutation")
-            ? mutationTimer
-            : queryTimer;
-        return Mono.fromSupplier(timer::start)
-            .flatMap(sample -> chain.next(request)
-                .doOnNext(response -> {
-                    sample.stop(timer);
-                    if (response.getErrors().isEmpty()) {
-                        successCounter.increment();
-                    } else {
-                        errorCounter.increment(response.getErrors().size());
-                    }
-                })
-            );
-    }
-}
-```
-</details>
----
-## Part 10-E のまとめ
-### 実装した機能一覧
-| 章 | 内容 | 主要技術 |
-|---|---|---|
-| **第14章: 基礎** | GraphQL サーバーの基礎 | Spring for GraphQL, スキーマ駆動開発 |
-| **第15章: マスタ API** | N+1 問題対策、ページネーション | DataLoader, Connection パターン |
-| **第16章: トランザクション API** | リアルタイム通知、非同期処理 | Subscription, Reactor Sinks |
-| **第17章: エラーハンドリング** | バリデーション、セキュリティ | ディレクティブ, Jakarta Validation |
-### 実装した GraphQL 操作
-- **Query**: 商品・取引先・倉庫・受注・出荷・請求の取得
-- **Mutation**: CRUD 操作、受注確定、出荷確定、締処理
-- **Subscription**: 受注ステータス変更、出荷進捗、在庫変動、締処理進捗
-### アーキテクチャの特徴
-```plantuml
-@startuml
-package "Adapter Layer (in)" {
-    [GraphQL Resolver] as resolver
-    [Exception Resolver] as exception_resolver
-    [Validation Directive] as validation
-    [DataLoader Registry] as dataloader
-    [Logging Interceptor] as logging
-    [Metrics Collector] as metrics
-}
-package "Application Layer" {
-    [UseCase] as usecase
-    [DTO] as dto
-    [Exception] as app_exception
-}
-package "Domain Layer" {
-    [Domain Model] as domain
-    [Domain Service] as domain_service
-    [Repository Interface] as repo_interface
-}
-package "Adapter Layer (out)" {
-    [Repository Implementation] as repo_impl
-    [MyBatis Mapper] as mapper
-}
-database "PostgreSQL" as db
-' Interceptor チェーン
-logging --> metrics
-metrics --> resolver
-' バリデーション
-validation --> resolver
-' メイン処理フロー
-resolver --> usecase
-resolver --> dataloader
-usecase --> domain_service
-usecase --> repo_interface
-domain_service --> domain
-repo_interface <|.. repo_impl
-repo_impl --> mapper
-mapper --> db
-' 例外処理
-resolver ..> exception_resolver : throws
-usecase ..> app_exception : throws
-' DataLoader
-dataloader --> repo_interface
-@enduml
-```
-### 技術スタック
-| カテゴリ | 技術 |
-|---------|------|
-| **言語** | Java 21 |
-| **フレームワーク** | Spring Boot 4.0, Spring for GraphQL |
-| **リアルタイム** | WebSocket, Reactor (Sinks) |
-| **ORM** | MyBatis 3.0 |
-| **データベース** | PostgreSQL 16 |
-| **テスト** | JUnit 5, spring-graphql-test, TestContainers |
-### API 形式の比較と選択基準
-| 観点 | REST API | gRPC | GraphQL |
-|------|----------|------|---------|
-| **データ取得** | 固定レスポンス | 固定レスポンス | クライアント指定 |
-| **エンドポイント** | 複数 | 複数 | 単一 |
-| **Over-fetching** | 発生しやすい | 発生しやすい | 防止可能 |
-| **Under-fetching** | 発生しやすい | 発生しやすい | 防止可能 |
-| **リアルタイム** | WebSocket 別実装 | ストリーミング | Subscription |
-| **N+1 問題** | 発生しにくい | 発生しにくい | DataLoader で解決 |
-| **主な用途** | 汎用 API | マイクロサービス | フロントエンド向け |
-### GraphQL を選択する場面
-1. **複雑なデータ構造**: 関連データを柔軟に取得したい
-2. **フロントエンド主導**: クライアントが必要なデータを指定したい
-3. **Over-fetching 回避**: 帯域幅の節約が重要
-4. **リアルタイム通知**: Subscription による統一的な通知機構が必要
-5. **API 統合**: 複数のバックエンドを単一 API で公開したい
-GraphQL は REST API と比較して、クライアントが必要なデータを柔軟に取得できる点が大きな利点です。特に複雑なデータ構造を持つ販売管理システムでは、DataLoader と Subscription を活用することで、効率的かつリアルタイムな API を提供できます。
+# 実践データベース設計：販売管理システム 研究 4 - GraphQL サービスの実装
+## はじめに
+本研究では、REST API（第10部-A）や gRPC（研究 3）とは異なるアプローチとして、**GraphQL** による販売管理システムを実装します。クライアントが必要なデータを正確に指定できる柔軟なクエリと、リアルタイム更新を実現する Subscription を活用します。
+研究 1 で構築したヘキサゴナルアーキテクチャ（ドメイン層・アプリケーション層）はそのまま共有し、**Input Adapter として GraphQL リゾルバ層のみを追加**します。
+---
+## 第14章：GraphQL サーバーの基礎
+### 14.1 GraphQL とは
+GraphQL は Facebook が開発したクエリ言語および実行エンジンです。クライアントが必要なデータの形状を指定でき、Over-fetching（不要なデータの取得）や Under-fetching（必要なデータの不足）を防ぎます。
+```plantuml
+@startuml graphql_architecture
+!define RECTANGLE class
+skinparam backgroundColor #FEFEFE
+package "GraphQL Architecture (販売管理システム)" {
+  package "Client Side" {
+    RECTANGLE "GraphQL Client\n(Apollo/Relay/urql)" as client {
+      - Query (読み取り)
+      - Mutation (書き込み)
+      - Subscription (リアルタイム)
+    }
+  }
+  package "Server Side" {
+    RECTANGLE "GraphQL Server\n(Spring for GraphQL)" as server {
+      - ProductResolver
+      - PartnerResolver
+      - OrderResolver
+      - InvoiceResolver
+    }
+  }
+  package "Shared" {
+    RECTANGLE "GraphQL Schema\n(.graphqls files)" as schema {
+      - schema.graphqls
+      - product.graphqls
+      - partner.graphqls
+      - order.graphqls
+    }
+  }
+}
+client --> schema : "スキーマに基づいて\nクエリを構築"
+server --> schema : "スキーマに基づいて\nリゾルバを実装"
+client <--> server : "HTTP/WebSocket\n(JSON)"
+note bottom of schema
+  スキーマ駆動開発
+  クライアント主導のデータ取得
+  型安全な API
+end note
+@enduml
+```
+**REST API / gRPC / GraphQL の比較：**
+| 特徴 | REST API | gRPC | GraphQL |
+|------|----------|------|---------|
+| プロトコル | HTTP/1.1 | HTTP/2 | HTTP/1.1 or HTTP/2 |
+| データ形式 | JSON | Protocol Buffers | JSON |
+| スキーマ | OpenAPI (任意) | .proto (必須) | .graphqls (必須) |
+| データ取得 | 固定レスポンス | 固定レスポンス | クライアント指定 |
+| エンドポイント | 複数 | 複数 | 単一 |
+| リアルタイム | WebSocket 別実装 | ストリーミング | Subscription |
+| 主な用途 | 汎用 API | マイクロサービス | フロントエンド向け |
+---
+### 14.2 3つの操作タイプ
+GraphQL は 3 つの操作タイプをサポートします：
+```plantuml
+@startuml graphql_operations
+skinparam backgroundColor #FEFEFE
+rectangle "1. Query\n(読み取り)" as query #LightBlue {
+}
+note right of query
+  { products { code name price } }
+  → { products: [...] }
+  データの取得
+  複数リソースを1回で取得可能
+end note
+rectangle "2. Mutation\n(書き込み)" as mutation #LightGreen {
+}
+note right of mutation
+  mutation { createOrder(...) }
+  → { createOrder: {...} }
+  データの作成・更新・削除
+end note
+rectangle "3. Subscription\n(リアルタイム)" as subscription #LightCoral {
+}
+note right of subscription
+  subscription { orderStatusChanged }
+  → (WebSocket でプッシュ通知)
+  リアルタイム更新の受信
+end note
+query -[hidden]-> mutation
+mutation -[hidden]-> subscription
+@enduml
+```
+**用途：**
+1. **Query**: データ取得（商品一覧、受注明細、在庫照会）
+2. **Mutation**: データ更新（受注登録、出荷確定、入金処理）
+3. **Subscription**: リアルタイム通知（受注ステータス変更、在庫変動）
+---
+### 14.3 GraphQL におけるヘキサゴナルアーキテクチャ
+GraphQL を導入しても、既存のヘキサゴナルアーキテクチャ（ドメイン層・アプリケーション層）はそのまま共有し、**Input Adapter として GraphQL リゾルバ層のみを追加**します。
+```plantuml
+@startuml hexagonal_graphql
+!define RECTANGLE class
+package "Hexagonal Architecture (GraphQL版)" {
+  RECTANGLE "Application Core\n(Domain + Use Cases)" as core {
+    - Product (商品)
+    - Partner (取引先)
+    - Order (受注)
+    - Shipment (出荷)
+    - Invoice (請求)
+    - ProductUseCase
+    - OrderUseCase
+    - InvoiceUseCase
+  }
+  RECTANGLE "Input Adapters\n(Driving Side)" as input {
+    - REST Controller（既存）
+    - gRPC Service（既存）
+    - GraphQL Resolver（新規追加）
+    - DataFetcher
+    - DataLoader
+  }
+  RECTANGLE "Output Adapters\n(Driven Side)" as output {
+    - MyBatis Repository
+    - Database Access
+    - Entity Mapping
+  }
+}
+input --> core : "Input Ports\n(Use Cases)"
+core --> output : "Output Ports\n(Repository Interfaces)"
+note top of core
+  既存のビジネスロジック
+  REST API / gRPC 版と完全に共有
+  GraphQL 固有のコードは含まない
+end note
+note left of input
+  GraphQL リゾルバを
+  Input Adapter として追加
+  既存の REST/gRPC と共存可能
+end note
+@enduml
+```
+**GraphQL でもヘキサゴナルアーキテクチャを維持する理由：**
+1. **再利用性**: 既存の UseCase/Repository をそのまま活用
+2. **並行運用**: REST API、gRPC、GraphQL を同時提供可能
+3. **テスト容易性**: ドメインロジックは通信プロトコルに依存しない
+4. **移行容易性**: 段階的に API 形式を追加・変更可能
+---
+### 14.4 ディレクトリ構成
+既存の構成に `infrastructure/graphql/` を追加するだけです。
+<details>
+<summary>コード例: ディレクトリ構成</summary>
+```
+src/main/java/com/example/sales/
+├── domain/                     # ドメイン層（API版と共通）
+│   ├── model/
+│   │   ├── product/
+│   │   ├── partner/
+│   │   ├── order/
+│   │   ├── shipment/
+│   │   └── invoice/
+│   └── exception/
+│
+├── application/               # アプリケーション層（API版と共通）
+│   ├── port/
+│   │   ├── in/               # Input Port（ユースケース）
+│   │   └── out/              # Output Port（リポジトリ）
+│   └── service/
+│
+├── infrastructure/
+│   ├── persistence/          # Output Adapter（DB実装）- 既存
+│   │   ├── mapper/
+│   │   └── repository/
+│   ├── rest/                 # Input Adapter（REST実装）- 既存
+│   ├── grpc/                 # Input Adapter（gRPC実装）- 既存
+│   └── graphql/              # Input Adapter（GraphQL実装）- 新規追加
+│       ├── resolver/         # Query/Mutation リゾルバ
+│       ├── dataloader/       # N+1 問題対策
+│       ├── scalar/           # カスタムスカラー型
+│       └── subscription/     # Subscription ハンドラ
+│
+├── config/
+│
+└── src/main/resources/
+    └── graphql/              # GraphQL スキーマ定義
+        ├── schema.graphqls
+        ├── product.graphqls
+        ├── partner.graphqls
+        ├── order.graphqls
+        ├── shipment.graphqls
+        └── invoice.graphqls
+```
+</details>
+---
+### 14.5 技術スタックの追加
+既存の `build.gradle.kts` に GraphQL 関連の依存関係を追加します。
+#### build.gradle.kts（差分）
+<details>
+<summary>コード例: build.gradle.kts</summary>
+```kotlin
+dependencies {
+    // 既存の依存関係（Spring Boot, MyBatis, PostgreSQL等）はそのまま
+    // GraphQL 関連を追加
+    implementation("org.springframework.boot:spring-boot-starter-graphql")
+    implementation("org.springframework.boot:spring-boot-starter-websocket")  // Subscription 用
+    // GraphQL 拡張
+    implementation("com.graphql-java:graphql-java-extended-scalars:21.0")
+    // Test
+    testImplementation("org.springframework.graphql:spring-graphql-test")
+}
+```
+</details>
+**追加パッケージの説明：**
+| パッケージ | 用途 |
+|-----------|------|
+| spring-boot-starter-graphql | Spring Boot GraphQL 統合 |
+| spring-boot-starter-websocket | Subscription (WebSocket) |
+| graphql-java-extended-scalars | DateTime, BigDecimal 等のスカラー型 |
+| spring-graphql-test | GraphQL テストサポート |
+#### application.yml（差分）
+<details>
+<summary>コード例: application.yml</summary>
+```yaml
+spring:
+  graphql:
+    graphiql:
+      enabled: true
+      path: /graphiql
+    websocket:
+      path: /graphql
+      connection-init-timeout: 60s
+      keep-alive:
+        enabled: true
+        interval: 30s
+    schema:
+      printer:
+        enabled: true
+      locations:
+        - classpath:graphql/
+    cors:
+      allowed-origins: "*"
+      allowed-methods: GET, POST
+```
+</details>
+---
+### 14.6 GraphQL 設定クラス
+<details>
+<summary>コード例: GraphQLConfig.java</summary>
+```java
+package com.example.sales.config;
+import graphql.scalars.ExtendedScalars;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.graphql.execution.RuntimeWiringConfigurer;
+/**
+ * GraphQL 設定
+ */
+@Configuration
+public class GraphQLConfig {
+    @Bean
+    public RuntimeWiringConfigurer runtimeWiringConfigurer() {
+        return wiringBuilder -> wiringBuilder
+            .scalar(ExtendedScalars.Date)
+            .scalar(ExtendedScalars.DateTime)
+            .scalar(ExtendedScalars.GraphQLBigDecimal)
+            .scalar(ExtendedScalars.GraphQLLong);
+    }
+}
+```
+</details>
+---
+### 14.7 GraphQL スキーマ定義
+#### src/main/resources/graphql/schema.graphqls
+<details>
+<summary>コード例: schema.graphqls</summary>
+```graphql
+# ルートスキーマ
+type Query {
+    # 商品
+    product(productCode: ID!): Product
+    products(category: ProductCategory, page: Int, size: Int): ProductConnection!
+    # 取引先
+    partner(partnerCode: ID!): Partner
+    partners(type: PartnerType, page: Int, size: Int): PartnerConnection!
+    # 倉庫
+    warehouse(warehouseCode: ID!): Warehouse
+    warehouses(page: Int, size: Int): WarehouseConnection!
+    # 受注
+    order(orderNumber: ID!): Order
+    orders(status: OrderStatus, partnerCode: ID, page: Int, size: Int): OrderConnection!
+    # 出荷
+    shipment(shipmentNumber: ID!): Shipment
+    shipments(status: ShipmentStatus, page: Int, size: Int): ShipmentConnection!
+    # 請求
+    invoice(invoiceNumber: ID!): Invoice
+    invoices(status: InvoiceStatus, partnerCode: ID, page: Int, size: Int): InvoiceConnection!
+}
+type Mutation {
+    # 商品
+    createProduct(input: CreateProductInput!): Product!
+    updateProduct(input: UpdateProductInput!): Product!
+    deleteProduct(productCode: ID!): Boolean!
+    # 取引先
+    createPartner(input: CreatePartnerInput!): Partner!
+    updatePartner(input: UpdatePartnerInput!): Partner!
+    # 受注
+    createOrder(input: CreateOrderInput!): Order!
+    confirmOrder(orderNumber: ID!): Order!
+    cancelOrder(orderNumber: ID!, reason: String): Order!
+    # 出荷
+    createShipment(input: CreateShipmentInput!): Shipment!
+    startPicking(shipmentNumber: ID!): Shipment!
+    confirmShipment(shipmentNumber: ID!): Shipment!
+    # 請求
+    executeClosing(input: ExecuteClosingInput!): ClosingResult!
+    issueInvoice(invoiceNumber: ID!): Invoice!
+    recordReceipt(input: RecordReceiptInput!): Receipt!
+}
+type Subscription {
+    # 受注ステータス変更
+    orderStatusChanged(orderNumber: ID): OrderStatusChange!
+    # 出荷進捗
+    shipmentProgressUpdated(shipmentNumber: ID): ShipmentProgress!
+    # 在庫変動
+    inventoryChanged(warehouseCode: ID, productCode: ID): InventoryChange!
+    # 締処理進捗
+    closingProgressUpdated(closingId: ID!): ClosingProgress!
+}
+# ページネーション共通型
+type PageInfo {
+    hasNextPage: Boolean!
+    hasPreviousPage: Boolean!
+    totalElements: Int!
+    totalPages: Int!
+    currentPage: Int!
+}
+# カスタムスカラー
+scalar Date
+scalar DateTime
+scalar BigDecimal
+scalar Long
+```
+</details>
+#### src/main/resources/graphql/product.graphqls
+<details>
+<summary>コード例: product.graphqls</summary>
+```graphql
+# 商品区分
+enum ProductCategory {
+    PRODUCT      # 製品
+    MATERIAL     # 原材料
+    PART         # 部品
+}
+# 税区分
+enum TaxCategory {
+    TAXABLE      # 課税
+    TAX_EXEMPT   # 非課税
+    TAX_FREE     # 免税
+}
+# 商品
+type Product {
+    productCode: ID!
+    productName: String!
+    productNameKana: String
+    category: ProductCategory!
+    taxCategory: TaxCategory!
+    unitCode: String
+    sellingPrice: BigDecimal!
+    purchasePrice: BigDecimal
+    costPrice: BigDecimal
+    safetyStock: Int
+    reorderPoint: Int
+    isActive: Boolean!
+    createdAt: DateTime!
+    updatedAt: DateTime!
+    # 関連データ（必要な場合のみ取得）
+    inventories: [Inventory!]!
+    classifications: [ProductClassification!]!
+    customerPrices: [CustomerPrice!]!
+}
+# 商品一覧（ページネーション付き）
+type ProductConnection {
+    edges: [ProductEdge!]!
+    pageInfo: PageInfo!
+}
+type ProductEdge {
+    node: Product!
+    cursor: String!
+}
+# 入力型
+input CreateProductInput {
+    productCode: ID!
+    productName: String!
+    productNameKana: String
+    category: ProductCategory!
+    taxCategory: TaxCategory!
+    unitCode: String
+    sellingPrice: BigDecimal!
+    purchasePrice: BigDecimal
+    costPrice: BigDecimal
+    safetyStock: Int
+    reorderPoint: Int
+}
+input UpdateProductInput {
+    productCode: ID!
+    productName: String
+    category: ProductCategory
+    taxCategory: TaxCategory
+    sellingPrice: BigDecimal
+    isActive: Boolean
+}
+```
+</details>
+#### src/main/resources/graphql/order.graphqls
+<details>
+<summary>コード例: order.graphqls</summary>
+```graphql
+# 受注ステータス
+enum OrderStatus {
+    DRAFT        # 仮登録
+    CONFIRMED    # 確定
+    SHIPPED      # 出荷済
+    CANCELLED    # キャンセル
+}
+# 受注
+type Order {
+    orderNumber: ID!
+    partnerCode: ID!
+    orderDate: Date!
+    deliveryDate: Date!
+    warehouseCode: ID!
+    status: OrderStatus!
+    totalAmount: BigDecimal!
+    taxAmount: BigDecimal!
+    grandTotal: BigDecimal!
+    salesPersonCode: String
+    remarks: String
+    createdAt: DateTime!
+    updatedAt: DateTime!
+    # 関連データ
+    partner: Partner!
+    warehouse: Warehouse!
+    details: [OrderDetail!]!
+    shipments: [Shipment!]!
+}
+# 受注明細
+type OrderDetail {
+    orderNumber: ID!
+    lineNumber: Int!
+    productCode: ID!
+    quantity: Int!
+    unitPrice: BigDecimal!
+    amount: BigDecimal!
+    taxCategory: TaxCategory!
+    deliveryDate: Date
+    remarks: String
+    # 関連データ
+    product: Product!
+}
+# 受注ステータス変更イベント
+type OrderStatusChange {
+    orderNumber: ID!
+    previousStatus: OrderStatus!
+    currentStatus: OrderStatus!
+    changedBy: String
+    changedAt: DateTime!
+    reason: String
+}
+# 入力型
+input CreateOrderInput {
+    partnerCode: ID!
+    orderDate: Date!
+    deliveryDate: Date!
+    warehouseCode: ID!
+    salesPersonCode: String
+    remarks: String
+    details: [OrderDetailInput!]!
+}
+input OrderDetailInput {
+    productCode: ID!
+    quantity: Int!
+    unitPrice: BigDecimal
+    deliveryDate: Date
+    remarks: String
+}
+```
+</details>
+---
+### 14.8 基本的なリゾルバの実装
+#### Query リゾルバ
+<details>
+<summary>コード例: QueryResolver.java</summary>
+```java
+package com.example.sales.infrastructure.graphql.resolver;
+import com.example.sales.application.port.in.ProductUseCase;
+import com.example.sales.application.port.in.PartnerUseCase;
+import com.example.sales.domain.model.product.Product;
+import com.example.sales.domain.model.partner.Partner;
+import com.example.sales.infrastructure.graphql.dto.*;
+import org.springframework.graphql.data.method.annotation.Argument;
+import org.springframework.graphql.data.method.annotation.QueryMapping;
+import org.springframework.stereotype.Controller;
+import java.util.List;
+/**
+ * GraphQL Query リゾルバ
+ */
+@Controller
+public class QueryResolver {
+    private final ProductUseCase productUseCase;
+    private final PartnerUseCase partnerUseCase;
+    public QueryResolver(ProductUseCase productUseCase, PartnerUseCase partnerUseCase) {
+        this.productUseCase = productUseCase;
+        this.partnerUseCase = partnerUseCase;
+    }
+    // === 商品 ===
+    @QueryMapping
+    public Product product(@Argument String productCode) {
+        return productUseCase.findByCode(productCode).orElse(null);
+    }
+    @QueryMapping
+    public ProductConnection products(
+            @Argument String category,
+            @Argument Integer page,
+            @Argument Integer size) {
+        int pageNum = page != null ? page : 0;
+        int pageSize = size != null ? size : 20;
+        List<Product> products = productUseCase.findAll(category, pageNum, pageSize);
+        long totalCount = productUseCase.count(category);
+        return ProductConnection.of(products, pageNum, pageSize, totalCount);
+    }
+    // === 取引先 ===
+    @QueryMapping
+    public Partner partner(@Argument String partnerCode) {
+        return partnerUseCase.findByCode(partnerCode).orElse(null);
+    }
+    @QueryMapping
+    public PartnerConnection partners(
+            @Argument String type,
+            @Argument Integer page,
+            @Argument Integer size) {
+        int pageNum = page != null ? page : 0;
+        int pageSize = size != null ? size : 20;
+        List<Partner> partners = partnerUseCase.findAll(type, pageNum, pageSize);
+        long totalCount = partnerUseCase.count(type);
+        return PartnerConnection.of(partners, pageNum, pageSize, totalCount);
+    }
+}
+```
+</details>
+#### Connection DTO（ページネーション）
+<details>
+<summary>コード例: ProductConnection.java</summary>
+```java
+package com.example.sales.infrastructure.graphql.dto;
+import com.example.sales.domain.model.product.Product;
+import java.util.Base64;
+import java.util.List;
+/**
+ * 商品ページネーション結果（Connection パターン）
+ */
+public record ProductConnection(
+    List<ProductEdge> edges,
+    PageInfo pageInfo
+) {
+    public static ProductConnection of(
+            List<Product> products,
+            int page,
+            int size,
+            long totalCount) {
+        List<ProductEdge> edges = products.stream()
+            .map(product -> new ProductEdge(
+                product,
+                encodeCursor(product.getProductCode())
+            ))
+            .toList();
+        int totalPages = (int) Math.ceil((double) totalCount / size);
+        PageInfo pageInfo = new PageInfo(
+            page < totalPages - 1,  // hasNextPage
+            page > 0,               // hasPreviousPage
+            totalCount,
+            totalPages,
+            page
+        );
+        return new ProductConnection(edges, pageInfo);
+    }
+    private static String encodeCursor(String productCode) {
+        return Base64.getEncoder().encodeToString(productCode.getBytes());
+    }
+}
+public record ProductEdge(
+    Product node,
+    String cursor
+) {}
+public record PageInfo(
+    boolean hasNextPage,
+    boolean hasPreviousPage,
+    long totalElements,
+    int totalPages,
+    int currentPage
+) {}
+```
+</details>
+---
+### 14.9 Spring for GraphQL の統合テスト
+<details>
+<summary>コード例: QueryResolverTest.java</summary>
+```java
+package com.example.sales.infrastructure.graphql;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.autoconfigure.graphql.tester.AutoConfigureHttpGraphQlTester;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.graphql.test.tester.HttpGraphQlTester;
+import org.springframework.test.context.DynamicPropertyRegistry;
+import org.springframework.test.context.DynamicPropertySource;
+import org.testcontainers.containers.PostgreSQLContainer;
+import org.testcontainers.junit.jupiter.Container;
+import org.testcontainers.junit.jupiter.Testcontainers;
+@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
+@AutoConfigureHttpGraphQlTester
+@Testcontainers
+class QueryResolverTest {
+    @Container
+    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16-alpine");
+    @DynamicPropertySource
+    static void configureProperties(DynamicPropertyRegistry registry) {
+        registry.add("spring.datasource.url", postgres::getJdbcUrl);
+        registry.add("spring.datasource.username", postgres::getUsername);
+        registry.add("spring.datasource.password", postgres::getPassword);
+    }
+    @Autowired
+    private HttpGraphQlTester graphQlTester;
+    @Test
+    void testQueryProduct() {
+        // language=GraphQL
+        String query = """
+            query {
+                product(productCode: "PRD001") {
+                    productCode
+                    productName
+                    sellingPrice
+                    category
+                }
+            }
+            """;
+        graphQlTester.document(query)
+            .execute()
+            .path("product.productCode")
+            .entity(String.class)
+            .isEqualTo("PRD001");
+    }
+    @Test
+    void testQueryProducts() {
+        // language=GraphQL
+        String query = """
+            query {
+                products(category: PRODUCT, page: 0, size: 10) {
+                    edges {
+                        node {
+                            productCode
+                            productName
+                        }
+                        cursor
+                    }
+                    pageInfo {
+                        hasNextPage
+                        totalElements
+                    }
+                }
+            }
+            """;
+        graphQlTester.document(query)
+            .execute()
+            .path("products.edges")
+            .entityList(Object.class)
+            .hasSizeGreaterThan(0);
+    }
+    @Test
+    void testQueryProductWithRelations() {
+        // 関連データも含めて取得
+        // language=GraphQL
+        String query = """
+            query {
+                product(productCode: "PRD001") {
+                    productCode
+                    productName
+                    inventories {
+                        warehouseCode
+                        quantity
+                        availableQuantity
+                    }
+                    classifications {
+                        classificationCode
+                        classificationName
+                    }
+                }
+            }
+            """;
+        graphQlTester.document(query)
+            .execute()
+            .path("product.productCode")
+            .entity(String.class)
+            .isEqualTo("PRD001");
+    }
+}
+```
+</details>
+---
+## 第15章：マスタ API の実装
+### 15.1 N+1 問題とは
+GraphQL では、ネストしたデータを取得する際に **N+1 問題** が発生しやすくなります。例えば、10件の商品を取得し、それぞれの在庫情報を取得すると、1回（商品一覧）+ 10回（各商品の在庫）= 11回のクエリが実行されます。
+```plantuml
+@startuml n_plus_1_problem
+title N+1 問題の発生パターン
+participant "GraphQL Client" as client
+participant "ProductResolver" as resolver
+participant "InventoryRepository" as repo
+database "PostgreSQL" as db
+client -> resolver : products(first: 10)
+resolver -> db : SELECT * FROM 商品マスタ LIMIT 10
+db --> resolver : 10件の商品
+loop 各商品に対して（N回）
+  resolver -> repo : findByProductCode(code)
+  repo -> db : SELECT * FROM 在庫データ WHERE 商品コード = ?
+  db --> repo : 在庫データ
+  repo --> resolver : 在庫
+end
+resolver --> client : 商品一覧（在庫付き）
+note right of db
+  合計 11回のクエリ
+  (1 + N = 1 + 10)
+  商品が100件なら101回！
+end note
+@enduml
+```
+---
+### 15.2 DataLoader による解決
+**DataLoader** は、複数の個別リクエストをバッチ処理にまとめることで N+1 問題を解決します。
+```plantuml
+@startuml dataloader_solution
+title DataLoader による N+1 問題の解決
+participant "GraphQL Client" as client
+participant "ProductResolver" as resolver
+participant "InventoryDataLoader" as loader
+participant "InventoryRepository" as repo
+database "PostgreSQL" as db
+client -> resolver : products(first: 10)
+resolver -> db : SELECT * FROM 商品マスタ LIMIT 10
+db --> resolver : 10件の商品
+loop 各商品に対して
+  resolver -> loader : load(productCode)
+  note right of loader : キューに追加
+end
+loader -> repo : loadMany([code1, code2, ...code10])
+repo -> db : SELECT * FROM 在庫データ WHERE 商品コード IN (?, ?, ..., ?)
+db --> repo : 10件の在庫データ
+repo --> loader : Map<商品コード, 在庫>
+loader --> resolver : 各商品の在庫
+resolver --> client : 商品一覧（在庫付き）
+note right of db
+  合計 2回のクエリ
+  (1 + 1 = 2)
+  商品が100件でも2回！
+end note
+@enduml
+```
+---
+### 15.3 DataLoader の実装
+#### 在庫 DataLoader
+<details>
+<summary>コード例: InventoryDataLoader.java</summary>
+```java
+package com.example.sales.infrastructure.graphql.dataloader;
+import com.example.sales.application.port.out.InventoryRepository;
+import com.example.sales.domain.model.inventory.Inventory;
+import org.dataloader.BatchLoaderEnvironment;
+import org.dataloader.MappedBatchLoader;
+import org.springframework.stereotype.Component;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.CompletionStage;
+import java.util.stream.Collectors;
+/**
+ * 在庫データの DataLoader
+ * 商品コードをキーにバッチ取得
+ */
+@Component
+public class InventoryDataLoader implements MappedBatchLoader<String, List<Inventory>> {
+    private final InventoryRepository inventoryRepository;
+    public InventoryDataLoader(InventoryRepository inventoryRepository) {
+        this.inventoryRepository = inventoryRepository;
+    }
+    @Override
+    public CompletionStage<Map<String, List<Inventory>>> load(
+            Set<String> productCodes,
+            BatchLoaderEnvironment environment) {
+        return CompletableFuture.supplyAsync(() -> {
+            // 一括取得
+            List<Inventory> inventories = inventoryRepository
+                .findByProductCodes(productCodes);
+            // 商品コードでグループ化
+            return inventories.stream()
+                .collect(Collectors.groupingBy(Inventory::getProductCode));
+        });
+    }
+}
+```
+</details>
+#### 取引先 DataLoader
+<details>
+<summary>コード例: PartnerDataLoader.java</summary>
+```java
+package com.example.sales.infrastructure.graphql.dataloader;
+import com.example.sales.application.port.out.PartnerRepository;
+import com.example.sales.domain.model.partner.Partner;
+import org.dataloader.BatchLoaderEnvironment;
+import org.dataloader.MappedBatchLoader;
+import org.springframework.stereotype.Component;
+import java.util.Map;
+import java.util.Set;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.CompletionStage;
+import java.util.function.Function;
+import java.util.stream.Collectors;
+/**
+ * 取引先データの DataLoader
+ */
+@Component
+public class PartnerDataLoader implements MappedBatchLoader<String, Partner> {
+    private final PartnerRepository partnerRepository;
+    public PartnerDataLoader(PartnerRepository partnerRepository) {
+        this.partnerRepository = partnerRepository;
+    }
+    @Override
+    public CompletionStage<Map<String, Partner>> load(
+            Set<String> partnerCodes,
+            BatchLoaderEnvironment environment) {
+        return CompletableFuture.supplyAsync(() -> {
+            return partnerRepository.findByCodes(partnerCodes).stream()
+                .collect(Collectors.toMap(
+                    Partner::getPartnerCode,
+                    Function.identity()
+                ));
+        });
+    }
+}
+```
+</details>
+---
+### 15.4 DataLoader の登録
+<details>
+<summary>コード例: DataLoaderConfig.java</summary>
+```java
+package com.example.sales.config;
+import com.example.sales.infrastructure.graphql.dataloader.*;
+import org.dataloader.DataLoader;
+import org.dataloader.DataLoaderOptions;
+import org.dataloader.DataLoaderRegistry;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.graphql.execution.BatchLoaderRegistry;
+/**
+ * DataLoader 設定
+ */
+@Configuration
+public class DataLoaderConfig {
+    public static final String INVENTORY_LOADER = "inventoryLoader";
+    public static final String PARTNER_LOADER = "partnerLoader";
+    public static final String PRODUCT_LOADER = "productLoader";
+    public static final String WAREHOUSE_LOADER = "warehouseLoader";
+    private final InventoryDataLoader inventoryDataLoader;
+    private final PartnerDataLoader partnerDataLoader;
+    private final ProductDataLoader productDataLoader;
+    private final WarehouseDataLoader warehouseDataLoader;
+    public DataLoaderConfig(
+            InventoryDataLoader inventoryDataLoader,
+            PartnerDataLoader partnerDataLoader,
+            ProductDataLoader productDataLoader,
+            WarehouseDataLoader warehouseDataLoader) {
+        this.inventoryDataLoader = inventoryDataLoader;
+        this.partnerDataLoader = partnerDataLoader;
+        this.productDataLoader = productDataLoader;
+        this.warehouseDataLoader = warehouseDataLoader;
+    }
+    @Bean
+    public BatchLoaderRegistry batchLoaderRegistry() {
+        return new BatchLoaderRegistry() {
+            @Override
+            public void registerDataLoaders(
+                    DataLoaderRegistry registry,
+                    graphql.GraphQLContext context) {
+                DataLoaderOptions options = DataLoaderOptions.newOptions()
+                    .setCachingEnabled(true)
+                    .setBatchingEnabled(true)
+                    .setMaxBatchSize(100);
+                registry.register(INVENTORY_LOADER,
+                    DataLoader.newMappedDataLoader(inventoryDataLoader, options));
+                registry.register(PARTNER_LOADER,
+                    DataLoader.newMappedDataLoader(partnerDataLoader, options));
+                registry.register(PRODUCT_LOADER,
+                    DataLoader.newMappedDataLoader(productDataLoader, options));
+                registry.register(WAREHOUSE_LOADER,
+                    DataLoader.newMappedDataLoader(warehouseDataLoader, options));
+            }
+        };
+    }
+}
+```
+</details>
+---
+### 15.5 商品リゾルバの実装（DataLoader 使用）
+<details>
+<summary>コード例: ProductResolver.java</summary>
+```java
+package com.example.sales.infrastructure.graphql.resolver;
+import com.example.sales.application.port.in.ProductUseCase;
+import com.example.sales.config.DataLoaderConfig;
+import com.example.sales.domain.model.inventory.Inventory;
+import com.example.sales.domain.model.product.Product;
+import com.example.sales.infrastructure.graphql.dto.*;
+import graphql.schema.DataFetchingEnvironment;
+import org.dataloader.DataLoader;
+import org.springframework.graphql.data.method.annotation.*;
+import org.springframework.stereotype.Controller;
+import java.util.List;
+import java.util.concurrent.CompletableFuture;
+/**
+ * 商品 GraphQL リゾルバ
+ */
+@Controller
+public class ProductResolver {
+    private final ProductUseCase productUseCase;
+    public ProductResolver(ProductUseCase productUseCase) {
+        this.productUseCase = productUseCase;
+    }
+    // === Query ===
+    @QueryMapping
+    public Product product(@Argument String productCode) {
+        return productUseCase.findByCode(productCode).orElse(null);
+    }
+    @QueryMapping
+    public ProductConnection products(
+            @Argument String category,
+            @Argument Integer page,
+            @Argument Integer size) {
+        int pageNum = page != null ? page : 0;
+        int pageSize = size != null ? size : 20;
+        List<Product> products = productUseCase.findAll(category, pageNum, pageSize);
+        long totalCount = productUseCase.count(category);
+        return ProductConnection.of(products, pageNum, pageSize, totalCount);
+    }
+    // === Mutation ===
+    @MutationMapping
+    public Product createProduct(@Argument CreateProductInput input) {
+        Product product = Product.builder()
+            .productCode(input.productCode())
+            .productName(input.productName())
+            .category(input.category())
+            .taxCategory(input.taxCategory())
+            .sellingPrice(input.sellingPrice())
+            .isActive(true)
+            .build();
+        return productUseCase.create(product);
+    }
+    @MutationMapping
+    public Product updateProduct(@Argument UpdateProductInput input) {
+        return productUseCase.update(input.productCode(), product -> {
+            if (input.productName() != null) {
+                product.setProductName(input.productName());
+            }
+            if (input.category() != null) {
+                product.setCategory(input.category());
+            }
+            if (input.sellingPrice() != null) {
+                product.setSellingPrice(input.sellingPrice());
+            }
+            if (input.isActive() != null) {
+                product.setActive(input.isActive());
+            }
+            return product;
+        });
+    }
+    @MutationMapping
+    public boolean deleteProduct(@Argument String productCode) {
+        return productUseCase.delete(productCode);
+    }
+    // === フィールドリゾルバ（DataLoader 使用）===
+    @SchemaMapping(typeName = "Product", field = "inventories")
+    public CompletableFuture<List<Inventory>> inventories(
+            Product product,
+            DataFetchingEnvironment env) {
+        DataLoader<String, List<Inventory>> loader =
+            env.getDataLoader(DataLoaderConfig.INVENTORY_LOADER);
+        return loader.load(product.getProductCode());
+    }
+    @SchemaMapping(typeName = "Product", field = "classifications")
+    public List<ProductClassification> classifications(Product product) {
+        return productUseCase.findClassifications(product.getProductCode());
+    }
+}
+```
+</details>
+---
+## 第16章：トランザクション API の実装
+### 16.1 GraphQL Subscription とは
+GraphQL **Subscription** は、サーバーからクライアントへのリアルタイム通知を実現する仕組みです。WebSocket を使用して双方向通信を行い、データの変更をプッシュ通知します。
+```plantuml
+@startuml subscription_flow
+title GraphQL Subscription フロー
+participant "Client" as client
+participant "WebSocket" as ws
+participant "GraphQL Server" as server
+participant "EventPublisher" as publisher
+participant "OrderService" as service
+database "PostgreSQL" as db
+== Subscription 開始 ==
+client -> ws : subscription { orderStatusChanged }
+ws -> server : WebSocket 接続確立
+server -> server : Subscription 登録
+== イベント発生 ==
+service -> db : 受注ステータス更新
+db --> service : 更新完了
+service -> publisher : OrderStatusChangedEvent 発行
+publisher -> server : イベント受信
+server -> ws : { orderStatusChanged: {...} }
+ws -> client : リアルタイム通知
+== 追加イベント ==
+service -> publisher : OrderStatusChangedEvent 発行
+publisher -> server : イベント受信
+server -> ws : { orderStatusChanged: {...} }
+ws -> client : リアルタイム通知
+== 接続終了 ==
+client -> ws : 接続クローズ
+ws -> server : Subscription 解除
+@enduml
+```
+---
+### 16.2 イベントクラスの定義
+<details>
+<summary>コード例: OrderStatusChangedEvent.java</summary>
+```java
+package com.example.sales.domain.event;
+import com.example.sales.domain.model.order.OrderStatus;
+import java.time.LocalDateTime;
+/**
+ * 受注ステータス変更イベント
+ */
+public record OrderStatusChangedEvent(
+    String orderNumber,
+    OrderStatus previousStatus,
+    OrderStatus currentStatus,
+    String changedBy,
+    LocalDateTime changedAt,
+    String reason
+) {
+    public static OrderStatusChangedEvent of(
+            String orderNumber,
+            OrderStatus previousStatus,
+            OrderStatus currentStatus,
+            String changedBy) {
+        return new OrderStatusChangedEvent(
+            orderNumber,
+            previousStatus,
+            currentStatus,
+            changedBy,
+            LocalDateTime.now(),
+            null
+        );
+    }
+}
+```
+</details>
+<details>
+<summary>コード例: InventoryChangedEvent.java</summary>
+```java
+package com.example.sales.domain.event;
+import java.time.LocalDateTime;
+/**
+ * 在庫変動イベント
+ */
+public record InventoryChangedEvent(
+    String warehouseCode,
+    String productCode,
+    InventoryChangeType changeType,
+    int quantity,
+    int previousQuantity,
+    int currentQuantity,
+    LocalDateTime timestamp
+) {
+    public enum InventoryChangeType {
+        RECEIPT,      // 入庫
+        SHIPMENT,     // 出庫
+        ADJUSTMENT,   // 調整
+        TRANSFER,     // 移動
+        ALLOCATION,   // 引当
+        RELEASE       // 引当解除
+    }
+    public static InventoryChangedEvent of(
+            String warehouseCode,
+            String productCode,
+            InventoryChangeType changeType,
+            int quantity,
+            int previousQuantity,
+            int currentQuantity) {
+        return new InventoryChangedEvent(
+            warehouseCode,
+            productCode,
+            changeType,
+            quantity,
+            previousQuantity,
+            currentQuantity,
+            LocalDateTime.now()
+        );
+    }
+}
+```
+</details>
+---
+### 16.3 イベントパブリッシャー（Reactor Sinks）
+<details>
+<summary>コード例: GraphQLEventPublisher.java</summary>
+```java
+package com.example.sales.infrastructure.graphql.subscription;
+import com.example.sales.domain.event.*;
+import org.springframework.stereotype.Component;
+import reactor.core.publisher.Flux;
+import reactor.core.publisher.Sinks;
+/**
+ * GraphQL Subscription 用イベントパブリッシャー
+ */
+@Component
+public class GraphQLEventPublisher {
+    // 受注ステータス変更
+    private final Sinks.Many<OrderStatusChangedEvent> orderStatusSink =
+        Sinks.many().multicast().onBackpressureBuffer();
+    // 出荷進捗
+    private final Sinks.Many<ShipmentProgressEvent> shipmentProgressSink =
+        Sinks.many().multicast().onBackpressureBuffer();
+    // 在庫変動
+    private final Sinks.Many<InventoryChangedEvent> inventoryChangedSink =
+        Sinks.many().multicast().onBackpressureBuffer();
+    // 締処理進捗
+    private final Sinks.Many<ClosingProgressEvent> closingProgressSink =
+        Sinks.many().multicast().onBackpressureBuffer();
+    // === 発行メソッド ===
+    public void publishOrderStatusChanged(OrderStatusChangedEvent event) {
+        orderStatusSink.tryEmitNext(event);
+    }
+    public void publishShipmentProgress(ShipmentProgressEvent event) {
+        shipmentProgressSink.tryEmitNext(event);
+    }
+    public void publishInventoryChanged(InventoryChangedEvent event) {
+        inventoryChangedSink.tryEmitNext(event);
+    }
+    public void publishClosingProgress(ClosingProgressEvent event) {
+        closingProgressSink.tryEmitNext(event);
+    }
+    // === Flux 取得メソッド ===
+    public Flux<OrderStatusChangedEvent> getOrderStatusChangedFlux() {
+        return orderStatusSink.asFlux();
+    }
+    public Flux<OrderStatusChangedEvent> getOrderStatusChangedFlux(String orderNumber) {
+        return orderStatusSink.asFlux()
+            .filter(event -> orderNumber == null ||
+                             event.orderNumber().equals(orderNumber));
+    }
+    public Flux<ShipmentProgressEvent> getShipmentProgressFlux(String shipmentNumber) {
+        return shipmentProgressSink.asFlux()
+            .filter(event -> shipmentNumber == null ||
+                             event.shipmentNumber().equals(shipmentNumber));
+    }
+    public Flux<InventoryChangedEvent> getInventoryChangedFlux(
+            String warehouseCode, String productCode) {
+        return inventoryChangedSink.asFlux()
+            .filter(event ->
+                (warehouseCode == null || event.warehouseCode().equals(warehouseCode)) &&
+                (productCode == null || event.productCode().equals(productCode))
+            );
+    }
+    public Flux<ClosingProgressEvent> getClosingProgressFlux(String closingId) {
+        return closingProgressSink.asFlux()
+            .filter(event -> event.closingId().equals(closingId));
+    }
+}
+```
+</details>
+---
+### 16.4 受注リゾルバの実装（Subscription 対応）
+<details>
+<summary>コード例: OrderResolver.java</summary>
+```java
+package com.example.sales.infrastructure.graphql.resolver;
+import com.example.sales.application.port.in.OrderUseCase;
+import com.example.sales.domain.event.OrderStatusChangedEvent;
+import com.example.sales.domain.model.order.*;
+import com.example.sales.infrastructure.graphql.dto.*;
+import com.example.sales.infrastructure.graphql.subscription.GraphQLEventPublisher;
+import org.springframework.graphql.data.method.annotation.*;
+import org.springframework.stereotype.Controller;
+import reactor.core.publisher.Flux;
+import java.util.List;
+/**
+ * 受注 GraphQL リゾルバ
+ */
+@Controller
+public class OrderResolver {
+    private final OrderUseCase orderUseCase;
+    private final GraphQLEventPublisher eventPublisher;
+    public OrderResolver(OrderUseCase orderUseCase,
+                         GraphQLEventPublisher eventPublisher) {
+        this.orderUseCase = orderUseCase;
+        this.eventPublisher = eventPublisher;
+    }
+    // === Query ===
+    @QueryMapping
+    public Order order(@Argument String orderNumber) {
+        return orderUseCase.findByNumber(orderNumber).orElse(null);
+    }
+    @QueryMapping
+    public OrderConnection orders(
+            @Argument String status,
+            @Argument String partnerCode,
+            @Argument Integer page,
+            @Argument Integer size) {
+        int pageNum = page != null ? page : 0;
+        int pageSize = size != null ? size : 20;
+        OrderStatus orderStatus = status != null ? OrderStatus.valueOf(status) : null;
+        List<Order> orders = orderUseCase.findAll(orderStatus, partnerCode, pageNum, pageSize);
+        long totalCount = orderUseCase.count(orderStatus, partnerCode);
+        return OrderConnection.of(orders, pageNum, pageSize, totalCount);
+    }
+    // === Mutation ===
+    @MutationMapping
+    public Order createOrder(@Argument CreateOrderInput input) {
+        return orderUseCase.create(
+            input.partnerCode(),
+            input.orderDate(),
+            input.deliveryDate(),
+            input.warehouseCode(),
+            input.salesPersonCode(),
+            input.remarks(),
+            input.details()
+        );
+    }
+    @MutationMapping
+    public Order confirmOrder(@Argument String orderNumber) {
+        Order order = orderUseCase.confirm(orderNumber);
+        // イベント発行
+        eventPublisher.publishOrderStatusChanged(
+            OrderStatusChangedEvent.of(
+                orderNumber,
+                OrderStatus.DRAFT,
+                OrderStatus.CONFIRMED,
+                "system"
+            )
+        );
+        return order;
+    }
+    @MutationMapping
+    public Order cancelOrder(@Argument String orderNumber, @Argument String reason) {
+        Order order = orderUseCase.cancel(orderNumber, reason);
+        // イベント発行
+        eventPublisher.publishOrderStatusChanged(
+            OrderStatusChangedEvent.withReason(
+                orderNumber,
+                order.getStatus(),
+                OrderStatus.CANCELLED,
+                "system",
+                reason
+            )
+        );
+        return order;
+    }
+    // === Subscription ===
+    @SubscriptionMapping
+    public Flux<OrderStatusChangedEvent> orderStatusChanged(
+            @Argument String orderNumber) {
+        return eventPublisher.getOrderStatusChangedFlux(orderNumber);
+    }
+}
+```
+</details>
+---
+### 16.5 GraphiQL によるトランザクション操作
+<details>
+<summary>コード例: GraphQL クエリ/ミューテーション/サブスクリプション</summary>
+```graphql
+# 受注登録
+mutation CreateOrder {
+  createOrder(input: {
+    partnerCode: "CUS001"
+    orderDate: "2025-12-29"
+    deliveryDate: "2026-01-05"
+    warehouseCode: "WH001"
+    details: [
+      { productCode: "PRD001", quantity: 10, unitPrice: 1000 }
+      { productCode: "PRD002", quantity: 5, unitPrice: 2000 }
+    ]
+  }) {
+    orderNumber
+    status
+    totalAmount
+    details {
+      productCode
+      quantity
+      amount
+    }
+  }
+}
+# 受注確定
+mutation ConfirmOrder {
+  confirmOrder(orderNumber: "ORD20251229001") {
+    orderNumber
+    status
+    partner {
+      partnerName
+    }
+  }
+}
+# 受注ステータス監視（Subscription）
+subscription WatchOrderStatus {
+  orderStatusChanged(orderNumber: "ORD20251229001") {
+    orderNumber
+    previousStatus
+    currentStatus
+    changedAt
+    changedBy
+    reason
+  }
+}
+# 在庫変動監視
+subscription WatchInventory {
+  inventoryChanged(warehouseCode: "WH001") {
+    warehouseCode
+    productCode
+    changeType
+    quantity
+    previousQuantity
+    currentQuantity
+    timestamp
+  }
+}
+```
+</details>
+---
+## 第17章：エラーハンドリングとベストプラクティス
+### 17.1 GraphQL エラーハンドリング
+GraphQL のエラーレスポンスは標準化された構造を持ちます：
+<details>
+<summary>コード例: エラーレスポンス構造</summary>
+```json
+{
+  "errors": [
+    {
+      "message": "商品コードが重複しています",
+      "locations": [{ "line": 2, "column": 3 }],
+      "path": ["createProduct"],
+      "extensions": {
+        "classification": "VALIDATION_ERROR",
+        "code": "PRODUCT_CODE_DUPLICATE",
+        "field": "productCode"
+      }
+    }
+  ],
+  "data": null
+}
+```
+</details>
+#### カスタム例外クラス
+<details>
+<summary>コード例: GraphQLErrorCode.java</summary>
+```java
+package com.example.sales.application.exception;
+public enum GraphQLErrorCode {
+    // バリデーションエラー
+    VALIDATION_ERROR("VALIDATION_ERROR"),
+    REQUIRED_FIELD_MISSING("REQUIRED_FIELD_MISSING"),
+    INVALID_FORMAT("INVALID_FORMAT"),
+    VALUE_OUT_OF_RANGE("VALUE_OUT_OF_RANGE"),
+    DUPLICATE_VALUE("DUPLICATE_VALUE"),
+    // ビジネスロジックエラー
+    BUSINESS_RULE_VIOLATION("BUSINESS_RULE_VIOLATION"),
+    INSUFFICIENT_STOCK("INSUFFICIENT_STOCK"),
+    INVALID_STATUS_TRANSITION("INVALID_STATUS_TRANSITION"),
+    CREDIT_LIMIT_EXCEEDED("CREDIT_LIMIT_EXCEEDED"),
+    // リソースエラー
+    NOT_FOUND("NOT_FOUND"),
+    ALREADY_EXISTS("ALREADY_EXISTS"),
+    CONFLICT("CONFLICT"),
+    // 認証・認可エラー
+    UNAUTHORIZED("UNAUTHORIZED"),
+    FORBIDDEN("FORBIDDEN"),
+    // システムエラー
+    INTERNAL_ERROR("INTERNAL_ERROR"),
+    SERVICE_UNAVAILABLE("SERVICE_UNAVAILABLE");
+    private final String code;
+    GraphQLErrorCode(String code) {
+        this.code = code;
+    }
+    public String getCode() {
+        return code;
+    }
+}
+```
+</details>
+<details>
+<summary>コード例: GraphQLBusinessException.java</summary>
+```java
+package com.example.sales.application.exception;
+import graphql.ErrorClassification;
+import graphql.GraphQLError;
+import graphql.language.SourceLocation;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+public class GraphQLBusinessException extends RuntimeException implements GraphQLError {
+    private final GraphQLErrorCode errorCode;
+    private final String field;
+    private final Map<String, Object> additionalData;
+    public GraphQLBusinessException(String message, GraphQLErrorCode errorCode) {
+        this(message, errorCode, null, null);
+    }
+    public GraphQLBusinessException(String message, GraphQLErrorCode errorCode, String field) {
+        this(message, errorCode, field, null);
+    }
+    public GraphQLBusinessException(
+            String message,
+            GraphQLErrorCode errorCode,
+            String field,
+            Map<String, Object> additionalData) {
+        super(message);
+        this.errorCode = errorCode;
+        this.field = field;
+        this.additionalData = additionalData != null ? additionalData : new HashMap<>();
+    }
+    @Override
+    public List<SourceLocation> getLocations() {
+        return null;
+    }
+    @Override
+    public ErrorClassification getErrorType() {
+        return CustomErrorClassification.fromCode(errorCode);
+    }
+    @Override
+    public Map<String, Object> getExtensions() {
+        Map<String, Object> extensions = new HashMap<>();
+        extensions.put("code", errorCode.getCode());
+        extensions.put("classification", getErrorType().toString());
+        if (field != null) {
+            extensions.put("field", field);
+        }
+        extensions.putAll(additionalData);
+        return extensions;
+    }
+}
+```
+</details>
+---
+### 17.2 例外リゾルバ
+<details>
+<summary>コード例: GraphQLExceptionResolver.java</summary>
+```java
+package com.example.sales.infrastructure.graphql.exception;
+import com.example.sales.application.exception.GraphQLBusinessException;
+import com.example.sales.application.exception.GraphQLErrorCode;
+import graphql.GraphQLError;
+import graphql.schema.DataFetchingEnvironment;
+import org.springframework.graphql.execution.DataFetcherExceptionResolverAdapter;
+import org.springframework.graphql.execution.ErrorType;
+import org.springframework.stereotype.Component;
+@Component
+public class GraphQLExceptionResolver extends DataFetcherExceptionResolverAdapter {
+    @Override
+    protected GraphQLError resolveToSingleError(Throwable ex, DataFetchingEnvironment env) {
+        // カスタムビジネス例外
+        if (ex instanceof GraphQLBusinessException businessEx) {
+            return businessEx;
+        }
+        // ドメイン例外をラップ
+        if (ex instanceof IllegalArgumentException) {
+            return new GraphQLBusinessException(
+                ex.getMessage(),
+                GraphQLErrorCode.VALIDATION_ERROR
+            );
+        }
+        if (ex instanceof IllegalStateException) {
+            return new GraphQLBusinessException(
+                ex.getMessage(),
+                GraphQLErrorCode.BUSINESS_RULE_VIOLATION
+            );
+        }
+        // Jakarta Validation 例外
+        if (ex instanceof jakarta.validation.ConstraintViolationException cve) {
+            var firstViolation = cve.getConstraintViolations().iterator().next();
+            return new GraphQLBusinessException(
+                firstViolation.getMessage(),
+                GraphQLErrorCode.VALIDATION_ERROR,
+                firstViolation.getPropertyPath().toString()
+            );
+        }
+        // 未知の例外はログ出力して汎用メッセージを返す
+        logger.error("Unexpected error in GraphQL resolver", ex);
+        return GraphQLError.newError()
+            .message("システムエラーが発生しました")
+            .errorType(ErrorType.INTERNAL_ERROR)
+            .build();
+    }
+}
+```
+</details>
+---
+### 17.3 入力バリデーション
+#### GraphQL ディレクティブによるバリデーション
+<details>
+<summary>コード例: directives.graphqls</summary>
+```graphql
+# schema/directives.graphqls
+directive @NotBlank(message: String = "必須項目です") on INPUT_FIELD_DEFINITION | ARGUMENT_DEFINITION
+directive @Size(min: Int = 0, max: Int = 255, message: String) on INPUT_FIELD_DEFINITION | ARGUMENT_DEFINITION
+directive @Min(value: Int!, message: String) on INPUT_FIELD_DEFINITION | ARGUMENT_DEFINITION
+directive @Pattern(regexp: String!, message: String) on INPUT_FIELD_DEFINITION | ARGUMENT_DEFINITION
+directive @Email(message: String = "有効なメールアドレスを入力してください") on INPUT_FIELD_DEFINITION | ARGUMENT_DEFINITION
+# 使用例
+input CreateProductInput {
+  productCode: String! @NotBlank @Size(min: 1, max: 16, message: "商品コードは16文字以内で入力してください")
+  productName: String! @NotBlank @Size(max: 100)
+  price: BigDecimal! @Min(value: 0, message: "価格は0以上で入力してください")
+}
+input CreatePartnerInput {
+  partnerCode: String! @NotBlank @Pattern(regexp: "^[A-Z0-9]{4,10}$", message: "取引先コードは英大文字と数字4〜10文字で入力してください")
+  partnerName: String! @NotBlank @Size(max: 100)
+  email: String @Email
+  creditLimit: BigDecimal @Min(value: 0)
+}
+```
+</details>
+#### Jakarta Validation との統合
+<details>
+<summary>コード例: CreateProductInputDto.java</summary>
+```java
+package com.example.sales.application.dto;
+import jakarta.validation.constraints.*;
+import java.math.BigDecimal;
+public record CreateProductInputDto(
+    @NotBlank(message = "商品コードは必須です")
+    @Size(max = 16, message = "商品コードは16文字以内で入力してください")
+    @Pattern(regexp = "^[A-Z0-9]+$", message = "商品コードは英大文字と数字のみ使用可能です")
+    String productCode,
+    @NotBlank(message = "商品名は必須です")
+    @Size(max = 100, message = "商品名は100文字以内で入力してください")
+    String productName,
+    @NotNull(message = "価格は必須です")
+    @DecimalMin(value = "0", message = "価格は0以上で入力してください")
+    @Digits(integer = 10, fraction = 2, message = "価格の形式が正しくありません")
+    BigDecimal price,
+    @Min(value = 0, message = "在庫数は0以上で入力してください")
+    Integer stockQuantity,
+    @Size(max = 500, message = "備考は500文字以内で入力してください")
+    String notes
+) {}
+```
+</details>
+---
+### 17.4 セキュリティ
+#### 認可ディレクティブ
+<details>
+<summary>コード例: 認可ディレクティブ</summary>
+```graphql
+# スキーマレベルでの認可定義
+directive @auth(
+  roles: [String!]!
+) on FIELD_DEFINITION
+type Mutation {
+  # 管理者のみ
+  deleteProduct(productCode: ID!): Boolean! @auth(roles: ["ADMIN"])
+  # 営業担当と管理者
+  createOrder(input: CreateOrderInput!): Order! @auth(roles: ["SALES", "ADMIN"])
+  # 経理担当と管理者
+  executeClosing(input: ExecuteClosingInput!): ClosingResult! @auth(roles: ["ACCOUNTING", "ADMIN"])
+}
+```
+</details>
+#### クエリ深度制限
+<details>
+<summary>コード例: クエリ深度制限</summary>
+```java
+@Bean
+public Instrumentation maxQueryDepthInstrumentation() {
+    return new MaxQueryDepthInstrumentation(10);
+}
+@Bean
+public Instrumentation maxQueryComplexityInstrumentation() {
+    return new MaxQueryComplexityInstrumentation(100);
+}
+```
+</details>
+---
+### 17.5 運用のベストプラクティス
+#### ログインターセプター
+<details>
+<summary>コード例: GraphQLLoggingInterceptor.java</summary>
+```java
+@Component
+public class GraphQLLoggingInterceptor implements WebGraphQlInterceptor {
+    private static final Logger logger = LoggerFactory.getLogger(GraphQLLoggingInterceptor.class);
+    @Override
+    public Mono<WebGraphQlResponse> intercept(WebGraphQlRequest request, Chain chain) {
+        String requestId = UUID.randomUUID().toString().substring(0, 8);
+        String operationName = request.getOperationName();
+        Instant start = Instant.now();
+        MDC.put("requestId", requestId);
+        MDC.put("operationName", operationName);
+        logger.info("GraphQL リクエスト開始: operation={}", operationName);
+        return chain.next(request)
+            .doOnNext(response -> {
+                Duration duration = Duration.between(start, Instant.now());
+                if (response.getErrors().isEmpty()) {
+                    logger.info("GraphQL リクエスト完了: operation={}, duration={}ms",
+                        operationName, duration.toMillis());
+                } else {
+                    logger.warn("GraphQL リクエスト完了（エラーあり）: operation={}, duration={}ms, errors={}",
+                        operationName, duration.toMillis(), response.getErrors().size());
+                }
+            })
+            .doFinally(signalType -> {
+                MDC.remove("requestId");
+                MDC.remove("operationName");
+            });
+    }
+}
+```
+</details>
+#### メトリクス収集
+<details>
+<summary>コード例: GraphQLMetricsCollector.java</summary>
+```java
+@Component
+public class GraphQLMetricsCollector implements WebGraphQlInterceptor {
+    private final Timer queryTimer;
+    private final Timer mutationTimer;
+    private final Counter errorCounter;
+    private final Counter successCounter;
+    public GraphQLMetricsCollector(MeterRegistry registry) {
+        this.queryTimer = Timer.builder("graphql.query.duration")
+            .description("GraphQL クエリ実行時間")
+            .register(registry);
+        this.mutationTimer = Timer.builder("graphql.mutation.duration")
+            .description("GraphQL ミューテーション実行時間")
+            .register(registry);
+        this.errorCounter = Counter.builder("graphql.errors")
+            .description("GraphQL エラー数")
+            .register(registry);
+        this.successCounter = Counter.builder("graphql.success")
+            .description("GraphQL 成功数")
+            .register(registry);
+    }
+    @Override
+    public Mono<WebGraphQlResponse> intercept(WebGraphQlRequest request, Chain chain) {
+        Timer timer = request.getDocument().contains("mutation")
+            ? mutationTimer
+            : queryTimer;
+        return Mono.fromSupplier(timer::start)
+            .flatMap(sample -> chain.next(request)
+                .doOnNext(response -> {
+                    sample.stop(timer);
+                    if (response.getErrors().isEmpty()) {
+                        successCounter.increment();
+                    } else {
+                        errorCounter.increment(response.getErrors().size());
+                    }
+                })
+            );
+    }
+}
+```
+</details>
+---
+## Part 10-E のまとめ
+### 実装した機能一覧
+| 章 | 内容 | 主要技術 |
+|---|---|---|
+| **第14章: 基礎** | GraphQL サーバーの基礎 | Spring for GraphQL, スキーマ駆動開発 |
+| **第15章: マスタ API** | N+1 問題対策、ページネーション | DataLoader, Connection パターン |
+| **第16章: トランザクション API** | リアルタイム通知、非同期処理 | Subscription, Reactor Sinks |
+| **第17章: エラーハンドリング** | バリデーション、セキュリティ | ディレクティブ, Jakarta Validation |
+### 実装した GraphQL 操作
+- **Query**: 商品・取引先・倉庫・受注・出荷・請求の取得
+- **Mutation**: CRUD 操作、受注確定、出荷確定、締処理
+- **Subscription**: 受注ステータス変更、出荷進捗、在庫変動、締処理進捗
+### アーキテクチャの特徴
+```plantuml
+@startuml
+package "Adapter Layer (in)" {
+    [GraphQL Resolver] as resolver
+    [Exception Resolver] as exception_resolver
+    [Validation Directive] as validation
+    [DataLoader Registry] as dataloader
+    [Logging Interceptor] as logging
+    [Metrics Collector] as metrics
+}
+package "Application Layer" {
+    [UseCase] as usecase
+    [DTO] as dto
+    [Exception] as app_exception
+}
+package "Domain Layer" {
+    [Domain Model] as domain
+    [Domain Service] as domain_service
+    [Repository Interface] as repo_interface
+}
+package "Adapter Layer (out)" {
+    [Repository Implementation] as repo_impl
+    [MyBatis Mapper] as mapper
+}
+database "PostgreSQL" as db
+' Interceptor チェーン
+logging --> metrics
+metrics --> resolver
+' バリデーション
+validation --> resolver
+' メイン処理フロー
+resolver --> usecase
+resolver --> dataloader
+usecase --> domain_service
+usecase --> repo_interface
+domain_service --> domain
+repo_interface <|.. repo_impl
+repo_impl --> mapper
+mapper --> db
+' 例外処理
+resolver ..> exception_resolver : throws
+usecase ..> app_exception : throws
+' DataLoader
+dataloader --> repo_interface
+@enduml
+```
+### 技術スタック
+| カテゴリ | 技術 |
+|---------|------|
+| **言語** | Java 21 |
+| **フレームワーク** | Spring Boot 4.0, Spring for GraphQL |
+| **リアルタイム** | WebSocket, Reactor (Sinks) |
+| **ORM** | MyBatis 3.0 |
+| **データベース** | PostgreSQL 16 |
+| **テスト** | JUnit 5, spring-graphql-test, TestContainers |
+### API 形式の比較と選択基準
+| 観点 | REST API | gRPC | GraphQL |
+|------|----------|------|---------|
+| **データ取得** | 固定レスポンス | 固定レスポンス | クライアント指定 |
+| **エンドポイント** | 複数 | 複数 | 単一 |
+| **Over-fetching** | 発生しやすい | 発生しやすい | 防止可能 |
+| **Under-fetching** | 発生しやすい | 発生しやすい | 防止可能 |
+| **リアルタイム** | WebSocket 別実装 | ストリーミング | Subscription |
+| **N+1 問題** | 発生しにくい | 発生しにくい | DataLoader で解決 |
+| **主な用途** | 汎用 API | マイクロサービス | フロントエンド向け |
+### GraphQL を選択する場面
+1. **複雑なデータ構造**: 関連データを柔軟に取得したい
+2. **フロントエンド主導**: クライアントが必要なデータを指定したい
+3. **Over-fetching 回避**: 帯域幅の節約が重要
+4. **リアルタイム通知**: Subscription による統一的な通知機構が必要
+5. **API 統合**: 複数のバックエンドを単一 API で公開したい
+GraphQL は REST API と比較して、クライアントが必要なデータを柔軟に取得できる点が大きな利点です。特に複雑なデータ構造を持つ販売管理システムでは、DataLoader と Subscription を活用することで、効率的かつリアルタイムな API を提供できます。