111 lines
4.7 KiB
Markdown
111 lines
4.7 KiB
Markdown
---
|
|
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*
|