nalalangan/fiddy
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
828bb301d6
fiddy/docs/ENTRIES_PIVOT_CHANGELOG_AND_IMPLEMENTATION_NOTES.md
Nico 4873449e16 initial commit
2026-02-11 23:45:15 -08:00

5.2 KiB
Raw Blame History

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

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