diff --git a/app/controllers/charges_controller.rb b/app/controllers/charges_controller.rb
index 12f47f48..ef3fef24 100644
--- a/app/controllers/charges_controller.rb
+++ b/app/controllers/charges_controller.rb
@@ -20,7 +20,11 @@ def create
unless Charges::CreateFeeService::ALLOWED_KINDS.include?(kind)
@charge = @tenancy.charges.new(charge_params)
@charge.errors.add(:charge_kind, "must be late_fee or other")
- return render :new, status: :unprocessable_content
+ respond_to do |format|
+ format.html { render :new, status: :unprocessable_content }
+ format.json { render json: @charge.errors, status: :unprocessable_content }
+ end
+ return
end
result = Charges::CreateFeeService.call(
diff --git a/app/controllers/properties_controller.rb b/app/controllers/properties_controller.rb
index a557e86a..de432343 100644
--- a/app/controllers/properties_controller.rb
+++ b/app/controllers/properties_controller.rb
@@ -15,6 +15,7 @@ def show
tenancies: %i[parties receipts charges]
).find(params.expect(:id))
@financial_items = @property.financial_items(@year)
+ @security_deposits_held_cents = Accounting::SecurityDepositBalanceQuery.call(property: @property)
end
def schedule_e
diff --git a/app/controllers/security_deposit_transactions_controller.rb b/app/controllers/security_deposit_transactions_controller.rb
new file mode 100644
index 00000000..c7fde17d
--- /dev/null
+++ b/app/controllers/security_deposit_transactions_controller.rb
@@ -0,0 +1,75 @@
+class SecurityDepositTransactionsController < ApplicationController
+ before_action :set_transaction
+
+ def show
+ @journal_entries = @transaction.journal_entries.includes(postings: :account).order(:occurred_on, :id)
+ end
+
+ def correction
+ if @transaction.voided? || @transaction.superseded?
+ redirect_to security_deposit_transaction_path(@transaction), alert: "This transaction cannot be corrected."
+ return
+ end
+
+ @parties = authenticated_user.parties.order(:display_name)
+ @active_charges = load_active_charges
+ end
+
+ def correct
+ result = SecurityDepositTransactions::CorrectService.call(
+ transaction: @transaction,
+ amount: transaction_params[:amount],
+ occurred_on: transaction_params[:occurred_on],
+ party_id: transaction_params[:party_id],
+ charge_id: transaction_params[:charge_id],
+ external_reference: transaction_params[:external_reference],
+ memo: transaction_params[:memo]
+ )
+
+ if result.success?
+ replacement = result.value!.data[:replacement]
+ redirect_to security_deposit_transaction_path(replacement), notice: "Deposit transaction corrected successfully."
+ else
+ @parties = authenticated_user.parties.order(:display_name)
+ @active_charges = load_active_charges
+ flash.now[:alert] = result.failure.error
+ render :correction, status: :unprocessable_entity
+ end
+ end
+
+ def void
+ result = SecurityDepositTransactions::VoidService.call(
+ transaction: @transaction,
+ reason: params[:reason]
+ )
+
+ if result.success?
+ redirect_to tenancy_security_deposit_path(@transaction.tenancy), notice: "Deposit transaction voided successfully."
+ else
+ redirect_to security_deposit_transaction_path(@transaction), alert: result.failure.error
+ end
+ end
+
+ private
+
+ def load_active_charges
+ tenancy = @transaction.tenancy
+ if tenancy
+ tenancy.charges.posted.active.order(charge_date: :desc)
+ else
+ Charge.none
+ end
+ end
+
+ def set_transaction
+ @transaction = SecurityDepositTransaction.joins(security_deposit: { tenancy: { rentable_unit: :property } })
+ .where(properties: { user_id: authenticated_user.id })
+ .find(params[:id])
+ end
+
+ def transaction_params
+ params.require(:security_deposit_transaction).permit(
+ :amount, :occurred_on, :party_id, :charge_id, :external_reference, :memo
+ )
+ end
+end
diff --git a/app/controllers/security_deposits_controller.rb b/app/controllers/security_deposits_controller.rb
new file mode 100644
index 00000000..bfb6d54f
--- /dev/null
+++ b/app/controllers/security_deposits_controller.rb
@@ -0,0 +1,128 @@
+class SecurityDepositsController < ApplicationController
+ before_action :set_tenancy
+ before_action :set_security_deposit, only: %i[show edit update receive refund apply]
+
+ def show
+ @transactions = @security_deposit.transactions.includes(:party, :charge, :superseded_by).order(occurred_on: :desc, id: :desc)
+ @parties = authenticated_user.parties.order(:display_name)
+ @active_charges = @tenancy.charges.posted.active.order(charge_date: :desc)
+ end
+
+ def new
+ if @tenancy.security_deposit.present?
+ redirect_to tenancy_security_deposit_path(@tenancy)
+ return
+ end
+
+ @security_deposit = @tenancy.build_security_deposit(due_on: @tenancy.commencement_date)
+ end
+
+ def create
+ result = SecurityDeposits::CreateService.call(
+ tenancy: @tenancy,
+ required_amount: security_deposit_params[:required_amount],
+ due_on: security_deposit_params[:due_on]
+ )
+
+ if result.success?
+ redirect_to tenancy_security_deposit_path(@tenancy), notice: "Security deposit requirement recorded."
+ else
+ @security_deposit = @tenancy.build_security_deposit(security_deposit_params)
+ flash.now[:alert] = result.failure.error
+ render :new, status: :unprocessable_entity
+ end
+ end
+
+ def edit
+ if @security_deposit.transactions.exists?
+ redirect_to tenancy_security_deposit_path(@tenancy), alert: "Deposit requirement cannot be edited after transactions exist."
+ end
+ end
+
+ def update
+ result = SecurityDeposits::UpdateService.call(
+ security_deposit: @security_deposit,
+ required_amount: security_deposit_params[:required_amount],
+ due_on: security_deposit_params[:due_on]
+ )
+
+ if result.success?
+ redirect_to tenancy_security_deposit_path(@tenancy), notice: "Security deposit requirement updated."
+ else
+ flash.now[:alert] = result.failure.error
+ render :edit, status: :unprocessable_entity
+ end
+ end
+
+ def receive
+ party = authenticated_user.parties.find_by(id: params[:party_id])
+ result = SecurityDepositTransactions::ReceiveService.call(
+ security_deposit: @security_deposit,
+ party: party,
+ amount: params[:amount],
+ occurred_on: params[:occurred_on],
+ external_reference: params[:external_reference],
+ memo: params[:memo]
+ )
+
+ if result.success?
+ redirect_to tenancy_security_deposit_path(@tenancy), notice: "Security deposit payment received."
+ else
+ redirect_to tenancy_security_deposit_path(@tenancy), alert: result.failure.error
+ end
+ end
+
+ def refund
+ party = authenticated_user.parties.find_by(id: params[:party_id])
+ result = SecurityDepositTransactions::RefundService.call(
+ security_deposit: @security_deposit,
+ party: party,
+ amount: params[:amount],
+ occurred_on: params[:occurred_on],
+ external_reference: params[:external_reference],
+ memo: params[:memo]
+ )
+
+ if result.success?
+ redirect_to tenancy_security_deposit_path(@tenancy), notice: "Security deposit refund recorded."
+ else
+ redirect_to tenancy_security_deposit_path(@tenancy), alert: result.failure.error
+ end
+ end
+
+ def apply
+ charge = @tenancy.charges.find_by(id: params[:charge_id])
+ result = SecurityDepositTransactions::ApplyService.call(
+ security_deposit: @security_deposit,
+ charge: charge,
+ amount: params[:amount],
+ occurred_on: params[:occurred_on],
+ memo: params[:memo]
+ )
+
+ if result.success?
+ redirect_to tenancy_security_deposit_path(@tenancy), notice: "Security deposit applied to charge."
+ else
+ redirect_to tenancy_security_deposit_path(@tenancy), alert: result.failure.error
+ end
+ end
+
+ private
+
+ def set_tenancy
+ @tenancy = authenticated_user.tenancies.find(params[:tenancy_id])
+ end
+
+ def set_security_deposit
+ deposit = @tenancy.security_deposit
+ unless deposit
+ redirect_to new_tenancy_security_deposit_path(@tenancy)
+ return
+ end
+ @security_deposit = deposit
+ end
+
+ def security_deposit_params
+ params.require(:security_deposit).permit(:required_amount, :due_on)
+ end
+end
diff --git a/app/models/charge.rb b/app/models/charge.rb
index 2902a672..cb870263 100644
--- a/app/models/charge.rb
+++ b/app/models/charge.rb
@@ -26,6 +26,10 @@ class Charge < ApplicationRecord
has_one :superseded_charge, class_name: "Charge", foreign_key: :superseded_by_id
has_many :journal_entries, as: :source, dependent: :restrict_with_error
+ has_many :security_deposit_applications,
+ -> { where(transaction_kind: "applied") },
+ class_name: "SecurityDepositTransaction",
+ dependent: :restrict_with_error
enum :charge_kind, CHARGE_KINDS.index_by(&:itself), prefix: false, validate: true
@@ -92,6 +96,14 @@ def accounting_user
tenancy&.accounting_user
end
+ def deposit_applied_cents
+ security_deposit_applications.active.sum(&:amount_cents)
+ end
+
+ def remaining_deposit_application_cents
+ [ amount_cents - deposit_applied_cents, 0 ].max
+ end
+
private
def validate_service_period_range
diff --git a/app/models/party.rb b/app/models/party.rb
index 58f4cedf..93dbe4d5 100644
--- a/app/models/party.rb
+++ b/app/models/party.rb
@@ -5,6 +5,7 @@ class Party < ApplicationRecord
has_many :tenancies, through: :tenancy_parties
has_many :accounting_postings, class_name: "Posting", dependent: :restrict_with_error
has_many :receipts_as_payer, class_name: "Receipt", foreign_key: :payer_party_id, dependent: :restrict_with_error
+ has_many :security_deposit_transactions, dependent: :restrict_with_error
has_many :payment_ingestions, dependent: :nullify
PARTY_TYPES = %w[
diff --git a/app/models/property.rb b/app/models/property.rb
index 9e321645..14dfebce 100644
--- a/app/models/property.rb
+++ b/app/models/property.rb
@@ -5,6 +5,7 @@ class Property < ApplicationRecord
has_many :expenses, dependent: :restrict_with_error
has_many :charges, through: :tenancies
has_many :receipts, through: :tenancies
+ has_many :security_deposit_transactions, through: :tenancies
has_many :accounting_postings, class_name: "Posting", dependent: :restrict_with_error
ASSET_TYPES = %w[
diff --git a/app/models/security_deposit.rb b/app/models/security_deposit.rb
new file mode 100644
index 00000000..2fafb2a1
--- /dev/null
+++ b/app/models/security_deposit.rb
@@ -0,0 +1,99 @@
+class SecurityDeposit < ApplicationRecord
+ belongs_to :tenancy
+
+ has_many :transactions,
+ class_name: "SecurityDepositTransaction",
+ dependent: :restrict_with_error
+
+ has_many :journal_entries, as: :source, dependent: :restrict_with_error
+ has_many :postings, through: :journal_entries
+
+ validates :required_amount_cents, numericality: { only_integer: true, greater_than: 0 }
+ validates :due_on, presence: true
+ validates :tenancy_id, uniqueness: true
+
+ validate :validate_requirement_immutability, on: :update
+
+ def required_amount
+ required_amount_cents ? (required_amount_cents / 100.0) : 0.0
+ end
+
+ def required_amount=(val)
+ if val.nil? || (val.is_a?(String) && val.blank?)
+ write_attribute(:required_amount_cents, nil)
+ return
+ end
+
+ str = val.is_a?(Numeric) ? val.to_s : val.to_s.strip
+ if str.match?(/\A\d+(\.\d{1,2})?\z/)
+ self.required_amount_cents = (BigDecimal(str) * 100).round
+ else
+ self.required_amount_cents = -1
+ end
+ end
+
+ def accounting_user
+ tenancy&.accounting_user
+ end
+
+ def property
+ tenancy&.property
+ end
+
+ def rentable_unit
+ tenancy&.rentable_unit
+ end
+
+ def held_cents(as_of: Date.current)
+ Accounting::SecurityDepositBalanceQuery.call(tenancy: tenancy, as_of: as_of)
+ end
+
+ def held_amount(as_of: Date.current)
+ held_cents(as_of: as_of) / 100.0
+ end
+
+ def remaining_required_cents(as_of: Date.current)
+ [ required_amount_cents - held_cents(as_of: as_of), 0 ].max
+ end
+
+ def remaining_required_amount(as_of: Date.current)
+ remaining_required_cents(as_of: as_of) / 100.0
+ end
+
+ def fully_funded?(as_of: Date.current)
+ held_cents(as_of: as_of) >= required_amount_cents
+ end
+
+ def overfunded?(as_of: Date.current)
+ held_cents(as_of: as_of) > required_amount_cents
+ end
+
+ def funding_status(as_of: Date.current)
+ held = held_cents(as_of: as_of)
+ if held == 0
+ "not_funded"
+ elsif held < required_amount_cents
+ "partially_funded"
+ elsif held == required_amount_cents
+ "funded"
+ else
+ "overfunded"
+ end
+ end
+
+ private
+
+ def validate_requirement_immutability
+ if transactions.exists?
+ if required_amount_cents_changed?
+ errors.add(:required_amount_cents, "cannot be changed after deposit transactions exist")
+ end
+ if due_on_changed?
+ errors.add(:due_on, "cannot be changed after deposit transactions exist")
+ end
+ if tenancy_id_changed?
+ errors.add(:tenancy_id, "cannot be changed after deposit transactions exist")
+ end
+ end
+ end
+end
diff --git a/app/models/security_deposit_transaction.rb b/app/models/security_deposit_transaction.rb
new file mode 100644
index 00000000..9a6b4d92
--- /dev/null
+++ b/app/models/security_deposit_transaction.rb
@@ -0,0 +1,175 @@
+class SecurityDepositTransaction < ApplicationRecord
+ KINDS = %w[received refunded applied].freeze
+
+ enum :transaction_kind, {
+ received: "received",
+ refunded: "refunded",
+ applied: "applied"
+ }, validate: true
+
+ belongs_to :security_deposit
+ belongs_to :party, optional: true
+ belongs_to :charge, optional: true
+ belongs_to :superseded_by, class_name: "SecurityDepositTransaction", optional: true
+ has_one :superseded_transaction, class_name: "SecurityDepositTransaction", foreign_key: :superseded_by_id, dependent: :nullify
+
+ has_many :journal_entries, as: :source, dependent: :restrict_with_error
+ has_many :postings, through: :journal_entries
+
+ validates :amount_cents, numericality: { only_integer: true, greater_than: 0 }
+ validates :occurred_on, presence: true
+ validate :validate_occurred_on_not_in_future
+ validate :validate_kind_requirements
+ validate :validate_ownership_and_tenancy
+ validate :prevent_direct_lifecycle_assignment
+ validate :validate_immutability_when_posted, on: :update
+
+ before_destroy :prevent_destroy_if_posted
+
+ scope :active, -> { where(voided_at: nil) }
+ scope :posted, -> { where.not(posted_at: nil) }
+ scope :voided, -> { where.not(voided_at: nil) }
+ scope :superseded, -> { where.not(superseded_by_id: nil) }
+
+ def amount
+ amount_cents ? (amount_cents / 100.0) : 0.0
+ end
+
+ def amount=(val)
+ if val.nil? || (val.is_a?(String) && val.blank?)
+ write_attribute(:amount_cents, nil)
+ return
+ end
+
+ str = val.is_a?(Numeric) ? val.to_s : val.to_s.strip
+ if str.match?(/\A\d+(\.\d{1,2})?\z/)
+ self.amount_cents = (BigDecimal(str) * 100).round
+ else
+ self.amount_cents = -1
+ end
+ end
+
+ def posted?
+ posted_at.present?
+ end
+
+ def voided?
+ voided_at.present?
+ end
+
+ def superseded?
+ superseded_by_id.present?
+ end
+
+ def active?
+ posted? && !voided?
+ end
+
+ def tenancy
+ security_deposit&.tenancy
+ end
+
+ def property
+ tenancy&.property
+ end
+
+ def rentable_unit
+ tenancy&.rentable_unit
+ end
+
+ def accounting_user
+ security_deposit&.accounting_user
+ end
+
+ private
+
+ def validate_occurred_on_not_in_future
+ return unless occurred_on
+
+ if occurred_on > Date.current
+ errors.add(:occurred_on, "cannot be in the future")
+ end
+ end
+
+ def validate_kind_requirements
+ case transaction_kind
+ when "received"
+ errors.add(:party, "is required for received deposit") if party_id.blank?
+ errors.add(:charge, "must be blank for received deposit") if charge_id.present?
+ when "refunded"
+ errors.add(:party, "is required for deposit refund") if party_id.blank?
+ errors.add(:charge, "must be blank for deposit refund") if charge_id.present?
+ when "applied"
+ errors.add(:charge, "is required for deposit application") if charge_id.blank?
+ errors.add(:party, "must be blank for deposit application") if party_id.present?
+ end
+ end
+
+ def validate_ownership_and_tenancy
+ return unless security_deposit
+
+ p = party
+ if p && p.user_id != security_deposit.accounting_user&.id
+ errors.add(:party, "must belong to your account")
+ end
+
+ c = charge
+ if c
+ if c.tenancy_id != security_deposit.tenancy_id
+ errors.add(:charge, "must belong to the same tenancy as the security deposit")
+ end
+ if c.tenancy&.accounting_user != security_deposit.accounting_user
+ errors.add(:charge, "must belong to your account")
+ end
+ if applied? && occurred_on.present? && c.charge_date.present? && occurred_on < c.charge_date
+ errors.add(:occurred_on, "cannot precede the charge being settled (#{c.charge_date})")
+ end
+ end
+ end
+
+ def prevent_direct_lifecycle_assignment
+ if new_record?
+ if posted_at.present?
+ errors.add(:posted_at, "cannot be modified directly; posting is managed by the accounting service")
+ end
+ if voided_at.present?
+ errors.add(:voided_at, "cannot be modified directly; use SecurityDepositTransactions::VoidService or SecurityDepositTransactions::CorrectService")
+ end
+ if superseded_by_id.present?
+ errors.add(:superseded_by_id, "cannot be modified directly; use SecurityDepositTransactions::CorrectService")
+ end
+ else
+ if will_save_change_to_voided_at?
+ errors.add(:voided_at, "cannot be modified directly; use SecurityDepositTransactions::VoidService or SecurityDepositTransactions::CorrectService")
+ end
+ if will_save_change_to_superseded_by_id?
+ errors.add(:superseded_by_id, "cannot be modified directly; use SecurityDepositTransactions::CorrectService")
+ end
+ if will_save_change_to_posted_at?
+ errors.add(:posted_at, "cannot be modified directly; posting is managed by the accounting service")
+ end
+ end
+ end
+
+ def validate_immutability_when_posted
+ return unless posted_at_was.present?
+
+ immutable_fields = %w[
+ security_deposit_id transaction_kind amount_cents occurred_on
+ party_id charge_id external_reference memo
+ ]
+
+ immutable_fields.each do |field|
+ if will_save_change_to_attribute?(field)
+ errors.add(field.to_sym, "cannot be changed after transaction is posted")
+ end
+ end
+ end
+
+ def prevent_destroy_if_posted
+ if posted?
+ errors.add(:base, "Posted transactions cannot be deleted")
+ throw :abort
+ end
+ end
+end
diff --git a/app/models/tenancy.rb b/app/models/tenancy.rb
index b5cc3539..541a9b4d 100644
--- a/app/models/tenancy.rb
+++ b/app/models/tenancy.rb
@@ -8,6 +8,8 @@ class Tenancy < ApplicationRecord
has_many :charges, dependent: :restrict_with_error
has_many :receipts, dependent: :restrict_with_error
has_many :accounting_postings, class_name: "Posting", dependent: :restrict_with_error
+ has_one :security_deposit, dependent: :restrict_with_error
+ has_many :security_deposit_transactions, through: :security_deposit, source: :transactions
has_many :payment_ingestions, dependent: :nullify
AGREEMENT_TYPES = %w[
@@ -91,7 +93,7 @@ def most_recent_rent_term
end
def financial_history?
- charges.exists? || receipts.exists? || accounting_postings.exists?
+ charges.exists? || receipts.exists? || accounting_postings.exists? || security_deposit_transactions.exists?
end
def balance_cents(as_of: Date.current)
diff --git a/app/queries/accounting/security_deposit_balance_query.rb b/app/queries/accounting/security_deposit_balance_query.rb
new file mode 100644
index 00000000..07e24e9d
--- /dev/null
+++ b/app/queries/accounting/security_deposit_balance_query.rb
@@ -0,0 +1,42 @@
+module Accounting
+ class SecurityDepositBalanceQuery
+ def self.call(tenancy: nil, property: nil, user: nil, as_of: nil)
+ new(tenancy: tenancy, property: property, user: user).balance_cents_as_of(as_of || Date.current)
+ end
+
+ def initialize(tenancy: nil, property: nil, user: nil)
+ @tenancy = tenancy
+ @property = property || tenancy&.property
+ @user = user || tenancy&.accounting_user || @property&.user
+ end
+
+ def balance_cents_as_of(as_of = Date.current)
+ return 0 unless user
+
+ account = user.accounts.find_by(key: "security_deposits_held")
+ return 0 unless account
+
+ scope = account.postings
+ .joins(:journal_entry)
+ .where("journal_entries.occurred_on <= ?", as_of)
+
+ if tenancy
+ scope = scope.where(tenancy_id: tenancy.id)
+ elsif property
+ scope = scope.where(property_id: property.id)
+ end
+
+ # Liability postings have negative amounts for credits (deposit held).
+ # Inverting sign gives positive amount for held deposit.
+ -scope.sum(:amount_cents)
+ end
+
+ def balance_as_of(as_of = Date.current)
+ BigDecimal(balance_cents_as_of(as_of)) / 100
+ end
+
+ private
+
+ attr_reader :tenancy, :property, :user
+ end
+end
diff --git a/app/queries/properties/active_years_query.rb b/app/queries/properties/active_years_query.rb
index 52b8a289..184daa74 100644
--- a/app/queries/properties/active_years_query.rb
+++ b/app/queries/properties/active_years_query.rb
@@ -10,6 +10,7 @@ def call(additional_years: [])
years.merge(years_for(:charges, :charge_date))
years.merge(years_for(:receipts, :received_on))
years.merge(years_for(:expenses, :paid_on))
+ years.merge(years_for(:security_deposit_transactions, :occurred_on))
additional_years.each do |year|
next unless year.respond_to?(:to_i)
diff --git a/app/queries/properties/financial_items_query.rb b/app/queries/properties/financial_items_query.rb
index 2736c396..0fb4ccb1 100644
--- a/app/queries/properties/financial_items_query.rb
+++ b/app/queries/properties/financial_items_query.rb
@@ -11,7 +11,8 @@ def call(year:)
[
items_for(:charges, :charge_date, "Charge", start_date, end_date),
items_for(:receipts, :received_on, "Payment", start_date, end_date),
- items_for(:expenses, :paid_on, "Expense", start_date, end_date)
+ items_for(:expenses, :paid_on, "Expense", start_date, end_date),
+ items_for(:security_deposit_transactions, :occurred_on, "Security Deposit", start_date, end_date)
].flatten.sort_by { |item| item[:date] }
end
diff --git a/app/services/charges/correct_service.rb b/app/services/charges/correct_service.rb
index c8506642..8cb61967 100644
--- a/app/services/charges/correct_service.rb
+++ b/app/services/charges/correct_service.rb
@@ -162,6 +162,11 @@ def call
end
end
+ if charge.security_deposit_applications.active.exists?
+ failure_result = failure("Cannot correct a charge with active security deposit applications. Void or correct the deposit applications first.", :active_deposit_applications)
+ raise ActiveRecord::Rollback
+ end
+
if charge.voided?
failure_result = failure("Cannot correct a voided charge", :already_voided)
raise ActiveRecord::Rollback
diff --git a/app/services/charges/void_service.rb b/app/services/charges/void_service.rb
index 99a48c6f..6ec08e46 100644
--- a/app/services/charges/void_service.rb
+++ b/app/services/charges/void_service.rb
@@ -48,6 +48,14 @@ def call
raise ActiveRecord::Rollback
end
+ if charge.security_deposit_applications.active.exists?
+ failure_result = ServiceResult.failure(
+ error: "Cannot void a charge with active security deposit applications. Void or correct the deposit applications first.",
+ code: :active_deposit_applications
+ )
+ raise ActiveRecord::Rollback
+ end
+
description = reason.presence || "Void charge ##{charge.id}: #{charge.description || charge.charge_kind}"
effective_occurred_on = [ resolved_occurred_on, journal_entry.occurred_on ].max
diff --git a/app/services/expenses/correct_service.rb b/app/services/expenses/correct_service.rb
index 7171da61..b8f9a3cb 100644
--- a/app/services/expenses/correct_service.rb
+++ b/app/services/expenses/correct_service.rb
@@ -143,6 +143,13 @@ def call
end
active_reimbursements.each do |reimb|
+ if reimb.security_deposit_applications.active.exists?
+ return failure(
+ "Active reimbursement charge ##{reimb.id} has active security deposit applications. Void or correct the deposit applications first.",
+ :active_deposit_applications
+ )
+ end
+
reimb_tenancy = reimb.tenancy
if reimb_tenancy&.property&.id != target_prop.id
return failure(
diff --git a/app/services/security_deposit_transactions/apply_service.rb b/app/services/security_deposit_transactions/apply_service.rb
new file mode 100644
index 00000000..11995112
--- /dev/null
+++ b/app/services/security_deposit_transactions/apply_service.rb
@@ -0,0 +1,200 @@
+module SecurityDepositTransactions
+ class ApplyService
+ def self.call(security_deposit:, charge: nil, charge_id: nil, amount: nil, amount_cents: nil, occurred_on: nil, memo: nil)
+ new(
+ security_deposit: security_deposit,
+ charge: charge,
+ charge_id: charge_id,
+ amount: amount,
+ amount_cents: amount_cents,
+ occurred_on: occurred_on,
+ memo: memo
+ ).call
+ end
+
+ def initialize(security_deposit:, charge: nil, charge_id: nil, amount: nil, amount_cents: nil, occurred_on: nil, memo: nil)
+ @security_deposit = security_deposit
+ @charge = charge
+ @charge_id = charge_id
+ @raw_amount = amount
+ @raw_cents = amount_cents
+ @raw_occurred_on = occurred_on
+ @memo = memo
+ end
+
+ def call
+ unless security_deposit.is_a?(SecurityDeposit) && security_deposit.persisted? && !security_deposit.destroyed?
+ return ServiceResult.failure(error: "Security deposit must be a persisted record", code: :invalid_deposit)
+ end
+
+ res_charge = resolve_charge
+ unless res_charge.is_a?(Charge) && res_charge.persisted? && !res_charge.destroyed?
+ return ServiceResult.failure(error: "Charge must be a persisted record", code: :invalid_charge)
+ end
+
+ if res_charge.tenancy_id != security_deposit.tenancy_id
+ return ServiceResult.failure(error: "Charge must belong to the same tenancy as the security deposit", code: :tenancy_mismatch)
+ end
+
+ cents = resolve_cents
+ if cents.nil? || !cents.positive?
+ return ServiceResult.failure(error: "Amount must be greater than zero", code: :invalid_input)
+ end
+
+ if raw_occurred_on.blank?
+ return ServiceResult.failure(error: "Occurred on date is required", code: :invalid_input)
+ end
+
+ occ_date = resolve_occurred_on
+ unless occ_date
+ return ServiceResult.failure(error: "Invalid occurred on date", code: :invalid_input)
+ end
+
+ if occ_date > Date.current
+ return ServiceResult.failure(error: "Occurred on date cannot be in the future", code: :invalid_date)
+ end
+
+ created_txn = nil # : SecurityDepositTransaction?
+ journal_entry = nil # : JournalEntry?
+ failure_res = nil # : (Dry::Monads::Result::Success | Dry::Monads::Result::Failure)?
+
+ SecurityDeposit.transaction do
+ # Enforce lock order: SecurityDeposit -> Charge
+ security_deposit.lock!
+ res_charge.lock!
+
+ unless res_charge.posted? && res_charge.active?
+ failure_res = ServiceResult.failure(error: "Cannot apply deposit to an inactive or unposted charge", code: :invalid_charge_state)
+ raise ActiveRecord::Rollback
+ end
+
+ if occ_date < res_charge.charge_date
+ failure_res = ServiceResult.failure(
+ error: "Application date (#{occ_date}) cannot precede the charge date (#{res_charge.charge_date})",
+ code: :precedes_charge_date
+ )
+ raise ActiveRecord::Rollback
+ end
+
+ remaining_charge_cap = res_charge.remaining_deposit_application_cents
+ if cents > remaining_charge_cap
+ failure_res = ServiceResult.failure(
+ error: "Applied amount (#{format_money(cents)}) exceeds charge remaining capacity (#{format_money(remaining_charge_cap)})",
+ code: :exceeds_charge_capacity
+ )
+ raise ActiveRecord::Rollback
+ end
+
+ outstanding_balance = security_deposit.tenancy.balance_cents(as_of: occ_date)
+ if cents > outstanding_balance
+ failure_res = ServiceResult.failure(
+ error: "Applied amount (#{format_money(cents)}) exceeds tenancy outstanding balance (#{format_money(outstanding_balance)}) as of #{occ_date}",
+ code: :exceeds_tenancy_balance
+ )
+ raise ActiveRecord::Rollback
+ end
+
+ timeline_res = SecurityDeposits::LiabilityTimeline.validate(
+ security_deposit: security_deposit,
+ additions: [ { occurred_on: occ_date, delta_cents: -cents } ]
+ )
+ unless timeline_res.success?
+ failure_res = timeline_res
+ raise ActiveRecord::Rollback
+ end
+
+ txn = security_deposit.transactions.create!(
+ transaction_kind: "applied",
+ charge: res_charge,
+ amount_cents: cents,
+ occurred_on: occ_date,
+ memo: memo
+ )
+
+ post_res = post_transaction(txn)
+ unless post_res.success?
+ failure_res = post_res
+ raise ActiveRecord::Rollback
+ end
+
+ txn.update_columns(posted_at: Time.current)
+ created_txn = txn
+ journal_entry = post_res.value!.data[:journal_entry]
+ end
+
+ if (f = failure_res)
+ f
+ elsif (t = created_txn)
+ ServiceResult.success(transaction: t, journal_entry: journal_entry)
+ else
+ ServiceResult.failure(error: "Failed to apply security deposit", code: :application_failed)
+ end
+ end
+
+ private
+
+ attr_reader :security_deposit, :charge, :charge_id, :raw_amount, :raw_cents, :raw_occurred_on, :memo
+
+ def post_transaction(txn)
+ postings = [
+ Accounting::PostingSpec.new(
+ account_key: "security_deposits_held",
+ amount_cents: txn.amount_cents,
+ tenancy: txn.tenancy
+ ),
+ Accounting::PostingSpec.new(
+ account_key: "tenant_receivable",
+ amount_cents: -txn.amount_cents,
+ tenancy: txn.tenancy
+ )
+ ]
+
+ charge_desc = txn.charge&.description || txn.charge&.charge_kind&.titleize || "charge"
+ default_desc = "Security deposit applied to #{charge_desc}"
+
+ Accounting::PostEntryService.call(
+ source: txn,
+ event_type: "deposit_applied",
+ occurred_on: txn.occurred_on,
+ postings: postings,
+ description: txn.memo.presence || default_desc
+ )
+ end
+
+ def resolve_charge
+ return charge if charge.is_a?(Charge)
+ return Charge.find_by(id: charge_id) if charge_id.present?
+
+ nil
+ end
+
+ def resolve_cents
+ if raw_cents.present?
+ return raw_cents if raw_cents.is_a?(Integer)
+
+ nil
+ elsif raw_amount.present?
+ str = raw_amount.is_a?(Numeric) ? raw_amount.to_s : raw_amount.to_s.strip
+ return nil unless str.match?(/\A\d+(\.\d{1,2})?\z/)
+
+ (BigDecimal(str) * 100).round
+ else
+ nil
+ end
+ end
+
+ def resolve_occurred_on
+ return nil if raw_occurred_on.blank?
+ return raw_occurred_on if raw_occurred_on.is_a?(Date)
+ return raw_occurred_on.to_date if raw_occurred_on.respond_to?(:to_date)
+
+ Date.parse(raw_occurred_on.to_s)
+ rescue ArgumentError, Date::Error
+ nil
+ end
+
+ def format_money(cents)
+ sprintf("$%.2f", cents.to_f / 100)
+ end
+ end
+end
diff --git a/app/services/security_deposit_transactions/correct_service.rb b/app/services/security_deposit_transactions/correct_service.rb
new file mode 100644
index 00000000..a0432a64
--- /dev/null
+++ b/app/services/security_deposit_transactions/correct_service.rb
@@ -0,0 +1,383 @@
+module SecurityDepositTransactions
+ class CorrectService
+ def self.call(
+ transaction:,
+ amount: :not_set,
+ amount_cents: :not_set,
+ occurred_on: :not_set,
+ party: :not_set,
+ party_id: :not_set,
+ charge: :not_set,
+ charge_id: :not_set,
+ external_reference: :not_set,
+ memo: :not_set
+ )
+ new(
+ transaction: transaction,
+ amount: amount,
+ amount_cents: amount_cents,
+ occurred_on: occurred_on,
+ party: party,
+ party_id: party_id,
+ charge: charge,
+ charge_id: charge_id,
+ external_reference: external_reference,
+ memo: memo
+ ).call
+ end
+
+ def initialize(
+ transaction:,
+ amount: :not_set,
+ amount_cents: :not_set,
+ occurred_on: :not_set,
+ party: :not_set,
+ party_id: :not_set,
+ charge: :not_set,
+ charge_id: :not_set,
+ external_reference: :not_set,
+ memo: :not_set
+ )
+ @transaction = transaction
+ @raw_amount = amount
+ @raw_cents = amount_cents
+ @raw_occurred_on = occurred_on
+ @party = party
+ @party_id = party_id
+ @charge = charge
+ @charge_id = charge_id
+ @external_reference = external_reference
+ @memo = memo
+ end
+
+ def call
+ unless transaction.is_a?(SecurityDepositTransaction) && transaction.persisted? && !transaction.destroyed?
+ return ServiceResult.failure(error: "Transaction must be a persisted SecurityDepositTransaction record", code: :invalid_source)
+ end
+
+ deposit = transaction.security_deposit
+ unless deposit
+ return ServiceResult.failure(error: "Security deposit not found", code: :not_found)
+ end
+
+ cents = if raw_cents == :not_set && raw_amount == :not_set
+ transaction.amount_cents
+ else
+ resolve_cents
+ end
+
+ if cents.nil? || !cents.positive?
+ return ServiceResult.failure(error: "Amount must be greater than zero", code: :invalid_input)
+ end
+
+ occ_date = if raw_occurred_on == :not_set
+ transaction.occurred_on
+ else
+ resolve_occurred_on
+ end
+
+ unless occ_date
+ return ServiceResult.failure(error: "Occurred on date is invalid", code: :invalid_date)
+ end
+
+ if occ_date > Date.current
+ return ServiceResult.failure(error: "Occurred on date cannot be in the future", code: :invalid_date)
+ end
+
+ # Resolve party for received/refunded
+ res_party = nil # : Party?
+ if transaction.received? || transaction.refunded?
+ if party == :not_set && party_id == :not_set
+ res_party = transaction.party
+ elsif party.is_a?(Party)
+ res_party = party
+ elsif party_id != :not_set && party_id.present?
+ res_party = Party.find_by(id: party_id)
+ unless res_party
+ return ServiceResult.failure(error: "Party not found", code: :invalid_party)
+ end
+ else
+ return ServiceResult.failure(error: "Party is required", code: :invalid_party)
+ end
+
+ if res_party && res_party.user_id != deposit.accounting_user&.id
+ return ServiceResult.failure(error: "Party must belong to your account", code: :party_user_mismatch)
+ end
+ end
+
+ # Resolve charge for applied
+ res_charge = nil # : Charge?
+ if transaction.applied?
+ if charge == :not_set && charge_id == :not_set
+ res_charge = transaction.charge
+ elsif charge.is_a?(Charge)
+ res_charge = charge
+ elsif charge_id != :not_set && charge_id.present?
+ res_charge = Charge.find_by(id: charge_id)
+ unless res_charge
+ return ServiceResult.failure(error: "Charge not found", code: :invalid_charge)
+ end
+ else
+ return ServiceResult.failure(error: "Charge is required", code: :invalid_charge)
+ end
+ end
+
+ res_memo = if memo == :not_set
+ transaction.memo
+ elsif memo.present?
+ memo.to_s.strip
+ else
+ nil
+ end
+
+ res_ext = if external_reference == :not_set
+ transaction.external_reference
+ elsif external_reference.present?
+ external_reference.to_s.strip
+ else
+ nil
+ end
+
+ failure_result = nil # : (Dry::Monads::Result::Success | Dry::Monads::Result::Failure)?
+ success_result = nil # : (Dry::Monads::Result::Success | Dry::Monads::Result::Failure)?
+
+ SecurityDeposit.transaction do
+ # Enforce lock order: SecurityDeposit -> Charge(s) -> SecurityDepositTransaction
+ deposit.lock!
+
+ charges_to_lock = [ transaction.charge, res_charge ].compact.uniq.sort_by(&:id)
+ charges_to_lock.each do |c|
+ c.lock!
+ c.reload
+ end
+
+ transaction.lock!
+ transaction.reload
+
+ # 1. Check if already superseded (Idempotency)
+ if transaction.superseded?
+ replacement = transaction.superseded_by
+ reversal = transaction.journal_entries.find_by(event_type: "deposit_#{transaction.transaction_kind}")&.reversal
+
+ if replacement &&
+ replacement.amount_cents == cents &&
+ replacement.occurred_on == occ_date &&
+ replacement.party_id == res_party&.id &&
+ replacement.charge_id == res_charge&.id &&
+ replacement.memo.to_s.strip == res_memo.to_s.strip &&
+ replacement.external_reference.to_s.strip == res_ext.to_s.strip
+ success_result = ServiceResult.success(original: transaction, replacement: replacement, reversal: reversal)
+ else
+ failure_result = ServiceResult.failure(
+ error: "Cannot correct an already superseded transaction with different parameters",
+ code: :idempotency_conflict
+ )
+ end
+ raise ActiveRecord::Rollback
+ end
+
+ if transaction.voided?
+ failure_result = ServiceResult.failure(error: "Cannot correct a voided deposit transaction", code: :already_voided)
+ raise ActiveRecord::Rollback
+ end
+
+ # 2. Kind-specific validations for replacement after locks acquired
+ case transaction.transaction_kind
+ when "received", "refunded"
+ unless res_party
+ failure_result = ServiceResult.failure(error: "Party is required", code: :invalid_party)
+ raise ActiveRecord::Rollback
+ end
+ when "applied"
+ unless res_charge
+ failure_result = ServiceResult.failure(error: "Charge is required", code: :invalid_charge)
+ raise ActiveRecord::Rollback
+ end
+ if res_charge.tenancy_id != deposit.tenancy_id
+ failure_result = ServiceResult.failure(error: "Charge must belong to the same tenancy", code: :tenancy_mismatch)
+ raise ActiveRecord::Rollback
+ end
+ unless res_charge.posted? && res_charge.active?
+ failure_result = ServiceResult.failure(error: "Target charge is inactive or unposted", code: :invalid_charge_state)
+ raise ActiveRecord::Rollback
+ end
+
+ if occ_date < res_charge.charge_date
+ failure_result = ServiceResult.failure(
+ error: "Application date (#{occ_date}) cannot precede the charge date (#{res_charge.charge_date})",
+ code: :precedes_charge_date
+ )
+ raise ActiveRecord::Rollback
+ end
+
+ prior_apps_cents = res_charge.security_deposit_applications.active.where.not(id: transaction.id).sum(:amount_cents)
+ remaining_cap = res_charge.amount_cents.to_i - prior_apps_cents.to_i
+ if cents > remaining_cap
+ failure_result = ServiceResult.failure(
+ error: "Applied amount (#{format_money(cents)}) exceeds remaining capacity for this charge (#{format_money(remaining_cap)})",
+ code: :exceeds_charge_capacity
+ )
+ raise ActiveRecord::Rollback
+ end
+
+ current_ar = deposit.tenancy.balance_cents(as_of: occ_date)
+ effective_ar = current_ar + (occ_date >= transaction.occurred_on ? transaction.amount_cents : 0)
+ if cents > effective_ar
+ failure_result = ServiceResult.failure(
+ error: "Applied amount (#{format_money(cents)}) exceeds tenancy outstanding balance (#{format_money(effective_ar)}) as of #{occ_date}",
+ code: :exceeds_tenancy_balance
+ )
+ raise ActiveRecord::Rollback
+ end
+ end
+
+ # 3. Timeline validation
+ replacement_delta = transaction.received? ? cents : -cents
+ timeline_res = SecurityDeposits::LiabilityTimeline.validate(
+ security_deposit: deposit,
+ removing_ids: [ transaction.id ],
+ additions: [ { occurred_on: occ_date, delta_cents: replacement_delta } ]
+ )
+ unless timeline_res.success?
+ failure_result = timeline_res
+ raise ActiveRecord::Rollback
+ end
+
+ # 4. Reverse original entry
+ entry_event = "deposit_#{transaction.transaction_kind}"
+ journal_entry = transaction.journal_entries.find_by(event_type: entry_event)
+ unless journal_entry
+ failure_result = ServiceResult.failure(error: "Original journal entry not found", code: :not_found)
+ raise ActiveRecord::Rollback
+ end
+
+ rev_res = Accounting::ReverseEntryService.call(
+ journal_entry: journal_entry,
+ occurred_on: transaction.occurred_on,
+ description: "Correction of deposit transaction ##{transaction.id}"
+ )
+ unless rev_res.success?
+ failure_result = rev_res
+ raise ActiveRecord::Rollback
+ end
+ reversal = rev_res.value!.data[:journal_entry]
+
+ # 5. Create replacement transaction
+ replacement = SecurityDepositTransaction.new(
+ security_deposit: deposit,
+ transaction_kind: transaction.transaction_kind,
+ amount_cents: cents,
+ occurred_on: occ_date,
+ party: (transaction.applied? ? nil : res_party),
+ charge: (transaction.applied? ? res_charge : nil),
+ external_reference: res_ext,
+ memo: res_memo
+ )
+
+ unless replacement.save
+ failure_result = ServiceResult.failure(error: replacement.errors.full_messages.join(", "), code: :validation_error)
+ raise ActiveRecord::Rollback
+ end
+
+ post_res = post_replacement(replacement)
+ unless post_res.success?
+ failure_result = post_res
+ raise ActiveRecord::Rollback
+ end
+
+ replacement.update_columns(posted_at: Time.current)
+ transaction.update_columns(
+ voided_at: Time.current,
+ superseded_by_id: replacement.id
+ )
+
+ success_result = ServiceResult.success(original: transaction, replacement: replacement, reversal: reversal)
+ end
+
+ if (s = success_result)
+ s
+ elsif (f = failure_result)
+ f
+ else
+ ServiceResult.failure(error: "Failed to correct deposit transaction", code: :correction_failed)
+ end
+ end
+
+ private
+
+ attr_reader :transaction, :raw_amount, :raw_cents, :raw_occurred_on, :party, :party_id, :charge, :charge_id, :external_reference, :memo
+
+ def post_replacement(rep)
+ case rep.transaction_kind
+ when "received"
+ postings = [
+ Accounting::PostingSpec.new(account_key: "cash", amount_cents: rep.amount_cents, tenancy: rep.tenancy, party: rep.party),
+ Accounting::PostingSpec.new(account_key: "security_deposits_held", amount_cents: -rep.amount_cents, tenancy: rep.tenancy, party: rep.party)
+ ]
+ Accounting::PostEntryService.call(
+ source: rep,
+ event_type: "deposit_received",
+ occurred_on: rep.occurred_on,
+ postings: postings,
+ description: rep.memo.presence || "Security deposit received"
+ )
+ when "refunded"
+ postings = [
+ Accounting::PostingSpec.new(account_key: "security_deposits_held", amount_cents: rep.amount_cents, tenancy: rep.tenancy, party: rep.party),
+ Accounting::PostingSpec.new(account_key: "cash", amount_cents: -rep.amount_cents, tenancy: rep.tenancy, party: rep.party)
+ ]
+ Accounting::PostEntryService.call(
+ source: rep,
+ event_type: "deposit_refunded",
+ occurred_on: rep.occurred_on,
+ postings: postings,
+ description: rep.memo.presence || "Security deposit refund"
+ )
+ when "applied"
+ postings = [
+ Accounting::PostingSpec.new(account_key: "security_deposits_held", amount_cents: rep.amount_cents, tenancy: rep.tenancy),
+ Accounting::PostingSpec.new(account_key: "tenant_receivable", amount_cents: -rep.amount_cents, tenancy: rep.tenancy)
+ ]
+ charge_desc = rep.charge&.description || rep.charge&.charge_kind&.titleize || "charge"
+ Accounting::PostEntryService.call(
+ source: rep,
+ event_type: "deposit_applied",
+ occurred_on: rep.occurred_on,
+ postings: postings,
+ description: rep.memo.presence || "Security deposit applied to #{charge_desc}"
+ )
+ else
+ ServiceResult.failure(error: "Unknown transaction kind", code: :invalid_input)
+ end
+ end
+
+ def resolve_cents
+ if raw_cents != :not_set && raw_cents.present?
+ return raw_cents if raw_cents.is_a?(Integer)
+
+ nil
+ elsif raw_amount != :not_set && raw_amount.present?
+ str = raw_amount.is_a?(Numeric) ? raw_amount.to_s : raw_amount.to_s.strip
+ return nil unless str.match?(/\A\d+(\.\d{1,2})?\z/)
+
+ (BigDecimal(str) * 100).round
+ else
+ nil
+ end
+ end
+
+ def resolve_occurred_on
+ return raw_occurred_on if raw_occurred_on.is_a?(Date)
+ return raw_occurred_on.to_date if raw_occurred_on.respond_to?(:to_date)
+ return nil if raw_occurred_on.blank? || raw_occurred_on == :not_set
+
+ Date.parse(raw_occurred_on.to_s)
+ rescue ArgumentError, Date::Error
+ nil
+ end
+
+ def format_money(cents)
+ sprintf("$%.2f", cents.to_f / 100)
+ end
+ end
+end
diff --git a/app/services/security_deposit_transactions/receive_service.rb b/app/services/security_deposit_transactions/receive_service.rb
new file mode 100644
index 00000000..cf3f10d7
--- /dev/null
+++ b/app/services/security_deposit_transactions/receive_service.rb
@@ -0,0 +1,163 @@
+module SecurityDepositTransactions
+ class ReceiveService
+ def self.call(security_deposit:, party: nil, party_id: nil, amount: nil, amount_cents: nil, occurred_on: nil, external_reference: nil, memo: nil)
+ new(
+ security_deposit: security_deposit,
+ party: party,
+ party_id: party_id,
+ amount: amount,
+ amount_cents: amount_cents,
+ occurred_on: occurred_on,
+ external_reference: external_reference,
+ memo: memo
+ ).call
+ end
+
+ def initialize(security_deposit:, party: nil, party_id: nil, amount: nil, amount_cents: nil, occurred_on: nil, external_reference: nil, memo: nil)
+ @security_deposit = security_deposit
+ @party = party
+ @party_id = party_id
+ @raw_amount = amount
+ @raw_cents = amount_cents
+ @raw_occurred_on = occurred_on
+ @external_reference = external_reference
+ @memo = memo
+ end
+
+ def call
+ unless security_deposit.is_a?(SecurityDeposit) && security_deposit.persisted? && !security_deposit.destroyed?
+ return ServiceResult.failure(error: "Security deposit must be a persisted record", code: :invalid_deposit)
+ end
+
+ res_party = resolve_party
+ unless res_party.is_a?(Party) && res_party.persisted? && !res_party.destroyed?
+ return ServiceResult.failure(error: "Party must be a persisted record", code: :invalid_party)
+ end
+
+ if res_party.user_id != security_deposit.accounting_user&.id
+ return ServiceResult.failure(error: "Party must belong to your account", code: :party_user_mismatch)
+ end
+
+ cents = resolve_cents
+ if cents.nil? || !cents.positive?
+ return ServiceResult.failure(error: "Amount must be greater than zero", code: :invalid_input)
+ end
+
+ if raw_occurred_on.blank?
+ return ServiceResult.failure(error: "Occurred on date is required", code: :invalid_input)
+ end
+
+ occ_date = resolve_occurred_on
+ unless occ_date
+ return ServiceResult.failure(error: "Invalid occurred on date", code: :invalid_input)
+ end
+
+ if occ_date > Date.current
+ return ServiceResult.failure(error: "Occurred on date cannot be in the future", code: :invalid_date)
+ end
+
+ created_txn = nil # : SecurityDepositTransaction?
+ journal_entry = nil # : JournalEntry?
+ failure_res = nil # : (Dry::Monads::Result::Success | Dry::Monads::Result::Failure)?
+
+ security_deposit.with_lock do
+ timeline_res = SecurityDeposits::LiabilityTimeline.validate(
+ security_deposit: security_deposit,
+ additions: [ { occurred_on: occ_date, delta_cents: cents } ]
+ )
+ unless timeline_res.success?
+ failure_res = timeline_res
+ raise ActiveRecord::Rollback
+ end
+
+ txn = security_deposit.transactions.create!(
+ transaction_kind: "received",
+ amount_cents: cents,
+ occurred_on: occ_date,
+ party: res_party,
+ external_reference: external_reference,
+ memo: memo
+ )
+
+ post_res = post_transaction(txn)
+ unless post_res.success?
+ failure_res = post_res
+ raise ActiveRecord::Rollback
+ end
+
+ txn.update_columns(posted_at: Time.current)
+ created_txn = txn
+ journal_entry = post_res.value!.data[:journal_entry]
+ end
+
+ if (f = failure_res)
+ f
+ elsif (t = created_txn)
+ ServiceResult.success(transaction: t, journal_entry: journal_entry)
+ else
+ ServiceResult.failure(error: "Failed to record deposit receipt", code: :receipt_failed)
+ end
+ end
+
+ private
+
+ attr_reader :security_deposit, :party, :party_id, :raw_amount, :raw_cents, :raw_occurred_on, :external_reference, :memo
+
+ def post_transaction(txn)
+ postings = [
+ Accounting::PostingSpec.new(
+ account_key: "cash",
+ amount_cents: txn.amount_cents,
+ tenancy: txn.tenancy,
+ party: txn.party
+ ),
+ Accounting::PostingSpec.new(
+ account_key: "security_deposits_held",
+ amount_cents: -txn.amount_cents,
+ tenancy: txn.tenancy,
+ party: txn.party
+ )
+ ]
+
+ Accounting::PostEntryService.call(
+ source: txn,
+ event_type: "deposit_received",
+ occurred_on: txn.occurred_on,
+ postings: postings,
+ description: txn.memo.presence || "Security deposit received"
+ )
+ end
+
+ def resolve_party
+ return party if party.is_a?(Party)
+ return Party.find_by(id: party_id) if party_id.present?
+
+ nil
+ end
+
+ def resolve_cents
+ if raw_cents.present?
+ return raw_cents if raw_cents.is_a?(Integer)
+
+ nil
+ elsif raw_amount.present?
+ str = raw_amount.is_a?(Numeric) ? raw_amount.to_s : raw_amount.to_s.strip
+ return nil unless str.match?(/\A\d+(\.\d{1,2})?\z/)
+
+ (BigDecimal(str) * 100).round
+ else
+ nil
+ end
+ end
+
+ def resolve_occurred_on
+ return nil if raw_occurred_on.blank?
+ return raw_occurred_on if raw_occurred_on.is_a?(Date)
+ return raw_occurred_on.to_date if raw_occurred_on.respond_to?(:to_date)
+
+ Date.parse(raw_occurred_on.to_s)
+ rescue ArgumentError, Date::Error
+ nil
+ end
+ end
+end
diff --git a/app/services/security_deposit_transactions/refund_service.rb b/app/services/security_deposit_transactions/refund_service.rb
new file mode 100644
index 00000000..915336f1
--- /dev/null
+++ b/app/services/security_deposit_transactions/refund_service.rb
@@ -0,0 +1,163 @@
+module SecurityDepositTransactions
+ class RefundService
+ def self.call(security_deposit:, party: nil, party_id: nil, amount: nil, amount_cents: nil, occurred_on: nil, external_reference: nil, memo: nil)
+ new(
+ security_deposit: security_deposit,
+ party: party,
+ party_id: party_id,
+ amount: amount,
+ amount_cents: amount_cents,
+ occurred_on: occurred_on,
+ external_reference: external_reference,
+ memo: memo
+ ).call
+ end
+
+ def initialize(security_deposit:, party: nil, party_id: nil, amount: nil, amount_cents: nil, occurred_on: nil, external_reference: nil, memo: nil)
+ @security_deposit = security_deposit
+ @party = party
+ @party_id = party_id
+ @raw_amount = amount
+ @raw_cents = amount_cents
+ @raw_occurred_on = occurred_on
+ @external_reference = external_reference
+ @memo = memo
+ end
+
+ def call
+ unless security_deposit.is_a?(SecurityDeposit) && security_deposit.persisted? && !security_deposit.destroyed?
+ return ServiceResult.failure(error: "Security deposit must be a persisted record", code: :invalid_deposit)
+ end
+
+ res_party = resolve_party
+ unless res_party.is_a?(Party) && res_party.persisted? && !res_party.destroyed?
+ return ServiceResult.failure(error: "Party must be a persisted record", code: :invalid_party)
+ end
+
+ if res_party.user_id != security_deposit.accounting_user&.id
+ return ServiceResult.failure(error: "Party must belong to your account", code: :party_user_mismatch)
+ end
+
+ cents = resolve_cents
+ if cents.nil? || !cents.positive?
+ return ServiceResult.failure(error: "Amount must be greater than zero", code: :invalid_input)
+ end
+
+ if raw_occurred_on.blank?
+ return ServiceResult.failure(error: "Occurred on date is required", code: :invalid_input)
+ end
+
+ occ_date = resolve_occurred_on
+ unless occ_date
+ return ServiceResult.failure(error: "Invalid occurred on date", code: :invalid_input)
+ end
+
+ if occ_date > Date.current
+ return ServiceResult.failure(error: "Occurred on date cannot be in the future", code: :invalid_date)
+ end
+
+ created_txn = nil # : SecurityDepositTransaction?
+ journal_entry = nil # : JournalEntry?
+ failure_res = nil # : (Dry::Monads::Result::Success | Dry::Monads::Result::Failure)?
+
+ security_deposit.with_lock do
+ timeline_res = SecurityDeposits::LiabilityTimeline.validate(
+ security_deposit: security_deposit,
+ additions: [ { occurred_on: occ_date, delta_cents: -cents } ]
+ )
+ unless timeline_res.success?
+ failure_res = timeline_res
+ raise ActiveRecord::Rollback
+ end
+
+ txn = security_deposit.transactions.create!(
+ transaction_kind: "refunded",
+ party: res_party,
+ amount_cents: cents,
+ occurred_on: occ_date,
+ external_reference: external_reference,
+ memo: memo
+ )
+
+ post_res = post_transaction(txn)
+ unless post_res.success?
+ failure_res = post_res
+ raise ActiveRecord::Rollback
+ end
+
+ txn.update_columns(posted_at: Time.current)
+ created_txn = txn
+ journal_entry = post_res.value!.data[:journal_entry]
+ end
+
+ if (f = failure_res)
+ f
+ elsif (t = created_txn)
+ ServiceResult.success(transaction: t, journal_entry: journal_entry)
+ else
+ ServiceResult.failure(error: "Failed to record deposit refund", code: :refund_failed)
+ end
+ end
+
+ private
+
+ attr_reader :security_deposit, :party, :party_id, :raw_amount, :raw_cents, :raw_occurred_on, :external_reference, :memo
+
+ def post_transaction(txn)
+ postings = [
+ Accounting::PostingSpec.new(
+ account_key: "security_deposits_held",
+ amount_cents: txn.amount_cents,
+ tenancy: txn.tenancy,
+ party: txn.party
+ ),
+ Accounting::PostingSpec.new(
+ account_key: "cash",
+ amount_cents: -txn.amount_cents,
+ tenancy: txn.tenancy,
+ party: txn.party
+ )
+ ]
+
+ Accounting::PostEntryService.call(
+ source: txn,
+ event_type: "deposit_refunded",
+ occurred_on: txn.occurred_on,
+ postings: postings,
+ description: txn.memo.presence || "Security deposit refund"
+ )
+ end
+
+ def resolve_party
+ return party if party.is_a?(Party)
+ return Party.find_by(id: party_id) if party_id.present?
+
+ nil
+ end
+
+ def resolve_cents
+ if raw_cents.present?
+ return raw_cents if raw_cents.is_a?(Integer)
+
+ nil
+ elsif raw_amount.present?
+ str = raw_amount.is_a?(Numeric) ? raw_amount.to_s : raw_amount.to_s.strip
+ return nil unless str.match?(/\A\d+(\.\d{1,2})?\z/)
+
+ (BigDecimal(str) * 100).round
+ else
+ nil
+ end
+ end
+
+ def resolve_occurred_on
+ return nil if raw_occurred_on.blank?
+ return raw_occurred_on if raw_occurred_on.is_a?(Date)
+ return raw_occurred_on.to_date if raw_occurred_on.respond_to?(:to_date)
+
+ Date.parse(raw_occurred_on.to_s)
+ rescue ArgumentError, Date::Error
+ nil
+ end
+ end
+end
diff --git a/app/services/security_deposit_transactions/void_service.rb b/app/services/security_deposit_transactions/void_service.rb
new file mode 100644
index 00000000..4f19a68c
--- /dev/null
+++ b/app/services/security_deposit_transactions/void_service.rb
@@ -0,0 +1,100 @@
+module SecurityDepositTransactions
+ class VoidService
+ def self.call(transaction:, reason: nil)
+ new(transaction: transaction, reason: reason).call
+ end
+
+ def initialize(transaction:, reason: nil)
+ @transaction = transaction
+ @reason = reason
+ end
+
+ def call
+ unless transaction.is_a?(SecurityDepositTransaction) && transaction.persisted? && !transaction.destroyed?
+ return ServiceResult.failure(error: "Transaction must be a persisted SecurityDepositTransaction record", code: :invalid_source)
+ end
+
+ deposit = transaction.security_deposit
+ unless deposit
+ return ServiceResult.failure(error: "Security deposit not found", code: :not_found)
+ end
+
+ entry_event = "deposit_#{transaction.transaction_kind}"
+ journal_entry = transaction.journal_entries.find_by(event_type: entry_event)
+ unless journal_entry
+ return ServiceResult.failure(error: "Journal entry not found for deposit transaction", code: :not_found)
+ end
+
+ reversal_entry = nil # : JournalEntry?
+ failure_result = nil # : (Dry::Monads::Result::Success | Dry::Monads::Result::Failure)?
+ success_result = nil # : (Dry::Monads::Result::Success | Dry::Monads::Result::Failure)?
+
+ SecurityDeposit.transaction do
+ deposit.lock!
+ transaction.lock!
+
+ if transaction.superseded?
+ failure_result = ServiceResult.failure(
+ error: "Cannot void an already superseded deposit transaction",
+ code: :already_superseded
+ )
+ raise ActiveRecord::Rollback
+ end
+
+ description = reason.presence || "Void deposit transaction ##{transaction.id}: #{transaction.transaction_kind}"
+
+ if transaction.voided?
+ existing_reversal = journal_entry.reversal
+ if existing_reversal &&
+ existing_reversal.occurred_on == transaction.occurred_on &&
+ existing_reversal.description.to_s.strip == description.to_s.strip
+ success_result = ServiceResult.success(transaction: transaction, journal_entry: existing_reversal)
+ else
+ failure_result = ServiceResult.failure(
+ error: "Cannot void an already voided transaction with different parameters",
+ code: :idempotency_conflict
+ )
+ end
+ raise ActiveRecord::Rollback
+ end
+
+ timeline_res = SecurityDeposits::LiabilityTimeline.validate(
+ security_deposit: deposit,
+ removing_ids: [ transaction.id ]
+ )
+ unless timeline_res.success?
+ failure_result = timeline_res
+ raise ActiveRecord::Rollback
+ end
+
+ reverse_result = Accounting::ReverseEntryService.call(
+ journal_entry: journal_entry,
+ occurred_on: transaction.occurred_on,
+ description: description
+ )
+
+ unless reverse_result.success?
+ failure_result = reverse_result
+ raise ActiveRecord::Rollback
+ end
+
+ reversal_entry = reverse_result.value!.data[:journal_entry]
+ transaction.update_columns(voided_at: Time.current)
+ end
+
+ if (s = success_result)
+ s
+ elsif (f = failure_result)
+ f
+ elsif (r = reversal_entry)
+ ServiceResult.success(transaction: transaction, journal_entry: r)
+ else
+ ServiceResult.failure(error: "Failed to void deposit transaction", code: :void_failed)
+ end
+ end
+
+ private
+
+ attr_reader :transaction, :reason
+ end
+end
diff --git a/app/services/security_deposits/create_service.rb b/app/services/security_deposits/create_service.rb
new file mode 100644
index 00000000..9cd848ef
--- /dev/null
+++ b/app/services/security_deposits/create_service.rb
@@ -0,0 +1,86 @@
+module SecurityDeposits
+ class CreateService
+ def self.call(tenancy:, required_amount: nil, required_amount_cents: nil, due_on: nil)
+ new(
+ tenancy: tenancy,
+ required_amount: required_amount,
+ required_amount_cents: required_amount_cents,
+ due_on: due_on
+ ).call
+ end
+
+ def initialize(tenancy:, required_amount: nil, required_amount_cents: nil, due_on: nil)
+ @tenancy = tenancy
+ @raw_amount = required_amount
+ @raw_cents = required_amount_cents
+ @raw_due_on = due_on
+ end
+
+ def call
+ unless tenancy.is_a?(Tenancy) && tenancy.persisted? && !tenancy.destroyed?
+ return ServiceResult.failure(error: "Tenancy must be a persisted Tenancy record", code: :invalid_tenancy)
+ end
+
+ cents = resolve_cents
+ return ServiceResult.failure(error: "Required amount must be greater than zero", code: :invalid_input) unless cents&.positive?
+
+ due_date = resolve_due_on
+ return ServiceResult.failure(error: "Due date is required", code: :invalid_input) unless due_date
+
+ tenancy.with_lock do
+ existing = tenancy.security_deposit
+ if existing
+ if existing.required_amount_cents == cents && existing.due_on == due_date
+ return ServiceResult.success(security_deposit: existing)
+ else
+ return ServiceResult.failure(
+ error: "A security deposit requirement already exists for this tenancy with different terms",
+ code: :conflict
+ )
+ end
+ end
+
+ deposit = SecurityDeposit.new(
+ tenancy: tenancy,
+ required_amount_cents: cents,
+ due_on: due_date
+ )
+
+ if deposit.save
+ ServiceResult.success(security_deposit: deposit)
+ else
+ ServiceResult.failure(error: deposit.errors.full_messages.join(", "), code: :validation_error)
+ end
+ end
+ end
+
+ private
+
+ attr_reader :tenancy, :raw_amount, :raw_cents, :raw_due_on
+
+ def resolve_cents
+ if raw_cents.present?
+ return raw_cents if raw_cents.is_a?(Integer)
+
+ nil
+ elsif raw_amount.present?
+ str = raw_amount.is_a?(Numeric) ? raw_amount.to_s : raw_amount.to_s.strip
+ return nil unless str.match?(/\A\d+(\.\d{1,2})?\z/)
+
+ (BigDecimal(str) * 100).round
+ else
+ nil
+ end
+ end
+
+ def resolve_due_on
+ return raw_due_on if raw_due_on.is_a?(Date)
+ return raw_due_on.to_date if raw_due_on.respond_to?(:to_date)
+ return nil if raw_due_on.blank?
+
+ Date.parse(raw_due_on.to_s)
+ rescue ArgumentError, Date::Error
+ nil
+ end
+ end
+end
diff --git a/app/services/security_deposits/liability_timeline.rb b/app/services/security_deposits/liability_timeline.rb
new file mode 100644
index 00000000..28b1bd52
--- /dev/null
+++ b/app/services/security_deposits/liability_timeline.rb
@@ -0,0 +1,66 @@
+module SecurityDeposits
+ class LiabilityTimeline
+ def self.validate(security_deposit:, additions: [], removing_ids: [])
+ new(security_deposit: security_deposit, additions: additions, removing_ids: removing_ids).validate
+ end
+
+ def initialize(security_deposit:, additions: [], removing_ids: [])
+ @security_deposit = security_deposit
+ @additions = additions
+ @removing_ids = if removing_ids.is_a?(Array)
+ removing_ids.compact.map(&:to_i)
+ elsif removing_ids.present?
+ [ removing_ids.to_i ]
+ else
+ []
+ end
+ end
+
+ def validate
+ date_deltas = {} # : Hash[Date, Integer]
+
+ # 1. Load active posted transactions (excluding those marked for removal)
+ existing_txns = security_deposit.transactions.active.posted
+ existing_txns = existing_txns.where.not(id: removing_ids) if removing_ids.present?
+
+ existing_txns.each do |txn|
+ delta_int = txn.received? ? txn.amount_cents.to_i : -txn.amount_cents.to_i
+ curr_cents = (date_deltas[txn.occurred_on] || 0).to_i
+ date_deltas[txn.occurred_on] = (curr_cents + delta_int).to_i
+ end
+
+ # 2. Incorporate additions
+ additions.each do |add|
+ occ = add[:occurred_on]
+ occ = Date.parse(occ.to_s) unless occ.is_a?(Date)
+ curr_cents = (date_deltas[occ] || 0).to_i
+ date_deltas[occ] = (curr_cents + add[:delta_cents].to_i).to_i
+ end
+
+ # 3. Walk timeline chronologically
+ running_held_cents = 0
+ sorted_dates = date_deltas.keys.sort
+
+ sorted_dates.each do |date|
+ running_held_cents += date_deltas[date]
+ if running_held_cents < 0
+ return ServiceResult.failure(
+ error: "Transaction would result in negative security deposit liability (#{format_money(running_held_cents)}) as of #{date}",
+ code: :negative_deposit_liability,
+ data: { as_of: date, balance_cents: running_held_cents }
+ )
+ end
+ end
+
+ ServiceResult.success(final_balance_cents: running_held_cents)
+ end
+
+ private
+
+ attr_reader :security_deposit, :additions, :removing_ids
+
+ def format_money(cents)
+ sprintf("$%.2f", cents.to_f / 100)
+ end
+ end
+end
diff --git a/app/services/security_deposits/update_service.rb b/app/services/security_deposits/update_service.rb
new file mode 100644
index 00000000..62875dfb
--- /dev/null
+++ b/app/services/security_deposits/update_service.rb
@@ -0,0 +1,92 @@
+module SecurityDeposits
+ class UpdateService
+ def self.call(security_deposit:, required_amount: nil, required_amount_cents: nil, due_on: nil)
+ new(
+ security_deposit: security_deposit,
+ required_amount: required_amount,
+ required_amount_cents: required_amount_cents,
+ due_on: due_on
+ ).call
+ end
+
+ def initialize(security_deposit:, required_amount: nil, required_amount_cents: nil, due_on: nil)
+ @security_deposit = security_deposit
+ @raw_amount = required_amount
+ @raw_cents = required_amount_cents
+ @raw_due_on = due_on
+ end
+
+ def call
+ unless security_deposit.is_a?(SecurityDeposit) && security_deposit.persisted? && !security_deposit.destroyed?
+ return ServiceResult.failure(error: "Security deposit must be a persisted record", code: :invalid_source)
+ end
+
+ cents = if raw_cents.present? || raw_amount.present?
+ resolve_cents
+ else
+ security_deposit.required_amount_cents
+ end
+
+ if cents.nil? || !cents.positive?
+ return ServiceResult.failure(error: "Required amount must be greater than zero", code: :invalid_amount)
+ end
+
+ due_date = if raw_due_on.present?
+ resolve_due_on
+ else
+ security_deposit.due_on
+ end
+
+ unless due_date
+ return ServiceResult.failure(error: "Invalid due date", code: :invalid_due_on)
+ end
+
+ security_deposit.with_lock do
+ if security_deposit.transactions.exists?
+ return ServiceResult.failure(
+ error: "Security deposit requirement cannot be updated after transactions exist",
+ code: :immutable_requirement
+ )
+ end
+
+ security_deposit.required_amount_cents = cents
+ security_deposit.due_on = due_date
+
+ if security_deposit.save
+ ServiceResult.success(security_deposit: security_deposit)
+ else
+ ServiceResult.failure(error: security_deposit.errors.full_messages.join(", "), code: :validation_error)
+ end
+ end
+ end
+
+ private
+
+ attr_reader :security_deposit, :raw_amount, :raw_cents, :raw_due_on
+
+ def resolve_cents
+ if raw_cents.present?
+ return raw_cents if raw_cents.is_a?(Integer)
+
+ nil
+ elsif raw_amount.present?
+ str = raw_amount.is_a?(Numeric) ? raw_amount.to_s : raw_amount.to_s.strip
+ return nil unless str.match?(/\A\d+(\.\d{1,2})?\z/)
+
+ (BigDecimal(str) * 100).round
+ else
+ nil
+ end
+ end
+
+ def resolve_due_on
+ return raw_due_on if raw_due_on.is_a?(Date)
+ return raw_due_on.to_date if raw_due_on.respond_to?(:to_date)
+ return nil if raw_due_on.blank?
+
+ Date.parse(raw_due_on.to_s)
+ rescue ArgumentError, Date::Error
+ nil
+ end
+ end
+end
diff --git a/app/views/properties/_financials.html.erb b/app/views/properties/_financials.html.erb
index 9f8714b7..643322ac 100644
--- a/app/views/properties/_financials.html.erb
+++ b/app/views/properties/_financials.html.erb
@@ -56,6 +56,8 @@
<%= item[:type] %>
<% when 'Expense' %>
<%= item[:type] %>
+ <% when 'Security Deposit' %>
+ <%= item[:type] %>
<% end %>
@@ -93,6 +95,19 @@
<% elsif exp.reimbursed? %>
Reimbursable
<% end %>
+ <% elsif item[:type] == 'Security Deposit' %>
+ <% sdt = item[:object] %>
+ <%= sdt.transaction_kind.titleize %>
+ <% if sdt.party %>
+ - <%= sdt.party.display_name %>
+ <% elsif sdt.charge %>
+ - Charge #<%= sdt.charge_id %>
+ <% end %>
+ <% if sdt.superseded? %>
+ Corrected
+ <% elsif sdt.voided? %>
+ Voided
+ <% end %>
<% end %>
@@ -102,6 +117,9 @@
<%= number_to_currency(item[:amount]) %>
<% elsif item[:type] == 'Payment' || item[:type] == 'Receipt' %>
+<%= number_to_currency(item[:amount]) %>
+ <% elsif item[:type] == 'Security Deposit' %>
+ <% sdt = item[:object] %>
+ <%= sdt.received? ? '+' : '-' %><%= number_to_currency(item[:amount]) %>
<% else %>
<%= number_to_currency(item[:amount]) %>
<% end %>
diff --git a/app/views/properties/show.html.erb b/app/views/properties/show.html.erb
index edbf0d9e..0071f06e 100644
--- a/app/views/properties/show.html.erb
+++ b/app/views/properties/show.html.erb
@@ -79,7 +79,7 @@
-
+
Active Tenancies
@@ -105,6 +105,16 @@
Rentable units
+
+
+
+
Security Deposits Held
+
+ <%= number_to_currency((@security_deposits_held_cents || 0) / 100.0) %>
+
+
Current refundable liability
+
+
diff --git a/app/views/security_deposit_transactions/correction.html.erb b/app/views/security_deposit_transactions/correction.html.erb
new file mode 100644
index 00000000..f8ef9ac5
--- /dev/null
+++ b/app/views/security_deposit_transactions/correction.html.erb
@@ -0,0 +1,61 @@
+<% content_for :title, "Correct Deposit Transaction ##{@transaction.id}" %>
+
+<% content_for :breadcrumbs do %>
+
<%= link_to "Tenancies", tenancies_path %>
+
<%= link_to "Tenancy ##{@transaction.tenancy.id}", tenancy_path(@transaction.tenancy) %>
+
<%= link_to "Security Deposit", tenancy_security_deposit_path(@transaction.tenancy) %>
+
<%= link_to "Transaction ##{@transaction.id}", security_deposit_transaction_path(@transaction) %>
+
Correct
+<% end %>
+
+
+
+
+
Correct Deposit <%= @transaction.transaction_kind.titleize %>
+
+ This will reverse the original journal entry on its original date (<%= @transaction.occurred_on.strftime("%b %d, %Y") %>) and post a replacement transaction.
+
+
+ <%= form_with model: @transaction, url: correct_security_deposit_transaction_path(@transaction), method: :post do |f| %>
+
+ Amount ($)
+ <%= f.number_field :amount, value: sprintf("%.2f", @transaction.amount), step: "0.01", min: "0.01", class: "input input-bordered w-full font-mono", id: "security_deposit_transaction_amount", required: true %>
+
+
+
+ Date
+ <%= f.date_field :occurred_on, value: @transaction.occurred_on, class: "input input-bordered w-full", id: "security_deposit_transaction_occurred_on", required: true %>
+
+
+ <% if @transaction.received? || @transaction.refunded? %>
+
+
+ <%= @transaction.received? ? "Contributor (Payer)" : "Recipient" %>
+
+ <%= f.collection_select :party_id, @parties, :id, :display_name, { selected: @transaction.party_id }, class: "select select-bordered w-full", id: "security_deposit_transaction_party_id", required: true %>
+
+ <% elsif @transaction.applied? %>
+
+ Target Charge
+ <%= f.collection_select :charge_id, @active_charges, :id, :description, { selected: @transaction.charge_id }, class: "select select-bordered w-full", id: "security_deposit_transaction_charge_id", required: true %>
+
+ <% end %>
+
+
+ Reference (Optional)
+ <%= f.text_field :external_reference, value: @transaction.external_reference, class: "input input-bordered w-full", id: "security_deposit_transaction_external_reference" %>
+
+
+
+ Memo (Optional)
+ <%= f.text_field :memo, value: @transaction.memo, class: "input input-bordered w-full", id: "security_deposit_transaction_memo" %>
+
+
+
+ <%= link_to "Cancel", security_deposit_transaction_path(@transaction), class: "btn btn-ghost" %>
+ <%= f.submit "Save Correction", class: "btn btn-primary" %>
+
+ <% end %>
+
+
+
diff --git a/app/views/security_deposit_transactions/show.html.erb b/app/views/security_deposit_transactions/show.html.erb
new file mode 100644
index 00000000..c3b14c91
--- /dev/null
+++ b/app/views/security_deposit_transactions/show.html.erb
@@ -0,0 +1,150 @@
+<% content_for :title, "Deposit Transaction ##{@transaction.id}" %>
+
+<% content_for :breadcrumbs do %>
+
<%= link_to "Tenancies", tenancies_path %>
+
<%= link_to "Tenancy ##{@transaction.tenancy.id}", tenancy_path(@transaction.tenancy) %>
+
<%= link_to "Security Deposit", tenancy_security_deposit_path(@transaction.tenancy) %>
+
Transaction #<%= @transaction.id %>
+<% end %>
+
+
+
+
+
Deposit <%= @transaction.transaction_kind.titleize %>
+
<%= @transaction.tenancy.property.address %> — <%= @transaction.tenancy.rentable_unit.display_name %>
+
+
+ <%= link_to "Back to Deposit", tenancy_security_deposit_path(@transaction.tenancy), class: "btn btn-ghost" %>
+ <% if @transaction.active? %>
+ <%= link_to "Correct Transaction", correction_security_deposit_transaction_path(@transaction), class: "btn btn-outline btn-warning" %>
+ <%= button_to "Void Transaction", void_security_deposit_transaction_path(@transaction), method: :post, class: "btn btn-outline btn-error", form: { data: { turbo_confirm: "Are you sure you want to void this deposit transaction? This will reverse the accounting entry on its original date." } } %>
+ <% end %>
+
+
+
+
+ <% if @transaction.superseded? %>
+
+
+
This transaction was corrected
+
+ Superseded by
+ <%= link_to "Transaction ##{@transaction.superseded_by_id}", security_deposit_transaction_path(@transaction.superseded_by), class: "link font-semibold" %>
+ on <%= @transaction.voided_at.strftime("%B %d, %Y at %l:%M %p") %>.
+
+
+
+ <% elsif @transaction.voided? %>
+
+
+
This transaction was voided
+
Voided on <%= @transaction.voided_at.strftime("%B %d, %Y at %l:%M %p") %>.
+
+
+ <% elsif @transaction.superseded_transaction.present? %>
+
+
+
This is a replacement transaction
+
+ Replaced
+ <%= link_to "Transaction ##{@transaction.superseded_transaction.id}", security_deposit_transaction_path(@transaction.superseded_transaction), class: "link font-semibold" %>.
+
+
+
+ <% end %>
+
+
+
+
+
Transaction Details
+
+
+
+
Transaction Kind
+ <%= @transaction.transaction_kind.titleize %>
+
+
+
Amount
+ <%= number_to_currency(@transaction.amount) %>
+
+
+
Date
+ <%= @transaction.occurred_on.strftime("%B %d, %Y") %>
+
+ <% if @transaction.party %>
+
+
<%= @transaction.received? ? "Contributor" : "Recipient" %>
+ <%= link_to @transaction.party.display_name, @transaction.party, class: "link link-hover" %>
+
+ <% end %>
+ <% if @transaction.charge %>
+
+
Target Charge
+ <%= link_to "Charge ##{@transaction.charge_id}: #{@transaction.charge.description || @transaction.charge.charge_kind.titleize}", charge_path(@transaction.charge), class: "link link-hover" %>
+
+ <% end %>
+
+
Reference
+ <%= @transaction.external_reference || "—" %>
+
+
+
Memo
+ <%= @transaction.memo || "—" %>
+
+
+
Status
+
+ <% if @transaction.superseded? %>
+ Corrected
+ <% elsif @transaction.voided? %>
+ Voided
+ <% else %>
+ Active
+ <% end %>
+
+
+
+
+
+
+
+
+
+
Accounting Postings
+
+ <% if @journal_entries.any? %>
+
+ <% @journal_entries.each do |entry| %>
+
+
+ <%= entry.event_type.titleize %>
+ <%= entry.occurred_on.strftime("%b %d, %Y") %>
+
+
+
+
+ Account
+ Debit
+ Credit
+
+
+
+ <% entry.postings.each do |p| %>
+
+ <%= p.account.name %>
+ <%= p.debit? ? number_to_currency(p.debit_amount / 100.0) : "" %>
+ <%= p.credit? ? number_to_currency(p.credit_amount / 100.0) : "" %>
+
+ <% end %>
+
+
+
+ <% end %>
+
+ <% else %>
+
No journal entries recorded.
+ <% end %>
+
+
+
+
diff --git a/app/views/security_deposits/edit.html.erb b/app/views/security_deposits/edit.html.erb
new file mode 100644
index 00000000..1d206e8d
--- /dev/null
+++ b/app/views/security_deposits/edit.html.erb
@@ -0,0 +1,48 @@
+<% content_for :title, "Edit Security Deposit — Tenancy ##{@tenancy.id}" %>
+
+<% content_for :breadcrumbs do %>
+
<%= link_to "Tenancies", tenancies_path %>
+
<%= link_to "Tenancy ##{@tenancy.id}", tenancy_path(@tenancy) %>
+
<%= link_to "Security Deposit", tenancy_security_deposit_path(@tenancy) %>
+
Edit
+<% end %>
+
+
+
+
+
Edit Security Deposit Requirement
+
Modify the contractual deposit terms before transactions have been recorded.
+
+ <%= form_with model: @security_deposit, url: tenancy_security_deposit_path(@tenancy), method: :patch do |f| %>
+ <% if @security_deposit.errors.any? %>
+
+
+ <% @security_deposit.errors.full_messages.each do |msg| %>
+ <%= msg %>
+ <% end %>
+
+
+ <% end %>
+
+
+
+ Required Deposit Amount ($)
+
+ <%= f.number_field :required_amount, step: "0.01", min: "0.01", value: sprintf("%.2f", @security_deposit.required_amount), class: "input input-bordered w-full font-mono", id: "security_deposit_required_amount", required: true %>
+
+
+
+
+ Due Date
+
+ <%= f.date_field :due_on, value: @security_deposit.due_on, class: "input input-bordered w-full", id: "security_deposit_due_on", required: true %>
+
+
+
+ <%= link_to "Cancel", tenancy_security_deposit_path(@tenancy), class: "btn btn-ghost" %>
+ <%= f.submit "Update Requirement", class: "btn btn-primary" %>
+
+ <% end %>
+
+
+
diff --git a/app/views/security_deposits/new.html.erb b/app/views/security_deposits/new.html.erb
new file mode 100644
index 00000000..8f2239c3
--- /dev/null
+++ b/app/views/security_deposits/new.html.erb
@@ -0,0 +1,47 @@
+<% content_for :title, "Set Up Security Deposit — Tenancy ##{@tenancy.id}" %>
+
+<% content_for :breadcrumbs do %>
+
<%= link_to "Tenancies", tenancies_path %>
+
<%= link_to "Tenancy ##{@tenancy.id}", tenancy_path(@tenancy) %>
+
Security Deposit
+<% end %>
+
+
+
+
+
Set Up Security Deposit
+
Record the contractual security deposit requirement for this tenancy.
+
+ <%= form_with model: @security_deposit, url: tenancy_security_deposit_path(@tenancy), method: :post do |f| %>
+ <% if @security_deposit.errors.any? %>
+
+
+ <% @security_deposit.errors.full_messages.each do |msg| %>
+ <%= msg %>
+ <% end %>
+
+
+ <% end %>
+
+
+
+ Required Deposit Amount ($)
+
+ <%= f.number_field :required_amount, step: "0.01", min: "0.01", placeholder: "2000.00", class: "input input-bordered w-full font-mono", id: "security_deposit_required_amount", required: true %>
+
+
+
+
+ Due Date
+
+ <%= f.date_field :due_on, class: "input input-bordered w-full", id: "security_deposit_due_on", required: true %>
+
+
+
+ <%= link_to "Cancel", tenancy_path(@tenancy), class: "btn btn-ghost" %>
+ <%= f.submit "Save Deposit Requirement", class: "btn btn-primary" %>
+
+ <% end %>
+
+
+
diff --git a/app/views/security_deposits/show.html.erb b/app/views/security_deposits/show.html.erb
new file mode 100644
index 00000000..0463b8b0
--- /dev/null
+++ b/app/views/security_deposits/show.html.erb
@@ -0,0 +1,281 @@
+<% content_for :title, "Security Deposit — Tenancy ##{@tenancy.id}" %>
+
+<% content_for :breadcrumbs do %>
+
<%= link_to "Tenancies", tenancies_path %>
+
<%= link_to "Tenancy ##{@tenancy.id}", tenancy_path(@tenancy) %>
+
Security Deposit
+<% end %>
+
+
+
+
+
Security Deposit
+
<%= @tenancy.property.address %> — <%= @tenancy.rentable_unit.display_name %>
+
+
+ <%= link_to "Back to Tenancy", tenancy_path(@tenancy), class: "btn btn-ghost" %>
+ <% if @transactions.none? %>
+ <%= link_to "Edit Requirement", edit_tenancy_security_deposit_path(@tenancy), class: "btn btn-outline" %>
+ <% end %>
+
+
+
+
+
+
+
+
Required
+
<%= number_to_currency(@security_deposit.required_amount) %>
+
Due: <%= @security_deposit.due_on.strftime("%b %d, %Y") %>
+
+
+
+
+
+
Currently Held
+
<%= number_to_currency(@security_deposit.held_amount) %>
+
Ledger liability
+
+
+
+
+
+
Remaining Due
+
+ <%= number_to_currency(@security_deposit.remaining_required_amount) %>
+
+
To fulfill requirement
+
+
+
+
+
+
Funding Status
+
+ <% case @security_deposit.funding_status %>
+ <% when "funded" %>
+ Funded
+ <% when "partially_funded" %>
+ Partially Funded
+ <% when "overfunded" %>
+ Overfunded
+ <% else %>
+ Not Funded
+ <% end %>
+
+
Contractual state
+
+
+
+
+
+
+
+
+
+
Record Deposit Payment
+
Record money received toward this security deposit liability.
+
+ <%= form_with url: receive_tenancy_security_deposit_path(@tenancy), method: :post, local: true do |f| %>
+
+ Contributor (Payer)
+ <%= select_tag :party_id, options_from_collection_for_select(@parties, :id, :display_name), class: "select select-bordered select-sm w-full", id: "receive_party_id", required: true %>
+
+
+
+ Amount ($)
+ <%= number_field_tag :amount, sprintf("%.2f", @security_deposit.remaining_required_amount > 0 ? @security_deposit.remaining_required_amount : 100.0), step: "0.01", min: "0.01", class: "input input-bordered input-sm font-mono w-full", id: "receive_amount", required: true %>
+
+
+
+ Received On
+ <%= date_field_tag :occurred_on, Date.current, class: "input input-bordered input-sm w-full", id: "receive_occurred_on", required: true %>
+
+
+
+ Reference (Optional)
+ <%= text_field_tag :external_reference, nil, placeholder: "Check #, wire ref", class: "input input-bordered input-sm w-full", id: "receive_external_reference" %>
+
+
+
+ Memo (Optional)
+ <%= text_field_tag :memo, nil, placeholder: "Security deposit receipt", class: "input input-bordered input-sm w-full", id: "receive_memo" %>
+
+
+
+ <%= f.submit "Record Deposit", class: "btn btn-primary btn-sm w-full" %>
+
+ <% end %>
+
+
+
+
+
+
+
Refund Deposit
+
Return held deposit funds to a tenant or contributor.
+
+ <% if @security_deposit.held_cents > 0 %>
+ <%= form_with url: refund_tenancy_security_deposit_path(@tenancy), method: :post, local: true do |f| %>
+
+ Recipient
+ <%= select_tag :party_id, options_from_collection_for_select(@parties, :id, :display_name), class: "select select-bordered select-sm w-full", id: "refund_party_id", required: true %>
+
+
+
+ Amount ($) — Max: <%= number_to_currency(@security_deposit.held_amount) %>
+ <%= number_field_tag :amount, sprintf("%.2f", @security_deposit.held_amount), step: "0.01", min: "0.01", max: sprintf("%.2f", @security_deposit.held_amount), class: "input input-bordered input-sm font-mono w-full", id: "refund_amount", required: true %>
+
+
+
+ Refunded On
+ <%= date_field_tag :occurred_on, Date.current, class: "input input-bordered input-sm w-full", id: "refund_occurred_on", required: true %>
+
+
+
+ Reference (Optional)
+ <%= text_field_tag :external_reference, nil, placeholder: "Check #, wire ref", class: "input input-bordered input-sm w-full", id: "refund_external_reference" %>
+
+
+
+ Memo (Optional)
+ <%= text_field_tag :memo, nil, placeholder: "Deposit refund at move-out", class: "input input-bordered input-sm w-full", id: "refund_memo" %>
+
+
+
+ <%= f.submit "Record Refund", class: "btn btn-secondary btn-sm w-full" %>
+
+ <% end %>
+ <% else %>
+
+ No deposit funds are currently held to refund.
+
+ <% end %>
+
+
+
+
+
+
+
Apply Deposit to Charge
+
Apply held deposit toward an active charge (damages, rent, late fee).
+
+ <% if @security_deposit.held_cents > 0 && @tenancy.current_balance > 0 && @active_charges.any? %>
+ <%= form_with url: apply_tenancy_security_deposit_path(@tenancy), method: :post, local: true do |f| %>
+
+ Select Active Charge
+
+ <% @active_charges.each do |c| %>
+ <% cap = [c.remaining_deposit_application_cents, @security_deposit.held_cents, @tenancy.current_balance_cents].min / 100.0 %>
+
+ <%= c.charge_date.strftime("%b %d, %Y") %> — <%= c.description || c.charge_kind.titleize %> (<%= number_to_currency(c.amount) %>, Max: <%= number_to_currency(cap) %>)
+
+ <% end %>
+
+
+
+
+ Amount to Apply ($)
+ <%= number_field_tag :amount, sprintf("%.2f", [@security_deposit.held_amount, @tenancy.current_balance].min), step: "0.01", min: "0.01", class: "input input-bordered input-sm font-mono w-full", id: "apply_amount", required: true %>
+
+
+
+ Application Date
+ <%= date_field_tag :occurred_on, Date.current, class: "input input-bordered input-sm w-full", id: "apply_occurred_on", required: true %>
+
+
+
+ Memo (Optional)
+ <%= text_field_tag :memo, nil, placeholder: "Deposit deduction for repairs", class: "input input-bordered input-sm w-full", id: "apply_memo" %>
+
+
+
+ <%= f.submit "Apply Deposit", class: "btn btn-accent btn-sm w-full" %>
+
+ <% end %>
+ <% else %>
+
+ <% if @security_deposit.held_cents <= 0 %>
+ No deposit funds are currently held.
+ <% elsif @tenancy.current_balance <= 0 %>
+ Tenancy has no outstanding balance ($0.00).
+ <% else %>
+ No active posted charges to apply against.
+ <% end %>
+
+ <% end %>
+
+
+
+
+
+
+
+
Deposit Transaction History
+
+
+
+
+
+ Date
+ Kind
+ Party / Charge
+ Reference / Memo
+ Amount
+ Status
+ Actions
+
+
+
+ <% if @transactions.any? %>
+ <% @transactions.each do |txn| %>
+
+ <%= txn.occurred_on.strftime("%b %d, %Y") %>
+
+
+ <%= txn.transaction_kind.titleize %>
+
+
+
+ <% if txn.received? || txn.refunded? %>
+ <%= txn.party&.display_name %>
+ <% elsif txn.applied? %>
+ <%= link_to "Charge ##{txn.charge_id}: #{txn.charge&.description || txn.charge&.charge_kind&.titleize}", charge_path(txn.charge_id), class: "link link-hover" if txn.charge_id %>
+ <% end %>
+
+
+ <%= txn.external_reference.present? ? "[#{txn.external_reference}] " : "" %>
+ <%= txn.memo || "—" %>
+
+
+ <%= txn.received? ? '+' : '-' %><%= number_to_currency(txn.amount) %>
+
+
+ <% if txn.superseded? %>
+ Corrected
+ <% elsif txn.voided? %>
+ Voided
+ <% elsif txn.superseded_transaction.present? %>
+ Replacement
+ <% else %>
+ Active
+ <% end %>
+
+
+ <%= link_to "View", security_deposit_transaction_path(txn), class: "btn btn-xs btn-ghost" %>
+
+
+ <% end %>
+ <% else %>
+
+
+ No deposit transactions recorded yet.
+
+
+ <% end %>
+
+
+
+
+
+
diff --git a/app/views/tenancies/show.html.erb b/app/views/tenancies/show.html.erb
index d6251aec..a5d26dbd 100644
--- a/app/views/tenancies/show.html.erb
+++ b/app/views/tenancies/show.html.erb
@@ -315,6 +315,45 @@
+
+
+
Security Deposit
+ <% if @tenancy.security_deposit %>
+ <% case @tenancy.security_deposit.funding_status %>
+ <% when "funded" %>
+
Funded
+ <% when "partially_funded" %>
+
Partial
+ <% when "overfunded" %>
+
Overfunded
+ <% else %>
+
Not Funded
+ <% end %>
+ <% end %>
+
+
+ <% if @tenancy.security_deposit %>
+ <% dep = @tenancy.security_deposit %>
+
+ <%= number_to_currency(dep.held_amount) %>
+
+
+
Required: <%= number_to_currency(dep.required_amount) %>
+ <% if dep.remaining_required_amount > 0 %>
+
Remaining: <%= number_to_currency(dep.remaining_required_amount) %>
+ <% end %>
+
+
+ <%= link_to "Manage Security Deposit", tenancy_security_deposit_path(@tenancy), class: "btn btn-outline btn-secondary btn-sm w-full" %>
+ <% else %>
+
No security deposit requirement recorded for this tenancy.
+ <%= link_to "＋ Set Up Security Deposit", new_tenancy_security_deposit_path(@tenancy), class: "btn btn-outline btn-sm w-full" %>
+ <% end %>
+
+