active_record_in_time_scope 0.1.7

data/docs/ja/index.md

@@ -0,0 +1,192 @@
+# InTimeScope
+
+Railsでこんなコードを毎回書いていませんか？
+
+```ruby
+# Before
+Event.where("start_at <= ? AND (end_at IS NULL OR end_at > ?)", Time.current, Time.current)
+
+# After
+class Event < ActiveRecord::Base
+  in_time_scope
+end
+
+Event.in_time
+```
+
+これだけです。DSL1行で、モデルに生SQLを書く必要がなくなります。
+
+## このGemを使う理由
+
+このGemの目的：
+
+- **時間範囲ロジックの一貫性を保つ** - コードベース全体で統一
+- **コピペSQLを回避** - 間違えやすいSQLの繰り返しを防止
+- **時間をファーストクラスのドメイン概念に** - `in_time_published`のような名前付きスコープ
+- **NULL許可を自動検出** - スキーマから最適化されたクエリを生成
+
+## 推奨される用途
+
+- 有効期限を持つRailsアプリケーション
+- `start_at` / `end_at`カラムを持つモデル
+- 散在する`where`句なしで一貫した時間ロジックを求めるチーム
+
+## インストール
+
+```bash
+bundle add in_time_scope
+```
+
+## クイックスタート
+
+```ruby
+class Event < ActiveRecord::Base
+  in_time_scope
+end
+
+# クラススコープ
+Event.in_time                          # 現在有効なレコード
+Event.in_time(Time.parse("2024-06-01")) # 特定時刻に有効なレコード
+
+# インスタンスメソッド
+event.in_time?                          # このレコードは現在有効？
+event.in_time?(some_time)               # その時刻に有効だった？
+```
+
+## 機能
+
+### 自動最適化されたSQL
+
+GemがスキーマをベースにSQLを読み取り、適切なSQLを生成します：
+
+```ruby
+# NULL許可カラム → NULL対応クエリ
+WHERE (start_at IS NULL OR start_at <= ?) AND (end_at IS NULL OR end_at > ?)
+
+# NOT NULLカラム → シンプルなクエリ
+WHERE start_at <= ? AND end_at > ?
+```
+
+### 名前付きスコープ
+
+モデルごとに複数の時間範囲：
+
+```ruby
+class Article < ActiveRecord::Base
+  in_time_scope :published   # → Article.in_time_published
+  in_time_scope :featured    # → Article.in_time_featured
+end
+```
+
+### カスタムカラム
+
+```ruby
+class Campaign < ActiveRecord::Base
+  in_time_scope start_at: { column: :available_at },
+                end_at: { column: :expired_at }
+end
+```
+
+### 開始のみパターン（バージョン履歴）
+
+各行が次の行まで有効なレコード用：
+
+```ruby
+class Price < ActiveRecord::Base
+  in_time_scope start_at: { null: false }, end_at: { column: nil }
+end
+
+# ボーナス：NOT EXISTSを使った効率的なhas_one
+class User < ActiveRecord::Base
+  has_one :current_price, -> { latest_in_time(:user_id) }, class_name: "Price"
+end
+
+User.includes(:current_price)  # N+1なし、ユーザーごとに最新のみ取得
+```
+
+### 終了のみパターン（有効期限）
+
+有効期限が切れるまで有効なレコード用：
+
+```ruby
+class Coupon < ActiveRecord::Base
+  in_time_scope start_at: { column: nil }, end_at: { null: false }
+end
+```
+
+### 逆スコープ
+
+時間範囲外のレコードをクエリ：
+
+```ruby
+# まだ開始していないレコード (start_at > time)
+Event.before_in_time
+event.before_in_time?
+
+# すでに終了したレコード (end_at <= time)
+Event.after_in_time
+event.after_in_time?
+
+# 時間範囲外のレコード（開始前または終了後）
+Event.out_of_time
+event.out_of_time?  # in_time?の論理的な逆
+```
+
+名前付きスコープでも動作：
+
+```ruby
+Article.before_in_time_published  # まだ公開されていない
+Article.after_in_time_published   # 公開終了
+Article.out_of_time_published     # 現在公開されていない
+```
+
+## オプションリファレンス
+
+| オプション | デフォルト | 説明 | 例 |
+| --- | --- | --- | --- |
+| `scope_name`（第1引数） | `:in_time` | `in_time_published`のような名前付きスコープ | `in_time_scope :published` |
+| `start_at: { column: }` | `:start_at` | カスタムカラム名、`nil`で無効化 | `start_at: { column: :available_at }` |
+| `end_at: { column: }` | `:end_at` | カスタムカラム名、`nil`で無効化 | `end_at: { column: nil }` |
+| `start_at: { null: }` | 自動検出 | NULL処理を強制 | `start_at: { null: false }` |
+| `end_at: { null: }` | 自動検出 | NULL処理を強制 | `end_at: { null: true }` |
+
+## 使用例
+
+- [有効期限付きポイントシステム](./point-system.md) - フルタイムウィンドウパターン
+- [ユーザー名履歴](./user-name-history.md) - 開始のみパターン
+
+## 謝辞
+
+[onk/shibaraku](https://github.com/onk/shibaraku)にインスパイアされました。このGemは以下の機能で概念を拡張しています：
+
+- 最適化されたクエリのためのスキーマ対応NULL処理
+- モデルごとの複数の名前付きスコープ
+- 開始のみ / 終了のみパターン
+- 効率的な`has_one`アソシエーション用の`latest_in_time` / `earliest_in_time`
+- 逆スコープ: `before_in_time`, `after_in_time`, `out_of_time`
+
+## 開発
+
+```bash
+# 依存関係のインストール
+bin/setup
+
+# テスト実行
+bundle exec rspec
+
+# Lint実行
+bundle exec rubocop
+
+# CLAUDE.mdの生成（AIコーディングアシスタント用）
+npx rulesync generate
+```
+
+このプロジェクトは[rulesync](https://github.com/dyoshikawa/rulesync)を使用してAIアシスタントルールを管理しています。`.rulesync/rules/*.md`を編集し、`npx rulesync generate`を実行して`CLAUDE.md`を更新してください。
+
+## 貢献
+
+バグレポートとプルリクエストは[GitHub](https://github.com/kyohah/in_time_scope)で受け付けています。
+
+## ライセンス
+
+MITライセンス

data/docs/ja/point-system.md

@@ -0,0 +1,295 @@
+# 有効期限付きポイントシステムの例
+
+この例では、`in_time_scope`を使用して有効期限付きポイントシステムを実装する方法を示します。ポイントは将来有効になるように事前付与でき、cronジョブが不要になります。
+
+参照: [spec/point_system_spec.rb](https://github.com/kyohah/in_time_scope/blob/main/spec/point_system_spec.rb)
+
+## ユースケース
+
+- ユーザーが有効期限付きのポイントを獲得（開始日と終了日）
+- ポイントを将来有効になるように事前付与可能（例：月額メンバーシップボーナス）
+- cronジョブなしで任意の時点の有効ポイントを計算
+- 今後のポイント、期限切れポイントなどを検索
+
+## Cronジョブ不要
+
+**これが最大の特徴です。** 従来のポイントシステムはスケジュールジョブの悪夢です：
+
+### よくあるCron地獄
+
+```ruby
+# activate_points_job.rb - 毎分実行
+class ActivatePointsJob < ApplicationJob
+  def perform
+    Point.where(status: "pending")
+         .where("start_at <= ?", Time.current)
+         .update_all(status: "active")
+  end
+end
+
+# expire_points_job.rb - 毎分実行
+class ExpirePointsJob < ApplicationJob
+  def perform
+    Point.where(status: "active")
+         .where("end_at <= ?", Time.current)
+         .update_all(status: "expired")
+  end
+end
+
+# さらに必要なもの：
+# - Sidekiq / Delayed Job / Good Job
+# - Redis（Sidekiq用）
+# - Cronまたはwhenever gem
+# - ジョブ失敗の監視
+# - 失敗時のリトライロジック
+# - 重複実行防止のロック機構
+```
+
+### InTimeScopeを使う方法
+
+```ruby
+# これだけ。ジョブなし。ステータスカラムなし。インフラ不要。
+user.points.in_time.sum(:amount)
+```
+
+**1行。インフラゼロ。常に正確。**
+
+### なぜこれが機能するのか
+
+`start_at`と`end_at`カラムがそのまま状態です。`status`カラムは不要で、時間比較はクエリ時に行われます：
+
+```ruby
+# これらすべてがバックグラウンド処理なしで動作：
+user.points.in_time                    # 現在有効
+user.points.in_time(1.month.from_now)  # 来月有効
+user.points.in_time(1.year.ago)        # 昨年有効だった（監査！）
+user.points.before_in_time             # 保留中（まだ有効でない）
+user.points.after_in_time              # 期限切れ
+```
+
+### 削減できるもの
+
+| コンポーネント | Cronベースシステム | InTimeScope |
+|-----------|------------------|-------------|
+| バックグラウンドジョブライブラリ | 必要 | **不要** |
+| ジョブ用Redis/データベース | 必要 | **不要** |
+| ジョブスケジューラ（cron） | 必要 | **不要** |
+| ステータスカラム | 必要 | **不要** |
+| ステータス更新のマイグレーション | 必要 | **不要** |
+| ジョブ失敗の監視 | 必要 | **不要** |
+| リトライロジック | 必要 | **不要** |
+| 競合状態の処理 | 必要 | **不要** |
+
+### ボーナス：タイムトラベルが無料
+
+Cronベースのシステムでは、「ユーザーXの1月15日のポイント残高は？」という質問に答えるには複雑な監査ログやイベントソーシングが必要です。
+
+InTimeScopeなら：
+
+```ruby
+user.points.in_time(Date.parse("2024-01-15").middle_of_day).sum(:amount)
+```
+
+**履歴クエリがそのまま動きます。** 追加テーブル不要。イベントソーシング不要。複雑さゼロ。
+
+## スキーマ
+
+```ruby
+# Migration
+class CreatePoints < ActiveRecord::Migration[7.0]
+  def change
+    create_table :points do |t|
+      t.references :user, null: false, foreign_key: true
+      t.integer :amount, null: false
+      t.string :reason, null: false
+      t.datetime :start_at, null: false  # ポイントが使用可能になる日時
+      t.datetime :end_at, null: false    # ポイントが期限切れになる日時
+      t.timestamps
+    end
+
+    add_index :points, [:user_id, :start_at, :end_at]
+  end
+end
+```
+
+## モデル
+
+```ruby
+class Point < ApplicationRecord
+  belongs_to :user
+
+  # start_atとend_atの両方が必須（完全な時間範囲）
+  in_time_scope start_at: { null: false }, end_at: { null: false }
+end
+
+class User < ApplicationRecord
+  has_many :points
+  has_many :in_time_points, -> { in_time }, class_name: "Point"
+
+  # 月次ボーナスポイントを付与（事前スケジュール）
+  def grant_monthly_bonus(amount:, months_valid: 6)
+    points.create!(
+      amount: amount,
+      reason: "Monthly membership bonus",
+      start_at: 1.month.from_now,  # 来月有効化
+      end_at: (1 + months_valid).months.from_now
+    )
+  end
+end
+```
+
+### `has_many :in_time_points`の威力
+
+このシンプルな1行で、有効ポイントの**N+1問題のないEager Loading**が可能になります：
+
+```ruby
+# 100人のユーザーと有効ポイントをたった2クエリで取得
+users = User.includes(:in_time_points).limit(100)
+
+users.each do |user|
+  # 追加クエリなし！すでにロード済み。
+  total = user.in_time_points.sum(&:amount)
+  puts "#{user.name}: #{total} points"
+end
+```
+
+このアソシエーションがないと：
+
+```ruby
+# N+1問題：ユーザー1クエリ + ポイント100クエリ
+users = User.limit(100)
+users.each do |user|
+  total = user.points.in_time.sum(:amount)  # ユーザーごとにクエリ！
+end
+```
+
+## 使い方
+
+### 異なる有効期限でポイントを付与
+
+```ruby
+user = User.find(1)
+
+# 即時ポイント（1年間有効）
+user.points.create!(
+  amount: 100,
+  reason: "Welcome bonus",
+  start_at: Time.current,
+  end_at: 1.year.from_now
+)
+
+# 6ヶ月会員向けの事前スケジュールポイント
+# ポイントは来月有効化、有効化後6ヶ月間有効
+user.grant_monthly_bonus(amount: 500, months_valid: 6)
+
+# キャンペーンポイント（期間限定）
+user.points.create!(
+  amount: 200,
+  reason: "Summer campaign",
+  start_at: Date.parse("2024-07-01").beginning_of_day,
+  end_at: Date.parse("2024-08-31").end_of_day
+)
+```
+
+### ポイントの検索
+
+```ruby
+# 現在の有効ポイント
+user.in_time_member_points.sum(:amount)
+# => 100（ウェルカムボーナスのみ現在有効）
+
+# 来月利用可能になるポイント数を確認
+user.in_time_member_points(1.month.from_now).sum(:amount)
+# => 600（ウェルカムボーナス + 月次ボーナス）
+
+# 保留中のポイント（スケジュール済みだがまだ有効でない）
+user.points.before_in_time.sum(:amount)
+# => 500（有効化待ちの月次ボーナス）
+
+# 期限切れポイント
+user.points.after_in_time.sum(:amount)
+
+# すべての無効ポイント（保留中 + 期限切れ）
+user.points.out_of_time.sum(:amount)
+```
+
+### 管理ダッシュボードクエリ
+
+```ruby
+# 履歴監査：特定日に有効だったポイント
+Point.in_time(Date.parse("2024-01-15").middle_of_day)
+     .group(:user_id)
+     .sum(:amount)
+```
+
+## 自動メンバーシップボーナスフロー
+
+6ヶ月プレミアムメンバー向けに、**cronなし、Sidekiqなし、Redisなし、監視なし**で定期ボーナスを設定できます：
+
+```ruby
+# ユーザーがプレミアムに登録したとき、メンバーシップと全ボーナスをアトミックに作成
+ActiveRecord::Base.transaction do
+  membership = Membership.create!(user: user, plan: "premium_6_months")
+
+  # 登録時に6ヶ月分の月次ボーナスを事前作成
+  6.times do |month|
+    user.points.create!(
+      amount: 500,
+      reason: "Premium member bonus - Month #{month + 1}",
+      start_at: (month + 1).months.from_now,
+      end_at: (month + 7).months.from_now  # 各ボーナスは6ヶ月間有効
+    )
+  end
+end
+# => メンバーシップ + 毎月有効化される6つのポイントレコードを作成
+```
+
+## この設計が優れている理由
+
+### 正確性
+
+- **競合状態なし**: Cronジョブは2回実行されたり、スキップしたり、重複したりする可能性があります。InTimeScopeのクエリは常に決定論的です。
+- **タイミングのずれなし**: Cronは間隔で実行（毎分？5分ごと？）。InTimeScopeはミリ秒単位で正確です。
+- **更新漏れなし**: ジョブの失敗でポイントが不正な状態になる可能性があります。InTimeScopeには破損する状態がありません。
+
+### シンプルさ
+
+- **インフラ不要**: Sidekiqを削除。Redisを削除。ジョブ監視を削除。
+- **ステータス変更のマイグレーション不要**: 時間がそのまま状態です。`UPDATE`文は不要。
+- **ジョブログのデバッグ不要**: データベースをクエリするだけで何が起きているかわかります。
+
+### テスト容易性
+
+```ruby
+# Cronベースのテストは面倒：
+travel_to 1.month.from_now do
+  ActivatePointsJob.perform_now
+  ExpirePointsJob.perform_now
+  expect(user.points.active.sum(:amount)).to eq(500)
+end
+
+# InTimeScopeのテストは簡単：
+expect(user.points.in_time(1.month.from_now).sum(:amount)).to eq(500)
+```
+
+### まとめ
+
+| 観点 | Cronベース | InTimeScope |
+|--------|-----------|-------------|
+| インフラ | Sidekiq + Redis + Cron | **なし** |
+| ポイント有効化 | バッチジョブ（遅延） | **即時** |
+| 履歴クエリ | 監査ログなしでは不可能 | **組み込み** |
+| タイミング精度 | 分（cron間隔） | **ミリ秒** |
+| デバッグ | ジョブログ + データベース | **データベースのみ** |
+| テスト | タイムトラベル + ジョブ実行 | **クエリのみ** |
+| 障害モード | 多数（ジョブ失敗、競合状態） | **なし** |
+
+## Tips
+
+1. **データベースインデックスを使用** - `[user_id, start_at, end_at]`にインデックスを追加してパフォーマンスを最適化。
+
+2. **登録時にポイントを事前付与** - cronジョブをスケジュールする代わりに。
+
+3. **監査には`in_time(time)`を使用** - 任意の過去時点のポイント残高を確認。
+
+4. **逆スコープと組み合わせ** - 保留中/期限切れポイントを表示する管理ダッシュボードを構築。

data/docs/ja/user-name-history.md

@@ -0,0 +1,164 @@
+# ユーザー名履歴の例
+
+この例では、`in_time_scope`を使用してユーザー名の履歴を管理し、任意の時点でのユーザー名を取得する方法を示します。
+
+参照: [spec/user_name_history_spec.rb](https://github.com/kyohah/in_time_scope/blob/main/spec/user_name_history_spec.rb)
+
+## ユースケース
+
+- ユーザーが表示名を変更できる
+- すべての名前変更の履歴を保持する必要がある
+- 特定の時点で有効だった名前を取得したい（監査ログ、履歴レポートなど）
+
+## スキーマ
+
+```ruby
+# Migration
+class CreateUserNameHistories < ActiveRecord::Migration[7.0]
+  def change
+    create_table :users do |t|
+      t.string :email, null: false
+      t.timestamps
+    end
+
+    create_table :user_name_histories do |t|
+      t.references :user, null: false, foreign_key: true
+      t.string :name, null: false
+      t.datetime :start_at, null: false  # この名前が有効になった日時
+      t.timestamps
+    end
+
+    add_index :user_name_histories, [:user_id, :start_at]
+  end
+end
+```
+
+## モデル
+
+```ruby
+class UserNameHistory < ApplicationRecord
+  belongs_to :user
+  include InTimeScope
+
+  # 開始日のみパターン: 各レコードはstart_atから次のレコードまで有効
+  in_time_scope start_at: { null: false }, end_at: { column: nil }
+end
+
+class User < ApplicationRecord
+  has_many :user_name_histories
+
+  # 現在の名前を取得（開始済みの最新レコード）
+  has_one :current_name_history,
+          -> { latest_in_time(:user_id) },
+          class_name: "UserNameHistory"
+
+  # 現在の名前を取得する便利メソッド
+  def current_name
+    current_name_history&.name
+  end
+
+  # 特定時点の名前を取得
+  def name_at(time)
+    user_name_histories.in_time(time).order(start_at: :desc).first&.name
+  end
+end
+```
+
+## 使い方
+
+### 名前履歴の作成
+
+```ruby
+user = User.create!(email: "alice@example.com")
+
+# 初期の名前
+UserNameHistory.create!(
+  user: user,
+  name: "Alice",
+  start_at: Time.parse("2024-01-01")
+)
+
+# 名前の変更
+UserNameHistory.create!(
+  user: user,
+  name: "Alice Smith",
+  start_at: Time.parse("2024-06-01")
+)
+
+# さらに名前を変更
+UserNameHistory.create!(
+  user: user,
+  name: "Alice Johnson",
+  start_at: Time.parse("2024-09-01")
+)
+```
+
+### 名前の取得
+
+```ruby
+# 現在の名前（has_oneとlatest_in_timeを使用）
+user.current_name
+# => "Alice Johnson"
+
+# 特定時点の名前
+user.name_at(Time.parse("2024-03-15"))
+# => "Alice"
+
+user.name_at(Time.parse("2024-07-15"))
+# => "Alice Smith"
+
+user.name_at(Time.parse("2024-10-15"))
+# => "Alice Johnson"
+```
+
+### 効率的なEager Loading
+
+```ruby
+# ユーザーと現在の名前を一括取得（N+1なし）
+users = User.includes(:current_name_history).limit(100)
+
+users.each do |user|
+  puts "#{user.email}: #{user.current_name_history&.name}"
+end
+```
+
+### 有効なレコードの検索
+
+```ruby
+# 現在有効なすべての名前レコード
+UserNameHistory.in_time
+# => 各ユーザーの最新の名前レコードを返す
+
+# 特定時点で有効だった名前レコード
+UserNameHistory.in_time(Time.parse("2024-05-01"))
+
+# まだ開始していない名前レコード（将来予定）
+UserNameHistory.before_in_time
+```
+
+## `latest_in_time`の仕組み
+
+`latest_in_time(:user_id)`スコープは効率的な`NOT EXISTS`サブクエリを生成します:
+
+```sql
+SELECT * FROM user_name_histories AS h
+WHERE h.start_at <= '2024-10-01'
+  AND NOT EXISTS (
+    SELECT 1 FROM user_name_histories AS newer
+    WHERE newer.user_id = h.user_id
+      AND newer.start_at <= '2024-10-01'
+      AND newer.start_at > h.start_at
+  )
+```
+
+これにより、指定時点で有効だったユーザーごとの最新レコードのみが返され、`has_one`アソシエーションに最適です。
+
+## Tips
+
+1. **`has_one`では必ず`latest_in_time`を使用** - 外部キーごとに1レコードのみが取得されることを保証します。
+
+2. **`[user_id, start_at]`の複合インデックスを追加** - クエリパフォーマンスを最適化します。
+
+3. **Eager Loadingには`includes`を使用** - `NOT EXISTS`パターンはRailsのEager Loadingと効率的に連携します。
+
+4. **`[user_id, start_at]`にユニーク制約を追加することを検討** - 同時刻の重複レコードを防止します。

data/docs/src/SUMMARY.md

@@ -0,0 +1,5 @@
+# Summary
+
+- [Introduction](./index.md)
+- [Point System with Expiration](./point-system.md)
+- [User Name History](./user-name-history.md)