Files
kandev/docs/plans/sidebar-default-view-persistence/plan.md
T
2026-08-24 11:09:03 +00:00

161 lines
8.1 KiB
Markdown

---
spec: docs/specs/ui/requirements/sidebar-view-creation.md
created: 2026-08-05
status: complete
---
# Implementation Plan: Persist the Default Sidebar View
## Overview
Repair the clean-settings contract at its backend source of truth. The backend
will provide the canonical `All tasks` view and matching active ID whenever
stored user settings omit sidebar-view fields, while preserving explicit stored
values and the existing active-view validation. A focused HTTP integration test
and the existing sidebar browser suite will prove that the first filter edit no
longer returns HTTP 400.
## Confirmed root cause
`internal/user/store.defaultUserSettings` currently supplies an empty
`SidebarViews` slice and no active ID, while the frontend independently starts
with `view-all-tasks`. The first draft-only PATCH sends
`sidebar_active_view_id="view-all-tasks"` without `sidebar_views`, so
`applySidebarViewState` validates the ID against the backend's empty list and
rejects the request. Commit `b9eb6ae05` removed the legacy client migration
that previously populated the backend, exposing this mismatch on clean data.
This repair follows
[ADR 0041](../../decisions/0041-backend-owned-portable-user-settings.md): the
backend owns the effective value of omitted portable settings. It does not
reintroduce browser migration or relax referential validation.
---
## Backend
### Canonical sidebar defaults
- In `apps/backend/internal/user/store/sqlite.go`, add a fresh-value helper for
the canonical sidebar view: ID `view-all-tasks`, name `All tasks`, empty
filters, `state`/`asc` sort, `repository` grouping, and empty collapsed
groups.
- Use fresh slices on each call so one request cannot mutate another user's
defaults through shared backing arrays.
- Set both `SidebarViews` and `SidebarActiveViewID` in
`defaultUserSettings`.
- Change the temporary JSON scan fields for `sidebar_views` and
`sidebar_active_view_id` to preserve field presence. Overlay them only when
they are present, so settings JSON such as `{}` or
`{"workspace_id":"..."}` retains the backend default while explicit stored
values remain authoritative.
- When a write explicitly replaces `sidebar_views` without an active-view
field, preserve the referential invariant: an empty replacement resolves to
the canonical default instead of persisting an active ID that has no view.
- Keep `applySidebarViewState` unchanged: non-default or stale active IDs must
still be rejected unless they exist in the effective saved-view list.
### HTTP integration path
- Add `apps/backend/internal/user/handlers/handlers_test.go` using an in-memory
SQLite repository, the real service/controller, and a Gin test router.
- Start from the repository-created default user whose settings JSON is `{}`.
- Assert `GET /api/v1/user/settings` returns the canonical view and matching
active ID.
- PATCH only `sidebar_active_view_id` plus `sidebar_draft`, matching the current
frontend edit request, and assert HTTP 200 plus durable read-back. This test
must return HTTP 400 before the production change for the diagnosed reason.
---
## Frontend
No production frontend change is planned. The existing client PATCH shape and
optimistic behavior remain the consumer contract being verified.
### E2E fixture and scenario
- In `apps/web/e2e/fixtures/test-base.ts`, reset sidebar settings to the same
canonical view and active ID rather than an impossible empty-view UI state.
Reuse one fixture constant for both reset paths.
- In `apps/web/e2e/tests/task/sidebar-filter.spec.ts`, extend the new-user
default-view scenario to edit the canonical view before any create/save-as
action. Assert the draft reaches user settings, no `Sidebar views` error toast
appears, and the view remains active after reload.
- Desktop and mobile use the same store action and backend route; this repair
changes no layout, interaction target, or responsive composition. Existing
mobile sidebar-view coverage remains applicable.
---
## Tests
- **What:** omitted sidebar fields resolve to a fresh canonical view and
matching active ID, including when unrelated settings are present.
**File:** `apps/backend/internal/user/store/sqlite_test.go`.
**How:** table-driven `scanUserSettings` unit test covering `{}` and an
unrelated-field JSON object, plus an explicit stored-view preservation case.
- **What:** the first draft PATCH succeeds through the real HTTP → controller →
service → SQLite path without sending `sidebar_views`.
**File:** `apps/backend/internal/user/handlers/handlers_test.go`.
**How:** Gin/`httptest` integration test with the repository-created clean
user; assert GET defaults, PATCH 200, and GET read-back.
- **What:** unmatched active IDs remain rejected.
**File:** `apps/backend/internal/user/service/service_test.go`.
**How:** retain and run the existing `TestApplySidebarViewState` regression
coverage; no validation weakening is expected.
- **What:** an explicit empty `sidebar_views` replacement without an active ID
retains a coherent canonical view.
**File:** `apps/backend/internal/user/service/service_test.go` and
`apps/backend/internal/user/handlers/handlers_test.go`.
**How:** assert service normalization and real HTTP read-back before the
first draft-only edit.
## E2E Tests
- **Scenario:** **GIVEN** a new user's canonical `All tasks` view, **WHEN** the
first filter is edited, **THEN** the draft persists without a settings error
and survives reload.
**File:** `apps/web/e2e/tests/task/sidebar-filter.spec.ts`.
**What to verify:** canonical view selection, persisted
`sidebar_active_view_id`/`sidebar_draft`, absence of the error toast, and
active-view continuity after reload.
---
## Verification Results
- `cd apps/backend && go test -tags fts5 -run 'TestScanUserSettingsSidebarDefaults|TestScanUserSettingsPreservesExplicitEmptySidebarSettings|TestHTTPUpdateSidebarDraftFromCleanSettings|TestApplySidebarViews|TestApplySidebarViewState' ./internal/user/store ./internal/user/handlers ./internal/user/service -v` — 23 tests passed across 3 packages.
- `cd apps/backend && go test -tags fts5 ./internal/user/...` — 227 tests passed across 6 packages.
- `cd apps && pnpm --filter @kandev/web run typecheck` — passed with no TypeScript errors.
- `cd apps && pnpm --filter @kandev/web test -- lib/state/slices/ui/ui-slice.test.ts -t "syncs filter sort and group drafts"` — 1 passed, 41 skipped.
- `cd apps && pnpm --filter @kandev/web lint -- e2e/fixtures/test-base.ts e2e/helpers/api-client.ts e2e/tests/task/sidebar-filter.spec.ts` — passed.
- `cd apps/web && pnpm e2e:run --host --project chromium tests/task/sidebar-filter.spec.ts -- --grep "default 'All tasks' view"` — 1 Playwright test passed in 5.3s against the rebuilt backend; the managed runner exited cleanly and left no E2E backend/browser processes.
- `git diff --check` — passed.
- PR #2293 ([implementation head `cdc4f3737408d0aeb9c24b7076d98db2b21342b3`](https://github.com/kdlbs/kandev/pull/2293)) — all 40 reported checks passed after the review fixup; subsequent documentation-only commits are pushed with no failures or unresolved review threads observed while their fresh checks run.
---
## Implementation Waves And Parallel Candidates
Sequential execution in the primary conversation:
- [x] [Task 01: Persist the canonical sidebar default](task-01-persist-canonical-sidebar-default.md) — done
This is one vertical fix spanning a shared persistence contract and its browser
regression. It is not parallel-safe and does not authorize subagents.
## Risks and boundaries
- The backend and frontend currently duplicate the canonical view identity and
shape. The tests pin their agreement; introducing a generated/shared contract
is out of scope for this repair.
- `All tasks` is existing persisted domain copy. This fix does not change
localization behavior or rename existing views.
- Explicit non-empty sidebar arrays remain explicit values under ADR 0041;
empty replacements without an active ID normalize to the canonical view so
the backend cannot persist an invalid active/view pair.
- No schema migration, endpoint shape change, feature flag, or settings-data
rewrite is required.