nearle_daily/nearle_pos
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Build promos for real: engine, storage, editor, and application at the till

Browse Source 
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>
This commit is contained in:
Suriya
2026-08-01 13:36:50 +05:30
parent fdd90f28d9
commit 46d354ced1
18 changed files with 2239 additions and 199 deletions
Download Patch File Download Diff File Expand all files Collapse all files

462
lib/presentation/modules/screens/promos_view.dart
View File

@@ -1,202 +1,304 @@
import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import '../../../app/providers.dart';
import '../../../core/theme/app_colors.dart';
import '../../../core/theme/app_dimens.dart';
import '../../../core/utils/formatters.dart';
import '../../../domain/entities/promo.dart';
import '../../../domain/entities/store_account.dart';
import '../../auth/providers/auth_controller.dart';
import '../../../core/widgets/empty_state.dart';
import '../widgets/module_widgets.dart';
import '../widgets/promo_editor_dialog.dart';
/// Discount rules and campaigns.
class PromosView extends StatefulWidget {
///
/// This was a mockup: three hardcoded rows with a toggle that changed nothing,
/// and no promo code anywhere in the domain or data layers. A cashier looking
/// at it would reasonably conclude promotions were running. They were not.
class PromosView extends ConsumerWidget {
const PromosView({super.key});
@override
State<PromosView> createState() => _PromosViewState();
}
Widget build(BuildContext context, WidgetRef ref) {
final promosAsync = ref.watch(promosProvider);
final isAdmin = ref.watch(currentUserProvider)?.role == StaffRole.admin;
class _PromosViewState extends State<PromosView> {
final Set<String> _enabled = {'WEEKEND10', 'DAIRY5', 'FESTIVE'};
static const _campaigns = [
(
'WEEKEND10',
'Weekend Saver',
'10% off bills above ₹500',
'Sat–Sun',
412,
AppColors.primary,
),
(
'DAIRY5',
'Dairy Days',
'5% off all dairy products',
'Ends 31 Aug',
286,
AppColors.info,
),
(
'FESTIVE',
'Festive Bonus',
'Double loyalty points',
'Ends 15 Sep',
178,
AppColors.tierGold,
),
(
'NEWCUST',
'First Purchase',
'₹50 off the first bill',
'Always on',
94,
AppColors.success,
),
];
@override
Widget build(BuildContext context) {
return ModulePage(
children: [
Wrap(
spacing: AppSpacing.lg,
runSpacing: AppSpacing.lg,
children: [
StatTile(
label: 'Active Campaigns',
value: '${_enabled.length}',
icon: Icons.campaign_rounded,
caption: 'of ${_campaigns.length} configured',
),
const StatTile(
label: 'Redemptions',
value: '970',
icon: Icons.confirmation_number_rounded,
color: AppColors.info,
caption: 'this month',
),
const StatTile(
label: 'Discount Given',
value: '₹48,240',
icon: Icons.local_offer_rounded,
color: AppColors.warning,
caption: '2.6% of sales',
),
const StatTile(
label: 'Incremental Sales',
value: '₹2.14L',
icon: Icons.trending_up_rounded,
color: AppColors.success,
delta: '+18%',
caption: 'attributed',
),
],
),
const SizedBox(height: AppSpacing.lg),
PanelCard(
title: 'Campaigns',
subtitle: 'Toggle a rule to apply it at the till immediately',
action: FilledButton.icon(
onPressed: () {},
icon: const Icon(Icons.add_rounded, size: 18),
label: const Text('New campaign'),
style: FilledButton.styleFrom(
backgroundColor: AppColors.primary,
minimumSize: const Size(0, 40),
),
promosAsync.when(
loading: () => const Padding(
padding: EdgeInsets.all(AppSpacing.xxl),
child: Center(child: CircularProgressIndicator()),
),
child: Column(
mainAxisSize: MainAxisSize.min,
error: (e, _) => Text('Could not load campaigns: $e'),
data: (promos) => Column(
children: [
for (final c in _campaigns)
Container(
margin: const EdgeInsets.only(bottom: AppSpacing.sm),
padding: const EdgeInsets.all(AppSpacing.md),
decoration: BoxDecoration(
color: AppColors.surfaceAlt,
borderRadius: AppRadius.brMd,
border: Border.all(color: AppColors.border),
),
// Wrap prevents collision when the panel is narrow.
child: Wrap(
alignment: WrapAlignment.spaceBetween,
crossAxisAlignment: WrapCrossAlignment.center,
spacing: AppSpacing.md,
runSpacing: AppSpacing.sm,
children: [
SizedBox(
width: 320,
child: Row(
children: [
Container(
width: 38,
height: 38,
decoration: BoxDecoration(
color: c.$6.withValues(alpha: 0.12),
borderRadius: AppRadius.brSm,
),
child: Icon(Icons.sell_rounded,
size: 18, color: c.$6,),
),
const SizedBox(width: AppSpacing.md),
Expanded(
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
mainAxisSize: MainAxisSize.min,
children: [
Text(
c.$2,
overflow: TextOverflow.ellipsis,
style: const TextStyle(
fontSize: 14,
fontWeight: FontWeight.w600,
),
),
Text(
c.$3,
overflow: TextOverflow.ellipsis,
style: const TextStyle(
fontSize: 12.5,
color: AppColors.textSecondary,
),
),
],
),
),
],
),
),
Row(
mainAxisSize: MainAxisSize.min,
children: [
TagChip(c.$1, color: c.$6),
const SizedBox(width: AppSpacing.sm),
TagChip(c.$4, color: AppColors.textSecondary),
const SizedBox(width: AppSpacing.sm),
Text(
'${c.$5} used',
style: const TextStyle(
fontSize: 12,
color: AppColors.textTertiary,
),
),
const SizedBox(width: AppSpacing.sm),
Switch(
value: _enabled.contains(c.$1),
onChanged: (v) => setState(() {
if (v) {
_enabled.add(c.$1);
} else {
_enabled.remove(c.$1);
}
}),
),
],
),
],
),
),
_summary(promos),
const SizedBox(height: AppSpacing.lg),
_campaignList(context, ref, promos, isAdmin: isAdmin),
],
),
),
],
);
}
Widget _summary(List<Promo> promos) {
final live = promos.where((p) => p.isLiveAt(DateTime.now())).length;
final scheduled = promos
.where((p) =>
p.isActive &&
p.validFrom != null &&
p.validFrom!.isAfter(DateTime.now()),)
.length;
return Row(
children: [
Expanded(
child: StatTile(
label: 'Running now',
value: '$live',
icon: Icons.play_circle_outline_rounded,
color: AppColors.success,
),
),
const SizedBox(width: AppSpacing.md),
Expanded(
child: StatTile(
label: 'Scheduled',
value: '$scheduled',
icon: Icons.schedule_rounded,
color: AppColors.info,
),
),
const SizedBox(width: AppSpacing.md),
Expanded(
child: StatTile(
label: 'Paused',
value: '${promos.where((p) => !p.isActive).length}',
icon: Icons.pause_circle_outline_rounded,
color: AppColors.textTertiary,
),
),
],
);
}
Widget _campaignList(
BuildContext context,
WidgetRef ref,
List<Promo> promos, {
required bool isAdmin,
}) {
return PanelCard(
title: 'Campaigns',
subtitle: promos.isEmpty
? 'Nothing running. Add a campaign and the till applies it '
'automatically.'
: 'Applied automatically at the till, in priority order',
action: isAdmin
? FilledButton.icon(
onPressed: () => showPromoEditor(context),
icon: const Icon(Icons.add_rounded, size: 18),
label: const Text('New campaign'),
style: FilledButton.styleFrom(
backgroundColor: AppColors.primary,
minimumSize: const Size(0, 40),
),
)
: null,
child: promos.isEmpty
? const EmptyState(
title: 'No campaigns yet',
message: 'A campaign here is applied to every bill that '
'qualifies, without the cashier doing anything.',
emoji: '🏷️',
compact: true,
)
: Column(
mainAxisSize: MainAxisSize.min,
children: [
for (final promo in promos)
_PromoRow(promo: promo, isAdmin: isAdmin),
],
),
);
}
}
class _PromoRow extends ConsumerWidget {
const _PromoRow({required this.promo, required this.isAdmin});
final Promo promo;
final bool isAdmin;
@override
Widget build(BuildContext context, WidgetRef ref) {
final live = promo.isLiveAt(DateTime.now());
return Container(
margin: const EdgeInsets.only(bottom: AppSpacing.sm),
padding: const EdgeInsets.all(AppSpacing.md),
decoration: BoxDecoration(
color: AppColors.surfaceAlt,
borderRadius: AppRadius.brMd,
border: Border.all(color: AppColors.border),
),
// Wrap prevents collision when the panel is narrow.
child: Wrap(
alignment: WrapAlignment.spaceBetween,
crossAxisAlignment: WrapCrossAlignment.center,
spacing: AppSpacing.md,
runSpacing: AppSpacing.sm,
children: [
SizedBox(
width: 360,
child: Row(
children: [
Container(
width: 38,
height: 38,
decoration: BoxDecoration(
color: (live ? AppColors.success : AppColors.textTertiary)
.withValues(alpha: 0.12),
borderRadius: AppRadius.brSm,
),
child: Icon(
Icons.sell_rounded,
size: 18,
color: live ? AppColors.success : AppColors.textTertiary,
),
),
const SizedBox(width: AppSpacing.md),
Expanded(
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
mainAxisSize: MainAxisSize.min,
children: [
Text(
promo.name,
overflow: TextOverflow.ellipsis,
style: const TextStyle(fontWeight: FontWeight.w700),
),
Text(
promo.summary,
overflow: TextOverflow.ellipsis,
style: const TextStyle(
fontSize: 12.5,
color: AppColors.textSecondary,
),
),
],
),
),
],
),
),
Wrap(
crossAxisAlignment: WrapCrossAlignment.center,
spacing: AppSpacing.sm,
children: [
if (promo.stackable)
const TagChip('Stacks', color: AppColors.info),
// The distinction a shop actually needs: switched on, but out of
// its date range or wrong day, is not the same as switched off.
if (promo.isActive && !live)
const TagChip('Not today', color: AppColors.warning),
Text(
_window(promo),
style: const TextStyle(
fontSize: 12,
color: AppColors.textTertiary,
),
),
if (isAdmin) ...[
Switch(
value: promo.isActive,
onChanged: (v) async {
await ref
.read(localStoreProvider)
.promos
.setActive(promo.id, active: v);
ref
..invalidate(promosProvider)
..invalidate(activePromosProvider);
},
),
IconButton(
tooltip: 'Edit',
icon: const Icon(Icons.edit_outlined, size: 17),
onPressed: () => showPromoEditor(context, existing: promo),
),
IconButton(
tooltip: 'Delete',
icon: const Icon(Icons.delete_outline_rounded, size: 17),
color: AppColors.danger,
onPressed: () => _confirmDelete(context, ref),
),
],
],
),
],
),
);
}
String _window(Promo promo) {
final from = promo.validFrom;
final to = promo.validTo;
if (from == null && to == null) {
return promo.daysOfWeek.isEmpty ? 'Always' : _days(promo.daysOfWeek);
}
final range = [
if (from != null) 'from ${Formatters.date(from)}',
if (to != null) 'to ${Formatters.date(to)}',
].join(' ');
return promo.daysOfWeek.isEmpty
? range
: '$range · ${_days(promo.daysOfWeek)}';
}
static String _days(Set<int> days) {
const names = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'];
final sorted = days.toList()..sort();
return sorted.map((d) => names[d - 1]).join(', ');
}
Future<void> _confirmDelete(BuildContext context, WidgetRef ref) async {
final confirmed = await showDialog<bool>(
context: context,
builder: (dialogContext) => AlertDialog(
title: Text('Delete "${promo.name}"?'),
content: const Text(
'Bills already rung keep the discount they were given — a bill '
'stores the amount, not a link to the campaign. Only future sales '
'are affected.',
),
actions: [
TextButton(
onPressed: () => Navigator.of(dialogContext).pop(false),
child: const Text('Cancel'),
),
TextButton(
onPressed: () => Navigator.of(dialogContext).pop(true),
style: TextButton.styleFrom(foregroundColor: AppColors.danger),
child: const Text('Delete'),
),
],
),
);
if (confirmed != true) return;
await ref.read(localStoreProvider).promos.delete(promo.id);
ref
..invalidate(promosProvider)
..invalidate(activePromosProvider);
}
}