in_time_scope 0.1.5 → 0.1.6

data/docs/zh/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
+```
+
+就是这样。一行 DSL，模型中无需原生 SQL。
+
+## 为什么使用这个 Gem？
+
+这个 Gem 的目的：
+
+- **保持时间范围逻辑一致性** - 在整个代码库中统一
+- **避免复制粘贴 SQL** - 防止容易出错的重复代码
+- **让时间成为一等公民的领域概念** - 使用像 `in_time_published` 这样的命名作用域
+- **自动检测可空性** - 从 schema 生成优化的查询
+
+## 推荐用途
+
+- 具有有效期的 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 读取你的 schema 并生成正确的 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`（第一个参数） | `: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 扩展了以下概念：
+
+- 用于优化查询的 schema 感知 NULL 处理
+- 每个模型多个命名作用域
+- 仅开始 / 仅结束模式
+- 用于高效 `has_one` 关联的 `latest_in_time` / `earliest_in_time`
+- 反向作用域：`before_in_time`、`after_in_time`、`out_of_time`
+
+## 开发
+
+```bash
+# 安装依赖
+bin/setup
+
+# 运行测试
+bundle exec rspec
+
+# 运行 linting
+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) 上提交 bug 报告和 pull request。
+
+## 许可证
+
+MIT 许可证

data/docs/zh/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
+# 就这样。没有任务。没有 status 列。没有基础设施。
+user.points.in_time.sum(:amount)
+```
+
+**一行代码。零基础设施。永远准确。**
+
+### 为什么这样可行
+
+`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) | 必需 | **不需要** |
+| Status 列 | 必需 | **不需要** |
+| 更新 status 的迁移 | 必需 | **不需要** |
+| 任务失败监控 | 必需 | **不需要** |
+| 重试逻辑 | 必需 | **不需要** |
+| 竞态条件处理 | 必需 | **不需要** |
+
+### 额外好处：免费的时间旅行
+
+使用基于 cron 的系统，回答"用户 X 在 1 月 15 日有多少积分？"需要复杂的审计日志或事件溯源。
+
+使用 InTimeScope：
+
+```ruby
+user.points.in_time(Date.parse("2024-01-15").middle_of_day).sum(:amount)
+```
+
+**历史查询直接可用。** 没有额外的表。没有事件溯源。没有复杂性。
+
+## Schema
+
+```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` 的威力
+
+这简单的一行解锁了有效积分的 **无 N+1 预加载**：
+
+```ruby
+# 仅用 2 个查询加载 100 个用户及其有效积分
+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 任务可能运行两次、跳过运行或重叠。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 间隔） | **毫秒** |
+| 调试 | 任务日志 + 数据库 | **仅数据库** |
+| 测试 | 时间旅行 + 运行任务 | **仅查询** |
+| 失败模式 | 多种（任务失败、竞态条件） | **无** |
+
+## 提示
+
+1. **使用数据库索引** 在 `[user_id, start_at, end_at]` 上以获得最佳性能。
+
+2. **在注册时预先发放积分** 而不是安排 cron 任务。
+
+3. **使用 `in_time(time)` 进行审计** 以检查任何历史时间点的积分余额。
+
+4. **与反向作用域结合** 以构建显示待生效/已过期积分的管理后台。

data/docs/zh/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)
+
+## 用例
+
+- 用户可以更改显示名称
+- 你需要保留所有名称变更的历史
+- 你想要检索在特定时间点有效的名称（例如：用于审计日志、历史报告）
+
+## Schema
+
+```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"
+```
+
+### 高效的预加载
+
+```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` 关联。
+
+## 提示
+
+1. **始终将 `latest_in_time` 与 `has_one` 一起使用** - 它确保每个外键只获取一条记录。
+
+2. **添加复合索引** 在 `[user_id, start_at]` 上以获得最佳查询性能。
+
+3. **使用 `includes` 进行预加载** - `NOT EXISTS` 模式与 Rails 预加载高效配合。
+
+4. **考虑添加唯一约束** 在 `[user_id, start_at]` 上以防止同一时间的重复记录。