@porulle/plugin-pos-restaurant 0.1.0

package/src/hooks/modifier-validation.ts

@@ -0,0 +1,60 @@
+/**
+ * Modifier Validation Hook — cart.beforeAddItem
+ *
+ * Validates modifier selections when items are added to a POS cart.
+ * URY has no modifier validation (modifiers are just flat item links).
+ * This hook enforces:
+ * - Required modifier groups must have at least minSelect selections
+ * - No group may exceed maxSelect selections
+ * - Unavailable (86'd) options are rejected
+ * - Price adjustments are summed into cart line item metadata
+ */
+
+import type { ModifierService } from "../services/modifier-service.js";
+
+export function buildModifierValidationHook(getService: () => ModifierService) {
+  return {
+    key: "cart.beforeAddItem",
+    handler: async (...args: unknown[]) => {
+      const hook = args[0] as {
+        data: {
+          entityId?: string;
+          metadata?: Record<string, unknown>;
+          [key: string]: unknown;
+        };
+        context: {
+          actor?: { organizationId?: string | null } | null;
+          [key: string]: unknown;
+        };
+      };
+
+      const { data, context } = hook;
+      const modifiers = data.metadata?.modifiers as Array<{
+        groupId: string;
+        optionIds: string[];
+      }> | undefined;
+
+      // If no modifiers provided, skip validation (non-restaurant items)
+      if (!modifiers || modifiers.length === 0) return data;
+      if (!data.entityId) return data;
+
+      const { resolveOrgId } = await import("@porulle/core");
+      const orgId = resolveOrgId(context.actor);
+      const service = getService();
+
+      const result = await service.validateModifiers(orgId, data.entityId, modifiers);
+      if (!result.ok) {
+        throw new Error(result.error);
+      }
+
+      // Inject validated modifiers and price adjustment into metadata
+      data.metadata = {
+        ...data.metadata,
+        validatedModifiers: result.value.validatedModifiers,
+        modifierPriceAdjustment: result.value.totalAdjustment,
+      };
+
+      return data;
+    },
+  };
+}

package/src/hooks/table-lifecycle.ts

@@ -0,0 +1,50 @@
+/**
+ * Table Lifecycle Hooks
+ *
+ * URY equivalent: table_status_delete() in ury_pos_invoice.py.
+ * URY clears occupied=0 on POS Invoice delete/cancel/submit.
+ *
+ * We hook into checkout.afterCreate to update table status when a
+ * POS transaction completes, and pos transaction void to clear tables.
+ */
+
+import { eq } from "@porulle/core/drizzle";
+import { posTableAssignments, posTables } from "../schema.js";
+import type { Db } from "../types.js";
+
+export function buildTableClearOnCompleteHook(getDb: () => Db) {
+  return {
+    key: "checkout.afterCreate",
+    handler: async (...args: unknown[]) => {
+      const hook = args[0] as {
+        result: { id: string; metadata?: Record<string, unknown> | null };
+        context: { [key: string]: unknown };
+      };
+
+      const metadata = hook.result?.metadata;
+      const posTransactionId = (metadata as Record<string, unknown>)?.posTransactionId as string | undefined;
+      if (!posTransactionId) return;
+
+      const db = getDb();
+
+      // Find table assignments for this transaction
+      const assignments = await db
+        .select()
+        .from(posTableAssignments)
+        .where(eq(posTableAssignments.transactionId, posTransactionId));
+
+      // Set tables to "cleaning" (staff will set to "available" after bussing)
+      for (const assignment of assignments) {
+        await db
+          .update(posTables)
+          .set({ status: "cleaning", updatedAt: new Date() })
+          .where(eq(posTables.id, assignment.tableId));
+      }
+
+      // Remove assignments
+      await db
+        .delete(posTableAssignments)
+        .where(eq(posTableAssignments.transactionId, posTransactionId));
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,218 @@
+/**
+ * POS Restaurant Extension — RFC-024a (Complete Feature Set)
+ *
+ * Extends @porulle/plugin-pos with all restaurant-specific features
+ * informed by URY Restaurant ERP (ury-erp/ury) production patterns.
+ *
+ * Feature coverage (maps to URY FEATURES.md):
+ *
+ * POS & Billing:
+ * - Pre-billing checklists (compliance enforcement)
+ * - Table service, QSR, and takeaway (order types)
+ * - Multi-cashier handling (via Tier 0 terminals)
+ * - Shift opening/closing with cash reconciliation (via Tier 0)
+ *
+ * Menu & Recipe Management:
+ * - Item modifiers (groups, options, required/optional, price adjustments)
+ * - Recipe/BOM mapping for COGS calculation
+ * - Combos and item bundles
+ * - Menu availability per outlet (86'd items)
+ *
+ * Table Order Management:
+ * - Table management with zones, floor plan, status lifecycle
+ * - Server section assignment
+ * - Table/captain transfer
+ * - Customer favorites (top ordered items)
+ *
+ * Kitchen Display & KOT Management:
+ * - Multi-station KDS with item-group routing
+ * - 4-state ticket flow (pending -> preparing -> ready -> served)
+ * - Item-level completion tracking (persistent, not localStorage)
+ * - Course sequencing with priority-based ordering
+ * - Delay and modification tracking
+ * - KOT reprint support
+ *
+ * Operational Red Flags & Alerts:
+ * - Delayed order alerts
+ * - KOT not started alerts
+ * - Prolonged table occupancy alerts
+ * - Excessive cancellation tracking
+ * - Configurable thresholds per alert type
+ *
+ * Reports & Analytics:
+ * - Daily Profit & Loss (gross sales, COGS, expenses, net profit)
+ * - Station performance (prep time, throughput)
+ * - Course-wise performance
+ * - Staff/captain performance
+ * - P&L expense breakdown
+ */
+
+import { defineCommercePlugin } from "@porulle/core";
+import {
+  posModifierGroups,
+  posModifierOptions,
+  posTables,
+  posTableAssignments,
+  kdsStations,
+  kdsStationItemGroups,
+  kdsTickets,
+  kdsTicketItems,
+  posChecklists,
+  posChecklistItems,
+  posChecklistCompletions,
+  posRestaurantAlerts,
+  posAlertConfig,
+  posRecipes,
+  posRecipeIngredients,
+  posCombos,
+  posComboGroups,
+  posComboItems,
+  posMenuAvailability,
+  posDailyPnl,
+  posPnlExpenses,
+  posCustomerFavorites,
+} from "./schema.js";
+import { ModifierService } from "./services/modifier-service.js";
+import { TableService } from "./services/table-service.js";
+import { KDSService } from "./services/kds-service.js";
+import { ChecklistService } from "./services/checklist-service.js";
+import { AlertService } from "./services/alert-service.js";
+import { RecipeService } from "./services/recipe-service.js";
+import { RestaurantAnalyticsService } from "./services/analytics-service.js";
+import { buildModifierRoutes, buildModifierOptionRoutes } from "./routes/modifiers.js";
+import { buildTableRoutes } from "./routes/tables.js";
+import { buildKDSRoutes } from "./routes/kds.js";
+import {
+  buildChecklistRoutes,
+  buildAlertRoutes,
+  buildRecipeRoutes,
+  buildAnalyticsRoutes,
+} from "./routes/operations.js";
+import { buildModifierValidationHook } from "./hooks/modifier-validation.js";
+import { buildTableClearOnCompleteHook } from "./hooks/table-lifecycle.js";
+import type { POSRestaurantPluginOptions, Db } from "./types.js";
+import { DEFAULT_RESTAURANT_OPTIONS } from "./types.js";
+
+export type { POSRestaurantPluginOptions, Db } from "./types.js";
+export { ModifierService } from "./services/modifier-service.js";
+export { TableService } from "./services/table-service.js";
+export { KDSService } from "./services/kds-service.js";
+export { ChecklistService } from "./services/checklist-service.js";
+export { AlertService } from "./services/alert-service.js";
+export { RecipeService } from "./services/recipe-service.js";
+export { RestaurantAnalyticsService } from "./services/analytics-service.js";
+export { RecipeDeductionService } from "./services/recipe-deduction-service.js";
+
+export function posRestaurantPlugin(userOptions: POSRestaurantPluginOptions = {}) {
+  const options: Required<POSRestaurantPluginOptions> = {
+    ...DEFAULT_RESTAURANT_OPTIONS,
+    ...userOptions,
+  };
+
+  const dbRef: { current: Db | null } = { current: null };
+  const modifierServiceRef: { current: ModifierService | null } = { current: null };
+
+  return defineCommercePlugin({
+    id: "pos-restaurant",
+    version: "1.0.0",
+    requires: ["pos"],
+
+    permissions: [
+      {
+        scope: "pos-restaurant:admin",
+        description: "Create/edit modifier groups, tables, KDS stations, checklists, recipes, alert config, analytics, floor plan layout.",
+      },
+    ],
+
+    schema: () => ({
+      // Core restaurant tables
+      posModifierGroups,
+      posModifierOptions,
+      posTables,
+      posTableAssignments,
+      kdsStations,
+      kdsStationItemGroups,
+      kdsTickets,
+      kdsTicketItems,
+      // Operational features
+      posChecklists,
+      posChecklistItems,
+      posChecklistCompletions,
+      posRestaurantAlerts,
+      posAlertConfig,
+      // Menu & recipe management
+      posRecipes,
+      posRecipeIngredients,
+      posCombos,
+      posComboGroups,
+      posComboItems,
+      posMenuAvailability,
+      // Analytics
+      posDailyPnl,
+      posPnlExpenses,
+      posCustomerFavorites,
+    }),
+
+    hooks: () => {
+      const hooks = [];
+
+      if (options.enableModifiers) {
+        hooks.push(buildModifierValidationHook(() => {
+          if (!modifierServiceRef.current) throw new Error("ModifierService not initialized");
+          return modifierServiceRef.current;
+        }));
+      }
+
+      hooks.push(buildTableClearOnCompleteHook(() => {
+        if (!dbRef.current) throw new Error("Restaurant plugin DB not initialized");
+        return dbRef.current;
+      }));
+
+      return hooks;
+    },
+
+    routes: (ctx) => {
+      const db = ctx.database.db;
+      if (!db) return [];
+
+      dbRef.current = db;
+
+      // Initialize all services
+      const modifierService = new ModifierService(db);
+      const tableService = new TableService(db);
+      const kdsService = new KDSService(db);
+      const checklistService = new ChecklistService(db);
+      const alertService = new AlertService(db);
+      const recipeService = new RecipeService(db);
+      const analyticsService = new RestaurantAnalyticsService(db);
+
+      modifierServiceRef.current = modifierService;
+
+      const routes = [
+        // Table management (always enabled)
+        ...buildTableRoutes(tableService, ctx),
+        // Checklists (always enabled)
+        ...buildChecklistRoutes(checklistService, ctx),
+        // Alerts (always enabled)
+        ...buildAlertRoutes(alertService, ctx),
+        // Recipes/BOM (always enabled)
+        ...buildRecipeRoutes(recipeService, ctx),
+        // Analytics (always enabled)
+        ...buildAnalyticsRoutes(analyticsService, ctx),
+      ];
+
+      if (options.enableModifiers) {
+        routes.push(
+          ...buildModifierRoutes(modifierService, ctx),
+          ...buildModifierOptionRoutes(modifierService, ctx),
+        );
+      }
+
+      if (options.enableKDS) {
+        routes.push(...buildKDSRoutes(kdsService, ctx));
+      }
+
+      return routes;
+    },
+  });
+}

package/src/routes/kds.ts

@@ -0,0 +1,121 @@
+import { router } from "@porulle/core";
+import { z } from "@hono/zod-openapi";
+import type { KDSService } from "../services/kds-service.js";
+import type { PluginRouteRegistration } from "@porulle/core";
+
+export function buildKDSRoutes(
+  service: KDSService,
+  ctx: { services?: Record<string, unknown>; database?: { db: unknown } },
+): PluginRouteRegistration[] {
+  const r = router("POS Restaurant KDS", "/pos/restaurant/kds", ctx);
+
+  // ─── Stations ──────────────────────────────────────────────────────
+
+  r.post("/stations")
+    .summary("Create KDS station")
+    .permission("pos-restaurant:admin")
+    .input(z.object({
+      name: z.string().min(1).max(100),
+      alertThresholdMinutes: z.number().int().min(1).optional(),
+      metadata: z.record(z.string(), z.unknown()).optional(),
+    }))
+    .handler(async ({ input, orgId }) => {
+      const body = input as { name: string; alertThresholdMinutes?: number; metadata?: Record<string, unknown> };
+      const result = await service.createStation(orgId, body);
+      if (!result.ok) throw new Error(result.error);
+      return result.value;
+    });
+
+  r.get("/stations")
+    .summary("List KDS stations")
+    .permission("pos:operate")
+    .handler(async ({ orgId }) => {
+      const result = await service.listStations(orgId);
+      if (!result.ok) throw new Error(result.error);
+      return result.value;
+    });
+
+  r.patch("/stations/{id}")
+    .summary("Update KDS station")
+    .permission("pos-restaurant:admin")
+    .input(z.object({
+      name: z.string().min(1).max(100).optional(),
+      isActive: z.boolean().optional(),
+      alertThresholdMinutes: z.number().int().min(1).optional(),
+    }))
+    .handler(async ({ params, input, orgId }) => {
+      const body = input as { name?: string; isActive?: boolean; alertThresholdMinutes?: number };
+      const result = await service.updateStation(orgId, params.id!, body);
+      if (!result.ok) throw new Error(result.error);
+      return result.value;
+    });
+
+  r.post("/stations/{id}/item-groups")
+    .summary("Add item group to station")
+    .permission("pos-restaurant:admin")
+    .input(z.object({ itemGroup: z.string().min(1) }))
+    .handler(async ({ params, input }) => {
+      const body = input as { itemGroup: string };
+      const result = await service.addItemGroup(params.id!, body.itemGroup);
+      if (!result.ok) throw new Error(result.error);
+      return result.value;
+    });
+
+  r.delete("/stations/{id}/item-groups/{group}")
+    .summary("Remove item group from station")
+    .permission("pos-restaurant:admin")
+    .handler(async ({ params }) => {
+      const result = await service.removeItemGroup(params.id!, params.group!);
+      if (!result.ok) throw new Error(result.error);
+      return result.value;
+    });
+
+  // ─── Tickets ───────────────────────────────────────────────────────
+
+  r.get("/stations/{id}/tickets")
+    .summary("List pending tickets for station")
+    .permission("pos:operate")
+    .handler(async ({ params, orgId }) => {
+      const result = await service.listPendingTickets(orgId, params.id!);
+      if (!result.ok) throw new Error(result.error);
+      return result.value;
+    });
+
+  r.post("/tickets/{id}/start")
+    .summary("Mark ticket as preparing")
+    .permission("pos:operate")
+    .handler(async ({ params }) => {
+      const result = await service.startTicket(params.id!);
+      if (!result.ok) throw new Error(result.error);
+      return result.value;
+    });
+
+  r.post("/tickets/{id}/ready")
+    .summary("Mark ticket as ready")
+    .permission("pos:operate")
+    .handler(async ({ params }) => {
+      const result = await service.readyTicket(params.id!);
+      if (!result.ok) throw new Error(result.error);
+      return result.value;
+    });
+
+  r.post("/tickets/{id}/serve")
+    .summary("Mark ticket as served")
+    .permission("pos:operate")
+    .handler(async ({ params }) => {
+      const result = await service.serveTicket(params.id!);
+      if (!result.ok) throw new Error(result.error);
+      return result.value;
+    });
+
+  r.post("/tickets/{id}/items/{itemId}/done")
+    .summary("Mark ticket item as done")
+    .permission("pos:operate")
+    .handler(async ({ params }) => {
+      const result = await service.markItemDone(params.id!, params.itemId!);
+      if (!result.ok) throw new Error(result.error);
+      return result.value;
+    });
+
+  return r.routes();
+}

package/src/routes/modifiers.ts

@@ -0,0 +1,129 @@
+import { router } from "@porulle/core";
+import { z } from "@hono/zod-openapi";
+import type { ModifierService } from "../services/modifier-service.js";
+import type { PluginRouteRegistration } from "@porulle/core";
+
+export function buildModifierRoutes(
+  service: ModifierService,
+  ctx: { services?: Record<string, unknown>; database?: { db: unknown } },
+): PluginRouteRegistration[] {
+  const r = router("POS Restaurant Modifiers", "/pos/restaurant/modifier-groups", ctx);
+
+  r.post("/")
+    .summary("Create modifier group")
+    .permission("pos-restaurant:admin")
+    .input(z.object({
+      name: z.string().min(1).max(200),
+      entityId: z.string().uuid().optional(),
+      itemGroup: z.string().optional(),
+      isRequired: z.boolean().optional(),
+      minSelect: z.number().int().min(0).optional(),
+      maxSelect: z.number().int().min(1).optional(),
+      sortOrder: z.number().int().optional(),
+    }))
+    .handler(async ({ input, orgId }) => {
+      const body = input as { name: string; entityId?: string; itemGroup?: string; isRequired?: boolean; minSelect?: number; maxSelect?: number; sortOrder?: number };
+      const result = await service.createGroup(orgId, body);
+      if (!result.ok) throw new Error(result.error);
+      return result.value;
+    });
+
+  r.get("/")
+    .summary("List modifier groups")
+    .permission("pos:operate")
+    .query(z.object({ entityId: z.string().uuid().optional() }))
+    .handler(async ({ query, orgId }) => {
+      const q = query as { entityId?: string };
+      const result = await service.listGroups(orgId, q.entityId);
+      if (!result.ok) throw new Error(result.error);
+      return result.value;
+    });
+
+  r.get("/{id}")
+    .summary("Get modifier group with options")
+    .permission("pos:operate")
+    .handler(async ({ params, orgId }) => {
+      const result = await service.getGroupWithOptions(orgId, params.id!);
+      if (!result.ok) throw new Error(result.error);
+      return result.value;
+    });
+
+  r.patch("/{id}")
+    .summary("Update modifier group")
+    .permission("pos-restaurant:admin")
+    .input(z.object({
+      name: z.string().min(1).max(200).optional(),
+      isRequired: z.boolean().optional(),
+      minSelect: z.number().int().min(0).optional(),
+      maxSelect: z.number().int().min(1).optional(),
+      sortOrder: z.number().int().optional(),
+    }))
+    .handler(async ({ params, input, orgId }) => {
+      const body = input as { name?: string; isRequired?: boolean; minSelect?: number; maxSelect?: number; sortOrder?: number };
+      const result = await service.updateGroup(orgId, params.id!, body);
+      if (!result.ok) throw new Error(result.error);
+      return result.value;
+    });
+
+  r.delete("/{id}")
+    .summary("Delete modifier group")
+    .permission("pos-restaurant:admin")
+    .handler(async ({ params, orgId }) => {
+      const result = await service.deleteGroup(orgId, params.id!);
+      if (!result.ok) throw new Error(result.error);
+      return result.value;
+    });
+
+  r.post("/{id}/options")
+    .summary("Add modifier option")
+    .permission("pos-restaurant:admin")
+    .input(z.object({
+      name: z.string().min(1).max(200),
+      priceAdjustment: z.number().int().optional(),
+      isDefault: z.boolean().optional(),
+      sortOrder: z.number().int().optional(),
+    }))
+    .handler(async ({ params, input }) => {
+      const body = input as { name: string; priceAdjustment?: number; isDefault?: boolean; sortOrder?: number };
+      const result = await service.addOption(params.id!, body);
+      if (!result.ok) throw new Error(result.error);
+      return result.value;
+    });
+
+  return r.routes();
+}
+
+export function buildModifierOptionRoutes(
+  service: ModifierService,
+  ctx: { services?: Record<string, unknown>; database?: { db: unknown } },
+): PluginRouteRegistration[] {
+  const r = router("POS Restaurant Modifier Options", "/pos/restaurant/modifier-options", ctx);
+
+  r.patch("/{id}")
+    .summary("Update modifier option")
+    .permission("pos-restaurant:admin")
+    .input(z.object({
+      name: z.string().min(1).max(200).optional(),
+      priceAdjustment: z.number().int().optional(),
+      isDefault: z.boolean().optional(),
+      isAvailable: z.boolean().optional(),
+      sortOrder: z.number().int().optional(),
+    }))
+    .handler(async ({ params, input }) => {
+      const body = input as { name?: string; priceAdjustment?: number; isDefault?: boolean; isAvailable?: boolean; sortOrder?: number };
+      const result = await service.updateOption(params.id!, body);
+      if (!result.ok) throw new Error(result.error);
+      return result.value;
+    });
+
+  r.delete("/{id}")
+    .summary("Delete modifier option")
+    .permission("pos-restaurant:admin")
+    .handler(async ({ params }) => {
+      const result = await service.deleteOption(params.id!);
+      if (!result.ok) throw new Error(result.error);
+      return result.value;
+    });
+
+  return r.routes();
+}