Merge pull request #5426 from rubyforgood/3652-1-kits-to-items

3652 #1: kits to items

Author: awwaiid

.gitignore

@@ -89,3 +89,4 @@ out/
 
 .vscode/
 .aider*
+.claude

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: `[email protected]`, `[email protected]`, `[email protected]`.

app/controllers/items_controller.rb

@@ -11,7 +11,7 @@ def index
     @items = @items.active unless params[:include_inactive_items]
 
     @item_categories = current_organization.item_categories.includes(:items).order('name ASC')
-    @kits = current_organization.kits.includes(line_items: :item)
+    @kits = current_organization.kits.includes(item: {line_items: :item})
     @storages = current_organization.storage_locations.active.order(id: :asc)
 
     @include_inactive_items = params[:include_inactive_items]

app/controllers/kits_controller.rb

@@ -4,7 +4,7 @@ def show
   end
 
   def index
-    @kits = current_organization.kits.includes(:item, line_items: :item).class_filter(filter_params)
+    @kits = current_organization.kits.includes(item: {line_items: :item}).class_filter(filter_params)
     @inventory = View::Inventory.new(current_organization.id)
     unless params[:include_inactive_items]
       @kits = @kits.active
@@ -16,7 +16,8 @@ def new
     load_form_collections
 
     @kit = current_organization.kits.new
-    @kit.line_items.build
+    @kit.item = current_organization.items.new
+    @kit.item.line_items.build
   end
 
   def create
@@ -31,9 +32,12 @@ def create
         .map { |error| formatted_error_message(error) }
         .join(", ")
 
-      @kit = Kit.new(kit_params)
+      # Extract kit and item params separately since line_items belong to Item, not Kit
+      kit_only_params = kit_params.except(:line_items_attributes)
+      @kit = Kit.new(kit_only_params)
       load_form_collections
-      @kit.line_items.build if @kit.line_items.empty?
+      @kit.item ||= current_organization.items.new(kit_params.slice(:line_items_attributes))
+      @kit.item.line_items.build if @kit.item.line_items.empty?
 
       render :new
     end
@@ -87,12 +91,14 @@ def load_form_collections
   end
 
   def kit_params
-    params.require(:kit).permit(
+    kit_params = params.require(:kit).permit(
       :name,
       :visible_to_partners,
-      :value_in_dollars,
-      line_items_attributes: [:item_id, :quantity, :_destroy]
+      :value_in_dollars
     )
+    item_params = params.require(:item)
+      .permit(line_items_attributes: [:item_id, :quantity, :_destroy])
+    kit_params.to_h.merge(item_params.to_h)
   end
 
   def kit_adjustment_params

app/events/kit_allocate_event.rb

@@ -1,6 +1,6 @@
 class KitAllocateEvent < Event
   def self.event_line_items(kit, storage_location, quantity)
-    items = kit.line_items.map do |item|
+    items = kit.item.line_items.map do |item|
       EventTypes::EventLineItem.new(
         quantity: item.quantity * quantity,
         item_id: item.item_id,

app/events/kit_deallocate_event.rb

@@ -1,6 +1,6 @@
 class KitDeallocateEvent < Event
   def self.event_line_items(kit, storage_location, quantity)
-    items = kit.line_items.map do |item|
+    items = kit.item.line_items.map do |item|
       EventTypes::EventLineItem.new(
         quantity: item.quantity * quantity,
         item_id: item.item_id,

app/models/item.rb

@@ -27,6 +27,7 @@ class Item < ApplicationRecord
   include Filterable
   include Exportable
   include Valuable
+  include Itemizable
 
   after_initialize :set_default_distribution_quantity, if: :new_record?
   after_update :update_associated_kit_name, if: -> { kit.present? }
@@ -45,12 +46,13 @@ class Item < ApplicationRecord
   validates :on_hand_minimum_quantity, numericality: { greater_than_or_equal_to: 0 }
   validates :package_size, numericality: { greater_than_or_equal_to: 0 }, allow_blank: true
   validates :reporting_category, presence: true, unless: proc { |i| i.kit }
+  validate -> { line_items_quantity_is_at_least(1) }
 
-  has_many :line_items, dependent: :destroy
+  has_many :used_line_items, dependent: :destroy, class_name: "LineItem"
   has_many :inventory_items, dependent: :destroy
   has_many :barcode_items, as: :barcodeable, dependent: :destroy
-  has_many :donations, through: :line_items, source: :itemizable, source_type: "::Donation"
-  has_many :distributions, through: :line_items, source: :itemizable, source_type: "::Distribution"
+  has_many :donations, through: :used_line_items, source: :itemizable, source_type: "::Donation"
+  has_many :distributions, through: :used_line_items, source: :itemizable, source_type: "::Distribution"
   has_many :request_units, class_name: "ItemUnit", dependent: :destroy
 
   scope :active, -> { where(active: true) }
@@ -103,17 +105,17 @@ 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
-        .joins(:line_items)
+        .joins(item: :line_items)
         .where(line_items: { item_id: id}).any?
     end
   end
 
   def can_delete?(inventory = nil, kits = nil)
-    can_deactivate_or_delete?(inventory, kits) && line_items.none? && !barcode_count&.positive? && !in_request? && kit.blank?
+    can_deactivate_or_delete?(inventory, kits) && used_line_items.none? && !barcode_count&.positive? && !in_request? && kit.blank?
   end
 
   # @return [Boolean]

app/models/kit.rb

@@ -13,7 +13,6 @@
 #
 class Kit < ApplicationRecord
   has_paper_trail
-  include Itemizable
   include Filterable
   include Valuable
 
@@ -22,15 +21,11 @@ class Kit < ApplicationRecord
 
   scope :active, -> { where(active: true) }
   scope :alphabetized, -> { order(:name) }
-  scope :by_partner_key, ->(key) { joins(:items).where(items: { partner_key: key }) }
   scope :by_name, ->(name) { where("name ILIKE ?", "%#{name}%") }
 
   validates :name, presence: true
   validates :name, uniqueness: { scope: :organization }
 
-  validate :at_least_one_item
-  validate -> { line_items_quantity_is_at_least(1) }
-
   # @param inventory [View::Inventory]
   # @return [Boolean]
   def can_deactivate?(inventory = nil)
@@ -47,19 +42,11 @@ def deactivate
   # or deallocated, we are changing inventory for inactive items (which we don't allow).
   # @return [Boolean]
   def can_reactivate?
-    line_items.joins(:item).where(items: { active: false }).none?
+    item.line_items.joins(:item).where(items: { active: false }).none?
   end
 
   def reactivate
     update!(active: true)
     item.update!(active: true)
   end
-
-  private
-
-  def at_least_one_item
-    unless line_items.any?
-      errors.add(:base, 'At least one item is required')
-    end
-  end
 end

app/services/kit_create_service.rb

@@ -23,8 +23,13 @@ def call
 
     organization.transaction do
       # Create the Kit record
+      line_items = kit_params.delete(:line_items_attributes)
       @kit = Kit.new(kit_params_with_organization)
       @kit.save!
+      if line_items.blank?
+        @kit.errors.add(:base, 'At least one item is required')
+        raise ActiveRecord::RecordInvalid.new(@kit)
+      end
 
       # Find or create the BaseItem for all items housing kits
       item_housing_a_kit_base_item = KitCreateService.find_or_create_kit_base_item!
@@ -33,6 +38,7 @@ def call
       item_creation = ItemCreateService.new(
         organization_id: organization.id,
         item_params: {
+          line_items_attributes: line_items,
           name: kit.name,
           partner_key: item_housing_a_kit_base_item.partner_key,
           kit_id: kit.id
@@ -80,7 +86,9 @@ def valid?
   def kit_validation_errors
     return @kit_validation_errors if @kit_validation_errors
 
-    kit = Kit.new(kit_params_with_organization)
+    # Exclude line_items_attributes as they belong to the Item, not the Kit
+    kit_only_params = kit_params_with_organization.except(:line_items_attributes)
+    kit = Kit.new(kit_only_params)
     kit.valid?
 
     @kit_validation_errors = kit.errors

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|