fe428931ec
Two defects that share a shape: a figure landing on the wrong record.
Bill-level discounts were apportioned across every line by a single
factor, so "20% off Beverages" pulled tax out of the atta line as well.
The bill total was right either way, which is what made it easy to ship
— only the slab split on a filed return was wrong. Targeted campaigns
now reduce the lines they name, and bill-wide reductions still spread
pro rata, so the arithmetic is unchanged wherever it was already right.
Shoppers registered at a till only ever reached the back office as three
fields riding along on a bill. Somebody who signed up and bought nothing
existed on one terminal and nowhere else, and two tills registering the
same mobile each minted their own row. Customers are now an outbox of
their own on pos/{store}/{terminal}/customer, and the id is a UUIDv5
over the normalised mobile number — so a hundred terminals agree on who
a shopper is without talking to each other.
Registrations go up before bills, and a failure there cannot strand a
day's takings. No loyalty figures are sent: they belong to the bill
stream, which is idempotent and knows about every counter.
Two things found while building it. Numbers were keyed on raw digits, so
a cashier typing +91 forked a shopper as effectively as a random id
would. And the sale path wrote the customer with ConflictAlgorithm
.replace, which is a DELETE and an INSERT — every column absent from the
row reverts to its schema default, so the new sync flag would have been
cleared by the shopper's next purchase.
Schema v8. Existing customers are queued rather than assumed sent: the
terminal cannot tell an imported row from a locally registered one, and
only one of those mistakes loses somebody.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
112 lines
3.3 KiB
Dart
112 lines
3.3 KiB
Dart
import '../entities/shift_report.dart';
|
|
import '../entities/sync_event.dart';
|
|
import '../entities/transaction.dart';
|
|
|
|
/// Result of one upload pass.
|
|
class SyncOutcome {
|
|
const SyncOutcome({
|
|
required this.attempted,
|
|
required this.uploaded,
|
|
this.rejected = 0,
|
|
this.error,
|
|
this.isRetryable = true,
|
|
});
|
|
|
|
final int attempted;
|
|
final int uploaded;
|
|
|
|
/// Bills the back office looked at and refused. These stay on the terminal
|
|
/// but sending them again unchanged will fail again, so they need a person.
|
|
final int rejected;
|
|
|
|
final String? error;
|
|
|
|
/// Whether trying again could plausibly work. False for a bad credential or
|
|
/// an unconfigured endpoint — the drain engine halts rather than retrying
|
|
/// something that cannot succeed.
|
|
final bool isRetryable;
|
|
|
|
bool get isSuccess => error == null;
|
|
bool get hadNothingToDo => attempted == 0;
|
|
int get remaining => attempted - uploaded;
|
|
}
|
|
|
|
/// One row of the order sync log.
|
|
class OrderSyncRow {
|
|
const OrderSyncRow({
|
|
required this.orderId,
|
|
required this.invoiceNumber,
|
|
required this.total,
|
|
required this.createdAt,
|
|
required this.isSynced,
|
|
this.syncedAt,
|
|
this.attempts = 0,
|
|
this.error,
|
|
});
|
|
|
|
final String orderId;
|
|
final String invoiceNumber;
|
|
final double total;
|
|
final DateTime createdAt;
|
|
final bool isSynced;
|
|
final DateTime? syncedAt;
|
|
final int attempts;
|
|
final String? error;
|
|
}
|
|
|
|
/// The terminal's network touchpoints.
|
|
///
|
|
/// Pull the catalogue; upload every order still at `sync_status = 0`. Nothing
|
|
/// else leaves the device. *When* the upload runs is not decided here — see
|
|
/// `SyncEngine`, which owns triggers and retry policy.
|
|
abstract class SyncRepository {
|
|
bool get hasCatalogue;
|
|
DateTime? get lastImportAt;
|
|
String? get catalogueRevision;
|
|
|
|
/// Morning step — downloads products and writes them to SQLite.
|
|
Future<SyncEvent> importCatalogue({
|
|
void Function(double progress, String stage)? onProgress,
|
|
});
|
|
|
|
/// How many bills are still held locally.
|
|
Future<int> unsyncedCount();
|
|
|
|
Future<List<SaleTransaction>> unsyncedOrders();
|
|
|
|
/// Today's trading totals, read back from SQLite.
|
|
///
|
|
/// Terminal-wide by default. Set [scopeToCashier] to cover only the bills
|
|
/// [cashierName] rang — what a till is actually settled against.
|
|
Future<ShiftReport> todayReport({
|
|
required String terminalId,
|
|
required String cashierName,
|
|
bool scopeToCashier = false,
|
|
});
|
|
|
|
/// One upload pass — sends pending orders and flips the ones the back office
|
|
/// confirmed to `sync_status = 1`. Failures leave every row untouched at 0.
|
|
Future<SyncOutcome> syncOrders({
|
|
void Function(double progress, String stage)? onProgress,
|
|
});
|
|
|
|
/// How many shoppers registered at this till are still waiting to go up.
|
|
Future<int> unsyncedCustomerCount();
|
|
|
|
/// Uploads shoppers registered at this till.
|
|
///
|
|
/// Deliberately separate from [syncOrders]. A registration is not a financial
|
|
/// record: it can be replayed safely, and it must not be stuck behind a bill
|
|
/// the back office has refused. Run it first so a bill referring to a new
|
|
/// shopper arrives after the shopper does.
|
|
Future<SyncOutcome> syncCustomers();
|
|
|
|
/// Retires confirmed bills past their retention window. Archived totals are
|
|
/// untouched.
|
|
Future<int> purgeExpired();
|
|
|
|
Future<List<OrderSyncRow>> orderSyncRows({int limit = 200});
|
|
|
|
List<SyncEvent> get events;
|
|
}
|