@k2works/claude-code-booster 3.0.0 → 3.1.0

package/lib/assets/docs/article/functional-desgin-ppp/clojure/15-gossiping-bus-drivers.md

@@ -0,0 +1,323 @@
+# 第15章: ゴシップ好きなバスの運転手
+
+## はじめに
+
+本章では、「ゴシップ好きなバスの運転手」という問題を通じて、関数型プログラミングの実践的なアプローチを学びます。この問題は、バス運転手が停留所で出会ったときに噂を共有するというシミュレーションです。
+
+この問題を通じて以下の概念を学びます：
+
+- 無限シーケンス（`cycle`）による循環データの表現
+- 集合演算による状態の伝播
+- データ変換パイプラインの設計
+
+## 1. 問題の説明
+
+複数のバス運転手がそれぞれのルートを巡回しています。各運転手は最初に1つ以上の噂を知っています。同じ停留所に複数の運転手がいると、彼らは知っている噂をすべて共有します。
+
+**ゴール**: 全ての運転手が全ての噂を知るまでに何分かかるか？
+
+```plantuml
+@startuml
+title ゴシップ好きなバスの運転手
+
+actor "Driver 1" as d1
+actor "Driver 2" as d2
+actor "Driver 3" as d3
+
+rectangle "Stop 1" as s1
+rectangle "Stop 2" as s2
+rectangle "Stop 3" as s3
+
+d1 --> s1 : 噂A
+d2 --> s1 : 噂B
+d3 --> s2 : 噂C
+
+note bottom of s1
+  同じ停留所にいる運転手は
+  噂を共有する
+  D1, D2 => {噂A, 噂B}
+end note
+@enduml
+```
+
+## 2. データモデル
+
+### ドライバーの表現
+
+```clojure
+(defn make-driver
+  "ドライバーを作成する
+   name - ドライバーの名前
+   route - 停留所のシーケンス
+   rumors - 知っている噂の集合"
+  [name route rumors]
+  {:name name
+   :route (cycle route)  ; 無限シーケンスで循環ルート
+   :rumors rumors})
+```
+
+ポイント:
+- `cycle` 関数で有限のルートを無限の循環シーケンスに変換
+- 噂は集合（set）として管理
+
+### 無限シーケンスの活用
+
+```clojure
+;; ルート [1 2 3] は無限に繰り返される
+(take 10 (cycle [1 2 3]))
+;; => (1 2 3 1 2 3 1 2 3 1)
+```
+
+```plantuml
+@startuml
+title 無限シーケンスによるルート表現
+
+rectangle "有限ルート" {
+  card "1" as r1
+  card "2" as r2
+  card "3" as r3
+  r1 --> r2
+  r2 --> r3
+}
+
+rectangle "cycle による無限化" {
+  card "1" as c1
+  card "2" as c2
+  card "3" as c3
+  card "1" as c4
+  card "..." as dots
+  c1 --> c2
+  c2 --> c3
+  c3 --> c4
+  c4 --> dots
+}
+
+note bottom
+  cycle 関数により
+  有限シーケンスを
+  無限に繰り返す
+end note
+@enduml
+```
+
+## 3. 移動と噂の伝播
+
+### ドライバーの移動
+
+```clojure
+(defn current-stop
+  "ドライバーの現在の停留所を取得"
+  [driver]
+  (first (:route driver)))
+
+(defn move-driver
+  "ドライバーを次の停留所に移動"
+  [driver]
+  (update driver :route rest))
+
+(defn move-drivers
+  "全ドライバーを次の停留所に移動"
+  [world]
+  (map move-driver world))
+```
+
+### 停留所ごとのドライバー集計
+
+```clojure
+(defn get-stops
+  "各停留所にいるドライバーをマップとして取得
+   {停留所番号 => [ドライバー1, ドライバー2, ...]}"
+  [world]
+  (loop [world world
+         stops {}]
+    (if (empty? world)
+      stops
+      (let [driver (first world)
+            stop (current-stop driver)
+            stops (update stops stop conj driver)]
+        (recur (rest world) stops)))))
+```
+
+### 噂の共有
+
+```clojure
+(defn merge-rumors
+  "同じ停留所にいるドライバー間で噂を共有
+   全員の噂を統合し、各ドライバーに設定"
+  [drivers]
+  (let [rumors (map :rumors drivers)
+        all-rumors (apply set/union rumors)]
+    (map #(assoc % :rumors all-rumors) drivers)))
+
+(defn spread-rumors
+  "全停留所で噂を伝播"
+  [world]
+  (let [stops-with-drivers (get-stops world)
+        drivers-by-stop (vals stops-with-drivers)]
+    (flatten (map merge-rumors drivers-by-stop))))
+```
+
+```plantuml
+@startuml
+title 噂の伝播プロセス
+
+participant "Driver 1" as d1
+participant "Stop" as stop
+participant "Driver 2" as d2
+
+d1 -> stop : 噂 {A, B}
+d2 -> stop : 噂 {C}
+
+stop -> stop : set/union
+note right: {A, B} ∪ {C} = {A, B, C}
+
+stop -> d1 : 噂 {A, B, C}
+stop -> d2 : 噂 {A, B, C}
+@enduml
+```
+
+## 4. シミュレーション
+
+### 1ステップの処理
+
+```clojure
+(defn drive
+  "1ステップ分のシミュレーション
+   1. 全ドライバーを移動
+   2. 同じ停留所にいるドライバー間で噂を共有"
+  [world]
+  (-> world
+      move-drivers
+      spread-rumors))
+```
+
+### 完了判定
+
+```clojure
+(defn all-rumors-shared?
+  "全ドライバーが同じ噂を持っているか確認"
+  [world]
+  (apply = (map :rumors world)))
+
+(defn drive-till-all-rumors-spread
+  "全ての噂が共有されるまでシミュレーション
+   480分（8時間）以内に共有されなければ :never を返す"
+  [world]
+  (loop [world (drive world)
+         time 1]
+    (cond
+      (> time 480) :never
+      (all-rumors-shared? world) time
+      :else (recur (drive world) (inc time)))))
+```
+
+## 5. シーケンス図
+
+```plantuml
+@startuml
+title シミュレーションのフロー
+
+participant "Main" as main
+participant "World" as world
+participant "Drivers" as drivers
+participant "Stops" as stops
+
+main -> world : drive-till-all-rumors-spread
+activate world
+
+loop 全噂が共有されるまで（最大480回）
+  world -> drivers : move-drivers
+  activate drivers
+  drivers --> world : 移動後のドライバー
+  deactivate drivers
+
+  world -> stops : get-stops
+  activate stops
+  stops --> world : 停留所ごとのドライバー
+  deactivate stops
+
+  world -> world : spread-rumors
+  note right: 各停留所で噂を共有
+
+  world -> world : all-rumors-shared?
+  alt 全噂が共有された
+    world --> main : 経過時間
+  else 480分経過
+    world --> main : :never
+  end
+end
+
+deactivate world
+@enduml
+```
+
+## 6. 使用例
+
+```clojure
+(require '[gossiping-bus-drivers.core :as gbd])
+
+;; 3人のドライバーを作成
+(def world
+  [(gbd/make-driver "D1" [3 1 2 3] #{:rumor-a})
+   (gbd/make-driver "D2" [3 2 3 1] #{:rumor-b})
+   (gbd/make-driver "D3" [4 2 3 4 5] #{:rumor-c})])
+
+;; シミュレーション実行
+(gbd/drive-till-all-rumors-spread world)
+;; => 5 (5分で全噂が共有される)
+
+;; 絶対に出会わないルートの場合
+(def never-meet
+  [(gbd/make-driver "D1" [1] #{:rumor-a})
+   (gbd/make-driver "D2" [2] #{:rumor-b})])
+
+(gbd/drive-till-all-rumors-spread never-meet)
+;; => :never
+```
+
+## 7. 関数型アプローチの特徴
+
+### 不変データ構造
+
+すべての状態変更は新しいデータ構造を返します。元のデータは変更されません。
+
+```clojure
+;; ドライバーを移動しても元のドライバーは変更されない
+(def original (gbd/make-driver "Test" [1 2 3] #{:a}))
+(def moved (gbd/move-driver original))
+
+(gbd/current-stop original) ;; => 1 (変更なし)
+(gbd/current-stop moved)    ;; => 2
+```
+
+### 遅延評価
+
+`cycle` による無限シーケンスは遅延評価されるため、メモリを効率的に使用できます。
+
+### 純粋関数
+
+すべての関数は副作用がなく、同じ入力に対して常に同じ出力を返します。これによりテストが容易になります。
+
+## 8. パターンの応用
+
+このパターンは以下のような場面で応用できます：
+
+- **ネットワーク伝播**: ウイルスや情報の拡散シミュレーション
+- **グラフ探索**: 巡回セールスマン問題の変形
+- **状態同期**: 分散システムでの状態共有
+
+## まとめ
+
+本章では、ゴシップ好きなバスの運転手問題を通じて以下を学びました：
+
+1. **無限シーケンス**: `cycle` による循環データの表現
+2. **集合演算**: `set/union` による状態の統合
+3. **データ変換パイプライン**: `->` マクロによる処理の連鎖
+4. **終了条件の設計**: ループと条件分岐の組み合わせ
+
+## 参考コード
+
+本章のコード例は以下のファイルで確認できます：
+
+- ソースコード: `apps/clojure/part6/src/gossiping_bus_drivers/`
+- テストコード: `apps/clojure/part6/spec/gossiping_bus_drivers/`

package/lib/assets/docs/article/functional-desgin-ppp/clojure/16-payroll-system.md

@@ -0,0 +1,401 @@
+# 第16章: 給与計算システム
+
+## はじめに
+
+本章では、給与計算システムを題材に、関数型プログラミングにおけるドメインモデリングとマルチメソッドによる多態性の実現を学びます。
+
+この問題を通じて以下の概念を学びます：
+
+- Clojure Spec によるデータ仕様定義
+- マルチメソッドによる給与タイプ別の計算
+- 支払いスケジュールのモデリング
+
+## 1. ドメインモデル
+
+### 従業員の給与タイプ
+
+給与計算システムでは、以下の3種類の給与タイプをサポートします：
+
+- **月給制（Salaried）**: 固定月給
+- **時給制（Hourly）**: 労働時間に基づく給与
+- **歩合制（Commissioned）**: 基本給 + 売上に応じたコミッション
+
+```plantuml
+@startuml
+title 給与計算システムのドメインモデル
+
+class Employee {
+  +id: string
+  +name: string
+  +pay-class: PayClass
+  +schedule: Schedule
+  +payment-method: PaymentMethod
+}
+
+abstract class PayClass {
+  +calc-pay()
+}
+
+class Salaried {
+  +salary: number
+  +calc-pay(): salary
+}
+
+class Hourly {
+  +hourly-rate: number
+  +calc-pay(): hours * rate
+}
+
+class Commissioned {
+  +base-pay: number
+  +commission-rate: number
+  +calc-pay(): base + sales * rate
+}
+
+enum Schedule {
+  MONTHLY
+  WEEKLY
+  BIWEEKLY
+}
+
+enum PaymentMethod {
+  HOLD
+  DIRECT_DEPOSIT
+  MAIL
+}
+
+Employee --> PayClass
+Employee --> Schedule
+Employee --> PaymentMethod
+Salaried --|> PayClass
+Hourly --|> PayClass
+Commissioned --|> PayClass
+@enduml
+```
+
+## 2. Clojure Spec による仕様定義
+
+### 従業員の仕様
+
+```clojure
+(ns payroll.employee
+  (:require [clojure.spec.alpha :as s]))
+
+;; 基本属性
+(s/def ::id string?)
+(s/def ::name string?)
+(s/def ::address string?)
+
+;; 給与分類
+(s/def ::salary number?)
+(s/def ::hourly-rate number?)
+(s/def ::base-pay number?)
+(s/def ::commission-rate number?)
+
+(s/def ::pay-class
+  (s/or :salaried (s/tuple #{:salaried} ::salary)
+        :hourly (s/tuple #{:hourly} ::hourly-rate)
+        :commissioned (s/tuple #{:commissioned} ::base-pay ::commission-rate)))
+
+;; 支払いスケジュール
+(s/def ::schedule #{:monthly :weekly :biweekly})
+
+;; 支払い方法
+(s/def ::payment-method #{:hold :direct-deposit :mail})
+
+;; 従業員
+(s/def ::employee
+  (s/keys :req [::id ::name ::pay-class ::schedule ::payment-method]
+          :opt [::address]))
+```
+
+### コンストラクタ
+
+```clojure
+(defn make-salaried-employee
+  "月給制従業員を作成"
+  [id name salary]
+  {::id id
+   ::name name
+   ::pay-class [:salaried salary]
+   ::schedule :monthly
+   ::payment-method :hold})
+
+(defn make-hourly-employee
+  "時給制従業員を作成"
+  [id name hourly-rate]
+  {::id id
+   ::name name
+   ::pay-class [:hourly hourly-rate]
+   ::schedule :weekly
+   ::payment-method :hold})
+
+(defn make-commissioned-employee
+  "歩合制従業員を作成"
+  [id name base-pay commission-rate]
+  {::id id
+   ::name name
+   ::pay-class [:commissioned base-pay commission-rate]
+   ::schedule :biweekly
+   ::payment-method :hold})
+```
+
+## 3. マルチメソッドによる給与計算
+
+### 給与計算のディスパッチ
+
+```clojure
+(ns payroll.classification
+  (:require [payroll.employee :as emp]))
+
+(defmulti calc-pay
+  "給与を計算する
+   給与タイプに応じて異なる計算ロジックを適用"
+  (fn [employee _context] (emp/get-pay-type employee)))
+```
+
+### 月給制
+
+```clojure
+(defmethod calc-pay :salaried
+  [employee _context]
+  (let [[_ salary] (emp/get-pay-class employee)]
+    salary))
+```
+
+### 時給制
+
+```clojure
+(defmethod calc-pay :hourly
+  [employee context]
+  (let [[_ hourly-rate] (emp/get-pay-class employee)
+        time-cards (get-in context [:time-cards (emp/get-id employee)] [])
+        hours (map second time-cards)
+        total-hours (reduce + 0 hours)
+        ;; 週40時間を超える分は1.5倍
+        regular-hours (min total-hours 40)
+        overtime-hours (max 0 (- total-hours 40))]
+    (+ (* regular-hours hourly-rate)
+       (* overtime-hours hourly-rate 1.5))))
+```
+
+### 歩合制
+
+```clojure
+(defmethod calc-pay :commissioned
+  [employee context]
+  (let [[_ base-pay commission-rate] (emp/get-pay-class employee)
+        sales-receipts (get-in context [:sales-receipts (emp/get-id employee)] [])
+        total-sales (reduce + 0 (map second sales-receipts))]
+    (+ base-pay (* total-sales commission-rate))))
+```
+
+```plantuml
+@startuml
+title マルチメソッドによる給与計算
+
+participant "calc-pay" as calc
+participant "dispatch" as disp
+participant ":salaried" as sal
+participant ":hourly" as hour
+participant ":commissioned" as comm
+
+calc -> disp : get-pay-type(employee)
+
+alt 月給制
+  disp -> sal : calc-pay
+  sal --> calc : salary
+else 時給制
+  disp -> hour : calc-pay
+  hour --> calc : hours * rate + overtime * 1.5
+else 歩合制
+  disp -> comm : calc-pay
+  comm --> calc : base + sales * rate
+end
+@enduml
+```
+
+## 4. 支払いスケジュール
+
+### スケジュール判定
+
+```clojure
+(ns payroll.schedule
+  (:require [payroll.employee :as emp]))
+
+(defmulti is-pay-day?
+  "指定日が支払日かどうかを判定"
+  (fn [employee _date] (emp/get-schedule employee)))
+
+;; 月次（月末）
+(defmethod is-pay-day? :monthly
+  [_employee date]
+  (= (:day date) (last-day-of-month date)))
+
+;; 週次（金曜日）
+(defmethod is-pay-day? :weekly
+  [_employee date]
+  (= (:day-of-week date) :friday))
+
+;; 隔週（隔週の金曜日）
+(defmethod is-pay-day? :biweekly
+  [_employee date]
+  (and (= (:day-of-week date) :friday)
+       (:is-pay-week date)))
+```
+
+## 5. 支払い処理
+
+### 支払い方法によるディスパッチ
+
+```clojure
+(ns payroll.payroll
+  (:require [payroll.employee :as emp]
+            [payroll.classification :as class]
+            [payroll.schedule :as sched]))
+
+(defmulti process-payment
+  "支払いを処理"
+  (fn [employee _amount] (emp/get-payment-method employee)))
+
+(defmethod process-payment :hold
+  [employee amount]
+  {:type :hold
+   :employee-id (emp/get-id employee)
+   :amount amount
+   :message "支払いを保留"})
+
+(defmethod process-payment :direct-deposit
+  [employee amount]
+  {:type :direct-deposit
+   :employee-id (emp/get-id employee)
+   :amount amount
+   :message "口座に振り込み"})
+
+(defmethod process-payment :mail
+  [employee amount]
+  {:type :mail
+   :employee-id (emp/get-id employee)
+   :amount amount
+   :message "小切手を郵送"})
+```
+
+## 6. 給与支払いの実行
+
+```clojure
+(defn run-payroll
+  "給与支払いを実行
+   支払日に該当する従業員にのみ支払いを行う"
+  [employees context date]
+  (let [payable-employees (filter #(sched/is-pay-day? % date) employees)]
+    (for [emp payable-employees
+          :let [pay (class/calc-pay emp context)]]
+      (process-payment emp pay))))
+```
+
+```plantuml
+@startuml
+title 給与支払いフロー
+
+start
+:従業員リストを取得;
+
+:支払日の従業員をフィルタ;
+note right: is-pay-day? でチェック
+
+while (支払対象の従業員がある?) is (yes)
+  :給与を計算;
+  note right: calc-pay で計算
+
+  :支払いを処理;
+  note right: process-payment で
+  支払い方法に応じた処理
+
+endwhile (no)
+
+:支払い結果を返す;
+stop
+@enduml
+```
+
+## 7. 使用例
+
+```clojure
+(require '[payroll.employee :as emp])
+(require '[payroll.classification :as class])
+(require '[payroll.schedule :as sched])
+(require '[payroll.payroll :as payroll])
+
+;; 従業員の作成
+(def salaried-emp
+  (emp/make-salaried-employee "E001" "田中太郎" 500000))
+
+(def hourly-emp
+  (emp/make-hourly-employee "E002" "佐藤花子" 1500))
+
+(def commissioned-emp
+  (emp/make-commissioned-employee "E003" "鈴木一郎" 200000 0.1))
+
+;; コンテキストの作成（タイムカード、売上データ）
+(def ctx
+  (-> (class/make-context)
+      (class/add-time-card "E002" "2024-01-15" 8)
+      (class/add-time-card "E002" "2024-01-16" 10)
+      (class/add-sales-receipt "E003" "2024-01-15" 100000)
+      (class/add-sales-receipt "E003" "2024-01-16" 50000)))
+
+;; 給与計算
+(class/calc-pay salaried-emp ctx)     ;; => 500000
+(class/calc-pay hourly-emp ctx)       ;; => 27000.0 (18時間 * 1500)
+(class/calc-pay commissioned-emp ctx) ;; => 215000.0 (200000 + 15000)
+```
+
+## 8. 関数型アプローチの利点
+
+### 1. テスト容易性
+
+純粋関数であるため、テストが簡単です。
+
+```clojure
+(describe "給与計算 - 時給制"
+  (it "残業時間は1.5倍で計算"
+    (let [e (emp/make-hourly-employee "E002" "佐藤" 1000)
+          ctx (class/add-time-card {} "E002" "2024-01-15" 45)]
+      ;; 40 * 1000 + 5 * 1000 * 1.5 = 47500
+      (should= 47500.0 (class/calc-pay e ctx)))))
+```
+
+### 2. 拡張容易性
+
+新しい給与タイプの追加は、新しいメソッドを定義するだけです。
+
+```clojure
+;; 新しい給与タイプ: 契約制
+(defmethod calc-pay :contract
+  [employee context]
+  (let [[_ contract-amount] (emp/get-pay-class employee)]
+    contract-amount))
+```
+
+### 3. 関心の分離
+
+- **employee**: データ構造とアクセサ
+- **classification**: 給与計算ロジック
+- **schedule**: 支払日判定
+- **payroll**: 統合処理
+
+## まとめ
+
+本章では、給与計算システムを通じて以下を学びました：
+
+1. **Clojure Spec**: データ仕様の定義
+2. **マルチメソッド**: 給与タイプによるディスパッチ
+3. **関心の分離**: モジュール化された設計
+4. **純粋関数**: テスト容易な実装
+
+## 参考コード
+
+本章のコード例は以下のファイルで確認できます：
+
+- ソースコード: `apps/clojure/part6/src/payroll/`
+- テストコード: `apps/clojure/part6/spec/payroll/`