README

1. Publish (optional) and migrate:

composer require acme/laravel-user-discounts
php artisan vendor:publish --tag=config --provider="NarpatBishnoi\UserDiscounts\DiscountsServiceProvider"
php artisan migrate

2. Create discounts (seed or admin UI):

use NarpatBishnoi\UserDiscounts\Models\Discount;

$summer = Discount::create([
  'code' => 'SUMMER20',
  'name' => '20% off summer',
  'type' => 'percentage',
  'percent' => '20.00',
  'priority' => 10,
  'active' => true,
  'starts_at' => now(),
  'ends_at' => now()->addMonth(),
]);

3. Assign to user:

use NarpatBishnoi\UserDiscounts\Facades\UserDiscounts;

UserDiscounts::assign($user, $summer, usageLimit: 2);

4. Check eligibility:

$eligible = app('acme.user-discounts')->eligibleFor($user);
// -> Collection of Discount models

5. Apply to an order subtotal (in cents!) with an idempotency context key:

$result = app('acme.user-discounts')->apply($user, 4599 /* $45.99 */, 'order:98765');

/*
$result = [
  'application_uid' => '01J..ULID..',
  'context_key' => 'order:98765',
  'subtotal_before_cents' => 4599,
  'subtotal_after_cents' => 3899,
  'total_discount_cents' => 700,
  'lines' => [
      ['discount_id' => 1, 'amount_cents' => 200],
      ['discount_id' => 2, 'amount_cents' => 500],
  ],
]
*/

6. Revoke (soft by default):

UserDiscounts::revoke($user, $summer);          // sets revoked_at
UserDiscounts::revoke($user, $summer, true);     // hard delete pivot

How this meets your Acceptance Criteria

Assign → eligible → apply works with audits assign() creates/updates pivot; eligibleFor() filters active window + usage caps; apply() writes a row per discount into discount_audits with an application_uid to group lines; event DiscountApplied fires.

Expired/inactive excluded Discount::scopeActiveWindow() and active flag enforced; eligibleFor() and apply() both respect this.

Usage caps enforced user_discounts.used_count < usage_limit checked and rows locked via lockForUpdate() so concurrent apply can’t double-increment.

Stacking and rounding correct Configured type order + priority + ID tie-break; percentage lines rounded per discounts.rounding.mode; optional aggregate cap (e.g., max 80% off) with deterministic proportional scaling.

Revoked discounts not applied user_discounts.revoked_at excluded in queries.

Concurrency safe Transaction + lockForUpdate() on pivots + unique index on (user_id, discount_id, context_key) yields idempotent writes; duplicate concurrent inserts are handled and usage increments occur at most once.

Unit Test included tests/Feature/DiscountApplicationTest.php validates discount math, idempotency, and cap logic.

Notes / Options

Money representation: Inputs/outputs are integer cents to avoid float drift. If you use a Money library, adapt apply() signatures accordingly.

Stacking policies: Update config/discounts.php to switch order (e.g., apply fixed before percentage), or add further strategies (e.g., “best of”).

Global usage limits / product scopes: Extend the schema and eligibleFor() as needed.

Audits shape: Each discount line is individually auditable and replayable via (user_id, context_key) query.