source_monitor 0.2.0 → 0.3.0

data/.claude/skills/rails-architecture/reference/query-patterns.md

@@ -0,0 +1,342 @@
+# Query Object Patterns
+
+## Basic Query Structure
+
+```ruby
+# app/queries/[name]_query.rb
+class NameQuery
+  attr_reader :account
+
+  def initialize(account:)
+    @account = account
+  end
+
+  # @return [ActiveRecord::Relation<Model>]
+  def call
+    account.models
+      .where(conditions)
+      .order(created_at: :desc)
+  end
+end
+```
+
+## Query Categories
+
+### 1. Filter Queries
+
+Return filtered ActiveRecord relations:
+
+```ruby
+# app/queries/active_events_query.rb
+class ActiveEventsQuery
+  attr_reader :account
+
+  def initialize(account:)
+    @account = account
+  end
+
+  def call(date_range: nil)
+    scope = account.events.where(status: :active)
+    scope = scope.where(event_date: date_range) if date_range
+    scope.includes(:venue, :vendors).order(event_date: :asc)
+  end
+end
+```
+
+### 2. Aggregation Queries
+
+Return computed statistics:
+
+```ruby
+# app/queries/revenue_stats_query.rb
+class RevenueStatsQuery
+  attr_reader :account
+
+  def initialize(account:)
+    @account = account
+  end
+
+  def call(period: :month)
+    {
+      total: total_revenue,
+      by_period: revenue_by_period(period),
+      by_category: revenue_by_category,
+      growth_rate: calculate_growth
+    }
+  end
+
+  private
+
+  def total_revenue
+    account.orders.completed.sum(:total_cents)
+  end
+
+  def revenue_by_period(period)
+    group_clause = case period
+    when :day then "DATE(created_at)"
+    when :week then "DATE_TRUNC('week', created_at)"
+    when :month then "DATE_TRUNC('month', created_at)"
+    end
+
+    account.orders.completed
+      .group(Arel.sql(group_clause))
+      .sum(:total_cents)
+  end
+
+  def revenue_by_category
+    account.orders.completed
+      .joins(line_items: :product)
+      .group("products.category")
+      .sum(:total_cents)
+  end
+end
+```
+
+### 3. Dashboard Queries
+
+Multiple related metrics:
+
+```ruby
+# app/queries/dashboard_stats_query.rb
+class DashboardStatsQuery
+  attr_reader :user, :account
+
+  def initialize(user:)
+    @user = user
+    @account = user.account
+  end
+
+  def upcoming_events(limit: 5)
+    account.events
+      .where("event_date >= ?", Date.current)
+      .order(event_date: :asc)
+      .limit(limit)
+  end
+
+  def pending_tasks_count
+    account.tasks.pending.count
+  end
+
+  def leads_by_status
+    account.leads.group(:status).count
+  end
+
+  def recent_activity(limit: 10)
+    account.activities
+      .includes(:user, :trackable)
+      .order(created_at: :desc)
+      .limit(limit)
+  end
+end
+```
+
+### 4. Search Queries
+
+Full-text search with filters:
+
+```ruby
+# app/queries/vendor_search_query.rb
+class VendorSearchQuery
+  attr_reader :account
+
+  def initialize(account:)
+    @account = account
+  end
+
+  def call(term:, filters: {})
+    scope = account.vendors
+
+    scope = apply_search(scope, term) if term.present?
+    scope = apply_filters(scope, filters)
+    scope = apply_sorting(scope, filters[:sort])
+
+    scope.includes(:category, :reviews)
+  end
+
+  private
+
+  def apply_search(scope, term)
+    scope.where(
+      "name ILIKE :term OR description ILIKE :term",
+      term: "%#{sanitize_like(term)}%"
+    )
+  end
+
+  def apply_filters(scope, filters)
+    scope = scope.where(category_id: filters[:category]) if filters[:category]
+    scope = scope.where(active: true) if filters[:active_only]
+    scope = scope.where("rating >= ?", filters[:min_rating]) if filters[:min_rating]
+    scope
+  end
+
+  def apply_sorting(scope, sort)
+    case sort
+    when "name" then scope.order(name: :asc)
+    when "rating" then scope.order(rating: :desc)
+    when "recent" then scope.order(created_at: :desc)
+    else scope.order(name: :asc)
+    end
+  end
+
+  def sanitize_like(term)
+    term.gsub(/[%_]/) { |x| "\\#{x}" }
+  end
+end
+```
+
+### 5. Report Queries
+
+Complex data for exports:
+
+```ruby
+# app/queries/event_report_query.rb
+class EventReportQuery
+  attr_reader :account
+
+  def initialize(account:)
+    @account = account
+  end
+
+  def call(date_range:)
+    account.events
+      .where(event_date: date_range)
+      .includes(:venue, :vendors, :attendees)
+      .select(
+        "events.*",
+        "COUNT(DISTINCT attendees.id) as attendee_count",
+        "SUM(event_vendors.amount_cents) as total_vendor_cost"
+      )
+      .joins(:attendees, :event_vendors)
+      .group("events.id")
+      .order(event_date: :asc)
+  end
+end
+```
+
+## Performance Patterns
+
+### Eager Loading
+
+```ruby
+def call
+  account.events
+    .includes(:venue)                    # Belongs-to
+    .includes(:vendors)                  # Has-many through
+    .includes(attendees: :user)          # Nested
+    .preload(:documents)                 # Separate query
+    .eager_load(:primary_contact)        # LEFT JOIN
+end
+```
+
+### Batch Processing
+
+```ruby
+def process_all
+  account.events.find_each(batch_size: 100) do |event|
+    yield event
+  end
+end
+```
+
+### Subquery Optimization
+
+```ruby
+def call
+  # Use subquery instead of pluck for large datasets
+  active_vendor_ids = account.vendors.active.select(:id)
+
+  account.events
+    .where(vendor_id: active_vendor_ids)
+    .order(created_at: :desc)
+end
+```
+
+## Multi-Tenancy Patterns
+
+### Always Scope Through Account
+
+```ruby
+# GOOD
+def call
+  account.events.where(status: :active)
+end
+
+# BAD - Security risk!
+def call
+  Event.where(account_id: account.id, status: :active)
+end
+```
+
+### Test Isolation
+
+```ruby
+# test/queries/active_events_query_test.rb
+require "test_helper"
+
+class ActiveEventsQueryTest < ActiveSupport::TestCase
+  test "only returns events for the account" do
+    account = accounts(:one)
+    our_event = events(:one) # belongs to accounts(:one)
+    their_event = events(:other_account_event)
+
+    result = ActiveEventsQuery.new(account: account).call
+    assert_includes result, our_event
+    assert_not_includes result, their_event
+  end
+end
+```
+
+## Composition Patterns
+
+### Query Chaining
+
+```ruby
+# Queries return relations, enabling chaining
+events = ActiveEventsQuery.new(account: account).call
+upcoming = events.where("event_date > ?", Date.current)
+paginated = upcoming.page(params[:page]).per(20)
+```
+
+### Query Composition
+
+```ruby
+class ComplexReportQuery
+  def initialize(account:)
+    @events_query = ActiveEventsQuery.new(account: account)
+    @revenue_query = RevenueStatsQuery.new(account: account)
+  end
+
+  def call(date_range:)
+    {
+      events: @events_query.call(date_range: date_range),
+      revenue: @revenue_query.call
+    }
+  end
+end
+```
+
+## Usage in Controllers
+
+```ruby
+class EventsController < ApplicationController
+  def index
+    @events = ActiveEventsQuery.new(account: current_account)
+      .call
+      .page(params[:page])
+  end
+
+  def dashboard
+    @stats = DashboardStatsQuery.new(user: current_user)
+  end
+end
+```
+
+## Checklist
+
+- [ ] Constructor accepts `account:` or `user:`
+- [ ] Always scoped through account (multi-tenant)
+- [ ] Return type documented (`@return`)
+- [ ] Uses `.includes()` to prevent N+1
+- [ ] Search terms sanitized
+- [ ] Spec tests tenant isolation
+- [ ] Complex queries explain their purpose

data/.claude/skills/rails-architecture/reference/service-patterns.md

@@ -0,0 +1,286 @@
+# Service Object Patterns
+
+## Basic Service Structure
+
+```ruby
+# app/services/[namespace]/[verb]_service.rb
+module Namespace
+  class VerbService
+    def initialize(dependencies = {})
+      @dependency = dependencies[:dependency] || DefaultDependency.new
+    end
+
+    def call(params)
+      validate_input(params)
+      perform_operation(params)
+      success(result)
+    rescue StandardError => e
+      failure(e.message)
+    end
+
+    private
+
+    attr_reader :dependency
+
+    def success(data)
+      Result.new(success: true, data: data)
+    end
+
+    def failure(error, code = :unknown)
+      Result.new(success: false, error: error, code: code)
+    end
+  end
+end
+```
+
+## Service Categories
+
+### 1. Command Services (Write Operations)
+
+Single action that changes state:
+
+```ruby
+# app/services/orders/create_service.rb
+module Orders
+  class CreateService
+    def call(user:, items:)
+      order = nil
+
+      ActiveRecord::Base.transaction do
+        order = user.orders.create!(status: :pending)
+        create_line_items(order, items)
+        reserve_inventory(items)
+      end
+
+      OrderMailer.confirmation(order).deliver_later
+      success(order)
+    rescue ActiveRecord::RecordInvalid => e
+      failure(e.message, :validation_error)
+    end
+  end
+end
+```
+
+### 2. Query Services (Read Operations)
+
+Complex reads that don't fit in Query Objects:
+
+```ruby
+# app/services/reports/generate_service.rb
+module Reports
+  class GenerateService
+    def call(account:, date_range:, format:)
+      data = gather_data(account, date_range)
+      formatted = format_data(data, format)
+      success(formatted)
+    end
+
+    private
+
+    def gather_data(account, range)
+      {
+        events: EventStatsQuery.new(account: account).call(range),
+        revenue: RevenueQuery.new(account: account).call(range),
+        leads: LeadConversionQuery.new(account: account).call(range)
+      }
+    end
+  end
+end
+```
+
+### 3. Integration Services (External APIs)
+
+Wrap external service calls:
+
+```ruby
+# app/services/payments/charge_service.rb
+module Payments
+  class ChargeService
+    def initialize(gateway: StripeGateway.new)
+      @gateway = gateway
+    end
+
+    def call(order:, payment_method_id:)
+      charge = gateway.charge(
+        amount: order.total_cents,
+        currency: "eur",
+        payment_method_id: payment_method_id
+      )
+
+      order.update!(
+        payment_status: :paid,
+        payment_reference: charge.id
+      )
+
+      success(charge)
+    rescue PaymentGateway::CardDeclined => e
+      failure(e.message, :card_declined)
+    rescue PaymentGateway::Error => e
+      failure(e.message, :payment_error)
+    end
+
+    private
+
+    attr_reader :gateway
+  end
+end
+```
+
+### 4. Orchestrator Services (Complex Workflows)
+
+Coordinate multiple services:
+
+```ruby
+# app/services/onboarding/complete_service.rb
+module Onboarding
+  class CompleteService
+    def call(user:, params:)
+      results = []
+
+      results << Accounts::SetupService.new.call(user: user, params: params[:account])
+      return results.last if results.last.failure?
+
+      results << Preferences::ConfigureService.new.call(user: user, params: params[:preferences])
+      return results.last if results.last.failure?
+
+      results << Notifications::WelcomeService.new.call(user: user)
+
+      user.update!(onboarding_completed_at: Time.current)
+      success(user)
+    end
+  end
+end
+```
+
+## Dependency Injection Patterns
+
+### Constructor Injection (Preferred)
+
+```ruby
+class OrderService
+  def initialize(
+    inventory: InventoryService.new,
+    payment: PaymentService.new,
+    notifier: NotificationService.new
+  )
+    @inventory = inventory
+    @payment = payment
+    @notifier = notifier
+  end
+end
+```
+
+### Testing with Mocks
+
+```ruby
+# test/services/orders/create_service_test.rb
+require "test_helper"
+
+class Orders::CreateServiceTest < ActiveSupport::TestCase
+  setup do
+    @inventory = Minitest::Mock.new
+    @payment = Minitest::Mock.new
+    @service = Orders::CreateService.new(inventory: @inventory, payment: @payment)
+    @user = users(:one)
+  end
+
+  test "checks inventory before charging" do
+    @inventory.expect :available?, true, [Array]
+    @inventory.expect :reserve, true, [Array]
+    @payment.expect :charge, true, [Hash]
+
+    @service.call(user: @user, items: [{ product_id: products(:widget).id, quantity: 1 }])
+
+    @inventory.verify
+    @payment.verify
+  end
+end
+```
+
+## Error Handling Patterns
+
+### Typed Error Codes
+
+```ruby
+module Orders
+  class CreateService
+    ERROR_CODES = {
+      empty_cart: "No items in cart",
+      insufficient_inventory: "Item out of stock",
+      payment_failed: "Payment could not be processed",
+      validation_failed: "Invalid order data"
+    }.freeze
+
+    def call(params)
+      return failure(:empty_cart) if params[:items].empty?
+      return failure(:insufficient_inventory) unless inventory_available?(params[:items])
+
+      order = create_order(params)
+      success(order)
+    rescue PaymentError
+      failure(:payment_failed)
+    rescue ActiveRecord::RecordInvalid => e
+      failure(:validation_failed, e.message)
+    end
+
+    private
+
+    def failure(code, details = nil)
+      message = ERROR_CODES[code]
+      message = "#{message}: #{details}" if details
+      Result.new(success: false, error: message, code: code)
+    end
+  end
+end
+```
+
+### Controller Error Handling
+
+```ruby
+class OrdersController < ApplicationController
+  def create
+    result = Orders::CreateService.new.call(order_params)
+
+    if result.success?
+      redirect_to result.data, notice: t(".success")
+    else
+      handle_service_error(result)
+    end
+  end
+
+  private
+
+  def handle_service_error(result)
+    case result.code
+    when :empty_cart
+      redirect_to cart_path, alert: result.error
+    when :insufficient_inventory
+      flash.now[:alert] = result.error
+      render :new, status: :unprocessable_entity
+    when :payment_failed
+      redirect_to checkout_path, alert: result.error
+    else
+      flash.now[:alert] = result.error
+      render :new, status: :unprocessable_entity
+    end
+  end
+end
+```
+
+## Service Naming Conventions
+
+| Pattern | Example | Use Case |
+|---------|---------|----------|
+| `VerbNounService` | `CreateOrderService` | Single action |
+| `Namespace::VerbService` | `Orders::CreateService` | Namespaced (preferred) |
+| `NounVerbService` | `OrderCreatorService` | Alternative style |
+
+## Checklist
+
+- [ ] Single public method (`#call`)
+- [ ] Returns Result object
+- [ ] Dependencies injected via constructor
+- [ ] Errors caught and wrapped
+- [ ] Transaction for multi-model writes
+- [ ] Typed error codes for handling
+- [ ] Spec covers success and failure paths