CR updates (thanks Claude for the spec fix)

dorner · dorner · commit 93c9d0c02b76 · 2026-02-08T10:08:22.000-05:00
diff --git a/.gitignore b/.gitignore
@@ -89,3 +89,4 @@ out/
 
 .vscode/
 .aider*
+.claude
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,99 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Human Essentials is a Ruby on Rails inventory management system for diaper banks and essentials banks. It's a Ruby for Good project serving 200+ non-profit organizations. The app manages donations, purchases, distributions, inventory, partners, and requests for essential items.
+
+## Common Commands
+
+### Development
+```bash
+bin/setup          # First-time setup (installs gems, creates DB, seeds)
+bin/start          # Starts Rails server (port 3000) + Delayed Job worker
+```
+
+### Testing
+```bash
+bundle exec rspec                              # Run full test suite
+bundle exec rspec spec/models/item_spec.rb     # Run a single test file
+bundle exec rspec spec/models/item_spec.rb:42  # Run a single test at line
+bundle exec rspec spec/models/                 # Run a directory of tests
+```
+
+CI splits tests into two workflows: `rspec` (unit tests, excludes system/request specs) and `rspec-system` (system and request specs only, 6 parallel nodes). System tests use Capybara with Cuprite (headless Chrome).
+
+### Linting
+```bash
+bundle exec rubocop                  # Ruby linter (Standard-based config)
+bundle exec erb_lint --lint-all      # ERB template linter
+bundle exec brakeman                 # Security scanner
+```
+
+### Database
+```bash
+bundle exec rake db:migrate
+bundle exec rake db:seed
+bundle exec rake db:reset            # Drop + create + migrate + seed
+```
+
+## Architecture
+
+### Multi-Tenancy
+Nearly all data is scoped to an `Organization`. Most models `belong_to :organization` and queries should always scope by organization context. The current user's organization is the primary tenant boundary.
+
+### Roles (Rolify)
+Four roles defined in `Role`: `ORG_USER`, `ORG_ADMIN`, `SUPER_ADMIN`, `PARTNER`. Roles are polymorphic and scoped to a resource (usually an Organization). Authentication is via Devise.
+
+### Event Sourcing for Inventory
+Inventory is **not** tracked via simple column updates. Instead, it uses an event sourcing pattern:
+
+- **`Event`** (STI base model) stores all inventory-affecting actions as JSONB events
+- Subclasses: `DonationEvent`, `DistributionEvent`, `PurchaseEvent`, `TransferEvent`, `AdjustmentEvent`, `AuditEvent`, `KitAllocateEvent`, `SnapshotEvent`, etc.
+- **`InventoryAggregate`** replays events to compute current inventory state. It finds the most recent `SnapshotEvent` and replays subsequent events
+- **`EventTypes::Inventory`** is the in-memory inventory representation built from events
+- When creating/updating donations, distributions, purchases, transfers, or adjustments, the corresponding service creates an Event, and `Event#validate_inventory` replays all events to verify consistency
+
+This means: to check inventory levels, use `InventoryAggregate.inventory_for(organization_id)`, not direct DB queries on quantity columns.
+
+### Service Objects
+Business logic lives in service classes (`app/services/`), not controllers. Pattern: `{Model}{Action}Service` (e.g., `DistributionCreateService`, `DonationDestroyService`). Controllers are thin and delegate to services.
+
+### Key Models
+- **Item**: Individual item types (diapers, wipes, etc.) belonging to an Organization. Maps to a `BaseItem` (system-wide template) via `partner_key`.
+- **Kit**: A bundle of items. Kits contain line items referencing Items.
+- **StorageLocation**: Where inventory is physically stored. Inventory quantities are per storage location.
+- **Distribution**: Items sent to a Partner. **Donation/Purchase**: Items coming in. **Transfer**: Items between storage locations. **Adjustment**: Manual inventory corrections.
+- **Partner**: Organizations that receive distributions. Partners have their own portal (`/partners/*` routes) and users.
+- **Request**: Partner requests for items, which can become Distributions.
+
+### Routes Structure
+- `/` - Bank user dashboard and resources (distributions, donations, etc.)
+- `/partners/*` - Partner-facing portal (separate namespace)
+- `/admin/*` - Super admin management
+- `/reports/*` - Reporting endpoints
+
+### Query Objects
+Complex queries are extracted into `app/queries/` (e.g., `ItemsInQuery`, `LowInventoryQuery`).
+
+### Frontend
+Bootstrap 5.2, Turbo Rails, Stimulus.js, ImportMap (no Webpack/bundler). JavaScript controllers live in `app/javascript/`.
+
+### Background Jobs
+Delayed Job for async processing (emails, etc.). Clockwork (`clock.rb`) for scheduled tasks (caching historical data, reminder emails, DB backups).
+
+### Feature Flags
+Flipper is available for feature flags, accessible at `/flipper` (auth required).
+
+## Testing Conventions
+
+- RSpec with FactoryBot. Factories are in `spec/factories/`.
+- **Setting up inventory in tests**: Use `TestInventory.create_inventory(organization, { storage_location_id => [[item_id, quantity], ...] })` from `spec/inventory.rb`. There's also a `setup_storage_location` helper in `spec/support/inventory_assistant.rb`.
+- System tests use Capybara with Cuprite driver. Failed screenshots go to `tmp/screenshots/` and `tmp/capybara/`.
+- Models use `has_paper_trail` for audit trails and `Discard` for soft deletes (not `destroy`).
+- The `Filterable` concern provides `class_filter` for scope-based filtering on index actions.
+
+## Dev Credentials
+
+All passwords are `password!`. Key accounts: `superadmin@example.com`, `org_admin1@example.com`, `user_1@example.com`.
diff --git a/app/models/item.rb b/app/models/item.rb
@@ -105,7 +105,7 @@ def in_request?
 
   def is_in_kit?(kits = nil)
     if kits
-      kits.any? { |k| k.line_items.map(&:item_id).include?(id) }
+      kits.any? { |k| k.item.line_items.map(&:item_id).include?(id) }
     else
       organization.kits
         .active
diff --git a/app/models/kit.rb b/app/models/kit.rb
@@ -13,7 +13,6 @@
 #
 class Kit < ApplicationRecord
   has_paper_trail
-  include Itemizable
   include Filterable
   include Valuable
 
diff --git a/app/services/reports/adult_incontinence_report_service.rb b/app/services/reports/adult_incontinence_report_service.rb
@@ -103,13 +103,13 @@ def distributed_adult_incontinence_items_from_kits
         FROM distributions 
         INNER JOIN line_items ON line_items.itemizable_type = 'Distribution' AND line_items.itemizable_id = distributions.id 
         INNER JOIN items ON items.id = line_items.item_id 
-        INNER JOIN kits ON kits.id = items.kit_id 
-        INNER JOIN line_items AS kit_line_items ON kits.id = kit_line_items.itemizable_id
+        INNER JOIN line_items AS kit_line_items ON items.id = kit_line_items.itemizable_id
         INNER JOIN items AS kit_items ON kit_items.id = kit_line_items.item_id
         WHERE distributions.organization_id = ?
           AND EXTRACT(year FROM issued_at) = ?
           AND kit_items.reporting_category = 'adult_incontinence'
-          AND kit_line_items.itemizable_type = 'Kit';
+          AND items.kit_id IS NOT NULL
+          AND kit_line_items.itemizable_type = 'Item';
       SQL
 
       sanitized_sql = ActiveRecord::Base.send(:sanitize_sql_array, [sql_query, organization_id, year])
@@ -144,7 +144,7 @@ def distributed_kits_for_year
 
     def total_distributed_kits_containing_adult_incontinence_items_per_month
       kits = Kit.where(id: distributed_kits_for_year).select do |kit|
-        kit.items.adult_incontinence.exists?
+        kit.item.items.adult_incontinence.exists?
       end
 
       total_assisted_adults = kits.sum do |kit|
diff --git a/spec/services/reports/adult_incontinence_report_service_spec.rb b/spec/services/reports/adult_incontinence_report_service_spec.rb
@@ -40,26 +40,22 @@
         adult_incontinence_item = organization.items.adult_incontinence.first
         non_adult_incontinence_item = organization.items.where.not(id: organization.items.adult_incontinence).first
 
-        # kits
-        adult_incontinence_kit_item_1 = create(:item, name: "Adult Briefs (Medium)", reporting_category: "adult_incontinence", distribution_quantity: 1)
-        adult_incontinence_kit_item_2 = create(:item, name: "Adult Briefs (Large)", reporting_category: "adult_incontinence", distribution_quantity: 1)
-        adult_incontinence_kit_item_3 = create(:item, name: "Adult Briefs (Small)", reporting_category: "adult_incontinence", distribution_quantity: 1)
-        non_adult_incontinence_kit_item = create(:item, name: "Baby Wipes", reporting_category: "other")
-
-        donation_1 = create(:donation)
-        donation_2 = create(:donation)
-        donation_3 = create(:donation)
-        donation_4 = create(:donation)
-
-        line_item_1 = LineItem.create!(item: adult_incontinence_kit_item_1, itemizable_id: donation_1.id, itemizable_type: "Donation", quantity: 5)
-        line_item_2 = LineItem.create!(item: adult_incontinence_kit_item_2, itemizable_id: donation_2.id, itemizable_type: "Donation", quantity: 5)
-        line_item_4 = LineItem.create!(item: adult_incontinence_kit_item_3, itemizable_id: donation_4.id, itemizable_type: "Donation", quantity: 5)
-        line_item_3 = LineItem.create!(item: non_adult_incontinence_kit_item, itemizable_id: donation_3.id, itemizable_type: "Donation", quantity: 5)
-
-        @kit_1 = create(:kit, line_items: [line_item_1], organization: organization, item: adult_incontinence_kit_item_1)
-        @kit_2 = create(:kit, line_items: [line_item_2], organization: organization, item: adult_incontinence_kit_item_2)
-        @kit_4 = create(:kit, line_items: [line_item_4], organization: organization, item: adult_incontinence_kit_item_3)
-        @kit_3 = create(:kit, line_items: [line_item_3], organization: organization, item: non_adult_incontinence_kit_item)
+        # kit items (each item represents a kit and contains itself as a component)
+        adult_incontinence_kit_item_1 = create(:item, name: "Adult Briefs (Medium)", reporting_category: "adult_incontinence", distribution_quantity: 1, organization: organization)
+        adult_incontinence_kit_item_2 = create(:item, name: "Adult Briefs (Large)", reporting_category: "adult_incontinence", distribution_quantity: 1, organization: organization)
+        adult_incontinence_kit_item_3 = create(:item, name: "Adult Briefs (Small)", reporting_category: "adult_incontinence", distribution_quantity: 1, organization: organization)
+        non_adult_incontinence_kit_item = create(:item, name: "Baby Wipes", reporting_category: "other", organization: organization)
+
+        # Add component line items to each kit item
+        adult_incontinence_kit_item_1.line_items.create!(item: adult_incontinence_kit_item_1, quantity: 5)
+        adult_incontinence_kit_item_2.line_items.create!(item: adult_incontinence_kit_item_2, quantity: 5)
+        adult_incontinence_kit_item_3.line_items.create!(item: adult_incontinence_kit_item_3, quantity: 5)
+        non_adult_incontinence_kit_item.line_items.create!(item: non_adult_incontinence_kit_item, quantity: 5)
+
+        @kit_1 = create(:kit, organization: organization, item: adult_incontinence_kit_item_1)
+        @kit_2 = create(:kit, organization: organization, item: adult_incontinence_kit_item_2)
+        @kit_4 = create(:kit, organization: organization, item: adult_incontinence_kit_item_3)
+        @kit_3 = create(:kit, organization: organization, item: non_adult_incontinence_kit_item)
 
         # kit distributions
         kit_distribution_1 = create(:distribution, organization: organization, issued_at: within_time)
@@ -68,11 +64,11 @@
         # wipes distribution
         kit_distribution_3 = create(:distribution, organization: organization, issued_at: within_time)
 
-        create(:line_item, :distribution, quantity: 100, item: @kit_1.line_items.first.item, itemizable: kit_distribution_1)
-        create(:line_item, :distribution, quantity: 100, item: @kit_2.line_items.first.item, itemizable: kit_distribution_2)
-        create(:line_item, :distribution, quantity: 100, item: @kit_4.line_items.first.item, itemizable: kit_distribution_4)
+        create(:line_item, :distribution, quantity: 100, item: @kit_1.item, itemizable: kit_distribution_1)
+        create(:line_item, :distribution, quantity: 100, item: @kit_2.item, itemizable: kit_distribution_2)
+        create(:line_item, :distribution, quantity: 100, item: @kit_4.item, itemizable: kit_distribution_4)
         # wipes kit no ai items
-        create(:line_item, :distribution, quantity: 100, item: @kit_3.line_items.first.item, itemizable: kit_distribution_3)
+        create(:line_item, :distribution, quantity: 100, item: @kit_3.item, itemizable: kit_distribution_3)
         # We will create data both within and outside our date range, and both adult_incontinence and non adult_incontinence.
         # Spec will ensure that only the required data is included.
 

Original file line number	Diff line number	Diff line change
`@@ -89,3 +89,4 @@ out/`
`89`	`89`
`90`	`90`	`.vscode/`
`91`	`91`	`.aider*`
	`92`	`+.claude`
Original file line number	Diff line number	Diff line change
`@@ -13,7 +13,6 @@`
`13`	`13`	`#`
`14`	`14`	`class Kit < ApplicationRecord`
`15`	`15`	`has_paper_trail`
`16`		`- include Itemizable`
`17`	`16`	`include Filterable`
`18`	`17`	`include Valuable`
`19`	`18`