Feature - Add support for a fiscal year period defined in user settings.

* Add "This fiscal year", "Last fiscal year" as date range options in Transaction Details to filter transactions to those periods * Add fiscal year ranges to Statistics & Trend Analysis * Add "fiscal year start date" to user profile settings, allowing the user to select any date of the calendar year as the start of the fiscal year * Add "fiscal year format" to user profile settings, allowing the user to specify how financial year date labels should appear Implementation notes: * The default fiscal year start is January 1 and the default fiscal year display format is "FY 2025" * Fiscal year start date (month number & day number) are stored together in db as a uint16, high byte & low byte respectively * February 29 is disallowed as a fiscal year start date, since it is never used as a convention in any country * Jest is added to the project as a dev dependency, for unit tests in frontend Signed-off-by: Sebastian Reategui <seb.reategui@gmail.com>
2026-05-17 00:12:11 +08:00 · 2025-06-05 12:36:46 +10:00
parent 70eea8ff33
commit b94dc8eb83
42 changed files with 3417 additions and 105 deletions
@@ -0,0 +1,109 @@
+package core
+
+import (
+	"fmt"
+
+	"github.com/mayswind/ezbookkeeping/pkg/errs"
+)
+
+// FiscalYearStart represents the fiscal year start date as a uint16 (month: high byte, day: low byte)
+type FiscalYearStart uint16
+
+// Fiscal Year Start Date Type
+const (
+	FISCAL_YEAR_START_DEFAULT FiscalYearStart = 0x0101 // January 1
+	FISCAL_YEAR_START_MIN     FiscalYearStart = 0x0101 // January 1
+	FISCAL_YEAR_START_MAX     FiscalYearStart = 0x0C1F // December 31
+	FISCAL_YEAR_START_INVALID FiscalYearStart = 0xFFFF // Invalid
+)
+
+// NewFiscalYearStart creates a new FiscalYearStart from month and day values
+func NewFiscalYearStart(month uint8, day uint8) (FiscalYearStart, error) {
+	month, day, err := validateMonthDay(month, day)
+	if err != nil {
+		return 0, err
+	}
+
+	return FiscalYearStart(uint16(month)<<8 | uint16(day)), nil
+}
+
+// GetMonthDay extracts the month and day from FiscalYearType
+func (f FiscalYearStart) GetMonthDay() (uint8, uint8, error) {
+	if f < FISCAL_YEAR_START_MIN || f > FISCAL_YEAR_START_MAX {
+		return 0, 0, errs.ErrFormatInvalid
+	}
+
+	// Extract month and day (month in high byte, day in low byte)
+	month := uint8(f >> 8)
+	day := uint8(f & 0xFF)
+
+	return validateMonthDay(month, day)
+}
+
+// String returns a string representation of FiscalYearStart in MM/DD format
+func (f FiscalYearStart) String() string {
+	month, day, err := f.GetMonthDay()
+	if err != nil {
+		return "Invalid"
+	}
+	return fmt.Sprintf("%02d-%02d", month, day)
+}
+
+// validateMonthDay validates a month and day and returns them if valid
+func validateMonthDay(month uint8, day uint8) (uint8, uint8, error) {
+	if month < 1 || month > 12 || day < 1 {
+		return 0, 0, errs.ErrFormatInvalid
+	}
+
+	maxDays := uint8(31)
+	switch month {
+	case 1, 3, 5, 7, 8, 10, 12: // January, March, May, July, August, October, December
+		maxDays = 31
+	case 4, 6, 9, 11: // April, June, September, November
+		maxDays = 30
+	case 2: // February
+		maxDays = 28 // Disallow fiscal year start on leap day
+	}
+
+	if day > maxDays {
+		return 0, 0, errs.ErrFormatInvalid
+	}
+
+	return month, day, nil
+}
+
+// FiscalYearFormat represents the fiscal year format as a uint8
+type FiscalYearFormat uint8
+
+// Fiscal Year Format Type Name
+const (
+	FISCAL_YEAR_FORMAT_DEFAULT           FiscalYearFormat = 0
+	FISCAL_YEAR_FORMAT_STARTYYYY_ENDYYYY FiscalYearFormat = 1
+	FISCAL_YEAR_FORMAT_STARTYYYY_ENDYY   FiscalYearFormat = 2
+	FISCAL_YEAR_FORMAT_STARTYY_ENDYY     FiscalYearFormat = 3
+	FISCAL_YEAR_FORMAT_ENDYYYY           FiscalYearFormat = 4
+	FISCAL_YEAR_FORMAT_ENDYY             FiscalYearFormat = 5
+	FISCAL_YEAR_FORMAT_INVALID           FiscalYearFormat = 255 // Invalid
+)
+
+// String returns a textual representation of the long date format enum
+func (f FiscalYearFormat) String() string {
+	switch f {
+	case FISCAL_YEAR_FORMAT_DEFAULT:
+		return "Default"
+	case FISCAL_YEAR_FORMAT_STARTYYYY_ENDYYYY:
+		return "StartYYYY-EndYYYY"
+	case FISCAL_YEAR_FORMAT_STARTYYYY_ENDYY:
+		return "StartYYYY-EndYY"
+	case FISCAL_YEAR_FORMAT_STARTYY_ENDYY:
+		return "StartYY-EndYY"
+	case FISCAL_YEAR_FORMAT_ENDYYYY:
+		return "EndYYYY"
+	case FISCAL_YEAR_FORMAT_ENDYY:
+		return "EndYY"
+	case FISCAL_YEAR_FORMAT_INVALID:
+		return "Invalid"
+	default:
+		return fmt.Sprintf("Invalid(%d)", int(f))
+	}
+}
@@ -0,0 +1,127 @@
+package core
+
+import (
+	"testing"
+
+	"github.com/mayswind/ezbookkeeping/pkg/errs"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestNewFiscalYearStart_ValidMonthDay(t *testing.T) {
+	testCases := []struct {
+		month    uint8
+		day      uint8
+		expected FiscalYearStart
+	}{
+		{1, 1, 0x0101},   // January 1
+		{4, 15, 0x040F},  // April 15
+		{7, 1, 0x0701},   // July 1
+		{12, 31, 0x0C1F}, // December 31
+	}
+
+	for _, tc := range testCases {
+		fiscal, err := NewFiscalYearStart(tc.month, tc.day)
+		assert.Nil(t, err)
+		assert.Equal(t, tc.expected, fiscal)
+	}
+}
+
+func TestNewFiscalYearStart_InvalidMonthDay(t *testing.T) {
+	testCases := []struct {
+		month uint8
+		day   uint8
+	}{
+		{0, 1},    // Month 0 (invalid)
+		{13, 1},   // Month 13 (invalid)
+		{1, 0},    // Day 0 (invalid)
+		{1, 32},   // Day 32 (invalid for January)
+		{2, 30},   // Day 30 (invalid for February)
+		{2, 29},   // Day 29 (leap day not permitted)
+		{4, 31},   // Day 31 (invalid for April)
+		{6, 31},   // Day 31 (invalid for June)
+		{9, 31},   // Day 31 (invalid for September)
+		{11, 32},  // Day 32 (invalid for November)
+		{255, 15}, // Invalid month
+		{5, 255},  // Invalid day
+	}
+
+	for _, tc := range testCases {
+		fiscal, err := NewFiscalYearStart(tc.month, tc.day)
+		assert.Equal(t, FiscalYearStart(0), fiscal)
+		assert.Equal(t, errs.ErrFormatInvalid, err)
+	}
+}
+
+func TestGetMonthDay_ValidFiscalYearStart(t *testing.T) {
+	testCases := []struct {
+		fiscalYear FiscalYearStart
+		month      uint8
+		day        uint8
+	}{
+		{0x0101, 1, 1},   // January 1st
+		{0x0C1F, 12, 31}, // December 31st
+		{0x0701, 7, 1},   // July 1st
+		{0x040F, 4, 15},  // April 15th
+	}
+
+	for _, tc := range testCases {
+		month, day, err := tc.fiscalYear.GetMonthDay()
+		assert.Nil(t, err)
+		assert.Equal(t, tc.month, month)
+		assert.Equal(t, tc.day, day)
+	}
+}
+
+func TestGetMonthDay_InvalidFiscalYearStart(t *testing.T) {
+	testCases := []struct {
+		fiscalYear FiscalYearStart
+	}{
+		{0x0000}, // 0/0 (invalid)
+		{0x0D01}, // Month 13 (invalid)
+		{0x0100}, // Day 0 (invalid)
+		{0x0120}, // January 32 (invalid)
+		{0x021D}, // February 29 (not permitted)
+		{0x021E}, // February 30 (invalid)
+		{0x041F}, // April 31 (invalid)
+		{0x061F}, // June 31 (invalid)
+		{0x091F}, // September 31 (invalid)
+		{0x0B20}, // November 32 (invalid)
+		{0xFF01}, // Invalid month
+		{0x01FF}, // Invalid day
+		{0},      // Zero value
+	}
+
+	for _, tc := range testCases {
+		month, day, err := tc.fiscalYear.GetMonthDay()
+		assert.Equal(t, uint8(0), month)
+		assert.Equal(t, uint8(0), day)
+		assert.Equal(t, errs.ErrFormatInvalid, err)
+	}
+}
+
+func TestFiscalYearStart_String(t *testing.T) {
+	testCases := []struct {
+		fiscalYear FiscalYearStart
+		expected   string
+	}{
+		{0x0101, "01-01"},   // January 1st
+		{0x0C1F, "12-31"},   // December 31st
+		{0x0701, "07-01"},   // July 1st
+		{0x040F, "04-15"},   // April 15th
+		{0x021D, "Invalid"}, // February 29th (leap day not permitted)
+		{0x0000, "Invalid"}, // Invalid date
+		{0x0D01, "Invalid"}, // Invalid month
+		{0x0120, "Invalid"}, // Invalid day
+	}
+
+	for _, tc := range testCases {
+		assert.Equal(t, tc.expected, tc.fiscalYear.String())
+	}
+}
+
+func TestFiscalYearStartConstants(t *testing.T) {
+	assert.Equal(t, FiscalYearStart(0xFFFF), FISCAL_YEAR_START_INVALID)
+	assert.Equal(t, FiscalYearStart(0x0101), FISCAL_YEAR_START_DEFAULT)
+	assert.Equal(t, FiscalYearStart(0x0101), FISCAL_YEAR_START_MIN)
+	assert.Equal(t, FiscalYearStart(0x0C1F), FISCAL_YEAR_START_MAX)
+}