@core / discounts

1.0.1 ▾

1.0.1

인증됨MIT

GitHub

할인 코드와 자동 할인: 비율·정액·무료 배송, 상품/카테고리 지정, 사용 횟수와 첫 주문 제한

코드파일 6개컨텍스트약 648토큰검사 통과

약 648토큰→ src/lib/discounts/AGENTS.md→ .cursor/rules/genpm-core-discounts.mdc

이것이 AI가 src/lib/discounts에서 작업할 때 읽는 내용 그대로입니다. 그 외에는 컨텍스트에 아무것도 추가되지 않습니다.

@core/discounts — rules for AI agents

Purpose

Discount codes and automatic discounts for @core/cart: percent, fixed amount or free shipping; optional scope by product or category slugs, minimum order, start/end dates, total and per-customer usage limits, first-order-only and combinability (non-combinable ones compete: the biggest wins). Registers the discounts (100) and free-shipping (250) totals steps and records redemptions inside the transaction that creates/pays the order (onOrderPaidTx of @core/orders), with the discount row locked. Limits count recorded redemptions plus open payments carrying the code (pendingCodeUses of @core/cart, fed by @core/checkout). If a limit was exceeded anyway (the customer already paid), the order is kept, the redemption recorded and a discount_over_limit event is added to the order timeline for review. Tables: discounts, discount_redemptions.

Map

index.ts — public API: upsertDiscount, DiscountInput, discountsStep, freeShippingStep, recordRedemptions, discountsAdminResource.
discounts.ts — validation, application and the redemption handler (registered on import). admin.ts — admin resource.

Integration

Migrations as in src/lib/db/AGENTS.md. Import this module at startup (it registers its steps and handler).
Cart page: a code field calling PUT /api/cart/codes {codes: [code]} (@core/cart); show totals.discounts and any invalid_code issues.
Pass the customer email to computeTotals(cart, { email }) once known so per-customer and first-order limits apply.
Add discountsAdminResource to src/genpm/admin.ts (permissions discounts:read|update).
Verify: create TEN (10 %), apply it, the total drops and each line shows its share.

Conventions

Codes are stored uppercase (A–Z 0–9 _ -); values: percent 1–100, fixed in minor units.
Deleting a discount deactivates it (redemption history stays).
Free-shipping adjustments carry their code (amount 0), so they count towards usage limits.
Check the order timeline (discount_over_limit) when a usage-limited campaign ends.
Prefer automatic discounts for store-wide sales; codes for campaigns.

Don't

Don't show a "was" price or a percentage off that isn't real: in the EU a price reduction must refer to the lowest price of the previous 30 days (Omnibus Directive). Use @core/pricing's price history for compare-at prices.
Don't apply discounts on the client or trust discount amounts sent by the browser.
Don't create fake urgency (countdowns that reset, "only today" when it isn't).

# @core/discounts — rules for AI agents

## Purpose
Discount codes and automatic discounts for @core/cart: percent, fixed amount or free shipping; optional scope by
product or category slugs, minimum order, start/end dates, total and per-customer usage limits, first-order-only and
combinability (non-combinable ones compete: the biggest wins). Registers the `discounts` (100) and `free-shipping`
(250) totals steps and records redemptions inside the transaction that creates/pays the order (`onOrderPaidTx` of
@core/orders), with the discount row locked. Limits count recorded redemptions plus open payments carrying the code
(`pendingCodeUses` of @core/cart, fed by @core/checkout). If a limit was exceeded anyway (the customer already paid),
the order is kept, the redemption recorded and a `discount_over_limit` event is added to the order timeline for review.
Tables: `discounts`, `discount_redemptions`.

## Map
- `index.ts` — public API: `upsertDiscount`, `DiscountInput`, `discountsStep`, `freeShippingStep`, `recordRedemptions`, `discountsAdminResource`.
- `discounts.ts` — validation, application and the redemption handler (registered on import). `admin.ts` — admin resource.

## Integration
1. Migrations as in `src/lib/db/AGENTS.md`. Import this module at startup (it registers its steps and handler).
2. Cart page: a code field calling `PUT /api/cart/codes {codes: [code]}` (@core/cart); show `totals.discounts` and any `invalid_code` issues.
3. Pass the customer email to `computeTotals(cart, { email })` once known so per-customer and first-order limits apply.
4. Add `discountsAdminResource` to `src/genpm/admin.ts` (permissions `discounts:read|update`).
5. Verify: create `TEN` (10 %), apply it, the total drops and each line shows its share.

## Conventions
- Codes are stored uppercase (`A–Z 0–9 _ -`); values: percent 1–100, fixed in minor units.
- Deleting a discount deactivates it (redemption history stays).
- Free-shipping adjustments carry their `code` (amount 0), so they count towards usage limits.
- Check the order timeline (`discount_over_limit`) when a usage-limited campaign ends.
- Prefer automatic discounts for store-wide sales; codes for campaigns.

## Don't
- Don't show a "was" price or a percentage off that isn't real: in the EU a price reduction must refer to the lowest
  price of the previous 30 days (Omnibus Directive). Use @core/pricing's price history for compare-at prices.
- Don't apply discounts on the client or trust discount amounts sent by the browser.
- Don't create fake urgency (countdowns that reset, "only today" when it isn't).

.genpmignore 적용 후 주입될 정확한 트리입니다. 고정 대상:

src/lib/discounts/schema.ts읽기 전용 · 6b23d34

// Tablas de @core/discounts. Las recoge drizzle-kit vía src/lib/db/drizzle.config.ts.
import { boolean, index, integer, jsonb, pgTable, text, timestamp, uniqueIndex } from 'drizzle-orm/pg-core';
import { primaryId, timestamps } from '../db/index.ts';

const ts = (name: string) => timestamp(name, { withTimezone: true, mode: 'date' });

export const discounts = pgTable('discounts', {
  id: primaryId('dsc'),
  /** Código en mayúsculas; null = descuento automático. */
  code: text('code').unique(),
  name: text('name').notNull(),
  type: text('type', { enum: ['percent', 'fixed', 'free_shipping'] }).notNull(),
  /** `percent`: 1–100. `fixed`: unidades menores. `free_shipping`: 0. */
  value: integer('value').notNull().default(0),
  minSubtotal: integer('min_subtotal'),
  /** Solo estos productos/categorías (slugs); vacío = todo el carrito. */
  productSlugs: jsonb('product_slugs').$type<string[]>().notNull().default([]),
  categorySlugs: jsonb('category_slugs').$type<string[]>().notNull().default([]),
  firstOrderOnly: boolean('first_order_only').notNull().default(false),
  usageLimit: integer('usage_limit'),
  perCustomerLimit: integer('per_customer_limit'),
  /** Se puede sumar a otros descuentos combinables; si no, compite y gana el mayor. */
  combinable: boolean('combinable').notNull().default(false),
  startsAt: ts('starts_at'),
  endsAt: ts('ends_at'),
  active: boolean('active').notNull().default(true),
  ...timestamps,
});

export const discountRedemptions = pgTable(
  'discount_redemptions',
  {
    id: primaryId('dre'),
    discountId: text('discount_id')
      .notNull()
      .references(() => discounts.id, { onDelete: 'cascade' }),
    orderId: text('order_id').notNull(),
    email: text('email').notNull(),
    userId: text('user_id'),
    amount: integer('amount').notNull(),
    ...timestamps,
  },
  (t) => [uniqueIndex('discount_redemptions_order_idx').on(t.discountId, t.orderId), index('discount_redemptions_email_idx').on(t.discountId, t.email)],
);

export type Discount = typeof discounts.$inferSelect;