feat(offline): tier 2 phase 3 — write queue with optimistic UI

Offline writes now queue + apply optimistically instead of throwing.
On reconnect, the queue drains automatically; conflicts and rejections
surface as one-time SnackBars so the user knows their edit didn't land.

- Drift schema v3: `pending_writes` table (verb + payload + baseline +
  tries + last_error). Negative ids serve as cache placeholders for
  offline-created rows until replay assigns the server id.
- Each write repository (notes, tasks, projects, milestones, events)
  now catches NetworkException, applies the change to cache (with a
  fresh `nextTempId()` for creates), and enqueues the API call.
- Edits to a still-queued offline-created row coalesce into the
  original create payload — only one server call per row, in order.
- Deletes of still-queued offline-created rows drop the queue entry
  and the cache row; no server call ever happens.
- New WriteQueue service drains the queue oldest-first.
  Server-wins on `updated_at` baseline check (notes/tasks/projects);
  last-writer-wins for milestones/events (no getOne available).
  4xx → drop + surface as `rejected`; conflict → drop + `overwritten`;
  404 on update → drop + `missing`; 5xx/network → keep + retry next
  online cycle.
- Replay fires on AuthStatus → authenticated transitions
  (cold-start, came-back-online, login).
- OfflineBanner shows "Retry (N)" with the pending-writes count.
- Distinct ServerException added so 4xx no longer masquerade as
  NetworkException — the queue can drop them instead of looping.

flutter analyze clean; 21 tests pass (3 new for QueueFailure messaging).
Phase 4 (read-only UI indicators on cached/temp rows) still ahead.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
2026-04-28 22:08:40 -04:00
parent fe10067761
commit 7df7b5ff85
14 changed files with 2090 additions and 93 deletions
+33
View File
@@ -1,5 +1,6 @@
import 'package:fabled_app/data/models/calendar_event.dart';
import 'package:fabled_app/data/api/voice_api.dart';
import 'package:fabled_app/data/repositories/write_queue.dart';
import 'package:fabled_app/providers/voice_provider.dart';
import 'package:fabled_app/data/models/knowledge_item.dart';
import 'package:fabled_app/data/models/note.dart';
@@ -207,4 +208,36 @@ void main() {
});
});
group('QueueFailure.message', () {
test('overwritten with title quotes the title', () {
final f = QueueFailure(
reason: QueueFailureReason.overwritten,
domain: 'notes',
title: 'Grocery list',
);
expect(f.message, contains('"Grocery list"'));
expect(f.message, contains('overwritten'));
});
test('rejected without title falls back to generic phrasing', () {
final f = QueueFailure(
reason: QueueFailureReason.rejected,
domain: 'tasks',
detail: 'title required',
);
expect(f.message, contains('an offline edit'));
expect(f.message, contains('title required'));
});
test('missing communicates server-side deletion', () {
final f = QueueFailure(
reason: QueueFailureReason.missing,
domain: 'projects',
title: 'Q2 launch',
);
expect(f.message, contains('"Q2 launch"'));
expect(f.message, contains('deleted on the server'));
});
});
}