mirror of https://github.com/ghostfolio/ghostfolio
Yip Shing him
3 weeks ago
1 changed files with 516 additions and 0 deletions
@ -0,0 +1,516 @@ |
|||||
|
# Budget Categories and CSPF-Inspired Budget Page Implementation Plan |
||||
|
|
||||
|
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. |
||||
|
|
||||
|
**Goal:** Add first-class expense category management and evolve the Budget page toward the CS Personal Finance Budget tab model: monthly budget lines, yearly expenses converted to monthly amounts, bank-account transfer summaries, and planned-vs-actual statistics. |
||||
|
|
||||
|
**Architecture:** Keep expense categories user-owned and reusable across expenses and budgets. Treat each monthly budget row as a budget line with item name, amount, account, category, and type instead of only one amount per category. Yearly expenses are separate user-owned records that the API converts into automatic monthly budget rows and summary totals. |
||||
|
|
||||
|
**Tech Stack:** Angular 21 standalone components, Angular Material table/dialog/form controls, NestJS, Prisma, PostgreSQL, Nx, Jest, Ghostfolio `DataService`, Ghostfolio permissions. |
||||
|
|
||||
|
**Reference:** CS Personal Finance Budget guide: `https://guide.cspersonalfinance.io/summary-tabs/budget` |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## What We Can Bring From CS Personal Finance |
||||
|
|
||||
|
The source Budget tab has five useful concepts: |
||||
|
|
||||
|
- Monthly budget table: item name, monthly amount, bank account, and category. |
||||
|
- Yearly expenses table: annual or irregular expenses converted into equivalent monthly cost. |
||||
|
- Automatic bank transfers: grouped view showing how much money needs to be sent to each bank account each month. |
||||
|
- Graphs and statistics: planned spend, actual spend, monthly savings, yearly savings, and estimated savings rate. |
||||
|
- Settings overview: read-only summary of assumptions used for calculations. |
||||
|
|
||||
|
Ghostfolio can support these, but with app-native data models instead of spreadsheet cells: |
||||
|
|
||||
|
- Expense categories become managed entities with create, edit, delete, color, and duplicate-name validation. |
||||
|
- Monthly budget rows become editable records in the Budget page. |
||||
|
- Yearly expenses become separate records and are displayed as automatic budget rows. |
||||
|
- Actual spend comes from the `Expense` table, using monthly totals and 6-month average actual spend. |
||||
|
- Account transfer summaries group monthly budget rows by `accountId`. |
||||
|
|
||||
|
## Current State |
||||
|
|
||||
|
- `ExpenseCategory`, `Expense`, and `Budget` Prisma models exist on this branch. |
||||
|
- Budget UI can create and edit monthly category budgets. |
||||
|
- Budget dialog now fetches existing categories, but there is no UI to create or manage categories. |
||||
|
- Budget rows are currently category-level only, so they cannot fully represent CS Personal Finance item-level budget rows yet. |
||||
|
|
||||
|
## Recommended Scope |
||||
|
|
||||
|
Build this in three slices: |
||||
|
|
||||
|
1. Category management inside the Budget page. |
||||
|
2. Budget line upgrade: item name, account, category, amount, and budget type. |
||||
|
3. CSPF-inspired yearly expense and statistics sections. |
||||
|
|
||||
|
This keeps each slice testable and usable without waiting for the full spreadsheet-style experience. |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## File Structure |
||||
|
|
||||
|
- Modify `prisma/schema.prisma`: extend `Budget`, add `BudgetType` enum, add `YearlyExpense`. |
||||
|
- Modify `libs/common/src/lib/dtos/`: add yearly expense DTOs and extend budget DTOs with `name`, `accountId`, and `type`. |
||||
|
- Modify `libs/common/src/lib/interfaces/responses/`: extend budget responses and add yearly expense/budget summary interfaces. |
||||
|
- Modify `apps/api/src/app/budgets/`: add category CRUD, budget line support, yearly expense support, and summary calculations. |
||||
|
- Modify `libs/ui/src/lib/services/data.service.ts`: add category CRUD and yearly expense methods. |
||||
|
- Modify `apps/client/src/app/pages/portfolio/budget/`: add category management dialog, yearly expense dialog, transfer summary, and statistics panels. |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## Task 1: Add Category Management API |
||||
|
|
||||
|
**Files:** |
||||
|
|
||||
|
- Modify: `apps/api/src/app/budgets/budgets.controller.ts` |
||||
|
- Modify: `apps/api/src/app/budgets/budgets.service.ts` |
||||
|
- Modify: `apps/api/src/app/budgets/budgets.service.spec.ts` |
||||
|
- Modify: `libs/ui/src/lib/services/data.service.ts` |
||||
|
- Modify: `libs/ui/src/lib/services/data.service.spec.ts` |
||||
|
|
||||
|
- [ ] **Step 1: Add failing service tests** |
||||
|
|
||||
|
Add tests for: |
||||
|
|
||||
|
```ts |
||||
|
it('creates an expense category for the current user'); |
||||
|
it('rejects duplicate category names for the current user'); |
||||
|
it('updates only categories owned by the current user'); |
||||
|
it('deletes only categories owned by the current user'); |
||||
|
``` |
||||
|
|
||||
|
Expected Prisma mocks: |
||||
|
|
||||
|
```ts |
||||
|
expenseCategory.create; |
||||
|
expenseCategory.delete; |
||||
|
expenseCategory.findFirst; |
||||
|
expenseCategory.findMany; |
||||
|
expenseCategory.update; |
||||
|
``` |
||||
|
|
||||
|
- [ ] **Step 2: Add service methods** |
||||
|
|
||||
|
Implement these methods in `BudgetsService`: |
||||
|
|
||||
|
```ts |
||||
|
createCategory({ data, userId }: { data: CreateExpenseCategoryDto; userId: string }) |
||||
|
updateCategory({ data, id, userId }: { data: UpdateExpenseCategoryDto; id: string; userId: string }) |
||||
|
deleteCategory({ id, userId }: { id: string; userId: string }) |
||||
|
``` |
||||
|
|
||||
|
Use `ConflictException` when a category name already exists for the same user. Use `ForbiddenException` when the category does not belong to the user. |
||||
|
|
||||
|
- [ ] **Step 3: Add controller endpoints** |
||||
|
|
||||
|
Add: |
||||
|
|
||||
|
```ts |
||||
|
POST /api/v1/budgets/categories |
||||
|
PUT /api/v1/budgets/categories/:id |
||||
|
DELETE /api/v1/budgets/categories/:id |
||||
|
``` |
||||
|
|
||||
|
Permissions: |
||||
|
|
||||
|
```ts |
||||
|
createExpenseCategory; |
||||
|
updateExpenseCategory; |
||||
|
deleteExpenseCategory; |
||||
|
``` |
||||
|
|
||||
|
- [ ] **Step 4: Add client service methods** |
||||
|
|
||||
|
Add to `DataService`: |
||||
|
|
||||
|
```ts |
||||
|
createExpenseCategory(category: CreateExpenseCategoryDto) |
||||
|
updateExpenseCategory({ category, id }: { category: UpdateExpenseCategoryDto; id: string }) |
||||
|
deleteExpenseCategory(id: string) |
||||
|
``` |
||||
|
|
||||
|
- [ ] **Step 5: Verify** |
||||
|
|
||||
|
Run: |
||||
|
|
||||
|
```bash |
||||
|
./node_modules/.bin/nx test api --testFile=budgets.service.spec.ts --runInBand |
||||
|
./node_modules/.bin/nx test ui --testFile=data.service.spec.ts --runInBand |
||||
|
``` |
||||
|
|
||||
|
- [ ] **Step 6: Commit** |
||||
|
|
||||
|
```bash |
||||
|
git add apps/api/src/app/budgets libs/ui/src/lib/services/data.service.ts libs/ui/src/lib/services/data.service.spec.ts |
||||
|
git commit -m "feat: add budget category management api" |
||||
|
``` |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## Task 2: Add Category Management UI |
||||
|
|
||||
|
**Files:** |
||||
|
|
||||
|
- Modify: `apps/client/src/app/pages/portfolio/budget/budget-page.component.ts` |
||||
|
- Modify: `apps/client/src/app/pages/portfolio/budget/budget-page.html` |
||||
|
- Modify: `apps/client/src/app/pages/portfolio/budget/budget-page.component.spec.ts` |
||||
|
- Create: `apps/client/src/app/pages/portfolio/budget/manage-budget-categories-dialog/manage-budget-categories-dialog.component.ts` |
||||
|
- Create: `apps/client/src/app/pages/portfolio/budget/manage-budget-categories-dialog/manage-budget-categories-dialog.html` |
||||
|
- Create: `apps/client/src/app/pages/portfolio/budget/manage-budget-categories-dialog/manage-budget-categories-dialog.scss` |
||||
|
- Create: `apps/client/src/app/pages/portfolio/budget/manage-budget-categories-dialog/manage-budget-categories-dialog.component.spec.ts` |
||||
|
|
||||
|
- [ ] **Step 1: Add a Manage Categories button** |
||||
|
|
||||
|
Place a secondary button near `Create budget`: |
||||
|
|
||||
|
```html |
||||
|
<button mat-stroked-button type="button" (click)="onManageCategories()"> |
||||
|
Manage categories |
||||
|
</button> |
||||
|
``` |
||||
|
|
||||
|
- [ ] **Step 2: Build the dialog** |
||||
|
|
||||
|
The dialog should show: |
||||
|
|
||||
|
- Category name input. |
||||
|
- Optional color input. |
||||
|
- Create button. |
||||
|
- Table/list of existing categories. |
||||
|
- Edit and delete icon buttons. |
||||
|
|
||||
|
Use `MatDialogModule`, `MatFormFieldModule`, `MatInputModule`, `MatButtonModule`, `MatIconModule`, and `MatTableModule`. |
||||
|
|
||||
|
- [ ] **Step 3: Refresh budget dialog category list** |
||||
|
|
||||
|
After categories are created or edited, closing the category dialog with `{ refresh: true }` should allow the next Budget dialog open to fetch the latest categories. |
||||
|
|
||||
|
- [ ] **Step 4: Verify** |
||||
|
|
||||
|
Run: |
||||
|
|
||||
|
```bash |
||||
|
./node_modules/.bin/nx test client --testFile=manage-budget-categories-dialog.component.spec.ts --runInBand |
||||
|
./node_modules/.bin/nx test client --testFile=budget-page.component.spec.ts --runInBand |
||||
|
``` |
||||
|
|
||||
|
- [ ] **Step 5: Commit** |
||||
|
|
||||
|
```bash |
||||
|
git add apps/client/src/app/pages/portfolio/budget |
||||
|
git commit -m "feat: add budget category management ui" |
||||
|
``` |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## Task 3: Upgrade Budget Rows Into Monthly Budget Lines |
||||
|
|
||||
|
**Files:** |
||||
|
|
||||
|
- Modify: `prisma/schema.prisma` |
||||
|
- Modify: `libs/common/src/lib/dtos/create-budget.dto.ts` |
||||
|
- Modify: `libs/common/src/lib/dtos/update-budget.dto.ts` |
||||
|
- Modify: `libs/common/src/lib/interfaces/responses/budget-response.interface.ts` |
||||
|
- Modify: `apps/api/src/app/budgets/budgets.service.ts` |
||||
|
- Modify: `apps/api/src/app/budgets/budgets.service.spec.ts` |
||||
|
- Modify: `apps/client/src/app/pages/portfolio/budget/create-or-update-budget-dialog/*` |
||||
|
- Modify: `apps/client/src/app/pages/portfolio/budget/budget-page.*` |
||||
|
|
||||
|
- [ ] **Step 1: Extend the Prisma model** |
||||
|
|
||||
|
Add: |
||||
|
|
||||
|
```prisma |
||||
|
enum BudgetType { |
||||
|
EXPENSE |
||||
|
CASH_SAVINGS |
||||
|
INVESTMENT_SAVINGS |
||||
|
YEARLY_EXPENSE_AUTOMATIC |
||||
|
LIABILITY_AUTOMATIC |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
Extend `Budget`: |
||||
|
|
||||
|
```prisma |
||||
|
account Account? @relation(fields: [accountId, accountUserId], references: [id, userId]) |
||||
|
accountId String? |
||||
|
accountUserId String? |
||||
|
name String |
||||
|
type BudgetType @default(EXPENSE) |
||||
|
``` |
||||
|
|
||||
|
Replace the current unique category/month constraint with: |
||||
|
|
||||
|
```prisma |
||||
|
@@index([accountId]) |
||||
|
@@index([type]) |
||||
|
``` |
||||
|
|
||||
|
Keep the existing indexes on `categoryId`, `month`, and `userId`. |
||||
|
|
||||
|
- [ ] **Step 2: Update contracts** |
||||
|
|
||||
|
Add to create/update DTOs: |
||||
|
|
||||
|
```ts |
||||
|
accountId?: string; |
||||
|
name: string; |
||||
|
type: 'EXPENSE' | 'CASH_SAVINGS' | 'INVESTMENT_SAVINGS'; |
||||
|
``` |
||||
|
|
||||
|
Do not allow clients to submit automatic types directly. |
||||
|
|
||||
|
- [ ] **Step 3: Update API calculations** |
||||
|
|
||||
|
`getBudgets()` should return manual monthly budget lines plus automatic yearly expense rows from Task 4. Totals should calculate: |
||||
|
|
||||
|
```ts |
||||
|
totalBudgeted = sum(all row amounts) |
||||
|
totalPlannedSpend = sum(EXPENSE + YEARLY_EXPENSE_AUTOMATIC + LIABILITY_AUTOMATIC) |
||||
|
totalMonthlySavings = sum(CASH_SAVINGS + INVESTMENT_SAVINGS) |
||||
|
totalRemaining = totalBudgeted - totalSpent |
||||
|
``` |
||||
|
|
||||
|
- [ ] **Step 4: Update UI table columns** |
||||
|
|
||||
|
Columns should become: |
||||
|
|
||||
|
```ts |
||||
|
[ |
||||
|
'name', |
||||
|
'category', |
||||
|
'account', |
||||
|
'type', |
||||
|
'amount', |
||||
|
'spent', |
||||
|
'remaining', |
||||
|
'progress', |
||||
|
'actions' |
||||
|
]; |
||||
|
``` |
||||
|
|
||||
|
The dialog should ask for item name, account, category, type, month, and amount. |
||||
|
|
||||
|
- [ ] **Step 5: Verify** |
||||
|
|
||||
|
Run: |
||||
|
|
||||
|
```bash |
||||
|
./node_modules/.bin/nx test api --testFile=budgets.service.spec.ts --runInBand |
||||
|
./node_modules/.bin/nx test client --testFile=create-or-update-budget-dialog.component.spec.ts --runInBand |
||||
|
./node_modules/.bin/nx test client --testFile=budget-page.component.spec.ts --runInBand |
||||
|
./node_modules/.bin/nx run api:build |
||||
|
./node_modules/.bin/nx run client:build:development-en |
||||
|
``` |
||||
|
|
||||
|
- [ ] **Step 6: Commit** |
||||
|
|
||||
|
```bash |
||||
|
git add prisma/schema.prisma libs/common apps/api/src/app/budgets apps/client/src/app/pages/portfolio/budget |
||||
|
git commit -m "feat: support monthly budget lines" |
||||
|
``` |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## Task 4: Add Yearly Expenses |
||||
|
|
||||
|
**Files:** |
||||
|
|
||||
|
- Modify: `prisma/schema.prisma` |
||||
|
- Create: `libs/common/src/lib/dtos/create-yearly-expense.dto.ts` |
||||
|
- Create: `libs/common/src/lib/dtos/update-yearly-expense.dto.ts` |
||||
|
- Modify: `libs/common/src/lib/dtos/index.ts` |
||||
|
- Create: `libs/common/src/lib/interfaces/responses/yearly-expense-response.interface.ts` |
||||
|
- Modify: `libs/common/src/lib/interfaces/index.ts` |
||||
|
- Modify: `apps/api/src/app/budgets/budgets.controller.ts` |
||||
|
- Modify: `apps/api/src/app/budgets/budgets.service.ts` |
||||
|
- Modify: `apps/api/src/app/budgets/budgets.service.spec.ts` |
||||
|
- Modify: `libs/ui/src/lib/services/data.service.ts` |
||||
|
- Modify: `apps/client/src/app/pages/portfolio/budget/*` |
||||
|
|
||||
|
- [ ] **Step 1: Add Prisma model** |
||||
|
|
||||
|
```prisma |
||||
|
model YearlyExpense { |
||||
|
account Account? @relation(fields: [accountId, accountUserId], references: [id, userId]) |
||||
|
accountId String? |
||||
|
accountUserId String? |
||||
|
category ExpenseCategory @relation(fields: [categoryId], onDelete: Cascade, references: [id]) |
||||
|
categoryId String |
||||
|
createdAt DateTime @default(now()) |
||||
|
currency String |
||||
|
id String @id @default(uuid()) |
||||
|
name String |
||||
|
updatedAt DateTime @updatedAt |
||||
|
user User @relation(fields: [userId], onDelete: Cascade, references: [id]) |
||||
|
userId String |
||||
|
yearlyCost Float |
||||
|
|
||||
|
@@index([accountId]) |
||||
|
@@index([categoryId]) |
||||
|
@@index([userId]) |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
- [ ] **Step 2: Add yearly expense endpoints** |
||||
|
|
||||
|
Add: |
||||
|
|
||||
|
```ts |
||||
|
GET /api/v1/budgets/yearly-expenses |
||||
|
POST /api/v1/budgets/yearly-expenses |
||||
|
PUT /api/v1/budgets/yearly-expenses/:id |
||||
|
DELETE /api/v1/budgets/yearly-expenses/:id |
||||
|
``` |
||||
|
|
||||
|
Use budget permissions for now: |
||||
|
|
||||
|
```ts |
||||
|
readBudgets; |
||||
|
createBudget; |
||||
|
updateBudget; |
||||
|
deleteBudget; |
||||
|
``` |
||||
|
|
||||
|
- [ ] **Step 3: Include automatic rows in `getBudgets()`** |
||||
|
|
||||
|
For each yearly expense, emit an automatic budget row: |
||||
|
|
||||
|
```ts |
||||
|
amount = yearlyCost / 12; |
||||
|
type = 'YEARLY_EXPENSE_AUTOMATIC'; |
||||
|
name = `${yearlyExpense.name} (yearly)`; |
||||
|
``` |
||||
|
|
||||
|
These rows should not be editable from the monthly budget table. They are edited in the Yearly Expenses table. |
||||
|
|
||||
|
- [ ] **Step 4: Add Yearly Expenses UI section** |
||||
|
|
||||
|
Below the monthly table, add a compact table: |
||||
|
|
||||
|
```ts |
||||
|
['name', 'category', 'account', 'yearlyCost', 'monthlyEquivalent', 'actions']; |
||||
|
``` |
||||
|
|
||||
|
Add create/edit dialog with fields: |
||||
|
|
||||
|
- Name |
||||
|
- Category |
||||
|
- Account |
||||
|
- Yearly cost |
||||
|
|
||||
|
- [ ] **Step 5: Verify and commit** |
||||
|
|
||||
|
Run the same API/client tests and builds from Task 3, then commit: |
||||
|
|
||||
|
```bash |
||||
|
git commit -m "feat: add yearly budget expenses" |
||||
|
``` |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## Task 5: Add Transfer Summary and Budget Statistics |
||||
|
|
||||
|
**Files:** |
||||
|
|
||||
|
- Modify: `libs/common/src/lib/interfaces/responses/budget-response.interface.ts` |
||||
|
- Modify: `apps/api/src/app/budgets/budgets.service.ts` |
||||
|
- Modify: `apps/api/src/app/budgets/budgets.service.spec.ts` |
||||
|
- Modify: `apps/client/src/app/pages/portfolio/budget/budget-page.component.ts` |
||||
|
- Modify: `apps/client/src/app/pages/portfolio/budget/budget-page.html` |
||||
|
- Modify: `apps/client/src/app/pages/portfolio/budget/budget-page.scss` |
||||
|
- Modify: `apps/client/src/app/pages/portfolio/budget/budget-page.component.spec.ts` |
||||
|
|
||||
|
- [ ] **Step 1: Extend `BudgetsResponse`** |
||||
|
|
||||
|
Add: |
||||
|
|
||||
|
```ts |
||||
|
actualSpendAverage: number; |
||||
|
estimatedSavingsRate: number; |
||||
|
totalMonthlySavings: number; |
||||
|
totalPlannedSpend: number; |
||||
|
totalYearlySavings: number; |
||||
|
transfers: Array<{ |
||||
|
accountId?: string; |
||||
|
accountName: string; |
||||
|
amount: number; |
||||
|
}>; |
||||
|
``` |
||||
|
|
||||
|
- [ ] **Step 2: Calculate 6-month actual spend** |
||||
|
|
||||
|
In `BudgetsService`, calculate actual spend as the average monthly sum of `Expense.amount` over the six months ending with the selected month. |
||||
|
|
||||
|
- [ ] **Step 3: Calculate transfer rows** |
||||
|
|
||||
|
Group all monthly and yearly automatic budget rows by account: |
||||
|
|
||||
|
```ts |
||||
|
transfers = rows.reduce((byAccount, row) => { |
||||
|
byAccount[row.accountId ?? 'unassigned'] += row.amount; |
||||
|
return byAccount; |
||||
|
}, {}); |
||||
|
``` |
||||
|
|
||||
|
- [ ] **Step 4: Render stats and transfer summary** |
||||
|
|
||||
|
Add top summary metrics: |
||||
|
|
||||
|
- Planned spend |
||||
|
- Actual spend average |
||||
|
- Monthly savings |
||||
|
- Yearly savings |
||||
|
- Estimated savings rate |
||||
|
|
||||
|
Add a compact transfer table: |
||||
|
|
||||
|
```ts |
||||
|
['account', 'amount']; |
||||
|
``` |
||||
|
|
||||
|
- [ ] **Step 5: Verify and commit** |
||||
|
|
||||
|
Run: |
||||
|
|
||||
|
```bash |
||||
|
./node_modules/.bin/nx test api --testFile=budgets.service.spec.ts --runInBand |
||||
|
./node_modules/.bin/nx test client --testFile=budget-page.component.spec.ts --runInBand |
||||
|
./node_modules/.bin/nx run client:build:development-en |
||||
|
git commit -m "feat: add budget transfer summary and statistics" |
||||
|
``` |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## Task 6: Final Verification |
||||
|
|
||||
|
- [ ] **Run focused tests** |
||||
|
|
||||
|
```bash |
||||
|
./node_modules/.bin/nx test api --testFile=budgets.service.spec.ts --runInBand |
||||
|
./node_modules/.bin/nx test ui --testFile=data.service.spec.ts --runInBand |
||||
|
./node_modules/.bin/nx test client --testFile=budget-page.component.spec.ts --runInBand |
||||
|
./node_modules/.bin/nx test client --testFile=create-or-update-budget-dialog.component.spec.ts --runInBand |
||||
|
``` |
||||
|
|
||||
|
- [ ] **Run builds** |
||||
|
|
||||
|
```bash |
||||
|
./node_modules/.bin/nx run api:build |
||||
|
./node_modules/.bin/nx run client:build:development-en |
||||
|
``` |
||||
|
|
||||
|
- [ ] **Manual browser check** |
||||
|
|
||||
|
Start the dev server and verify: |
||||
|
|
||||
|
- Budget page loads. |
||||
|
- Manage categories opens. |
||||
|
- A category can be created. |
||||
|
- A monthly budget line can be created using that category. |
||||
|
- A yearly expense appears as monthly equivalent. |
||||
|
- Transfer summary groups rows by account. |
||||
|
- Stats update when changing month. |
||||
Loading…
Reference in new issue