Files
nearle_pos/lib/domain/entities/cart.dart
Suriya af3933092f Fix billing data integrity, sale atomicity and stock safety
Bills were persisted correctly but read back wrong. The read path rebuilt a
cart from its lines alone, dropping bill-level discounts and loyalty, so every
figure derived from a stored bill was overstated: the upload payload, the day
archive and the shift report. A discounted 529 bill read back as 620.

Money and data integrity
- order_dao: restore bill_discount and points_redeemed when rebuilding a cart;
  keep the reconstruction tier-less so the membership discount is not applied
  twice. Trust the recorded total and points via SaleTransaction.storedTotal.
- checkout_sale + order_dao.commitSale: write the bill, its stock movement and
  the loyalty update in one transaction. Previously a failure part-way through
  left a persisted bill the cashier believed had failed, inviting a duplicate.
- checkout_sale: re-check every line against live stock. A parked bill resumed
  after its stock was sold passed validation and oversold.
- catalogue_dao: allocate the invoice sequence in one transaction; the previous
  read-modify-write could hand two sales the same number and fail UNIQUE.
- local_store: replay unsynced sales after a catalogue import, so a mid-shift
  re-import cannot restore stock that has already been sold.
- payment_controller: stamp the signed-in operator on the bill instead of the
  hardcoded seed session, and pass the terminal id through.
- cart: reconcile per-slab GST against the bill total so the parts sum to the
  whole on a tax invoice.

Sync and reporting
- sync_repository: drain unsynced bills in a loop rather than silently capping
  at one page; stop on rejection so rejected rows cannot loop forever.
- sync_log_dao (new): persist the sync history to the sync_log table, which the
  schema already defined but nothing used. It was in memory, so the only record
  that bills had been uploaded died at restart.
- Scope shift reports by cashier. day_archive is re-keyed to
  (business_date, cashier_name) so a till stays settleable after its bills are
  uploaded and deleted. Schema v4 with a migration that carries v3 rows across.

Input and UI
- barcode_service: consume machine-paced keystrokes so a scan cannot also land
  in the focused field, and raise the bar to 60ms/char while a text field has
  focus so typing a mobile number is not read as a scan. Clock and focus check
  injected so the behaviour is testable.
- primary_button: make the label flexible; label plus trailing total overflowed
  the Charge button by up to 131px.
- app_router: redirect instead of null-casting when the receipt route is
  entered without its transaction.
- customer_repository: reduce the search query to digits so a punctuated mobile
  number matches.

Cleanup
- Remove TransactionRepository.save, CustomerRepository.recordSale and
  OrderDao.insertOrder, all superseded by commitSale.
- dart fix across the tree; 251 analyzer issues down to 3 info-level.

Tests: 23 passing / 15 failing -> 90 passing. Fixed the two defects that broke
the existing suite (containsAll type argument, reset() needing a catalogue) and
deleted the leftover template test. Added coverage for the order round trip,
the day archive after a real sync, stock safety, checkout atomicity, the v3->v4
migration, scanner-versus-human input, and an app-level smoke test that renders
every module.

Note: bills already uploaded with a discount went up overstated. This stops it
happening again but does not correct historical server data.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-07-31 18:34:10 +05:30

257 lines
7.9 KiB
Dart

import 'package:equatable/equatable.dart';
import '../../core/constants/app_constants.dart';
import '../../core/utils/extensions.dart';
import 'customer.dart';
import 'product.dart';
/// How a discount value should be interpreted.
enum DiscountType { none, percentage, flat }
/// A discount applied to a single line or to the whole bill.
class Discount extends Equatable {
const Discount({this.type = DiscountType.none, this.value = 0, this.reason});
final DiscountType type;
final double value;
final String? reason;
static const Discount none = Discount();
bool get isActive => type != DiscountType.none && value > 0;
/// Resolves the discount to rupees against [base], never exceeding it.
double amountOn(double base) {
if (!isActive || base <= 0) return 0;
final raw = switch (type) {
DiscountType.percentage => base * (value / 100),
DiscountType.flat => value,
DiscountType.none => 0.0,
};
return raw.clamp(0, base).toDouble().asMoney;
}
String get label => switch (type) {
DiscountType.percentage => '${value.toStringAsFixed(0)}% off',
DiscountType.flat => 'Flat ${AppConstants.currencySymbol}$value off',
DiscountType.none => 'No discount',
};
@override
List<Object?> get props => [type, value, reason];
}
/// One product line inside the cart.
class CartLine extends Equatable {
const CartLine({
required this.product,
required this.quantity,
this.discount = Discount.none,
this.addedAt,
});
final Product product;
final double quantity;
final Discount discount;
final DateTime? addedAt;
String get id => product.id;
/// Line value before discount, GST inclusive.
double get grossAmount => (product.price * quantity).asMoney;
double get discountAmount => discount.amountOn(grossAmount);
/// Payable for this line after discount, GST inclusive.
double get payable => (grossAmount - discountAmount).asMoney;
/// Taxable value inside [payable].
double get taxableValue => (payable / (1 + product.gstRate)).asMoney;
/// GST rupees inside [payable].
double get taxAmount => (payable - taxableValue).asMoney;
double get cgst => (taxAmount / 2).asMoney;
double get sgst => (taxAmount / 2).asMoney;
double get mrpSavings => product.hasDiscount
? (product.savings * quantity).asMoney
: 0;
bool get exceedsStock => quantity > product.stock;
CartLine copyWith({double? quantity, Discount? discount}) => CartLine(
product: product,
quantity: quantity ?? this.quantity,
discount: discount ?? this.discount,
addedAt: addedAt,
);
@override
List<Object?> get props => [product.id, quantity, discount];
}
/// The live bill. Immutable — every mutation returns a new instance, which
/// keeps the Riverpod notifier predictable and makes undo trivial.
class Cart extends Equatable {
const Cart({
this.lines = const [],
this.customer,
this.billDiscount = Discount.none,
this.pointsRedeemed = 0,
this.note,
});
final List<CartLine> lines;
final Customer? customer;
final Discount billDiscount;
final int pointsRedeemed;
final String? note;
static const Cart empty = Cart();
bool get isEmpty => lines.isEmpty;
bool get isNotEmpty => lines.isNotEmpty;
bool get isWalkIn => customer == null;
int get lineCount => lines.length;
double get totalQuantity =>
lines.fold(0.0, (sum, l) => sum + l.quantity);
/// Sum of line values before any bill-level discount, GST inclusive.
double get subtotal =>
lines.fold(0.0, (sum, l) => sum + l.payable).asMoney;
/// Discounts applied at the individual line level.
double get lineDiscountTotal =>
lines.fold(0.0, (sum, l) => sum + l.discountAmount).asMoney;
/// Automatic discount earned through the customer's membership tier.
Discount get membershipDiscount {
final rate = customer?.tier.discountRate ?? 0;
if (rate <= 0) return Discount.none;
return Discount(
type: DiscountType.percentage,
value: rate * 100,
reason: '${customer!.tier.label} member',
);
}
double get membershipDiscountAmount =>
membershipDiscount.amountOn(subtotal);
double get manualBillDiscountAmount => billDiscount.amountOn(subtotal);
/// All bill-level reductions combined.
double get billDiscountTotal =>
(membershipDiscountAmount + manualBillDiscountAmount)
.clamp(0, subtotal)
.toDouble()
.asMoney;
double get loyaltyRedemptionValue =>
(pointsRedeemed * AppConstants.loyaltyPointValue).asMoney;
/// Payable after every discount, GST inclusive, before round-off.
double get netAmount {
final v = subtotal - billDiscountTotal - loyaltyRedemptionValue;
return v.clamp(0, double.infinity).toDouble().asMoney;
}
/// Proportion of the bill remaining after bill-level reductions. Used to
/// spread those reductions fairly across lines when apportioning GST.
double get _billFactor => subtotal <= 0 ? 1 : netAmount / subtotal;
/// GST payable across the bill, after apportioning bill-level discounts.
double get taxAmount =>
lines.fold(0.0, (sum, l) => sum + l.taxAmount * _billFactor).asMoney;
double get cgst => (taxAmount / 2).asMoney;
double get sgst => (taxAmount / 2).asMoney;
/// Taxable value across the bill.
double get taxableAmount => (netAmount - taxAmount).asMoney;
/// GST broken out per slab — required on a compliant tax invoice.
///
/// The slabs are reconciled against [taxAmount] before being returned.
/// Rounding each slab on its own leaves the parts summing to a paisa either
/// side of the total printed on the same bill, which a tax invoice cannot
/// show; the residue is absorbed by the largest slab.
Map<double, double> get taxBreakdown {
final raw = <double, double>{};
for (final line in lines) {
final rate = line.product.gstRate;
raw[rate] = (raw[rate] ?? 0) + line.taxAmount * _billFactor;
}
if (raw.isEmpty) return const {};
final map = {
for (final e in raw.entries) e.key: e.value.asMoney,
};
final drift =
(taxAmount - map.values.fold(0.0, (a, b) => a + b)).asMoney;
if (drift != 0) {
final largest =
raw.entries.reduce((a, b) => a.value >= b.value ? a : b).key;
map[largest] = (map[largest]! + drift).asMoney;
}
return map;
}
double get grandTotal => netAmount.roundedToRupee;
/// The paise adjustment shown as "Round Off" on the bill.
double get roundOff => (grandTotal - netAmount).asMoney;
double get mrpSavingsTotal =>
lines.fold(0.0, (sum, l) => sum + l.mrpSavings).asMoney;
/// Everything the shopper saved on this bill.
double get totalSavings =>
(mrpSavingsTotal + lineDiscountTotal + billDiscountTotal).asMoney;
/// Points this sale will earn. Walk-in customers earn nothing.
int get pointsEarned {
if (customer == null) return 0;
return (grandTotal / AppConstants.loyaltyRupeesPerPoint).floor();
}
int get maxRedeemablePoints {
final c = customer;
if (c == null) return 0;
final byBalance = c.loyaltyPoints;
final byBill =
(subtotal - billDiscountTotal) ~/ AppConstants.loyaltyPointValue;
return byBalance < byBill ? byBalance : byBill;
}
CartLine? lineFor(String productId) =>
lines.firstWhereOrNull((l) => l.product.id == productId);
bool contains(String productId) => lineFor(productId) != null;
Cart copyWith({
List<CartLine>? lines,
Customer? customer,
bool clearCustomer = false,
Discount? billDiscount,
int? pointsRedeemed,
String? note,
}) {
return Cart(
lines: lines ?? this.lines,
customer: clearCustomer ? null : (customer ?? this.customer),
billDiscount: billDiscount ?? this.billDiscount,
pointsRedeemed: pointsRedeemed ?? this.pointsRedeemed,
note: note ?? this.note,
);
}
@override
List<Object?> get props =>
[lines, customer, billDiscount, pointsRedeemed, note];
}