arthur/xtablo-source
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions 5

docs(10): capture phase context

Browse source
This commit is contained in:
Arthur Belleville 2026-05-16 00:04:26 +02:00
parent ec6bb7d11c
commit c896b26f47
No known key found for this signature in database
2 changed files with 227 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

144
.planning/phases/10-events/10-CONTEXT.md Normal file
View file

@ -0,0 +1,144 @@
# Phase 10: Events - Context
**Gathered:** 2026-05-16
**Status:** Ready for planning
<domain>
## Phase Boundary
Phase 10 delivers scheduled events attached to tablos. Users can create, edit, delete, and browse events inside a tablo with the same authorization expectations as tasks, files, and etapes. The first UI is a functional Events tab with a simple month calendar, not a polished calendar product. Phase 10 should also expose enough query surface for Phase 11 to build an individual planning page without reworking the event model.
</domain>
<decisions>
## Implementation Decisions
### Time Model
- **D-01:** Use local date/time semantics in the first version; do not add timezone selection or timezone conversion UI.
- **D-02:** Event start date and start time are required.
- **D-03:** End time is optional and same-day only.
- **D-04:** If an event has no end time, display only the start time. Do not infer or store a default duration.
- **D-05:** Store event time as separate `event_date`, `start_time`, and nullable `end_time` columns. Do not use `timestamptz` for Phase 10 event scheduling.
### Events Tab Shape
- **D-06:** Add an `Events` tab to the existing tablo detail tabs beside Overview, Tasks, and Files.
- **D-07:** The first Events tab view is a simple month grid.
- **D-08:** Include previous/next month navigation.
- **D-09:** Users can create events from both a general `New event` button and by clicking a day cell with that date prefilled.
- **D-10:** Day cells show event titles only, not start times.
- **D-11:** When a day has more events than fit cleanly, show the first few titles plus a `+N more` indicator.
### Create/Edit Flow
- **D-12:** Render create/edit forms inline inside the Events tab using HTMX fragments.
- **D-13:** The form fields are: required title, date, start time; optional end time, description, and location.
- **D-14:** Clicking an event title in the calendar opens the inline edit form.
- **D-15:** Create, edit, and delete operations refresh the whole Events tab/calendar rather than only one day cell.
### Event Lifecycle
- **D-16:** Delete is hard delete after confirmation. Do not add `deleted_at`, archive, cancel, or restore semantics in Phase 10.
- **D-17:** Past events remain visible when browsing past months.
- **D-18:** Events within a day are ordered by start time ascending, then title.
- **D-19:** Do not add a special empty state beyond the calendar and the `New event` action.
### Phase 11 Handoff
- **D-20:** Phase 10 should include a user-scoped query surface for events across tablos the authenticated user can access, even if Phase 10 only renders tablo-local events.
- **D-21:** Planning links should target the tablo Events tab with month query params, e.g. `/tablos/{id}/events?month=YYYY-MM`.
- **D-22:** User-scoped event rows should include event fields plus tablo title and tablo color.
- **D-23:** User-scoped query surface should support date-range filtering so Phase 11 can implement planning navigation cleanly.
### the agent's Discretion
- Exact route names, query names, and HTMX fragment boundaries are planner discretion if they preserve the decisions above and match existing local patterns.
- Exact calendar CSS and mobile layout are planner discretion; the result should remain functional and restrained until the user supplies a richer UI later.
- Exact validation copy is planner discretion, but it must clearly explain that an end time must be after the start time when provided.
</decisions>
<canonical_refs>
## Canonical References
**Downstream agents MUST read these before planning or implementing.**
### Product Scope
- `.planning/ROADMAP.md` - Phase 10 goal, MVP mode, success criteria, and user-in-loop checkpoint.
- `.planning/REQUIREMENTS.md` - EVENT-01 through EVENT-05 and Phase 11 PLAN requirements that depend on event aggregation.
- `.planning/PROJECT.md` - v2 constraints: Go + HTMX, Postgres, plain functional UI, events belong to tablos, planning is individual.
### Prior Phase Patterns
- `.planning/phases/09-etapes/09-CONTEXT.md` - Recent tablo-scoped child-resource decisions, Tasks tab integration, and HTMX fragment patterns.
- `.planning/phases/09-etapes/09-04-SUMMARY.md` - Most recent UAT lessons around HTMX tab refreshes and filter/form precedence.
### Go Backend Entry Points
- `backend/migrations/0003_tablos.sql` - Current `tablos` ownership model and FK target.
- `backend/migrations/0007_etapes.sql` - Recent example of adding a tablo-owned child table and indices.
- `backend/internal/db/queries/tablos.sql` - Existing owner-scoped tablo query shape.
- `backend/internal/db/queries/tasks.sql` - Existing tablo-scoped list/create/update/delete query style.
- `backend/templates/tablos.templ` - Current tab navigation and tab fragment integration point for adding Events.
- `backend/internal/web/router.go` - Protected route mounting order and static-before-parametric route pattern.
- `backend/internal/web/handlers_tablos.go` - Tablo detail/tab handlers and `loadOwnedTablo` authorization pattern.
- `backend/internal/web/handlers_tasks.go` - Task child-resource create/update/delete patterns to mirror for events.
- `backend/internal/web/handlers_etapes.go` - Recent full-tab refresh pattern for child-resource mutations.
- `backend/internal/web/handlers_tasks_test.go` - DB-backed authorization and HTMX regression testing style.
### Historical TypeScript Reference
- `packages/tablo-views/src/TabloEventsSection.tsx` - Old product reference for event display, upcoming filtering, and empty-state wording; use as reference only, not a visual contract.
- `packages/shared-types/src/events.types.ts` - Old event domain type names and event-with-tablo shape.
- `packages/shared-types/src/database.types.ts` - Old schema had `start_date`, `start_time`, `end_time`, `created_by`, and `deleted_at`; Phase 10 intentionally keeps date/time split but chooses hard delete and no `deleted_at`.
- `apps/main/src/hooks/events.ts` - Old event query/mutation surface and aggregation ideas; use as behavior reference only.
- `apps/main/src/pages/planning.tsx` - Old planning page reference for why Phase 10 should expose user-scoped date-range queries.
</canonical_refs>
<code_context>
## Existing Code Insights
### Reusable Assets
- `TabloDetailPage` already renders tab navigation with HTMX links targeting `#tab-content`; Events should follow the same tab pattern.
- `TasksTabFragment` and `FilesTabFragment` show the current pattern for standalone tab fragments returned by HTMX tab routes.
- `loadOwnedTablo` and existing child-resource handlers enforce ownership through the parent tablo and return 404 for inaccessible resources.
- `ui.Button`, `ui.Card`, and existing form field/error patterns are enough for the first functional Events UI.
### Established Patterns
- Tablo-owned resources mount under `/tablos/{id}/...` protected by `auth.RequireAuth`.
- Static child routes are declared before parametric child routes in `router.go`.
- SQLC query files are canonical; generated Go files are reproduced by `just generate` and not hand-edited.
- Mutations that affect a whole tab can return the full tab fragment for reliability.
- DB-backed tests use `setupTestDB`, `newTaskTestRouter`/similar router helpers, session cookies, and CSRF tokens.
- Unauthorized access to resources owned by another user's tablo should return 404 rather than 403.
### Integration Points
- Add a migration after `0007_etapes.sql` for a tablo-owned `events` table.
- Add `backend/internal/db/queries/events.sql` with tablo-scoped CRUD, month/date-range list queries, and user-scoped aggregation query including tablo title/color.
- Add event dependencies to `web.NewRouter` similarly to `TasksDeps`, `EtapesDeps`, and `FilesDeps`.
- Extend `TabloDetailPage` with an Events tab and render Events tab content when active.
- Add event handlers and templates under the existing `backend/internal/web` and `backend/templates` patterns.
- Add tests proving owner-only read/create/update/delete and end-time validation.
</code_context>
<specifics>
## Specific Ideas
- The Events tab should be a simple month calendar grid, not an agenda list.
- Day-cell clicks should prefill the create form date.
- Event titles are enough inside calendar cells for Phase 10.
- Planning deep links should preserve month context with `?month=YYYY-MM`.
</specifics>
<deferred>
## Deferred Ideas
- Timezone selection or conversion.
- Multi-day events.
- Date-only/all-day events.
- Event colors, categories, archive/cancel states, or soft-delete restore flows.
- Week/day calendar views.
- Rich day-detail panels.
- Full individual planning UI; Phase 11 owns that screen.
</deferred>
---
*Phase: 10-Events*
*Context gathered: 2026-05-16*

83
.planning/phases/10-events/10-DISCUSSION-LOG.md Normal file
View file

@ -0,0 +1,83 @@
# Phase 10: Events - Discussion Log
> **Audit trail only.** Do not use as input to planning, research, or execution agents.
> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
**Date:** 2026-05-16
**Phase:** 10-Events
**Areas discussed:** Time Model, Events Tab Shape, Create/Edit Flow, Event Lifecycle, Phase 11 Handoff
---
## Time Model
| Option | Description | Selected |
|--------|-------------|----------|
| Local date/time, no timezone field | User enters date + time and Xtablo displays the same date + time everywhere. | ✓ |
| UTC timestamps with timezone conversion | Store exact instants and convert for display. | |
| Date-only allowed | Support all-day/date-only or timed events. | |
**User's choice:** Local date/time, no timezone field.
**Notes:** Start date/time required. End time is optional, same-day only, and must be after start when provided. If no end time exists, display only the start time. Store separate `event_date`, `start_time`, and nullable `end_time` columns.
---
## Events Tab Shape
| Option | Description | Selected |
|--------|-------------|----------|
| Agenda/list-first tab | Chronological list inside a new Events tab. | |
| Compact upcoming section on Overview | Small upcoming-events block on overview. | |
| Calendar grid | Month/week style calendar surface. | ✓ |
**User's choice:** Calendar grid.
**Notes:** Scope is a simple month grid only. Include previous/next month navigation. Users can create events from both a `New event` button and day-cell clicks with the clicked date prefilled. Day cells show event titles only. Crowded days show first few titles plus `+N more`.
---
## Create/Edit Flow
| Option | Description | Selected |
|--------|-------------|----------|
| Inline panel inside the Events tab | HTMX swaps a form inside the Events tab. | ✓ |
| Separate event form page | Full-page form and validation flow. | |
| Modal-like dialog fragment | Dialog-style fragment with more custom interaction state. | |
**User's choice:** Inline panel inside the Events tab.
**Notes:** Form fields are required title/date/start time plus optional end time/description/location. Clicking an event title opens inline edit. Create, edit, and delete refresh the whole Events tab/calendar.
---
## Event Lifecycle
| Option | Description | Selected |
|--------|-------------|----------|
| Hard delete | Remove the row after confirmation. | ✓ |
| Soft delete with `deleted_at` | Preserve rows and filter deleted events. | |
| Archive/cancel state | Add a richer lifecycle state. | |
**User's choice:** Hard delete.
**Notes:** Past events remain visible when browsing past months. Events inside a day are ordered by start time, then title. No special empty state is needed beyond the calendar and the `New event` action.
---
## Phase 11 Handoff
| Option | Description | Selected |
|--------|-------------|----------|
| User-scoped query surface | Query events across accessible tablos for the authenticated user. | ✓ |
| Tablo-only query surface | Keep Phase 10 strictly tablo-local. | |
| Full planning route now | Start the Phase 11 screen during Phase 10. | |
**User's choice:** User-scoped query surface.
**Notes:** Planning links should target `/tablos/{id}/events?month=YYYY-MM`. User-scoped results should include event fields plus tablo title/color, and support date-range filtering.
---
## the agent's Discretion
- Exact route names, query names, fragment boundaries, calendar CSS, mobile layout, and validation copy are left to planner/executor discretion within the captured decisions.
## Deferred Ideas
- Timezone selection/conversion, multi-day events, all-day/date-only events, event categories/colors, soft delete/archive/cancel lifecycle, week/day views, richer day details, and the full individual planning page.