Add checklist functionality for company onboarding (#409)

Author: the-wunmi

backend/app/controllers/internal/companies/workers_controller.rb

@@ -17,14 +17,14 @@ def create
     ).perform
 
     if result[:success]
-      render json: { success: true, new_user_id: result[:company_worker].user_id, document_id: result[:document].id }, status: :ok
+      render json: { success: true, new_user_id: result[:company_worker].user_id, document_id: result[:document]&.id }, status: :ok
     else
       render json: result, status: :unprocessable_entity
     end
   end
 
   private
     def worker_params
-      params.require(:contractor).permit(:email, :started_at, :pay_rate_in_subunits, :role, :pay_rate_type)
+      params.require(:contractor).permit(:email, :started_at, :pay_rate_in_subunits, :role, :pay_rate_type, :contract_signed_elsewhere)
     end
 end

backend/app/models/company.rb

@@ -26,6 +26,19 @@ class Company < ApplicationRecord
     self.const_set("ACCESS_ROLE_#{access_role.upcase}", access_role)
   end
 
+  ADMIN_CHECKLIST_ITEMS = [
+    { key: "add_company_details", title: "Add company details", description: "Add your company name and basic information" },
+    { key: "add_bank_account", title: "Add bank account", description: "Connect your bank account to enable payments" },
+    { key: "invite_contractor", title: "Invite a contractor", description: "Add your first team member" },
+    { key: "send_first_payment", title: "Send your first payment", description: "Process your first contractor payment" }
+  ].freeze
+
+  WORKER_CHECKLIST_ITEMS = [
+    { key: "fill_tax_information", title: "Fill tax information", description: "Complete your tax details" },
+    { key: "add_payout_information", title: "Add payout information", description: "Set up your payment method" },
+    { key: "sign_contract", title: "Sign contract", description: "Review and sign your contractor agreement" }
+  ].freeze
+
   has_many :company_administrators
   has_many :administrators, through: :company_administrators, source: :user
   has_many :company_lawyers
@@ -98,7 +111,6 @@ def active
   after_create_commit :create_balance!
   after_update_commit :update_convertible_implied_shares, if: :saved_change_to_fully_diluted_shares?
 
-
   accepts_nested_attributes_for :expense_categories
 
   delegate :stripe_setup_intent, :bank_account_last_four, :microdeposit_verification_required?,
@@ -190,6 +202,28 @@ def json_flag?(flag)
     json_data&.dig("flags")&.include?(flag)
   end
 
+  def checklist_items(user)
+    case user
+    when CompanyAdministrator
+      ADMIN_CHECKLIST_ITEMS.map do |item|
+        item.merge(completed: checklist_item_completed?(item[:key], user))
+      end
+    when CompanyWorker
+      WORKER_CHECKLIST_ITEMS.map do |item|
+        item.merge(completed: checklist_item_completed?(item[:key], user))
+      end
+    else
+      []
+    end
+  end
+
+  def checklist_completion_percentage(user)
+    completed_count = checklist_items(user).count { |item| item[:completed] }
+    return 0 if checklist_items(user).empty?
+
+    (completed_count.to_f / checklist_items(user).size * 100).round
+  end
+
   private
     def update_convertible_implied_shares
       convertible_investments.each do |investment|
@@ -211,4 +245,25 @@ def fetch_or_create_stripe_customer_id!
       update!(stripe_customer_id: stripe_customer.id)
       stripe_customer_id
     end
+
+    def checklist_item_completed?(key, user)
+      case key
+      when "add_company_details"
+        name.present?
+      when "add_bank_account"
+        bank_account_ready?
+      when "invite_contractor"
+        company_workers.active.exists?
+      when "send_first_payment"
+        invoices.where(status: Invoice::PAID_OR_PAYING_STATES).exists?
+      when "fill_tax_information"
+        user.user.compliance_info&.tax_information_confirmed_at.present?
+      when "add_payout_information"
+        user.user.bank_account.present?
+      when "sign_contract"
+        user.contract_signed?
+      else
+        false
+      end
+    end
 end

backend/app/models/company_worker.rb

@@ -98,6 +98,14 @@ def end_contract!
     update!(ended_at: Time.current)
   end
 
+  def contract_signed?
+    contract_signed_elsewhere ||
+      user.documents.joins(:signatures)
+          .where(documents: { document_type: Document.document_types[:consulting_contract], deleted_at: nil, company: company })
+          .where.not(document_signatures: { signed_at: nil })
+          .exists?
+  end
+
   def quickbooks_entity
     "Vendor"
   end

backend/app/presenters/user_presenter.rb

@@ -125,6 +125,8 @@ def logged_in_user
           primaryAdminName: company.primary_admin.user.name,
           completedPaymentMethodSetup: company.bank_account_ready?,
           isTrusted: company.is_trusted,
+          checklistItems: company.checklist_items(user.company_administrator_for(company) || user.company_worker_for(company)),
+          checklistCompletionPercentage: company.checklist_completion_percentage(user.company_administrator_for(company) || user.company_worker_for(company)),
         }
       end,
       id: user.external_id,

backend/spec/models/company_spec.rb

@@ -58,6 +58,213 @@
     end
   end
 
+  describe "checklist functionality" do
+    let(:company) { create(:company, :without_bank_account) }
+
+    describe "#checklist_items" do
+      context "for company administrators" do
+        let(:company) { create(:company, :pre_onboarding) }
+        let(:admin) { create(:company_administrator, company: company) }
+
+        it "returns admin checklist items with completion status" do
+          items = company.checklist_items(admin)
+
+          expect(items).to have_attributes(size: 4)
+          expect(items.map { |item| item[:key] }).to contain_exactly(
+            "add_company_details", "add_bank_account", "invite_contractor", "send_first_payment"
+          )
+          expect(items.all? { |item| item[:completed] == false }).to be true
+        end
+
+        it "completes company details item when company name is present" do
+          items = company.checklist_items(admin)
+          company_details_item = items.find { |item| item[:key] == "add_company_details" }
+          expect(company_details_item[:completed]).to be false
+
+          company.update!(name: "Test Company")
+          items = company.reload.checklist_items(admin)
+          company_details_item = items.find { |item| item[:key] == "add_company_details" }
+          expect(company_details_item[:completed]).to be true
+        end
+
+        it "completes bank account item when stripe account becomes ready" do
+          items = company.checklist_items(admin)
+          bank_account_item = items.find { |item| item[:key] == "add_bank_account" }
+          expect(bank_account_item[:completed]).to be false
+
+          stripe_account = create(:company_stripe_account, company: company, status: "processing")
+          items = company.reload.checklist_items(admin)
+          bank_account_item = items.find { |item| item[:key] == "add_bank_account" }
+          expect(bank_account_item[:completed]).to be false
+
+          stripe_account.update!(status: "ready")
+          items = company.reload.checklist_items(admin)
+          bank_account_item = items.find { |item| item[:key] == "add_bank_account" }
+          expect(bank_account_item[:completed]).to be true
+        end
+
+        it "completes contractor item when worker is created" do
+          items = company.checklist_items(admin)
+          contractor_item = items.find { |item| item[:key] == "invite_contractor" }
+          expect(contractor_item[:completed]).to be false
+
+          create(:company_worker, company: company, user: create(:user))
+          items = company.reload.checklist_items(admin)
+          contractor_item = items.find { |item| item[:key] == "invite_contractor" }
+          expect(contractor_item[:completed]).to be true
+        end
+
+        it "completes payment item when payment succeeds" do
+          items = company.checklist_items(admin)
+          payment_item = items.find { |item| item[:key] == "send_first_payment" }
+          expect(payment_item[:completed]).to be false
+
+          contractor = create(:company_worker, company: company)
+          company.update!(name: "Test Company")
+          invoice = create(:invoice, company: company, company_worker: contractor, user: contractor.user)
+          items = company.reload.checklist_items(admin)
+          payment_item = items.find { |item| item[:key] == "send_first_payment" }
+          expect(payment_item[:completed]).to be false
+
+          invoice.update!(status: Invoice::PAID)
+          items = company.reload.checklist_items(admin)
+          payment_item = items.find { |item| item[:key] == "send_first_payment" }
+          expect(payment_item[:completed]).to be true
+        end
+
+        it "marks all admin items as completed when conditions are met" do
+          company.update!(name: "Test Company")
+          create(:company_stripe_account, company: company, status: "ready")
+          contractor = create(:company_worker, company: company)
+          invoice = create(:invoice, company: company, company_worker: contractor, user: contractor.user)
+          invoice.update!(status: Invoice::PAID)
+          company.reload
+
+          items = company.checklist_items(admin)
+          expect(items.all? { |item| item[:completed] }).to be true
+        end
+      end
+
+      context "for company workers" do
+        let(:worker) { create(:company_worker, without_contract: true, company: company, user: create(:user, without_bank_account: true)) }
+
+        it "returns worker checklist items with completion status" do
+          items = company.checklist_items(worker)
+
+          expect(items).to have_attributes(size: 3)
+          expect(items.map { |item| item[:key] }).to contain_exactly(
+            "fill_tax_information", "add_payout_information", "sign_contract"
+          )
+          expect(items.all? { |item| item[:completed] == false }).to be true
+        end
+
+        it "completes tax information item when worker confirms tax details" do
+          items = company.checklist_items(worker)
+          tax_item = items.find { |item| item[:key] == "fill_tax_information" }
+          expect(tax_item[:completed]).to be false
+
+          worker.user.compliance_info.update!(tax_information_confirmed_at: Time.current)
+
+          items = company.checklist_items(worker)
+          tax_item = items.find { |item| item[:key] == "fill_tax_information" }
+          expect(tax_item[:completed]).to be true
+        end
+
+        it "completes payout information item when worker adds bank account" do
+          items = company.checklist_items(worker)
+          payout_item = items.find { |item| item[:key] == "add_payout_information" }
+          expect(payout_item[:completed]).to be false
+
+          create(:wise_recipient, user: worker.user, used_for_invoices: true)
+          worker.user.reload
+
+          items = company.checklist_items(worker)
+          payout_item = items.find { |item| item[:key] == "add_payout_information" }
+          expect(payout_item[:completed]).to be true
+        end
+
+        it "completes contract item when worker signs contract" do
+          items = company.checklist_items(worker)
+          contract_item = items.find { |item| item[:key] == "sign_contract" }
+          expect(contract_item[:completed]).to be false
+
+          create(:document, company: company, document_type: :consulting_contract, signatories: [worker.user])
+
+          items = company.checklist_items(worker)
+          contract_item = items.find { |item| item[:key] == "sign_contract" }
+          expect(contract_item[:completed]).to be true
+        end
+      end
+
+      context "for other user types" do
+        let(:other_user) { create(:user) }
+
+        it "returns empty array for non-company users" do
+          items = company.checklist_items(other_user)
+          expect(items).to be_empty
+        end
+      end
+    end
+
+    describe "#checklist_completion_percentage" do
+      context "for company administrators" do
+        let(:company) { create(:company, :pre_onboarding) }
+        let(:admin) { create(:company_administrator, company: company) }
+
+        it "returns 0 when no items are completed" do
+          expect(company.checklist_completion_percentage(admin)).to eq(0)
+        end
+
+        it "returns correct percentage when some items are completed" do
+          create(:company_stripe_account, company: company, status: "ready")
+          company.reload
+          expect(company.checklist_completion_percentage(admin)).to eq(25)
+        end
+
+        it "returns 100 when all items are completed" do
+          company.update!(name: "Test Company")
+          create(:company_stripe_account, company: company, status: "ready")
+          contractor = create(:company_worker, company: company)
+          invoice = create(:invoice, company: company, user: contractor.user)
+          invoice.update!(status: Invoice::PAID)
+          company.reload
+
+          expect(company.checklist_completion_percentage(admin)).to eq(100)
+        end
+      end
+
+      context "for company workers" do
+        let(:worker) { create(:company_worker, without_contract: true, company: company, user: create(:user, without_bank_account: true)) }
+
+        it "returns 0 when no items are completed" do
+          expect(company.checklist_completion_percentage(worker)).to eq(0)
+        end
+
+        it "returns correct percentage when some items are completed" do
+          worker.user.compliance_info.update!(tax_information_confirmed_at: Time.current)
+
+          expect(company.checklist_completion_percentage(worker)).to eq(33)
+        end
+
+        it "returns 100 when all worker items are completed" do
+          worker.user.compliance_info.update!(tax_information_confirmed_at: Time.current)
+          create(:wise_recipient, user: worker.user, used_for_invoices: true)
+          create(:document, company: company, document_type: :consulting_contract, signatories: [worker.user])
+
+          expect(company.checklist_completion_percentage(worker)).to eq(100)
+        end
+      end
+
+      context "for other user types" do
+        let(:other_user) { create(:user) }
+
+        it "returns 0 for non-company users" do
+          expect(company.checklist_completion_percentage(other_user)).to eq(0)
+        end
+      end
+    end
+  end
+
   describe "validations" do
     it { is_expected.to validate_presence_of(:email) }
     it { is_expected.to validate_presence_of(:country_code) }