Bestellungen: eingefrorene Positionen, Lagerreservierung, Zahlungs- und Versandstatus, Teillieferungen, Erstattungen
Installieren
genpm add @core/ordersWas du bekommst
- Quellcode in src/lib/orders/, 10 Dateien. (41,3 kB)
- KI-Regeln in src/lib/orders/AGENTS.md, dazu Regeldateien für die IDE.
- Umgebungsvariablen in .env.example ergänzt: ORDER_LINK_SECRET, ORDER_NUMBER_PREFIX, SITE_URL.
- Löst @core/auth, @core/catalog, @core/contracts, @core/db, @core/email, @core/jobs, @core/money für dich auf.
README
Dieses Paket hat keine README.
Genau das liest deine KI, wenn sie in src/lib/orders arbeitet. Sonst wird ihrem Kontext nichts hinzugefügt.
@core/orders — rules for AI agents
Purpose
Orders after payment: lines frozen at purchase time (name, price, discount), stock reserved in the same transaction
(@core/catalog), sequential order numbers, two independent states — payment (pending → paid → partially_refunded/refunded,
or cancelled) and fulfillment (unfulfilled → partial → fulfilled → delivered) — partial shipments with tracking,
refunds through the registered PaymentProvider, a timeline, customer access by owner session or signed link, and
background events (onOrderEvent) with built-in emails (confirmation, shipped, refund). Payment itself is @core/checkout.
Map
index.ts— public API:createOrder,markPaid,addFulfillment,markDelivered,cancelOrder,refundOrder,getOrder,getOrderForCustomer,onOrderEvent,onOrderPaidTx,registerPaymentProvider,ordersAdminResource,setOrderMessages.orders.ts— logic and theorders.eventjob.emails.ts— default emails.admin.ts— admin.schema.ts— tables.adapters/hono.ts—orderRoutes({ currentUserId }).adapters/next.ts—orderRoute,publicOrder.
Integration
- Env:
ORDER_LINK_SECRET(≥ 32 chars),SITE_URL,EMAIL_FROM, optionalORDER_NUMBER_PREFIX. Migrations as insrc/lib/db/AGENTS.md; the @core/jobs cron must run. - Orders are created by @core/checkout from the paid cart; for manual flows call
createOrder({ … }). - Customer page
/orders/[number]:getOrderForCustomer(number, { userId, token })(404 when null) rendered withpublicOrder. - React to events in a module imported at startup:
onOrderEvent('paid', 'my-crm', async (order) => …). Translate emails withsetOrderMessages((locale) => ({ … })). For bookkeeping that must be atomic with the payment (e.g. counting coupon uses) useonOrderPaidTx(name, async (order, tx) => …): it runs inside the order transaction, must be fast and must not throw for business rules (a throw aborts the order). - Add
ordersAdminResourcetosrc/genpm/admin.ts(permissionsorders:read|update|fulfill|refund). - Verify: create a paid order, ship it from the admin with a tracking URL, the customer gets both emails.
Conventions
- Change states only with these functions; they lock the order row and validate transitions.
- Cancel only unfulfilled orders; after shipping, refund instead (optionally restocking returned lines).
- A paid order that was cancelled is refunded with
refundOrder(up tototal - refundedTotal, norestock: the stock was returned when cancelling); it stayscancelled. - Event handlers must be idempotent; each runs once per event and retries if it fails.
Don't
- Don't delete orders or edit their lines/totals after creation (legal and accounting record).
- Don't expose orders by id or number without the owner check or the signed token.
- Don't mark orders paid from the browser's success redirect; only from the payment webhook or the admin.
# @core/orders — rules for AI agents
## Purpose
Orders after payment: lines frozen at purchase time (name, price, discount), stock reserved in the same transaction
(@core/catalog), sequential order numbers, two independent states — payment (`pending → paid → partially_refunded/refunded`,
or `cancelled`) and fulfillment (`unfulfilled → partial → fulfilled → delivered`) — partial shipments with tracking,
refunds through the registered `PaymentProvider`, a timeline, customer access by owner session or signed link, and
background events (`onOrderEvent`) with built-in emails (confirmation, shipped, refund). Payment itself is @core/checkout.
## Map
- `index.ts` — public API: `createOrder`, `markPaid`, `addFulfillment`, `markDelivered`, `cancelOrder`, `refundOrder`, `getOrder`, `getOrderForCustomer`, `onOrderEvent`, `onOrderPaidTx`, `registerPaymentProvider`, `ordersAdminResource`, `setOrderMessages`.
- `orders.ts` — logic and the `orders.event` job. `emails.ts` — default emails. `admin.ts` — admin. `schema.ts` — tables.
- `adapters/hono.ts` — `orderRoutes({ currentUserId })`. `adapters/next.ts` — `orderRoute`, `publicOrder`.
## Integration
1. Env: `ORDER_LINK_SECRET` (≥ 32 chars), `SITE_URL`, `EMAIL_FROM`, optional `ORDER_NUMBER_PREFIX`. Migrations as in `src/lib/db/AGENTS.md`; the @core/jobs cron must run.
2. Orders are created by @core/checkout from the paid cart; for manual flows call `createOrder({ … })`.
3. Customer page `/orders/[number]`: `getOrderForCustomer(number, { userId, token })` (404 when null) rendered with `publicOrder`.
4. React to events in a module imported at startup: `onOrderEvent('paid', 'my-crm', async (order) => …)`.
Translate emails with `setOrderMessages((locale) => ({ … }))`. For bookkeeping that must be atomic with the payment
(e.g. counting coupon uses) use `onOrderPaidTx(name, async (order, tx) => …)`: it runs inside the order transaction,
must be fast and must not throw for business rules (a throw aborts the order).
5. Add `ordersAdminResource` to `src/genpm/admin.ts` (permissions `orders:read|update|fulfill|refund`).
6. Verify: create a paid order, ship it from the admin with a tracking URL, the customer gets both emails.
## Conventions
- Change states only with these functions; they lock the order row and validate transitions.
- Cancel only unfulfilled orders; after shipping, refund instead (optionally restocking returned lines).
- A paid order that was cancelled is refunded with `refundOrder` (up to `total - refundedTotal`, no `restock`: the
stock was returned when cancelling); it stays `cancelled`.
- Event handlers must be idempotent; each runs once per event and retries if it fails.
## Don't
- Don't delete orders or edit their lines/totals after creation (legal and accounting record).
- Don't expose orders by id or number without the owner check or the signed token.
- Don't mark orders paid from the browser's success redirect; only from the payment webhook or the admin.
Der genaue Baum, der nach .genpmignore eingebunden wird. Gepinnt an
// Emails transaccionales del pedido (confirmación con enlace de seguimiento, enviado, reembolso), enviados una vez
// por evento a través de @core/email. Textos sustituibles por idioma con `setOrderMessages`.
import { getEmailProvider } from '../email/index.ts';
import { format, money } from '../money/index.ts';
import { type OrderDetail, onOrderEvent, orderAccessToken } from './orders.ts';
export type OrderMessages = {
confirmationSubject: (number: string) => string;
confirmationIntro: string;
shippedSubject: (number: string) => string;
shippedIntro: string;
refundSubject: (number: string) => string;
refundIntro: (amount: string) => string;
viewOrder: string;
tracking: string;
total: string;
};
const EN: OrderMessages = {
confirmationSubject: (n) => `Order ${n} confirmed`,
confirmationIntro: 'Thanks for your order. Here is a summary:',
shippedSubject: (n) => `Order ${n} is on its way`,
shippedIntro: 'Good news: your order has shipped.',
refundSubject: (n) => `Refund for order ${n}`,
refundIntro: (a) => `We have refunded ${a} to your original payment method.`,
viewOrder: 'View your order',
tracking: 'Tracking',
total: 'Total',
};
let messagesFor: (locale: string | null) => OrderMessages = () => EN;
export const setOrderMessages = (fn: (locale: string | null) => Partial<OrderMessages>) => {
messagesFor = (l) => ({ ...EN, ...fn(l) });
};
const esc = (s: string) => s.replaceAll('&', '&').replaceAll('<', '<').replaceAll('>', '>').replaceAll('"', '"');
/** URL pública del pedido para el cliente (con token si es invitado). */
export async function orderUrl(o: Pick<OrderDetail, 'id' | 'number'>): Promise<string> {
const site = process.env.SITE_URL;
if (!site) throw new Error('SITE_URL is not set');
return new URL(`/orders/${encodeURIComponent(o.number)}?token=${await orderAccessToken(o)}`, site).toString();
}
async function send(o: OrderDetail, subject: string, paragraphs: string[], extra: Array<[string, string]> = []) {
const from = process.env.EMAIL_FROM;
if (!from) throw new Error('EMAIL_FROM is not set');
const m = messagesFor(o.locale);
const link = await orderUrl(o);
const fmt = (n: number) => format(money(n, o.currency), o.locale ?? 'en');
const rows = o.lines.map((l) => [`${l.name}${l.title ? ` (${l.title})` : ''} × ${l.quantity}`, fmt(l.total)] as [string, string]);
rows.push([m.total, fmt(o.total)]);
const text = [...paragraphs, '', ...rows.map(([a, b]) => `${a}: ${b}`), ...extra.map(([a, b]) => `${a}: ${b}`), '', `${m.viewOrder}: ${link}`].join('\n');
const html = `${paragraphs.map((p) => `<p>${esc(p)}</p>`).join('')}<table>${rows.map(([a, b]) => `<tr><td>${esc(a)}</td><td align="right">${esc(b)}</td></tr>`).join('')}</table>${extra.map(([a, b]) => `<p>${esc(a)}: ${b.startsWith('https://') ? `<a href="${esc(b)}">${esc(b)}</a>` : esc(b)}</p>`).join('')}<p><a href="${esc(link)}">${esc(m.viewOrder)}</a></p>`;
await getEmailProvider().send({ from, to: o.email, subject, text, html });
}
/** Registra los tres emails. Llamado al importar el módulo; `onOrderEvent` con el mismo nombre los sustituye. */
export function registerOrderEmails(): void {
onOrderEvent('paid', 'email.confirmation', (o) => send(o, messagesFor(o.locale).confirmationSubject(o.number), [messagesFor(o.locale).confirmationIntro]));
onOrderEvent('shipped', 'email.shipped', (o, data) => {
const f = o.fulfillments.find((x) => x.id === data.fulfillmentId);
const m = messagesFor(o.locale);
const tracking = f?.trackingUrl ?? f?.trackingNumber;
return send(o, m.shippedSubject(o.number), [m.shippedIntro], tracking ? [[m.tracking, tracking]] : []);
});
onOrderEvent('refunded', 'email.refunded', (o, data) => {
const r = o.refunds.find((x) => x.id === data.refundId);
const m = messagesFor(o.locale);
return send(o, m.refundSubject(o.number), [m.refundIntro(format(money(r?.amount ?? 0, o.currency), o.locale ?? 'en'))]);
});
}
registerOrderEmails();
Dieses Paket deklariert keine MCP-Server.
| Version | Commit | Veröffentlicht | Prüfung |
|---|---|---|---|
| 1.1.0 | f73e6a4 | vor 5 Stunden | Prüfung bestanden |
- genpm
- @core/auth ^1.1.0@core/catalog ^1.0.0@core/contracts ^1.0.0@core/db ^1.0.0@core/email ^1.0.1@core/jobs ^1.0.0@core/money ^1.0.0
- npm
- zod ^4.0.0
- vorgeschlagen
- GenPM schlägt den npm-Befehl vor und führt ihn nur aus, wenn du zustimmst.
- Prüfung
- Prüfung bestanden · 0 Befunde
- Commit
- v1.1.0 → f73e6a4c90491b16d047c7ba7bc8841b9f29d0de · nach dem Abruf verifiziert
- Skripte
- Keine. GenPM führt niemals Paketcode aus.
- Lizenz
- MIT
- Qualität
- 100/100
- Anerkannte Lizenzerfüllt
- AGENTS.md erklärt den Zweckerfüllt
- AGENTS.md enthält Integrationsschritteerfüllt
- AGENTS.md nennt Konventionen oder Verboteerfüllt
- Enthält Testserfüllt
- Sicherheitsscan bestandenerfüllt
- In den letzten 6 Monaten veröffentlichterfüllt
- Verifizierter Herausgebererfüllt
- Zusammenfassung und Schlagwörtererfüllt
- Meldung
- Stimmt etwas nicht?