171 lines
5.2 KiB
Markdown
171 lines
5.2 KiB
Markdown
# Entries Pivot — Changelog & Implementation Notes
|
||
|
||
## Purpose
|
||
This document lists the required codebase changes to pivot from **spendings** to **entries** (including income), plus new features (buckets, recurring entries) and UI adjustments. It is the primary reference for implementation and debugging during the transition.
|
||
|
||
---
|
||
|
||
## Global Rename (Spendings → Entries)
|
||
### Terminology
|
||
- `spending` → `entry`
|
||
- `spendings` → `entries`
|
||
- UI labels should use “Entry” and “Entries” (or “Transaction(s)” if explicitly needed in copy).
|
||
- New entry type: **Spending** or **Income**.
|
||
|
||
### Codebase Areas to Rename
|
||
- **DB tables/columns**: `spendings`, `spending_tags` → `entries`, `entry_tags`
|
||
- **API routes**: `/api/spendings` → `/api/entries`
|
||
- **Server services**: `lib/server/spendings.ts` → `entries.ts`
|
||
- **Client wrappers**: `lib/client/spendings.ts` → `entries.ts`
|
||
- **Hooks**: `hooks/use-spendings.ts` → `use-entries.ts`
|
||
- **Components**: `spendings-panel`, `new-spending-modal`, `spending-details-modal`
|
||
- **Legacy shims**: remove spendings re-export stubs (components/hooks/lib and /api/spendings proxies)
|
||
- **Types**: `Spending` → `Entry`
|
||
- **Tests**: all spendings tests → entries tests
|
||
|
||
### Migration Record
|
||
- See [docs/SPENDINGS_TO_ENTRIES_SCHEMA_MIGRATION_RECORD.md](docs/SPENDINGS_TO_ENTRIES_SCHEMA_MIGRATION_RECORD.md).
|
||
|
||
---
|
||
|
||
## Entries Schema (Planned)
|
||
### New Fields
|
||
- `entry_type` enum (`SPENDING`, `INCOME`) or equivalent flag
|
||
- Recurring fields (see below)
|
||
|
||
### Existing Fields Kept
|
||
- `amount_dollars`, `occurred_at`, `notes`, `receipt_id`, `created_by`, `group_id`, etc.
|
||
|
||
---
|
||
|
||
## Recurring Entries (New Domain)
|
||
### Requirements
|
||
- Toggle recurring on entry creation
|
||
- Frequency: daily, weekly, biweekly, monthly, quarterly, yearly
|
||
- End conditions: never, after X occurrences, by date
|
||
- `next_run_at` set on creation (if start date is today, set to today)
|
||
- `last_executed_at` default `NULL`
|
||
- **Reminder:** execution will require cron/scheduler later (not implemented now)
|
||
|
||
### Data Model (Suggested)
|
||
- `is_recurring` boolean
|
||
- `frequency` enum
|
||
- `interval_count` integer
|
||
- `end_condition` enum
|
||
- `end_count` integer nullable
|
||
- `end_date` date nullable
|
||
- `next_run_at` date nullable
|
||
- `last_executed_at` date nullable
|
||
|
||
---
|
||
|
||
## Buckets (New Domain)
|
||
### Requirements
|
||
- Buckets are like tags with a **budget limit**
|
||
- Each bucket:
|
||
- name, description, icon (from predefined set)
|
||
- editable and deletable via modal
|
||
- has a budget limit
|
||
- shows total spending based on associated tags
|
||
- **Totals logic:**
|
||
- For each tag in the bucket, collect all entries with that tag
|
||
- Remove duplicates (unique entry IDs), then sum amounts
|
||
- Overlapping tags between buckets are allowed
|
||
|
||
### UI Requirements
|
||
- New dashboard view for buckets
|
||
- Visual indicators near/over budget
|
||
- Hamburger menu: edit, delete, view details, auto‑fill spendings search
|
||
- Drag handle icon for reordering
|
||
|
||
---
|
||
|
||
## Modal Close Buttons
|
||
- Replace all modal close buttons with **“x”** in top‑right corner
|
||
- Use **New Spending Modal** (soon **New Entry Modal**) as the reference
|
||
|
||
---
|
||
|
||
## Spendings Dashboard → Entries Dashboard
|
||
### Filtering
|
||
Add filtering modal with:
|
||
- Amount range
|
||
- Date range
|
||
- Necessity
|
||
- Tags
|
||
- Text in notes
|
||
- Tags filter mode: **match all** vs **match any**
|
||
|
||
### Naming Pivot
|
||
- Rename dashboard, labels, filters, and API payloads to “entries”
|
||
|
||
---
|
||
|
||
## New Entry Modal (formerly New Spending Modal)
|
||
### Tagging & Navigation
|
||
- Fix tags not being added
|
||
- Allow dropdown navigation via typing
|
||
- Maintain highlighted index across list shrink/grow
|
||
|
||
### Validation UX
|
||
- Keep amount or tags borders red until filled
|
||
- If submit with missing fields:
|
||
- Show “Please fill out this field” on both
|
||
- Focus amount first, tags second
|
||
|
||
### Date Navigation
|
||
- Add 4 buttons around date input:
|
||
- `<<` (back 1 week), `<` (back 1 day), `>` (forward 1 day), `>>` (forward 1 week)
|
||
- Format: `[ << ][ < ][ today’s date ][ > ][ >> ]`
|
||
|
||
### Recurring Toggle
|
||
- Toggle button near header: refresh icon tooltip “Toggle Recurring Entry”
|
||
- Header changes: “New One‑Time Expense” → “New Recurring Expense”
|
||
- Show/hide frequency and end condition inputs
|
||
|
||
### Income vs Spending Toggle
|
||
- Toggle under header to switch entry type
|
||
- Default to spending
|
||
- Update header: “New [One‑Time/Recurring] Income entry”
|
||
- Add icon left of amount input:
|
||
- Income: stocks going up
|
||
- Spending: money going down
|
||
|
||
---
|
||
|
||
## API / Server / Client / Hooks
|
||
### API
|
||
- New `/api/entries` endpoints (CRUD)
|
||
- New `/api/buckets` endpoints (CRUD)
|
||
- New `/api/recurring-entries` endpoints (CRUD)
|
||
|
||
### Server
|
||
- `lib/server/entries.ts`, `buckets.ts`, `recurring-entries.ts`
|
||
- Enforce auth + group membership
|
||
|
||
### Client / Hooks
|
||
- `lib/client/entries.ts`, `use-entries.ts`
|
||
- `lib/client/buckets.ts`, `use-buckets.ts`
|
||
- `lib/client/recurring-entries.ts`, `use-recurring-entries.ts`
|
||
|
||
---
|
||
|
||
## Tests
|
||
- Rename spendings tests to entries
|
||
- Add tests for:
|
||
- income entries
|
||
- recurring entries (validation only; no cron execution)
|
||
- buckets CRUD
|
||
- buckets totals with overlapping tags
|
||
- filtering modal behavior
|
||
|
||
---
|
||
|
||
## Non‑Regression Rules
|
||
- Entries list endpoints must **never** return receipt image bytes
|
||
- Auth checks remain server‑side only
|
||
|
||
---
|
||
|
||
_Last updated: 2026-02-09_
|