From 6b66ec6ca72e2722e46864ef0cf67913a44f9d76 Mon Sep 17 00:00:00 2001 From: Jean-Luc Makiola Date: Thu, 12 Mar 2026 11:54:44 +0100 Subject: [PATCH] docs(05): capture phase context --- .../05-CONTEXT.md | 115 ++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 .planning/phases/05-template-data-model-and-api/05-CONTEXT.md diff --git a/.planning/phases/05-template-data-model-and-api/05-CONTEXT.md b/.planning/phases/05-template-data-model-and-api/05-CONTEXT.md new file mode 100644 index 0000000..0ad2516 --- /dev/null +++ b/.planning/phases/05-template-data-model-and-api/05-CONTEXT.md @@ -0,0 +1,115 @@ +# Phase 5: Template Data Model and API - Context + +**Gathered:** 2026-03-12 +**Status:** Ready for planning + + +## Phase Boundary + +Backend infrastructure for the template system — new DB tables (templates, template_items), migration to add item_tier to budget_items, and REST endpoints for template CRUD and budget-from-template generation. No frontend changes in this phase. One-off items are excluded from templates at the data layer. + + + + +## Implementation Decisions + +### Item type storage +- New PostgreSQL ENUM `item_tier` with values: `fixed`, `variable`, `one_off` +- Added as column on `budget_items` table via migration 002 +- Existing budget items default to `'fixed'` (they were created via copy-from-previous, treating all as recurring) +- Column named `item_tier` (not `item_type`) to avoid collision with existing `category_type` field on BudgetItem +- Settable via existing `POST /api/budgets/{id}/items` and `PUT /api/budgets/{id}/items/{itemId}` endpoints — optional field, defaults to `'one_off'` for new items + +### Template ownership +- One template per user — `templates` table with UNIQUE constraint on `user_id` +- Lazy creation: template auto-created when user first adds a template item (POST /api/template/items) +- GET /api/template returns `{ "id": null, "items": [] }` when no template exists +- Template auto-named "My Template" on creation; user can rename via PUT /api/template + +### Template item data model +- `template_items` table: id, template_id (FK), category_id (FK), item_tier, budgeted_amount (NULLABLE), sort_order, created_at, updated_at +- Fixed items: category + budgeted_amount set +- Variable items: category + budgeted_amount NULL +- CHECK constraint on template_items: `item_tier IN ('fixed', 'variable')` — one_off cannot exist in templates (DB-level enforcement) + +### Generation endpoint +- `POST /api/budgets/generate` with body `{ "month": "2026-04", "currency": "EUR" }` +- Single atomic transaction: creates budget + all template-derived items together +- Fixed items generated with their template amounts; variable items generated with budgeted_amount = 0 +- Returns 201 Created with full BudgetDetail response (same shape as GET /api/budgets/{id}) +- Returns 409 Conflict with `{ "error": "budget already exists", "budget_id": "..." }` if budget for that month exists +- If user has no template: creates empty budget with zero items (no error) +- Budget auto-named from month using user's preferred_locale (localized month name + year, e.g. "April 2026") +- Start/end dates computed from month parameter (first and last day of month) + +### API routes +- Singular `/api/template` (one template per user, no ID needed): + - `GET /api/template` — get template with items (joined category name, type, icon) + - `PUT /api/template` — update template name + - `POST /api/template/items` — add item (auto-creates template if needed) + - `PUT /api/template/items/{itemId}` — update item + - `DELETE /api/template/items/{itemId}` — remove item + - `PUT /api/template/items/reorder` — batch update sort_order +- Generation: `POST /api/budgets/generate` (under budgets, since the output is a budget) + +### API response shape +- `item_tier` always included in budget item JSON responses (additive, non-breaking) +- Template GET response includes joined category details: category_name, category_type, category_icon +- Generation endpoint returns standard BudgetDetail shape + +### Claude's Discretion +- Go struct design for Template and TemplateItem models +- Exact migration SQL structure and index choices +- Handler implementation patterns (error messages, validation order) +- Query function signatures and SQL query structure +- Month name localization approach (map vs library) + + + + +## Specific Ideas + +- Migration defaults existing items to 'fixed' since the old copy-from-previous treated everything as recurring +- Lazy template creation removes friction — user doesn't need to "set up" a template before using the app +- 409 Conflict on duplicate month matches existing error patterns (409 for unique constraint violations) +- Template response joins category details so Phase 6 frontend doesn't need extra API calls + + + + +## Existing Code Insights + +### Reusable Assets +- `models.go`: BudgetItem struct — add ItemTier field, BudgetDetail response shape reused by generation endpoint +- `queries.go`: 22 existing query functions — CopyBudgetItems as reference for template-to-budget generation pattern +- `handlers.go`: Handlers struct with queries dependency injection — add template handlers following same pattern +- `router.go`: Chi router with auth middleware group — add `/api/template` route group and `/api/budgets/generate` endpoint + +### Established Patterns +- PostgreSQL ENUM types (category_type) — same pattern for item_tier +- User-scoped data isolation: all queries filter by userID from auth context +- JSON serialization with `json:"field_name"` tags on structs +- Error responses: `writeError(w, status, message)` helper +- UUID primary keys with `uuid_generate_v4()` default +- Decimal amounts via `shopspring/decimal` and `NUMERIC(12,2)` in PostgreSQL + +### Integration Points +- `001_initial.sql` existing schema — new migration 002 adds item_tier column and template tables +- `handlers.go` CreateBudgetItem/UpdateBudgetItem — add item_tier to request parsing and query calls +- `queries.go` GetBudgetWithItems — add item_tier to SELECT and Scan +- `router.go` protected routes group — add template routes and generate endpoint +- `models.go` — add ItemTier type, Template struct, TemplateItem struct + + + + +## Deferred Ideas + +None — discussion stayed within phase scope + + + +--- + +*Phase: 05-template-data-model-and-api* +*Context gathered: 2026-03-12*