@k2works/claude-code-booster 3.2.1 → 3.3.1

package/lib/assets/docs/article/practical-database-design/part3-orm/chapter18-orm.md

@@ -0,0 +1,1183 @@
+# 第18章：勘定科目残高の設計（ORM版）
+
+会計システムにおける残高管理の基盤となる「勘定科目別残高テーブル」を TDD で設計していきます。日次・月次の残高管理と、帳票出力に必要なテーブル構造を実装します。
+
+JPA 版では、@EmbeddedId による複合主キー、@Query による集計クエリ、Projection インターフェースを活用します。
+
+---
+
+## 18.1 日次勘定科目残高の設計
+
+### 日次残高管理の目的
+
+日次勘定科目残高は、日々の仕訳処理に連動して更新される残高情報を管理します。日計表の出力やリアルタイムな残高把握に使用します。
+
+```plantuml
+@startuml
+
+title 日次残高管理の役割
+
+rectangle "仕訳処理" as journal {
+  card "仕訳入力" as j1
+  card "仕訳承認" as j2
+  card "仕訳転記" as j3
+}
+
+rectangle "残高更新" as balance {
+  card "日次残高更新" as b1
+  card "月次残高更新" as b2
+}
+
+rectangle "帳票出力" as report {
+  card "日計表" as r1
+  card "合計残高試算表" as r2
+  card "財務諸表" as r3
+}
+
+j3 --> b1 : 即時更新
+b1 --> b2 : 月末集計
+b1 --> r1 : データ参照
+b2 --> r2 : データ参照
+b2 --> r3 : データ参照
+
+note bottom of b1
+日次勘定科目残高は
+仕訳入力時に即座に更新
+リアルタイムな残高把握を実現
+end note
+
+@enduml
+```
+
+| 目的 | 説明 |
+|-----|------|
+| 日計表出力 | 日単位の勘定科目別借方・貸方合計の集計 |
+| リアルタイム残高 | 仕訳入力と同時に残高を更新 |
+| 監査証跡 | 日付別の取引履歴の保持 |
+| 決算仕訳の区別 | 通常仕訳と決算仕訳の分離管理 |
+
+### 複合主キーによる多次元管理
+
+日次残高テーブルは、以下の6つのカラムで複合主キーを構成します。
+
+| カラム | 説明 | 例 |
+|--------|------|-----|
+| 起票日 | 仕訳の起票日 | 2024-04-01 |
+| 勘定科目コード | 勘定科目マスタのコード | 11110 |
+| 補助科目コード | 補助的な分類（空文字可） | 空文字 |
+| 部門コード | 部門マスタのコード | 10100 |
+| プロジェクトコード | プロジェクト単位管理（空文字可） | P001 |
+| 決算仕訳フラグ | 決算仕訳か否か | false |
+
+この設計により、同じ勘定科目でも以下の粒度で残高を分けて管理できます。
+
+- 部門別の売上高
+- プロジェクト別の原価
+- 通常仕訳と決算仕訳の分離
+
+---
+
+## 18.2 MyBatis 版との実装比較
+
+### データアクセス層の比較
+
+| 機能 | MyBatis 版 | JPA 版 |
+|-----|-----------|--------|
+| 複合主キー | Key 内部クラス | @EmbeddedId + @Embeddable |
+| 検索結果マッピング | resultMap + DTO | Projection インターフェース |
+| UPSERT | XML で INSERT ON CONFLICT | @Query + nativeQuery |
+| 集計クエリ | XML で GROUP BY | Native Query + Projection |
+| 日計表出力 | resultMap でマッピング | Projection → DTO 変換 |
+
+### Flyway マイグレーション
+
+<details>
+<summary>V008__create_daily_account_balance_table.sql</summary>
+
+```sql
+-- 日次勘定科目残高
+CREATE TABLE "日次勘定科目残高" (
+    "起票日" DATE NOT NULL,
+    "勘定科目コード" VARCHAR(5) NOT NULL,
+    "補助科目コード" VARCHAR(10) NOT NULL DEFAULT '',
+    "部門コード" VARCHAR(5) NOT NULL DEFAULT '00000',
+    "プロジェクトコード" VARCHAR(10) NOT NULL DEFAULT '',
+    "決算仕訳フラグ" SMALLINT NOT NULL DEFAULT 0,
+    "借方金額" DECIMAL(14,2) NOT NULL DEFAULT 0,
+    "貸方金額" DECIMAL(14,2) NOT NULL DEFAULT 0,
+    "作成日時" TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL,
+    "更新日時" TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL,
+    PRIMARY KEY (
+        "起票日",
+        "勘定科目コード",
+        "補助科目コード",
+        "部門コード",
+        "プロジェクトコード",
+        "決算仕訳フラグ"
+    ),
+    CONSTRAINT "fk_日次残高_勘定科目"
+        FOREIGN KEY ("勘定科目コード") REFERENCES "勘定科目マスタ"("勘定科目コード"),
+    CONSTRAINT "fk_日次残高_部門"
+        FOREIGN KEY ("部門コード") REFERENCES "部門マスタ"("部門コード")
+);
+
+-- インデックス
+CREATE INDEX "idx_日次残高_起票日" ON "日次勘定科目残高"("起票日");
+CREATE INDEX "idx_日次残高_勘定科目" ON "日次勘定科目残高"("勘定科目コード");
+CREATE INDEX "idx_日次残高_部門" ON "日次勘定科目残高"("部門コード");
+```
+
+</details>
+
+---
+
+## 18.3 JPA エンティティの実装
+
+### 複合主キークラス（@Embeddable）
+
+<details>
+<summary>DailyAccountBalanceId.java</summary>
+
+```java
+package com.example.accounting.domain.model.balance;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Embeddable;
+import lombok.*;
+
+import java.io.Serializable;
+import java.time.LocalDate;
+import java.util.Objects;
+
+/**
+ * 日次勘定科目残高の複合主キー
+ *
+ * JPA では @EmbeddedId で複合主キーを表現
+ * MyBatis 版では Key 内部クラスを使用していたが、
+ * JPA 版では @Embeddable アノテーション付きクラスで実装
+ *
+ * 注意: equals() と hashCode() の実装が必須
+ */
+@Embeddable
+@Data
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+public class DailyAccountBalanceId implements Serializable {
+
+    @Column(name = "起票日", nullable = false)
+    private LocalDate postingDate;
+
+    @Column(name = "勘定科目コード", length = 5, nullable = false)
+    private String accountCode;
+
+    @Column(name = "補助科目コード", length = 10, nullable = false)
+    private String subAccountCode;
+
+    @Column(name = "部門コード", length = 5, nullable = false)
+    private String departmentCode;
+
+    @Column(name = "プロジェクトコード", length = 10, nullable = false)
+    private String projectCode;
+
+    @Column(name = "決算仕訳フラグ", nullable = false)
+    private Boolean closingJournalFlag;
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) return true;
+        if (o == null || getClass() != o.getClass()) return false;
+        DailyAccountBalanceId that = (DailyAccountBalanceId) o;
+        return Objects.equals(postingDate, that.postingDate) &&
+               Objects.equals(accountCode, that.accountCode) &&
+               Objects.equals(subAccountCode, that.subAccountCode) &&
+               Objects.equals(departmentCode, that.departmentCode) &&
+               Objects.equals(projectCode, that.projectCode) &&
+               Objects.equals(closingJournalFlag, that.closingJournalFlag);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(postingDate, accountCode, subAccountCode,
+                           departmentCode, projectCode, closingJournalFlag);
+    }
+}
+```
+
+</details>
+
+### 日次勘定科目残高 Entity
+
+<details>
+<summary>DailyAccountBalance.java</summary>
+
+```java
+package com.example.accounting.domain.model.balance;
+
+import com.example.accounting.domain.model.account.Account;
+import com.example.accounting.domain.model.department.Department;
+import jakarta.persistence.*;
+import lombok.*;
+
+import java.math.BigDecimal;
+import java.time.LocalDateTime;
+
+/**
+ * 日次勘定科目残高 Entity
+ *
+ * JPA 版では @EmbeddedId で複合主キーを定義
+ * MyBatis 版では単純な POJO + Key 内部クラスだったが、
+ * JPA 版では Entity アノテーションと関連定義が必要
+ */
+@Entity
+@Table(name = "日次勘定科目残高")
+@Data
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+public class DailyAccountBalance {
+
+    /**
+     * 複合主キー
+     * @EmbeddedId で埋め込みIDを使用
+     */
+    @EmbeddedId
+    private DailyAccountBalanceId id;
+
+    /**
+     * 勘定科目マスタとの関連
+     */
+    @ManyToOne(fetch = FetchType.LAZY)
+    @JoinColumn(name = "勘定科目コード", referencedColumnName = "勘定科目コード",
+                insertable = false, updatable = false)
+    private Account account;
+
+    /**
+     * 部門マスタとの関連
+     */
+    @ManyToOne(fetch = FetchType.LAZY)
+    @JoinColumn(name = "部門コード", referencedColumnName = "部門コード",
+                insertable = false, updatable = false)
+    private Department department;
+
+    @Column(name = "借方金額", nullable = false, precision = 14, scale = 2)
+    private BigDecimal debitAmount;
+
+    @Column(name = "貸方金額", nullable = false, precision = 14, scale = 2)
+    private BigDecimal creditAmount;
+
+    @Column(name = "作成日時", nullable = false, updatable = false)
+    private LocalDateTime createdAt;
+
+    @Column(name = "更新日時", nullable = false)
+    private LocalDateTime updatedAt;
+
+    /**
+     * 残高を計算する（貸借区分に応じて）
+     * @param isDebitAccount 借方勘定かどうか
+     * @return 残高
+     */
+    public BigDecimal calculateBalance(boolean isDebitAccount) {
+        if (isDebitAccount) {
+            // 借方勘定：借方 - 貸方
+            return debitAmount.subtract(creditAmount);
+        } else {
+            // 貸方勘定：貸方 - 借方
+            return creditAmount.subtract(debitAmount);
+        }
+    }
+
+    /**
+     * 金額を加算する
+     */
+    public void addAmounts(BigDecimal debit, BigDecimal credit) {
+        this.debitAmount = this.debitAmount.add(debit);
+        this.creditAmount = this.creditAmount.add(credit);
+        this.updatedAt = LocalDateTime.now();
+    }
+
+    @PrePersist
+    protected void onCreate() {
+        LocalDateTime now = LocalDateTime.now();
+        this.createdAt = now;
+        this.updatedAt = now;
+        if (this.debitAmount == null) {
+            this.debitAmount = BigDecimal.ZERO;
+        }
+        if (this.creditAmount == null) {
+            this.creditAmount = BigDecimal.ZERO;
+        }
+    }
+
+    @PreUpdate
+    protected void onUpdate() {
+        this.updatedAt = LocalDateTime.now();
+    }
+}
+```
+
+</details>
+
+### 日計表行用 Projection インターフェース
+
+<details>
+<summary>DailyReportLineProjection.java と DailyReportLine.java</summary>
+
+```java
+package com.example.accounting.domain.model.balance;
+
+import java.math.BigDecimal;
+import java.time.LocalDate;
+
+/**
+ * 日計表行の Projection インターフェース
+ *
+ * JPA 版では Projection インターフェースを使用して
+ * 集計クエリの結果をマッピング
+ * MyBatis 版では resultMap で DTO にマッピングしていた
+ */
+public interface DailyReportLineProjection {
+    LocalDate getReportDate();
+    String getAccountCode();
+    String getAccountName();
+    String getSubAccountCode();
+    String getSubAccountName();
+    BigDecimal getDebitTotal();
+    BigDecimal getCreditTotal();
+    BigDecimal getBalance();
+}
+```
+
+```java
+package com.example.accounting.domain.model.balance;
+
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+import java.math.BigDecimal;
+import java.time.LocalDate;
+
+/**
+ * 日計表行 DTO
+ */
+@Data
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+public class DailyReportLine {
+    private LocalDate reportDate;         // 対象日
+    private String accountCode;           // 勘定科目コード
+    private String accountName;           // 勘定科目名
+    private String subAccountCode;        // 補助科目コード
+    private String subAccountName;        // 補助科目名
+    private BigDecimal debitTotal;        // 借方合計
+    private BigDecimal creditTotal;       // 貸方合計
+    private BigDecimal balance;           // 残高
+
+    /**
+     * Projection から DTO を生成
+     */
+    public static DailyReportLine fromProjection(DailyReportLineProjection projection) {
+        return DailyReportLine.builder()
+            .reportDate(projection.getReportDate())
+            .accountCode(projection.getAccountCode())
+            .accountName(projection.getAccountName())
+            .subAccountCode(projection.getSubAccountCode())
+            .subAccountName(projection.getSubAccountName())
+            .debitTotal(projection.getDebitTotal())
+            .creditTotal(projection.getCreditTotal())
+            .balance(projection.getBalance())
+            .build();
+    }
+}
+```
+
+</details>
+
+---
+
+## 18.4 TDD による日次残高テーブルの実装
+
+### リポジトリのテスト
+
+<details>
+<summary>DailyAccountBalanceRepositoryTest.java</summary>
+
+```java
+package com.example.accounting.infrastructure.persistence;
+
+import com.example.accounting.domain.model.balance.DailyAccountBalance;
+import com.example.accounting.domain.model.balance.DailyAccountBalanceId;
+import com.example.accounting.infrastructure.persistence.repository.DailyAccountBalanceJpaRepository;
+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.test.autoconfigure.jdbc.AutoConfigureTestDatabase;
+import org.springframework.boot.test.autoconfigure.orm.jpa.DataJpaTest;
+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;
+
+import java.math.BigDecimal;
+import java.time.LocalDate;
+
+import static org.assertj.core.api.Assertions.*;
+
+/**
+ * 日次勘定科目残高リポジトリのテスト
+ *
+ * JPA 版では @DataJpaTest を使用（MyBatis 版では @MybatisTest）
+ */
+@DataJpaTest
+@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
+@Testcontainers
+@DisplayName("日次勘定科目残高リポジトリのテスト")
+class DailyAccountBalanceRepositoryTest {
+
+    @Container
+    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16")
+            .withDatabaseName("testdb")
+            .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
+    private DailyAccountBalanceJpaRepository dailyBalanceRepository;
+
+    @Nested
+    @DisplayName("日次残高の登録・更新")
+    class DailyBalanceUpsertTest {
+
+        @Test
+        @DisplayName("新規の日次残高を登録できる")
+        void shouldInsertNewDailyBalance() {
+            // Given
+            var id = DailyAccountBalanceId.builder()
+                .postingDate(LocalDate.of(2024, 4, 1))
+                .accountCode("11110")  // 現金
+                .subAccountCode("")
+                .departmentCode("10100")
+                .projectCode("")
+                .closingJournalFlag(false)
+                .build();
+
+            var balance = DailyAccountBalance.builder()
+                .id(id)
+                .debitAmount(new BigDecimal("100000"))
+                .creditAmount(BigDecimal.ZERO)
+                .build();
+
+            // When
+            dailyBalanceRepository.save(balance);
+
+            // Then
+            var saved = dailyBalanceRepository.findById(id);
+            assertThat(saved).isPresent();
+            assertThat(saved.get().getDebitAmount())
+                .isEqualByComparingTo("100000");
+        }
+
+        @Test
+        @DisplayName("既存の日次残高を更新できる")
+        void shouldUpdateExistingDailyBalance() {
+            // Given: 初回登録
+            var id = DailyAccountBalanceId.builder()
+                .postingDate(LocalDate.of(2024, 4, 1))
+                .accountCode("11110")
+                .subAccountCode("")
+                .departmentCode("10100")
+                .projectCode("")
+                .closingJournalFlag(false)
+                .build();
+
+            var balance1 = DailyAccountBalance.builder()
+                .id(id)
+                .debitAmount(new BigDecimal("100000"))
+                .creditAmount(BigDecimal.ZERO)
+                .build();
+            dailyBalanceRepository.save(balance1);
+
+            // When: 金額を追加
+            var saved = dailyBalanceRepository.findById(id).orElseThrow();
+            saved.addAmounts(new BigDecimal("50000"), BigDecimal.ZERO);
+            dailyBalanceRepository.save(saved);
+
+            // Then: 合算される
+            var updated = dailyBalanceRepository.findById(id);
+            assertThat(updated).isPresent();
+            assertThat(updated.get().getDebitAmount())
+                .isEqualByComparingTo("150000");
+        }
+    }
+
+    @Nested
+    @DisplayName("日次残高の検索")
+    class DailyBalanceSearchTest {
+
+        @Test
+        @DisplayName("日付範囲で日次残高を検索できる")
+        void shouldFindBalancesByDateRange() {
+            // When
+            var balances = dailyBalanceRepository.findByIdPostingDateBetween(
+                LocalDate.of(2024, 4, 1),
+                LocalDate.of(2024, 4, 30)
+            );
+
+            // Then
+            assertThat(balances).allMatch(b ->
+                !b.getId().getPostingDate().isBefore(LocalDate.of(2024, 4, 1)) &&
+                !b.getId().getPostingDate().isAfter(LocalDate.of(2024, 4, 30))
+            );
+        }
+
+        @Test
+        @DisplayName("勘定科目コードで日次残高を検索できる")
+        void shouldFindBalancesByAccountCode() {
+            // When
+            var balances = dailyBalanceRepository.findByIdAccountCode("11110");
+
+            // Then
+            assertThat(balances).allMatch(b ->
+                b.getId().getAccountCode().equals("11110")
+            );
+        }
+    }
+}
+```
+
+</details>
+
+---
+
+## 18.5 JpaRepository インターフェース
+
+### 日次勘定科目残高 Repository
+
+<details>
+<summary>DailyAccountBalanceJpaRepository.java</summary>
+
+```java
+package com.example.accounting.infrastructure.persistence.repository;
+
+import com.example.accounting.domain.model.balance.DailyAccountBalance;
+import com.example.accounting.domain.model.balance.DailyAccountBalanceId;
+import com.example.accounting.domain.model.balance.DailyReportLineProjection;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.Modifying;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.data.repository.query.Param;
+import org.springframework.stereotype.Repository;
+
+import java.math.BigDecimal;
+import java.time.LocalDate;
+import java.util.List;
+
+/**
+ * 日次勘定科目残高 JpaRepository
+ *
+ * JPA 版では JpaRepository を継承
+ * 複合主キーは DailyAccountBalanceId として定義
+ * 集計クエリは @Query + Projection で実装
+ */
+@Repository
+public interface DailyAccountBalanceJpaRepository
+        extends JpaRepository<DailyAccountBalance, DailyAccountBalanceId> {
+
+    /**
+     * 日付範囲で検索
+     * メソッド名規約で自動生成
+     */
+    List<DailyAccountBalance> findByIdPostingDateBetween(
+            LocalDate fromDate, LocalDate toDate);
+
+    /**
+     * 起票日で検索
+     */
+    List<DailyAccountBalance> findByIdPostingDate(LocalDate postingDate);
+
+    /**
+     * 勘定科目コードで検索
+     */
+    List<DailyAccountBalance> findByIdAccountCode(String accountCode);
+
+    /**
+     * 部門コードで検索
+     */
+    List<DailyAccountBalance> findByIdDepartmentCode(String departmentCode);
+
+    /**
+     * 日計表データ取得
+     * Native Query で集計クエリを実行し、Projection にマッピング
+     */
+    @Query(value = """
+        SELECT
+            d."起票日" as reportDate,
+            d."勘定科目コード" as accountCode,
+            a."勘定科目名" as accountName,
+            d."補助科目コード" as subAccountCode,
+            '' as subAccountName,
+            SUM(d."借方金額") as debitTotal,
+            SUM(d."貸方金額") as creditTotal,
+            CASE
+                WHEN a."貸借区分" = '借方'
+                THEN SUM(d."借方金額") - SUM(d."貸方金額")
+                ELSE SUM(d."貸方金額") - SUM(d."借方金額")
+            END as balance
+        FROM "日次勘定科目残高" d
+        JOIN "勘定科目マスタ" a ON d."勘定科目コード" = a."勘定科目コード"
+        WHERE d."起票日" = :reportDate
+        GROUP BY d."起票日", d."勘定科目コード", a."勘定科目名",
+                 d."補助科目コード", a."貸借区分"
+        ORDER BY d."勘定科目コード", d."補助科目コード"
+        """, nativeQuery = true)
+    List<DailyReportLineProjection> getDailyReport(@Param("reportDate") LocalDate reportDate);
+
+    /**
+     * UPSERT 用のカスタムクエリ
+     * PostgreSQL の ON CONFLICT を使用
+     */
+    @Modifying
+    @Query(value = """
+        INSERT INTO "日次勘定科目残高" (
+            "起票日", "勘定科目コード", "補助科目コード",
+            "部門コード", "プロジェクトコード", "決算仕訳フラグ",
+            "借方金額", "貸方金額", "作成日時", "更新日時"
+        ) VALUES (
+            :postingDate, :accountCode, :subAccountCode,
+            :departmentCode, :projectCode, :closingJournalFlag,
+            :debitAmount, :creditAmount, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP
+        )
+        ON CONFLICT (
+            "起票日", "勘定科目コード", "補助科目コード",
+            "部門コード", "プロジェクトコード", "決算仕訳フラグ"
+        )
+        DO UPDATE SET
+            "借方金額" = "日次勘定科目残高"."借方金額" + EXCLUDED."借方金額",
+            "貸方金額" = "日次勘定科目残高"."貸方金額" + EXCLUDED."貸方金額",
+            "更新日時" = CURRENT_TIMESTAMP
+        """, nativeQuery = true)
+    void upsert(
+            @Param("postingDate") LocalDate postingDate,
+            @Param("accountCode") String accountCode,
+            @Param("subAccountCode") String subAccountCode,
+            @Param("departmentCode") String departmentCode,
+            @Param("projectCode") String projectCode,
+            @Param("closingJournalFlag") Boolean closingJournalFlag,
+            @Param("debitAmount") BigDecimal debitAmount,
+            @Param("creditAmount") BigDecimal creditAmount);
+}
+```
+
+</details>
+
+---
+
+## 18.6 月次勘定科目残高の設計
+
+### 月次残高管理の目的
+
+月次勘定科目残高は、月単位での残高管理を行い、合計残高試算表や財務諸表の出力に使用します。
+
+```plantuml
+@startuml
+
+title 月次残高管理の役割
+
+rectangle "日次処理" as daily {
+  card "日次残高更新" as d1
+  card "日計表" as d2
+}
+
+rectangle "月次処理" as monthly {
+  card "月末残高確定" as m1
+  card "月次残高更新" as m2
+  card "繰越処理" as m3
+}
+
+rectangle "帳票・決算" as closing {
+  card "合計残高試算表" as c1
+  card "損益計算書" as c2
+  card "貸借対照表" as c3
+  card "決算仕訳" as c4
+}
+
+d1 --> m2 : 月末集計
+m2 --> m1
+m1 --> m3 : 翌月初
+m2 --> c1
+m2 --> c2
+m2 --> c3
+c4 --> m2
+
+note bottom of m2
+月次勘定科目残高は
+・月初残高
+・当月借方・貸方
+・月末残高
+を管理
+end note
+
+@enduml
+```
+
+| 目的 | 説明 |
+|-----|------|
+| 合計残高試算表 | 月次の勘定科目別借方・貸方・残高の集計 |
+| 財務諸表出力 | 貸借対照表・損益計算書のデータソース |
+| 月次決算 | 月末残高の確定と繰越処理 |
+| 決算仕訳対応 | 通常仕訳と決算仕訳の分離管理 |
+
+### 月次勘定科目残高テーブルの ER 図
+
+```plantuml
+@startuml
+
+entity "月次勘定科目残高" as MonthlyBalance {
+  * **決算期**: INTEGER <<PK>>
+  * **月度**: SMALLINT <<PK>>
+  * **勘定科目コード**: VARCHAR(5) <<PK>> <<FK>>
+  * **補助科目コード**: VARCHAR(10) <<PK>>
+  * **部門コード**: VARCHAR(5) <<PK>> <<FK>>
+  * **プロジェクトコード**: VARCHAR(10) <<PK>>
+  * **決算仕訳フラグ**: SMALLINT <<PK>>
+  --
+  * **月初残高**: DECIMAL(13,0)
+  * **借方金額**: DECIMAL(14,2)
+  * **貸方金額**: DECIMAL(14,2)
+  * **月末残高**: DECIMAL(13,0)
+}
+
+entity "日次勘定科目残高" as DailyBalance {
+  * **起票日** <<PK>>
+  * **勘定科目コード** <<PK>>
+  ...
+  --
+  借方金額
+  貸方金額
+}
+
+DailyBalance ..> MonthlyBalance : 月末集計
+
+note right of MonthlyBalance
+決算期・月度による期間管理
+月初残高は前月末残高から繰越
+月末残高 = 月初残高 + 借方金額 - 貸方金額
+(借方勘定の場合)
+end note
+
+@enduml
+```
+
+---
+
+## 18.7 月次残高の JPA エンティティ
+
+### 複合主キークラス
+
+<details>
+<summary>MonthlyAccountBalanceId.java</summary>
+
+```java
+package com.example.accounting.domain.model.balance;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Embeddable;
+import lombok.*;
+
+import java.io.Serializable;
+import java.util.Objects;
+
+/**
+ * 月次勘定科目残高の複合主キー
+ */
+@Embeddable
+@Data
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+public class MonthlyAccountBalanceId implements Serializable {
+
+    @Column(name = "決算期", nullable = false)
+    private Integer fiscalYear;
+
+    @Column(name = "月度", nullable = false)
+    private Integer month;
+
+    @Column(name = "勘定科目コード", length = 5, nullable = false)
+    private String accountCode;
+
+    @Column(name = "補助科目コード", length = 10, nullable = false)
+    private String subAccountCode;
+
+    @Column(name = "部門コード", length = 5, nullable = false)
+    private String departmentCode;
+
+    @Column(name = "プロジェクトコード", length = 10, nullable = false)
+    private String projectCode;
+
+    @Column(name = "決算仕訳フラグ", nullable = false)
+    private Boolean closingJournalFlag;
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) return true;
+        if (o == null || getClass() != o.getClass()) return false;
+        MonthlyAccountBalanceId that = (MonthlyAccountBalanceId) o;
+        return Objects.equals(fiscalYear, that.fiscalYear) &&
+               Objects.equals(month, that.month) &&
+               Objects.equals(accountCode, that.accountCode) &&
+               Objects.equals(subAccountCode, that.subAccountCode) &&
+               Objects.equals(departmentCode, that.departmentCode) &&
+               Objects.equals(projectCode, that.projectCode) &&
+               Objects.equals(closingJournalFlag, that.closingJournalFlag);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(fiscalYear, month, accountCode, subAccountCode,
+                           departmentCode, projectCode, closingJournalFlag);
+    }
+}
+```
+
+</details>
+
+### 月次勘定科目残高 Entity
+
+<details>
+<summary>MonthlyAccountBalance.java</summary>
+
+```java
+package com.example.accounting.domain.model.balance;
+
+import com.example.accounting.domain.model.account.Account;
+import com.example.accounting.domain.model.department.Department;
+import jakarta.persistence.*;
+import lombok.*;
+
+import java.math.BigDecimal;
+import java.time.LocalDateTime;
+
+/**
+ * 月次勘定科目残高 Entity
+ */
+@Entity
+@Table(name = "月次勘定科目残高")
+@Data
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+public class MonthlyAccountBalance {
+
+    @EmbeddedId
+    private MonthlyAccountBalanceId id;
+
+    @ManyToOne(fetch = FetchType.LAZY)
+    @JoinColumn(name = "勘定科目コード", referencedColumnName = "勘定科目コード",
+                insertable = false, updatable = false)
+    private Account account;
+
+    @ManyToOne(fetch = FetchType.LAZY)
+    @JoinColumn(name = "部門コード", referencedColumnName = "部門コード",
+                insertable = false, updatable = false)
+    private Department department;
+
+    @Column(name = "月初残高", nullable = false, precision = 13)
+    private BigDecimal openingBalance;
+
+    @Column(name = "借方金額", nullable = false, precision = 14, scale = 2)
+    private BigDecimal debitAmount;
+
+    @Column(name = "貸方金額", nullable = false, precision = 14, scale = 2)
+    private BigDecimal creditAmount;
+
+    @Column(name = "月末残高", nullable = false, precision = 13)
+    private BigDecimal closingBalance;
+
+    @Column(name = "作成日時", nullable = false, updatable = false)
+    private LocalDateTime createdAt;
+
+    @Column(name = "更新日時", nullable = false)
+    private LocalDateTime updatedAt;
+
+    /**
+     * 月末残高を計算する
+     * @param isDebitAccount 借方勘定かどうか
+     */
+    public void calculateClosingBalance(boolean isDebitAccount) {
+        if (isDebitAccount) {
+            // 借方勘定：月初 + 借方 - 貸方
+            this.closingBalance = openingBalance
+                .add(debitAmount)
+                .subtract(creditAmount);
+        } else {
+            // 貸方勘定：月初 + 貸方 - 借方
+            this.closingBalance = openingBalance
+                .add(creditAmount)
+                .subtract(debitAmount);
+        }
+    }
+
+    @PrePersist
+    protected void onCreate() {
+        LocalDateTime now = LocalDateTime.now();
+        this.createdAt = now;
+        this.updatedAt = now;
+        initializeDefaults();
+    }
+
+    @PreUpdate
+    protected void onUpdate() {
+        this.updatedAt = LocalDateTime.now();
+    }
+
+    private void initializeDefaults() {
+        if (this.openingBalance == null) this.openingBalance = BigDecimal.ZERO;
+        if (this.debitAmount == null) this.debitAmount = BigDecimal.ZERO;
+        if (this.creditAmount == null) this.creditAmount = BigDecimal.ZERO;
+        if (this.closingBalance == null) this.closingBalance = BigDecimal.ZERO;
+    }
+}
+```
+
+</details>
+
+### 合計残高試算表行用 Projection
+
+<details>
+<summary>TrialBalanceLineProjection.java と TrialBalanceLine.java</summary>
+
+```java
+package com.example.accounting.domain.model.balance;
+
+import java.math.BigDecimal;
+
+/**
+ * 合計残高試算表行の Projection インターフェース
+ */
+public interface TrialBalanceLineProjection {
+    Integer getFiscalYear();
+    Integer getMonth();
+    String getAccountCode();
+    String getAccountName();
+    String getBsplType();
+    String getDebitCreditType();
+    BigDecimal getOpeningBalance();
+    BigDecimal getDebitTotal();
+    BigDecimal getCreditTotal();
+    BigDecimal getClosingBalance();
+}
+```
+
+```java
+package com.example.accounting.domain.model.balance;
+
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+import java.math.BigDecimal;
+
+/**
+ * 合計残高試算表行 DTO
+ */
+@Data
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+public class TrialBalanceLine {
+    private Integer fiscalYear;           // 決算期
+    private Integer month;                // 月度
+    private String accountCode;           // 勘定科目コード
+    private String accountName;           // 勘定科目名
+    private String bsplType;              // BSPL区分
+    private String debitCreditType;       // 貸借区分
+    private BigDecimal openingBalance;    // 月初残高
+    private BigDecimal debitTotal;        // 借方合計
+    private BigDecimal creditTotal;       // 貸方合計
+    private BigDecimal closingBalance;    // 月末残高
+
+    /**
+     * Projection から DTO を生成
+     */
+    public static TrialBalanceLine fromProjection(TrialBalanceLineProjection projection) {
+        return TrialBalanceLine.builder()
+            .fiscalYear(projection.getFiscalYear())
+            .month(projection.getMonth())
+            .accountCode(projection.getAccountCode())
+            .accountName(projection.getAccountName())
+            .bsplType(projection.getBsplType())
+            .debitCreditType(projection.getDebitCreditType())
+            .openingBalance(projection.getOpeningBalance())
+            .debitTotal(projection.getDebitTotal())
+            .creditTotal(projection.getCreditTotal())
+            .closingBalance(projection.getClosingBalance())
+            .build();
+    }
+}
+```
+
+</details>
+
+---
+
+## 18.8 残高更新サービスの実装
+
+<details>
+<summary>BalanceUpdateService.java</summary>
+
+```java
+package com.example.accounting.application.service;
+
+import com.example.accounting.application.port.out.DailyAccountBalanceRepository;
+import com.example.accounting.application.port.out.MonthlyAccountBalanceRepository;
+import com.example.accounting.domain.model.journal.DebitCreditType;
+import com.example.accounting.domain.model.journal.Journal;
+import com.example.accounting.domain.model.journal.JournalDebitCreditDetail;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.math.BigDecimal;
+import java.time.LocalDate;
+
+/**
+ * 残高更新サービス
+ *
+ * 仕訳登録時の残高更新を担当
+ * JPA 版でもビジネスロジックは MyBatis 版と同じ
+ */
+@Service
+@RequiredArgsConstructor
+@Slf4j
+public class BalanceUpdateService {
+
+    private final DailyAccountBalanceRepository dailyBalanceRepository;
+    private final MonthlyAccountBalanceRepository monthlyBalanceRepository;
+
+    /**
+     * 仕訳登録に伴う残高更新
+     */
+    @Transactional
+    public void updateBalancesForJournal(Journal journal) {
+        var postingDate = journal.getPostingDate();
+        var closingFlag = journal.getClosingEntryFlag() != null
+            ? journal.getClosingEntryFlag() : false;
+
+        // 仕訳の各明細について残高を更新
+        for (var detail : journal.getDetails()) {
+            for (var dcDetail : detail.getDebitCreditDetails()) {
+                updateDailyBalance(postingDate, dcDetail, closingFlag);
+            }
+        }
+
+        log.info("残高更新完了: 仕訳伝票番号={}, 起票日={}",
+            journal.getJournalVoucherNumber(), postingDate);
+    }
+
+    /**
+     * 日次残高の更新
+     * JPA 版では upsert メソッドで Native Query を使用
+     */
+    private void updateDailyBalance(LocalDate postingDate,
+            JournalDebitCreditDetail dcDetail, boolean closingFlag) {
+        var debitAmount = dcDetail.getDebitCreditType() == DebitCreditType.DEBIT
+            ? dcDetail.getAmount() : BigDecimal.ZERO;
+        var creditAmount = dcDetail.getDebitCreditType() == DebitCreditType.CREDIT
+            ? dcDetail.getAmount() : BigDecimal.ZERO;
+
+        dailyBalanceRepository.upsert(
+            postingDate,
+            dcDetail.getAccountCode(),
+            dcDetail.getSubAccountCode() != null ? dcDetail.getSubAccountCode() : "",
+            dcDetail.getDepartmentCode() != null ? dcDetail.getDepartmentCode() : "00000",
+            dcDetail.getProjectCode() != null ? dcDetail.getProjectCode() : "",
+            closingFlag,
+            debitAmount,
+            creditAmount
+        );
+    }
+
+    /**
+     * 月次残高の集計
+     */
+    @Transactional
+    public int aggregateMonthlyBalance(int fiscalYear, int month) {
+        LocalDate fromDate = LocalDate.of(fiscalYear, month, 1);
+        LocalDate toDate = fromDate.withDayOfMonth(fromDate.lengthOfMonth());
+
+        int count = monthlyBalanceRepository.aggregateFromDaily(
+            fiscalYear, month, fromDate, toDate);
+
+        log.info("月次残高集計完了: 決算期={}, 月度={}, 件数={}",
+            fiscalYear, month, count);
+
+        return count;
+    }
+
+    /**
+     * 月次残高の繰越処理
+     */
+    @Transactional
+    public int carryForwardMonthlyBalance(int fiscalYear, int fromMonth, int toMonth) {
+        int count = monthlyBalanceRepository.carryForward(fiscalYear, fromMonth, toMonth);
+
+        log.info("月次残高繰越完了: 決算期={}, {}月 → {}月, 件数={}",
+            fiscalYear, fromMonth, toMonth, count);
+
+        return count;
+    }
+}
+```
+
+</details>
+
+---
+
+## 18.9 まとめ：設計のポイント
+
+### 複合主キーによる多次元管理
+
+1. **日次残高**：起票日 + 勘定科目 + 補助科目 + 部門 + プロジェクト + 決算仕訳フラグ
+2. **月次残高**：決算期 + 月度 + 勘定科目 + 補助科目 + 部門 + プロジェクト + 決算仕訳フラグ
+3. JPA では @EmbeddedId + @Embeddable で複合主キーを表現
+
+### UPSERT による効率的な残高更新
+
+- PostgreSQL の `INSERT ON CONFLICT DO UPDATE` を使用
+- JPA では @Query + nativeQuery で Native SQL を実行
+- 既存レコードがあれば金額を加算、なければ新規挿入
+
+### Projection による集計結果のマッピング
+
+- Native Query の結果を Projection インターフェースで受け取り
+- Projection から DTO への変換メソッドを用意
+- 型安全な集計結果の取り扱いが可能
+
+### MyBatis 版との比較
+
+| 観点 | MyBatis 版 | JPA 版 |
+|------|-----------|--------|
+| 複合主キー | Key 内部クラス | @EmbeddedId + @Embeddable |
+| 集計結果マッピング | resultMap + DTO | Projection インターフェース |
+| UPSERT | XML で INSERT ON CONFLICT | @Query + nativeQuery |
+| テスト | @MybatisTest | @DataJpaTest |
+
+---
+
+## 次章予告
+
+[第19章](chapter19-orm.md)では、赤黒処理によるデータ訂正方式と、JPA Auditing を使用したログ管理の設計について解説します。