active_record_in_time_scope 0.1.7

data/docs/fr/index.md

@@ -0,0 +1,192 @@
+# InTimeScope
+
+Vous écrivez ceci à chaque fois dans 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
+```
+
+C'est tout. Une ligne de DSL, zéro SQL brut dans vos modèles.
+
+## Pourquoi ce Gem ?
+
+Ce gem existe pour :
+
+- **Maintenir une logique de plage temporelle cohérente** dans tout votre codebase
+- **Éviter le copier-coller de SQL** facile à mal écrire
+- **Faire du temps un concept de domaine de première classe** avec des scopes nommés comme `in_time_published`
+- **Détecter automatiquement la nullabilité** depuis votre schéma pour des requêtes optimisées
+
+## Recommandé pour
+
+- Les nouvelles applications Rails avec des périodes de validité
+- Les modèles avec des colonnes `start_at` / `end_at`
+- Les équipes qui veulent une logique temporelle cohérente sans clauses `where` dispersées
+
+## Installation
+
+```bash
+bundle add in_time_scope
+```
+
+## Démarrage rapide
+
+```ruby
+class Event < ActiveRecord::Base
+  in_time_scope
+end
+
+# Scope de classe
+Event.in_time                          # Enregistrements actifs maintenant
+Event.in_time(Time.parse("2024-06-01")) # Enregistrements actifs à un moment précis
+
+# Méthode d'instance
+event.in_time?                          # Cet enregistrement est-il actif maintenant ?
+event.in_time?(some_time)               # Était-il actif à ce moment-là ?
+```
+
+## Fonctionnalités
+
+### SQL auto-optimisé
+
+Le gem lit votre schéma et génère le bon SQL :
+
+```ruby
+# Colonnes autorisant NULL → requête NULL-aware
+WHERE (start_at IS NULL OR start_at <= ?) AND (end_at IS NULL OR end_at > ?)
+
+# Colonnes NOT NULL → requête simple
+WHERE start_at <= ? AND end_at > ?
+```
+
+### Scopes nommés
+
+Plusieurs fenêtres temporelles par modèle :
+
+```ruby
+class Article < ActiveRecord::Base
+  in_time_scope :published   # → Article.in_time_published
+  in_time_scope :featured    # → Article.in_time_featured
+end
+```
+
+### Colonnes personnalisées
+
+```ruby
+class Campaign < ActiveRecord::Base
+  in_time_scope start_at: { column: :available_at },
+                end_at: { column: :expired_at }
+end
+```
+
+### Modèle début uniquement (historique de versions)
+
+Pour les enregistrements où chaque ligne est valide jusqu'à la suivante :
+
+```ruby
+class Price < ActiveRecord::Base
+  in_time_scope start_at: { null: false }, end_at: { column: nil }
+end
+
+# Bonus : has_one efficace avec NOT EXISTS
+class User < ActiveRecord::Base
+  has_one :current_price, -> { latest_in_time(:user_id) }, class_name: "Price"
+end
+
+User.includes(:current_price)  # Pas de N+1, récupère uniquement le plus récent par utilisateur
+```
+
+### Modèle fin uniquement (expiration)
+
+Pour les enregistrements actifs jusqu'à leur expiration :
+
+```ruby
+class Coupon < ActiveRecord::Base
+  in_time_scope start_at: { column: nil }, end_at: { null: false }
+end
+```
+
+### Scopes inversés
+
+Requêter les enregistrements en dehors de la fenêtre temporelle :
+
+```ruby
+# Enregistrements pas encore commencés (start_at > time)
+Event.before_in_time
+event.before_in_time?
+
+# Enregistrements déjà terminés (end_at <= time)
+Event.after_in_time
+event.after_in_time?
+
+# Enregistrements en dehors de la fenêtre temporelle (avant OU après)
+Event.out_of_time
+event.out_of_time?  # Inverse logique de in_time?
+```
+
+Fonctionne aussi avec les scopes nommés :
+
+```ruby
+Article.before_in_time_published  # Pas encore publié
+Article.after_in_time_published   # Publication terminée
+Article.out_of_time_published     # Non publié actuellement
+```
+
+## Référence des options
+
+| Option | Défaut | Description | Exemple |
+| --- | --- | --- | --- |
+| `scope_name` (1er arg) | `:in_time` | Scope nommé comme `in_time_published` | `in_time_scope :published` |
+| `start_at: { column: }` | `:start_at` | Nom de colonne personnalisé, `nil` pour désactiver | `start_at: { column: :available_at }` |
+| `end_at: { column: }` | `:end_at` | Nom de colonne personnalisé, `nil` pour désactiver | `end_at: { column: nil }` |
+| `start_at: { null: }` | auto-détection | Forcer la gestion des NULL | `start_at: { null: false }` |
+| `end_at: { null: }` | auto-détection | Forcer la gestion des NULL | `end_at: { null: true }` |
+
+## Exemples
+
+- [Système de points avec expiration](./point-system.md) - Modèle fenêtre temporelle complète
+- [Historique des noms d'utilisateur](./user-name-history.md) - Modèle début uniquement
+
+## Remerciements
+
+Inspiré par [onk/shibaraku](https://github.com/onk/shibaraku). Ce gem étend le concept avec :
+
+- Gestion NULL sensible au schéma pour des requêtes optimisées
+- Plusieurs scopes nommés par modèle
+- Modèles début uniquement / fin uniquement
+- `latest_in_time` / `earliest_in_time` pour des associations `has_one` efficaces
+- Scopes inversés : `before_in_time`, `after_in_time`, `out_of_time`
+
+## Développement
+
+```bash
+# Installer les dépendances
+bin/setup
+
+# Exécuter les tests
+bundle exec rspec
+
+# Exécuter le linting
+bundle exec rubocop
+
+# Générer CLAUDE.md (pour les assistants de codage IA)
+npx rulesync generate
+```
+
+Ce projet utilise [rulesync](https://github.com/dyoshikawa/rulesync) pour gérer les règles des assistants IA. Éditez `.rulesync/rules/*.md` et exécutez `npx rulesync generate` pour mettre à jour `CLAUDE.md`.
+
+## Contribuer
+
+Les rapports de bugs et les pull requests sont les bienvenus sur [GitHub](https://github.com/kyohah/in_time_scope).
+
+## Licence
+
+Licence MIT

data/docs/fr/point-system.md

@@ -0,0 +1,295 @@
+# Exemple de système de points avec expiration
+
+Cet exemple montre comment implémenter un système de points avec dates d'expiration en utilisant `in_time_scope`. Les points peuvent être pré-accordés pour devenir actifs dans le futur, éliminant le besoin de jobs cron.
+
+Voir aussi : [spec/point_system_spec.rb](https://github.com/kyohah/in_time_scope/blob/main/spec/point_system_spec.rb)
+
+## Cas d'utilisation
+
+- Les utilisateurs gagnent des points avec des périodes de validité (date de début et date d'expiration)
+- Les points peuvent être pré-accordés pour s'activer dans le futur (ex : bonus mensuels d'adhésion)
+- Calculer les points valides à tout moment sans jobs cron
+- Requêter les points à venir, expirés, etc.
+
+## Aucun job Cron requis
+
+**C'est LA fonctionnalité phare.** Les systèmes de points traditionnels sont un cauchemar de jobs planifiés :
+
+### L'enfer Cron auquel vous êtes habitué
+
+```ruby
+# activate_points_job.rb - s'exécute chaque minute
+class ActivatePointsJob < ApplicationJob
+  def perform
+    Point.where(status: "pending")
+         .where("start_at <= ?", Time.current)
+         .update_all(status: "active")
+  end
+end
+
+# expire_points_job.rb - s'exécute chaque minute
+class ExpirePointsJob < ApplicationJob
+  def perform
+    Point.where(status: "active")
+         .where("end_at <= ?", Time.current)
+         .update_all(status: "expired")
+  end
+end
+
+# Et ensuite vous avez besoin de :
+# - Sidekiq / Delayed Job / Good Job
+# - Redis (pour Sidekiq)
+# - Cron ou whenever gem
+# - Monitoring des échecs de jobs
+# - Logique de retry pour les jobs échoués
+# - Mécanismes de verrouillage pour éviter les exécutions en double
+```
+
+### La méthode InTimeScope
+
+```ruby
+# C'est tout. Pas de jobs. Pas de colonne status. Pas d'infrastructure.
+user.points.in_time.sum(:amount)
+```
+
+**Une ligne. Zéro infrastructure. Toujours précis.**
+
+### Pourquoi ça fonctionne
+
+Les colonnes `start_at` et `end_at` SONT l'état. Pas besoin de colonne `status` car la comparaison temporelle se fait au moment de la requête :
+
+```ruby
+# Tout cela fonctionne sans traitement en arrière-plan :
+user.points.in_time                    # Actuellement valides
+user.points.in_time(1.month.from_now)  # Valides le mois prochain
+user.points.in_time(1.year.ago)        # Étaient valides l'année dernière (audit !)
+user.points.before_in_time             # En attente (pas encore actifs)
+user.points.after_in_time              # Expirés
+```
+
+### Ce que vous éliminez
+
+| Composant | Système basé sur Cron | InTimeScope |
+|-----------|------------------|-------------|
+| Bibliothèque de jobs en arrière-plan | Requis | **Non nécessaire** |
+| Redis/base de données pour les jobs | Requis | **Non nécessaire** |
+| Planificateur de jobs (cron) | Requis | **Non nécessaire** |
+| Colonne status | Requis | **Non nécessaire** |
+| Migration pour mettre à jour le status | Requis | **Non nécessaire** |
+| Monitoring des échecs de jobs | Requis | **Non nécessaire** |
+| Logique de retry | Requis | **Non nécessaire** |
+| Gestion des conditions de concurrence | Requis | **Non nécessaire** |
+
+### Bonus : voyage dans le temps gratuit
+
+Avec les systèmes basés sur cron, répondre à "Combien de points l'utilisateur X avait-il le 15 janvier ?" nécessite une journalisation d'audit complexe ou du event sourcing.
+
+Avec InTimeScope :
+
+```ruby
+user.points.in_time(Date.parse("2024-01-15").middle_of_day).sum(:amount)
+```
+
+**Les requêtes historiques fonctionnent directement.** Pas de tables supplémentaires. Pas d'event sourcing. Pas de complexité.
+
+## Schéma
+
+```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  # Quand les points deviennent utilisables
+      t.datetime :end_at, null: false    # Quand les points expirent
+      t.timestamps
+    end
+
+    add_index :points, [:user_id, :start_at, :end_at]
+  end
+end
+```
+
+## Modèles
+
+```ruby
+class Point < ApplicationRecord
+  belongs_to :user
+
+  # start_at et end_at sont tous deux requis (fenêtre temporelle complète)
+  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"
+
+  # Accorder des points bonus mensuels (pré-planifiés)
+  def grant_monthly_bonus(amount:, months_valid: 6)
+    points.create!(
+      amount: amount,
+      reason: "Monthly membership bonus",
+      start_at: 1.month.from_now,  # S'active le mois prochain
+      end_at: (1 + months_valid).months.from_now
+    )
+  end
+end
+```
+
+### La puissance de `has_many :in_time_points`
+
+Cette simple ligne débloque le **chargement anticipé sans N+1** pour les points valides :
+
+```ruby
+# Charger 100 utilisateurs avec leurs points valides en seulement 2 requêtes
+users = User.includes(:in_time_points).limit(100)
+
+users.each do |user|
+  # Pas de requêtes supplémentaires ! Déjà chargé.
+  total = user.in_time_points.sum(&:amount)
+  puts "#{user.name}: #{total} points"
+end
+```
+
+Sans cette association, vous auriez besoin de :
+
+```ruby
+# Problème N+1 : 1 requête pour les utilisateurs + 100 requêtes pour les points
+users = User.limit(100)
+users.each do |user|
+  total = user.points.in_time.sum(:amount)  # Requête par utilisateur !
+end
+```
+
+## Utilisation
+
+### Accorder des points avec différentes périodes de validité
+
+```ruby
+user = User.find(1)
+
+# Points immédiats (valides 1 an)
+user.points.create!(
+  amount: 100,
+  reason: "Welcome bonus",
+  start_at: Time.current,
+  end_at: 1.year.from_now
+)
+
+# Points pré-planifiés pour les membres 6 mois
+# Les points s'activent le mois prochain, valides 6 mois après activation
+user.grant_monthly_bonus(amount: 500, months_valid: 6)
+
+# Points de campagne (durée limitée)
+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
+)
+```
+
+### Requêter les points
+
+```ruby
+# Points valides actuellement
+user.in_time_member_points.sum(:amount)
+# => 100 (seul le bonus de bienvenue est actuellement actif)
+
+# Vérifier combien de points seront disponibles le mois prochain
+user.in_time_member_points(1.month.from_now).sum(:amount)
+# => 600 (bonus de bienvenue + bonus mensuel)
+
+# Points en attente (planifiés mais pas encore actifs)
+user.points.before_in_time.sum(:amount)
+# => 500 (bonus mensuel en attente d'activation)
+
+# Points expirés
+user.points.after_in_time.sum(:amount)
+
+# Tous les points invalides (en attente + expirés)
+user.points.out_of_time.sum(:amount)
+```
+
+### Requêtes pour tableau de bord admin
+
+```ruby
+# Audit historique : points valides à une date spécifique
+Point.in_time(Date.parse("2024-01-15").middle_of_day)
+     .group(:user_id)
+     .sum(:amount)
+```
+
+## Flux de bonus d'adhésion automatique
+
+Pour les membres premium 6 mois, vous pouvez configurer des bonus récurrents **sans cron, sans Sidekiq, sans Redis, sans monitoring** :
+
+```ruby
+# Quand l'utilisateur s'inscrit en premium, créer l'adhésion et tous les bonus de façon atomique
+ActiveRecord::Base.transaction do
+  membership = Membership.create!(user: user, plan: "premium_6_months")
+
+  # Pré-créer les 6 bonus mensuels à l'inscription
+  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  # Chaque bonus valide 6 mois
+    )
+  end
+end
+# => Crée l'adhésion + 6 enregistrements de points qui s'activeront mensuellement
+```
+
+## Pourquoi cette conception est supérieure
+
+### Exactitude
+
+- **Pas de conditions de concurrence** : Les jobs cron peuvent s'exécuter deux fois, sauter des exécutions ou se chevaucher. Les requêtes InTimeScope sont toujours déterministes.
+- **Pas de dérive temporelle** : Cron s'exécute à intervalles (chaque minute ? toutes les 5 minutes ?). InTimeScope est précis à la milliseconde.
+- **Pas de mises à jour perdues** : Les échecs de jobs peuvent laisser les points dans des états incorrects. InTimeScope n'a pas d'état à corrompre.
+
+### Simplicité
+
+- **Pas d'infrastructure** : Supprimez Sidekiq. Supprimez Redis. Supprimez le monitoring des jobs.
+- **Pas de migrations pour les changements de status** : Le temps EST le status. Pas besoin d'instructions `UPDATE`.
+- **Pas de débogage des logs de jobs** : Interrogez simplement la base de données pour voir exactement ce qui se passe.
+
+### Testabilité
+
+```ruby
+# Les tests basés sur cron sont pénibles :
+travel_to 1.month.from_now do
+  ActivatePointsJob.perform_now
+  ExpirePointsJob.perform_now
+  expect(user.points.active.sum(:amount)).to eq(500)
+end
+
+# Les tests InTimeScope sont triviaux :
+expect(user.points.in_time(1.month.from_now).sum(:amount)).to eq(500)
+```
+
+### Résumé
+
+| Aspect | Basé sur Cron | InTimeScope |
+|--------|-----------|-------------|
+| Infrastructure | Sidekiq + Redis + Cron | **Aucune** |
+| Activation des points | Job batch (différé) | **Instantané** |
+| Requêtes historiques | Impossible sans log d'audit | **Intégré** |
+| Précision temporelle | Minutes (intervalle cron) | **Millisecondes** |
+| Débogage | Logs de jobs + base de données | **Base de données uniquement** |
+| Tests | Voyage dans le temps + exécuter les jobs | **Juste une requête** |
+| Modes d'échec | Nombreux (échecs de jobs, conditions de concurrence) | **Aucun** |
+
+## Conseils
+
+1. **Utilisez des index de base de données** sur `[user_id, start_at, end_at]` pour des performances optimales.
+
+2. **Pré-accordez les points à l'inscription** au lieu de planifier des jobs cron.
+
+3. **Utilisez `in_time(time)` pour les audits** pour vérifier les soldes de points à n'importe quel moment historique.
+
+4. **Combinez avec les scopes inversés** pour construire des tableaux de bord admin affichant les points en attente/expirés.

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

@@ -0,0 +1,164 @@
+# Exemple d'historique des noms d'utilisateur
+
+Cet exemple montre comment gérer l'historique des noms d'utilisateur avec `in_time_scope`, vous permettant de requêter le nom d'un utilisateur à n'importe quel moment.
+
+Voir aussi : [spec/user_name_history_spec.rb](https://github.com/kyohah/in_time_scope/blob/main/spec/user_name_history_spec.rb)
+
+## Cas d'utilisation
+
+- Les utilisateurs peuvent changer leur nom d'affichage
+- Vous devez conserver un historique de tous les changements de nom
+- Vous voulez récupérer le nom qui était actif à un moment spécifique (ex : pour les logs d'audit, rapports historiques)
+
+## Schéma
+
+```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  # Quand ce nom est devenu actif
+      t.timestamps
+    end
+
+    add_index :user_name_histories, [:user_id, :start_at]
+  end
+end
+```
+
+## Modèles
+
+```ruby
+class UserNameHistory < ApplicationRecord
+  belongs_to :user
+  include InTimeScope
+
+  # Modèle début uniquement : chaque enregistrement est valide de start_at jusqu'au suivant
+  in_time_scope start_at: { null: false }, end_at: { column: nil }
+end
+
+class User < ApplicationRecord
+  has_many :user_name_histories
+
+  # Obtenir le nom actuel (dernier enregistrement qui a commencé)
+  has_one :current_name_history,
+          -> { latest_in_time(:user_id) },
+          class_name: "UserNameHistory"
+
+  # Méthode pratique pour le nom actuel
+  def current_name
+    current_name_history&.name
+  end
+
+  # Obtenir le nom à un moment spécifique
+  def name_at(time)
+    user_name_histories.in_time(time).order(start_at: :desc).first&.name
+  end
+end
+```
+
+## Utilisation
+
+### Créer l'historique des noms
+
+```ruby
+user = User.create!(email: "alice@example.com")
+
+# Nom initial
+UserNameHistory.create!(
+  user: user,
+  name: "Alice",
+  start_at: Time.parse("2024-01-01")
+)
+
+# Changement de nom
+UserNameHistory.create!(
+  user: user,
+  name: "Alice Smith",
+  start_at: Time.parse("2024-06-01")
+)
+
+# Autre changement de nom
+UserNameHistory.create!(
+  user: user,
+  name: "Alice Johnson",
+  start_at: Time.parse("2024-09-01")
+)
+```
+
+### Requêter les noms
+
+```ruby
+# Nom actuel (utilise has_one avec latest_in_time)
+user.current_name
+# => "Alice Johnson"
+
+# Nom à un moment spécifique
+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"
+```
+
+### Chargement anticipé efficace
+
+```ruby
+# Charger les utilisateurs avec leurs noms actuels (pas de N+1)
+users = User.includes(:current_name_history).limit(100)
+
+users.each do |user|
+  puts "#{user.email}: #{user.current_name_history&.name}"
+end
+```
+
+### Requêter les enregistrements actifs
+
+```ruby
+# Tous les enregistrements de noms actuellement actifs
+UserNameHistory.in_time
+# => Retourne le dernier enregistrement de nom pour chaque utilisateur
+
+# Enregistrements de noms qui étaient actifs à un moment spécifique
+UserNameHistory.in_time(Time.parse("2024-05-01"))
+
+# Enregistrements de noms pas encore commencés (planifiés pour le futur)
+UserNameHistory.before_in_time
+```
+
+## Comment fonctionne `latest_in_time`
+
+Le scope `latest_in_time(:user_id)` génère une sous-requête `NOT EXISTS` efficace :
+
+```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
+  )
+```
+
+Cela retourne uniquement l'enregistrement le plus récent par utilisateur qui était actif au moment donné, ce qui est parfait pour les associations `has_one`.
+
+## Conseils
+
+1. **Utilisez toujours `latest_in_time` avec `has_one`** - Cela garantit que vous obtenez exactement un enregistrement par clé étrangère.
+
+2. **Ajoutez un index composite** sur `[user_id, start_at]` pour des performances de requête optimales.
+
+3. **Utilisez `includes` pour le chargement anticipé** - Le pattern `NOT EXISTS` fonctionne efficacement avec le chargement anticipé de Rails.
+
+4. **Envisagez d'ajouter une contrainte d'unicité** sur `[user_id, start_at]` pour éviter les enregistrements en double au même moment.

data/docs/ja/SUMMARY.md

@@ -0,0 +1,5 @@
+# 目次
+
+- [はじめに](./index.md)
+- [有効期限付きポイントシステム](./point-system.md)
+- [ユーザー名履歴](./user-name-history.md)