ドメインモデル: 境界づけられたコンテキストと集約
前の章で、注文するときに起きる出来事を並べ、語を用語集にまとめました。この章では、その語から、何をひとまとまりとして扱い、どの決まりをいつも守るかを決めます。決めたものをドメインモデルと呼びます。
ドメインモデルは、後の章のどこにも効きます。リソースと URL を決める章は集約から出発し、第 2 部はクラスとして実装し、第 3 部はテーブルに写します。この章で決めた不変条件不変条件 (Invariant)そのオブジェクトが存在する間、常に成り立っていなければならない条件。派生クラスはこれを弱められない。は、どの段でも守る決まりになります。
決めたものは、サンプルリポジトリの docs/model/domain-model.md に置き、消費税額の計算例を examples/domain/tax-calculation.json に置きました。
エンティティと値オブジェクト
ドメインモデルの部品は、まずエンティティと値オブジェクト値オブジェクト (Value Object)識別子ではなく保持する値そのもので同一性が決まるオブジェクト。生成後は変更せず、不正な値をコンストラクタで弾く使い方をする。に分けます。
- エンティティ: 中身が変わっても、同じものとして追うもの。注文は、状態が変わっても同じ注文です。見分けるために ID を持ちます
- 値オブジェクト: 中身が同じなら区別しないもの。1,080 円と 1,080 円は同じ金額で、どちらの 1,080 円かを問いません。作った後に変えません
注文の題材では、次のように分けました。
## エンティティと値オブジェクト
| 種類 | もの | 理由 |
| --- | --- | --- |
| エンティティ | 注文・在庫・商品 | 中身が変わっても同じものとして追う (注文の状態が変わる、在庫の数量が変わる、商品の価格が変わる) |
| 値オブジェクト | 注文明細・注文 ID・商品 ID・数量・金額・税率・連絡先メールアドレス | 中身が同じなら区別しない。作った後に変えない |
注文明細は、注文の外から注文明細だけを指すことが無く、1 周目では作った後に変えないので、値オブジェクトにする。
注文明細をエンティティにする設計もあります。注文明細を 1 つずつ指して数量を変える操作があるなら、どの注文明細かを見分ける ID が要ります。1 周目にはその操作が無いので、値オブジェクトにしました。注文を変える操作を扱う後の周回で、見直します。
エンティティと値オブジェクトの考え方は、Laravel × DDD ガイドの値オブジェクトの章とエンティティの章で詳しく扱っています。
集約と集約ルート
集約は、一緒に変えて、いつも決まりを守らなければならないもののまとまりです。まとまりの外から触れてよいのは、集約ルートと呼ぶ 1 つのエンティティだけにします。注文明細を扱うときも、注文明細を直接触らず、注文 (集約ルート) を通します。そうすると、決まりを確かめる場所が集約ルートの 1 か所に集まります。
何を 1 つの集約にするかは、いつも守る決まりで決めます。Vaughn Vernon は、境界づけられたコンテキスト (この章の後半で扱います) の中で集約を見つけるには、モデルの本当の不変条件を理解する必要があると書いています。その知識があって初めて、どのオブジェクトを 1 つの集約にまとめるかを決められる、という説明です。不変条件とは、常に整合していなければならない業務の決まりです (Effective Aggregate Design Part I)。
1 周目の集約は 3 つです。
## 集約
| 集約 | 集約ルート | 中に持つもの | 不変条件 (存在する間ずっと成り立つ決まり) |
| --- | --- | --- | --- |
| 注文 | Order | 注文明細 (OrderLine) | 注文明細は 1 つ以上。どの注文明細の数量も 1 以上。合計は、注文明細ごとの単価と数量の積の和。消費税額は、税率ごとの合計から割り戻した額の和 (1 円未満は切り捨て、端数処理は税率ごとに 1 回) |
| 在庫 | Inventory | (なし) | 数量は 0 以上 |
| 商品 | Product | (なし) | 価格は 0 以上の円の整数。税率は 8% か 10% |
不変条件のほかに、作るときと操作の決まりがある。
- 注文は、受付の状態で作る
- 在庫の引き当ては、そのときの数量を超える数量を断る。数量を 0 以上に保つための決まりで、断るのは業務の失敗 (在庫が足りない) として扱う
集約は、その中の不変条件を 1 つのトランザクションで守る範囲 (整合性の境界) になる。
ほかの集約は ID で指す。注文明細は商品を商品 ID で指し、注文した時点の商品の価格と税率を写して持つ。在庫は商品を商品 ID で指す。
不変条件は、集約が存在する間ずっと成り立つ決まりです。「数量は 1 以上」は、前の章までの受け入れ条件にも、入力の確かめとして出てきました。入力の確かめは、送られてきた注文を受け付けるかどうかを決めます。不変条件は、入力がどう届いても、数量 0 の注文明細を持つ注文は 1 件も存在しない、という決まりです。入力の確かめを通り抜けても、集約ルートが最後に守ります。
表の下の 2 つは、存在する間ずっと成り立つ決まりではないので、不変条件と分けました。「受付の状態で作る」は作るときだけの決まりで、後の周回で取り消すと、注文は受付でなくなります。在庫が足りないときに引き当てを断るのは、購入者の注文しだいで普通に起きる業務の失敗です。不変条件が破られた (プログラムの誤り) のとは扱いを分けます。
集約の考え方は、Laravel × DDD ガイドの集約の章で詳しく扱っています。
消費税額の求め方
前の章までで、消費税額を「税率ごとの合計から割り戻して求める」と決めました。ここで、その求め方を国税庁の資料の考え方に合わせて具体的にし、1 円未満の端数の扱いも決めます。
国税庁の Q&A の問 57 (令和 6 年 4 月改訂) は、適格請求書に記載する消費税額等に 1 円未満の端数が出るときは、1 つの適格請求書につき、税率ごとに 1 回の端数処理を行う必要があると答えています。端数処理の方法 (切上げ・切捨て・四捨五入など) は任意に選べます。一方で、適格請求書の個々の商品ごとに消費税額等を求めて端数を処理し、その合計を記載することは認められない、としています (問 57 の PDF)。消費税法施行令の第 70 条の 10 (適格請求書に記載すべき消費税額等の計算) は、各号に掲げる方法のいずれかで求めると定めています。第 1 号は税率ごとに区分した税抜価額の合計に 100 分の 10 (軽減税率の対象は 100 分の 8) を掛ける方法、第 2 号は税込価額の合計に 110 分の 10 (108 分の 8) を掛ける方法です (e-Gov 法令 API が返す条文 (XML))。
これらは適格請求書についての決まりで、注文の API が返す消費税額を直接決めるものではありません。このガイドでは、注文の消費税額にも同じ考え方を使うことにしました。店が注文 1 件ごとに書類を出し、同じ端数処理をするなら、購入者に見せる消費税額と書類の消費税額が食い違いません。いくつかの注文を 1 枚の書類にまとめる場合は、書類の側で税率ごとに計算し直すので、注文ごとの消費税額の和と一致するとは限りません。価格は消費税を含んだ金額なので、税込価額の合計から割り戻す方法 (第 2 号) を使います。
- 税率ごとに、注文明細の単価と数量の積を合計する
- 税率ごとの合計に、税率 / (100 + 税率) を掛ける
- 1 円未満は切り捨てる。端数処理は、税率ごとに 1 回だけ行う
- 税率ごとの消費税額を足したものを、注文の消費税額にする
端数処理の方法は任意なので、このガイドでは切り捨てを選びました。
計算例を値で残す
求め方を文で書くだけでは、読む人によって計算が変わりえます。計算例を値で残し、第 2 部で注文の集約を実装するときのテストの入力にもします。
{
"rounding": "floor",
"examples": [
{
"title": "税率ごとに注文明細が 1 つずつで、端数が出ない",
"lines": [
{ "productId": "01a0f4c2-c400-7a11-8b52-3c9d0e1f2a34", "unitPrice": 1080, "quantity": 2, "taxRate": 8 },
{ "productId": "01a0f4c2-c7e8-7b22-a963-4dae1f203b45", "unitPrice": 1650, "quantity": 1, "taxRate": 10 }
],
"total": 3810,
"taxByRate": [
{ "taxRate": 8, "total": 2160, "taxAmount": 160 },
{ "taxRate": 10, "total": 1650, "taxAmount": 150 }
],
"taxAmount": 310
},
{
"title": "同じ税率の注文明細が 2 つあり、端数が出る",
"lines": [
{ "productId": "01a0f4c2-c9b4-7d44-9c85-6fc0314a5d67", "unitPrice": 1050, "quantity": 1, "taxRate": 8 },
{ "productId": "01a0f4c2-cb20-7e55-ad96-70d1425b6e78", "unitPrice": 1050, "quantity": 1, "taxRate": 8 }
],
"total": 2100,
"taxByRate": [
{ "taxRate": 8, "total": 2100, "taxAmount": 155 }
],
"taxAmount": 155
},
{
"title": "2 つの税率で端数が出て、端数の和が 1 円を超える",
"lines": [
{ "productId": "01a0f4c2-c9b4-7d44-9c85-6fc0314a5d67", "unitPrice": 1050, "quantity": 2, "taxRate": 8 },
{ "productId": "01a0f4c2-cd8c-7f66-bea7-81e2536c7f89", "unitPrice": 999, "quantity": 1, "taxRate": 10 }
],
"total": 3099,
"taxByRate": [
{ "taxRate": 8, "total": 2100, "taxAmount": 155 },
{ "taxRate": 10, "total": 999, "taxAmount": 90 }
],
"taxAmount": 245
}
]
}
lines の要素は、注文明細と同じ productId・unitPrice・quantity・taxRate を持ちます (この章の後半のクラス図の OrderLine と同じ名前です)。商品 ID は例のための仮の値で、1 つ目の例の 2 つは、受け入れ条件のりんごと保存容器です。商品 ID の形は、表現の設計の章で扱います。
3 つの例には、それぞれ役目があります。
- 1 つ目は、受け入れ条件の注文と同じ値です。端数が出ないので、どの求め方でも 310 円になります。求め方の誤りを見分ける例ではなく、受け入れ条件の値を確かめる例です
- 2 つ目は、注文明細ごとに割り戻して足す誤りを見分けます。8% の 2,100 円から 1 回で割り戻すと 155.55… を切り捨てて 155 円です。注文明細ごとに割り戻すと、1,050 円から 77.77… を切り捨てた 77 円が 2 つで、154 円になります。四捨五入する誤りもここで分かれます (156 円)
- 3 つ目は、税率をまたいで足してから 1 回だけ切り捨てる誤りを見分けます。8% の 2,100 円からは 155.55…、10% の 999 円からは 90.81… です。税率ごとに切り捨てて足すと 155 円 + 90 円 = 245 円、端数を残したまま足してから切り捨てると 246.37… から 246 円になります
サンプルリポジトリのテスト (test/tax-calculation.test.ts) は、計算例の注文明細から合計と消費税額を求め直し、計算例に書いた値と比べます。計算は、浮動小数点の誤差が入らないよう、整数の割り算で行います。読んだ直後に計算例の形も確かめ、キーの綴り違い、1 より小さい数量、8 と 10 でない税率のどれでも落ちます。コードは章末の「この章のテストのコード」にあります。
テストの計算を、四捨五入する形、税率をまたいで 1 回だけ切り捨てる形、注文明細ごとに割り戻す形のどれに変えても、どれかの例で落ちます (四捨五入は 2 つ目と 3 つ目、1 回だけ切り捨てる形は 3 つ目、注文明細ごとの形は 2 つ目)。この 3 つと違う書き方の誤りまで捕まえるとは限りません。新しい誤り方に気づいたら、それを見分ける例を足します。
他の集約を ID で指す
注文明細は、どの商品を買うかを持ちます。このとき、商品の集約そのものを中に持たず、商品 ID で指します。Vernon は、他の集約は、オブジェクトへの直接の参照ではなく、グローバルに一意な識別子だけで参照するのが望ましいとしています (Effective Aggregate Design Part II)。ある集約が他の集約を参照しても、参照先は参照元の整合性の境界に入らない、とも書いています。
注文明細は、注文した時点の商品の価格と税率を、単価と税率として写して持ちます。商品の価格は後で変わることがありますが、受け付けた注文の金額は変わってはいけないからです。用語集の単価の定義 (後で商品の価格が変わっても変わらない) は、この写しのことです。
トランザクションと 1 つの集約
トランザクションは、いくつかの変更を、すべて行うか 1 つも行わないかのどちらかにするまとまりです。データベースでどう実現するかは、第 3 部で扱います。ここでは、ドメインモデルの決まりとしての意味だけを使います。
Vernon は、適切に設計された集約は、業務が求めるどんな変更も 1 つのトランザクションの中で不変条件を完全に保ったまま行える、と書いています。そして、適切に設計された境界づけられたコンテキストはどの場合も、1 つのトランザクションで 1 つの集約インスタンスだけを変更する、としています (Part I)。集約を小さく保つことも、規則の 1 つとして挙げています。集約は、その中で不変条件を守る範囲 (整合性の境界) です。1 つのトランザクションで 1 つの集約インスタンスだけを変えれば、トランザクションの範囲と不変条件を守る範囲がそろいます。
このガイドは、これを原則にします。そのうえで、1 周目の例外の節のとおり、1 周目に例外を 1 つ置きます。例外を置くのは Vernon の主張ではなく、このガイドの判断です。
在庫の引き当てを注文の集約に入れない理由
在庫は注文の集約に入れず、別の集約にしました。在庫は、1 つの商品について、多くの注文から引き当てられます。後の周回では、入荷でも増えます。在庫を注文の集約の中に入れると、注文ごとに在庫を持つことになり、「在庫より多くは引き当てない」という決まりを、注文をまたいで守れません。逆に、注文を在庫の集約の中に入れると、1 つの商品の在庫の集約が、その商品を頼んだすべての注文を抱えることになります。
在庫の不変条件 (数量は 0 以上) は、在庫の集約が守ります。そのときの数量を超える引き当てを断るのも、在庫の集約です。
1 周目の例外: 注文と在庫を一緒に変える
注文するときに変わるのは、注文が 1 つと、頼んだ商品ごとの在庫です。受け入れ条件の注文 (りんごと保存容器) なら、注文 1 つと在庫 2 つの、3 つの集約インスタンスが変わります。原則どおりなら、これを別々のトランザクションで変えます。たとえば、注文を受け付けた後に、別のトランザクションで在庫を 1 つずつ引き当てる形です。このように、集約をまたぐ決まりを、少し遅れて満たす形を結果整合と呼びます。
Vernon は、ある集約へのコマンドの実行で、他の集約にも業務の決まりを当てる必要があるなら、結果整合を使うとしています。そのうえで、インスタンスのあいだの更新の遅れを許せるかを、業務の専門家に尋ねるよう勧めています (Part II)。
このガイドの 1 周目の要件は、この遅れを許しません。在庫が足りなければ注文は作られず、受け付けたなら在庫は減っている、という受け入れ条件があるからです。ここからどう作るかは、このガイドの判断です。1 周目は、例外として、注文と在庫を 1 つのトランザクションで変えることにしました。
## トランザクション
1 つのトランザクションでは、1 つの集約インスタンスだけを変えるのを原則にする。
1 周目の注文するでは、例外として、注文 1 つと、頼んだ商品ごとの在庫を、1 つのトランザクションで変える (受け入れ条件の注文なら、注文 1 つと在庫 2 つ)。途中で失敗しても、在庫だけが減って注文が無い状態や、注文があるのに在庫が減っていない状態を作らないため。
ほかの形を選ばない理由:
- 在庫を後から引き当てる形 (結果整合): 受け付けたと答えた注文を、在庫が足りないと後から断ることになり、受け入れ条件と合わない
- 引き当てと注文の記録を別々のトランザクションで続けて行い、後のほうが失敗したら引き当てを戻す形: 答える時点では受け入れ条件を満たせるが、戻す前に処理が止まると在庫だけが減ったまま残り、それを見つけて直す仕組みが別に要る。1 周目は注文と在庫を 1 つのデータベースに置くので、1 つのトランザクションで済ませる
代償として、同じ商品への同時の注文が在庫を取り合う。1 つの注文で複数の商品の在庫を変えるので、注文どうしが互いを待ち続けないよう、在庫を変える順をそろえる必要もある。
前の章のボードでは、「在庫が引き当てられた」と「注文が受け付けられた」を縦に並べ、一緒に起きるのか別々に起きてよいのかを、この章で決めるとしていました。答えは「一緒に起きる」です。前の章で足した受け入れ条件 (一部の商品の在庫が足りないと、注文全体が受け付けられない) も、注文と在庫が一緒に変わることを前提にしています。
この例外の代償 (在庫の取り合いと、在庫を変える順) は、第 3 部で、同時の注文で在庫を守る方法として扱います。
結果整合にすると、購入者に「受け付けた」と「断った」の両方が届くので、要件と受け入れ条件から変える必要があります。結果整合と、それを支えるドメインイベントは、Laravel × DDD ガイドの集約の章の結果整合性の節とドメインイベントの章で扱っています。
境界づけられたコンテキスト
集約の外側に、もう 1 つ大きな区切りがあります。境界づけられたコンテキストは、1 つのモデルと語が通じる範囲です。同じ「商品」でも、商品の情報を扱う場面と、注文の中で買ったものとして扱う場面では、持つ情報と決まりが違います。
1 周目は、注文・在庫・商品の 3 つのコンテキストに分けました。
## 境界づけられたコンテキスト
| コンテキスト | 受け持つこと | 1 周目に使う語 |
| --- | --- | --- |
| 注文 | 注文を受け付け、注文の内容と状態を持つ | 注文・注文 ID・注文明細・数量・単価・合計・消費税額・状態・受付・連絡先メールアドレス |
| 在庫 | 商品ごとの、注文に引き当てられる数量を持つ | 在庫・数量・引き当て |
| 商品 | 注文できる品物と、その価格と税率を持つ | 商品・商品 ID・商品名・価格・税率 |
注文は、商品の価格と税率を読んで注文明細に写し、在庫に引き当てを頼む。矢印は、頼る側から頼られる側へ向ける。
コンテキストどうしの関係を図にしたものを、コンテキストマップと呼びます。1 周目のコンテキストマップは、次のとおりです。
注文は、商品と在庫の 2 つに頼ります。境界は、語と決まりが通じる範囲を分けるもので、コードやデータベースをどう分けるかまでは決めません。1 周目は 1 つの API と 1 つのデータベースで作ります。前の節の例外のトランザクションは、注文と在庫の 2 つのコンテキストにまたがります。1 つのデータベースに置くので、またいで 1 つのトランザクションにできます。2 つのコンテキストを別のサービスとデータベースに分けると、1 つのデータベースのトランザクションでは、この例外を実現できなくなります。コンテキストどうしの関係の種類は、Laravel × DDD ガイドの戦略的設計の章のコンテキストマップの節で扱っています。
クラス図
ここまでの集約を、クラス図にまとめました。名前は用語集の code の名前です (lines は注文明細 OrderLine の並び)。
*-- は、注文が注文明細を中に持ち、注文明細は注文の外に出ないことを表します。..> は、商品 ID で指すだけで、中には持たないことを表します。型は書いていません。数量・金額・税率をどんな型で表すかは、第 2 部のクラス設計で決めます。
用語集には、この章で使う語 (注文 ID・数量・合計・商品 ID・商品名・状態・金額) を足しました。
実務で効く注意点
集約を大きくしない
関係のあるものを全部 1 つの集約に入れると、決まりを確かめる場所は 1 つで済みます。その代わり、1 つの変更のたびに大きなまとまりを読み書きし、同時の変更が衝突しやすくなります。注文の集約に在庫や商品を入れない理由もここにあります。集約に入れるのは、一緒に変えないと不変条件を守れないものだけにします。
計算の決まりを値で決める
消費税額のような計算の決まりは、文だけで書くと、読む人ごとに端数の扱いが変わります。計算例を値で残し、実装の誤りを見分けられる例を選んでおくと、後の章でコードが例と合わないときに、どちらが誤っているかをすぐ確かめられます。
まとめ
- エンティティは中身が変わっても同じものとして追い、値オブジェクトは中身が同じなら区別しません。1 周目の注文明細は値オブジェクトにしました
- 集約は、一緒に変えて不変条件を守るまとまりで、外から触れるのは集約ルートだけです。1 周目の集約は、注文・在庫・商品の 3 つです
- 消費税額は、税率ごとの合計から 1 回だけ割り戻し、1 円未満を切り捨てます。計算例を値で残し、テストで求め直して確かめます
- 他の集約は ID で指し、注文明細は注文した時点の価格と税率を写して持ちます
- 1 つのトランザクションで 1 つの集約インスタンスを変えるのが原則です。1 周目は、途中で失敗しても注文と在庫が食い違わないよう、注文と在庫を 1 つのトランザクションで変える例外にしました
- 境界づけられたコンテキストは、モデルと語が通じる範囲です。1 周目は、注文・在庫・商品に分けました
次に読む
前の章は ドメインを探る です。
次章 REST の考え方 では、ここまでのモデルを API として見せる前に、REST が何を決めた考え方なのかを確かめます。
練習問題
「在庫を注文の集約に入れれば、注文するときに 1 つの集約だけを変えればよくなる」という案があります。何が問題でしょうか
解答例
在庫は、1 つの商品について、多くの注文から引き当てられます。在庫を注文の集約に入れると、注文ごとに在庫を持つことになり、ある注文の中の在庫を減らしても、別の注文の中の在庫には伝わりません。「在庫より多くは引き当てない」という決まりを、注文をまたいで守れなくなります。
集約は、その中で不変条件を守る範囲です。在庫の不変条件は商品ごとの数量の決まりなので、在庫は商品ごとの集約にするのが合います。注文と在庫の集約を 1 つのトランザクションで変えることになりますが、それは集約を誤って大きくする理由にはなりません。原則から外れるなら、この章のように、外れる理由と代償を書いておきます。
1 周目の例外をやめて、在庫を後から引き当てる形 (結果整合) にしたとします。要件と受け入れ条件のどこが変わるでしょうか
解答例
注文するコマンドは、在庫を確かめずに注文を受け付けるようになります。その後、注文が受け付けられたことを受けて、在庫を引き当てるポリシーが動きます。在庫が足りなければ、注文を断る (取り消す) ことになります。
要件では、ユースケースの主な流れから在庫の確かめが外れます。別の流れ 4a は「受け付けた後に在庫が足りないと分かったら、注文を取り消して購入者に知らせる」に変わります。購入者に知らせる手段 (連絡先メールアドレスへの連絡など) も要件に入ります。
受け入れ条件の「在庫より多い数量を頼むと、注文は受け付けられない」は、「在庫より多い数量を頼むと、注文はいったん受け付けられて後で取り消される」のような条件に変わります。Then には、受け付けた時点の状態と、取り消された後の状態の両方を書きます。取り消しは 1 周目に入れていない機能なので、入れないものの表も見直すことになります。
この章のテストのコード
消費税額の計算例が、ドメインモデルの求め方と合っていることを確かめるテストのコードです。読まなくても本文は追えます。
計算例のテスト (test/tax-calculation.test.ts) です。
/*
* examples/domain/tax-calculation.json の計算例が、ドメインモデル (docs/model/domain-model.md) の求め方と合っていることを確かめる。
* 計算例は、注文の集約を実装するときのテストの入力にもなるので、例の値そのものが誤っていないかを先に確かめる。
*/
import { readFileSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
import { expect, it } from 'vitest';
interface Line {
productId: string;
unitPrice: number;
quantity: number;
taxRate: number;
}
interface RateTotal {
taxRate: number;
total: number;
taxAmount: number;
}
interface Example {
title: string;
lines: Line[];
total: number;
taxByRate: RateTotal[];
taxAmount: number;
}
const raw: unknown = JSON.parse(
readFileSync(fileURLToPath(new URL('../examples/domain/tax-calculation.json', import.meta.url)), 'utf8'),
);
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === 'object' && value !== null && !Array.isArray(value);
}
/** 綴りを誤ったキーを見つけるため、keys のキーが欠けているときだけでなく、keys に無いキーがあるときも false にする。 */
function hasExactly(value: unknown, keys: string[]): value is Record<string, unknown> {
return isRecord(value) && Object.keys(value).sort().join() === [...keys].sort().join();
}
function isYen(value: unknown): boolean {
return Number.isInteger(value) && (value as number) >= 0;
}
function isQuantity(value: unknown): boolean {
return Number.isInteger(value) && (value as number) >= 1;
}
function isTaxRate(value: unknown): boolean {
return value === 8 || value === 10;
}
function isLine(value: unknown): boolean {
return (
hasExactly(value, ['productId', 'unitPrice', 'quantity', 'taxRate']) &&
typeof value.productId === 'string' &&
value.productId !== '' &&
isYen(value.unitPrice) &&
isQuantity(value.quantity) &&
isTaxRate(value.taxRate)
);
}
function isRateTotal(value: unknown): boolean {
return (
hasExactly(value, ['taxRate', 'total', 'taxAmount']) &&
isTaxRate(value.taxRate) &&
isYen(value.total) &&
isYen(value.taxAmount)
);
}
/**
* 計算例の形の崩れを、見つけた順に文で返す。キーの綴り違いや値の型の誤りがあると、計算と照らす前に値が読めず、
* 例が黙って抜けるか、誤った理由で落ちるので、先に形を確かめる。
*/
function shapeProblems(value: unknown): string[] {
if (!hasExactly(value, ['rounding', 'examples'])) return ['最上位のキーが rounding と examples の 2 つでない'];
if (value.rounding !== 'floor') return ['rounding が floor でない (このテストは 1 円未満を切り捨てて計算する)'];
if (!Array.isArray(value.examples) || value.examples.length === 0) return ['examples が、1 つ以上の例の配列でない'];
const problems: string[] = [];
value.examples.forEach((example: unknown, index) => {
const where = `examples の ${index + 1} 番目`;
if (!hasExactly(example, ['title', 'lines', 'total', 'taxByRate', 'taxAmount'])) {
problems.push(`${where}: キーが title・lines・total・taxByRate・taxAmount の 5 つでない`);
return;
}
if (typeof example.title !== 'string' || example.title === '') problems.push(`${where}: title が無い`);
if (!Array.isArray(example.lines) || example.lines.length === 0 || !example.lines.every(isLine)) {
problems.push(`${where}: lines が、商品 ID・単価・数量 (1 以上)・税率 (8 か 10) を持つ注文明細の配列でない`);
}
if (!Array.isArray(example.taxByRate) || !example.taxByRate.every(isRateTotal)) {
problems.push(`${where}: taxByRate が、税率・合計・消費税額を持つ配列でない`);
}
if (!isYen(example.total) || !isYen(example.taxAmount)) problems.push(`${where}: total か taxAmount が円の整数でない`);
});
return problems;
}
/** 税率ごとの合計に含まれる消費税額。1 円未満を切り捨て、整数の割り算で求める (浮動小数点の誤差を入れない)。 */
function taxAmountOf(total: number, taxRate: number): number {
const numerator = total * taxRate;
return (numerator - (numerator % (100 + taxRate))) / (100 + taxRate);
}
/** 注文明細から、合計・税率ごとの合計と消費税額・消費税額を求める。税率ごとの合計から 1 回だけ割り戻す。 */
function calculate(lines: Line[]): Omit<Example, 'title' | 'lines'> {
const totals = new Map<number, number>();
for (const line of lines) {
totals.set(line.taxRate, (totals.get(line.taxRate) ?? 0) + line.unitPrice * line.quantity);
}
const taxByRate = [...totals]
.sort(([a], [b]) => a - b)
.map(([taxRate, total]) => ({ taxRate, total, taxAmount: taxAmountOf(total, taxRate) }));
return {
total: taxByRate.reduce((sum, rate) => sum + rate.total, 0),
taxByRate,
taxAmount: taxByRate.reduce((sum, rate) => sum + rate.taxAmount, 0),
};
}
const problems = shapeProblems(raw);
const examples: Example[] = problems.length === 0 ? (raw as { examples: Example[] }).examples : [];
it('計算例の形が崩れていない', () => {
expect(problems).toEqual([]);
});
for (const example of examples) {
it(`計算例「${example.title}」の合計と消費税額が、求め方と合う`, () => {
const { total, taxByRate, taxAmount } = example;
expect({ total, taxByRate, taxAmount }).toEqual(calculate(example.lines));
});
}