feat: custom roles with per-permission matrix for café owners

- Owner can define named custom roles (e.g. Barista, Supervisor) with
  color, description, and a fine-grained permission set (21 permissions
  across 7 categories: admin, menu, staff, customer, reports, ops, kitchen)
- Employee assigned a custom role gets its permissions embedded in the
  JWT at login (customPerms claim) and parsed by TenantMiddleware —
  overrides the static EmployeeRole matrix for all API permission checks
- New endpoints: GET/POST/PATCH/DELETE /api/cafes/{id}/custom-roles and
  PUT /api/cafes/{id}/employees/{id}/custom-role for assignment
- Dashboard Settings → Team & Staff → Custom Roles panel with grouped
  checkbox matrix, group-level toggles, color preset picker, CRUD forms,
  and employee-count display; translations in fa/en/ar
- EF migration adds CustomRoles table + nullable CustomRoleId FK on Employees
- POS slip now shows per-item notes on both thermal print and bill preview

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
soroush.asadi
2026-06-21 03:12:43 +03:30
parent 73a5e5183b
commit aebfa825cd
23 changed files with 1126 additions and 20 deletions
+48 -1
View File
@@ -1203,7 +1203,54 @@
"printer": "الطابعة",
"printerSettings": "إعدادات الطابعة",
"printTest": "صفحة اختبار الطباعة",
"shopDiscover": "اكتشاف و AI"
"shopDiscover": "اكتشاف و AI",
"team": "الفريق والموظفون",
"customRoles": "الأدوار المخصصة"
},
"customRoles": {
"title": "الأدوار المخصصة",
"subtitle": "حدّد أدواراً بصلاحيات مخصصة لموظفيك",
"newRole": "دور جديد",
"editRole": "تعديل الدور",
"name": "اسم الدور",
"namePlaceholder": "مثلاً: باريستا، مشرف الطابق",
"description": "الوصف (اختياري)",
"descriptionPlaceholder": "وصف مختصر لهذا الدور",
"color": "اللون",
"permissions": "الصلاحيات",
"empty": "لم يتم تعريف أي أدوار مخصصة بعد",
"saveError": "فشل حفظ الدور",
"deleteConfirm": "حذف الدور «{name}»؟ سيعود الموظفون إلى صلاحيات دورهم الأساسي.",
"groupAdmin": "إدارة المقهى",
"groupMenu": "القائمة والمخزون",
"groupStaff": "الموظفون",
"groupCustomer": "العملاء والطاولات",
"groupReports": "التقارير والمالية",
"groupOps": "عمليات الصندوق",
"groupKitchen": "المطبخ والتوصيل",
"perm": {
"ManageCafeSettings": "إعدادات المقهى",
"ManageBilling": "الاشتراك والفواتير",
"ManageBranches": "إدارة الفروع",
"ManageMenu": "إدارة القائمة",
"ManageInventory": "المخزون",
"ManageTaxes": "الضرائب",
"ManagePrintSettings": "إعدادات الطباعة",
"ManageStaff": "إدارة الموظفين",
"ManageSalaries": "الرواتب",
"ReviewLeave": "طلبات الإجازة",
"ManageReservations": "الحجوزات",
"ManageTables": "الطاولات",
"ManageCoupons": "الكوبونات",
"ViewReports": "التقارير",
"ManageExpenses": "المصروفات",
"ProcessOrders": "معالجة الطلبات",
"HandlePayments": "المدفوعات",
"OperateRegister": "الصندوق",
"ManageQueue": "قائمة الانتظار",
"ViewKitchen": "شاشة المطبخ",
"HandleDelivery": "التوصيل"
}
},
"appearance": {
"paletteSection": "لوحة الألوان",
+48 -1
View File
@@ -1275,7 +1275,54 @@
"printer": "Printer",
"printerSettings": "Printer settings",
"printTest": "Print test page",
"shopDiscover": "Discover & AI"
"shopDiscover": "Discover & AI",
"team": "Team & Staff",
"customRoles": "Custom Roles"
},
"customRoles": {
"title": "Custom Roles",
"subtitle": "Define roles with tailored permissions for your staff",
"newRole": "New Role",
"editRole": "Edit Role",
"name": "Role Name",
"namePlaceholder": "e.g. Barista, Floor Supervisor",
"description": "Description (optional)",
"descriptionPlaceholder": "Brief description of this role",
"color": "Color",
"permissions": "Permissions",
"empty": "No custom roles defined yet",
"saveError": "Failed to save role",
"deleteConfirm": "Delete role '{name}'? Employees will revert to their base role permissions.",
"groupAdmin": "Café Administration",
"groupMenu": "Menu & Inventory",
"groupStaff": "Staff",
"groupCustomer": "Customer & Tables",
"groupReports": "Reports & Finance",
"groupOps": "Register Operations",
"groupKitchen": "Kitchen & Delivery",
"perm": {
"ManageCafeSettings": "Café settings",
"ManageBilling": "Billing & subscription",
"ManageBranches": "Manage branches",
"ManageMenu": "Menu management",
"ManageInventory": "Inventory",
"ManageTaxes": "Taxes",
"ManagePrintSettings": "Print settings",
"ManageStaff": "Staff management",
"ManageSalaries": "Salaries",
"ReviewLeave": "Leave requests",
"ManageReservations": "Reservations",
"ManageTables": "Tables",
"ManageCoupons": "Coupons",
"ViewReports": "Reports",
"ManageExpenses": "Expenses",
"ProcessOrders": "Process orders",
"HandlePayments": "Handle payments",
"OperateRegister": "Register",
"ManageQueue": "Queue",
"ViewKitchen": "Kitchen display",
"HandleDelivery": "Delivery"
}
},
"appearance": {
"paletteSection": "Color palette",
+48 -1
View File
@@ -1276,7 +1276,54 @@
"printer": "پرینتر",
"printerSettings": "تنظیمات پرینتر",
"printTest": "صفحه تست چاپ",
"shopDiscover": "کشف و AI"
"shopDiscover": "کشف و AI",
"team": "تیم و کارمندان",
"customRoles": "نقش‌های سفارشی"
},
"customRoles": {
"title": "نقش‌های سفارشی",
"subtitle": "نقش‌هایی با دسترسی دلخواه برای کارمندان تعریف کنید",
"newRole": "نقش جدید",
"editRole": "ویرایش نقش",
"name": "نام نقش",
"namePlaceholder": "مثلاً: باریستا، مسئول طبقه",
"description": "توضیح (اختیاری)",
"descriptionPlaceholder": "توضیح مختصر درباره این نقش",
"color": "رنگ",
"permissions": "دسترسی‌ها",
"empty": "هنوز نقش سفارشی تعریف نشده است",
"saveError": "ذخیره نقش ناموفق بود",
"deleteConfirm": "نقش «{name}» حذف شود؟ این کارمندان به دسترسی پیش‌فرض نقش اصلی خود بازمی‌گردند.",
"groupAdmin": "مدیریت کافه",
"groupMenu": "منو و انبار",
"groupStaff": "پرسنل",
"groupCustomer": "مشتری و میز",
"groupReports": "گزارش و مالی",
"groupOps": "عملیات صندوق",
"groupKitchen": "آشپزخانه و تحویل",
"perm": {
"ManageCafeSettings": "تنظیمات کافه",
"ManageBilling": "اشتراک و پرداخت",
"ManageBranches": "مدیریت شعب",
"ManageMenu": "مدیریت منو",
"ManageInventory": "انبار و موجودی",
"ManageTaxes": "مالیات",
"ManagePrintSettings": "تنظیمات چاپ",
"ManageStaff": "مدیریت کارمندان",
"ManageSalaries": "حقوق و دستمزد",
"ReviewLeave": "بررسی مرخصی",
"ManageReservations": "رزروها",
"ManageTables": "میزها",
"ManageCoupons": "کوپن‌ها",
"ViewReports": "گزارش‌ها",
"ManageExpenses": "هزینه‌ها",
"ProcessOrders": "ثبت سفارش",
"HandlePayments": "پردازش پرداخت",
"OperateRegister": "صندوق",
"ManageQueue": "صف انتظار",
"ViewKitchen": "نمایش آشپزخانه",
"HandleDelivery": "تحویل و پیک"
}
},
"appearance": {
"paletteSection": "پالت رنگ",
@@ -125,6 +125,7 @@ export function PosSlipModal({
name: item.menuItemName,
quantity: item.quantity,
price: formatCurrency(item.unitPrice * item.quantity, numberLocale),
notes: item.notes,
})),
totals: {
total: formatCurrency(order!.total, numberLocale),
@@ -187,13 +188,20 @@ export function PosSlipModal({
</div>
))
: activeBillItems.map((item) => (
<div key={item.id} className="receipt-row mb-1 text-xs">
<span>
{item.menuItemName} × {item.quantity}
</span>
<span>
{formatCurrency(item.unitPrice * item.quantity, numberLocale)}
</span>
<div key={item.id} className="mb-1 text-xs">
<div className="receipt-row">
<span>
{item.menuItemName} × {item.quantity}
</span>
<span>
{formatCurrency(item.unitPrice * item.quantity, numberLocale)}
</span>
</div>
{item.notes && (
<div className="ps-2 text-[10px] text-muted-foreground">
{item.notes}
</div>
)}
</div>
))}
@@ -0,0 +1,406 @@
"use client";
import { useState } from "react";
import { useTranslations } from "next-intl";
import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
import { Plus, Pencil, Trash2, Users, ShieldCheck } from "lucide-react";
import { apiDelete, apiGet, apiPatch, apiPost } from "@/lib/api/client";
import { Button } from "@/components/ui/button";
import { Input } from "@/components/ui/input";
import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
import { Badge } from "@/components/ui/badge";
import { useConfirm } from "@/components/providers/confirm-provider";
import { cn } from "@/lib/utils";
// ─── Types ────────────────────────────────────────────────────────────────────
interface CustomRoleDto {
id: string;
name: string;
description?: string | null;
color?: string | null;
permissions: string[];
employeeCount: number;
createdAt: string;
}
// ─── Permission catalogue ─────────────────────────────────────────────────────
interface PermGroup {
labelKey: string;
perms: string[];
}
const PERM_GROUPS: PermGroup[] = [
{
labelKey: "customRoles.groupAdmin",
perms: ["ManageCafeSettings", "ManageBilling", "ManageBranches"],
},
{
labelKey: "customRoles.groupMenu",
perms: ["ManageMenu", "ManageInventory", "ManageTaxes", "ManagePrintSettings"],
},
{
labelKey: "customRoles.groupStaff",
perms: ["ManageStaff", "ManageSalaries", "ReviewLeave"],
},
{
labelKey: "customRoles.groupCustomer",
perms: ["ManageReservations", "ManageTables", "ManageCoupons"],
},
{
labelKey: "customRoles.groupReports",
perms: ["ViewReports", "ManageExpenses"],
},
{
labelKey: "customRoles.groupOps",
perms: ["ProcessOrders", "HandlePayments", "OperateRegister", "ManageQueue"],
},
{
labelKey: "customRoles.groupKitchen",
perms: ["ViewKitchen", "HandleDelivery"],
},
];
const PRESET_COLORS = [
"#6366F1", "#8B5CF6", "#EC4899", "#F59E0B",
"#10B981", "#3B82F6", "#EF4444", "#64748B",
];
// ─── Permission checkbox matrix ───────────────────────────────────────────────
function PermissionMatrix({
selected,
onChange,
t,
}: {
selected: Set<string>;
onChange: (next: Set<string>) => void;
t: ReturnType<typeof useTranslations>;
}) {
const toggle = (perm: string) => {
const next = new Set(selected);
if (next.has(perm)) next.delete(perm);
else next.add(perm);
onChange(next);
};
const toggleGroup = (perms: string[]) => {
const allOn = perms.every((p) => selected.has(p));
const next = new Set(selected);
if (allOn) perms.forEach((p) => next.delete(p));
else perms.forEach((p) => next.add(p));
onChange(next);
};
return (
<div className="space-y-3">
{PERM_GROUPS.map((group) => {
const allOn = group.perms.every((p) => selected.has(p));
const someOn = group.perms.some((p) => selected.has(p));
return (
<div key={group.labelKey} className="rounded-lg border border-border p-3">
<button
type="button"
onClick={() => toggleGroup(group.perms)}
className="mb-2 flex w-full cursor-pointer items-center gap-2 text-start"
>
<span
className={cn(
"flex h-4 w-4 shrink-0 items-center justify-center rounded border text-[10px] font-bold transition-colors",
allOn
? "border-primary bg-primary text-primary-foreground"
: someOn
? "border-primary bg-primary/20 text-primary"
: "border-border bg-background"
)}
>
{allOn ? "✓" : someOn ? "" : ""}
</span>
<span className="text-xs font-semibold text-foreground">
{t(group.labelKey)}
</span>
</button>
<div className="grid grid-cols-2 gap-1.5 ps-6 sm:grid-cols-3">
{group.perms.map((perm) => (
<label key={perm} className="flex cursor-pointer items-center gap-1.5">
<input
type="checkbox"
checked={selected.has(perm)}
onChange={() => toggle(perm)}
className="accent-primary"
/>
<span className="text-[11px] text-muted-foreground">
{t(`customRoles.perm.${perm}`)}
</span>
</label>
))}
</div>
</div>
);
})}
</div>
);
}
// ─── Create / Edit form ───────────────────────────────────────────────────────
function RoleForm({
cafeId,
role,
onDone,
t,
tCommon,
}: {
cafeId: string;
role?: CustomRoleDto;
onDone: () => void;
t: ReturnType<typeof useTranslations>;
tCommon: ReturnType<typeof useTranslations>;
}) {
const qc = useQueryClient();
const [name, setName] = useState(role?.name ?? "");
const [description, setDescription] = useState(role?.description ?? "");
const [color, setColor] = useState(role?.color ?? PRESET_COLORS[0]!);
const [perms, setPerms] = useState<Set<string>>(new Set(role?.permissions ?? []));
const [error, setError] = useState<string | null>(null);
const save = useMutation({
mutationFn: async () => {
const body = {
name: name.trim(),
description: description.trim() || null,
color,
permissions: Array.from(perms),
};
if (role) {
return apiPatch(`/api/cafes/${cafeId}/custom-roles/${role.id}`, body);
}
return apiPost(`/api/cafes/${cafeId}/custom-roles`, body);
},
onSuccess: () => {
qc.invalidateQueries({ queryKey: ["custom-roles", cafeId] });
onDone();
},
onError: () => setError(t("customRoles.saveError")),
});
return (
<div className="space-y-4">
{/* Name + color */}
<div className="flex gap-3">
<div className="flex-1 space-y-1">
<label className="text-xs font-medium">{t("customRoles.name")}</label>
<Input
value={name}
onChange={(e) => setName(e.target.value)}
placeholder={t("customRoles.namePlaceholder")}
maxLength={100}
/>
</div>
<div className="space-y-1">
<label className="text-xs font-medium">{t("customRoles.color")}</label>
<div className="flex flex-wrap gap-1.5">
{PRESET_COLORS.map((c) => (
<button
key={c}
type="button"
onClick={() => setColor(c)}
className={cn(
"h-7 w-7 cursor-pointer rounded-full border-2 transition-transform",
color === c ? "border-foreground scale-110" : "border-transparent"
)}
style={{ backgroundColor: c }}
aria-label={c}
/>
))}
</div>
</div>
</div>
{/* Description */}
<div className="space-y-1">
<label className="text-xs font-medium">{t("customRoles.description")}</label>
<Input
value={description}
onChange={(e) => setDescription(e.target.value)}
placeholder={t("customRoles.descriptionPlaceholder")}
maxLength={200}
/>
</div>
{/* Permissions */}
<div className="space-y-1">
<p className="text-xs font-medium">{t("customRoles.permissions")}</p>
<PermissionMatrix selected={perms} onChange={setPerms} t={t} />
</div>
{error && <p className="text-sm text-destructive">{error}</p>}
<div className="flex justify-end gap-2 pt-1">
<Button variant="outline" onClick={onDone} disabled={save.isPending}>
{tCommon("cancel")}
</Button>
<Button
onClick={() => save.mutate()}
disabled={save.isPending || !name.trim()}
>
{save.isPending ? tCommon("saving") : tCommon("save")}
</Button>
</div>
</div>
);
}
// ─── Main panel ───────────────────────────────────────────────────────────────
export function CustomRolesPanel({ cafeId }: { cafeId: string }) {
const t = useTranslations("settings");
const tCommon = useTranslations("common");
const qc = useQueryClient();
const confirm = useConfirm();
const [editing, setEditing] = useState<CustomRoleDto | null | "new">(null);
const { data: roles = [], isLoading } = useQuery<CustomRoleDto[]>({
queryKey: ["custom-roles", cafeId],
queryFn: () => apiGet(`/api/cafes/${cafeId}/custom-roles`),
});
const deleteRole = useMutation({
mutationFn: (id: string) => apiDelete(`/api/cafes/${cafeId}/custom-roles/${id}`),
onSuccess: () => qc.invalidateQueries({ queryKey: ["custom-roles", cafeId] }),
});
const handleDelete = async (role: CustomRoleDto) => {
const ok = await confirm({
description: t("customRoles.deleteConfirm", { name: role.name }),
variant: "destructive",
confirmLabel: tCommon("confirm"),
});
if (!ok) return;
deleteRole.mutate(role.id);
};
if (editing !== null) {
return (
<Card>
<CardHeader className="pb-3">
<CardTitle className="text-base">
{editing === "new" ? t("customRoles.newRole") : t("customRoles.editRole")}
</CardTitle>
</CardHeader>
<CardContent>
<RoleForm
cafeId={cafeId}
role={editing === "new" ? undefined : editing}
onDone={() => setEditing(null)}
t={t}
tCommon={tCommon}
/>
</CardContent>
</Card>
);
}
return (
<div className="space-y-4">
<Card>
<CardHeader className="flex flex-row items-center justify-between gap-2 pb-3">
<div>
<CardTitle className="flex items-center gap-2 text-base">
<ShieldCheck className="size-4 text-primary" />
{t("customRoles.title")}
</CardTitle>
<p className="mt-0.5 text-xs text-muted-foreground">
{t("customRoles.subtitle")}
</p>
</div>
<Button size="sm" className="shrink-0 gap-1.5" onClick={() => setEditing("new")}>
<Plus className="size-4" />
{t("customRoles.newRole")}
</Button>
</CardHeader>
<CardContent>
{isLoading ? (
<div className="space-y-2">
{[0, 1, 2].map((i) => (
<div key={i} className="h-16 animate-pulse rounded-lg bg-muted" />
))}
</div>
) : roles.length === 0 ? (
<p className="py-6 text-center text-sm text-muted-foreground">
{t("customRoles.empty")}
</p>
) : (
<div className="space-y-2">
{roles.map((role) => (
<div
key={role.id}
className="flex items-start gap-3 rounded-lg border border-border p-3"
>
{/* Color dot */}
<div
className="mt-0.5 h-3 w-3 shrink-0 rounded-full"
style={{ backgroundColor: role.color ?? "#6366F1" }}
/>
<div className="min-w-0 flex-1">
<div className="flex items-center gap-2">
<span className="text-sm font-semibold">{role.name}</span>
{role.description && (
<span className="truncate text-xs text-muted-foreground">
{role.description}
</span>
)}
</div>
{/* Permission badges */}
<div className="mt-1.5 flex flex-wrap gap-1">
{role.permissions.slice(0, 6).map((p) => (
<Badge key={p} variant="secondary" className="text-[10px]">
{t(`customRoles.perm.${p}`)}
</Badge>
))}
{role.permissions.length > 6 && (
<Badge variant="outline" className="text-[10px]">
+{role.permissions.length - 6}
</Badge>
)}
</div>
</div>
{/* Employee count */}
<div className="flex shrink-0 items-center gap-1 text-xs text-muted-foreground">
<Users className="size-3.5" />
{role.employeeCount}
</div>
{/* Actions */}
<div className="flex shrink-0 gap-1">
<Button
size="icon"
variant="ghost"
className="h-8 w-8"
onClick={() => setEditing(role)}
>
<Pencil className="size-3.5" />
</Button>
<Button
size="icon"
variant="ghost"
className="h-8 w-8 text-destructive hover:text-destructive"
onClick={() => handleDelete(role)}
disabled={deleteRole.isPending}
>
<Trash2 className="size-3.5" />
</Button>
</div>
</div>
))}
</div>
)}
</CardContent>
</Card>
</div>
);
}
@@ -12,6 +12,7 @@ import { SettingsShopPanel } from "@/components/settings/settings-shop-panel";
import { SettingsTerminalsPanel } from "@/components/settings/settings-terminals-panel";
import { SettingsPrinterPanel } from "@/components/settings/settings-printer-panel";
import { SettingsPrintTestPanel } from "@/components/settings/settings-print-test-panel";
import { CustomRolesPanel } from "@/components/settings/custom-roles-panel";
import {
DEFAULT_SETTINGS_LEAF,
groupForLeaf,
@@ -25,6 +26,7 @@ const LEAF_PAGE_TITLE: Record<SettingsLeafId, string> = {
"shop-discover": "nav.shopDiscover",
"printer-config": "nav.printerSettings",
"print-test": "nav.printTest",
"team-custom-roles": "nav.customRoles",
};
export function SettingsScreen() {
@@ -40,7 +42,10 @@ export function SettingsScreen() {
const toggleGroup = (group: SettingsGroupId) => {
setExpandedGroup((prev) => (prev === group ? prev : group));
const firstChild = group === "shop" ? "shop-general" : "printer-config";
const firstChild =
group === "shop" ? "shop-general" :
group === "team" ? "team-custom-roles" :
"printer-config";
if (groupForLeaf(activeLeaf) !== group) {
selectLeaf(firstChild);
}
@@ -98,6 +103,10 @@ export function SettingsScreen() {
onOpenPrinterSettings={() => selectLeaf("printer-config")}
/>
) : null}
{activeLeaf === "team-custom-roles" ? (
<CustomRolesPanel cafeId={cafeId} />
) : null}
</div>
</div>
</div>
@@ -1,11 +1,12 @@
export type SettingsGroupId = "shop" | "printer";
export type SettingsGroupId = "shop" | "printer" | "team";
export type SettingsLeafId =
| "shop-general"
| "shop-appearance"
| "shop-discover"
| "printer-config"
| "print-test";
| "print-test"
| "team-custom-roles";
export type SettingsNavGroup = {
id: SettingsGroupId;
@@ -31,10 +32,19 @@ export const SETTINGS_NAV: SettingsNavGroup[] = [
{ id: "print-test", labelKey: "nav.printTest" },
],
},
{
id: "team",
labelKey: "nav.team",
children: [
{ id: "team-custom-roles", labelKey: "nav.customRoles" },
],
},
];
export const DEFAULT_SETTINGS_LEAF: SettingsLeafId = "shop-general";
export function groupForLeaf(leaf: SettingsLeafId): SettingsGroupId {
return leaf === "printer-config" || leaf === "print-test" ? "printer" : "shop";
if (leaf === "printer-config" || leaf === "print-test") return "printer";
if (leaf === "team-custom-roles") return "team";
return "shop";
}