Model financial values in csv for importing

To try and simplify our approach to importing from csv files this
Import::Csv::Financial class is a basic wrapper for a financial value
that is to be imported from csv.

Our philosophy when importing from csv is that a financial value is to expect:

- a positive number
- a negatvie number
- zero
- any kind of blank space
- invalid
- some kind of financial formatting e.g. 10,000.00

Here, invalid means

> We could not convert the supplied string to a BigDecimal.

This implementation treats a `0` and an empty cell the same,
which makes the upstream import code more approachable as we can
assume everything will be `0`.

We resue the existing `ConvertFinancialValue` service object to do the
actual conversion, dealing with an errors as described above - we chose
this approach over changing the `ConvertFinancialValue` to keep the
changes isolated to the current work.

When we use this class during import, we can expect a financial value to
be one of three states:

- a BigDecimal value
- a zero
- nil

Where nil means it could not be converted.

We also retain the original string value from the csv so it can be
presented back to the user in any error messages.

CHANGELOG.md

@@ -4,6 +4,8 @@
 
 [Full changelog][unreleased]
 
+- model a financial value from a csv file
+
 ## Release 141 - 2023-12-04
 
 [Full changelog][141]

app/models/import/csv/financial.rb

@@ -0,0 +1,19 @@
+class Import::Csv::Financial
+  attr_reader :decimal_value, :original_value
+
+  def initialize(value)
+    @decimal_value = convert_to_decimal(value.to_s)
+    @original_value = value.to_s
+  end
+
+  private def convert_to_decimal(value)
+    return BigDecimal("0") if value.blank?
+
+    begin
+      converted_value = ConvertFinancialValue.new.convert(value)
+    rescue ConvertFinancialValue::Error
+      return nil
+    end
+    converted_value
+  end
+end

spec/models/import/csv/financial_spec.rb

@@ -0,0 +1,106 @@
+require "rails_helper"
+
+RSpec.describe Import::Csv::Financial do
+  describe "#value" do
+    context "when the value is positive number" do
+      it "returns a BigDecimal of the number" do
+        csv_value = "1000.0"
+        finance_value = described_class.new(csv_value)
+
+        expect(finance_value.decimal_value).to eql BigDecimal("1_000")
+      end
+    end
+
+    context "when the value is negative number" do
+      it "returns a BigDecimal of the number" do
+        csv_value = "-1000.0"
+        finance_value = described_class.new(csv_value)
+
+        expect(finance_value.decimal_value).to eql BigDecimal("-1_000")
+      end
+    end
+
+    context "when the value is zero" do
+      it "returns a BigDecimal of zero" do
+        csv_value = "0.0"
+        finance_value = described_class.new(csv_value)
+
+        expect(finance_value.decimal_value).to eql BigDecimal("0")
+      end
+    end
+
+    context "when the value has financial punctuation" do
+      it "returns a BigDecimal of the number" do
+        csv_value = "£1,000,000,000.0"
+        finance_value = described_class.new(csv_value)
+
+        expect(finance_value.decimal_value).to eql BigDecimal("1_000_000_000")
+      end
+    end
+
+    context "when the value is space" do
+      it "returns a BigDecimal of zero" do
+        csv_value = " "
+        finance_value = described_class.new(csv_value)
+
+        expect(finance_value.decimal_value).to eql BigDecimal("0")
+      end
+    end
+
+    context "when the value is multiple spaces" do
+      it "returns a BigDecimal of zero" do
+        csv_value = "   "
+        finance_value = described_class.new(csv_value)
+
+        expect(finance_value.decimal_value).to eql BigDecimal("0")
+      end
+    end
+
+    context "when the value is nil" do
+      it "returns a BigDecimal of zero" do
+        csv_value = nil
+        finance_value = described_class.new(csv_value)
+
+        expect(finance_value.decimal_value).to eql BigDecimal("0")
+      end
+    end
+
+    context "when the value is empty" do
+      it "returns a BigDecimal of zero" do
+        csv_value = ""
+        finance_value = described_class.new(csv_value)
+
+        expect(finance_value.decimal_value).to eql BigDecimal("0")
+      end
+    end
+
+    context "when the value cannot be converted" do
+      it "returns nil" do
+        csv_value = "this cannot be converted"
+        finance_value = described_class.new(csv_value)
+
+        expect(finance_value.decimal_value).to be_nil
+      end
+    end
+  end
+
+  describe "#original_value" do
+    context "when the conversion can take place" do
+      it "returns the original string from the csv cell" do
+        csv_value = "1000.0"
+        finance_value = described_class.new(csv_value)
+
+        expect(finance_value.original_value).to eql csv_value
+      end
+    end
+
+    context "when the conversion cannot take place" do
+      it "returns the original string from the csv cell" do
+        csv_value = "ten thousand pounds"
+        finance_value = described_class.new(csv_value)
+
+        expect(finance_value.original_value).to eql csv_value
+      end
+    end
+  end
+end