# Phase 09 - Pattern Map

## Purpose

Concrete code patterns Phase 9 should reuse when adding etapes to the Go/HTMX task board.

## Closest Analogs

### Schema And SQLC

- `backend/migrations/0004_tasks.sql` - task enum/table/index pattern; down migration order matters.
- `backend/migrations/0005_files.sql` - tablo-owned child table pattern for resources under a tablo.
- `backend/internal/db/queries/tasks.sql` - current task CRUD query shape and `GetTaskByID` ownership binding.
- `backend/internal/db/queries/files.sql` - tablo-scoped file query analog if present during execution.

### Handlers

- `backend/internal/web/handlers_tasks.go` - task CRUD, inline HTMX fragments, status parsing, reorder behavior.
- `backend/internal/web/handlers_files.go` - additional tablo-scoped resource handlers and ownership helpers.
- `backend/internal/web/handlers_tablos.go` - canonical `loadOwnedTablo` helper and 404-on-authz-failure pattern.

### Templates

- `backend/templates/tasks.templ` - kanban board, task card, create/edit/delete fragments, OOB add-slot reset.
- `backend/templates/tablos.templ` - tab content boundary and `TasksTabFragment` integration point.
- `backend/internal/web/ui/button.css` and `backend/internal/web/ui` helpers - existing button/card/badge styling.

### Tests

- `backend/internal/web/handlers_tasks_test.go` - DB-backed handler tests for task create/update/reorder/delete/ownership.
- `backend/internal/web/handlers_files_test.go` - useful analog for tablo-scoped resource ownership tests if present during execution.

## Reuse Rules

- Keep `TaskColumns` and the current kanban column DOM stable.
- New etape routes should live under `/tablos/{id}/...` and call `loadOwnedTablo` before any etape lookup.
- Etape-specific lookup must bind both `id` and `tablo_id`, mirroring `GetTaskByID`.
- HTMX filter operations should swap `#tasks-tab` or `#tab-content`, not just `#kanban-board`, so chip active state and counts stay accurate.
- Task reorder must preserve `etape_id` once the task row grows that field.
- Use `just generate` after migration, sqlc query, or templ changes.

## Planned File Map

| Target file | Role | Closest analog |
|-------------|------|----------------|
| `backend/migrations/0007_etapes.sql` | Add etape table and nullable task assignment | `backend/migrations/0004_tasks.sql`, `backend/migrations/0005_files.sql` |
| `backend/internal/db/queries/etapes.sql` | Etape CRUD and position queries | `backend/internal/db/queries/tasks.sql` |
| `backend/internal/db/queries/tasks.sql` | Add nullable etape assignment and filtered task lists | existing same file |
| `backend/internal/web/handlers_etapes.go` | Etape CRUD/reorder handlers | `backend/internal/web/handlers_tasks.go`, `backend/internal/web/handlers_files.go` |
| `backend/internal/web/handlers_tasks.go` | Task assignment and filter-aware task loading | existing same file |
| `backend/internal/web/router.go` | Mount etape routes and preserve task routes | existing task/file route groups |
| `backend/templates/etapes.templ` | Etape strip, chips, forms, delete confirmation | `backend/templates/tasks.templ` |
| `backend/templates/tasks.templ` | Add etape selector and preserve kanban | existing same file |
| `backend/templates/tablos.templ` | Expand `TasksTabFragment` signature and wrapper | existing same file |
| `backend/internal/web/handlers_etapes_test.go` | Etape behavior and ownership coverage | `backend/internal/web/handlers_tasks_test.go` |
| `backend/internal/web/handlers_tasks_test.go` | Assignment/filter/reorder regression coverage | existing same file |
