nearle_pos/lib/data/local/app_database.dart

import 'package:flutter/foundation.dart';
import 'package:path/path.dart' as p;
import 'package:sqflite_common_ffi/sqflite_ffi.dart';

/// SQLite database for the terminal.
///
/// This is the source of truth for everything the cashier produces. Orders are
/// written here the moment a sale completes, so a crash, a power cut or a
/// closed app cannot lose a bill that has not yet reached the server.
class AppDatabase {
  AppDatabase._();

  static final AppDatabase instance = AppDatabase._();

  static const String _fileName = 'nearle_pos.db';
  static const int _version = 4;

  Database? _db;

  Database get db {
    final database = _db;
    if (database == null) {
      throw StateError('AppDatabase.open() must be called before use.');
    }
    return database;
  }

  bool get isOpen => _db != null;

  /// Opens the database, creating the schema on first run.
  ///
  /// Desktop needs the FFI factory installed first; Android and iOS use the
  /// platform implementation that ships with sqflite.
  Future<void> open({String? overridePath}) async {
    if (_db != null) return;

    if (kIsWeb) {
      // sqflite has no web implementation. Fail loudly here rather than
      // letting databaseFactory throw something unreadable further down.
      throw UnsupportedError(
        'Nearle POS stores bills in SQLite, which has no web implementation. '
        'Run the app on macOS, Windows, Linux or an Android tablet.',
      );
    }

    const desktop = {
      TargetPlatform.windows,
      TargetPlatform.linux,
      TargetPlatform.macOS,
    };
    if (desktop.contains(defaultTargetPlatform)) {
      sqfliteFfiInit();
      databaseFactory = databaseFactoryFfi;
    }

    final path = overridePath ??
        p.join(await databaseFactory.getDatabasesPath(), _fileName);

    _db = await databaseFactory.openDatabase(
      path,
      options: OpenDatabaseOptions(
        version: _version,
        onConfigure: _configure,
        onCreate: (db, version) async => _createSchema(db),
        onUpgrade: (db, from, to) async {
          if (from < 2) await db.execute(_createDayArchive);
          if (from < 3) {
            await db.execute(
              'ALTER TABLE ${Tables.products} ADD COLUMN hsn_code TEXT',
            );
          }
          if (from < 4) await _upgradeToV4(db, from: from);
        },
      ),
    );
  }

  /// In-memory database for tests.
  Future<void> openInMemory() async {
    if (_db != null) await close();
    sqfliteFfiInit();
    databaseFactory = databaseFactoryFfi;
    _db = await databaseFactory.openDatabase(
      inMemoryDatabasePath,
      options: OpenDatabaseOptions(
        version: _version,
        onConfigure: _configure,
        onCreate: (db, version) async => _createSchema(db),
      ),
    );
  }

  /// Pragmas applied on every connection, before any query runs.
  ///
  /// Defaults are wrong for a till:
  ///
  /// * **WAL** lets a read proceed while a write is in flight. On the rollback
  ///   journal the product grid refreshing would block the sale being written.
  ///   It also survives a power cut better: the database file is never left
  ///   mid-rewrite.
  /// * **busy_timeout** makes a contended lock wait instead of throwing
  ///   `database is locked` — which, at checkout, is a failed sale.
  /// * **synchronous = NORMAL** is the right trade under WAL: an fsync per
  ///   transaction costs more than a POS can spare, and WAL still recovers a
  ///   committed transaction after a crash. Only a host OS crash or power loss
  ///   can lose the last commits, which is what the UPS is for.
  static Future<void> _configure(Database db) async {
    await db.execute('PRAGMA foreign_keys = ON');
    await db.execute('PRAGMA busy_timeout = 5000');

    // In-memory databases have no WAL; asking for it is harmless but pointless.
    await db.execute('PRAGMA journal_mode = WAL');
    await db.execute('PRAGMA synchronous = NORMAL');
  }

  Future<void> close() async {
    await _db?.close();
    _db = null;
  }

  /// Drops every row without touching the schema. Used by tests.
  Future<void> clear() async {
    final batch = db.batch();
    for (final t in const [
      Tables.orderItems,
      Tables.orders,
      Tables.dayArchive,
      Tables.products,
      Tables.customers,
      Tables.parkedBills,
      Tables.syncLog,
      Tables.meta,
    ]) {
      batch.delete(t);
    }
    await batch.commit(noResult: true);
  }

  Future<void> _createSchema(Database db) async {
    // ------------------------------------------------------------ products
    await db.execute('''
      CREATE TABLE ${Tables.products} (
        id          TEXT PRIMARY KEY,
        name        TEXT    NOT NULL,
        barcode     TEXT    NOT NULL,
        sku         TEXT    NOT NULL,
        category    TEXT    NOT NULL,
        price       REAL    NOT NULL,
        mrp         REAL,
        stock       REAL    NOT NULL DEFAULT 0,
        emoji       TEXT,
        image_url   TEXT,
        unit        TEXT    NOT NULL DEFAULT 'piece',
        gst_rate    REAL    NOT NULL DEFAULT 0.18,
        hsn_code    TEXT,
        brand       TEXT,
        is_active   INTEGER NOT NULL DEFAULT 1,
        updated_at  INTEGER NOT NULL
      )
    ''');
    // Barcode lookup is the hot path during scanning.
    await db.execute(
      'CREATE UNIQUE INDEX idx_products_barcode ON ${Tables.products}(barcode)',
    );
    await db.execute(
      'CREATE INDEX idx_products_category ON ${Tables.products}(category)',
    );

    // ----------------------------------------------------------- customers
    await db.execute('''
      CREATE TABLE ${Tables.customers} (
        id             TEXT PRIMARY KEY,
        name           TEXT    NOT NULL,
        mobile         TEXT    NOT NULL,
        email          TEXT,
        gender         TEXT    NOT NULL DEFAULT 'unspecified',
        date_of_birth  INTEGER,
        loyalty_points INTEGER NOT NULL DEFAULT 0,
        lifetime_spend REAL    NOT NULL DEFAULT 0,
        visit_count    INTEGER NOT NULL DEFAULT 0,
        created_at     INTEGER,
        last_visit_at  INTEGER
      )
    ''');
    await db.execute(
      'CREATE UNIQUE INDEX idx_customers_mobile ON ${Tables.customers}(mobile)',
    );

    // -------------------------------------------------------------- orders
    await db.execute('''
      CREATE TABLE ${Tables.orders} (
        id               TEXT PRIMARY KEY,
        invoice_number   TEXT    NOT NULL UNIQUE,
        created_at       INTEGER NOT NULL,
        business_date    TEXT    NOT NULL,
        cashier_name     TEXT    NOT NULL,
        terminal_id      TEXT    NOT NULL,
        customer_id      TEXT,
        customer_mobile  TEXT,
        customer_name    TEXT,
        subtotal         REAL    NOT NULL,
        line_discount    REAL    NOT NULL DEFAULT 0,
        bill_discount    REAL    NOT NULL DEFAULT 0,
        loyalty_value    REAL    NOT NULL DEFAULT 0,
        taxable_amount   REAL    NOT NULL DEFAULT 0,
        tax_amount       REAL    NOT NULL DEFAULT 0,
        round_off        REAL    NOT NULL DEFAULT 0,
        total            REAL    NOT NULL,
        points_earned    INTEGER NOT NULL DEFAULT 0,
        points_redeemed  INTEGER NOT NULL DEFAULT 0,
        payments_json    TEXT    NOT NULL,
        status           TEXT    NOT NULL DEFAULT 'completed',

        -- 0 = held on this terminal, 1 = accepted by the server
        sync_status      INTEGER NOT NULL DEFAULT 0,
        synced_at        INTEGER,
        sync_attempts    INTEGER NOT NULL DEFAULT 0,
        sync_error       TEXT
      )
    ''');
    // The end-of-day upload selects on this, so it must be indexed.
    await db.execute(
      'CREATE INDEX idx_orders_sync ON ${Tables.orders}(sync_status)',
    );
    await db.execute(
      'CREATE INDEX idx_orders_date ON ${Tables.orders}(business_date)',
    );

    // --------------------------------------------------------- order items
    await db.execute('''
      CREATE TABLE ${Tables.orderItems} (
        id          INTEGER PRIMARY KEY AUTOINCREMENT,
        order_id    TEXT NOT NULL,
        product_id  TEXT NOT NULL,
        name        TEXT NOT NULL,
        barcode     TEXT NOT NULL,
        sku         TEXT NOT NULL,
        unit        TEXT NOT NULL,
        unit_price  REAL NOT NULL,
        quantity    REAL NOT NULL,
        discount    REAL NOT NULL DEFAULT 0,
        gst_rate    REAL NOT NULL DEFAULT 0,
        tax_amount  REAL NOT NULL DEFAULT 0,
        line_total  REAL NOT NULL,
        FOREIGN KEY (order_id) REFERENCES ${Tables.orders}(id)
          ON DELETE CASCADE
      )
    ''');
    await db.execute(
      'CREATE INDEX idx_items_order ON ${Tables.orderItems}(order_id)',
    );

    // --------------------------------------------------------- parked bills
    await db.execute('''
      CREATE TABLE ${Tables.parkedBills} (
        id         TEXT PRIMARY KEY,
        label      TEXT,
        parked_at  INTEGER NOT NULL,
        cart_json  TEXT    NOT NULL
      )
    ''');

    // -------------------------------------------------------------- syncLog
    await db.execute(_createSyncLog);

    // ------------------------------------------------------------- archive
    await db.execute(_createDayArchive);

    // ----------------------------------------------------------------- meta
    await db.execute('''
      CREATE TABLE ${Tables.meta} (
        key   TEXT PRIMARY KEY,
        value TEXT NOT NULL
      )
    ''');
  }
}

/// Moves the schema to v4.
///
/// Adds the payload column the sync log needs to be usable at all, and re-keys
/// the day archive by cashier so a shift report can be scoped to whoever is
/// settling their till. Existing archived rows predate per-cashier attribution,
/// so they are folded under an empty name rather than guessed at.
Future<void> _upgradeToV4(Database db, {required int from}) async {
  // A v1 database had no sync_log payload column; v2+ did not either.
  await db.execute(
    'ALTER TABLE ${Tables.syncLog} ADD COLUMN payload_json TEXT',
  );

  await db.execute('ALTER TABLE ${Tables.dayArchive} RENAME TO _day_archive_v3');
  await db.execute(_createDayArchive);
  await db.execute('''
    INSERT INTO ${Tables.dayArchive} (
      business_date, cashier_name, bill_count, item_count, gross_sales,
      tax_collected, discount_given, round_off, points_issued,
      points_redeemed, payments_json, first_bill_at, last_bill_at,
      synced_bills
    )
    SELECT
      business_date, '', bill_count, item_count, gross_sales,
      tax_collected, discount_given, round_off, points_issued,
      points_redeemed, payments_json, first_bill_at, last_bill_at,
      synced_bills
    FROM _day_archive_v3
  ''');
  await db.execute('DROP TABLE _day_archive_v3');
}

const String _createSyncLog = '''
  CREATE TABLE sync_log (
    id           TEXT PRIMARY KEY,
    type         TEXT    NOT NULL,
    status       TEXT    NOT NULL,
    created_at   INTEGER NOT NULL,
    synced_at    INTEGER,
    summary      TEXT    NOT NULL,
    error        TEXT,
    attempts     INTEGER NOT NULL DEFAULT 0,
    payload_json TEXT
  )
''';

/// Running totals per business day and cashier.
///
/// Synced orders are deleted from the terminal, so their figures are folded in
/// here first — otherwise "Bills Today" would collapse to zero the moment a
/// mid-shift sync ran. Keyed by cashier as well as date, because once the
/// orders are gone this row is the only thing left to settle a till against.
const String _createDayArchive = '''
  CREATE TABLE day_archive (
    business_date   TEXT    NOT NULL,
    cashier_name    TEXT    NOT NULL DEFAULT '',
    bill_count      INTEGER NOT NULL DEFAULT 0,
    item_count      REAL    NOT NULL DEFAULT 0,
    gross_sales     REAL    NOT NULL DEFAULT 0,
    tax_collected   REAL    NOT NULL DEFAULT 0,
    discount_given  REAL    NOT NULL DEFAULT 0,
    round_off       REAL    NOT NULL DEFAULT 0,
    points_issued   INTEGER NOT NULL DEFAULT 0,
    points_redeemed INTEGER NOT NULL DEFAULT 0,
    payments_json   TEXT    NOT NULL DEFAULT '{}',
    first_bill_at   INTEGER,
    last_bill_at    INTEGER,
    synced_bills    INTEGER NOT NULL DEFAULT 0,
    PRIMARY KEY (business_date, cashier_name)
  )
''';

class Tables {
  const Tables._();

  static const String dayArchive = 'day_archive';

  static const String products = 'products';
  static const String customers = 'customers';
  static const String orders = 'orders';
  static const String orderItems = 'order_items';
  static const String parkedBills = 'parked_bills';
  static const String syncLog = 'sync_log';
  static const String meta = 'app_meta';
}

class MetaKeys {
  const MetaKeys._();

  static const String lastImportAt = 'last_import_at';
  static const String catalogueRevision = 'catalogue_revision';
  static const String invoiceSequence = 'invoice_sequence';

  /// Fleet identity. Minted once on first run and never changed — it is what
  /// ties a bill, an MQTT topic and a presence record to one physical till.
  static const String deviceId = 'terminal_device_id';

  /// Short code stamped into invoice numbers, e.g. `T4A9`. Unique per device
  /// so two tills in the same shop cannot mint the same invoice.
  static const String terminalCode = 'terminal_code';

  /// Human label shown in Settings and on the fleet board, e.g. "Counter 2".
  static const String terminalName = 'terminal_name';

  static const String storeId = 'store_id';

  /// Printer chosen in Settings. Stored as the printer's `url`, which is what
  /// `Printing.directPrintPdf` needs to target it without a dialog.
  static const String printerUrl = 'printer_url';
  static const String printerName = 'printer_name';
  static const String autoPrint = 'auto_print';
  static const String openDrawer = 'open_cash_drawer';
}