Drain bills to the back office automatically, over MQTT or HTTP
Turns the orders table into a queue that empties itself. Bills were only uploaded when a cashier pressed Sync at end of day; a till that was never pressed held a day's takings indefinitely. Drain engine (lib/data/sync/sync_engine.dart) - Triggers on sale committed, network regained, 5-minute poll, head-office request, and the manual button. - Single flight: a busy till firing a trigger per sale would otherwise have several passes reading the same pending rows and send every bill twice. A trigger arriving mid-drain is queued and replayed, so nothing is dropped. - Exponential backoff with +/-20% jitter to a 5-minute ceiling. The jitter matters: a store's terminals all fail at the same instant when the line drops, and would retry in lockstep without it. - Halts rather than loops on a failure retrying cannot fix (bad credential, refused batch). Pressing Sync clears the halt. Transports (lib/data/remote/) - OrderTransport interface; MQTT, HTTP and simulated implementations. The repository does not know which is in use. - MQTT: QoS 1 uplink, application-level ACK correlated by batch_id on a return topic, retained Last Will for terminal-offline detection, downlink for catalogue pushes and remote sync requests. - A broker PUBACK is never treated as acceptance. It means the broker holds the bytes, not that the ledger took the sale. Only ids the back office names are marked synced; silence leaves a bill pending. - HTTP carries a stable idempotency key across retries of the same bills. Retention - Accepted bills are kept 7 days instead of deleted, so a batch the back office later loses can be re-sent in full. Purged after that; archived totals stay forever. - forBusinessDate now reads pending rows only. A retained bill exists in both the orders table and day_archive, and summing both would overstate the day. Fixes found while building this - SyncEngine._refreshPending wrote state.copyWith(pending: await ...). Dart evaluates the receiver before the awaited argument, so a connectivity drop during the wait was silently overwritten by the stale snapshot. Caught by the first run of the new engine tests. - PrinterSettingsController wrote state after four awaits with no mounted check, throwing "used after dispose" when Settings was left mid-load. This was pre-existing and reached the cashier as a red screen. Also - Header pill now reports real sync state: LIVE / n QUEUED / SYNCING / SYNC HALTED, with an explanation of where the bills are. - Settings shows the route, last upload, next retry and retention window. - docs/sync-contract.md states what the back office must implement, including the idempotency requirement that at-least-once delivery makes mandatory. Tests: 90 -> 129 passing. New coverage for backoff shape and jitter band, single flight, halting, ACK correlation and partial acceptance, at-least-once duplicate handling, retention and purge, and no double-counting after a sync. Suite run six times clean. Not addressed: bills already synced by an older build went up overstated and still need server-side reconciliation. Broker credentials have no Settings editor yet. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Suriya
@@ -154,16 +154,19 @@ class _Breadcrumb extends StatelessWidget {
|
||||
}
|
||||
}
|
||||
|
||||
class _LivePill extends StatefulWidget {
|
||||
/// What the pill is saying, in the order it takes precedence.
|
||||
enum _Liveness { offlineSim, halted, syncing, queued, live }
|
||||
|
||||
class _LivePill extends ConsumerStatefulWidget {
|
||||
const _LivePill({required this.offline});
|
||||
|
||||
final bool offline;
|
||||
|
||||
@override
|
||||
State<_LivePill> createState() => _LivePillState();
|
||||
ConsumerState<_LivePill> createState() => _LivePillState();
|
||||
}
|
||||
|
||||
class _LivePillState extends State<_LivePill>
|
||||
class _LivePillState extends ConsumerState<_LivePill>
|
||||
with SingleTickerProviderStateMixin {
|
||||
late final AnimationController _c = AnimationController(
|
||||
vsync: this,
|
||||
@@ -178,16 +181,62 @@ class _LivePillState extends State<_LivePill>
|
||||
|
||||
@override
|
||||
Widget build(BuildContext context) {
|
||||
final offline = widget.offline;
|
||||
final tone = offline ? AppColors.warning : AppColors.success;
|
||||
final surface =
|
||||
offline ? AppColors.warningSurface : AppColors.successSurface;
|
||||
// The engine may not have emitted yet on a cold start, so fall back to its
|
||||
// current value rather than showing nothing.
|
||||
final sync = ref.watch(syncEngineStateProvider).value ??
|
||||
ref.watch(syncEngineProvider).state;
|
||||
|
||||
final liveness = switch (0) {
|
||||
_ when widget.offline => _Liveness.offlineSim,
|
||||
_ when sync.isHalted => _Liveness.halted,
|
||||
_ when sync.isSyncing => _Liveness.syncing,
|
||||
// Bills waiting is normal for a few seconds after a sale; it is only
|
||||
// worth flagging once they are visibly piling up.
|
||||
_ when sync.pending > 0 => _Liveness.queued,
|
||||
_ => _Liveness.live,
|
||||
};
|
||||
|
||||
final (label, tone, surface, message) = switch (liveness) {
|
||||
_Liveness.offlineSim => (
|
||||
'OFFLINE (SIM)',
|
||||
AppColors.warning,
|
||||
AppColors.warningSurface,
|
||||
'Simulate offline is ON in Settings — imports and syncs are being '
|
||||
'failed deliberately.',
|
||||
),
|
||||
_Liveness.halted => (
|
||||
'SYNC HALTED',
|
||||
AppColors.danger,
|
||||
AppColors.dangerSurface,
|
||||
'Uploading stopped because retrying will not help: '
|
||||
'${sync.lastError ?? 'the back office refused the batch'}. '
|
||||
'Every bill is still safe on this terminal. Press Sync to try '
|
||||
'again once it is sorted.',
|
||||
),
|
||||
_Liveness.syncing => (
|
||||
'SYNCING',
|
||||
AppColors.primary,
|
||||
AppColors.primarySurface,
|
||||
'Uploading bills to the back office.',
|
||||
),
|
||||
_Liveness.queued => (
|
||||
'${sync.pending} QUEUED',
|
||||
AppColors.warning,
|
||||
AppColors.warningSurface,
|
||||
'${sync.pending} bill(s) are stored on this terminal and waiting to '
|
||||
'upload. They are safe; nothing is lost while the line is down.',
|
||||
),
|
||||
_Liveness.live => (
|
||||
'LIVE',
|
||||
AppColors.success,
|
||||
AppColors.successSurface,
|
||||
'Terminal is operating normally and everything rung has been '
|
||||
'uploaded.',
|
||||
),
|
||||
};
|
||||
|
||||
return Tooltip(
|
||||
message: offline
|
||||
? 'Simulate offline is ON in Settings — imports and syncs are being '
|
||||
'failed deliberately.'
|
||||
: 'Terminal is operating normally.',
|
||||
message: message,
|
||||
child: Container(
|
||||
padding: const EdgeInsets.symmetric(
|
||||
horizontal: AppSpacing.md,
|
||||
@@ -210,7 +259,7 @@ class _LivePillState extends State<_LivePill>
|
||||
),
|
||||
const SizedBox(width: AppSpacing.xs + 2),
|
||||
Text(
|
||||
offline ? 'OFFLINE (SIM)' : 'LIVE',
|
||||
label,
|
||||
style: TextStyle(
|
||||
color: tone,
|
||||
fontSize: 10.5,
|
||||
|
||||
Reference in New Issue
Block a user