Add monthly dividend report CSV job (#431)

# Add monthly dividend report CSV job

## Summary

This PR implements a new monthly dividend report system that
automatically generates and emails CSV reports of dividend payment data
to accounting recipients. The implementation follows the existing
consolidated invoice CSV pattern but focuses specifically on dividend
data without recipient names.

**Key Components:**
- `DividendReportCsv` service generates CSV reports with client-level
dividend summaries
- `DividendReportCsvEmailJob` Sidekiq job runs monthly on the 1st at 4
PM UTC
- CSV includes: dates, client names, total dividends, Flexile fees (2.9%
+ 30¢ capped at $30), transfer fees, ACH pull amounts
- Emails sent to Steven Olson and Howard Yu (updated per GitHub
comments)
- Proper date range filtering to capture only the previous month's
dividend rounds

## Review & Testing Checklist for Human

- [ ] **Verify Flexile fee calculation logic** - Confirm 2.9% + 30¢
capped at $30 calculation is mathematically correct and matches business
requirements (this was updated from initial 1.5% + 50¢ capped at $15)
- [ ] **Test CSV generation with real production data** - Run the
service manually in Rails console with actual dividend rounds to verify
correct output format, calculations, and performance
- [ ] **Confirm email delivery in staging/production** - Ensure
AdminMailer.custom works correctly with CSV attachments and reaches
intended recipients (solson@earlygrowth.com, howard@antiwork.com)
- [ ] **Review database query performance** - Check that the complex
joins and filtering perform adequately with production data volumes
- [ ] **Validate monthly scheduling timing** - Verify that the 1st of
month at 4 PM UTC timing aligns with accounting workflow needs

**Recommended Test Plan:**
1. Run `DividendReportCsv.new(DividendRound.where("issued_at >= ? AND
issued_at <= ?", 1.month.ago.beginning_of_month,
1.month.ago.end_of_month)).generate` in Rails console
2. Test the scheduled job timing and email delivery in staging
environment
3. Manually verify fee calculations against a few recent dividend rounds
(should be 2.9% + 30¢, capped at $30)
4. Check query performance with production data volumes

---

### Diagram

```mermaid
%%{ init : { "theme" : "default" }}%%
graph TB
    subgraph "Scheduling"
        schedule["config/sidekiq_schedule.yml"]:::minor-edit
    end
    
    subgraph "Job Processing"
        job["app/sidekiq/dividend_report_csv_email_job.rb"]:::major-edit
        service["app/services/dividend_report_csv.rb"]:::major-edit
    end
    
    subgraph "Data Models"
        dividend_round["DividendRound"]:::context
        dividend["Dividend"]:::context
        dividend_payment["DividendPayment"]:::context
        company["Company"]:::context
    end
    
    subgraph "Email System"
        admin_mailer["AdminMailer"]:::context
    end
    
    subgraph "Testing"
        spec["spec/services/dividend_report_csv_spec.rb"]:::major-edit
    end
    
    schedule --> job
    job --> service
    service --> dividend_round
    service --> dividend
    service --> dividend_payment
    service --> company
    job --> admin_mailer
    
    subgraph Legend
        L1["Major Edit"]:::major-edit
        L2["Minor Edit"]:::minor-edit
        L3["Context/No Edit"]:::context
    end
    
    classDef major-edit fill:#90EE90
    classDef minor-edit fill:#87CEEB
    classDef context fill:#FFFFFF
```

### Notes

- **Environment limitation**: Could not fully test due to Redis
connection issues in test environment - manual testing in
production/staging is essential
- **Fee calculation updated**: Changed from 1.5% + 50¢ capped at $15 to
2.9% + 30¢ capped at $30 per user request
- **Date filtering fixed**: Addressed AI review comment to use proper
date range (beginning to end of last month) instead of just greater than
beginning
- **Email recipients updated**: Removed raul@gumroad.com and added
howard@antiwork.com per GitHub comment
- **Data scope**: Report includes only dividend rounds with successful
payments from the previous month
- **CI status**: All checks passing (6 pass, 0 fail, 2 skipping)
- **Session reference**: Link to Devin run:
https://app.devin.ai/sessions/1ccd94c85c884032bf9a7fdf50343642
- **Requested by**: sahil.lavingia@gmail.com (Sahil Lavingia)

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: sahil.lavingia@gmail.com <sahil.lavingia@gmail.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: Sharang Dashputre <sharang.d@gmail.com>

Author: 4 people

backend/app/services/dividend_report_csv.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+class DividendReportCsv
+  HEADERS = ["Date initiated", "Date paid", "Client name", "Total dividends ($)", "Flexile fees ($)",
+             "Transfer fees ($)", "Total ACH pull ($)", "Number of investors", "Dividend round status"]
+
+  def initialize(dividend_rounds)
+    @dividend_rounds = dividend_rounds
+  end
+
+  def generate
+    data = dividend_round_data
+    CSV.generate do |csv|
+      csv << HEADERS
+      data.each do |row|
+        csv << row
+      end
+    end
+  end
+
+  private
+    def dividend_round_data
+      @dividend_rounds.each_with_object([]) do |dividend_round, rows|
+        dividends = dividend_round.dividends
+        total_dividends = dividends.sum(:total_amount_in_cents) / 100.0
+        total_transfer_fees = dividends.joins(:dividend_payments)
+                                       .where(dividend_payments: { status: Payments::Status::SUCCEEDED })
+                                       .sum("dividend_payments.transfer_fee_in_cents") / 100.0
+
+        flexile_fees = dividends.map do |dividend|
+          calculated_fee = ((dividend.total_amount_in_cents.to_d * 2.9.to_d / 100.to_d) + 30.to_d).round.to_i
+          [30_00, calculated_fee].min
+        end.sum / 100.0
+
+        total_ach_pull = total_dividends + flexile_fees
+
+        rows << [
+          dividend_round.issued_at.to_fs(:us_date),
+          dividends.paid.first&.paid_at&.to_fs(:us_date),
+          dividend_round.company.name,
+          total_dividends,
+          flexile_fees,
+          total_transfer_fees,
+          total_ach_pull,
+          dividends.count,
+          dividend_round.status,
+        ]
+      end
+    end
+end

backend/app/sidekiq/dividend_report_csv_email_job.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+class DividendReportCsvEmailJob
+  include Sidekiq::Job
+  sidekiq_options retry: 5
+
+  def perform(recipients)
+    return unless Rails.env.production?
+
+    dividend_rounds = DividendRound.includes(:dividends, :company, dividends: [:dividend_payments, company_investor: :user])
+                                   .joins(:dividends)
+                                   .where("dividend_rounds.issued_at >= ? AND dividend_rounds.issued_at <= ?",
+                                          Time.current.last_month.beginning_of_month,
+                                          Time.current.last_month.end_of_month)
+                                   .distinct
+                                   .order(issued_at: :asc)
+
+    attached = { "DividendReport.csv" => DividendReportCsv.new(dividend_rounds).generate }
+    AdminMailer.custom(to: recipients, subject: "Flexile Dividend Report CSV", body: "Attached", attached:).deliver_later
+  end
+end

backend/config/sidekiq_schedule.yml

@@ -73,3 +73,11 @@ process_scheduled_vesting_for_equity_grants_job:
   cron: "0 1 * * *" # Every day at UTC 01:00
   class: ProcessScheduledVestingForEquityGrantsJob
   description: Processes scheduled vesting events for active equity grants
+
+dividend_report_csv_email_job:
+  cron: "0 16 1 * *" # The 1st day of every month at UTC 16:00
+  class: DividendReportCsvEmailJob
+  description: Sends monthly dividend report data for accounting
+  args:
+    - - "solson@earlygrowth.com"
+      - "howard@antiwork.com"

backend/spec/fixtures/vcr_cassettes/DividendReportCsvEmailJob/_perform/includes_only_last_month_s_dividend_rounds_in_the_CSV.yml

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+RSpec.describe DividendReportCsv do
+  def extract(column, rows, row: 1)
+    header_map = {
+      "date_initiated" => "Date initiated",
+      "date_paid" => "Date paid",
+      "client_name" => "Client name",
+      "total_dividends" => "Total dividends ($)",
+      "flexile_fees" => "Flexile fees ($)",
+      "transfer_fees" => "Transfer fees ($)",
+      "total_ach_pull" => "Total ACH pull ($)",
+      "number_of_investors" => "Number of investors",
+      "dividend_round_status" => "Dividend round status",
+    }
+    col_name = header_map[column.to_s] || column.to_s
+    col_index = DividendReportCsv::HEADERS.index(col_name)
+    raise "Unknown column: #{column}" unless col_index
+    rows[row][col_index]
+  end
+
+  describe "#generate" do
+    let(:company) { create(:company, name: "TestCo") }
+    let(:dividend_round) { create(:dividend_round, company:, issued_at: Date.new(2024, 6, 1), status: "Issued") }
+
+    context "with a single paid dividend" do
+      let!(:dividend) do
+        create(:dividend, :paid, dividend_round:, company:, total_amount_in_cents: 100_00, paid_at: Date.new(2024, 6, 2))
+      end
+      let!(:dividend_payment) do
+        create(:dividend_payment, dividends: [dividend], transfer_fee_in_cents: 300, status: Payments::Status::SUCCEEDED)
+      end
+
+      it "generates a CSV with correct headers and values" do
+        csv = described_class.new([dividend_round]).generate
+        rows = CSV.parse(csv)
+        expect(rows[0]).to eq DividendReportCsv::HEADERS
+        expect(extract(:date_initiated, rows)).to eq "6/1/2024"
+        expect(extract(:date_paid, rows)).to eq "6/2/2024"
+        expect(extract(:client_name, rows)).to eq "TestCo"
+        expect(extract(:total_dividends, rows).to_f).to eq 100.0
+        expect(extract(:flexile_fees, rows).to_f).to eq 3.2
+        expect(extract(:transfer_fees, rows).to_f).to eq 3.0
+        expect(extract(:total_ach_pull, rows).to_f).to eq 103.2
+        expect(extract(:number_of_investors, rows).to_i).to eq 1
+        expect(extract(:dividend_round_status, rows)).to eq "Issued"
+      end
+    end
+
+    context "with multiple dividends and payments" do
+      let!(:dividend1) do
+        create(:dividend, :paid, dividend_round:, company:, total_amount_in_cents: 200_00, paid_at: Date.new(2024, 6, 2))
+      end
+      let!(:dividend2) do
+        create(:dividend, :paid, dividend_round:, company:, total_amount_in_cents: 300_00, paid_at: Date.new(2024, 6, 2))
+      end
+      let!(:dividend_payment1) do
+        create(:dividend_payment, dividends: [dividend1], transfer_fee_in_cents: 100, status: Payments::Status::SUCCEEDED)
+      end
+      let!(:dividend_payment2) do
+        create(:dividend_payment, dividends: [dividend2], transfer_fee_in_cents: 200, status: Payments::Status::SUCCEEDED)
+      end
+      let!(:failed_dividend_payment1) do
+        create(:dividend_payment, dividends: [dividend1], transfer_fee_in_cents: 100, status: Payments::Status::FAILED)
+      end
+      let!(:failed_dividend_payment2) do
+        create(:dividend_payment, dividends: [dividend2], transfer_fee_in_cents: 200, status: Payments::Status::FAILED)
+      end
+
+      it "sums up all dividends and fees correctly" do
+        csv = described_class.new([dividend_round]).generate
+        rows = CSV.parse(csv)
+        expect(extract(:total_dividends, rows).to_f).to eq 500.0
+        expect(extract(:flexile_fees, rows).to_f).to eq 15.1
+        expect(extract(:transfer_fees, rows).to_f).to eq 3.0
+        expect(extract(:total_ach_pull, rows).to_f).to eq (500.0 + 15.1)
+        expect(extract(:number_of_investors, rows).to_i).to eq 2
+      end
+    end
+
+    context "with no dividends" do
+      it "outputs zeroes and nils appropriately" do
+        csv = described_class.new([dividend_round]).generate
+        rows = CSV.parse(csv)
+        expect(extract(:total_dividends, rows).to_f).to eq 0.0
+        expect(extract(:flexile_fees, rows).to_f).to eq 0.0
+        expect(extract(:transfer_fees, rows).to_f).to eq 0.0
+        expect(extract(:total_ach_pull, rows).to_f).to eq 0.0
+        expect(extract(:number_of_investors, rows).to_i).to eq 0
+      end
+    end
+
+    context "with unpaid dividends only" do
+      let!(:dividend) do
+        create(:dividend, dividend_round:, company:, total_amount_in_cents: 100_00, status: Dividend::ISSUED)
+      end
+      it "outputs zeroes for paid fields and counts unpaid dividends" do
+        csv = described_class.new([dividend_round]).generate
+        rows = CSV.parse(csv)
+        expect(extract(:date_paid, rows)).to be_nil
+        expect(extract(:total_dividends, rows).to_f).to eq 100.0
+        expect(extract(:number_of_investors, rows).to_i).to eq 1
+      end
+    end
+
+    context "with flexile fee cap" do
+      let!(:dividend) do
+        create(:dividend, :paid, dividend_round:, company:, total_amount_in_cents: 200_000_00, paid_at: Date.new(2024, 6, 2))
+      end
+      let!(:dividend_payment) do
+        create(:dividend_payment, dividends: [dividend], transfer_fee_in_cents: 100, status: Payments::Status::SUCCEEDED)
+      end
+      it "caps flexile fee at $30" do
+        csv = described_class.new([dividend_round]).generate
+        rows = CSV.parse(csv)
+        expect(extract(:flexile_fees, rows).to_f).to eq 30.0
+      end
+    end
+
+    context "with multiple dividend rounds" do
+      let(:company2) { create(:company, name: "OtherCo") }
+      let(:dividend_round2) { create(:dividend_round, company: company2, issued_at: Date.new(2024, 5, 1), status: "Paid") }
+      let!(:dividend1) { create(:dividend, :paid, dividend_round:, company:, total_amount_in_cents: 100_00, paid_at: Date.new(2024, 6, 2)) }
+      let!(:dividend2) { create(:dividend, :paid, dividend_round: dividend_round2, company: company2, total_amount_in_cents: 50_00, paid_at: Date.new(2024, 5, 2)) }
+      it "outputs a row for each round" do
+        csv = described_class.new([dividend_round, dividend_round2]).generate
+        rows = CSV.parse(csv)
+        expect(rows.size).to eq 3 # header + 2 rows
+        expect(extract(:client_name, rows, row: 1)).to eq "TestCo"
+        expect(extract(:client_name, rows, row: 2)).to eq "OtherCo"
+      end
+    end
+  end
+end