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>
186 lines
5.9 KiB
Dart
186 lines
5.9 KiB
Dart
import 'package:sqflite/sqflite.dart';
|
|
import 'package:uuid/uuid.dart';
|
|
|
|
import '../../domain/entities/promo.dart';
|
|
import 'app_database.dart';
|
|
|
|
/// Raised when a campaign would be saved in a state the till cannot apply.
|
|
class PromoException implements Exception {
|
|
const PromoException(this.message);
|
|
|
|
final String message;
|
|
|
|
@override
|
|
String toString() => message;
|
|
}
|
|
|
|
/// Stores campaigns on the terminal.
|
|
///
|
|
/// Local like everything else the till needs: a shop mid-promotion with a dead
|
|
/// line still has to honour the price on the shelf edge.
|
|
class PromoDao {
|
|
const PromoDao(this._db);
|
|
|
|
final Database _db;
|
|
|
|
static const _uuid = Uuid();
|
|
|
|
Future<List<Promo>> all({bool activeOnly = false}) async {
|
|
final rows = await _db.query(
|
|
Tables.promos,
|
|
where: activeOnly ? 'is_active = 1' : null,
|
|
orderBy: 'priority ASC, created_at ASC',
|
|
);
|
|
return rows.map(_fromRow).toList();
|
|
}
|
|
|
|
Future<Promo?> findById(String id) async {
|
|
final rows = await _db.query(
|
|
Tables.promos,
|
|
where: 'id = ?',
|
|
whereArgs: [id],
|
|
limit: 1,
|
|
);
|
|
return rows.isEmpty ? null : _fromRow(rows.first);
|
|
}
|
|
|
|
/// Inserts or updates. Returns the stored campaign, with its id.
|
|
Future<Promo> save(Promo promo) async {
|
|
_validate(promo);
|
|
|
|
final id = promo.id.isEmpty ? _uuid.v4() : promo.id;
|
|
final now = DateTime.now().millisecondsSinceEpoch;
|
|
final existing = await findById(id);
|
|
|
|
await _db.insert(
|
|
Tables.promos,
|
|
{
|
|
'id': id,
|
|
'name': promo.name.trim(),
|
|
'type': promo.type.name,
|
|
'value': promo.value,
|
|
'target_id': promo.targetId,
|
|
'target_label': promo.targetLabel,
|
|
'buy_quantity': promo.buyQuantity,
|
|
'free_quantity': promo.freeQuantity,
|
|
'min_bill_value': promo.minBillValue,
|
|
'max_discount': promo.maxDiscount,
|
|
'valid_from': promo.validFrom?.millisecondsSinceEpoch,
|
|
'valid_to': promo.validTo?.millisecondsSinceEpoch,
|
|
'days_of_week': (promo.daysOfWeek.toList()..sort()).join(','),
|
|
'stackable': promo.stackable ? 1 : 0,
|
|
'priority': promo.priority,
|
|
'is_active': promo.isActive ? 1 : 0,
|
|
// Preserved on update so the list keeps a stable order.
|
|
'created_at': existing == null ? now : await _createdAt(id) ?? now,
|
|
'updated_at': now,
|
|
},
|
|
conflictAlgorithm: ConflictAlgorithm.replace,
|
|
);
|
|
|
|
// Read back rather than echoing the input, so the caller gets exactly what
|
|
// the database holds — including the id minted for a new campaign.
|
|
return (await findById(id))!;
|
|
}
|
|
|
|
Future<int?> _createdAt(String id) async {
|
|
final rows = await _db.query(
|
|
Tables.promos,
|
|
columns: ['created_at'],
|
|
where: 'id = ?',
|
|
whereArgs: [id],
|
|
limit: 1,
|
|
);
|
|
return rows.isEmpty ? null : rows.first['created_at'] as int?;
|
|
}
|
|
|
|
Future<void> setActive(String id, {required bool active}) async {
|
|
await _db.update(
|
|
Tables.promos,
|
|
{
|
|
'is_active': active ? 1 : 0,
|
|
'updated_at': DateTime.now().millisecondsSinceEpoch,
|
|
},
|
|
where: 'id = ?',
|
|
whereArgs: [id],
|
|
);
|
|
}
|
|
|
|
/// Hard delete. Unlike staff, nothing already recorded points at a promo row
|
|
/// — a bill stores the amount it was given, not a reference to the campaign,
|
|
/// so deleting one cannot change a past total.
|
|
Future<void> delete(String id) async {
|
|
await _db.delete(Tables.promos, where: 'id = ?', whereArgs: [id]);
|
|
}
|
|
|
|
// ------------------------------------------------------------- Internals
|
|
static void _validate(Promo promo) {
|
|
if (promo.name.trim().isEmpty) {
|
|
throw const PromoException('A campaign needs a name.');
|
|
}
|
|
|
|
if (promo.type.needsTarget &&
|
|
(promo.targetId == null || promo.targetId!.isEmpty)) {
|
|
throw const PromoException(
|
|
'This campaign needs a product or category to apply to.',
|
|
);
|
|
}
|
|
|
|
if (promo.type == PromoType.buyXGetY) {
|
|
if (promo.buyQuantity < 1 || promo.freeQuantity < 1) {
|
|
throw const PromoException(
|
|
'Buy and free quantities must both be at least one.',
|
|
);
|
|
}
|
|
} else if (promo.value <= 0) {
|
|
throw const PromoException('A campaign must give something away.');
|
|
}
|
|
|
|
if (promo.type.isPercentage && promo.value > 100) {
|
|
// Over 100% is a refund with extra steps.
|
|
throw const PromoException('A percentage cannot exceed 100.');
|
|
}
|
|
|
|
final from = promo.validFrom;
|
|
final to = promo.validTo;
|
|
if (from != null && to != null && to.isBefore(from)) {
|
|
throw const PromoException('The end date is before the start date.');
|
|
}
|
|
|
|
if (promo.daysOfWeek.any((d) => d < 1 || d > 7)) {
|
|
throw const PromoException('Days of the week must be 1 (Mon) to 7 (Sun).');
|
|
}
|
|
}
|
|
|
|
static Promo _fromRow(Map<String, Object?> row) {
|
|
final days = (row['days_of_week'] as String? ?? '')
|
|
.split(',')
|
|
.where((s) => s.isNotEmpty)
|
|
.map(int.parse)
|
|
.toSet();
|
|
|
|
return Promo(
|
|
id: row['id']! as String,
|
|
name: row['name']! as String,
|
|
type: PromoType.values.byName(row['type']! as String),
|
|
value: (row['value'] as num? ?? 0).toDouble(),
|
|
targetId: row['target_id'] as String?,
|
|
targetLabel: row['target_label'] as String?,
|
|
buyQuantity: (row['buy_quantity'] as int?) ?? 0,
|
|
freeQuantity: (row['free_quantity'] as int?) ?? 0,
|
|
minBillValue: (row['min_bill_value'] as num? ?? 0).toDouble(),
|
|
maxDiscount: (row['max_discount'] as num?)?.toDouble(),
|
|
validFrom: row['valid_from'] == null
|
|
? null
|
|
: DateTime.fromMillisecondsSinceEpoch(row['valid_from']! as int),
|
|
validTo: row['valid_to'] == null
|
|
? null
|
|
: DateTime.fromMillisecondsSinceEpoch(row['valid_to']! as int),
|
|
daysOfWeek: days,
|
|
stackable: (row['stackable'] as int? ?? 0) == 1,
|
|
priority: (row['priority'] as int?) ?? 100,
|
|
isActive: (row['is_active'] as int? ?? 1) == 1,
|
|
);
|
|
}
|
|
}
|