Staff Operations Implementation Plan

convex/
├── schema.ts                    # MODIFY — add tables, menuItems, orders, orderItems
└── functions/
    ├── tables.ts               # CREATE — table CRUD
    ├── menu.ts                 # CREATE — menu item CRUD
    └── orders.ts               # CREATE — order lifecycle mutations

apps/frontend/
├── app/
│   ├── pos/
│   │   ├── kitchen/
│   │   │   └── page.tsx        # CREATE — KDS kanban board
│   │   ├── reception/
│   │   │   └── page.tsx        # CREATE — table list + check-in
│   │   └── staff/
│   │       └── page.tsx        # CREATE — POS for taking orders
│   └── table/
│       └── page.tsx             # CREATE — guest PWA (mobile-first ordering, nuqs URL state)
├── components/
│   ├── pos/
│   │   ├── kitchen-kanban.tsx  # CREATE — kanban columns + drag
│   │   ├── table-list.tsx      # CREATE — table status list
│   │   └── menu-browser.tsx     # CREATE — menu grid for staff ordering
│   └── table/
│       ├── menu-grid.tsx        # CREATE — guest menu browsing
│       ├── cart.tsx             # CREATE — guest cart
│       └── order-status.tsx     # CREATE — live order status tracker
└── lib/
    └── convex/
        └── provider.tsx        # MODIFY — ensure ConvexProvider wraps POS

cat convex/schema.ts

tables: defineTable({
  name: v.string(), // Table number only (e.g., "T01")
  capacity: v.number(),
  status: v.union(v.literal("ACTIVE"), v.literal("INACTIVE")),
  createdAt: v.number(),
  updatedAt: v.number(),
})
  .index("by_status", ["status"]),
 
menuItems: defineTable({
  name: v.string(),
  description: v.string(),
  price: v.number(),
  imageUrl: v.optional(v.string()),
  category: v.union(
    v.literal("APPETIZER"), v.literal("MAIN"), v.literal("DESSERT"),
    v.literal("DRINK"), v.literal("COCKTAIL"), v.literal("WINE"),
    v.literal("BEER"), v.literal("SOFT_DRINK"), v.literal("OTHER")
  ),
  station: v.union(v.literal("KITCHEN"), v.literal("BAR")),
  available: v.boolean(),
  sortOrder: v.number(),
  createdAt: v.number(),
  updatedAt: v.number(),
})
  .index("by_category", ["category"])
  .index("by_station", ["station"])
  .index("by_available", ["available"]),
 
orders: defineTable({
  tableId: v.id("tables"),
  reservationId: v.optional(v.id("reservations")),
  status: v.union(
    v.literal("OPEN"), v.literal("SUBMITTED"),
    v.literal("COMPLETED"), v.literal("CANCELLED")
  ),
  totalAmount: v.number(),
  notes: v.optional(v.string()),
  createdAt: v.number(),
  updatedAt: v.number(),
})
  .index("by_table", ["tableId"])
  .index("by_reservation", ["reservationId"])
  .index("by_status", ["status"]),
 
orderItems: defineTable({
  orderId: v.id("orders"),
  menuItemId: v.id("menuItems"),
  quantity: v.number(),
  unitPrice: v.number(),
  status: v.union(
    v.literal("PENDING"), v.literal("SUBMITTED"),
    v.literal("PREPARING"), v.literal("READY"),
    v.literal("SERVED"), v.literal("CANCELLED")
  ),
  station: v.union(v.literal("KITCHEN"), v.literal("BAR")),
  notes: v.optional(v.string()),
  isComp: v.boolean().default(false),
  compSource: v.optional(v.union(
    v.literal("SPIN"), v.literal("PHOTO_WIN"), v.literal("GOOGLE_REVIEW")
  )),
  createdAt: v.number(),
  updatedAt: v.number(),
})
  .index("by_order", ["orderId"])
  .index("by_station_status", ["station", "status"])
  .index("by_status", ["status"]),

// Add to existing reservations table definition
tableId: v.optional(v.id("tables")),
checkedInAt: v.optional(v.number()),

git add convex/schema.ts
git commit -m "feat(pos): add tables, menuItems, orders, orderItems to schema"

// convex/functions/tables.ts
import { query, mutation } from "../_generated/server";
import { v } from "convex/values";
import { Id } from "../_generated/dataModel";
import { consola } from "consola";
 
// Inline role check — staffMutation/adminMutation not available yet
// Convex QueryBuilder types are inferred automatically
async function requireStaffOrAdmin(ctx: {
  auth: { getUserIdentity: () => Promise<{ email?: string } | null> };
  db: { query: (table: string) => { withIndex: (name: string, fn: (q: { eq: (field: string, value: string) => { first: () => Promise<unknown> } }) => { first: () => Promise<unknown> } }) => { first: () => Promise<unknown> } } };
}): Promise<{ _id: Id<"users">; role: string; email: string }> {
  const identity = await ctx.auth.getUserIdentity();
  if (!identity) throw new Error("UNAUTHORIZED");
  const user = await ctx.db
    .query("users")
    .withIndex("by_email", (q) => q.eq("email", identity.email!))
    .first();
  if (!user || (user.role !== "ADMIN" && user.role !== "STAFF")) {
    throw new Error("UNAUTHORIZED");
  }
  return user as { _id: Id<"users">; role: string; email: string };
}
 
export const list = query({
  args: {},
  handler: async (ctx) => {
    return await ctx.db.query("tables").collect();
  },
});
 
export const create = mutation({
  args: {
    name: v.string(), // Table number (e.g., "T01")
    capacity: v.number(),
  },
  handler: async (ctx, args) => {
    // CORRECT: inline role check via ctx.auth.getUserIdentity()
    await requireStaffOrAdmin(ctx);
 
    const now = Date.now();
    return await ctx.db.insert("tables", {
      ...args,
      status: "ACTIVE",
      createdAt: now,
      updatedAt: now,
    });
  },
});

// convex/functions/menu.ts
import { query, mutation } from "../_generated/server";
import { v } from "convex/values";
import { Id } from "../_generated/dataModel";
import { consola } from "consola";
 
// Inline role check — staffMutation/adminMutation not available yet
async function requireStaffOrAdmin(ctx: {
  auth: { getUserIdentity: () => Promise<{ email?: string } | null> };
  db: { query: (table: string) => { withIndex: (name: string, fn: (q: { eq: (field: string, value: string) => { first: () => Promise<unknown> } }) => { first: () => Promise<unknown> } }) => { first: () => Promise<unknown> } } };
}): Promise<{ _id: Id<"users">; role: string; email: string }> {
  const identity = await ctx.auth.getUserIdentity();
  if (!identity) throw new Error("UNAUTHORIZED");
  const user = await ctx.db
    .query("users")
    .withIndex("by_email", (q) => q.eq("email", identity.email!))
    .first();
  if (!user || (user.role !== "ADMIN" && user.role !== "STAFF")) {
    throw new Error("UNAUTHORIZED");
  }
  return user as { _id: Id<"users">; role: string; email: string };
}
 
export const listAvailable = query({
  args: {},
  handler: async (ctx) => {
    return await ctx.db
      .query("menuItems")
      .withIndex("by_available", (q) => q.eq("available", true))
      .collect();
  },
});
 
export const listByCategory = query({
  args: { category: v.string() },
  handler: async (ctx, { category }) => {
    return await ctx.db
      .query("menuItems")
      .withIndex("by_category", (q) => q.eq("category", category))
      .collect();
  },
});
 
export const create = mutation({
  args: {
    name: v.string(),
    description: v.string(),
    price: v.number(),
    category: v.string(),
    station: v.union(v.literal("KITCHEN"), v.literal("BAR")),
    imageUrl: v.optional(v.string()),
  },
  handler: async (ctx, args) => {
    // Inline role check
    await requireStaffOrAdmin(ctx);
 
    const now = Date.now();
    return await ctx.db.insert("menuItems", {
      ...args,
      available: true,
      sortOrder: 0,
      createdAt: now,
      updatedAt: now,
    });
  },
});

// convex/functions/orders.ts
import { query, mutation } from "../_generated/server";
import { v } from "convex/values";
import { Id } from "../_generated/dataModel";
import { consola } from "consola";
 
export const createOrder = mutation({
  args: {
    tableId: v.id("tables"),
    reservationId: v.optional(v.id("reservations")),
  },
  handler: async (ctx, { tableId, reservationId }) => {
    const now = Date.now();
    return await ctx.db.insert("orders", {
      tableId,
      reservationId,
      status: "OPEN",
      totalAmount: 0,
      createdAt: now,
      updatedAt: now,
    });
  },
});
 
export const addItem = mutation({
  args: {
    orderId: v.id("orders"),
    menuItemId: v.id("menuItems"),
    quantity: v.number(),
    notes: v.optional(v.string()),
  },
  handler: async (ctx, { orderId, menuItemId, quantity, notes }) => {
    const menuItem = await ctx.db.get(menuItemId);
    if (!menuItem) {
      throw new Error("MENU_ITEM_NOT_FOUND");
    }
 
    const now = Date.now();
    const itemId = await ctx.db.insert("orderItems", {
      orderId,
      menuItemId,
      quantity,
      unitPrice: menuItem.price,
      status: "PENDING",
      station: menuItem.station,
      notes,
      isComp: false,
      createdAt: now,
      updatedAt: now,
    });
 
    // Update order total
    const order = await ctx.db.get(orderId);
    if (order) {
      await ctx.db.patch(orderId, {
        totalAmount: order.totalAmount + menuItem.price * quantity,
        updatedAt: now,
      });
    }
 
    return itemId;
  },
});
 
export const updateItemStatus = mutation({
  args: {
    itemId: v.id("orderItems"),
    status: v.union(
      v.literal("SUBMITTED"),
      v.literal("PREPARING"),
      v.literal("READY"),
      v.literal("SERVED"),
      v.literal("CANCELLED"),
    ),
  },
  handler: async (ctx, { itemId, status }) => {
    await ctx.db.patch(itemId, { status, updatedAt: Date.now() });
    consola.debug("KDS item status updated", { itemId, status });
  },
});
 
export const submitOrder = mutation({
  args: { orderId: v.id("orders") },
  handler: async (ctx, { orderId }) => {
    const now = Date.now();
    await ctx.db.patch(orderId, { status: "SUBMITTED", updatedAt: now });
    // Update all PENDING items to SUBMITTED
    const items = await ctx.db
      .query("orderItems")
      .withIndex("by_order", (q) => q.eq("orderId", orderId))
      .collect();
    for (const item of items) {
      if (item.status === "PENDING") {
        await ctx.db.patch(item._id, {
          status: "SUBMITTED",
          updatedAt: now,
        });
      }
    }
    consola.info("Order submitted", { orderId, itemCount: items.length });
  },
});
 
export const getByStationAndStatus = query({
  args: {
    station: v.union(v.literal("KITCHEN"), v.literal("BAR")),
    status: v.optional(v.string()),
  },
  handler: async (ctx, { station, status }) => {
    const items = await ctx.db
      .query("orderItems")
      .withIndex("by_station_status", (q) =>
        status
          ? q.eq("station", station).eq("status", status)
          : q.eq("station", station),
      )
      .collect();
 
    // Enrich with order + menu item data
    const enriched = [];
    for (const item of items) {
      const order = await ctx.db.get(item.orderId);
      const menuItem = await ctx.db.get(item.menuItemId);
      if (order && menuItem) {
        enriched.push({ item, order, menuItem });
      }
    }
    return enriched;
  },
});
 
export const getOpenOrderByTable = query({
  args: { tableId: v.id("tables") },
  handler: async (ctx, { tableId }) => {
    const orders = await ctx.db
      .query("orders")
      .withIndex("by_table", (q) => q.eq("tableId", tableId))
      .collect();
    return (
      orders.find((o) => o.status === "OPEN" || o.status === "SUBMITTED") ??
      null
    );
  },
});

// NOTE: This is a PUBLIC mutation — no auth required since guests access via QR code
export const getOrCreateForTable = mutation({
  args: {
    tableId: v.id("tables"),
    reservationId: v.optional(v.id("reservations")),
  },
  handler: async (ctx, { tableId, reservationId }) => {
    const existing = await ctx.db
      .query("orders")
      .withIndex("by_table", (q) => q.eq("tableId", tableId))
      .collect()
      .then((orders) =>
        orders.find((o) => o.status === "OPEN" || o.status === "SUBMITTED"),
      );
 
    if (existing) {
      return existing;
    }
 
    const id = await ctx.db.insert("orders", {
      tableId,
      reservationId: reservationId ?? undefined,
      status: "OPEN",
      totalAmount: 0,
      createdAt: Date.now(),
      updatedAt: Date.now(),
    });
 
    return await ctx.db.get(id);
  },
});

git add convex/functions/tables.ts convex/functions/menu.ts convex/functions/orders.ts
git commit -m "feat(pos): add table, menu, and order Convex functions"

// apps/frontend/components/pos/kitchen-kanban.tsx
"use client";
 
import { useCallback, useTransition } from "react";
import { useQuery, useMutation } from "convex/react";
import { api } from "~/convex/_generated/api";
import { useTranslations } from "next-intl";
import { consola } from "consola";
 
const COLUMNS = [
  { id: "SUBMITTED", labelKey: "pos.kanban.new", color: "border-blue-500" },
  { id: "PREPARING", labelKey: "pos.kanban.preparing", color: "border-orange-500" },
  { id: "READY", labelKey: "pos.kanban.ready", color: "border-green-500" },
  { id: "SERVED", labelKey: "pos.kanban.served", color: "border-gray-500" },
];
 
const NEXT_STATUS: Record<string, string> = {
  SUBMITTED: "PREPARING",
  PREPARING: "READY",
  READY: "SERVED",
};
 
export function KitchenKanban() {
  const t = useTranslations();
  const [isPending, startTransition] = useTransition();
  const station = "KITCHEN";
  // CORRECT: useQuery(api.fn, args) — pass function reference, not call
  const allItems = useQuery(api.orders.getByStationAndStatus, { station });
 
  const updateStatus = useMutation(api.orders.updateItemStatus);
 
  const byStatus = COLUMNS.reduce((acc, col) => {
    acc[col.id] = allItems?.filter((e) => e.item.status === col.id) ?? [];
    return acc;
  }, {} as Record<string, typeof allItems>);
 
  const handleMove = useCallback(
    async (itemId: string, currentStatus: string) => {
      const nextStatus = NEXT_STATUS[currentStatus];
      if (!nextStatus) return;
      startTransition(() => {
        updateStatus({ itemId, status: nextStatus });
      });
      consola.debug("KDS item status advanced", { itemId, nextStatus });
    },
    [updateStatus]
  );
 
  const getMoveButtonLabel = (currentStatus: string): string => {
    const next = NEXT_STATUS[currentStatus];
    if (next === "PREPARING") return t("pos.kanban.moveTo", { target: t("pos.kanban.preparing") });
    if (next === "READY") return t("pos.kanban.moveTo", { target: t("pos.kanban.ready") });
    if (next === "SERVED") return t("pos.kanban.moveTo", { target: t("pos.kanban.served") });
    return t("pos.kanban.served");
  };
 
  return (
    <div className="flex gap-4 overflow-x-auto pb-4">
      {COLUMNS.map((col) => (
        <div key={col.id} className={`flex-1 min-w-64 border-t-4 ${col.color}`}>
          <div className="bg-[#2E2E2E] p-3 rounded-b-lg">
            <h3 className="font-bold text-[#e6e6e6] mb-3">
              {t(col.labelKey)} ({byStatus[col.id]?.length ?? 0})
            </h3>
            <div className="space-y-2" data-testid={`kanban-column-${col.id}`}>
              {byStatus[col.id]?.map(({ item, order, menuItem }) => (
                <div
                  key={item._id}
                  className="bg-[#1a1a1a] border border-[#4d4d4d] p-3 rounded-lg"
                >
                  <p className="font-bold text-[#C5A059]">
                    {t("pos.kanban.table")} {order.tableId}
                  </p>
                  <p className="text-[#e6e6e6]">{menuItem.name} x {item.quantity}</p>
                  {item.notes && (
                    <p className="text-xs text-[#808080] mt-1">
                      {t("pos.kanban.note")}: {item.notes}
                    </p>
                  )}
                  {col.id !== "SERVED" && (
                    <button
                      onClick={() => handleMove(item._id, item.status)}
                      disabled={isPending}
                      data-testid="move-btn"
                      className="mt-2 w-full py-1 text-xs bg-[#C5A059]/20 text-[#C5A059] rounded hover:bg-[#C5A059]/30 disabled:opacity-50"
                    >
                      {getMoveButtonLabel(item.status)}
                    </button>
                  )}
                </div>
              ))}
              {byStatus[col.id]?.length === 0 && (
                <p className="text-[#808080] text-sm text-center py-4" data-testid={`kanban-column-${col.id}-empty`}>
                  {t("pos.kanban.noItems")}
                </p>
              )}
            </div>
          </div>
        </div>
      ))}
    </div>
  );
}

// apps/frontend/app/pos/kitchen/page.tsx
"use client";
 
import { Suspense } from "react";
import { useTranslations } from "next-intl";
import { KitchenKanban } from "~/components/pos/kitchen-kanban";
 
const STATION_FILTERS = [
  { key: "ALL", labelKey: "pos.kitchen.filterAll" },
  { key: "KITCHEN", labelKey: "pos.kitchen.filterKitchen" },
  { key: "BAR", labelKey: "pos.kitchen.filterBar" },
  { key: "READY", labelKey: "pos.kitchen.filterReady" },
];
 
function KitchenLoading() {
  return (
    <div className="flex gap-4 overflow-x-auto pb-4">
      {[1, 2, 3, 4].map((i) => (
        <div key={i} className="flex-1 min-w-64 border-t-4 border-[#4d4d4d]">
          <div className="bg-[#2E2E2E] p-3 rounded-b-lg animate-pulse">
            <div className="h-6 bg-[#4d4d4d] rounded mb-3 w-24" />
            <div className="space-y-2">
              {[1, 2, 3].map((j) => (
                <div key={j} className="bg-[#1a1a1a] border border-[#4d4d4d] p-3 rounded-lg h-24" />
              ))}
            </div>
          </div>
        </div>
      ))}
    </div>
  );
}
 
export default function KitchenPage() {
  const t = useTranslations();
 
  return (
    <div className="min-h-screen bg-[#1a1a1a] p-6">
      <div className="flex items-center justify-between mb-6">
        <h1 className="text-2xl font-serif text-[#C5A059]">
          {t("pos.kitchen.title")}
        </h1>
        <div className="flex gap-2">
          {STATION_FILTERS.map((filter) => (
            <button
              key={filter.key}
              className="px-3 py-1 text-sm bg-[#2E2E2E] border border-[#4d4d4d] text-[#e6e6e6] rounded hover:border-[#C5A059] transition-colors"
            >
              {t(filter.labelKey)}
            </button>
          ))}
        </div>
      </div>
      <Suspense fallback={<KitchenLoading />}>
        <KitchenKanban />
      </Suspense>
    </div>
  );
}

git add apps/frontend/app/pos/kitchen/ apps/frontend/components/pos/kitchen-kanban.tsx
git commit -m "feat(pos): add kitchen KDS kanban board"

// apps/frontend/components/pos/table-list.tsx
"use client";
 
import { useQuery } from "convex/react";
import { api } from "~/convex/_generated/api";
import { useTranslations } from "next-intl";
 
type TableStatus = "AVAILABLE" | "OCCUPIED" | "RESERVED";
 
export function TableList() {
  const t = useTranslations();
  const tables = useQuery(api.tables.list);
 
  const getStatusColor = (status: TableStatus) => {
    switch (status) {
      case "AVAILABLE": return "bg-green-500";
      case "OCCUPIED": return "bg-[#C5A059]";
      case "RESERVED": return "bg-orange-500";
      default: return "bg-[#4d4d4d]";
    }
  };
 
  return (
    <div className="grid grid-cols-4 gap-4" data-testid="table-list">
      {tables?.map((table) => (
        <div
          key={table._id}
          className="bg-[#2E2E2E] p-4 rounded-lg border border-[#4d4d4d]"
          data-testid={`table-${table.name}`}
        >
          <div className="font-bold text-lg text-[#e6e6e6]">{table.name}</div>
          <div className="text-sm text-[#808080]">{table.capacity} seats</div>
          <div className={`mt-2 w-3 h-3 rounded-full ${getStatusColor(table.status)}`} />
        </div>
      ))}
    </div>
  );
}

// apps/frontend/app/pos/reception/page.tsx
"use client";
 
import { Suspense } from "react";
import { useTranslations } from "next-intl";
import { TableList } from "~/components/pos/table-list";
 
function ReceptionLoading() {
  return <div className="grid grid-cols-4 gap-4">
    {[1,2,3,4].map(i => (
      <div key={i} className="h-24 bg-[#2E2E2E] rounded-lg animate-pulse" />
    ))}
  </div>;
}
 
export default function ReceptionPage() {
  const t = useTranslations();
 
  return (
    <div className="min-h-screen bg-[#1a1a1a] p-6">
      <h1 className="text-2xl font-serif text-[#C5A059] mb-6">
        {t("pos.reception.title")}
      </h1>
      <Suspense fallback={<ReceptionLoading />}>
        <TableList />
      </Suspense>
    </div>
  );
}

git add apps/frontend/app/pos/reception/ apps/frontend/components/pos/table-list.tsx
git commit -m "feat(pos): add reception table list"

// apps/frontend/app/table/page.tsx
"use client";
 
import { useEffect, useTransition } from "react";
import { useQuery, useMutation } from "convex/react";
import { useQueryState } from "nuqs";
import { api } from "~/convex/_generated/api";
import { useTranslations } from "next-intl";
import { MenuGrid } from "~/components/table/menu-grid";
import { Cart } from "~/components/table/cart";
import { OrderStatus } from "~/components/table/order-status";
 
export default function TablePage() {
  const t = useTranslations();
  const [isPending, startTransition] = useTransition();
 
  // CORRECT: nuqs URL state — no dynamic route segments
  const [tableId] = useQueryState("tableId", { defaultValue: "" });
  const [token] = useQueryState("token", { defaultValue: "" });
  const [isSubmitted, setIsSubmitted] = useQueryState("submitted", { defaultValue: "false" });
 
  // CORRECT: useQuery(api.fn, args) — pass function reference, not call
  const openOrder = useQuery(
    api.orders.getOpenOrderByTable,
    tableId ? { tableId } : "skip"
  );
 
  const getOrCreateOrder = useMutation(api.orders.getOrCreateForTable);
 
  useEffect(() => {
    if (tableId) {
      startTransition(() => {
        getOrCreateOrder({ tableId });
      });
    }
  }, [tableId, getOrCreateOrder]);
 
  useEffect(() => {
    if (openOrder) {
      setIsSubmitted(openOrder.status === "SUBMITTED" || openOrder.status === "COMPLETED" ? "true" : "false");
    }
  }, [openOrder, setIsSubmitted]);
 
  return (
    <div className="min-h-screen bg-[#1a1a1a] text-[#e6e6e6]">
      <header className="sticky top-0 z-10 bg-[#2E2E2E] border-b border-[#4d4d4d] px-4 py-3">
        <div className="max-w-lg mx-auto flex justify-between items-center">
          <div>
            <h1 className="font-serif text-[#C5A059] text-lg">
              {t("pos.table.title", { tableId: tableId || t("pos.table.noTable") })}
            </h1>
            <p className="text-xs text-[#808080]">{t("pos.table.venue")}</p>
          </div>
          {isSubmitted === "true" && (
            <span className="text-xs bg-[#C5A059]/20 text-[#C5A059] px-2 py-1 rounded" data-testid="order-sent-badge">
              {t("pos.table.orderSent")}
            </span>
          )}
        </div>
      </header>
 
      <div className="max-w-lg mx-auto">
        <MenuGrid tableId={tableId} openOrder={openOrder} />
        <Cart tableId={tableId} openOrder={openOrder} onSubmitted={setIsSubmitted} />
      </div>
    </div>
  );
}

// apps/frontend/components/table/menu-grid.tsx
"use client";
 
import { useCallback, useState, useTransition } from "react";
import { useQuery, useMutation } from "convex/react";
import { useQueryState } from "nuqs";
import { api } from "~/convex/_generated/api";
import { useTranslations } from "next-intl";
 
const CATEGORIES = [
  { key: "APPETIZER", labelKey: "menu.category.appetizer" },
  { key: "MAIN", labelKey: "menu.category.main" },
  { key: "DESSERT", labelKey: "menu.category.dessert" },
  { key: "DRINK", labelKey: "menu.category.drink" },
  { key: "COCKTAIL", labelKey: "menu.category.cocktail" },
];
 
type MenuItem = {
  _id: string;
  name: string;
  description: string;
  price: number;
  category: string;
};
 
type OpenOrder = {
  _id: string;
  status: string;
  items?: Array<{ _id: string; menuItemId: string; quantity: number; status: string }>;
} | null;
 
export function MenuGrid({ tableId, openOrder }: { tableId: string; openOrder: OpenOrder }) {
  const t = useTranslations();
  const [isPending, startTransition] = useTransition();
  const [category, setCategory] = useQueryState("cat", {
    defaultValue: "APPETIZER",
    serialize: (v) => v,
    parse: (v) => v,
  });
 
  // CORRECT: useQuery(api.fn, args) — pass function reference
  const items = useQuery(api.menu.listByCategory, { category });
  const addItem = useMutation(api.orders.addItem);
 
  const [cart, setCart] = useState<Record<string, number>>({});
 
  const handleAdd = useCallback(
    async (menuItemId: string) => {
      if (!openOrder) return;
      const current = cart[menuItemId] ?? 0;
      setCart((prev) => ({ ...prev, [menuItemId]: current + 1 }));
      startTransition(() => {
        addItem({ orderId: openOrder._id, menuItemId, quantity: 1 });
      });
    },
    [openOrder, addItem, cart]
  );
 
  return (
    <div data-testid="menu-grid">
      {/* Category tabs */}
      <div className="flex gap-1 px-4 py-3 overflow-x-auto">
        {CATEGORIES.map((cat) => (
          <button
            key={cat.key}
            onClick={() => setCategory(cat.key)}
            data-testid={`category-tab-${cat.key}`}
            className={`px-3 py-1.5 text-sm rounded whitespace-nowrap ${
              category === cat.key
                ? "bg-[#C5A059] text-[#1a1a1a] font-medium"
                : "bg-[#2E2E2E] text-[#808080] border border-[#4d4d4d]"
            }`}
          >
            {t(cat.labelKey)}
          </button>
        ))}
      </div>
 
      {/* Items grid */}
      <div className="px-4 pb-24 space-y-3">
        {items?.map((item: MenuItem) => {
          const qty = cart[item._id] ?? 0;
          return (
            <div key={item._id} className="bg-[#2E2E2E] border border-[#4d4d4d] p-4 rounded-lg" data-testid="menu-item-card" data-category={item.category}>
              <div className="flex justify-between items-start">
                <div className="flex-1">
                  <h3 className="font-medium text-[#e6e6e6]">{item.name}</h3>
                  <p className="text-sm text-[#808080] mt-1">{item.description}</p>
                </div>
                <span className="text-[#C5A059] font-medium ml-4">
                  {item.price.toLocaleString()}{t("common.currencyShort")}
                </span>
              </div>
 
              <div className="mt-3 flex items-center gap-2">
                {qty === 0 ? (
                  <button
                    onClick={() => handleAdd(item._id)}
                    data-testid="menu-item-add-btn"
                    className="text-sm bg-[#C5A059] text-[#1a1a1a] px-3 py-1.5 rounded font-medium hover:bg-[#DEC89E] transition-colors"
                  >
                    {t("common.add")}
                  </button>
                ) : (
                  <>
                    <button
                      data-testid="menu-item-remove-btn"
                      className="w-8 h-8 rounded border border-[#4d4d4d] flex items-center justify-center text-[#808080] hover:border-[#C5A059] transition-colors"
                    >
                      <span className="text-lg">-</span>
                    </button>
                    <span className="font-medium w-8 text-center" data-testid={`cart-count-${item._id}`}>{qty}</span>
                    <button
                      onClick={() => handleAdd(item._id)}
                      className="w-8 h-8 rounded border border-[#4d4d4d] flex items-center justify-center text-[#C5A059] hover:border-[#C5A059] transition-colors"
                    >
                      <span className="text-lg">+</span>
                    </button>
                  </>
                )}
              </div>
            </div>
          );
        })}
      </div>
    </div>
  );
}

git add apps/frontend/app/table/ apps/frontend/components/table/
git commit -m "feat(pos): add guest table ordering PWA"

// convex/functions/tables.ts
import { z } from "zod";
 
export const CreateTableSchema = z.object({
  name: z.string().min(1, "Table name is required"),
  capacity: z.number().int().positive("Capacity must be at least 1"),
});
 
export const UpdateTableSchema = z.object({
  id: z.string(),
  name: z.string().min(1).optional(),
  capacity: z.number().int().positive().optional(),
  status: z.enum(["ACTIVE", "INACTIVE"]).optional(),
});
 
// convex/functions/menu.ts
export const CreateMenuItemSchema = z.object({
  name: z.string().min(1, "Menu item name is required"),
  description: z.string(),
  price: z.number().nonnegative("Price must be non-negative"),
  category: z.enum([
    "APPETIZER",
    "MAIN",
    "DESSERT",
    "DRINK",
    "COCKTAIL",
    "WINE",
    "BEER",
    "SOFT_DRINK",
    "OTHER",
  ]),
  station: z.enum(["KITCHEN", "BAR"]),
  imageUrl: z.string().url().optional(),
  sortOrder: z.number().int().default(0),
});
 
export const UpdateMenuItemSchema = z.object({
  id: z.string(),
  name: z.string().min(1).optional(),
  description: z.string().optional(),
  price: z.number().nonnegative().optional(),
  category: z
    .enum([
      "APPETIZER",
      "MAIN",
      "DESSERT",
      "DRINK",
      "COCKTAIL",
      "WINE",
      "BEER",
      "SOFT_DRINK",
      "OTHER",
    ])
    .optional(),
  station: z.enum(["KITCHEN", "BAR"]).optional(),
  imageUrl: z.string().url().optional(),
  available: z.boolean().optional(),
  sortOrder: z.number().int().optional(),
});
 
// convex/functions/orders.ts
export const CreateOrderSchema = z.object({
  tableId: z.string().min(1, "Table ID is required"),
  reservationId: z.string().optional(),
});
 
export const AddItemSchema = z.object({
  orderId: z.string().min(1, "Order ID is required"),
  menuItemId: z.string().min(1, "Menu item ID is required"),
  quantity: z.number().int().positive("Quantity must be at least 1"),
  notes: z.string().optional(),
});
 
export const UpdateItemStatusSchema = z.object({
  itemId: z.string().min(1, "Item ID is required"),
  status: z.enum(["SUBMITTED", "PREPARING", "READY", "SERVED", "CANCELLED"]),
});
 
export const SubmitOrderSchema = z.object({
  orderId: z.string().min(1, "Order ID is required"),
});
 
export const GetOpenOrderByTableSchema = z.object({
  tableId: z.string().min(1, "Table ID is required"),
});

// convex/functions/orders.ts
export const POS_ERROR_CODES = {
  TABLE_NAME_REQUIRED: "TABLE_NAME_REQUIRED",
  INVALID_CAPACITY: "INVALID_CAPACITY",
  MENU_ITEM_NOT_FOUND: "MENU_ITEM_NOT_FOUND",
  MENU_ITEM_UNAVAILABLE: "MENU_ITEM_UNAVAILABLE",
  ORDER_NOT_FOUND: "ORDER_NOT_FOUND",
  ORDER_NOT_OPEN: "ORDER_NOT_OPEN",
  INVALID_QUANTITY: "INVALID_QUANTITY",
  ORDER_EMPTY: "ORDER_EMPTY",
  ORDER_ITEM_NOT_FOUND: "ORDER_ITEM_NOT_FOUND",
  UNAUTHORIZED: "UNAUTHORIZED",
} as const;
 
type POSErrorCode = keyof typeof POS_ERROR_CODES;

// Kitchen KDS — list view
// CORRECT: pass function reference, not call
const submittedItems = useQuery(api.orders.getByStationAndStatus, {
  station: "KITCHEN",
});
 
// Guest PWA — individual order
// CORRECT: pass function reference, not call
const openOrder = useQuery(
  api.orders.getOpenOrderByTable,
  tableId ? { tableId } : "skip",
);
 
// Reception — all tables for floor plan
const tables = useQuery(api.tables.list);
 
// Staff POS — available menu items
const menuItems = useQuery(api.menu.listAvailable);
 
// Category-filtered menu items
const categoryItems = useQuery(api.menu.listByCategory, { category });

/table page shell: Cache-First (revalidate in background)
/menu items: Network-First with 5s timeout, fallback to cached
/convex subscription: Always online (real-time required for ordering)

Offline state:
- Menu browsing: WORKS (cached menu items)
- Add to cart: BLOCKED (shows "Offline" banner)
- Send Order: BLOCKED (button disabled, tooltip explains)

{
  "name": "House of Legends - Table Ordering",
  "short_name": "HOL Table",
  "display": "standalone",
  "theme_color": "#C5A059",
  "background_color": "#1a1a1a",
  "start_url": "/table",
  "icons": [
    { "src": "/icons/icon-192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/icons/icon-512.png", "sizes": "512x512", "type": "image/png" }
  ]
}

{
  "pos": {
    "kanban": {
      "new": "New",
      "preparing": "Preparing",
      "ready": "Ready",
      "served": "Served",
      "table": "Table",
      "note": "Note",
      "moveTo": "Move to {target}",
      "noItems": "No items"
    },
    "kitchen": {
      "title": "Kitchen Display",
      "filterAll": "All",
      "filterKitchen": "Kitchen",
      "filterBar": "Bar",
      "filterReady": "Ready"
    },
    "reception": {
      "title": "Reception",
      "legendAvailable": "Available",
      "legendOccupied": "Occupied",
      "legendNeedsAttention": "Needs Attention",
      "checkIn": "Check In",
      "noShow": "No Show",
      "viewOrders": "View Orders",
      "blockTable": "Block Table"
    },
    "staff": {
      "title": "Floor POS",
      "selectTable": "Select a table",
      "tableTitle": "Table {name}",
      "selectTablePrompt": "Select a table to start",
      "cartEmpty": "Cart is empty",
      "total": "Total",
      "sendToKitchen": "Send to Kitchen"
    },
    "table": {
      "title": "Table {tableId}",
      "noTable": "Unknown Table",
      "venue": "House of Legends",
      "orderSent": "Order Sent",
      "sendOrder": "Send Order",
      "callStaff": "Call Staff"
    },
    "orderStatus": {
      "pending": "Pending",
      "submitted": "Submitted",
      "preparing": "Preparing",
      "ready": "Ready",
      "served": "Served"
    }
  },
  "menu": {
    "category": {
      "appetizer": "Appetizers",
      "main": "Main Courses",
      "dessert": "Desserts",
      "drink": "Drinks",
      "cocktail": "Cocktails",
      "wine": "Wine",
      "softDrink": "Soft Drinks"
    }
  },
  "common": {
    "add": "Add",
    "currencyShort": " VND",
    "loading": "Loading..."
  },
  "errors": {
    "table": {
      "nameRequired": "Table name is required",
      "invalidCapacity": "Table capacity must be at least 1"
    },
    "menu": {
      "notFound": "Menu item not found",
      "unavailable": "Menu item is currently unavailable"
    },
    "order": {
      "notFound": "Order not found",
      "notOpen": "Order is not open for modifications",
      "invalidQuantity": "Quantity must be at least 1",
      "empty": "Cannot submit an empty order",
      "itemNotFound": "Order item not found"
    },
    "auth": {
      "unauthorized": "You must be signed in as staff or admin"
    }
  }
}

# Server-only (never exposed to client):
CLERK_SECRET_KEY=           # Clerk secret key
 
# Client-safe (NEXT_PUBLIC_ prefix):
NEXT_PUBLIC_CONVEX_URL=    # Convex deployment URL
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=  # Clerk publishable key
 
# QR token configuration:
QR_TOKEN_SECRET=           # HMAC secret for table QR tokens (32+ bytes, server-only)

// e2e/staff-operations.spec.ts
 
test("SO-E2E-1.1: Kitchen KDS displays incoming orders in real-time", async ({
  page,
}) => {
  // Given: Kitchen KDS page is open and an order with KITCHEN items exists
  // When: Guest submits order via PWA
  // Then: New order appears in the "New" column within 2 seconds
  await page.goto("/en/pos/kitchen");
  await page.waitForTimeout(500);
  await expect(
    page.locator('[data-testid="kanban-column-SUBMITTED"]'),
  ).toBeVisible();
});
 
test("SO-E2E-1.2: Kitchen staff can advance item status through kanban", async ({
  page,
}) => {
  // Given: An item is in "New" column on KDS
  // When: Staff clicks "Start Preparing" button on that item
  // Then: Item moves to "Preparing" column
  await page.goto("/en/pos/kitchen");
  const newItem = page
    .locator('[data-testid="kanban-column-SUBMITTED"]')
    .first();
  await newItem.getByTestId("move-btn").click();
  await expect(
    page.locator('[data-testid="kanban-column-PREPARING"]'),
  ).toBeVisible();
});
 
test("SO-E2E-1.3: Reception floor plan shows table statuses", async ({
  page,
}) => {
  // Given: Reception page is open with tables configured
  // When: Page loads
  // Then: Floor plan shows all tables with status colors
  await page.goto("/en/pos/reception");
  await expect(page.locator('[data-testid="floor-plan"]')).toBeVisible();
  await expect(page.locator('[data-testid="table-1"]')).toBeVisible();
});
 
test("SO-E2E-1.4: Guest PWA shows menu grid", async ({ page }) => {
  // Given: Guest scans QR code and lands on /table?tableId=xxx&token=xxx
  // When: Page loads
  // Then: Menu categories are visible and items are listed
  await page.goto("/en/table?tableId=table123&token=abc");
  await expect(page.locator('[data-testid="menu-grid"]')).toBeVisible();
  await expect(page.getByTestId("category-tab-APPETIZER")).toBeVisible();
});
 
test("SO-E2E-1.5: Guest PWA add to cart updates order total", async ({
  page,
}) => {
  // Given: Guest is on /table page with an open order
  // When: Guest taps "Add" on a menu item
  // Then: Cart count increments and total updates
  await page.goto("/en/table?tableId=table123&token=abc");
  await page.getByTestId("menu-item-add-btn").first().click();
  await expect(
    page.locator('[data-testid^="cart-count-"]').first(),
  ).toContainText("1");
});
 
test("SO-E2E-1.6: Guest PWA submit order sends to kitchen", async ({
  page,
}) => {
  // Given: Guest has added items to cart
  // When: Guest taps "Send Order"
  // Then: Order status changes to SUBMITTED, cart clears
  await page.goto("/en/table?tableId=table123&token=abc");
  await page.getByTestId("menu-item-add-btn").first().click();
  await page.getByTestId("send-order-btn").click();
  await expect(page.locator('[data-testid="order-sent-badge"]')).toBeVisible();
});