zhengchen.tao/ezbookkeeping
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
* 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>
This commit is contained in:
Sebastian Reategui
2025-06-05 12:36:46 +10:00
committed by mayswind
parent 70eea8ff33
commit b94dc8eb83
42 changed files with 3417 additions and 105 deletions
Download Patch File Download Diff File Expand all files Collapse all files
pkg/api/users.go
+18
View File
@@ -349,6 +349,15 @@ func (a *UsersApi) UserUpdateProfileHandler(c *core.WebContext) (any, *errs.Erro
userNew.FirstDayOfWeek = core.WEEKDAY_INVALID
}
if userUpdateReq.FiscalYearStart != nil && *userUpdateReq.FiscalYearStart != user.FiscalYearStart {
user.FiscalYearStart = *userUpdateReq.FiscalYearStart
userNew.FiscalYearStart = *userUpdateReq.FiscalYearStart
modifyProfileBasicInfo = true
anythingUpdate = true
} else {
userNew.FiscalYearStart = core.FISCAL_YEAR_START_INVALID
}
if userUpdateReq.LongDateFormat != nil && *userUpdateReq.LongDateFormat != user.LongDateFormat {
user.LongDateFormat = *userUpdateReq.LongDateFormat
userNew.LongDateFormat = *userUpdateReq.LongDateFormat
@@ -385,6 +394,15 @@ func (a *UsersApi) UserUpdateProfileHandler(c *core.WebContext) (any, *errs.Erro
userNew.ShortTimeFormat = core.SHORT_TIME_FORMAT_INVALID
}
if userUpdateReq.FiscalYearFormat != nil && *userUpdateReq.FiscalYearFormat != user.FiscalYearFormat {
user.FiscalYearFormat = *userUpdateReq.FiscalYearFormat
userNew.FiscalYearFormat = *userUpdateReq.FiscalYearFormat
modifyProfileBasicInfo = true
anythingUpdate = true
} else {
userNew.FiscalYearFormat = core.FISCAL_YEAR_FORMAT_INVALID
}
if userUpdateReq.DecimalSeparator != nil && *userUpdateReq.DecimalSeparator != user.DecimalSeparator {
user.DecimalSeparator = *userUpdateReq.DecimalSeparator
userNew.DecimalSeparator = *userUpdateReq.DecimalSeparator
pkg/core/fiscalyear.go
+109
View File
@@ -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))
}
}
pkg/core/fiscalyear_test.go
+127
View File
@@ -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)
}
pkg/models/user.go
+38 -30
View File
@@ -82,37 +82,39 @@ func (s AmountColorType) String() string {
// User represents user data stored in database
type User struct {
Uid int64 `xorm:"PK"`
Username string `xorm:"VARCHAR(32) UNIQUE NOT NULL"`
Email string `xorm:"VARCHAR(100) UNIQUE NOT NULL"`
Nickname string `xorm:"VARCHAR(64) NOT NULL"`
Password string `xorm:"VARCHAR(64) NOT NULL"`
Salt string `xorm:"VARCHAR(10) NOT NULL"`
CustomAvatarType string `xorm:"VARCHAR(10)"`
DefaultAccountId int64
TransactionEditScope TransactionEditScope `xorm:"TINYINT NOT NULL"`
Language string `xorm:"VARCHAR(10)"`
DefaultCurrency string `xorm:"VARCHAR(3) NOT NULL"`
FirstDayOfWeek core.WeekDay `xorm:"TINYINT NOT NULL"`
LongDateFormat core.LongDateFormat `xorm:"TINYINT"`
ShortDateFormat core.ShortDateFormat `xorm:"TINYINT"`
LongTimeFormat core.LongTimeFormat `xorm:"TINYINT"`
ShortTimeFormat core.ShortTimeFormat `xorm:"TINYINT"`
DecimalSeparator core.DecimalSeparator `xorm:"TINYINT"`
DigitGroupingSymbol core.DigitGroupingSymbol `xorm:"TINYINT"`
DigitGrouping core.DigitGroupingType `xorm:"TINYINT"`
CurrencyDisplayType core.CurrencyDisplayType `xorm:"TINYINT"`
Uid int64 `xorm:"PK"`
Username string `xorm:"VARCHAR(32) UNIQUE NOT NULL"`
Email string `xorm:"VARCHAR(100) UNIQUE NOT NULL"`
Nickname string `xorm:"VARCHAR(64) NOT NULL"`
Password string `xorm:"VARCHAR(64) NOT NULL"`
Salt string `xorm:"VARCHAR(10) NOT NULL"`
CustomAvatarType string `xorm:"VARCHAR(10)"`
DefaultAccountId int64
TransactionEditScope TransactionEditScope `xorm:"TINYINT NOT NULL"`
Language string `xorm:"VARCHAR(10)"`
DefaultCurrency string `xorm:"VARCHAR(3) NOT NULL"`
FirstDayOfWeek core.WeekDay `xorm:"TINYINT NOT NULL"`
FiscalYearStart core.FiscalYearStart `xorm:"SMALLINT"`
LongDateFormat core.LongDateFormat `xorm:"TINYINT"`
ShortDateFormat core.ShortDateFormat `xorm:"TINYINT"`
LongTimeFormat core.LongTimeFormat `xorm:"TINYINT"`
ShortTimeFormat core.ShortTimeFormat `xorm:"TINYINT"`
FiscalYearFormat core.FiscalYearFormat `xorm:"TINYINT"`
DecimalSeparator core.DecimalSeparator `xorm:"TINYINT"`
DigitGroupingSymbol core.DigitGroupingSymbol `xorm:"TINYINT"`
DigitGrouping core.DigitGroupingType `xorm:"TINYINT"`
CurrencyDisplayType core.CurrencyDisplayType `xorm:"TINYINT"`
CoordinateDisplayType core.CoordinateDisplayType `xorm:"TINYINT"`
ExpenseAmountColor AmountColorType `xorm:"TINYINT"`
IncomeAmountColor AmountColorType `xorm:"TINYINT"`
FeatureRestriction core.UserFeatureRestrictions
Disabled bool
Deleted bool `xorm:"NOT NULL"`
EmailVerified bool `xorm:"NOT NULL"`
CreatedUnixTime int64
UpdatedUnixTime int64
DeletedUnixTime int64
LastLoginUnixTime int64
ExpenseAmountColor AmountColorType `xorm:"TINYINT"`
IncomeAmountColor AmountColorType `xorm:"TINYINT"`
FeatureRestriction core.UserFeatureRestrictions
Disabled bool
Deleted bool `xorm:"NOT NULL"`
EmailVerified bool `xorm:"NOT NULL"`
CreatedUnixTime int64
UpdatedUnixTime int64
DeletedUnixTime int64
LastLoginUnixTime int64
}
// UserBasicInfo represents a view-object of user basic info
@@ -127,10 +129,12 @@ type UserBasicInfo struct {
Language string `json:"language"`
DefaultCurrency string `json:"defaultCurrency"`
FirstDayOfWeek core.WeekDay `json:"firstDayOfWeek"`
FiscalYearStart core.FiscalYearStart `json:"fiscalYearStart"`
LongDateFormat core.LongDateFormat `json:"longDateFormat"`
ShortDateFormat core.ShortDateFormat `json:"shortDateFormat"`
LongTimeFormat core.LongTimeFormat `json:"longTimeFormat"`
ShortTimeFormat core.ShortTimeFormat `json:"shortTimeFormat"`
FiscalYearFormat core.FiscalYearFormat `json:"fiscalYearFormat"`
DecimalSeparator core.DecimalSeparator `json:"decimalSeparator"`
DigitGroupingSymbol core.DigitGroupingSymbol `json:"digitGroupingSymbol"`
DigitGrouping core.DigitGroupingType `json:"digitGrouping"`
@@ -188,10 +192,12 @@ type UserProfileUpdateRequest struct {
Language string `json:"language" binding:"omitempty,min=2,max=16"`
DefaultCurrency string `json:"defaultCurrency" binding:"omitempty,len=3,validCurrency"`
FirstDayOfWeek *core.WeekDay `json:"firstDayOfWeek" binding:"omitempty,min=0,max=6"`
FiscalYearStart *core.FiscalYearStart `json:"fiscalYearStart" binding:"omitempty,validFiscalYearStart"`
LongDateFormat *core.LongDateFormat `json:"longDateFormat" binding:"omitempty,min=0,max=3"`
ShortDateFormat *core.ShortDateFormat `json:"shortDateFormat" binding:"omitempty,min=0,max=3"`
LongTimeFormat *core.LongTimeFormat `json:"longTimeFormat" binding:"omitempty,min=0,max=3"`
ShortTimeFormat *core.ShortTimeFormat `json:"shortTimeFormat" binding:"omitempty,min=0,max=3"`
FiscalYearFormat *core.FiscalYearFormat `json:"fiscalYearFormat" binding:"omitempty,min=0,max=5"`
DecimalSeparator *core.DecimalSeparator `json:"decimalSeparator" binding:"omitempty,min=0,max=3"`
DigitGroupingSymbol *core.DigitGroupingSymbol `json:"digitGroupingSymbol" binding:"omitempty,min=0,max=4"`
DigitGrouping *core.DigitGroupingType `json:"digitGrouping" binding:"omitempty,min=0,max=2"`
@@ -268,11 +274,13 @@ func (u *User) ToUserBasicInfo(avatarProvider core.UserAvatarProviderType, avata
Language: u.Language,
DefaultCurrency: u.DefaultCurrency,
FirstDayOfWeek: u.FirstDayOfWeek,
FiscalYearStart: u.FiscalYearStart,
LongDateFormat: u.LongDateFormat,
ShortDateFormat: u.ShortDateFormat,
LongTimeFormat: u.LongTimeFormat,
ShortTimeFormat: u.ShortTimeFormat,
DecimalSeparator: u.DecimalSeparator,
FiscalYearFormat: u.FiscalYearFormat,
DigitGroupingSymbol: u.DigitGroupingSymbol,
DigitGrouping: u.DigitGrouping,
CurrencyDisplayType: u.CurrencyDisplayType,
pkg/services/users.go
+8
View File
@@ -289,6 +289,10 @@ func (s *UserService) UpdateUser(c core.Context, user *models.User, modifyUserLa
updateCols = append(updateCols, "first_day_of_week")
}
if core.FISCAL_YEAR_START_MIN <= user.FiscalYearStart && core.FISCAL_YEAR_START_MAX >= user.FiscalYearStart {
updateCols = append(updateCols, "fiscal_year_start")
}
if core.LONG_DATE_FORMAT_DEFAULT <= user.LongDateFormat && user.LongDateFormat <= core.LONG_DATE_FORMAT_D_M_YYYY {
updateCols = append(updateCols, "long_date_format")
}
@@ -305,6 +309,10 @@ func (s *UserService) UpdateUser(c core.Context, user *models.User, modifyUserLa
updateCols = append(updateCols, "short_time_format")
}
if core.FISCAL_YEAR_FORMAT_DEFAULT <= user.FiscalYearFormat && user.FiscalYearFormat <= core.FISCAL_YEAR_FORMAT_ENDYY {
updateCols = append(updateCols, "fiscal_year_format")
}
if core.DECIMAL_SEPARATOR_DEFAULT <= user.DecimalSeparator && user.DecimalSeparator <= core.DECIMAL_SEPARATOR_COMMA {
updateCols = append(updateCols, "decimal_separator")
}
pkg/validators/fiscal_year_start_date.go
+26
View File
@@ -0,0 +1,26 @@
package validators
import (
"github.com/gin-gonic/gin/binding"
"github.com/go-playground/validator/v10"
"github.com/mayswind/ezbookkeeping/pkg/core"
)
// ValidateFiscalYearStart validates if a fiscal year start date is valid
func ValidateFiscalYearStart(fl validator.FieldLevel) bool {
date, ok := fl.Field().Interface().(core.FiscalYearStart)
if !ok {
return false
}
// Use the core functionality to validate
_, _, err := date.GetMonthDay()
return err == nil
}
// RegisterFiscalYearStartValidator registers the fiscal year start date validator
func RegisterFiscalYearStartValidator() {
if v, ok := binding.Validator.Engine().(*validator.Validate); ok {
v.RegisterValidation("validFiscalYearStart", ValidateFiscalYearStart)
}
}
pkg/validators/fiscal_year_start_date_test.go
+68
View File
@@ -0,0 +1,68 @@
package validators
import (
"testing"
"github.com/go-playground/validator/v10"
"github.com/mayswind/ezbookkeeping/pkg/core"
"github.com/stretchr/testify/assert"
)
type fiscalYearStartContainer struct {
FiscalYearStart core.FiscalYearStart `validate:"validFiscalYearStart"`
}
func TestValidateFiscalYearStart_ValidValues(t *testing.T) {
validate := validator.New()
validate.RegisterValidation("validFiscalYearStart", ValidateFiscalYearStart)
testCases := []struct {
name string
value core.FiscalYearStart
}{
{"January 1", 0x0101}, // January 1
{"December 31", 0x0C1F}, // December 31
{"July 1", 0x0701}, // July 1
{"April 15", 0x040F}, // April 15
}
for _, tc := range testCases {
t.Run(tc.name, func(t *testing.T) {
container := fiscalYearStartContainer{FiscalYearStart: tc.value}
err := validate.Struct(container)
assert.Nil(t, err)
})
}
}
func TestValidateFiscalYearStart_InvalidValues(t *testing.T) {
validate := validator.New()
validate.RegisterValidation("validFiscalYearStart", ValidateFiscalYearStart)
testCases := []struct {
name string
value core.FiscalYearStart
}{
{"Zero value", 0}, // Zero value
{"Month 0", 0x0001}, // Month 0 (invalid)
{"Month 13", 0x0D01}, // Month 13 (invalid)
{"Day 0", 0x0100}, // Day 0 (invalid)
{"January 32", 0x0120}, // January 32 (invalid)
{"February 29", 0x021D}, // February 29 (not permitted)
{"February 30", 0x021E}, // February 30 (invalid)
{"April 31", 0x041F}, // April 31 (invalid)
{"June 31", 0x061F}, // June 31 (invalid)
{"September 31", 0x091F}, // September 31 (invalid)
{"November 32", 0x0B20}, // November 32 (invalid)
{"Invalid month 255", 0xFF01}, // Invalid month
{"Invalid day 255", 0x01FF}, // Invalid day
}
for _, tc := range testCases {
t.Run(tc.name, func(t *testing.T) {
container := fiscalYearStartContainer{FiscalYearStart: tc.value}
err := validate.Struct(container)
assert.NotNil(t, err)
})
}
}