feat(checks): require payment method on settlement (#26) (#32)

Author: vekexasia

backend/drizzle/0019_check_payment.sql

@@ -0,0 +1,2 @@
+ALTER TABLE checks ADD COLUMN payment_method TEXT;
+ALTER TABLE checks ADD COLUMN note TEXT;

backend/src/__tests__/checks.test.ts

@@ -173,24 +173,32 @@ describe('check patch (discount/adjustments)', () => {
 });
 
 describe('check settle / void', () => {
-  it('settle closes the session and marks the check settled', async () => {
+  it('settle requires and stores payment metadata, then closes the session', async () => {
     const db = checksDb();
     const sessionId = openSession(db);
     seedOrder(db, sessionId, 'Bruschetta', 750, 1);
     const id = ((await (await createCheck(db, sessionId)).json()) as { id: string }).id;
-    const res = await testRequest(`/admin/checks/${id}/settle`, { method: 'POST', headers: await adminHeaders(), env: adminEnv(db) });
+
+    const missing = await testRequest(`/admin/checks/${id}/settle`, { method: 'POST', headers: await adminHeaders(), env: adminEnv(db) });
+    expect(missing.status).toBe(400);
+
+    const res = await testRequest(`/admin/checks/${id}/settle`, { method: 'POST', body: { paymentMethod: 'card', note: 'Visa ending 42' }, headers: await adminHeaders(), env: adminEnv(db) });
     expect(res.status).toBe(200);
-    expect((await res.json() as { status: string; settledAt: number | null }).status).toBe('settled');
+    const body = await res.json() as { status: string; settledAt: number | null; paymentMethod: string; note: string | null };
+    expect(body.status).toBe('settled');
+    expect(body.paymentMethod).toBe('card');
+    expect(body.note).toBe('Visa ending 42');
     expect((db.raw.prepare('SELECT closed_at FROM table_sessions WHERE id = ?').get(sessionId) as { closed_at: number | null }).closed_at).not.toBeNull();
+    expect((db.raw.prepare('SELECT payment_method, note FROM checks WHERE id = ?').get(id) as { payment_method: string; note: string })).toEqual({ payment_method: 'card', note: 'Visa ending 42' });
   });
 
   it('refuses settling a non-open check (409)', async () => {
     const db = checksDb();
     const sessionId = openSession(db);
     seedOrder(db, sessionId, 'Bruschetta', 750, 1);
     const id = ((await (await createCheck(db, sessionId)).json()) as { id: string }).id;
-    await testRequest(`/admin/checks/${id}/settle`, { method: 'POST', headers: await adminHeaders(), env: adminEnv(db) });
-    const again = await testRequest(`/admin/checks/${id}/settle`, { method: 'POST', headers: await adminHeaders(), env: adminEnv(db) });
+    await testRequest(`/admin/checks/${id}/settle`, { method: 'POST', body: { paymentMethod: 'cash' }, headers: await adminHeaders(), env: adminEnv(db) });
+    const again = await testRequest(`/admin/checks/${id}/settle`, { method: 'POST', body: { paymentMethod: 'cash' }, headers: await adminHeaders(), env: adminEnv(db) });
     expect(again.status).toBe(409);
   });
 

backend/src/db/schema.ts

@@ -466,6 +466,8 @@ export const checks = sqliteTable(
     adjustments: jsonColumn<{ label: string; amount: number }[]>('adjustments').notNull().default([]),
     createdAt: integer('created_at').notNull().$defaultFn(() => Date.now()),
     settledAt: integer('settled_at'),
+    paymentMethod: text('payment_method'),
+    note: text('note'),
     voidedAt: integer('voided_at'),
   },
   (table) => ({

backend/src/routes/admin-checks.ts

@@ -5,7 +5,7 @@ import { requireAdmin } from '../middleware/admin-guard';
 import { requireDb } from '../middleware/db';
 import { parseBody } from '../lib/validate';
 import { z } from 'zod';
-import { UpdateCheckBodySchema, computeCheckTotals, type CheckDTO, type CheckLine } from '@menu/schemas';
+import { UpdateCheckBodySchema, SettleCheckBodySchema, computeCheckTotals, type CheckDTO, type CheckLine } from '@menu/schemas';
 import * as schema from '../db/schema';
 import type { AppBindings } from '../types';
 import type { DbInstance } from '../db';
@@ -41,6 +41,8 @@ function toCheckDTO(row: CheckRow): CheckDTO {
     total,
     createdAt: row.createdAt,
     settledAt: row.settledAt,
+    paymentMethod: row.paymentMethod as CheckDTO['paymentMethod'],
+    note: row.note,
     voidedAt: row.voidedAt,
   };
 }
@@ -262,9 +264,11 @@ admin.post('/checks/:id/settle', ...base, async (c) => {
   if (!row) return c.json({ error: 'Not Found' }, 404);
   if (row.status !== 'open') return c.json({ error: 'not_open' }, 409);
 
+  const body = await parseBody(c, SettleCheckBodySchema);
+  if (body instanceof Response) return body;
   const now = Date.now();
   await db.batch([
-    db.update(schema.checks).set({ status: 'settled', settledAt: now }).where(eq(schema.checks.id, id)),
+    db.update(schema.checks).set({ status: 'settled', settledAt: now, paymentMethod: body.paymentMethod, note: body.note ?? null }).where(eq(schema.checks.id, id)),
     db.update(schema.tableSessions).set({ closedAt: now }).where(eq(schema.tableSessions.id, row.tableSessionId)),
   ]);
   const [updated] = await db.select().from(schema.checks).where(eq(schema.checks.id, id)).limit(1);

packages/schemas/src/checks.ts

@@ -9,6 +9,7 @@ import type { StaffOrder, TableShape } from './staff.js';
 // the client and server agree.
 
 export type CheckStatus = 'open' | 'settled' | 'voided';
+export type PaymentMethod = 'cash' | 'card' | 'other';
 
 export interface CheckLine {
   name: string;
@@ -39,6 +40,8 @@ export interface CheckDTO {
   total: number;
   createdAt: number;
   settledAt: number | null;
+  paymentMethod: PaymentMethod | null;
+  note: string | null;
   voidedAt: number | null;
 }
 
@@ -81,6 +84,12 @@ export const UpdateCheckBodySchema = z.object({
 });
 export type UpdateCheckBody = z.infer<typeof UpdateCheckBodySchema>;
 
+export const SettleCheckBodySchema = z.object({
+  paymentMethod: z.enum(['cash', 'card', 'other']),
+  note: z.string().trim().max(120).optional(),
+});
+export type SettleCheckBody = z.infer<typeof SettleCheckBodySchema>;
+
 // ── Admin table detail (#15 follow-up) ──────────────────────────────
 
 export interface AdminTableSessionOrders {

web/e2e/admin/admin-checks-real.spec.ts

@@ -74,12 +74,15 @@ test.describe.serial("Checks (conto) — real backend", () => {
 
     // Settle (confirm) → session closes, table free, settled in history.
     await page.getByTestId("settle").click();
+    await expect(page.getByTestId("settle-confirm")).toBeDisabled();
+    await page.getByTestId("payment-method-card").click();
     const settleRes = page.waitForResponse((res) => res.url().includes("/settle") && res.request().method() === "POST" && res.status() < 300);
     await page.getByTestId("settle-confirm").click();
     await settleRes;
 
     await expect(page.getByTestId("table-free")).toBeVisible();
     await expect(page.getByText(/Pagato|Paid/).first()).toBeVisible();
+    await expect(page.getByText(/Carta|Card/).first()).toBeVisible();
   });
   test("admin adds searchable items from the table page", async ({ page, request }) => {
     await seedSessionWithOrder(request);

web/messages/de.json

@@ -662,7 +662,12 @@
     "tableDetail.noAvailableItems": "Keine verfügbaren Artikel gefunden.",
     "tableDetail.submitItems": "Artikel hinzufügen",
     "tableDetail.checkOpenAddItemsBlocked": "Begleiche oder storniere die offene Rechnung, bevor du weitere Artikel hinzufügst.",
-    "tables.checkOpen": "Rechnung"
+    "tables.checkOpen": "Rechnung",
+    "tableDetail.settlementTitle": "Zahlung",
+    "tableDetail.paymentMethod.cash": "Bar",
+    "tableDetail.paymentMethod.card": "Karte",
+    "tableDetail.paymentMethod.other": "Andere",
+    "tableDetail.paymentNote": "Zahlungsnotiz (optional)"
   },
   "outOfStock": "AUSVERKAUFT",
   "staff": {

web/messages/en.json

@@ -662,7 +662,12 @@
     "tableDetail.noAvailableItems": "No available items found.",
     "tableDetail.submitItems": "Add items",
     "tableDetail.checkOpenAddItemsBlocked": "Settle or void the open check before adding more items.",
-    "tables.checkOpen": "Check"
+    "tables.checkOpen": "Check",
+    "tableDetail.settlementTitle": "Payment",
+    "tableDetail.paymentMethod.cash": "Cash",
+    "tableDetail.paymentMethod.card": "Card",
+    "tableDetail.paymentMethod.other": "Other",
+    "tableDetail.paymentNote": "Payment note (optional)"
   },
   "outOfStock": "OUT OF STOCK",
   "staff": {

web/messages/es.json

@@ -662,7 +662,12 @@
     "tableDetail.noAvailableItems": "No se encontraron artículos disponibles.",
     "tableDetail.submitItems": "Añadir artículos",
     "tableDetail.checkOpenAddItemsBlocked": "Cobra o anula la cuenta abierta antes de añadir más artículos.",
-    "tables.checkOpen": "Cuenta"
+    "tables.checkOpen": "Cuenta",
+    "tableDetail.settlementTitle": "Pago",
+    "tableDetail.paymentMethod.cash": "Efectivo",
+    "tableDetail.paymentMethod.card": "Tarjeta",
+    "tableDetail.paymentMethod.other": "Otro",
+    "tableDetail.paymentNote": "Nota de pago (opcional)"
   },
   "outOfStock": "AGOTADO",
   "staff": {

web/messages/fr.json

@@ -662,7 +662,12 @@
     "tableDetail.noAvailableItems": "Aucun article disponible trouvé.",
     "tableDetail.submitItems": "Ajouter des articles",
     "tableDetail.checkOpenAddItemsBlocked": "Encaissez ou annulez l’addition ouverte avant d’ajouter d’autres articles.",
-    "tables.checkOpen": "Note"
+    "tables.checkOpen": "Note",
+    "tableDetail.settlementTitle": "Paiement",
+    "tableDetail.paymentMethod.cash": "Espèces",
+    "tableDetail.paymentMethod.card": "Carte",
+    "tableDetail.paymentMethod.other": "Autre",
+    "tableDetail.paymentNote": "Note de paiement (facultatif)"
   },
   "outOfStock": "ÉPUISÉ",
   "staff": {