From c8fc17c43c068bf8fa36a09f169d15295fb65d42 Mon Sep 17 00:00:00 2001 From: Jean-Luc Makiola Date: Thu, 12 Mar 2026 12:11:38 +0100 Subject: [PATCH] docs(05-02): complete template API handlers plan --- .planning/ROADMAP.md | 4 +- .planning/STATE.md | 15 ++- .../05-02-SUMMARY.md | 110 ++++++++++++++++++ 3 files changed, 121 insertions(+), 8 deletions(-) create mode 100644 .planning/phases/05-template-data-model-and-api/05-02-SUMMARY.md diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 6e404c8..84f8dc4 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -91,7 +91,7 @@ Plans: 2. A user's template can be created and fetched via the API — it contains fixed items (with amounts) and variable items (category only, no amount) 3. One-off items are excluded from template contents — the API never includes them in template responses 4. The template API endpoints are documented and return correct data for all three item tiers -**Plans:** 1/2 plans executed +**Plans:** 2/2 plans complete Plans: - [ ] 05-01-PLAN.md — DB migration (item_tier enum, templates/template_items tables) + Go models + query functions @@ -153,7 +153,7 @@ Phases execute in numeric order: 1 -> 2 -> 3 -> 4 -> 5 -> 6 -> 7 -> 8 | 2. Layout and Brand Identity | v1.0 | 2/2 | Complete | 2026-03-12 | | 3. Interaction Quality and Completeness | v1.0 | 4/4 | Complete | 2026-03-12 | | 4. Chart Polish and Bug Fixes | v1.0 | 2/2 | Complete | 2026-03-12 | -| 5. Template Data Model and API | 1/2 | In Progress| | - | +| 5. Template Data Model and API | 2/2 | Complete | 2026-03-12 | - | | 6. Template Frontend and Workflow Replacement | v1.1 | 0/3 | Not started | - | | 7. Quick-Add Library | v1.1 | 0/2 | Not started | - | | 8. Layout and Density Rethink | v1.1 | 0/2 | Not started | - | diff --git a/.planning/STATE.md b/.planning/STATE.md index 3846886..12c22cd 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -3,14 +3,14 @@ gsd_state_version: 1.0 milestone: v1.1 milestone_name: Usability and Templates status: planning -stopped_at: Completed 05-template-data-model-and-api-01-PLAN.md -last_updated: "2026-03-12T11:07:58.758Z" +stopped_at: Completed 05-template-data-model-and-api-02-PLAN.md +last_updated: "2026-03-12T11:11:30.005Z" last_activity: 2026-03-12 — v1.1 roadmap created, Phases 5-8 defined progress: total_phases: 8 - completed_phases: 4 + completed_phases: 5 total_plans: 12 - completed_plans: 11 + completed_plans: 12 percent: 0 --- @@ -51,6 +51,7 @@ Progress: [░░░░░░░░░░] 0% *Updated after each plan completion* | Phase 05-template-data-model-and-api P01 | 3 | 2 tasks | 4 files | +| Phase 05-template-data-model-and-api P02 | 1min | 2 tasks | 2 files | ## Accumulated Context @@ -67,6 +68,8 @@ Recent decisions affecting current work: - [Phase 05-template-data-model-and-api]: New API-created budget items default to item_tier=one_off at the query layer - [Phase 05-template-data-model-and-api]: Template creation is lazy: CreateTemplateItem upserts template via ON CONFLICT - [Phase 05-template-data-model-and-api]: GenerateBudgetFromTemplate returns BudgetExistsError struct for structured 409 response +- [Phase 05-template-data-model-and-api]: PUT /items/reorder registered before PUT /items/{itemId} for correct chi static-before-param routing +- [Phase 05-template-data-model-and-api]: GenerateBudget returns 409 JSON with budget_id field using BudgetExistsError.ExistingBudgetID ### Pending Todos @@ -79,6 +82,6 @@ None yet. ## Session Continuity -Last session: 2026-03-12T11:07:58.757Z -Stopped at: Completed 05-template-data-model-and-api-01-PLAN.md +Last session: 2026-03-12T11:11:30.004Z +Stopped at: Completed 05-template-data-model-and-api-02-PLAN.md Resume file: None diff --git a/.planning/phases/05-template-data-model-and-api/05-02-SUMMARY.md b/.planning/phases/05-template-data-model-and-api/05-02-SUMMARY.md new file mode 100644 index 0000000..9fffb09 --- /dev/null +++ b/.planning/phases/05-template-data-model-and-api/05-02-SUMMARY.md @@ -0,0 +1,110 @@ +--- +phase: 05-template-data-model-and-api +plan: 02 +subsystem: api +tags: [go, rest-api, templates, budget-generation, http-handlers] + +requires: + - phase: 05-template-data-model-and-api + plan: 01 + provides: GetTemplate, CreateTemplateItem, UpdateTemplateItem, DeleteTemplateItem, ReorderTemplateItems, GenerateBudgetFromTemplate, BudgetExistsError + +provides: + - GET /api/template returns TemplateDetail (empty items when no template) + - PUT /api/template updates template name + - POST /api/template/items adds template item with validation (no one_off, fixed requires budgeted_amount) + - PUT /api/template/items/{itemId} updates template item + - DELETE /api/template/items/{itemId} removes template item (204) + - PUT /api/template/items/reorder batch-updates sort order (204) + - POST /api/budgets/generate creates budget from template or returns 409 with budget_id + - CreateBudgetItem/UpdateBudgetItem handlers already accept item_tier (done in Plan 01 auto-fix) + +affects: + - 06 (frontend template UI will call these endpoints) + +tech-stack: + added: [] + patterns: + - errors.As for typed BudgetExistsError detection in GenerateBudget handler + - Static route /items/reorder registered before parameterized /items/{itemId} for correct chi routing + - Handler-level validation mirrors DB CHECK constraint as defense in depth + +key-files: + created: [] + modified: + - backend/internal/api/handlers.go + - backend/internal/api/router.go + +key-decisions: + - "PUT /items/reorder registered before PUT /items/{itemId} to prevent chi treating 'reorder' as an itemId" + - "GenerateBudget returns 409 JSON with both error message and budget_id field using BudgetExistsError.ExistingBudgetID" + - "Handler validates month format via time.Parse before calling query layer (redundant but explicit)" + +duration: 1min +completed: 2026-03-12 +--- + +# Phase 5 Plan 2: Template API Handlers Summary + +**HTTP handlers and routes for template CRUD, item reorder, and budget-from-template generation wired to the query layer built in Plan 01** + +## Performance + +- **Duration:** ~1 min +- **Started:** 2026-03-12T11:09:32Z +- **Completed:** 2026-03-12T11:10:40Z +- **Tasks:** 2 +- **Files modified:** 2 + +## Accomplishments + +- All 7 template handler methods added to handlers.go: GetTemplate, UpdateTemplateName, CreateTemplateItem, UpdateTemplateItem, DeleteTemplateItem, ReorderTemplateItems, GenerateBudget +- Handler-level validation for template items: one_off tier rejected with 400, fixed tier requires budgeted_amount +- GenerateBudget uses errors.As to detect BudgetExistsError and returns structured 409 with budget_id +- /api/template route group fully wired in router.go with correct static-before-param ordering for /items/reorder vs /items/{itemId} +- POST /api/budgets/generate placed before /{id} routes to avoid "generate" being parsed as a budget ID +- Full backend builds and vets clean + +## Task Commits + +Each task committed atomically: + +1. **Task 1: Template handlers and budget generation handler** - `ceca2fc` (feat) +2. **Task 2: Wire routes in router.go** - `387507b` (feat) + +## Files Created/Modified + +- `backend/internal/api/handlers.go` - Added 7 new handler methods, added `errors` import +- `backend/internal/api/router.go` - Added /api/template route group and POST /api/budgets/generate + +## Decisions Made + +- `PUT /items/reorder` registered before `PUT /items/{itemId}` — chi matches static routes first when registered in order; this prevents "reorder" being treated as an itemId parameter +- `GenerateBudget` returns JSON body `{"error": "budget already exists", "budget_id": "..."}` on 409 — uses `BudgetExistsError.ExistingBudgetID` (field name established in Plan 01) +- `UpdateTemplateName` handler returns 404 for any error — since lazy creation means the only failure mode before an item exists is "no template", and connection errors are rare; consistent with UpdateCategory pattern + +## Deviations from Plan + +None - plan executed exactly as written. The budget item handler updates (item_tier pass-through) were already done in Plan 01's auto-fix, so Task 1 focused entirely on new template handlers. + +## Issues Encountered + +None. + +## User Setup Required + +None - no external service configuration required. Routes are live after next server start. + +## Next Phase Readiness + +- All REST endpoints for Phase 6 (template UI) are available +- API contract is stable: GET returns empty items array (not error) when no template exists +- 409 conflict response includes budget_id so frontend can navigate to existing budget + +## Self-Check: PASSED + +Both modified files verified on disk. Both task commits (ceca2fc, 387507b) present in git log. `go build ./...` and `go vet ./...` pass clean. + +--- +*Phase: 05-template-data-model-and-api* +*Completed: 2026-03-12*