Give every terminal its own identity, and report fleet presence

Answers "which of my 100 tills are alive and healthy", and fixes three things
that were fine on one device and broken on a hundred.

Terminal identity (lib/data/local/terminal_identity.dart)
- Every device mints a UUID on first run, stored in its own database, plus a
  short code (T4A9) derived from it. Renaming keeps the device id, so history
  keeps pointing at the same physical till.
- Replaces the literal 'TERM-01', which was hardcoded in five places. The whole
  fleet reported as one terminal: shift reports merged, MQTT topics collided,
  and a second connection with the same client id evicts the first from the
  broker — so two tills would have knocked each other offline in a loop.

Invoice numbers now carry the terminal code
- INV-2608-T4A9-00042. The sequence counter lives in each till's own database
  and starts at 1, so without this every terminal in the fleet minted
  INV-2608-00001 for its first sale of the month. The order UUID kept the data
  distinct; the number a customer quotes on a receipt was not.

SQLite pragmas
- WAL, so the product grid refreshing does not block the sale being written,
  and the file is never left mid-rewrite by a power cut.
- busy_timeout 5s, so a contended lock waits instead of throwing "database is
  locked" — which at checkout is a failed sale with a customer standing there.
- synchronous NORMAL, the right trade under WAL for a till.

Fleet presence (lib/data/sync/presence_reporter.dart)
- Retained status record on connect and once a minute: device id, code, name,
  app version, pending bill count, last upload, catalogue revision, sync halt
  state. Retained so a dashboard connecting at noon gets all 100 terminals
  immediately rather than a blank board.
- The Last Will already said "reachable". A till can be connected and still be
  holding 200 unsent bills or running last month's prices; only pending_bills
  and catalogue_revision say so.

NATS
- The MQTT gateway maps / to . so the existing transport works unchanged.
  SyncConfig.asNatsSubject() exposes the translation, and the contract doc
  gives the JetStream subjects (pos.*.*.order, pos.*.*.status) plus the two
  server-side requirements: a file-backed stream, and the ack published by the
  consumer after commit rather than by the ingest handler.

Tests: 129 -> 140. New coverage for identity minting and stability, per-device
invoice uniqueness, topic and client-id separation, NATS subject mapping, and
the two pragmas. Suite run three times clean.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

test/unit/checkout_test.dart

@@ -62,6 +62,7 @@ void main() {
           PaymentSplit(method: PaymentMethod.cash, amount: 124, tendered: 200),
         ],
         cashierName: 'Suriya',
+      terminalId: 'T0TEST',
       );
 
       final txn = result.transaction;
@@ -83,6 +84,7 @@ void main() {
           PaymentSplit(method: PaymentMethod.cash, amount: 124, tendered: 124),
         ],
         cashierName: 'Suriya',
+      terminalId: 'T0TEST',
       );
 
       final milk = await products.findByBarcode('8901234500011');
@@ -98,6 +100,7 @@ void main() {
           PaymentSplit(method: PaymentMethod.cash, amount: 124, tendered: 124),
         ],
         cashierName: 'Suriya',
+      terminalId: 'T0TEST',
       );
 
       final history = await transactions.history();
@@ -119,6 +122,7 @@ void main() {
           ),
         ],
         cashierName: 'Suriya',
+      terminalId: 'T0TEST',
       );
 
       expect(result.transaction.isSplit, isTrue);
@@ -140,6 +144,7 @@ void main() {
           PaymentSplit(method: PaymentMethod.cash, amount: 122, tendered: 200),
         ],
         cashierName: 'Suriya',
+      terminalId: 'T0TEST',
       );
 
       final updated = result.updatedCustomer!;
@@ -158,6 +163,7 @@ void main() {
             PaymentSplit(method: PaymentMethod.cash, amount: 0),
           ],
           cashierName: 'Suriya',
+      terminalId: 'T0TEST',
         ),
         throwsA(isA<CheckoutFailure>()),
       );
@@ -166,7 +172,12 @@ void main() {
     test('refuses a bill with no tender', () async {
       final cart = await milkCart();
       expect(
-        () => checkout(cart: cart, payments: const [], cashierName: 'Suriya'),
+        () => checkout(
+          cart: cart,
+          payments: const [],
+          cashierName: 'Suriya',
+          terminalId: 'T0TEST',
+        ),
         throwsA(isA<CheckoutFailure>()),
       );
     });
@@ -180,6 +191,7 @@ void main() {
             PaymentSplit(method: PaymentMethod.cash, amount: 100, tendered: 100),
           ],
           cashierName: 'Suriya',
+      terminalId: 'T0TEST',
         ),
         throwsA(isA<CheckoutFailure>()),
       );
@@ -198,6 +210,7 @@ void main() {
             ),
           ],
           cashierName: 'Suriya',
+      terminalId: 'T0TEST',
         ),
         throwsA(isA<CheckoutFailure>()),
       );
@@ -206,7 +219,12 @@ void main() {
     test('leaves stock untouched when validation fails', () async {
       final cart = await milkCart();
       try {
-        await checkout(cart: cart, payments: const [], cashierName: 'Suriya');
+        await checkout(
+          cart: cart,
+          payments: const [],
+          cashierName: 'Suriya',
+          terminalId: 'T0TEST',
+        );
       } on CheckoutFailure {
         // expected
       }

test/unit/fleet_identity_test.dart

@@ -0,0 +1,171 @@
+import 'package:flutter_test/flutter_test.dart';
+import 'package:nearle_pos/core/config/sync_config.dart';
+import 'package:nearle_pos/core/utils/formatters.dart';
+import 'package:nearle_pos/data/datasources/local_store.dart';
+import 'package:nearle_pos/data/datasources/seed_data.dart';
+import 'package:nearle_pos/data/local/app_database.dart';
+import 'package:nearle_pos/data/local/terminal_identity.dart';
+import 'package:nearle_pos/data/repositories/customer_repository_impl.dart';
+import 'package:nearle_pos/data/repositories/product_repository_impl.dart';
+import 'package:nearle_pos/data/repositories/transaction_repository_impl.dart';
+import 'package:nearle_pos/domain/entities/cart.dart';
+import 'package:nearle_pos/domain/entities/transaction.dart';
+import 'package:nearle_pos/domain/usecases/checkout_sale.dart';
+
+/// What has to hold when the same build is installed on 100 tills.
+///
+/// Every one of these was broken: the terminal id was the literal `TERM-01` in
+/// five places, so the whole fleet shared one identity, one set of MQTT topics
+/// and one invoice series.
+void main() {
+  late LocalStore store;
+
+  setUpAll(() {
+    LocalStore.registerSeed(
+      products: SeedData.products,
+      customers: SeedData.customers,
+    );
+  });
+
+  setUp(() async {
+    store = LocalStore.instance;
+    await store.reset(withCatalogue: true);
+  });
+
+  group('identity', () {
+    test('a device mints an identity on first run and keeps it', () async {
+      final identityStore = TerminalIdentityStore(store.catalogue);
+
+      final first = await identityStore.load();
+      expect(first.deviceId, isNotEmpty);
+      expect(first.code, startsWith('T'));
+
+      // A second read must not re-mint. If it did, a terminal would change
+      // identity on every restart and orphan the bills it had already written.
+      final second = await identityStore.load();
+      expect(second.deviceId, first.deviceId);
+      expect(second.code, first.code);
+    });
+
+    test('two devices get different codes', () {
+      // Derived from the device UUID rather than a counter, because there is no
+      // shared counter to draw from — each till mints alone and offline.
+      final a = TerminalIdentityStore.codeFor(
+        'a1b2c3d4-0000-0000-0000-000000000000',
+      );
+      final b = TerminalIdentityStore.codeFor(
+        '9f8e7d6c-0000-0000-0000-000000000000',
+      );
+      expect(a, 'TA1B2');
+      expect(b, 'T9F8E');
+      expect(a, isNot(b));
+    });
+
+    test('renaming keeps the device id, so history still points at the till',
+        () async {
+      final identityStore = TerminalIdentityStore(store.catalogue);
+      final before = await identityStore.load();
+
+      await identityStore.rename(code: 'till7', name: 'Counter 7');
+      final after = await identityStore.load();
+
+      expect(after.code, 'TILL7');
+      expect(after.name, 'Counter 7');
+      expect(after.deviceId, before.deviceId,
+          reason: 'the machine identity must survive a re-code',);
+    });
+
+    test('the identity is loaded by the store before anything is written',
+        () async {
+      expect(store.isReady, isTrue);
+      expect(store.terminal.deviceId, isNotEmpty);
+      expect(store.terminal.code, startsWith('T'));
+    });
+  });
+
+  group('invoice numbers', () {
+    test('two terminals ringing their first sale do not collide', () {
+      // The counter lives in each till's own database, so without the terminal
+      // code every device in the fleet mints INV-2608-00001 for its first sale.
+      final date = DateTime(2026, 8, 1);
+      final onTillA = Formatters.invoiceNumber(1, date, terminalCode: 'TA1B2');
+      final onTillB = Formatters.invoiceNumber(1, date, terminalCode: 'T9F8E');
+
+      expect(onTillA, 'INV-2608-TA1B2-00001');
+      expect(onTillA, isNot(onTillB));
+    });
+
+    test('a real sale carries this terminal\'s code', () async {
+      final products = ProductRepositoryImpl(store);
+      final checkout = CheckoutSale(
+        productRepository: products,
+        customerRepository: CustomerRepositoryImpl(store),
+        transactionRepository: TransactionRepositoryImpl(store),
+      );
+
+      final milk = (await products.findByBarcode('8901234500011'))!;
+      final result = await checkout(
+        cart: Cart(lines: [CartLine(product: milk, quantity: 1)]),
+        payments: const [
+          PaymentSplit(method: PaymentMethod.cash, amount: 62, tendered: 100),
+        ],
+        cashierName: 'Divya',
+        terminalId: store.terminal.code,
+      );
+
+      expect(result.transaction.invoiceNumber, contains(store.terminal.code));
+      expect(result.transaction.terminalId, store.terminal.code);
+    });
+  });
+
+  group('topics', () {
+    test('two terminals in one store publish on different topics', () {
+      const a = SyncConfig(storeId: 'store-01', terminalId: 'TA1B2');
+      const b = SyncConfig(storeId: 'store-01', terminalId: 'T9F8E');
+
+      expect(a.orderTopic, isNot(b.orderTopic));
+      expect(a.statusTopic, isNot(b.statusTopic));
+      // A shared client id would evict the other till from the broker on every
+      // connect, in a loop.
+      expect(a.clientId, isNot(b.clientId));
+    });
+
+    test('the catalogue topic is shared, because a price change is store-wide',
+        () {
+      const a = SyncConfig(storeId: 'store-01', terminalId: 'TA1B2');
+      const b = SyncConfig(storeId: 'store-01', terminalId: 'T9F8E');
+      expect(a.catalogueTopic, b.catalogueTopic);
+    });
+
+    test('topics translate to NATS subjects', () {
+      // NATS' MQTT gateway maps / to . — this is what a JetStream consumer
+      // binds to.
+      const config = SyncConfig(storeId: 'store-01', terminalId: 'TA1B2');
+      expect(
+        SyncConfig.asNatsSubject(config.orderTopic),
+        'pos.store-01.TA1B2.order',
+      );
+      expect(
+        SyncConfig.asNatsSubject(config.statusTopic),
+        'pos.store-01.TA1B2.status',
+      );
+    });
+  });
+
+  group('database pragmas', () {
+    test('foreign keys are enforced', () async {
+      final rows =
+          await AppDatabase.instance.db.rawQuery('PRAGMA foreign_keys');
+      expect(rows.first.values.first, 1,
+          reason: 'order_items must cascade with their order',);
+    });
+
+    test('a contended lock waits instead of throwing', () async {
+      // Default is 0, which surfaces at checkout as "database is locked" —
+      // a failed sale with a customer standing there.
+      final rows =
+          await AppDatabase.instance.db.rawQuery('PRAGMA busy_timeout');
+      expect(rows.first.values.first, greaterThanOrEqualTo(5000));
+    });
+  });
+}

test/unit/persistence_test.dart

@@ -82,6 +82,7 @@ void main() {
           PaymentSplit(method: PaymentMethod.cash, amount: 529, tendered: 529),
         ],
         cashierName: 'Divya',
+      terminalId: 'T0TEST',
       );
 
       final stored = (await transactions.history()).single;
@@ -113,6 +114,7 @@ void main() {
           PaymentSplit(method: PaymentMethod.cash, amount: 589, tendered: 600),
         ],
         cashierName: 'Divya',
+      terminalId: 'T0TEST',
       );
 
       final stored = (await transactions.history()).single;
@@ -135,6 +137,7 @@ void main() {
           PaymentSplit(method: PaymentMethod.cash, amount: 529, tendered: 529),
         ],
         cashierName: 'Divya',
+      terminalId: 'T0TEST',
       );
 
       final report = ShiftReport.fromTransactions(
@@ -193,6 +196,7 @@ void main() {
             ),
           ],
           cashierName: 'Divya',
+      terminalId: 'T0TEST',
         ),
         throwsA(isA<CheckoutFailure>()),
       );
@@ -210,6 +214,7 @@ void main() {
           PaymentSplit(method: PaymentMethod.cash, amount: 248, tendered: 250),
         ],
         cashierName: 'Divya',
+      terminalId: 'T0TEST',
       );
       expect((await products.findByBarcode('8901234500011'))!.stock,
           opening - 4,);
@@ -248,6 +253,7 @@ void main() {
             PaymentSplit(method: PaymentMethod.cash, amount: 124, tendered: 124),
           ],
           cashierName: 'Divya',
+      terminalId: 'T0TEST',
         ),
         throwsA(isA<CheckoutFailure>()),
       );
@@ -288,6 +294,7 @@ void main() {
           PaymentSplit(method: PaymentMethod.cash, amount: 529, tendered: 529),
         ],
         cashierName: 'Divya',
+      terminalId: 'T0TEST',
       );
 
       final outcome = await sync.syncOrders();
@@ -325,6 +332,7 @@ void main() {
           PaymentSplit(method: PaymentMethod.cash, amount: 62, tendered: 62),
         ],
         cashierName: 'Divya',
+      terminalId: 'T0TEST',
       );
       await sync.syncOrders();
 
@@ -365,6 +373,7 @@ void main() {
           PaymentSplit(method: PaymentMethod.cash, amount: due, tendered: due),
         ],
         cashierName: cashier,
+      terminalId: 'T0TEST',
       );
     }
 

test/unit/retention_test.dart

@@ -107,6 +107,7 @@ void main() {
         ),
       ],
       cashierName: cashier,
+      terminalId: 'T0TEST',
     );
     return due;
   }