Files
nearle_pos/lib/presentation/pos/widgets/page_header.dart
Suriya 0a49323858 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>
2026-08-01 10:57:29 +05:30

403 lines
12 KiB
Dart

import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import '../../../app/providers.dart';
import '../../../core/theme/app_colors.dart';
import '../../../core/theme/app_dimens.dart';
import '../../../core/theme/app_layout.dart';
import '../../../core/utils/formatters.dart';
import '../providers/cart_controller.dart';
import '../providers/navigation_provider.dart';
/// White page header: breadcrumb, title, and the terminal's quick actions.
///
/// Replaces the old purple app bar now that branding lives in the sidebar.
class PageHeader extends ConsumerWidget {
const PageHeader({
super.key,
required this.layout,
this.onMenuTap,
});
final PosLayout layout;
final VoidCallback? onMenuTap;
@override
Widget build(BuildContext context, WidgetRef ref) {
final compact = layout.sidebarIsDrawer;
// Measured from the header's own box, not the window. The window can be
// wide while this column is narrow — the sidebar and the docked bill both
// take from it — which is how the status chrome ended up overflowing.
return LayoutBuilder(
builder: (context, box) {
final showStatus = box.maxWidth >= 720;
return _bar(context, ref, compact, showStatus);
},
);
}
Widget _bar(
BuildContext context,
WidgetRef ref,
bool compact,
bool showStatus,
) {
final module = ref.watch(activeModuleProvider);
final now = ref.watch(clockProvider).value ?? DateTime.now();
return Container(
constraints: const BoxConstraints(minHeight: AppSizes.headerHeight),
padding: EdgeInsets.symmetric(
horizontal: layout.contentPadding,
vertical: AppSpacing.md,
),
decoration: const BoxDecoration(
color: AppColors.surface,
border: Border(bottom: BorderSide(color: AppColors.border)),
),
child: Row(
children: [
if (compact) ...[
IconButton(
onPressed: onMenuTap,
icon: const Icon(Icons.menu_rounded),
tooltip: 'Menu',
color: AppColors.textPrimary,
),
const SizedBox(width: AppSpacing.xs),
],
Flexible(
child: Column(
mainAxisSize: MainAxisSize.min,
crossAxisAlignment: CrossAxisAlignment.start,
children: [
Text(
module.title,
overflow: TextOverflow.ellipsis,
style: const TextStyle(
fontSize: 19,
fontWeight: FontWeight.w600,
letterSpacing: -0.4,
color: AppColors.textPrimary,
height: 1.2,
),
),
if (!compact) _Breadcrumb(module: module),
],
),
),
const Spacer(),
if (showStatus) ...[
_LivePill(offline: ref.watch(simulateOfflineProvider)),
const SizedBox(width: AppSpacing.lg),
Text(
Formatters.time(now),
style: const TextStyle(
fontSize: 13.5,
fontWeight: FontWeight.w500,
color: AppColors.textSecondary,
fontFeatures: [FontFeature.tabularFigures()],
),
),
const SizedBox(width: AppSpacing.lg),
Container(width: 1, height: 26, color: AppColors.border),
const SizedBox(width: AppSpacing.lg),
],
_ParkedBillsButton(compact: compact),
const SizedBox(width: AppSpacing.sm),
_NewSaleButton(compact: compact),
],
),
);
}
}
class _Breadcrumb extends StatelessWidget {
const _Breadcrumb({required this.module});
final PosModule module;
@override
Widget build(BuildContext context) {
const style = TextStyle(fontSize: 12, color: AppColors.textTertiary);
return Row(
mainAxisSize: MainAxisSize.min,
children: [
const Text('Home', style: style),
const Padding(
padding: EdgeInsets.symmetric(horizontal: AppSpacing.xs + 2),
child: Icon(Icons.chevron_right_rounded,
size: 13, color: AppColors.textTertiary,),
),
Text(module.section.label, style: style),
const Padding(
padding: EdgeInsets.symmetric(horizontal: AppSpacing.xs + 2),
child: Icon(Icons.chevron_right_rounded,
size: 13, color: AppColors.textTertiary,),
),
Text(
module.label,
style: const TextStyle(
fontSize: 12,
fontWeight: FontWeight.w600,
color: AppColors.primary,
),
),
],
);
}
}
/// 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
ConsumerState<_LivePill> createState() => _LivePillState();
}
class _LivePillState extends ConsumerState<_LivePill>
with SingleTickerProviderStateMixin {
late final AnimationController _c = AnimationController(
vsync: this,
duration: const Duration(milliseconds: 1400),
)..repeat(reverse: true);
@override
void dispose() {
_c.dispose();
super.dispose();
}
@override
Widget build(BuildContext context) {
// 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: message,
child: Container(
padding: const EdgeInsets.symmetric(
horizontal: AppSpacing.md,
vertical: AppSpacing.xs + 2,
),
decoration: BoxDecoration(
color: surface,
borderRadius: AppRadius.brPill,
),
child: Row(
mainAxisSize: MainAxisSize.min,
children: [
FadeTransition(
opacity: _c,
child: Container(
width: 7,
height: 7,
decoration: BoxDecoration(color: tone, shape: BoxShape.circle),
),
),
const SizedBox(width: AppSpacing.xs + 2),
Text(
label,
style: TextStyle(
color: tone,
fontSize: 10.5,
fontWeight: FontWeight.w700,
letterSpacing: 0.8,
),
),
],
),
),
);
}
}
class _ParkedBillsButton extends ConsumerWidget {
const _ParkedBillsButton({required this.compact});
final bool compact;
@override
Widget build(BuildContext context, WidgetRef ref) {
final parked = ref.watch(parkedBillsProvider).value ?? const [];
if (compact) {
return IconButton(
tooltip: 'Parked bills',
onPressed: () => _openParked(context, ref),
icon: Badge(
isLabelVisible: parked.isNotEmpty,
label: Text('${parked.length}'),
backgroundColor: AppColors.warning,
child: const Icon(Icons.pause_circle_outline_rounded),
),
);
}
return OutlinedButton.icon(
onPressed: () => _openParked(context, ref),
icon: const Icon(Icons.pause_circle_outline_rounded, size: 17),
label: Text(
parked.isEmpty ? 'Parked' : 'Parked (${parked.length})',
),
style: OutlinedButton.styleFrom(
minimumSize: const Size(0, 42),
padding: const EdgeInsets.symmetric(horizontal: AppSpacing.lg),
foregroundColor: AppColors.textSecondary,
),
);
}
void _openParked(BuildContext context, WidgetRef ref) {
final parked = ref.read(parkedBillsProvider).value ?? const [];
if (parked.isEmpty) {
ScaffoldMessenger.of(context)
..hideCurrentSnackBar()
..showSnackBar(const SnackBar(content: Text('No parked bills.')));
return;
}
showDialog<void>(
context: context,
builder: (_) => AlertDialog(
title: const Text('Parked bills'),
content: SizedBox(
width: (MediaQuery.sizeOf(context).width - 96).clamp(280.0, 380.0),
child: ListView.separated(
shrinkWrap: true,
itemCount: parked.length,
separatorBuilder: (_, __) => const Divider(height: 1),
itemBuilder: (_, i) {
final bill = parked[i];
return ListTile(
leading: const Icon(Icons.receipt_long_rounded,
color: AppColors.primary,),
title: Text(bill.displayLabel),
subtitle: Text(
'${bill.cart.lineCount} items · '
'${Formatters.money(bill.cart.grandTotal)} · '
'${Formatters.time(bill.parkedAt)}',
),
onTap: () async {
await ref
.read(cartControllerProvider.notifier)
.resume(bill);
ref.invalidate(parkedBillsProvider);
if (context.mounted) Navigator.of(context).pop();
},
);
},
),
),
actions: [
TextButton(
onPressed: () => Navigator.of(context).pop(),
child: const Text('Close'),
),
],
),
);
}
}
class _NewSaleButton extends ConsumerWidget {
const _NewSaleButton({required this.compact});
final bool compact;
@override
Widget build(BuildContext context, WidgetRef ref) {
void start() {
ref.read(cartControllerProvider.notifier).reset();
ref.read(activeModuleProvider.notifier).state = PosModule.pos;
ScaffoldMessenger.of(context)
..hideCurrentSnackBar()
..showSnackBar(const SnackBar(content: Text('Started a new sale.')));
}
if (compact) {
return IconButton.filled(
tooltip: 'New sale',
onPressed: start,
icon: const Icon(Icons.add_rounded),
style: IconButton.styleFrom(backgroundColor: AppColors.primary),
);
}
return FilledButton.icon(
onPressed: start,
icon: const Icon(Icons.add_rounded, size: 18),
label: const Text('New Sale'),
style: FilledButton.styleFrom(
backgroundColor: AppColors.primary,
minimumSize: const Size(0, 42),
padding: const EdgeInsets.symmetric(horizontal: AppSpacing.lg),
shape: const RoundedRectangleBorder(borderRadius: AppRadius.brSm),
),
);
}
}