npm - @k2works/claude-code-booster - Versions diffs - 3.6.1 → 3.8.0 - Mend

@k2works/claude-code-booster 3.6.1 → 3.8.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/part2/chapter13.md CHANGED Viewed

@@ -1,1434 +1,1434 @@
-# 第13章：API サービスの実装
-本章では、販売管理システムのデータベース設計を外部から利用できるようにするため、RESTful API サービスを実装します。ヘキサゴナルアーキテクチャ（Ports and Adapters）を採用し、ドメインロジックを外部技術から分離した保守性の高い API を構築します。
----
-## 13.1 ヘキサゴナルアーキテクチャの復習
-### Ports and Adapters パターンの概要
-ヘキサゴナルアーキテクチャ（Ports and Adapters パターン）は、Alistair Cockburn によって提唱された設計手法で、アプリケーションの中核となるビジネスロジック（ドメイン層）を外部の技術的詳細から完全に分離することを目的とします。
-```plantuml
-@startuml hexagonal_architecture_sales
-!define RECTANGLE class
-package "Hexagonal Architecture (販売管理API)" {
-  RECTANGLE "Application Core\n(Domain + Use Cases)" as core {
-    - Product (商品)
-    - Partner (取引先)
-    - Order (受注)
-    - Sales (売上)
-    - Invoice (請求)
-    - ProductUseCase
-    - OrderUseCase
-    - SalesUseCase
-  }
-  RECTANGLE "Input Adapters\n(Driving Side)" as input {
-    - Spring Controllers
-    - REST API Endpoints
-    - Request Validation
-    - Error Handling
-  }
-  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
-  純粋なビジネスロジック
-  MyBatis に依存しない
-  高速でテスト可能
-end note
-note left of input
-  外部からアプリケーションを
-  駆動するアダプター
-  HTTP, REST等
-end note
-note right of output
-  アプリケーションが外部の
-  技術を使うためのアダプター
-  PostgreSQL, MyBatis等
-end note
-@enduml
-```
-### ドメイン中心設計
-ビジネスロジックを中心に据え、外部技術（DB、Web、UI など）を周辺に配置します。これにより、ビジネスルールが技術的な関心事から独立し、変更に強い設計が実現できます。
-### 依存性の逆転
-ドメイン層は外部に依存せず、外部がドメイン層に依存します。具体的には、リポジトリのインターフェース（Output Port）をドメイン層で定義し、その実装（Adapter）をインフラストラクチャ層に配置します。
-### テスト容易性
-モックやスタブを使った単体テストが容易になります。ドメインロジックを独立してテストでき、外部依存（データベースなど）なしで高速なテストが可能です。
----
-## 13.2 アーキテクチャ構造
-### レイヤー構成
-販売管理 API の実装では、以下のレイヤー構造を採用します。
-```
-src/main/java/com/example/sms/
-├── domain/                     # ドメイン層（純粋なビジネスロジック）
-│   ├── model/                 # ドメインモデル（エンティティ、値オブジェクト）
-│   │   ├── department/        # 部門関連
-│   │   ├── employee/          # 社員関連
-│   │   ├── inventory/         # 在庫関連
-│   │   ├── partner/           # 取引先関連
-│   │   ├── product/           # 商品関連
-│   │   ├── purchase/          # 仕入関連
-│   │   └── sales/             # 販売関連
-│   ├── exception/             # ドメイン例外
-│   └── type/                  # 値型定義
-│
-├── application/               # アプリケーション層
-│   └── port/
-│       └── out/              # Output Port（リポジトリインターフェース）
-│
-├── infrastructure/            # インフラストラクチャ層
-│   ├── in/                   # Input Adapter（受信アダプター）
-│   │   ├── rest/             # REST API（Web実装）
-│   │   │   ├── controller/   # REST Controller（Spring MVC）
-│   │   │   ├── dto/          # Data Transfer Object
-│   │   │   └── exception/    # Exception Handler
-│   │   └── seed/             # Seed データ投入
-│   └── out/                  # Output Adapter（送信アダプター）
-│       └── persistence/      # DB実装
-│           ├── mapper/       # MyBatis Mapper
-│           ├── repository/   # Repository実装
-│           └── typehandler/  # 型ハンドラー
-│
-└── config/                   # 設定クラス
-```
-### Domain 層
-ビジネスルールとドメインモデルを定義します。外部技術に依存しない純粋な Java コードで構成されます。
-<details>
-<summary>Product.java（商品ドメインモデル）</summary>
-```java
-package com.example.sms.domain.model.product;
-import lombok.AllArgsConstructor;
-import lombok.Builder;
-import lombok.Data;
-import lombok.NoArgsConstructor;
-import java.math.BigDecimal;
-import java.time.LocalDateTime;
-/**
- * 商品エンティティ.
- */
-@Data
-@Builder
-@NoArgsConstructor
-@AllArgsConstructor
-public class Product {
-    private String productCode;
-    private String productFullName;
-    private String productName;
-    private String productNameKana;
-    private ProductCategory productCategory;
-    private String modelNumber;
-    @Builder.Default
-    private BigDecimal sellingPrice = BigDecimal.ZERO;
-    @Builder.Default
-    private BigDecimal purchasePrice = BigDecimal.ZERO;
-    private TaxCategory taxCategory;
-    private String classificationCode;
-    @Builder.Default
-    private boolean isMiscellaneous = false;
-    @Builder.Default
-    private boolean isInventoryManaged = true;
-    @Builder.Default
-    private boolean isInventoryAllocated = true;
-    private String supplierCode;
-    private String supplierBranchNumber;
-    private LocalDateTime createdAt;
-    private String createdBy;
-    private LocalDateTime updatedAt;
-    private String updatedBy;
-}
-```
-</details>
-### Application 層
-ユースケースの実装とオーケストレーションを担当します。
-<details>
-<summary>ProductRepository.java（Output Port）</summary>
-```java
-package com.example.sms.application.port.out;
-import com.example.sms.domain.model.product.Product;
-import com.example.sms.domain.model.product.ProductCategory;
-import java.util.List;
-import java.util.Optional;
-/**
- * 商品リポジトリ（Output Port）.
- */
-public interface ProductRepository {
-    void save(Product product);
-    Optional<Product> findByCode(String productCode);
-    List<Product> findAll();
-    List<Product> findByCategory(ProductCategory category);
-    List<Product> findByClassificationCode(String classificationCode);
-    void update(Product product);
-    void deleteByCode(String productCode);
-    void deleteAll();
-}
-```
-</details>
-### Infrastructure 層
-外部技術との接続を担当します。DB アクセス（MyBatis）や Web フレームワーク（Spring MVC）の実装を含みます。
-### Input Port / Output Port の分離
-| ポート | 役割 | 例 |
-|--------|------|-----|
-| Input Port | アプリケーションへの入力インターフェース | `ProductUseCase`, `OrderUseCase` |
-| Output Port | アプリケーションからの出力インターフェース | `ProductRepository`, `OrderRepository` |
----
-## 13.3 マスタ API の実装
-### 商品マスタ API（CRUD エンドポイント）
-#### Output Port（リポジトリインターフェース）
-<details>
-<summary>ProductRepository.java</summary>
-```java
-package com.example.sms.application.port.out;
-/**
- * 商品リポジトリ（Output Port）
- */
-public interface ProductRepository {
-    Product save(Product product);
-    List<Product> findAll();
-    Optional<Product> findByCode(String productCode, LocalDate effectiveDate);
-    List<Product> findByType(ProductType type);
-    List<Product> findByCategoryCode(String categoryCode);
-    void deleteByCode(String productCode, LocalDate effectiveDate);
-}
-```
-</details>
-#### Input Port（ユースケースインターフェース）
-<details>
-<summary>コマンドオブジェクト</summary>
-```java
-package com.example.sms.application.port.in;
-public record CreateProductCommand(
-    String productCode,
-    String productName,
-    String categoryCode,
-    ProductType productType,
-    TaxType taxType,
-    BigDecimal sellingPrice,
-    BigDecimal purchasePrice
-) {}
-public record UpdateProductCommand(
-    String productCode,
-    String productName,
-    ProductType productType,
-    TaxType taxType,
-    BigDecimal sellingPrice,
-    BigDecimal purchasePrice
-) {}
-```
-</details>
-### TDD による実装（Red-Green-Refactor）
-#### Red: 失敗するテストを書く
-<details>
-<summary>ProductControllerTest.java</summary>
-```java
-package com.example.sms.infrastructure.in.rest;
-import com.example.sms.application.port.out.ProductClassificationRepository;
-import com.example.sms.application.port.out.ProductRepository;
-import com.example.sms.domain.model.product.Product;
-import com.example.sms.domain.model.product.ProductCategory;
-import com.example.sms.domain.model.product.ProductClassification;
-import com.example.sms.domain.model.product.TaxCategory;
-import com.example.sms.testsetup.BaseIntegrationTest;
-import org.junit.jupiter.api.BeforeEach;
-import org.junit.jupiter.api.DisplayName;
-import org.junit.jupiter.api.Nested;
-import org.junit.jupiter.api.Test;
-import org.springframework.beans.factory.annotation.Autowired;
-import org.springframework.boot.webmvc.test.autoconfigure.AutoConfigureMockMvc;
-import org.springframework.http.MediaType;
-import org.springframework.test.web.servlet.MockMvc;
-import java.math.BigDecimal;
-import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*;
-import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;
-@AutoConfigureMockMvc
-@DisplayName("商品マスタ API テスト")
-class ProductControllerTest extends BaseIntegrationTest {
-    private static final String TEST_CLASSIFICATION_CODE = "CAT-TEST";
-    @Autowired
-    private MockMvc mockMvc;
-    @Autowired
-    private ProductRepository productRepository;
-    @Autowired
-    private ProductClassificationRepository productClassificationRepository;
-    @BeforeEach
-    void setUp() {
-        productRepository.deleteAll();
-        productClassificationRepository.deleteAll();
-        // テスト用の商品分類を作成
-        ProductClassification classification = ProductClassification.builder()
-            .classificationCode(TEST_CLASSIFICATION_CODE)
-            .classificationName("テスト分類")
-            .hierarchyLevel(1)
-            .classificationPath("/CAT-TEST")
-            .isLeaf(true)
-            .build();
-        productClassificationRepository.save(classification);
-    }
-    @Nested
-    @DisplayName("POST /api/v1/products")
-    class CreateProduct {
-        @Test
-        @DisplayName("商品を登録できる")
-        void shouldCreateProduct() throws Exception {
-            var request = """
-                {
-                    "productCode": "NEW-001",
-                    "productFullName": "新規テスト商品 フルネーム",
-                    "productName": "新規テスト商品",
-                    "productNameKana": "シンキテストショウヒン",
-                    "productCategory": "PRODUCT",
-                    "modelNumber": "MODEL-001",
-                    "sellingPrice": 5000,
-                    "purchasePrice": 3000,
-                    "taxCategory": "EXCLUSIVE",
-                    "classificationCode": "CAT-TEST"
-                }
-                """;
-            mockMvc.perform(post("/api/v1/products")
-                    .contentType(MediaType.APPLICATION_JSON)
-                    .content(request))
-                .andExpect(status().isCreated())
-                .andExpect(jsonPath("$.productCode").value("NEW-001"))
-                .andExpect(jsonPath("$.productName").value("新規テスト商品"));
-        }
-    }
-}
-```
-</details>
-#### Green: テストを通す実装
-<details>
-<summary>ProductController.java</summary>
-```java
-package com.example.sms.infrastructure.in.rest.controller;
-import com.example.sms.application.port.out.ProductRepository;
-import com.example.sms.domain.exception.DuplicateProductException;
-import com.example.sms.domain.exception.ProductNotFoundException;
-import com.example.sms.domain.model.product.Product;
-import com.example.sms.infrastructure.in.rest.dto.CreateProductRequest;
-import com.example.sms.infrastructure.in.rest.dto.ProductResponse;
-import com.example.sms.infrastructure.in.rest.dto.UpdateProductRequest;
-import io.swagger.v3.oas.annotations.Operation;
-import io.swagger.v3.oas.annotations.Parameter;
-import io.swagger.v3.oas.annotations.responses.ApiResponse;
-import io.swagger.v3.oas.annotations.tags.Tag;
-import jakarta.validation.Valid;
-import org.springframework.http.HttpStatus;
-import org.springframework.http.ResponseEntity;
-import org.springframework.web.bind.annotation.*;
-import java.util.List;
-@RestController
-@RequestMapping("/api/v1/products")
-@Tag(name = "products", description = "商品マスタ API")
-public class ProductController {
-    private final ProductRepository productRepository;
-    public ProductController(ProductRepository productRepository) {
-        this.productRepository = productRepository;
-    }
-    @GetMapping
-    @Operation(summary = "商品一覧の取得")
-    @ApiResponse(responseCode = "200", description = "商品一覧を返却")
-    public ResponseEntity<List<ProductResponse>> getAllProducts() {
-        List<Product> products = productRepository.findAll();
-        List<ProductResponse> responses = products.stream()
-            .map(ProductResponse::from)
-            .toList();
-        return ResponseEntity.ok(responses);
-    }
-    @GetMapping("/{productCode}")
-    @Operation(summary = "商品の取得")
-    @ApiResponse(responseCode = "200", description = "商品を返却")
-    @ApiResponse(responseCode = "404", description = "商品が見つからない")
-    public ResponseEntity<ProductResponse> getProduct(
-            @Parameter(description = "商品コード")
-            @PathVariable String productCode) {
-        Product product = productRepository.findByCode(productCode)
-            .orElseThrow(() -> new ProductNotFoundException(productCode));
-        return ResponseEntity.ok(ProductResponse.from(product));
-    }
-    @PostMapping
-    @Operation(summary = "商品の登録")
-    @ApiResponse(responseCode = "201", description = "商品を登録")
-    @ApiResponse(responseCode = "409", description = "商品が既に存在する")
-    public ResponseEntity<ProductResponse> createProduct(
-            @Valid @RequestBody CreateProductRequest request) {
-        // 重複チェック
-        productRepository.findByCode(request.productCode())
-            .ifPresent(existing -> {
-                throw new DuplicateProductException(request.productCode());
-            });
-        Product product = Product.builder()
-            .productCode(request.productCode())
-            .productFullName(request.productFullName())
-            .productName(request.productName())
-            .productNameKana(request.productNameKana())
-            .productCategory(request.productCategory())
-            .modelNumber(request.modelNumber())
-            .sellingPrice(request.sellingPrice())
-            .purchasePrice(request.purchasePrice())
-            .taxCategory(request.taxCategory())
-            .classificationCode(request.classificationCode())
-            .build();
-        productRepository.save(product);
-        return ResponseEntity.status(HttpStatus.CREATED)
-            .body(ProductResponse.from(product));
-    }
-}
-```
-</details>
-### Controller・Service・Repository の実装
-#### Application Service
-<details>
-<summary>ProductService.java</summary>
-```java
-@Service
-@Transactional
-public class ProductService implements ProductUseCase {
-    private final ProductRepository productRepository;
-    public ProductService(ProductRepository productRepository) {
-        this.productRepository = productRepository;
-    }
-    @Override
-    public Product createProduct(CreateProductCommand command) {
-        LocalDate effectiveDate = LocalDate.now();
-        // 重複チェック
-        productRepository.findByCode(command.productCode(), effectiveDate)
-            .ifPresent(existing -> {
-                throw new DuplicateProductException(command.productCode());
-            });
-        Product product = new Product(
-            command.productCode(),
-            effectiveDate,
-            command.productName(),
-            command.categoryCode(),
-            effectiveDate,
-            command.productType(),
-            command.taxType(),
-            command.sellingPrice(),
-            command.purchasePrice()
-        );
-        return productRepository.save(product);
-    }
-    @Override
-    @Transactional(readOnly = true)
-    public Product getProductByCode(String productCode) {
-        LocalDate effectiveDate = LocalDate.now();
-        return productRepository.findByCode(productCode, effectiveDate)
-            .orElseThrow(() -> new ProductNotFoundException(productCode));
-    }
-}
-```
-</details>
-### 顧客マスタ API（請求先・回収先の管理）
-顧客マスタ API では、請求先と回収先の概念を正しく管理します。
-<details>
-<summary>CustomerController.java</summary>
-```java
-@RestController
-@RequestMapping("/api/v1/customers")
-@Tag(name = "customers", description = "顧客 API")
-public class CustomerController {
-    private final CustomerUseCase customerUseCase;
-    @GetMapping("/{customerCode}")
-    @Operation(summary = "顧客の取得")
-    public ResponseEntity<CustomerResponse> getCustomer(
-            @PathVariable String customerCode) {
-        Customer customer = customerUseCase.getCustomerByCode(customerCode);
-        return ResponseEntity.ok(CustomerResponse.from(customer));
-    }
-    @GetMapping("/{customerCode}/billing-destinations")
-    @Operation(summary = "請求先一覧の取得")
-    public ResponseEntity<List<BillingDestinationResponse>> getBillingDestinations(
-            @PathVariable String customerCode) {
-        List<BillingDestination> destinations =
-            customerUseCase.getBillingDestinations(customerCode);
-        return ResponseEntity.ok(destinations.stream()
-            .map(BillingDestinationResponse::from)
-            .toList());
-    }
-}
-```
-</details>
----
-## 13.4 トランザクション API の実装
-### 受注 API（受注登録・受注照会・受注明細照会）
-<details>
-<summary>OrderController.java</summary>
-```java
-@RestController
-@RequestMapping("/api/v1/orders")
-@Tag(name = "orders", description = "受注 API")
-public class OrderController {
-    private final OrderUseCase orderUseCase;
-    @PostMapping
-    @Operation(summary = "受注の登録")
-    public ResponseEntity<OrderResponse> createOrder(
-            @Valid @RequestBody CreateOrderRequest request) {
-        Order order = orderUseCase.createOrder(request.toCommand());
-        return ResponseEntity.status(HttpStatus.CREATED)
-            .body(OrderResponse.from(order));
-    }
-    @GetMapping("/{orderNumber}")
-    @Operation(summary = "受注の取得")
-    public ResponseEntity<OrderResponse> getOrder(
-            @PathVariable String orderNumber) {
-        Order order = orderUseCase.getOrderByNumber(orderNumber);
-        return ResponseEntity.ok(OrderResponse.from(order));
-    }
-    @GetMapping("/{orderNumber}/details")
-    @Operation(summary = "受注明細の取得")
-    public ResponseEntity<List<OrderDetailResponse>> getOrderDetails(
-            @PathVariable String orderNumber) {
-        List<OrderDetail> details = orderUseCase.getOrderDetails(orderNumber);
-        return ResponseEntity.ok(details.stream()
-            .map(OrderDetailResponse::from)
-            .toList());
-    }
-}
-```
-</details>
-### 出荷 API（出荷指示・出荷確定）
-<details>
-<summary>ShipmentController.java</summary>
-```java
-@RestController
-@RequestMapping("/api/v1/shipments")
-@Tag(name = "shipments", description = "出荷 API")
-public class ShipmentController {
-    private final ShipmentUseCase shipmentUseCase;
-    @PostMapping("/instructions")
-    @Operation(summary = "出荷指示の登録")
-    public ResponseEntity<ShipmentInstructionResponse> createShipmentInstruction(
-            @Valid @RequestBody CreateShipmentInstructionRequest request) {
-        ShipmentInstruction instruction =
-            shipmentUseCase.createInstruction(request.toCommand());
-        return ResponseEntity.status(HttpStatus.CREATED)
-            .body(ShipmentInstructionResponse.from(instruction));
-    }
-    @PostMapping("/{shipmentNumber}/confirm")
-    @Operation(summary = "出荷確定")
-    public ResponseEntity<ShipmentResponse> confirmShipment(
-            @PathVariable String shipmentNumber) {
-        Shipment shipment = shipmentUseCase.confirmShipment(shipmentNumber);
-        return ResponseEntity.ok(ShipmentResponse.from(shipment));
-    }
-}
-```
-</details>
-### 売上 API（売上計上・売上照会）
-<details>
-<summary>SalesController.java</summary>
-```java
-@RestController
-@RequestMapping("/api/v1/sales")
-@Tag(name = "sales", description = "売上 API")
-public class SalesController {
-    private final SalesUseCase salesUseCase;
-    @PostMapping
-    @Operation(summary = "売上計上")
-    public ResponseEntity<SalesResponse> recordSales(
-            @Valid @RequestBody RecordSalesRequest request) {
-        Sales sales = salesUseCase.recordSales(request.toCommand());
-        return ResponseEntity.status(HttpStatus.CREATED)
-            .body(SalesResponse.from(sales));
-    }
-    @GetMapping
-    @Operation(summary = "売上一覧の取得")
-    public ResponseEntity<List<SalesResponse>> getSalesList(
-            @RequestParam(required = false) LocalDate fromDate,
-            @RequestParam(required = false) LocalDate toDate,
-            @RequestParam(required = false) String customerCode) {
-        List<Sales> salesList = salesUseCase.getSalesList(fromDate, toDate, customerCode);
-        return ResponseEntity.ok(salesList.stream()
-            .map(SalesResponse::from)
-            .toList());
-    }
-}
-```
-</details>
-### 請求・入金 API（請求締め・入金消込）
-<details>
-<summary>InvoiceController.java / ReceiptController.java</summary>
-```java
-@RestController
-@RequestMapping("/api/v1/invoices")
-@Tag(name = "invoices", description = "請求 API")
-public class InvoiceController {
-    private final InvoiceUseCase invoiceUseCase;
-    @PostMapping("/closing")
-    @Operation(summary = "請求締め処理")
-    public ResponseEntity<List<InvoiceResponse>> executeClosing(
-            @Valid @RequestBody InvoiceClosingRequest request) {
-        List<Invoice> invoices = invoiceUseCase.executeClosing(
-            request.closingDate(),
-            request.customerCode()
-        );
-        return ResponseEntity.ok(invoices.stream()
-            .map(InvoiceResponse::from)
-            .toList());
-    }
-}
-@RestController
-@RequestMapping("/api/v1/receipts")
-@Tag(name = "receipts", description = "入金 API")
-public class ReceiptController {
-    private final ReceiptUseCase receiptUseCase;
-    @PostMapping
-    @Operation(summary = "入金登録")
-    public ResponseEntity<ReceiptResponse> recordReceipt(
-            @Valid @RequestBody RecordReceiptRequest request) {
-        Receipt receipt = receiptUseCase.recordReceipt(request.toCommand());
-        return ResponseEntity.status(HttpStatus.CREATED)
-            .body(ReceiptResponse.from(receipt));
-    }
-    @PostMapping("/{receiptNumber}/apply")
-    @Operation(summary = "入金消込")
-    public ResponseEntity<ReceiptResponse> applyReceipt(
-            @PathVariable String receiptNumber,
-            @Valid @RequestBody ApplyReceiptRequest request) {
-        Receipt receipt = receiptUseCase.applyToInvoices(
-            receiptNumber,
-            request.invoiceNumbers()
-        );
-        return ResponseEntity.ok(ReceiptResponse.from(receipt));
-    }
-}
-```
-</details>
----
-## 13.5 エラーハンドリング
-### グローバル例外ハンドラー（@RestControllerAdvice）
-<details>
-<summary>GlobalExceptionHandler.java</summary>
-```java
-package com.example.sms.infrastructure.in.rest.exception;
-import com.example.sms.domain.exception.BusinessRuleViolationException;
-import com.example.sms.domain.exception.DuplicateResourceException;
-import com.example.sms.domain.exception.OptimisticLockException;
-import com.example.sms.domain.exception.ResourceNotFoundException;
-import com.example.sms.infrastructure.in.rest.dto.ErrorResponse;
-import com.example.sms.infrastructure.in.rest.dto.ValidationErrorResponse;
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
-import org.springframework.http.HttpStatus;
-import org.springframework.http.ResponseEntity;
-import org.springframework.validation.FieldError;
-import org.springframework.web.bind.MethodArgumentNotValidException;
-import org.springframework.web.bind.annotation.ExceptionHandler;
-import org.springframework.web.bind.annotation.RestControllerAdvice;
-import java.time.Instant;
-import java.util.Map;
-import java.util.concurrent.ConcurrentHashMap;
-@RestControllerAdvice
-public class GlobalExceptionHandler {
-    private static final Logger LOG = LoggerFactory.getLogger(GlobalExceptionHandler.class);
-    @ExceptionHandler(ResourceNotFoundException.class)
-    public ResponseEntity<ErrorResponse> handleResourceNotFound(ResourceNotFoundException e) {
-        LOG.warn("Resource not found: {}", e.getMessage());
-        ErrorResponse response = new ErrorResponse(
-            HttpStatus.NOT_FOUND.value(),
-            "NOT_FOUND",
-            e.getMessage(),
-            Instant.now()
-        );
-        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(response);
-    }
-    @ExceptionHandler(DuplicateResourceException.class)
-    public ResponseEntity<ErrorResponse> handleDuplicateResource(DuplicateResourceException e) {
-        LOG.warn("Duplicate resource: {}", e.getMessage());
-        ErrorResponse response = new ErrorResponse(
-            HttpStatus.CONFLICT.value(),
-            "CONFLICT",
-            e.getMessage(),
-            Instant.now()
-        );
-        return ResponseEntity.status(HttpStatus.CONFLICT).body(response);
-    }
-    @ExceptionHandler(BusinessRuleViolationException.class)
-    public ResponseEntity<ErrorResponse> handleBusinessRuleViolation(BusinessRuleViolationException e) {
-        LOG.warn("Business rule violation: {}", e.getMessage());
-        ErrorResponse response = new ErrorResponse(
-            HttpStatus.UNPROCESSABLE_ENTITY.value(),
-            "BUSINESS_RULE_VIOLATION",
-            e.getMessage(),
-            Instant.now()
-        );
-        return ResponseEntity.status(HttpStatus.UNPROCESSABLE_ENTITY).body(response);
-    }
-    @ExceptionHandler(OptimisticLockException.class)
-    public ResponseEntity<ErrorResponse> handleOptimisticLock(OptimisticLockException e) {
-        LOG.warn("Optimistic lock exception: {}", e.getMessage());
-        ErrorResponse response = new ErrorResponse(
-            HttpStatus.CONFLICT.value(),
-            "OPTIMISTIC_LOCK",
-            e.getMessage(),
-            Instant.now()
-        );
-        return ResponseEntity.status(HttpStatus.CONFLICT).body(response);
-    }
-    @ExceptionHandler(MethodArgumentNotValidException.class)
-    public ResponseEntity<ValidationErrorResponse> handleValidationErrors(
-            MethodArgumentNotValidException e) {
-        Map<String, String> errors = new ConcurrentHashMap<>();
-        e.getBindingResult().getAllErrors().forEach(error -> {
-            String fieldName = ((FieldError) error).getField();
-            String errorMessage = error.getDefaultMessage();
-            errors.put(fieldName, errorMessage);
-        });
-        ValidationErrorResponse response = new ValidationErrorResponse(
-            HttpStatus.BAD_REQUEST.value(),
-            "VALIDATION_ERROR",
-            "入力値が不正です",
-            errors,
-            Instant.now()
-        );
-        return ResponseEntity.badRequest().body(response);
-    }
-    @ExceptionHandler(Exception.class)
-    public ResponseEntity<ErrorResponse> handleGenericException(Exception e) {
-        LOG.error("Unexpected error occurred", e);
-        ErrorResponse response = new ErrorResponse(
-            HttpStatus.INTERNAL_SERVER_ERROR.value(),
-            "INTERNAL_ERROR",
-            "システムエラーが発生しました",
-            Instant.now()
-        );
-        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(response);
-    }
-}
-```
-</details>
-### ドメイン例外の定義と変換
-<details>
-<summary>ドメイン例外クラス</summary>
-```java
-package com.example.sms.domain.exception;
-public abstract class ResourceNotFoundException extends RuntimeException {
-    protected ResourceNotFoundException(String message) {
-        super(message);
-    }
-}
-public class ProductNotFoundException extends ResourceNotFoundException {
-    public ProductNotFoundException(String productCode) {
-        super("商品が見つかりません: " + productCode);
-    }
-}
-public class OrderNotFoundException extends ResourceNotFoundException {
-    public OrderNotFoundException(String orderNumber) {
-        super("受注が見つかりません: " + orderNumber);
-    }
-}
-public abstract class BusinessRuleViolationException extends RuntimeException {
-    protected BusinessRuleViolationException(String message) {
-        super(message);
-    }
-}
-public class CreditLimitExceededException extends BusinessRuleViolationException {
-    public CreditLimitExceededException(String customerCode, BigDecimal limit, BigDecimal amount) {
-        super(String.format(
-            "与信限度額を超過しています（顧客: %s, 限度額: %s, 申請額: %s）",
-            customerCode, limit, amount
-        ));
-    }
-}
-public class InsufficientInventoryException extends BusinessRuleViolationException {
-    public InsufficientInventoryException(String productCode, BigDecimal available, BigDecimal requested) {
-        super(String.format(
-            "在庫が不足しています（商品: %s, 有効在庫: %s, 要求数量: %s）",
-            productCode, available, requested
-        ));
-    }
-}
-```
-</details>
-### ProblemDetail によるエラーレスポンス
-RFC 7807 に準拠した ProblemDetail 形式でエラーを返却することも可能です。
-<details>
-<summary>エラーレスポンス DTO</summary>
-```java
-public record ErrorResponse(
-    int status,
-    String code,
-    String message,
-    Instant timestamp
-) {}
-public record ValidationErrorResponse(
-    int status,
-    String code,
-    String message,
-    Map<String, String> errors,
-    Instant timestamp
-) {}
-```
-</details>
-### バリデーションエラーの処理
-リクエスト DTO に Bean Validation アノテーションを付与し、バリデーションエラーを統一的に処理します。
-<details>
-<summary>CreateProductRequest.java</summary>
-```java
-public record CreateProductRequest(
-    @NotBlank(message = "商品コードは必須です")
-    String productCode,
-    @NotBlank(message = "商品名は必須です")
-    String productName,
-    @NotBlank(message = "商品分類コードは必須です")
-    String categoryCode,
-    @NotNull(message = "商品区分は必須です")
-    ProductType productType,
-    @NotNull(message = "税区分は必須です")
-    TaxType taxType,
-    @NotNull(message = "販売単価は必須です")
-    @Positive(message = "販売単価は正の数である必要があります")
-    BigDecimal sellingPrice,
-    @NotNull(message = "仕入単価は必須です")
-    @Positive(message = "仕入単価は正の数である必要があります")
-    BigDecimal purchasePrice
-) {}
-```
-</details>
----
-## 13.6 API ドキュメント
-### OpenAPI / Swagger の設定
-<details>
-<summary>OpenApiConfig.java</summary>
-```java
-@Configuration
-public class OpenApiConfig {
-    @Bean
-    public OpenAPI openAPI() {
-        return new OpenAPI()
-            .info(new Info()
-                .title("販売管理システム API")
-                .description("TDD で育てる販売管理システムの API ドキュメント")
-                .version("1.0.0"))
-            .servers(List.of(
-                new Server()
-                    .url("http://localhost:8080")
-                    .description("開発サーバー")))
-            .tags(List.of(
-                new Tag().name("products").description("商品マスタ API"),
-                new Tag().name("partners").description("取引先マスタ API"),
-                new Tag().name("customers").description("顧客 API"),
-                new Tag().name("orders").description("受注 API"),
-                new Tag().name("shipments").description("出荷 API"),
-                new Tag().name("sales").description("売上 API"),
-                new Tag().name("invoices").description("請求 API"),
-                new Tag().name("receipts").description("入金 API")));
-    }
-}
-```
-</details>
-### エンドポイントの文書化
-<details>
-<summary>アノテーションによるドキュメント化</summary>
-```java
-@GetMapping("/{productCode}")
-@Operation(
-    summary = "商品の取得",
-    description = "商品コードを指定して商品情報を取得します"
-)
-@ApiResponse(responseCode = "200", description = "商品を返却")
-@ApiResponse(responseCode = "404", description = "商品が見つからない")
-public ResponseEntity<ProductResponse> getProduct(
-        @Parameter(description = "商品コード", example = "BEEF-001")
-        @PathVariable String productCode) {
-    // ...
-}
-```
-</details>
-### リクエスト・レスポンスのスキーマ定義
-application.yml に Swagger UI の設定を追加します。
-<details>
-<summary>application.yml（Swagger 設定）</summary>
-```yaml
-springdoc:
-  swagger-ui:
-    path: /swagger-ui.html
-    tags-sorter: alpha
-    operations-sorter: alpha
-  api-docs:
-    path: /api-docs
-```
-</details>
-Swagger UI にアクセスすると、API ドキュメントが自動生成されます。
----
-## 13.7 API インテグレーションテスト
-### テストコンテナによる統合テスト環境
-Testcontainers を使用して、実際のデータベース環境で API の統合テストを実行します。
-<details>
-<summary>テスト基盤クラス</summary>
-```java
-@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
-@Testcontainers
-@ActiveProfiles("test")
-public abstract class IntegrationTestBase {
-    @Container
-    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16")
-            .withDatabaseName("sales_test")
-            .withUsername("test")
-            .withPassword("test");
-    @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
-    protected TestRestTemplate restTemplate;
-    @Autowired
-    protected ObjectMapper objectMapper;
-}
-```
-</details>
-### REST API エンドポイントのテスト
-<details>
-<summary>ProductApiIntegrationTest.java</summary>
-```java
-@DisplayName("商品 API 統合テスト")
-class ProductApiIntegrationTest extends IntegrationTestBase {
-    @Nested
-    @DisplayName("商品登録・取得フロー")
-    class ProductCrudFlow {
-        @Test
-        @DisplayName("商品を登録して取得できる")
-        void shouldCreateAndRetrieveProduct() {
-            // Given: 商品登録リクエスト
-            var createRequest = new CreateProductRequest(
-                "BEEF-INT-001",
-                "統合テスト用商品",
-                "CAT-BEEF",
-                ProductType.PRODUCT,
-                TaxType.STANDARD,
-                new BigDecimal("5000"),
-                new BigDecimal("3000")
-            );
-            // When: 商品を登録
-            ResponseEntity<ProductResponse> createResponse = restTemplate.postForEntity(
-                "/api/v1/products",
-                createRequest,
-                ProductResponse.class
-            );
-            // Then: 登録成功
-            assertThat(createResponse.getStatusCode()).isEqualTo(HttpStatus.CREATED);
-            assertThat(createResponse.getBody()).isNotNull();
-            assertThat(createResponse.getBody().productCode()).isEqualTo("BEEF-INT-001");
-            // When: 登録した商品を取得
-            ResponseEntity<ProductResponse> getResponse = restTemplate.getForEntity(
-                "/api/v1/products/BEEF-INT-001",
-                ProductResponse.class
-            );
-            // Then: 取得成功
-            assertThat(getResponse.getStatusCode()).isEqualTo(HttpStatus.OK);
-            assertThat(getResponse.getBody().productName()).isEqualTo("統合テスト用商品");
-        }
-        @Test
-        @DisplayName("存在しない商品を取得すると404エラー")
-        void shouldReturn404WhenProductNotFound() {
-            // When
-            ResponseEntity<ErrorResponse> response = restTemplate.getForEntity(
-                "/api/v1/products/NOT-EXIST",
-                ErrorResponse.class
-            );
-            // Then
-            assertThat(response.getStatusCode()).isEqualTo(HttpStatus.NOT_FOUND);
-            assertThat(response.getBody().code()).isEqualTo("NOT_FOUND");
-        }
-    }
-}
-```
-</details>
-### データベース状態の検証
-<details>
-<summary>OrderApiIntegrationTest.java</summary>
-```java
-@DisplayName("受注 API 統合テスト")
-class OrderApiIntegrationTest extends IntegrationTestBase {
-    @Autowired
-    private JdbcTemplate jdbcTemplate;
-    @BeforeEach
-    void setUp() {
-        // テストデータのセットアップ
-        jdbcTemplate.execute("""
-            INSERT INTO 商品 (商品コード, 適用開始日, 商品名, 販売単価, 仕入単価)
-            VALUES ('BEEF-001', CURRENT_DATE, 'テスト牛肉', 5000, 3000)
-            ON CONFLICT DO NOTHING
-        """);
-    }
-    @Test
-    @DisplayName("受注登録時にデータベースに正しく保存される")
-    void shouldPersistOrderToDatabase() {
-        // Given
-        var createRequest = new CreateOrderRequest(
-            "CUS-001",
-            LocalDate.now(),
-            List.of(new OrderDetailRequest("BEEF-001", 10, new BigDecimal("5000")))
-        );
-        // When
-        ResponseEntity<OrderResponse> response = restTemplate.postForEntity(
-            "/api/v1/orders",
-            createRequest,
-            OrderResponse.class
-        );
-        // Then: API レスポンスの検証
-        assertThat(response.getStatusCode()).isEqualTo(HttpStatus.CREATED);
-        String orderNumber = response.getBody().orderNumber();
-        // Then: データベース状態の検証
-        Integer count = jdbcTemplate.queryForObject(
-            "SELECT COUNT(*) FROM 受注 WHERE 受注番号 = ?",
-            Integer.class,
-            orderNumber
-        );
-        assertThat(count).isEqualTo(1);
-        // Then: 明細データの検証
-        Integer detailCount = jdbcTemplate.queryForObject(
-            "SELECT COUNT(*) FROM 受注明細 WHERE 受注番号 = ?",
-            Integer.class,
-            orderNumber
-        );
-        assertThat(detailCount).isEqualTo(1);
-    }
-}
-```
-</details>
-### テストデータのセットアップとクリーンアップ
-<details>
-<summary>TestDataManager.java</summary>
-```java
-@Component
-@Profile("test")
-public class TestDataManager {
-    private final JdbcTemplate jdbcTemplate;
-    public TestDataManager(JdbcTemplate jdbcTemplate) {
-        this.jdbcTemplate = jdbcTemplate;
-    }
-    @Transactional
-    public void setupMasterData() {
-        // 商品分類マスタ
-        jdbcTemplate.execute("""
-            INSERT INTO 商品分類 (商品分類コード, 適用開始日, 商品分類名)
-            VALUES ('CAT-BEEF', CURRENT_DATE, '牛肉'),
-                   ('CAT-PORK', CURRENT_DATE, '豚肉')
-            ON CONFLICT DO NOTHING
-        """);
-        // 取引先マスタ
-        jdbcTemplate.execute("""
-            INSERT INTO 取引先 (取引先コード, 取引先名, 取引先区分コード)
-            VALUES ('CUS-001', 'テスト顧客', '1'),
-                   ('SUP-001', 'テスト仕入先', '2')
-            ON CONFLICT DO NOTHING
-        """);
-    }
-    @Transactional
-    public void cleanupTransactionData() {
-        // トランザクションデータのクリーンアップ（外部キー制約の順序に注意）
-        jdbcTemplate.execute("DELETE FROM 入金明細");
-        jdbcTemplate.execute("DELETE FROM 入金");
-        jdbcTemplate.execute("DELETE FROM 請求明細");
-        jdbcTemplate.execute("DELETE FROM 請求");
-        jdbcTemplate.execute("DELETE FROM 売上明細");
-        jdbcTemplate.execute("DELETE FROM 売上");
-        jdbcTemplate.execute("DELETE FROM 出荷明細");
-        jdbcTemplate.execute("DELETE FROM 出荷");
-        jdbcTemplate.execute("DELETE FROM 受注明細");
-        jdbcTemplate.execute("DELETE FROM 受注");
-    }
-    @Transactional
-    public void cleanupAll() {
-        cleanupTransactionData();
-        jdbcTemplate.execute("DELETE FROM 商品");
-        jdbcTemplate.execute("DELETE FROM 商品分類");
-        jdbcTemplate.execute("DELETE FROM 取引先");
-    }
-}
-```
-</details>
-<details>
-<summary>統合テストでの使用例</summary>
-```java
-@DisplayName("販売フロー統合テスト")
-class SalesFlowIntegrationTest extends IntegrationTestBase {
-    @Autowired
-    private TestDataManager testDataManager;
-    @BeforeEach
-    void setUp() {
-        testDataManager.cleanupTransactionData();
-        testDataManager.setupMasterData();
-    }
-    @AfterEach
-    void tearDown() {
-        testDataManager.cleanupTransactionData();
-    }
-    @Test
-    @DisplayName("受注から売上までの一連のフローが正常に動作する")
-    void shouldCompleteSalesFlow() {
-        // 1. 受注登録
-        var orderRequest = createOrderRequest();
-        ResponseEntity<OrderResponse> orderResponse = restTemplate.postForEntity(
-            "/api/v1/orders",
-            orderRequest,
-            OrderResponse.class
-        );
-        assertThat(orderResponse.getStatusCode()).isEqualTo(HttpStatus.CREATED);
-        String orderNumber = orderResponse.getBody().orderNumber();
-        // 2. 出荷指示
-        var shipmentRequest = new CreateShipmentInstructionRequest(orderNumber);
-        ResponseEntity<ShipmentInstructionResponse> shipmentResponse = restTemplate.postForEntity(
-            "/api/v1/shipments/instructions",
-            shipmentRequest,
-            ShipmentInstructionResponse.class
-        );
-        assertThat(shipmentResponse.getStatusCode()).isEqualTo(HttpStatus.CREATED);
-        String shipmentNumber = shipmentResponse.getBody().shipmentNumber();
-        // 3. 出荷確定
-        ResponseEntity<ShipmentResponse> confirmResponse = restTemplate.postForEntity(
-            "/api/v1/shipments/" + shipmentNumber + "/confirm",
-            null,
-            ShipmentResponse.class
-        );
-        assertThat(confirmResponse.getStatusCode()).isEqualTo(HttpStatus.OK);
-        // 4. 売上計上の確認
-        ResponseEntity<SalesResponse[]> salesResponse = restTemplate.getForEntity(
-            "/api/v1/sales?orderNumber=" + orderNumber,
-            SalesResponse[].class
-        );
-        assertThat(salesResponse.getStatusCode()).isEqualTo(HttpStatus.OK);
-        assertThat(salesResponse.getBody()).hasSize(1);
-    }
-}
-```
-</details>
----
-## 本章のまとめ
-本章では、販売管理システムの API サービスを実装しました。
-### 実装したコンポーネント
-| カテゴリ | 内容 |
-|----------|------|
-| アーキテクチャ | ヘキサゴナルアーキテクチャ（Ports & Adapters） |
-| マスタ API | 商品マスタ、顧客マスタ |
-| トランザクション API | 受注、出荷、売上、請求・入金 |
-| エラーハンドリング | グローバル例外ハンドラー、ドメイン例外 |
-| API ドキュメント | OpenAPI / Swagger UI |
-### アーキテクチャの利点
-1. **テスト容易性**: ドメインロジックを独立してテスト可能
-2. **技術変更の容易さ**: アダプターを差し替えるだけで技術を変更可能
-3. **保守性**: 関心事の分離による高い保守性
-4. **チーム開発**: レイヤーごとに並行開発が可能
-### エンドポイント一覧
-| メソッド | パス | 説明 |
-|----------|------|------|
-| GET | `/api/v1/products` | 商品一覧の取得 |
-| GET | `/api/v1/products/{code}` | 商品の取得 |
-| POST | `/api/v1/products` | 商品の登録 |
-| PUT | `/api/v1/products/{code}` | 商品の更新 |
-| DELETE | `/api/v1/products/{code}` | 商品の削除 |
-| GET | `/api/v1/orders` | 受注一覧の取得 |
-| POST | `/api/v1/orders` | 受注の登録 |
-| POST | `/api/v1/shipments/instructions` | 出荷指示の登録 |
-| POST | `/api/v1/shipments/{number}/confirm` | 出荷確定 |
-| POST | `/api/v1/sales` | 売上計上 |
-| POST | `/api/v1/invoices/closing` | 請求締め処理 |
-| POST | `/api/v1/receipts` | 入金登録 |
-| POST | `/api/v1/receipts/{number}/apply` | 入金消込 |
+# 第13章：API サービスの実装
+本章では、販売管理システムのデータベース設計を外部から利用できるようにするため、RESTful API サービスを実装します。ヘキサゴナルアーキテクチャ（Ports and Adapters）を採用し、ドメインロジックを外部技術から分離した保守性の高い API を構築します。
+---
+## 13.1 ヘキサゴナルアーキテクチャの復習
+### Ports and Adapters パターンの概要
+ヘキサゴナルアーキテクチャ（Ports and Adapters パターン）は、Alistair Cockburn によって提唱された設計手法で、アプリケーションの中核となるビジネスロジック（ドメイン層）を外部の技術的詳細から完全に分離することを目的とします。
+```plantuml
+@startuml hexagonal_architecture_sales
+!define RECTANGLE class
+package "Hexagonal Architecture (販売管理API)" {
+  RECTANGLE "Application Core\n(Domain + Use Cases)" as core {
+    - Product (商品)
+    - Partner (取引先)
+    - Order (受注)
+    - Sales (売上)
+    - Invoice (請求)
+    - ProductUseCase
+    - OrderUseCase
+    - SalesUseCase
+  }
+  RECTANGLE "Input Adapters\n(Driving Side)" as input {
+    - Spring Controllers
+    - REST API Endpoints
+    - Request Validation
+    - Error Handling
+  }
+  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
+  純粋なビジネスロジック
+  MyBatis に依存しない
+  高速でテスト可能
+end note
+note left of input
+  外部からアプリケーションを
+  駆動するアダプター
+  HTTP, REST等
+end note
+note right of output
+  アプリケーションが外部の
+  技術を使うためのアダプター
+  PostgreSQL, MyBatis等
+end note
+@enduml
+```
+### ドメイン中心設計
+ビジネスロジックを中心に据え、外部技術（DB、Web、UI など）を周辺に配置します。これにより、ビジネスルールが技術的な関心事から独立し、変更に強い設計が実現できます。
+### 依存性の逆転
+ドメイン層は外部に依存せず、外部がドメイン層に依存します。具体的には、リポジトリのインターフェース（Output Port）をドメイン層で定義し、その実装（Adapter）をインフラストラクチャ層に配置します。
+### テスト容易性
+モックやスタブを使った単体テストが容易になります。ドメインロジックを独立してテストでき、外部依存（データベースなど）なしで高速なテストが可能です。
+---
+## 13.2 アーキテクチャ構造
+### レイヤー構成
+販売管理 API の実装では、以下のレイヤー構造を採用します。
+```
+src/main/java/com/example/sms/
+├── domain/                     # ドメイン層（純粋なビジネスロジック）
+│   ├── model/                 # ドメインモデル（エンティティ、値オブジェクト）
+│   │   ├── department/        # 部門関連
+│   │   ├── employee/          # 社員関連
+│   │   ├── inventory/         # 在庫関連
+│   │   ├── partner/           # 取引先関連
+│   │   ├── product/           # 商品関連
+│   │   ├── purchase/          # 仕入関連
+│   │   └── sales/             # 販売関連
+│   ├── exception/             # ドメイン例外
+│   └── type/                  # 値型定義
+│
+├── application/               # アプリケーション層
+│   └── port/
+│       └── out/              # Output Port（リポジトリインターフェース）
+│
+├── infrastructure/            # インフラストラクチャ層
+│   ├── in/                   # Input Adapter（受信アダプター）
+│   │   ├── rest/             # REST API（Web実装）
+│   │   │   ├── controller/   # REST Controller（Spring MVC）
+│   │   │   ├── dto/          # Data Transfer Object
+│   │   │   └── exception/    # Exception Handler
+│   │   └── seed/             # Seed データ投入
+│   └── out/                  # Output Adapter（送信アダプター）
+│       └── persistence/      # DB実装
+│           ├── mapper/       # MyBatis Mapper
+│           ├── repository/   # Repository実装
+│           └── typehandler/  # 型ハンドラー
+│
+└── config/                   # 設定クラス
+```
+### Domain 層
+ビジネスルールとドメインモデルを定義します。外部技術に依存しない純粋な Java コードで構成されます。
+<details>
+<summary>Product.java（商品ドメインモデル）</summary>
+```java
+package com.example.sms.domain.model.product;
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+import java.math.BigDecimal;
+import java.time.LocalDateTime;
+/**
+ * 商品エンティティ.
+ */
+@Data
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+public class Product {
+    private String productCode;
+    private String productFullName;
+    private String productName;
+    private String productNameKana;
+    private ProductCategory productCategory;
+    private String modelNumber;
+    @Builder.Default
+    private BigDecimal sellingPrice = BigDecimal.ZERO;
+    @Builder.Default
+    private BigDecimal purchasePrice = BigDecimal.ZERO;
+    private TaxCategory taxCategory;
+    private String classificationCode;
+    @Builder.Default
+    private boolean isMiscellaneous = false;
+    @Builder.Default
+    private boolean isInventoryManaged = true;
+    @Builder.Default
+    private boolean isInventoryAllocated = true;
+    private String supplierCode;
+    private String supplierBranchNumber;
+    private LocalDateTime createdAt;
+    private String createdBy;
+    private LocalDateTime updatedAt;
+    private String updatedBy;
+}
+```
+</details>
+### Application 層
+ユースケースの実装とオーケストレーションを担当します。
+<details>
+<summary>ProductRepository.java（Output Port）</summary>
+```java
+package com.example.sms.application.port.out;
+import com.example.sms.domain.model.product.Product;
+import com.example.sms.domain.model.product.ProductCategory;
+import java.util.List;
+import java.util.Optional;
+/**
+ * 商品リポジトリ（Output Port）.
+ */
+public interface ProductRepository {
+    void save(Product product);
+    Optional<Product> findByCode(String productCode);
+    List<Product> findAll();
+    List<Product> findByCategory(ProductCategory category);
+    List<Product> findByClassificationCode(String classificationCode);
+    void update(Product product);
+    void deleteByCode(String productCode);
+    void deleteAll();
+}
+```
+</details>
+### Infrastructure 層
+外部技術との接続を担当します。DB アクセス（MyBatis）や Web フレームワーク（Spring MVC）の実装を含みます。
+### Input Port / Output Port の分離
+| ポート | 役割 | 例 |
+|--------|------|-----|
+| Input Port | アプリケーションへの入力インターフェース | `ProductUseCase`, `OrderUseCase` |
+| Output Port | アプリケーションからの出力インターフェース | `ProductRepository`, `OrderRepository` |
+---
+## 13.3 マスタ API の実装
+### 商品マスタ API（CRUD エンドポイント）
+#### Output Port（リポジトリインターフェース）
+<details>
+<summary>ProductRepository.java</summary>
+```java
+package com.example.sms.application.port.out;
+/**
+ * 商品リポジトリ（Output Port）
+ */
+public interface ProductRepository {
+    Product save(Product product);
+    List<Product> findAll();
+    Optional<Product> findByCode(String productCode, LocalDate effectiveDate);
+    List<Product> findByType(ProductType type);
+    List<Product> findByCategoryCode(String categoryCode);
+    void deleteByCode(String productCode, LocalDate effectiveDate);
+}
+```
+</details>
+#### Input Port（ユースケースインターフェース）
+<details>
+<summary>コマンドオブジェクト</summary>
+```java
+package com.example.sms.application.port.in;
+public record CreateProductCommand(
+    String productCode,
+    String productName,
+    String categoryCode,
+    ProductType productType,
+    TaxType taxType,
+    BigDecimal sellingPrice,
+    BigDecimal purchasePrice
+) {}
+public record UpdateProductCommand(
+    String productCode,
+    String productName,
+    ProductType productType,
+    TaxType taxType,
+    BigDecimal sellingPrice,
+    BigDecimal purchasePrice
+) {}
+```
+</details>
+### TDD による実装（Red-Green-Refactor）
+#### Red: 失敗するテストを書く
+<details>
+<summary>ProductControllerTest.java</summary>
+```java
+package com.example.sms.infrastructure.in.rest;
+import com.example.sms.application.port.out.ProductClassificationRepository;
+import com.example.sms.application.port.out.ProductRepository;
+import com.example.sms.domain.model.product.Product;
+import com.example.sms.domain.model.product.ProductCategory;
+import com.example.sms.domain.model.product.ProductClassification;
+import com.example.sms.domain.model.product.TaxCategory;
+import com.example.sms.testsetup.BaseIntegrationTest;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Nested;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.webmvc.test.autoconfigure.AutoConfigureMockMvc;
+import org.springframework.http.MediaType;
+import org.springframework.test.web.servlet.MockMvc;
+import java.math.BigDecimal;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;
+@AutoConfigureMockMvc
+@DisplayName("商品マスタ API テスト")
+class ProductControllerTest extends BaseIntegrationTest {
+    private static final String TEST_CLASSIFICATION_CODE = "CAT-TEST";
+    @Autowired
+    private MockMvc mockMvc;
+    @Autowired
+    private ProductRepository productRepository;
+    @Autowired
+    private ProductClassificationRepository productClassificationRepository;
+    @BeforeEach
+    void setUp() {
+        productRepository.deleteAll();
+        productClassificationRepository.deleteAll();
+        // テスト用の商品分類を作成
+        ProductClassification classification = ProductClassification.builder()
+            .classificationCode(TEST_CLASSIFICATION_CODE)
+            .classificationName("テスト分類")
+            .hierarchyLevel(1)
+            .classificationPath("/CAT-TEST")
+            .isLeaf(true)
+            .build();
+        productClassificationRepository.save(classification);
+    }
+    @Nested
+    @DisplayName("POST /api/v1/products")
+    class CreateProduct {
+        @Test
+        @DisplayName("商品を登録できる")
+        void shouldCreateProduct() throws Exception {
+            var request = """
+                {
+                    "productCode": "NEW-001",
+                    "productFullName": "新規テスト商品 フルネーム",
+                    "productName": "新規テスト商品",
+                    "productNameKana": "シンキテストショウヒン",
+                    "productCategory": "PRODUCT",
+                    "modelNumber": "MODEL-001",
+                    "sellingPrice": 5000,
+                    "purchasePrice": 3000,
+                    "taxCategory": "EXCLUSIVE",
+                    "classificationCode": "CAT-TEST"
+                }
+                """;
+            mockMvc.perform(post("/api/v1/products")
+                    .contentType(MediaType.APPLICATION_JSON)
+                    .content(request))
+                .andExpect(status().isCreated())
+                .andExpect(jsonPath("$.productCode").value("NEW-001"))
+                .andExpect(jsonPath("$.productName").value("新規テスト商品"));
+        }
+    }
+}
+```
+</details>
+#### Green: テストを通す実装
+<details>
+<summary>ProductController.java</summary>
+```java
+package com.example.sms.infrastructure.in.rest.controller;
+import com.example.sms.application.port.out.ProductRepository;
+import com.example.sms.domain.exception.DuplicateProductException;
+import com.example.sms.domain.exception.ProductNotFoundException;
+import com.example.sms.domain.model.product.Product;
+import com.example.sms.infrastructure.in.rest.dto.CreateProductRequest;
+import com.example.sms.infrastructure.in.rest.dto.ProductResponse;
+import com.example.sms.infrastructure.in.rest.dto.UpdateProductRequest;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.validation.Valid;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.*;
+import java.util.List;
+@RestController
+@RequestMapping("/api/v1/products")
+@Tag(name = "products", description = "商品マスタ API")
+public class ProductController {
+    private final ProductRepository productRepository;
+    public ProductController(ProductRepository productRepository) {
+        this.productRepository = productRepository;
+    }
+    @GetMapping
+    @Operation(summary = "商品一覧の取得")
+    @ApiResponse(responseCode = "200", description = "商品一覧を返却")
+    public ResponseEntity<List<ProductResponse>> getAllProducts() {
+        List<Product> products = productRepository.findAll();
+        List<ProductResponse> responses = products.stream()
+            .map(ProductResponse::from)
+            .toList();
+        return ResponseEntity.ok(responses);
+    }
+    @GetMapping("/{productCode}")
+    @Operation(summary = "商品の取得")
+    @ApiResponse(responseCode = "200", description = "商品を返却")
+    @ApiResponse(responseCode = "404", description = "商品が見つからない")
+    public ResponseEntity<ProductResponse> getProduct(
+            @Parameter(description = "商品コード")
+            @PathVariable String productCode) {
+        Product product = productRepository.findByCode(productCode)
+            .orElseThrow(() -> new ProductNotFoundException(productCode));
+        return ResponseEntity.ok(ProductResponse.from(product));
+    }
+    @PostMapping
+    @Operation(summary = "商品の登録")
+    @ApiResponse(responseCode = "201", description = "商品を登録")
+    @ApiResponse(responseCode = "409", description = "商品が既に存在する")
+    public ResponseEntity<ProductResponse> createProduct(
+            @Valid @RequestBody CreateProductRequest request) {
+        // 重複チェック
+        productRepository.findByCode(request.productCode())
+            .ifPresent(existing -> {
+                throw new DuplicateProductException(request.productCode());
+            });
+        Product product = Product.builder()
+            .productCode(request.productCode())
+            .productFullName(request.productFullName())
+            .productName(request.productName())
+            .productNameKana(request.productNameKana())
+            .productCategory(request.productCategory())
+            .modelNumber(request.modelNumber())
+            .sellingPrice(request.sellingPrice())
+            .purchasePrice(request.purchasePrice())
+            .taxCategory(request.taxCategory())
+            .classificationCode(request.classificationCode())
+            .build();
+        productRepository.save(product);
+        return ResponseEntity.status(HttpStatus.CREATED)
+            .body(ProductResponse.from(product));
+    }
+}
+```
+</details>
+### Controller・Service・Repository の実装
+#### Application Service
+<details>
+<summary>ProductService.java</summary>
+```java
+@Service
+@Transactional
+public class ProductService implements ProductUseCase {
+    private final ProductRepository productRepository;
+    public ProductService(ProductRepository productRepository) {
+        this.productRepository = productRepository;
+    }
+    @Override
+    public Product createProduct(CreateProductCommand command) {
+        LocalDate effectiveDate = LocalDate.now();
+        // 重複チェック
+        productRepository.findByCode(command.productCode(), effectiveDate)
+            .ifPresent(existing -> {
+                throw new DuplicateProductException(command.productCode());
+            });
+        Product product = new Product(
+            command.productCode(),
+            effectiveDate,
+            command.productName(),
+            command.categoryCode(),
+            effectiveDate,
+            command.productType(),
+            command.taxType(),
+            command.sellingPrice(),
+            command.purchasePrice()
+        );
+        return productRepository.save(product);
+    }
+    @Override
+    @Transactional(readOnly = true)
+    public Product getProductByCode(String productCode) {
+        LocalDate effectiveDate = LocalDate.now();
+        return productRepository.findByCode(productCode, effectiveDate)
+            .orElseThrow(() -> new ProductNotFoundException(productCode));
+    }
+}
+```
+</details>
+### 顧客マスタ API（請求先・回収先の管理）
+顧客マスタ API では、請求先と回収先の概念を正しく管理します。
+<details>
+<summary>CustomerController.java</summary>
+```java
+@RestController
+@RequestMapping("/api/v1/customers")
+@Tag(name = "customers", description = "顧客 API")
+public class CustomerController {
+    private final CustomerUseCase customerUseCase;
+    @GetMapping("/{customerCode}")
+    @Operation(summary = "顧客の取得")
+    public ResponseEntity<CustomerResponse> getCustomer(
+            @PathVariable String customerCode) {
+        Customer customer = customerUseCase.getCustomerByCode(customerCode);
+        return ResponseEntity.ok(CustomerResponse.from(customer));
+    }
+    @GetMapping("/{customerCode}/billing-destinations")
+    @Operation(summary = "請求先一覧の取得")
+    public ResponseEntity<List<BillingDestinationResponse>> getBillingDestinations(
+            @PathVariable String customerCode) {
+        List<BillingDestination> destinations =
+            customerUseCase.getBillingDestinations(customerCode);
+        return ResponseEntity.ok(destinations.stream()
+            .map(BillingDestinationResponse::from)
+            .toList());
+    }
+}
+```
+</details>
+---
+## 13.4 トランザクション API の実装
+### 受注 API（受注登録・受注照会・受注明細照会）
+<details>
+<summary>OrderController.java</summary>
+```java
+@RestController
+@RequestMapping("/api/v1/orders")
+@Tag(name = "orders", description = "受注 API")
+public class OrderController {
+    private final OrderUseCase orderUseCase;
+    @PostMapping
+    @Operation(summary = "受注の登録")
+    public ResponseEntity<OrderResponse> createOrder(
+            @Valid @RequestBody CreateOrderRequest request) {
+        Order order = orderUseCase.createOrder(request.toCommand());
+        return ResponseEntity.status(HttpStatus.CREATED)
+            .body(OrderResponse.from(order));
+    }
+    @GetMapping("/{orderNumber}")
+    @Operation(summary = "受注の取得")
+    public ResponseEntity<OrderResponse> getOrder(
+            @PathVariable String orderNumber) {
+        Order order = orderUseCase.getOrderByNumber(orderNumber);
+        return ResponseEntity.ok(OrderResponse.from(order));
+    }
+    @GetMapping("/{orderNumber}/details")
+    @Operation(summary = "受注明細の取得")
+    public ResponseEntity<List<OrderDetailResponse>> getOrderDetails(
+            @PathVariable String orderNumber) {
+        List<OrderDetail> details = orderUseCase.getOrderDetails(orderNumber);
+        return ResponseEntity.ok(details.stream()
+            .map(OrderDetailResponse::from)
+            .toList());
+    }
+}
+```
+</details>
+### 出荷 API（出荷指示・出荷確定）
+<details>
+<summary>ShipmentController.java</summary>
+```java
+@RestController
+@RequestMapping("/api/v1/shipments")
+@Tag(name = "shipments", description = "出荷 API")
+public class ShipmentController {
+    private final ShipmentUseCase shipmentUseCase;
+    @PostMapping("/instructions")
+    @Operation(summary = "出荷指示の登録")
+    public ResponseEntity<ShipmentInstructionResponse> createShipmentInstruction(
+            @Valid @RequestBody CreateShipmentInstructionRequest request) {
+        ShipmentInstruction instruction =
+            shipmentUseCase.createInstruction(request.toCommand());
+        return ResponseEntity.status(HttpStatus.CREATED)
+            .body(ShipmentInstructionResponse.from(instruction));
+    }
+    @PostMapping("/{shipmentNumber}/confirm")
+    @Operation(summary = "出荷確定")
+    public ResponseEntity<ShipmentResponse> confirmShipment(
+            @PathVariable String shipmentNumber) {
+        Shipment shipment = shipmentUseCase.confirmShipment(shipmentNumber);
+        return ResponseEntity.ok(ShipmentResponse.from(shipment));
+    }
+}
+```
+</details>
+### 売上 API（売上計上・売上照会）
+<details>
+<summary>SalesController.java</summary>
+```java
+@RestController
+@RequestMapping("/api/v1/sales")
+@Tag(name = "sales", description = "売上 API")
+public class SalesController {
+    private final SalesUseCase salesUseCase;
+    @PostMapping
+    @Operation(summary = "売上計上")
+    public ResponseEntity<SalesResponse> recordSales(
+            @Valid @RequestBody RecordSalesRequest request) {
+        Sales sales = salesUseCase.recordSales(request.toCommand());
+        return ResponseEntity.status(HttpStatus.CREATED)
+            .body(SalesResponse.from(sales));
+    }
+    @GetMapping
+    @Operation(summary = "売上一覧の取得")
+    public ResponseEntity<List<SalesResponse>> getSalesList(
+            @RequestParam(required = false) LocalDate fromDate,
+            @RequestParam(required = false) LocalDate toDate,
+            @RequestParam(required = false) String customerCode) {
+        List<Sales> salesList = salesUseCase.getSalesList(fromDate, toDate, customerCode);
+        return ResponseEntity.ok(salesList.stream()
+            .map(SalesResponse::from)
+            .toList());
+    }
+}
+```
+</details>
+### 請求・入金 API（請求締め・入金消込）
+<details>
+<summary>InvoiceController.java / ReceiptController.java</summary>
+```java
+@RestController
+@RequestMapping("/api/v1/invoices")
+@Tag(name = "invoices", description = "請求 API")
+public class InvoiceController {
+    private final InvoiceUseCase invoiceUseCase;
+    @PostMapping("/closing")
+    @Operation(summary = "請求締め処理")
+    public ResponseEntity<List<InvoiceResponse>> executeClosing(
+            @Valid @RequestBody InvoiceClosingRequest request) {
+        List<Invoice> invoices = invoiceUseCase.executeClosing(
+            request.closingDate(),
+            request.customerCode()
+        );
+        return ResponseEntity.ok(invoices.stream()
+            .map(InvoiceResponse::from)
+            .toList());
+    }
+}
+@RestController
+@RequestMapping("/api/v1/receipts")
+@Tag(name = "receipts", description = "入金 API")
+public class ReceiptController {
+    private final ReceiptUseCase receiptUseCase;
+    @PostMapping
+    @Operation(summary = "入金登録")
+    public ResponseEntity<ReceiptResponse> recordReceipt(
+            @Valid @RequestBody RecordReceiptRequest request) {
+        Receipt receipt = receiptUseCase.recordReceipt(request.toCommand());
+        return ResponseEntity.status(HttpStatus.CREATED)
+            .body(ReceiptResponse.from(receipt));
+    }
+    @PostMapping("/{receiptNumber}/apply")
+    @Operation(summary = "入金消込")
+    public ResponseEntity<ReceiptResponse> applyReceipt(
+            @PathVariable String receiptNumber,
+            @Valid @RequestBody ApplyReceiptRequest request) {
+        Receipt receipt = receiptUseCase.applyToInvoices(
+            receiptNumber,
+            request.invoiceNumbers()
+        );
+        return ResponseEntity.ok(ReceiptResponse.from(receipt));
+    }
+}
+```
+</details>
+---
+## 13.5 エラーハンドリング
+### グローバル例外ハンドラー（@RestControllerAdvice）
+<details>
+<summary>GlobalExceptionHandler.java</summary>
+```java
+package com.example.sms.infrastructure.in.rest.exception;
+import com.example.sms.domain.exception.BusinessRuleViolationException;
+import com.example.sms.domain.exception.DuplicateResourceException;
+import com.example.sms.domain.exception.OptimisticLockException;
+import com.example.sms.domain.exception.ResourceNotFoundException;
+import com.example.sms.infrastructure.in.rest.dto.ErrorResponse;
+import com.example.sms.infrastructure.in.rest.dto.ValidationErrorResponse;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.validation.FieldError;
+import org.springframework.web.bind.MethodArgumentNotValidException;
+import org.springframework.web.bind.annotation.ExceptionHandler;
+import org.springframework.web.bind.annotation.RestControllerAdvice;
+import java.time.Instant;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+@RestControllerAdvice
+public class GlobalExceptionHandler {
+    private static final Logger LOG = LoggerFactory.getLogger(GlobalExceptionHandler.class);
+    @ExceptionHandler(ResourceNotFoundException.class)
+    public ResponseEntity<ErrorResponse> handleResourceNotFound(ResourceNotFoundException e) {
+        LOG.warn("Resource not found: {}", e.getMessage());
+        ErrorResponse response = new ErrorResponse(
+            HttpStatus.NOT_FOUND.value(),
+            "NOT_FOUND",
+            e.getMessage(),
+            Instant.now()
+        );
+        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(response);
+    }
+    @ExceptionHandler(DuplicateResourceException.class)
+    public ResponseEntity<ErrorResponse> handleDuplicateResource(DuplicateResourceException e) {
+        LOG.warn("Duplicate resource: {}", e.getMessage());
+        ErrorResponse response = new ErrorResponse(
+            HttpStatus.CONFLICT.value(),
+            "CONFLICT",
+            e.getMessage(),
+            Instant.now()
+        );
+        return ResponseEntity.status(HttpStatus.CONFLICT).body(response);
+    }
+    @ExceptionHandler(BusinessRuleViolationException.class)
+    public ResponseEntity<ErrorResponse> handleBusinessRuleViolation(BusinessRuleViolationException e) {
+        LOG.warn("Business rule violation: {}", e.getMessage());
+        ErrorResponse response = new ErrorResponse(
+            HttpStatus.UNPROCESSABLE_ENTITY.value(),
+            "BUSINESS_RULE_VIOLATION",
+            e.getMessage(),
+            Instant.now()
+        );
+        return ResponseEntity.status(HttpStatus.UNPROCESSABLE_ENTITY).body(response);
+    }
+    @ExceptionHandler(OptimisticLockException.class)
+    public ResponseEntity<ErrorResponse> handleOptimisticLock(OptimisticLockException e) {
+        LOG.warn("Optimistic lock exception: {}", e.getMessage());
+        ErrorResponse response = new ErrorResponse(
+            HttpStatus.CONFLICT.value(),
+            "OPTIMISTIC_LOCK",
+            e.getMessage(),
+            Instant.now()
+        );
+        return ResponseEntity.status(HttpStatus.CONFLICT).body(response);
+    }
+    @ExceptionHandler(MethodArgumentNotValidException.class)
+    public ResponseEntity<ValidationErrorResponse> handleValidationErrors(
+            MethodArgumentNotValidException e) {
+        Map<String, String> errors = new ConcurrentHashMap<>();
+        e.getBindingResult().getAllErrors().forEach(error -> {
+            String fieldName = ((FieldError) error).getField();
+            String errorMessage = error.getDefaultMessage();
+            errors.put(fieldName, errorMessage);
+        });
+        ValidationErrorResponse response = new ValidationErrorResponse(
+            HttpStatus.BAD_REQUEST.value(),
+            "VALIDATION_ERROR",
+            "入力値が不正です",
+            errors,
+            Instant.now()
+        );
+        return ResponseEntity.badRequest().body(response);
+    }
+    @ExceptionHandler(Exception.class)
+    public ResponseEntity<ErrorResponse> handleGenericException(Exception e) {
+        LOG.error("Unexpected error occurred", e);
+        ErrorResponse response = new ErrorResponse(
+            HttpStatus.INTERNAL_SERVER_ERROR.value(),
+            "INTERNAL_ERROR",
+            "システムエラーが発生しました",
+            Instant.now()
+        );
+        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(response);
+    }
+}
+```
+</details>
+### ドメイン例外の定義と変換
+<details>
+<summary>ドメイン例外クラス</summary>
+```java
+package com.example.sms.domain.exception;
+public abstract class ResourceNotFoundException extends RuntimeException {
+    protected ResourceNotFoundException(String message) {
+        super(message);
+    }
+}
+public class ProductNotFoundException extends ResourceNotFoundException {
+    public ProductNotFoundException(String productCode) {
+        super("商品が見つかりません: " + productCode);
+    }
+}
+public class OrderNotFoundException extends ResourceNotFoundException {
+    public OrderNotFoundException(String orderNumber) {
+        super("受注が見つかりません: " + orderNumber);
+    }
+}
+public abstract class BusinessRuleViolationException extends RuntimeException {
+    protected BusinessRuleViolationException(String message) {
+        super(message);
+    }
+}
+public class CreditLimitExceededException extends BusinessRuleViolationException {
+    public CreditLimitExceededException(String customerCode, BigDecimal limit, BigDecimal amount) {
+        super(String.format(
+            "与信限度額を超過しています（顧客: %s, 限度額: %s, 申請額: %s）",
+            customerCode, limit, amount
+        ));
+    }
+}
+public class InsufficientInventoryException extends BusinessRuleViolationException {
+    public InsufficientInventoryException(String productCode, BigDecimal available, BigDecimal requested) {
+        super(String.format(
+            "在庫が不足しています（商品: %s, 有効在庫: %s, 要求数量: %s）",
+            productCode, available, requested
+        ));
+    }
+}
+```
+</details>
+### ProblemDetail によるエラーレスポンス
+RFC 7807 に準拠した ProblemDetail 形式でエラーを返却することも可能です。
+<details>
+<summary>エラーレスポンス DTO</summary>
+```java
+public record ErrorResponse(
+    int status,
+    String code,
+    String message,
+    Instant timestamp
+) {}
+public record ValidationErrorResponse(
+    int status,
+    String code,
+    String message,
+    Map<String, String> errors,
+    Instant timestamp
+) {}
+```
+</details>
+### バリデーションエラーの処理
+リクエスト DTO に Bean Validation アノテーションを付与し、バリデーションエラーを統一的に処理します。
+<details>
+<summary>CreateProductRequest.java</summary>
+```java
+public record CreateProductRequest(
+    @NotBlank(message = "商品コードは必須です")
+    String productCode,
+    @NotBlank(message = "商品名は必須です")
+    String productName,
+    @NotBlank(message = "商品分類コードは必須です")
+    String categoryCode,
+    @NotNull(message = "商品区分は必須です")
+    ProductType productType,
+    @NotNull(message = "税区分は必須です")
+    TaxType taxType,
+    @NotNull(message = "販売単価は必須です")
+    @Positive(message = "販売単価は正の数である必要があります")
+    BigDecimal sellingPrice,
+    @NotNull(message = "仕入単価は必須です")
+    @Positive(message = "仕入単価は正の数である必要があります")
+    BigDecimal purchasePrice
+) {}
+```
+</details>
+---
+## 13.6 API ドキュメント
+### OpenAPI / Swagger の設定
+<details>
+<summary>OpenApiConfig.java</summary>
+```java
+@Configuration
+public class OpenApiConfig {
+    @Bean
+    public OpenAPI openAPI() {
+        return new OpenAPI()
+            .info(new Info()
+                .title("販売管理システム API")
+                .description("TDD で育てる販売管理システムの API ドキュメント")
+                .version("1.0.0"))
+            .servers(List.of(
+                new Server()
+                    .url("http://localhost:8080")
+                    .description("開発サーバー")))
+            .tags(List.of(
+                new Tag().name("products").description("商品マスタ API"),
+                new Tag().name("partners").description("取引先マスタ API"),
+                new Tag().name("customers").description("顧客 API"),
+                new Tag().name("orders").description("受注 API"),
+                new Tag().name("shipments").description("出荷 API"),
+                new Tag().name("sales").description("売上 API"),
+                new Tag().name("invoices").description("請求 API"),
+                new Tag().name("receipts").description("入金 API")));
+    }
+}
+```
+</details>
+### エンドポイントの文書化
+<details>
+<summary>アノテーションによるドキュメント化</summary>
+```java
+@GetMapping("/{productCode}")
+@Operation(
+    summary = "商品の取得",
+    description = "商品コードを指定して商品情報を取得します"
+)
+@ApiResponse(responseCode = "200", description = "商品を返却")
+@ApiResponse(responseCode = "404", description = "商品が見つからない")
+public ResponseEntity<ProductResponse> getProduct(
+        @Parameter(description = "商品コード", example = "BEEF-001")
+        @PathVariable String productCode) {
+    // ...
+}
+```
+</details>
+### リクエスト・レスポンスのスキーマ定義
+application.yml に Swagger UI の設定を追加します。
+<details>
+<summary>application.yml（Swagger 設定）</summary>
+```yaml
+springdoc:
+  swagger-ui:
+    path: /swagger-ui.html
+    tags-sorter: alpha
+    operations-sorter: alpha
+  api-docs:
+    path: /api-docs
+```
+</details>
+Swagger UI にアクセスすると、API ドキュメントが自動生成されます。
+---
+## 13.7 API インテグレーションテスト
+### テストコンテナによる統合テスト環境
+Testcontainers を使用して、実際のデータベース環境で API の統合テストを実行します。
+<details>
+<summary>テスト基盤クラス</summary>
+```java
+@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
+@Testcontainers
+@ActiveProfiles("test")
+public abstract class IntegrationTestBase {
+    @Container
+    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16")
+            .withDatabaseName("sales_test")
+            .withUsername("test")
+            .withPassword("test");
+    @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
+    protected TestRestTemplate restTemplate;
+    @Autowired
+    protected ObjectMapper objectMapper;
+}
+```
+</details>
+### REST API エンドポイントのテスト
+<details>
+<summary>ProductApiIntegrationTest.java</summary>
+```java
+@DisplayName("商品 API 統合テスト")
+class ProductApiIntegrationTest extends IntegrationTestBase {
+    @Nested
+    @DisplayName("商品登録・取得フロー")
+    class ProductCrudFlow {
+        @Test
+        @DisplayName("商品を登録して取得できる")
+        void shouldCreateAndRetrieveProduct() {
+            // Given: 商品登録リクエスト
+            var createRequest = new CreateProductRequest(
+                "BEEF-INT-001",
+                "統合テスト用商品",
+                "CAT-BEEF",
+                ProductType.PRODUCT,
+                TaxType.STANDARD,
+                new BigDecimal("5000"),
+                new BigDecimal("3000")
+            );
+            // When: 商品を登録
+            ResponseEntity<ProductResponse> createResponse = restTemplate.postForEntity(
+                "/api/v1/products",
+                createRequest,
+                ProductResponse.class
+            );
+            // Then: 登録成功
+            assertThat(createResponse.getStatusCode()).isEqualTo(HttpStatus.CREATED);
+            assertThat(createResponse.getBody()).isNotNull();
+            assertThat(createResponse.getBody().productCode()).isEqualTo("BEEF-INT-001");
+            // When: 登録した商品を取得
+            ResponseEntity<ProductResponse> getResponse = restTemplate.getForEntity(
+                "/api/v1/products/BEEF-INT-001",
+                ProductResponse.class
+            );
+            // Then: 取得成功
+            assertThat(getResponse.getStatusCode()).isEqualTo(HttpStatus.OK);
+            assertThat(getResponse.getBody().productName()).isEqualTo("統合テスト用商品");
+        }
+        @Test
+        @DisplayName("存在しない商品を取得すると404エラー")
+        void shouldReturn404WhenProductNotFound() {
+            // When
+            ResponseEntity<ErrorResponse> response = restTemplate.getForEntity(
+                "/api/v1/products/NOT-EXIST",
+                ErrorResponse.class
+            );
+            // Then
+            assertThat(response.getStatusCode()).isEqualTo(HttpStatus.NOT_FOUND);
+            assertThat(response.getBody().code()).isEqualTo("NOT_FOUND");
+        }
+    }
+}
+```
+</details>
+### データベース状態の検証
+<details>
+<summary>OrderApiIntegrationTest.java</summary>
+```java
+@DisplayName("受注 API 統合テスト")
+class OrderApiIntegrationTest extends IntegrationTestBase {
+    @Autowired
+    private JdbcTemplate jdbcTemplate;
+    @BeforeEach
+    void setUp() {
+        // テストデータのセットアップ
+        jdbcTemplate.execute("""
+            INSERT INTO 商品 (商品コード, 適用開始日, 商品名, 販売単価, 仕入単価)
+            VALUES ('BEEF-001', CURRENT_DATE, 'テスト牛肉', 5000, 3000)
+            ON CONFLICT DO NOTHING
+        """);
+    }
+    @Test
+    @DisplayName("受注登録時にデータベースに正しく保存される")
+    void shouldPersistOrderToDatabase() {
+        // Given
+        var createRequest = new CreateOrderRequest(
+            "CUS-001",
+            LocalDate.now(),
+            List.of(new OrderDetailRequest("BEEF-001", 10, new BigDecimal("5000")))
+        );
+        // When
+        ResponseEntity<OrderResponse> response = restTemplate.postForEntity(
+            "/api/v1/orders",
+            createRequest,
+            OrderResponse.class
+        );
+        // Then: API レスポンスの検証
+        assertThat(response.getStatusCode()).isEqualTo(HttpStatus.CREATED);
+        String orderNumber = response.getBody().orderNumber();
+        // Then: データベース状態の検証
+        Integer count = jdbcTemplate.queryForObject(
+            "SELECT COUNT(*) FROM 受注 WHERE 受注番号 = ?",
+            Integer.class,
+            orderNumber
+        );
+        assertThat(count).isEqualTo(1);
+        // Then: 明細データの検証
+        Integer detailCount = jdbcTemplate.queryForObject(
+            "SELECT COUNT(*) FROM 受注明細 WHERE 受注番号 = ?",
+            Integer.class,
+            orderNumber
+        );
+        assertThat(detailCount).isEqualTo(1);
+    }
+}
+```
+</details>
+### テストデータのセットアップとクリーンアップ
+<details>
+<summary>TestDataManager.java</summary>
+```java
+@Component
+@Profile("test")
+public class TestDataManager {
+    private final JdbcTemplate jdbcTemplate;
+    public TestDataManager(JdbcTemplate jdbcTemplate) {
+        this.jdbcTemplate = jdbcTemplate;
+    }
+    @Transactional
+    public void setupMasterData() {
+        // 商品分類マスタ
+        jdbcTemplate.execute("""
+            INSERT INTO 商品分類 (商品分類コード, 適用開始日, 商品分類名)
+            VALUES ('CAT-BEEF', CURRENT_DATE, '牛肉'),
+                   ('CAT-PORK', CURRENT_DATE, '豚肉')
+            ON CONFLICT DO NOTHING
+        """);
+        // 取引先マスタ
+        jdbcTemplate.execute("""
+            INSERT INTO 取引先 (取引先コード, 取引先名, 取引先区分コード)
+            VALUES ('CUS-001', 'テスト顧客', '1'),
+                   ('SUP-001', 'テスト仕入先', '2')
+            ON CONFLICT DO NOTHING
+        """);
+    }
+    @Transactional
+    public void cleanupTransactionData() {
+        // トランザクションデータのクリーンアップ（外部キー制約の順序に注意）
+        jdbcTemplate.execute("DELETE FROM 入金明細");
+        jdbcTemplate.execute("DELETE FROM 入金");
+        jdbcTemplate.execute("DELETE FROM 請求明細");
+        jdbcTemplate.execute("DELETE FROM 請求");
+        jdbcTemplate.execute("DELETE FROM 売上明細");
+        jdbcTemplate.execute("DELETE FROM 売上");
+        jdbcTemplate.execute("DELETE FROM 出荷明細");
+        jdbcTemplate.execute("DELETE FROM 出荷");
+        jdbcTemplate.execute("DELETE FROM 受注明細");
+        jdbcTemplate.execute("DELETE FROM 受注");
+    }
+    @Transactional
+    public void cleanupAll() {
+        cleanupTransactionData();
+        jdbcTemplate.execute("DELETE FROM 商品");
+        jdbcTemplate.execute("DELETE FROM 商品分類");
+        jdbcTemplate.execute("DELETE FROM 取引先");
+    }
+}
+```
+</details>
+<details>
+<summary>統合テストでの使用例</summary>
+```java
+@DisplayName("販売フロー統合テスト")
+class SalesFlowIntegrationTest extends IntegrationTestBase {
+    @Autowired
+    private TestDataManager testDataManager;
+    @BeforeEach
+    void setUp() {
+        testDataManager.cleanupTransactionData();
+        testDataManager.setupMasterData();
+    }
+    @AfterEach
+    void tearDown() {
+        testDataManager.cleanupTransactionData();
+    }
+    @Test
+    @DisplayName("受注から売上までの一連のフローが正常に動作する")
+    void shouldCompleteSalesFlow() {
+        // 1. 受注登録
+        var orderRequest = createOrderRequest();
+        ResponseEntity<OrderResponse> orderResponse = restTemplate.postForEntity(
+            "/api/v1/orders",
+            orderRequest,
+            OrderResponse.class
+        );
+        assertThat(orderResponse.getStatusCode()).isEqualTo(HttpStatus.CREATED);
+        String orderNumber = orderResponse.getBody().orderNumber();
+        // 2. 出荷指示
+        var shipmentRequest = new CreateShipmentInstructionRequest(orderNumber);
+        ResponseEntity<ShipmentInstructionResponse> shipmentResponse = restTemplate.postForEntity(
+            "/api/v1/shipments/instructions",
+            shipmentRequest,
+            ShipmentInstructionResponse.class
+        );
+        assertThat(shipmentResponse.getStatusCode()).isEqualTo(HttpStatus.CREATED);
+        String shipmentNumber = shipmentResponse.getBody().shipmentNumber();
+        // 3. 出荷確定
+        ResponseEntity<ShipmentResponse> confirmResponse = restTemplate.postForEntity(
+            "/api/v1/shipments/" + shipmentNumber + "/confirm",
+            null,
+            ShipmentResponse.class
+        );
+        assertThat(confirmResponse.getStatusCode()).isEqualTo(HttpStatus.OK);
+        // 4. 売上計上の確認
+        ResponseEntity<SalesResponse[]> salesResponse = restTemplate.getForEntity(
+            "/api/v1/sales?orderNumber=" + orderNumber,
+            SalesResponse[].class
+        );
+        assertThat(salesResponse.getStatusCode()).isEqualTo(HttpStatus.OK);
+        assertThat(salesResponse.getBody()).hasSize(1);
+    }
+}
+```
+</details>
+---
+## 本章のまとめ
+本章では、販売管理システムの API サービスを実装しました。
+### 実装したコンポーネント
+| カテゴリ | 内容 |
+|----------|------|
+| アーキテクチャ | ヘキサゴナルアーキテクチャ（Ports & Adapters） |
+| マスタ API | 商品マスタ、顧客マスタ |
+| トランザクション API | 受注、出荷、売上、請求・入金 |
+| エラーハンドリング | グローバル例外ハンドラー、ドメイン例外 |
+| API ドキュメント | OpenAPI / Swagger UI |
+### アーキテクチャの利点
+1. **テスト容易性**: ドメインロジックを独立してテスト可能
+2. **技術変更の容易さ**: アダプターを差し替えるだけで技術を変更可能
+3. **保守性**: 関心事の分離による高い保守性
+4. **チーム開発**: レイヤーごとに並行開発が可能
+### エンドポイント一覧
+| メソッド | パス | 説明 |
+|----------|------|------|
+| GET | `/api/v1/products` | 商品一覧の取得 |
+| GET | `/api/v1/products/{code}` | 商品の取得 |
+| POST | `/api/v1/products` | 商品の登録 |
+| PUT | `/api/v1/products/{code}` | 商品の更新 |
+| DELETE | `/api/v1/products/{code}` | 商品の削除 |
+| GET | `/api/v1/orders` | 受注一覧の取得 |
+| POST | `/api/v1/orders` | 受注の登録 |
+| POST | `/api/v1/shipments/instructions` | 出荷指示の登録 |
+| POST | `/api/v1/shipments/{number}/confirm` | 出荷確定 |
+| POST | `/api/v1/sales` | 売上計上 |
+| POST | `/api/v1/invoices/closing` | 請求締め処理 |
+| POST | `/api/v1/receipts` | 入金登録 |
+| POST | `/api/v1/receipts/{number}/apply` | 入金消込 |