dscf-credit 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0c02d9169a31706be543d781e69d56a1d0bda57524ccde6c016acfe75ac42ecf
-  data.tar.gz: 55258ca56dd7e93305b82002bfc591946d0f48f5b06469ac5fa5507e100c3e37
+  metadata.gz: 6914417c9552b795ef7f98f17f2ffbd9854c52230e2a7dcc972e2f62d48e43f1
+  data.tar.gz: 27aa925e0fa5dbe419c9df8f54d77c0a03b94101e81c9a61ce3daeddac1bd0a6
 SHA512:
-  metadata.gz: 57e3868b428a74c8b9b0cbf10d2b4126f28e0ebf0fdef328a82b4827fc9d06627a1e89709b54a6a361ab888e679f42d903a826ad98da6863cea871ce69c415b6
-  data.tar.gz: 7c77eaf42cfe6e0c28e3465834a52a7c410460f35fb3cd443e9b211bac50a671ecab24ad4dac1d1efa5e49987d3e3a7e43a4ddd557d8bd6f545953ac33d89b3b
+  metadata.gz: c7f0f12531ba3b30ec55c527f0091bd49bbb4606218a6ddbe03d45793c16a10d22e02258f6a3ea821fde1812c386fafe3f98b64590c9c074960c4cc22c0d4883
+  data.tar.gz: ac5a855d4322ba647a1c9439b32600eaf736253dc6397ed5eb333339e9bd901550f73fe326c4a24e87a1fd77b70cdde9558fd41bb146c7bdd779602703c18e41

data/app/controllers/concerns/dscf/core/copilot-instructions.md

@@ -0,0 +1,683 @@
+# AI Coding Assistant Guidelines for DSCF Credit Engine
+
+## Project Overview
+
+This is `dscf-credit`, a Rails Engine for credit scoring and loan management. It's part of the Digital Supply Chain Finance (DSCF) platform, built as a modular engine that depends on `dscf-core` for shared functionality.
+
+## Architecture Patterns
+
+### Rails Engine Structure
+
+- **Isolated namespace**: All models/controllers under `Dscf::Credit::*`
+- **Engine configuration**: Located in `lib/dscf/credit/engine.rb` with API-only config
+- **Dependency**: Inherits authentication, JSON responses, and common patterns from `dscf-core`
+
+### Model Patterns
+
+- **Base class**: All models inherit from `Dscf::Credit::ApplicationRecord`
+- **Table naming**: Prefixed with `dscf_credit_` (e.g., `dscf_credit_loans`)
+- **Polymorphic relationships**: Use `*_type` and `*_id` for flexible associations (e.g., `backer`, `reviewed_by`)
+- **Ransack integration**: Always implement `ransackable_attributes` and `ransackable_associations`
+- **Status enums**: Use string enums for status fields (e.g., `pending`, `approved`, `rejected`)
+
+### Controller Patterns
+
+- **Base**: Inherit from `Dscf::Credit::ApplicationController`
+- **Includes**: Use `Dscf::Core::Common` for standard CRUD patterns
+- **Required methods**: Implement `model_params`, `eager_loaded_associations`, `allowed_order_columns`, `default_serializer_includes`
+- **Reviewable workflows**: Include `Dscf::Core::ReviewableController` for approval workflows
+
+### External Dependencies from dscf-core
+
+- **Authentication**: `Dscf::Core::Authenticatable` provides Bearer token auth with `current_user` access
+- **JSON Response**: `Dscf::Core::JsonResponse` already included in `ApplicationController` - provides `render_success`/`render_error`
+- **CRUD Operations**: `Dscf::Core::Common` provides standard index/show/create/update with pagination
+- **Filtering**: `Dscf::Core::Filterable` enables Ransack-based filtering (requires `ransackable_*` methods)
+- **Pagination**: Built-in pagination with `page`, `per_page`, `order_by`, `order_direction` params
+- **I18n Integration**: Automatic message resolution using `{model}.{success|errors}.{action}` pattern
+
+### Service Patterns
+
+- **Location**: Place in `app/services/dscf/credit/`
+- **Naming**: Use `*Service` suffix (e.g., `FacilitatorCreationService`)
+- **Structure**: Accept dependencies in constructor, provide public methods for operations
+- **Transactions**: Wrap complex operations in `ActiveRecord::Base.transaction`
+
+## Development Workflows
+
+### Reviewable System (Core Feature)
+
+The engine's primary feature is the `Dscf::Core::ReviewableController` system for approval workflows:
+
+#### DSCF Review Workflow Setup
+
+**Step 1: Include the Concerns**
+
+```ruby
+# app/controllers/your_controller.rb
+module YourEngine
+  class YourController < ApplicationController
+    include Dscf::Core::Common                # ✅ For CRUD operations
+    include Dscf::Core::ReviewableController  # ✅ For review workflow
+
+    # Your existing controller code...
+  end
+end
+
+# app/models/your_model.rb
+module YourEngine
+  class YourModel < ApplicationRecord
+    include Dscf::Core::ReviewableModel  # ✅ For review associations
+
+    # Your existing model code...
+  end
+end
+```
+
+**Step 2: Add Required Controller Methods**
+
+```ruby
+# app/controllers/your_controller.rb
+class YourController < ApplicationController
+  include Dscf::Core::Common
+  include Dscf::Core::ReviewableController
+
+  private
+
+  # ✅ REQUIRED: Add reviews with user_profile to eager loading
+  def eager_loaded_associations
+    [
+      :your_associations,
+      reviews: { reviewed_by: :user_profile }  # ← ADD THIS
+    ]
+  end
+
+  # ✅ REQUIRED: Add reviews to serializer includes
+  def default_serializer_includes
+    {
+      index: [
+        :your_associations,
+        reviews: { reviewed_by: :user_profile }  # ← ADD THIS
+      ],
+      show: [
+        :your_associations,
+        reviews: { reviewed_by: :user_profile }  # ← ADD THIS
+      ],
+      create: [],
+      update: [:your_associations]
+    }
+  end
+
+  # ✅ REQUIRED: Your model params
+  def model_params
+    params.require(:your_model).permit(:field1, :field2, :field3)
+  end
+
+  # ✅ REQUIRED: Allowed order columns
+  def allowed_order_columns
+    %w[id name created_at updated_at]
+  end
+end
+```
+
+dont forget to add the serializer
+
+```ruby
+# app/serializers/your_model_serializer.rb
+class YourModelSerializer < ActiveModel::Serializer
+  attributes :id, :field1, :field2, :field3
+
+  # ✅ REQUIRED: Add reviews to serializer
+  has_many :reviews, serializer: ReviewSerializer
+end
+```
+
+**Step 3: Update Model Ransackable Associations**
+
+```ruby
+# app/models/your_model.rb
+class YourModel < ApplicationRecord
+  include Dscf::Core::ReviewableModel
+
+  # ✅ REQUIRED: Add reviews to ransackable associations
+  def self.ransackable_associations(auth_object = nil)
+    %w[your_associations reviews]  # ← ADD 'reviews'
+  end
+end
+```
+
+**Step 4: Add Routes for Review Actions**
+
+For Zero-Config (Default Actions Only):
+
+```ruby
+# config/routes.rb
+resources :your_resources do
+  member do
+    patch :approve
+    patch :reject
+    patch :request_modification
+    patch :resubmit
+  end
+end
+```
+
+For Custom Actions:
+
+```ruby
+# config/routes.rb
+resources :your_resources do
+  member do
+    # Zero-config default actions (always available)
+    patch :approve
+    patch :reject
+    patch :request_modification
+    patch :resubmit
+
+    # Your custom actions (if you define custom reviewable_context)
+    patch :start_review      # ← ADD CUSTOM ACTIONS
+    patch :escalate         # ← ADD CUSTOM ACTIONS
+    patch :your_custom_action
+  end
+end
+```
+
+**Step 5: Add I18n Messages**
+
+For Default Actions (Zero-Config):
+
+```yaml
+# config/locales/en.yml
+en:
+  your_model: # ← Replace with your model name (lowercase, underscore)
+    success:
+      # Default actions (always needed)
+      approve: "Your model approved successfully"
+      reject: "Your model rejected successfully"
+      request_modification: "Modification requested for your model successfully"
+      resubmit: "Your model resubmitted successfully"
+    errors:
+      # Default actions (always needed)
+      approve: "Failed to approve your model"
+      reject: "Failed to reject your model"
+      request_modification: "Failed to request modification for your model"
+      resubmit: "Failed to resubmit your model"
+```
+
+For Custom Actions and Contexts:
+
+```yaml
+# config/locales/en.yml
+en:
+  your_model:
+    success:
+      # Default actions
+      approve: "Your model approved successfully"
+      reject: "Your model rejected successfully"
+      request_modification: "Modification requested successfully"
+      resubmit: "Your model resubmitted successfully"
+
+      # ✅ ADD: Custom actions based on your reviewable_context
+      start_review: "Review started for your model successfully"
+      escalate: "Your model escalated successfully"
+      your_custom_action: "Custom action completed successfully"
+
+    errors:
+      # Default actions
+      approve: "Failed to approve your model"
+      reject: "Failed to reject your model"
+      request_modification: "Failed to request modification"
+      resubmit: "Failed to resubmit your model"
+
+      # ✅ ADD: Custom actions based on your reviewable_context
+      start_review: "Failed to start review for your model"
+      escalate: "Failed to escalate your model"
+      your_custom_action: "Failed to complete custom action"
+```
+
+#### Zero-Config Default Context
+
+Including `Dscf::Core::ReviewableController` automatically provides default actions:
+
+- `approve` (pending → approved)
+- `reject` (pending → rejected, requires feedback)
+- `request_modification` (pending → modify, requires feedback)
+- `resubmit` (modify → pending, can update model)
+
+#### Custom Contexts
+
+Define custom review workflows with `reviewable_context`:
+
+```ruby
+# Multiple contexts supported
+reviewable_context :compliance,
+  statuses: %w[pending_review verified non_compliant needs_documents],
+  initial_status: "pending_review",
+  transitions: {
+    "pending_review" => %w[verified non_compliant needs_documents],
+    "needs_documents" => %w[pending_review]
+  },
+  actions: {
+    verify: { status: "verified" },
+    mark_non_compliant: { status: "non_compliant", require_feedback: true },
+    request_documents: { status: "needs_documents", require_feedback: true },
+    resubmit: { status: "pending_review", update_model: true }
+  }
+```
+
+#### API Endpoints and Context Switching
+
+- Default context: `/banks/123/approve`
+- Custom context: `/banks/123/verify?context=compliance`
+- Feedback structure: `{ "review_feedback": { "message": "...", "field": "..." } }`
+
+#### Required I18n Messages
+
+Auto-resolves using pattern: `{model}.{success|errors}.{action}`
+
+```yaml
+bank:
+  success:
+    verify: "Bank verified successfully"
+  errors:
+    verify: "Failed to verify bank"
+```
+
+### Testing with reviewable_request_spec
+
+Use the specialized shared example for testing reviewable controllers:
+
+```ruby
+# Test built-in default actions only
+it_behaves_like "reviewable_request_spec", "categories", {
+  review_contexts: {
+    default: true
+  }
+}
+
+# Test customized default context
+it_behaves_like "reviewable_request_spec", "banks", {
+  review_contexts: {
+    default: {
+      statuses: %w[pending approved rejected modify revise],
+      actions: { /* custom actions */ }
+    }
+  }
+}
+
+# Test multiple custom contexts
+it_behaves_like "reviewable_request_spec", "banks", {
+  review_contexts: {
+    compliance: { /* config */ },
+    audit: { /* config */ }
+  }
+}
+```
+
+**Required setup:**
+
+- Include `with authenticated_user` context
+- Define `new_attributes` for `update_model` actions
+- Add I18n messages for all custom actions
+
+### Testing
+
+- **Framework**: RSpec with FactoryBot for fixtures
+- **Shared examples**: Use `request_shared_spec` for standard CRUD testing and `reviewable_request_spec` for reviewable workflows
+- **Authentication**: Include `with authenticated_user` context for request specs
+- **Factories**: Located in `spec/factories/dscf/credit/` with traits for different states
+
+### Development Workflow Tips
+
+- **Common Generator**: Use `rails generate common ModelName` to scaffold complete API resources
+- **Yield Blocks**: Override Common module actions using `super` pattern for custom logic
+- **Message Resolution**: System automatically resolves I18n keys - no manual message keys needed
+- **Security**: Always implement `ransackable_attributes` and `ransackable_associations` for filtering
+- **Reviewable Testing**: Use `reviewable_request_spec` with `default: true` for built-in workflows or full config for custom contexts
+
+### Database Conventions
+
+- **Migrations**: Prefix with `dscf_credit_` and include comprehensive indexing
+- **Precision**: Use `precision: 15, scale: 2` for monetary amounts
+- **Foreign keys**: Explicitly name foreign key tables (e.g., `foreign_key: { to_table: :dscf_credit_banks }`)
+- **JSONB**: Use for flexible data storage (e.g., `metadata`, `review_feedback`)
+
+### Key Commands
+
+```bash
+# Run tests
+bundle exec rspec
+
+# Generate migration
+rails generate migration CreateDscfCreditModelName
+
+# Generate complete API resource with Common module
+rails generate common Dscf::Credit::ModelName
+
+# Generate only specific components
+rails generate common ModelName --only controller serializer
+rails generate common ModelName --skip routes locales
+
+# Run engine in dummy app context
+cd spec/dummy && rails console
+
+# Install gem locally
+gem build dscf-credit.gemspec && gem install dscf-credit-*.gem
+```
+
+## Core Dependencies Deep Dive
+
+### Dscf::Core::Common Module
+
+Provides standardized CRUD with automatic model resolution and I18n integration:
+
+```ruby
+# Automatic model resolution
+# Controller: Dscf::Credit::LoansController → Model: Dscf::Credit::Loan
+# Fallback: Dscf::Core::Loan if credit model doesn't exist
+
+def index
+  # Built-in features:
+  # - Pagination with metadata when ?page= param present
+  # - Ransack filtering with whitelisted attributes
+  # - Eager loading via eager_loaded_associations
+  # - Automatic I18n message resolution
+  # - Serializer includes based on action
+
+  # Custom logic with yield blocks
+  super do
+    loans = Loan.active.includes(:bank)
+    options = { include: [:bank, :user] }
+    [loans, options]  # Return [data, serializer_options]
+  end
+end
+
+def create
+  # Automatic validation and error handling
+  # Uses model_params for strong parameters
+  # Automatically reloads with eager_loaded_associations
+  # Resolves I18n messages: "loan.success.create" or "loan.errors.create"
+end
+```
+
+### Yield Block Customization Patterns
+
+```ruby
+# Pattern 1: Custom data only
+def index
+  super do
+    User.active.verified  # Return custom ActiveRecord::Relation
+  end
+end
+
+# Pattern 2: Custom data with options
+def show
+  super do
+    options = {
+      include: [:profile, :roles],
+      meta: { last_login: @obj.last_login_at }
+    }
+    [@obj, options]  # Return [data, serializer_options]
+  end
+end
+
+# Pattern 3: Hash options only (uses default data)
+def index
+  super do
+    { include: [:profile], meta: { total: User.count } }
+  end
+end
+```
+
+### Required Controller Methods
+
+All controllers using `Dscf::Core::Common` must implement:
+
+```ruby
+private
+
+def model_params
+  # Strong parameters for the model
+  params.require(:loan).permit(:amount, :status, :due_date)
+end
+
+def eager_loaded_associations
+  # Associations to preload for N+1 query prevention
+  [:loan_profile, :credit_line, :payment_request]
+end
+
+def allowed_order_columns
+  # Whitelisted columns for sorting (security)
+  %w[id amount status due_date created_at updated_at]
+end
+
+def default_serializer_includes
+  # Action-specific includes for serialization
+  {
+    index: [:loan_profile, :credit_line],
+    show: [:loan_profile, :credit_line, :loan_transactions],
+    create: [:loan_profile, :credit_line],
+    update: [:loan_profile, :credit_line]
+  }
+end
+```
+
+### Dscf::Core::JsonResponse Patterns
+
+Standardized API responses with automatic I18n message resolution:
+
+```ruby
+# Automatic message resolution using locale keys
+# Pattern: {model}.{success|errors}.{action}
+# Example: bank.success.create, facilitator.errors.approve
+
+# Success with automatic message
+render_success(data: @loan)
+# Looks for: "loan.success.{action_name}" in config/locales/en.yml
+
+# Success with explicit message key
+render_success(
+  "operations.success.completed",
+  data: @loan,
+  serializer_options: { include: [:loan_profile, :credit_line] }
+)
+
+# Error with automatic message
+render_error(
+  errors: @loan.errors.full_messages[0],
+  status: :unprocessable_entity
+)
+# Looks for: "loan.errors.{action_name}" in config/locales/en.yml
+
+# Error with explicit message key
+render_error(
+  "errors.validation_failed",
+  errors: @loan.errors.full_messages,
+  status: :unprocessable_entity
+)
+
+# Response format with pagination metadata
+{
+  "success": true,
+  "message": "Loans retrieved successfully",
+  "data": [...],
+  "pagination": {
+    "current_page": 1,
+    "per_page": 10,
+    "total_count": 150,
+    "total_pages": 15,
+    "links": {
+      "first": "/loans?page=1",
+      "prev": null,
+      "next": "/loans?page=2",
+      "last": "/loans?page=15"
+    }
+  }
+}
+```
+
+### I18n Message Configuration
+
+Define messages in `config/locales/en.yml` following the pattern:
+
+```yaml
+en:
+  model_name:
+    success:
+      index: "Model retrieved successfully"
+      show: "Model details retrieved successfully"
+      create: "Model created successfully"
+      update: "Model updated successfully"
+      # Reviewable actions
+      approve: "Model approved successfully"
+      reject: "Model rejected successfully"
+      request_modification: "Modification requested for model successfully"
+      resubmit: "Model resubmitted successfully"
+    errors:
+      create: "Failed to create model"
+      update: "Failed to update model"
+      # Reviewable actions
+      approve: "Failed to approve model"
+      reject: "Failed to reject model"
+      request_modification: "Failed to request modification for model"
+      resubmit: "Failed to resubmit model"
+```
+
+### Dscf::Core::Filterable Security
+
+Ransack integration with mandatory attribute whitelisting:
+
+```ruby
+# REQUIRED in all models for security
+def self.ransackable_attributes(auth_object = nil)
+  %w[id status amount created_at updated_at]  # Explicit whitelist
+end
+
+def self.ransackable_associations(auth_object = nil)
+  %w[bank user loan_profile]  # Explicit whitelist
+end
+
+# Common Ransack predicates
+# _eq (equals), _cont (contains), _start (starts with), _end (ends with)
+# _gt/_gteq (greater than/equal), _lt/_lteq (less than/equal)
+# _in (in array), _null/_not_null (is/isn't null)
+
+# API usage examples
+GET /loans?q[status_eq]=active&q[amount_gteq]=1000
+GET /loans?q[user_email_cont]=john&q[created_at_gteq]=2023-01-01
+GET /loans?q[status_in][]=active&q[status_in][]=pending
+```
+
+### Authentication Integration
+
+Bearer token authentication from dscf-core:
+
+```ruby
+# Automatic in ApplicationController
+include Dscf::Core::Authenticatable
+
+# Provides:
+# - current_user method
+# - Authentication verification
+# - Token parsing from Authorization header
+
+# Test context
+include_context "with authenticated_user"  # Provides auth_user and headers
+```
+
+### API Response Standards
+
+All API responses follow this format:
+
+```ruby
+# Success Response
+{
+  "success": true,
+  "message": "Resource created successfully",  # From I18n or explicit
+  "data": { ... },                            # Serialized data
+  "pagination": { ... }                       # If paginated
+}
+
+# Error Response
+{
+  "success": false,
+  "error": "Failed to create resource",       # From I18n or explicit
+  "errors": ["Validation error messages"]     # Array of specific errors
+}
+```
+
+### Controller Implementation Template
+
+```ruby
+module Dscf::Credit
+  class ExampleController < ApplicationController
+    include Dscf::Core::Common
+    include Dscf::Credit::Reviewable  # If approval workflow needed
+
+    private
+
+    def model_params
+      params.require(:example).permit(:attr1, :attr2)
+    end
+
+    def eager_loaded_associations
+      [:association1, :association2]
+    end
+
+    def allowed_order_columns
+      %w[id name status created_at updated_at]
+    end
+
+    def default_serializer_includes
+      {
+        index: [:association1],
+        show: [:association1, :association2],
+        create: [:association1],
+        update: [:association1, :association2]
+      }
+    end
+  end
+end
+```
+
+### Model Implementation Template
+
+```ruby
+module Dscf::Credit
+  class Example < ApplicationRecord
+    self.table_name = "dscf_credit_examples"
+
+    # Associations with explicit class names
+    belongs_to :bank, class_name: "Dscf::Credit::Bank"
+    has_many :items, class_name: "Dscf::Credit::Item", dependent: :destroy
+
+    # Validations
+    validates :status, inclusion: { in: %w[pending approved rejected] }
+    validates :amount, numericality: { greater_than: 0 }
+
+    # Scopes
+    scope :active, -> { where(status: "approved") }
+
+    # Ransack configuration
+    def self.ransackable_attributes(auth_object = nil)
+      %w[id status amount created_at updated_at]
+    end
+
+    def self.ransackable_associations(auth_object = nil)
+      %w[bank items]
+    end
+  end
+end
+```
+
+### Critical Files to Reference
+
+- `app/controllers/dscf/credit/application_controller.rb` - Base controller pattern
+- `app/models/dscf/credit/loan.rb` - Complex model with multiple associations
+- `app/controllers/concerns/dscf/core/reviewable_controller.rb` - Review workflow implementation
+- `spec/support/requests/shared_examples.rb` - Test patterns with `request_shared_spec`
+- `spec/support/requests/reviewable_controller_spec.rb` - Reviewable testing with `reviewable_request_spec`
+- `spec/support/shared_context/authenticated_user.rb` - Authentication setup
+- `config/routes.rb` - Engine routing patterns with member actions for approvals
+- `docs/REVIEWABLE_REQUEST_SPEC_DOCUMENTATION.md` - Comprehensive testing guide for reviewable controllers
+- `docs/docs/CORE_CONCERNS_DOCUMENTATION.md` - Detailed dscf-core dependency patterns