Files
nearle_pos/lib/domain/entities/cart.dart
Suriya 46d354ced1 Build promos for real: engine, storage, editor, and application at the till
The Promo module was a mockup. Three hardcoded rows, a toggle that changed
nothing, and no promo code anywhere in lib/domain or lib/data. A cashier
looking at it would reasonably conclude promotions were running.

Engine (domain/services/promo_engine.dart)
- Five campaign types: percent or flat off the bill, percent off a category
  or a product, and buy-X-get-Y.
- Conditions: date range (inclusive of the closing day), days of the week,
  minimum bill value, and a cap on what a percentage can take off — without
  one an unusually large trolley gives away more than the campaign was costed
  for.
- Stacking is conservative by default. All stackable campaigns apply together;
  of the exclusive ones only the single best does, chosen by what it is worth
  to the shopper with priority breaking ties. Two percentages compounding
  produce a discount nobody signed off, and the shop finds out at the end of
  the month.
- The total is capped at the subtotal, so no combination of campaign, tier and
  manual discount can turn a sale into a payout.
- buy-X-get-Y counts whole groups only, and prices the free unit at what is
  actually being charged — a line already carrying a manual discount must not
  refund more than it took.

Kept out of Cart deliberately: Cart owns arithmetic that must never be wrong,
this owns policy a shop changes weekly.

Storage (schema v6, plus promos_json on orders at v7)
- Campaigns persist locally, because a shop mid-promotion with a dead line
  still has to honour the price on the shelf edge.
- A bill records the campaign name and the amount given, not a link to the
  row. A campaign edited or deleted later cannot change what a past sale
  shows, and a reprinted receipt still names what the shopper was given.
- On read-back the promo amounts are subtracted from the manual discount,
  because bill_discount already contains them. Restoring both at full value
  would discount the bill twice — the same shape as the bug that used to
  overstate synced totals.

At the till
- Every cart mutation re-evaluates, so a promo cannot survive the line that
  earned it being removed.
- A resumed parked bill is re-evaluated rather than restored: a campaign that
  has since ended must not be honoured because the bill was parked while it
  was running.
- Campaigns are named individually on the billing panel and the printed
  receipt, so a shopper who came in for an advertised offer can see it applied.

Editor
- Full CRUD, admin-only, with validation for the cases that would save happily
  and then silently never fire — a targeted campaign with no target, a
  percentage over 100, an end date before the start.

Tests: 199 -> 210. Covers each campaign type, the eligibility conditions, the
stacking rules, the impossible-to-go-negative guarantee, GST recomputation
against the reduced total, round-tripping, and the double-count guard.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-01 13:36:50 +05:30

277 lines
8.7 KiB
Dart

import 'package:equatable/equatable.dart';
import '../../core/constants/app_constants.dart';
import '../../core/utils/extensions.dart';
import 'customer.dart';
import 'product.dart';
import 'promo.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,
this.appliedPromos = const [],
});
final List<CartLine> lines;
final Customer? customer;
final Discount billDiscount;
final int pointsRedeemed;
final String? note;
/// Campaigns that fired on this bill.
///
/// Resolved by `PromoEngine` and handed in, rather than computed here: which
/// campaigns exist is policy that changes weekly, and Cart owns arithmetic
/// that must never be wrong. Stored as amounts so a bill read back years
/// later shows what was actually given, not what today's rules would give.
final List<AppliedPromo> appliedPromos;
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);
/// What the automatic campaigns took off.
double get promoDiscountAmount =>
appliedPromos.fold(0.0, (sum, p) => sum + p.amount).asMoney;
/// All bill-level reductions combined.
///
/// Clamped to the subtotal so no combination of tier, campaign and manual
/// discount can drive a bill below zero and turn a sale into a payout.
double get billDiscountTotal =>
(membershipDiscountAmount + manualBillDiscountAmount +
promoDiscountAmount)
.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,
List<AppliedPromo>? appliedPromos,
}) {
return Cart(
lines: lines ?? this.lines,
customer: clearCustomer ? null : (customer ?? this.customer),
billDiscount: billDiscount ?? this.billDiscount,
pointsRedeemed: pointsRedeemed ?? this.pointsRedeemed,
note: note ?? this.note,
appliedPromos: appliedPromos ?? this.appliedPromos,
);
}
@override
List<Object?> get props =>
[lines, customer, billDiscount, pointsRedeemed, note, appliedPromos];
}