fix: envelope balance does not roll over

Author: morremeyer

docs/usage.md

@@ -21,6 +21,8 @@ The key of the budget. Each envelope tracks budget for one specific purpose, e.g
 
 If you do not spend all of the allocated budget, it rolls over to the next month. This allows to allocate a budget for expenses that do not occur that often. Say you have an insurance that is billed yearly for 120€. In this case, you can budget 10€ per month for this insurance. Once the bill arrives, all the needed budget is already allocated.
 
+Contrary to other popular tools, if you overspend on an Envelope, the negative balance also rolls over to the next month and has to be balanced by allocating this amount. It is planned to make this behaviour configurable by budget. If you want to help out in the development of this, see [#327](https://github.com/envelope-zero/backend/issues/327).
+
 ### Transaction
 
 A transaction represents an actual transaction. Paying for groceries, getting paid your salary, gifting somebody money for their wedding, all of those are transactions. Every transaction must be tied to a source account and destination account.

pkg/controllers/budget_test.go

@@ -307,7 +307,7 @@ func (suite *TestSuiteEnv) TestBudgetMonth() {
 							Name:       "Utilities",
 							Month:      time.Date(2022, 2, 1, 0, 0, 0, 0, time.UTC),
 							Spent:      decimal.NewFromFloat(-5),
-							Balance:    decimal.NewFromFloat(42.12),
+							Balance:    decimal.NewFromFloat(53.11),
 							Allocation: decimal.NewFromFloat(47.12),
 						},
 					},
@@ -325,7 +325,7 @@ func (suite *TestSuiteEnv) TestBudgetMonth() {
 							Name:       "Utilities",
 							Month:      time.Date(2022, 3, 1, 0, 0, 0, 0, time.UTC),
 							Spent:      decimal.NewFromFloat(-15),
-							Balance:    decimal.NewFromFloat(16.17),
+							Balance:    decimal.NewFromFloat(69.28),
 							Allocation: decimal.NewFromFloat(31.17),
 						},
 					},

pkg/controllers/envelope_test.go

@@ -285,7 +285,7 @@ func (suite *TestSuiteEnv) TestEnvelopeMonth() {
 				Name:       "Utilities",
 				Month:      time.Date(2022, 2, 1, 0, 0, 0, 0, time.UTC),
 				Spent:      decimal.NewFromFloat(-5),
-				Balance:    decimal.NewFromFloat(42.12),
+				Balance:    decimal.NewFromFloat(53.11),
 				Allocation: decimal.NewFromFloat(47.12),
 			},
 		},
@@ -295,7 +295,7 @@ func (suite *TestSuiteEnv) TestEnvelopeMonth() {
 				Name:       "Utilities",
 				Month:      time.Date(2022, 3, 1, 0, 0, 0, 0, time.UTC),
 				Spent:      decimal.NewFromFloat(-15),
-				Balance:    decimal.NewFromFloat(16.17),
+				Balance:    decimal.NewFromFloat(69.28),
 				Allocation: decimal.NewFromFloat(31.17),
 			},
 		},
@@ -312,6 +312,8 @@ func (suite *TestSuiteEnv) TestEnvelopeMonth() {
 		},
 	}
 
+	// Sum alloc: 99.28
+
 	var envelopeMonth controllers.EnvelopeMonthResponse
 	for _, tt := range tests {
 		r := test.Request(suite.T(), http.MethodGet, tt.path, "")

pkg/models/envelope.go

@@ -65,6 +65,72 @@ func (e Envelope) Spent(t time.Time) decimal.Decimal {
 	return incomingSum.Sub(outgoingSum)
 }
 
+// Balance calculates the balance of an Envelope in a specific month
+// This code performs negative and positive rollover. See also
+// https://github.com/envelope-zero/backend/issues/327
+func (e Envelope) Balance(month time.Time) (decimal.Decimal, error) {
+	// We add one month as the balance should include all transactions and the allocation for the present month
+	// With that, we can query for all resources where the date/month is < the month
+	month = time.Date(month.Year(), month.AddDate(0, 1, 0).Month(), 1, 0, 0, 0, 0, time.UTC)
+
+	// Sum of incoming transactions
+	var incoming decimal.NullDecimal
+	err := database.DB.
+		Table("transactions").
+		Select("SUM(amount)").
+		Joins("JOIN accounts source_account ON transactions.source_account_id = source_account.id AND source_account.deleted_at IS NULL").
+		Joins("JOIN accounts destination_account ON transactions.destination_account_id = destination_account.id AND destination_account.deleted_at IS NULL").
+		Where("source_account.external = 1 AND destination_account.external = 0 AND transactions.envelope_id = ?", e.ID).
+		Where("transactions.date < date(?) ", month).
+		Find(&incoming).Error
+	if err != nil {
+		return decimal.Zero, err
+	}
+
+	// If no transactions are found, the value is nil
+	if !incoming.Valid {
+		incoming.Decimal = decimal.Zero
+	}
+
+	// Sum of outgoing transactions
+	var outgoing decimal.NullDecimal
+	err = database.DB.
+		Table("transactions").
+		Select("SUM(amount)").
+		Joins("JOIN accounts source_account ON transactions.source_account_id = source_account.id AND source_account.deleted_at IS NULL").
+		Joins("JOIN accounts destination_account ON transactions.destination_account_id = destination_account.id AND destination_account.deleted_at IS NULL").
+		Where("source_account.external = 0 AND destination_account.external = 1 AND transactions.envelope_id = ?", e.ID).
+		Where("transactions.date < date(?) ", month).
+		Find(&outgoing).Error
+	if err != nil {
+		return decimal.Zero, err
+	}
+
+	// If no transactions are found, the value is nil
+	if !outgoing.Valid {
+		outgoing.Decimal = decimal.Zero
+	}
+
+	var budgeted decimal.NullDecimal
+	err = database.DB.
+		Select("SUM(amount)").
+		Where("allocations.envelope_id = ?", e.ID).
+		Where("allocations.month < date(?) ", month).
+		Table("allocations").
+		Find(&budgeted).
+		Error
+	if err != nil {
+		return decimal.Zero, err
+	}
+
+	// If no transactions are found, the value is nil
+	if !budgeted.Valid {
+		budgeted.Decimal = decimal.Zero
+	}
+
+	return budgeted.Decimal.Add(incoming.Decimal).Sub(outgoing.Decimal), nil
+}
+
 // Month calculates the month specific values for an envelope and returns an EnvelopeMonth for them.
 func (e Envelope) Month(t time.Time) (EnvelopeMonth, error) {
 	spent := e.Spent(t)
@@ -92,7 +158,11 @@ func (e Envelope) Month(t time.Time) (EnvelopeMonth, error) {
 		return EnvelopeMonth{}, err
 	}
 
-	envelopeMonth.Balance = allocation.Amount.Add(spent)
+	envelopeMonth.Balance, err = e.Balance(month)
+	if err != nil {
+		return EnvelopeMonth{}, err
+	}
+
 	envelopeMonth.Allocation = allocation.Amount
 	return envelopeMonth, nil
 }

pkg/models/envelope_test.go

@@ -60,6 +60,8 @@ func (suite *TestSuiteEnv) TestEnvelopeMonthSum() {
 		suite.Assert().Fail("Resource could not be saved", err)
 	}
 
+	january := time.Date(2022, 1, 1, 0, 0, 0, 0, time.UTC)
+
 	spent := decimal.NewFromFloat(17.32)
 	transaction := &models.Transaction{
 		TransactionCreate: models.TransactionCreate{
@@ -68,7 +70,7 @@ func (suite *TestSuiteEnv) TestEnvelopeMonthSum() {
 			Amount:               spent,
 			SourceAccountID:      internalAccount.ID,
 			DestinationAccountID: externalAccount.ID,
-			Date:                 time.Date(2022, 1, 15, 0, 0, 0, 0, time.UTC),
+			Date:                 january,
 		},
 	}
 	err = database.DB.Create(&transaction).Error
@@ -83,19 +85,19 @@ func (suite *TestSuiteEnv) TestEnvelopeMonthSum() {
 			Amount:               spent.Neg(),
 			SourceAccountID:      externalAccount.ID,
 			DestinationAccountID: internalAccount.ID,
-			Date:                 time.Date(2022, 2, 15, 0, 0, 0, 0, time.UTC),
+			Date:                 january.AddDate(0, 1, 0),
 		},
 	}
 	err = database.DB.Create(&transactionIn).Error
 	if err != nil {
 		suite.Assert().Fail("Resource could not be saved", err)
 	}
 
-	envelopeMonth, err := envelope.Month(time.Date(2022, 1, 1, 0, 0, 0, 0, time.UTC))
+	envelopeMonth, err := envelope.Month(january)
 	assert.Nil(suite.T(), err)
 	assert.True(suite.T(), envelopeMonth.Spent.Equal(spent.Neg()), "Month calculation for 2022-01 is wrong: should be %v, but is %v", spent.Neg(), envelopeMonth.Spent)
 
-	envelopeMonth, err = envelope.Month(time.Date(2022, 2, 1, 0, 0, 0, 0, time.UTC))
+	envelopeMonth, err = envelope.Month(january.AddDate(0, 1, 0))
 	assert.Nil(suite.T(), err)
 	assert.True(suite.T(), envelopeMonth.Spent.Equal(spent.Neg()), "Month calculation for 2022-02 is wrong: should be %v, but is %v", spent, envelopeMonth.Spent)
 
@@ -104,7 +106,7 @@ func (suite *TestSuiteEnv) TestEnvelopeMonthSum() {
 		suite.Assert().Fail("Resource could not be deleted", err)
 	}
 
-	envelopeMonth, err = envelope.Month(time.Date(2022, 1, 1, 0, 0, 0, 0, time.UTC))
+	envelopeMonth, err = envelope.Month(january)
 	assert.Nil(suite.T(), err)
 	assert.True(suite.T(), envelopeMonth.Spent.Equal(decimal.NewFromFloat(0)), "Month calculation for 2022-01 is wrong: should be %v, but is %v", decimal.NewFromFloat(0), envelopeMonth.Spent)
 }
@@ -160,5 +162,123 @@ func (suite *TestSuiteEnv) TestCreateTransactionNoEnvelope() {
 	}
 	err = database.DB.Create(&transaction).Error
 
-	assert.Nil(suite.T(), err, "Transactions must be able to be created without an envelope (to enable internal transfers without an Envelope)")
+	assert.Nil(suite.T(), err, "Transactions must be able to be created without an envelope (to enable internal transfers without an Envelope and income transactions)")
+}
+
+func (suite *TestSuiteEnv) TestEnvelopeMonthBalance() {
+	budget := models.Budget{}
+	err := database.DB.Save(&budget).Error
+	if err != nil {
+		suite.Assert().Fail("Resource could not be saved", err)
+	}
+
+	internalAccount := &models.Account{
+		AccountCreate: models.AccountCreate{
+			Name:     "Internal Source Account",
+			BudgetID: budget.ID,
+		},
+	}
+	err = database.DB.Create(internalAccount).Error
+	if err != nil {
+		suite.Assert().Fail("Resource could not be saved", err)
+	}
+
+	externalAccount := &models.Account{
+		AccountCreate: models.AccountCreate{
+			Name:     "External Destination Account",
+			BudgetID: budget.ID,
+			External: true,
+		},
+	}
+	err = database.DB.Create(&externalAccount).Error
+	if err != nil {
+		suite.Assert().Fail("Resource could not be saved", err)
+	}
+
+	category := models.Category{
+		CategoryCreate: models.CategoryCreate{
+			BudgetID: budget.ID,
+		},
+	}
+	err = database.DB.Save(&category).Error
+	if err != nil {
+		suite.Assert().Fail("Resource could not be saved", err)
+	}
+
+	envelope := &models.Envelope{
+		EnvelopeCreate: models.EnvelopeCreate{
+			Name:       "Testing envelope",
+			CategoryID: category.ID,
+		},
+	}
+	err = database.DB.Create(&envelope).Error
+	if err != nil {
+		suite.Assert().Fail("Resource could not be saved", err)
+	}
+
+	january := time.Date(2022, 1, 1, 0, 0, 0, 0, time.UTC)
+
+	allocationJan := &models.Allocation{
+		AllocationCreate: models.AllocationCreate{
+			EnvelopeID: envelope.ID,
+			Month:      january,
+			Amount:     decimal.NewFromFloat(50),
+		},
+	}
+	err = database.DB.Create(&allocationJan).Error
+	if err != nil {
+		suite.Assert().Fail("Resource could not be saved", err)
+	}
+
+	allocationFeb := &models.Allocation{
+		AllocationCreate: models.AllocationCreate{
+			EnvelopeID: envelope.ID,
+			Month:      january.AddDate(0, 1, 0),
+			Amount:     decimal.NewFromFloat(40),
+		},
+	}
+	err = database.DB.Create(&allocationFeb).Error
+	if err != nil {
+		suite.Assert().Fail("Resource could not be saved", err)
+	}
+
+	transaction := &models.Transaction{
+		TransactionCreate: models.TransactionCreate{
+			BudgetID:             budget.ID,
+			EnvelopeID:           &envelope.ID,
+			Amount:               decimal.NewFromFloat(15),
+			SourceAccountID:      internalAccount.ID,
+			DestinationAccountID: externalAccount.ID,
+			Date:                 january,
+		},
+	}
+	err = database.DB.Create(&transaction).Error
+	if err != nil {
+		suite.Assert().Fail("Resource could not be saved", err)
+	}
+
+	transaction2 := &models.Transaction{
+		TransactionCreate: models.TransactionCreate{
+			BudgetID:             budget.ID,
+			EnvelopeID:           &envelope.ID,
+			Amount:               decimal.NewFromFloat(30),
+			SourceAccountID:      internalAccount.ID,
+			DestinationAccountID: externalAccount.ID,
+			Date:                 january.AddDate(0, 1, 0),
+		},
+	}
+	err = database.DB.Create(&transaction2).Error
+	if err != nil {
+		suite.Assert().Fail("Resource could not be saved", err)
+	}
+
+	shouldBalance := decimal.NewFromFloat(35)
+	envelopeMonth, err := envelope.Month(january)
+	assert.Nil(suite.T(), err)
+	assert.True(suite.T(), envelopeMonth.Balance.Equal(shouldBalance), "Balance calculation for 2022-01 is wrong: should be %v, but is %v", shouldBalance, envelopeMonth.Balance)
+
+	shouldBalance = decimal.NewFromFloat(45)
+	envelopeMonth, err = envelope.Month(january.AddDate(0, 1, 0))
+	assert.Nil(suite.T(), err)
+	assert.True(suite.T(), envelopeMonth.Balance.Equal(shouldBalance), "Balance calculation for 2022-02 is wrong: should be %v, but is %v", shouldBalance, envelopeMonth.Balance)
 }