308aada5f9
Co-authored-by: Carlos Florencio <carlosmflorencio@gmail.com>
5.0 KiB
5.0 KiB
id, title, status, wave, depends_on, plan, requirements, acceptance_criteria, system_design
| id | title | status | wave | depends_on | plan | requirements | acceptance_criteria | system_design | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 01-persist-and-sync-feedback | Persist and synchronize preview feedback | completed | 1 | plan.md |
|
|
|
Task 01: Persist and Synchronize Preview Feedback
Summary
Create the task-owned revisioned collection, screenshot claim state, authorized WebSocket CRUD, and frontend snapshot projection. This work makes pending data durable and recoverable before any production capture or delivery UI depends on it.
In scope
- SQLite and PostgreSQL schema, replay-safe migrations, constraints, indexes, task cascades, and stable ordering.
- Shared models and
previewfeedbackvalidators for kinds, fields, collection limits, PNG limits, and optimistic versions. - Service and repository CRUD, idempotent caller-generated create IDs, clear by collection revision, and screenshot task claims and deletion cleanup.
- Authorized
task.preview_feedback.*WebSocket actions, stable conflict/error codes, full snapshots, and changed events. - A task-keyed frontend API, state slice, reconnect reconciliation, and hooks.
- Tests for session deletion and primary changes remaining irrelevant to task ownership.
Out of scope
- Composer context and message delivery.
- Browser or HTML-preview capture controls.
- Client-side screenshot rasterization.
Acceptance
- Backend restart, reconnect, session changes, and a second authorized client recover the same task snapshot and screenshot descriptors.
- Exact-version update/delete and revision-guarded clear reject stale clients without changing the collection.
- Task deletion, feedback deletion, and failed creates leave no unowned durable screenshot claims; transient object-delete failure remains recoverable.
TDD sequence
- Add failing repository and service contract tests for schema replay, constraints, limits, optimistic versions, task cascades, and attachment ownership; run them and record the expected failure.
- Implement the minimum models, migrations, repositories, and service until those tests pass under the race detector.
- Add failing handler and frontend snapshot tests for authorization, idempotency, events, reconnect, and stale revisions; run them RED.
- Implement the WebSocket and frontend state boundary, rerun GREEN, then refactor duplicate plan-comment-shaped synchronization helpers only where both call sites remain clearer.
Verification
cd apps/backend
go test -race ./internal/task/previewfeedback ./internal/task/repository/sqlite ./internal/task/service ./internal/task/handlers
cd ../../apps
pnpm --filter @kandev/web test -- --run lib/api/domains/preview-feedback-api.test.ts lib/state/slices/preview-feedback lib/ws/handlers/preview-feedback.test.ts hooks/domains/comments/use-preview-feedback.test.ts
cd web
pnpm run typecheck
pnpm exec eslint lib/api/domains/preview-feedback-api.ts lib/state/slices/preview-feedback lib/ws/handlers/preview-feedback.ts hooks/domains/comments/use-preview-feedback.ts
Files likely touched
apps/backend/internal/task/models/apps/backend/internal/task/previewfeedback/apps/backend/internal/task/repository/interfaces.goapps/backend/internal/task/repository/sqlite/base_schema.goapps/backend/internal/task/repository/sqlite/base_migrations.goapps/backend/internal/task/repository/sqlite/preview_feedback*.goapps/backend/internal/task/service/preview_feedback_service*.goapps/backend/internal/task/handlers/task_preview_feedback_handlers*.goapps/backend/pkg/websocket/actions.goapps/web/lib/api/domains/preview-feedback-api*.tsapps/web/lib/state/slices/preview-feedback/apps/web/lib/ws/handlers/preview-feedback*.tsapps/web/hooks/domains/comments/use-preview-feedback*.ts
Dependencies
None.
Risks
- A claimed image can leak if row deletion and storage cleanup do not share the existing attachment lifecycle.
- Database checks and byte accounting can diverge between SQLite and PostgreSQL unless the shared validator remains authoritative.
- Snapshot replacement must reject stale revisions without hiding a legitimate empty collection.
Parallelism
sequential
Inputs
- Persistence, limits, synchronization, lifecycle, and security sections in the system design.
- Existing task plan comment and prompt attachment implementations as adjacent reference patterns.
Results
Implemented task-owned SQLite/PostgreSQL-compatible storage, optimistic CRUD, idempotent creates, screenshot claim validation and cleanup, authorized WebSocket actions, authoritative change events, and a reconnecting task-keyed frontend snapshot projection. Focused backend tests pass under the race detector; the frontend API, state, WebSocket, and hook tests plus the web typecheck pass.