branch crud and intergration

Frontend/erp-system/components/Layouts/AppSidebar.tsx

@@ -32,6 +32,7 @@ import {
   LineChart,
   ListTree,
   Lock,
+  MapPin,
   Menu,
   Package,
   PackageCheck,
@@ -212,6 +213,7 @@ const navItems: {
     icon: Settings,
     chevron: true,
     children: [
+      { title: "Branches", code: "settings.branches", href: "/dashboard/settings/branches", icon: MapPin },
       { title: "Roles", code: "settings.roles", href: "/dashboard/settings/roles", icon: ShieldCheck },
       { title: "Users", code: "settings.users", href: "/dashboard/settings/users", icon: Users },
       { title: "Configuration", code: "products.configuration", href: "/dashboard/settings/configuration", icon: SlidersHorizontal },

Frontend/erp-system/components/Layouts/Header.tsx

@@ -3,12 +3,15 @@
 import { useEffect, useState } from "react"
 import Link from "next/link"
 import { usePathname, useRouter } from "next/navigation"
-import { ArrowLeft, Bell, LogOut, Settings, User } from "lucide-react"
+import { ArrowLeft, Bell, Building2, LogOut, Settings, User } from "lucide-react"
 
 import { authApi } from "@/lib/api/auth"
 import { clearStoredUser, displayName, getStoredUser } from "@/lib/auth-session"
+import { branchesHrmApi } from "@/lib/api/hrm-masters"
 import { AuthUser } from "@/types/auth"
+import { Branch } from "@/types/hrm"
 import { cn } from "@/lib/utils"
+import { useAuth } from "@/components/auth/AuthProvider"
 import { ThemeToggle } from "@/components/theme-toggle"
 import { Avatar, AvatarFallback } from "@/components/ui/avatar"
 import { Badge } from "@/components/ui/badge"
@@ -20,6 +23,7 @@ import {
   DropdownMenuTrigger,
 } from "@/components/ui/dropdown-menu"
 import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover"
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select"
 
 /** Avatar initials from a display name: "ERP Admin" -> "EA", "erpadmin" -> "ER". */
 function initials(name: string): string {
@@ -166,9 +170,27 @@ export function Header() {
   const router = useRouter()
   const title = titleFromPath(pathname)
   const showBackButton = pathname !== "/dashboard"
+  const { isAdmin, branchName, activeBranchId, activeBranchName, setActiveBranch, branchingEnabled } = useAuth()
+  const branchLabel = isAdmin ? (activeBranchName ?? "All Branches") : branchName
   const [notifications, setNotifications] = useState(initialNotifications)
   const unreadCount = notifications.filter((n) => n.unread).length
 
+  const [branches, setBranches] = useState<Branch[]>([])
+  useEffect(() => {
+    if (!isAdmin || !branchingEnabled) return
+    branchesHrmApi.list({ pageSize: 200, status: "Active" }).then((r) => setBranches(r.items)).catch(() => setBranches([]))
+  }, [isAdmin, branchingEnabled])
+
+  const ALL_BRANCHES = "__all__"
+  function handleBranchChange(value: string | null) {
+    if (!value || value === ALL_BRANCHES) {
+      setActiveBranch(null, null)
+      return
+    }
+    const branch = branches.find((b) => String(b.branchId) === value)
+    setActiveBranch(branch?.branchId ?? null, branch?.name ?? null)
+  }
+
   // Read after mount so the first client render matches the server render.
   const [user, setUser] = useState<AuthUser | null>(null)
 
@@ -213,6 +235,36 @@ export function Header() {
       </div>
 
       <div className="flex shrink-0 items-center gap-1.5 sm:gap-3">
+        {branchingEnabled && (isAdmin ? (
+          <Select value={activeBranchId ? String(activeBranchId) : ALL_BRANCHES} onValueChange={handleBranchChange}>
+            <SelectTrigger
+              className="hidden h-8! shrink-0 gap-1.5 rounded-full border-transparent bg-muted px-2.5 text-xs font-medium text-muted-foreground hover:bg-muted/70 sm:flex"
+              aria-label="Switch branch"
+            >
+              <Building2 className="size-3.5" />
+              <SelectValue />
+            </SelectTrigger>
+            <SelectContent>
+              <SelectItem value={ALL_BRANCHES}>All Branches</SelectItem>
+              {branches.map((b) => (
+                <SelectItem key={b.branchId} value={String(b.branchId)}>
+                  {b.name}
+                </SelectItem>
+              ))}
+            </SelectContent>
+          </Select>
+        ) : (
+          branchLabel && (
+            <Badge
+              variant="outline"
+              className="hidden shrink-0 items-center gap-1.5 border-transparent bg-muted px-2.5 py-1 text-xs font-medium text-muted-foreground sm:flex"
+            >
+              <Building2 className="size-3.5" />
+              {branchLabel}
+            </Badge>
+          )
+        ))}
+
         <ThemeToggle />
 
         <Popover>
@@ -298,6 +350,12 @@ export function Header() {
                 {user ? displayName(user) : "Signed in"}
               </p>
               {user?.email && <p className="text-sm font-normal text-muted-foreground">{user.email}</p>}
+              {branchLabel && (
+                <p className="mt-1 flex items-center gap-1.5 text-sm font-normal text-muted-foreground">
+                  <Building2 className="size-3.5" />
+                  {branchLabel}
+                </p>
+              )}
             </div>
             <DropdownMenuSeparator />
             <DropdownMenuItem

Frontend/erp-system/components/auth/AuthProvider.tsx

@@ -9,10 +9,53 @@ import { createContext, useContext, useEffect, useState } from "react"
 import { authApi } from "@/lib/api/auth"
 import { MeResponse } from "@/types/rbac"
 
+interface ActiveBranch {
+  id: number | null
+  name: string | null
+}
+
+/** Admin's last-picked header branch, kept per-browser (docs/BRANCH_ISOLATION_PLAN.md
+ * §Frontend impact: "a current branch selector... persisted per session"). Purely a
+ * display/filter convenience — never trusted server-side. */
+const ACTIVE_BRANCH_KEY = "erpcore.activeBranch"
+
+function readStoredActiveBranch(): ActiveBranch | null {
+  if (typeof window === "undefined") return null
+  const raw = window.localStorage.getItem(ACTIVE_BRANCH_KEY)
+  if (!raw) return null
+  try {
+    return JSON.parse(raw) as ActiveBranch
+  } catch {
+    window.localStorage.removeItem(ACTIVE_BRANCH_KEY)
+    return null
+  }
+}
+
 interface AuthContextValue {
   roleCode: string | null
   roleName: string | null
   navCodes: string[]
+  /** True for the Admin role — the only role that may pick any branch (others are locked to their own). */
+  isAdmin: boolean
+  /** The caller's own branch, via their linked Employee record — null if unlinked. */
+  branchId: number | null
+  branchName: string | null
+  /**
+   * The branch currently being "worked in": for non-admins this always mirrors their own
+   * branch; for an Admin it's whichever branch they last picked in the header (null = "All
+   * Branches"), persisted per-browser. Screens that want to filter by "the branch the user
+   * is currently viewing" should read this, not `branchId`.
+   */
+  activeBranchId: number | null
+  activeBranchName: string | null
+  /** Admin-only — switches the header's active branch. A no-op for any other role. */
+  setActiveBranch: (id: number | null, name: string | null) => void
+  /**
+   * The deployment-wide toggle (Settings → Configuration → Branch Configuration). False
+   * means this deployment doesn't use branches at all — every branch picker/badge in the
+   * app should be hidden entirely, not merely restricted by role.
+   */
+  branchingEnabled: boolean
   /** True until the first `/auth/me` response lands. */
   loading: boolean
 }
@@ -21,11 +64,19 @@ const AuthContext = createContext<AuthContextValue>({
   roleCode: null,
   roleName: null,
   navCodes: [],
+  isAdmin: false,
+  branchId: null,
+  branchName: null,
+  activeBranchId: null,
+  activeBranchName: null,
+  setActiveBranch: () => {},
+  branchingEnabled: true,
   loading: true,
 })
 
 export function AuthProvider({ children }: { children: React.ReactNode }) {
   const [me, setMe] = useState<MeResponse | null>(null)
+  const [activeBranch, setActiveBranchState] = useState<ActiveBranch | null>(null)
 
   useEffect(() => {
     let cancelled = false
@@ -37,19 +88,39 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
       .catch(() => {
         // Unauthenticated/unreachable — fall back to "no permissions" rather than
         // crash the shell; proxy.ts already redirects unauthenticated users to /login.
-        if (!cancelled) setMe({ roleCode: null, roleName: null, navCodes: [] })
+        if (!cancelled) setMe({ roleCode: null, roleName: null, navCodes: [], isAdmin: false, branchId: null, branchName: null, branchingEnabled: true })
       })
     return () => {
       cancelled = true
     }
   }, [])
 
+  useEffect(() => {
+    if (me === null) return
+    // Non-admins are always pinned to their own branch — never their own past picks.
+    setActiveBranchState(me.isAdmin ? (readStoredActiveBranch() ?? { id: null, name: null }) : { id: me.branchId, name: me.branchName })
+  }, [me])
+
+  function setActiveBranch(id: number | null, name: string | null) {
+    if (!me?.isAdmin) return
+    const next = { id, name }
+    setActiveBranchState(next)
+    if (typeof window !== "undefined") window.localStorage.setItem(ACTIVE_BRANCH_KEY, JSON.stringify(next))
+  }
+
   return (
     <AuthContext.Provider
       value={{
         roleCode: me?.roleCode ?? null,
         roleName: me?.roleName ?? null,
         navCodes: me?.navCodes ?? [],
+        isAdmin: me?.isAdmin ?? false,
+        branchId: me?.branchId ?? null,
+        branchName: me?.branchName ?? null,
+        activeBranchId: activeBranch?.id ?? null,
+        activeBranchName: activeBranch?.name ?? null,
+        setActiveBranch,
+        branchingEnabled: me?.branchingEnabled ?? true,
         loading: me === null,
       }}
     >

Frontend/erp-system/components/settings/BranchMasterPage.tsx

@@ -0,0 +1,191 @@
+"use client"
+
+// Dedicated Branch list/create/deactivate screen — Branch diverges from the plain
+// "code + name" HRM masters (CodeNameMasterPage): its code is server-generated
+// (never entered), and it carries Address + Phone Number too. Shared by both
+// entry points (Settings → Branches and HRM → Settings → Branches) since Branch
+// is a cross-cutting concept now, not HRM-specific.
+import { useEffect, useState } from "react"
+import { Plus } from "lucide-react"
+
+import { branchesHrmApi } from "@/lib/api/hrm-masters"
+import { errorMessage } from "@/lib/error-map"
+import { cn } from "@/lib/utils"
+import { Branch } from "@/types/hrm"
+import { EntityStatus, PaginationMeta } from "@/types/common"
+
+import { Button } from "@/components/ui/button"
+import { Input } from "@/components/ui/input"
+import { Badge } from "@/components/ui/badge"
+import { Field, FieldError, FieldGroup, FieldLabel } from "@/components/ui/field"
+import { Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle, DialogTrigger } from "@/components/ui/dialog"
+import { Skeleton } from "@/components/ui/skeleton"
+import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table"
+import { toast } from "@/components/ui/toast"
+
+export function BranchMasterPage() {
+  const PAGE_SIZE = 10
+  const [items, setItems] = useState<Branch[] | null>(null)
+  const [pagination, setPagination] = useState<PaginationMeta | null>(null)
+  const [error, setError] = useState<string | null>(null)
+  const [page, setPage] = useState(1)
+
+  const [open, setOpen] = useState(false)
+  const [name, setName] = useState("")
+  const [address, setAddress] = useState("")
+  const [phoneNumber, setPhoneNumber] = useState("")
+  const [errors, setErrors] = useState<Record<string, string>>({})
+  const [submitting, setSubmitting] = useState(false)
+
+  function load() {
+    branchesHrmApi
+      .list({ page, pageSize: PAGE_SIZE })
+      .then((res) => {
+        setItems(res.items)
+        setPagination(res.pagination)
+      })
+      .catch((err) => setError(errorMessage(err)))
+  }
+
+  useEffect(load, [page])
+
+  function resetForm() {
+    setName("")
+    setAddress("")
+    setPhoneNumber("")
+    setErrors({})
+  }
+
+  async function handleCreate() {
+    const nextErrors: Record<string, string> = {}
+    if (!name.trim()) nextErrors.name = "Name is required"
+    setErrors(nextErrors)
+    if (Object.keys(nextErrors).length > 0) return
+
+    setSubmitting(true)
+    try {
+      await branchesHrmApi.create({
+        name: name.trim(),
+        address: address.trim() || null,
+        phoneNumber: phoneNumber.trim() || null,
+      })
+      toast.success("Branch created")
+      setOpen(false)
+      resetForm()
+      load()
+    } catch (err) {
+      toast.error("Could not create branch", errorMessage(err))
+    } finally {
+      setSubmitting(false)
+    }
+  }
+
+  async function toggleStatus(item: Branch) {
+    const next: EntityStatus = item.status === "Active" ? "Inactive" : "Active"
+    try {
+      await branchesHrmApi.updateStatus(item.branchId, next)
+      load()
+    } catch (err) {
+      toast.error("Could not update status", errorMessage(err))
+    }
+  }
+
+  return (
+    <div className="flex flex-col gap-6">
+      <div className="flex items-center justify-between">
+        <div>
+          <h1 className="text-2xl font-bold text-foreground">Branches</h1>
+          <p className="text-base text-muted-foreground">Company branches/locations — used for multi-branch scoping.</p>
+        </div>
+        <Dialog open={open} onOpenChange={(next) => { setOpen(next); if (!next) resetForm() }}>
+          <DialogTrigger render={<Button size="lg"><Plus className="size-5" />New</Button>} />
+          <DialogContent className="sm:max-w-sm">
+            <DialogHeader className="items-center text-center">
+              <DialogTitle>New Branch</DialogTitle>
+              <DialogDescription>Code is generated automatically. Deactivate later — branches are never deleted.</DialogDescription>
+            </DialogHeader>
+            <FieldGroup>
+              <Field data-invalid={!!errors.name}>
+                <FieldLabel htmlFor="branch-name">Name</FieldLabel>
+                <Input id="branch-name" value={name} onChange={(e) => setName(e.target.value)} aria-invalid={!!errors.name} />
+                <FieldError errors={[errors.name ? { message: errors.name } : undefined]} />
+              </Field>
+              <Field>
+                <FieldLabel htmlFor="branch-address">Address</FieldLabel>
+                <Input id="branch-address" value={address} onChange={(e) => setAddress(e.target.value)} />
+              </Field>
+              <Field>
+                <FieldLabel htmlFor="branch-phone">Phone Number</FieldLabel>
+                <Input id="branch-phone" value={phoneNumber} onChange={(e) => setPhoneNumber(e.target.value)} />
+              </Field>
+            </FieldGroup>
+            <div className="flex justify-center gap-3 pt-2">
+              <Button variant="outline" className="min-w-32" onClick={() => setOpen(false)} disabled={submitting}>Cancel</Button>
+              <Button className="min-w-32" onClick={handleCreate} disabled={submitting}>{submitting ? "Creating…" : "Create"}</Button>
+            </div>
+          </DialogContent>
+        </Dialog>
+      </div>
+
+      {error && <div className="rounded-lg border border-destructive/30 bg-destructive/5 p-5 text-base text-destructive">{error}</div>}
+
+      {!error && items === null && (
+        <div className="flex flex-col gap-3">{Array.from({ length: 4 }).map((_, i) => <Skeleton key={i} className="h-14 w-full" />)}</div>
+      )}
+
+      {!error && items !== null && items.length === 0 && (
+        <div className="flex flex-col items-center gap-4 rounded-xl border border-dashed py-20 text-center">
+          <p className="text-base text-muted-foreground">No branches yet.</p>
+        </div>
+      )}
+
+      {!error && items !== null && items.length > 0 && (
+        <Table className="text-base">
+          <TableHeader>
+            <TableRow>
+              <TableHead className="h-12 px-3 text-sm">Code</TableHead>
+              <TableHead className="h-12 px-3 text-sm">Name</TableHead>
+              <TableHead className="h-12 px-3 text-sm">Address</TableHead>
+              <TableHead className="h-12 px-3 text-sm">Phone Number</TableHead>
+              <TableHead className="h-12 px-3 text-sm">Status</TableHead>
+              <TableHead className="h-12 px-3 text-sm">Actions</TableHead>
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            {items.map((item) => (
+              <TableRow key={item.branchId}>
+                <TableCell className="px-3 py-3.5 font-medium">{item.code}</TableCell>
+                <TableCell className="px-3 py-3.5">{item.name}</TableCell>
+                <TableCell className="px-3 py-3.5 text-muted-foreground">{item.address ?? "—"}</TableCell>
+                <TableCell className="px-3 py-3.5 text-muted-foreground">{item.phoneNumber ?? "—"}</TableCell>
+                <TableCell className="px-3 py-3.5">
+                  <Badge variant="outline" className={cn("h-6 w-fit justify-center border-transparent px-2.5 text-sm", item.status === "Active" ? "bg-success/10 text-success" : "bg-muted text-muted-foreground")}>
+                    {item.status}
+                  </Badge>
+                </TableCell>
+                <TableCell className="px-3 py-3.5">
+                  <Button variant="ghost" size="sm" onClick={() => toggleStatus(item)}>
+                    {item.status === "Active" ? "Deactivate" : "Activate"}
+                  </Button>
+                </TableCell>
+              </TableRow>
+            ))}
+          </TableBody>
+        </Table>
+      )}
+
+      {pagination && pagination.totalPages > 1 && (
+        <div className="flex items-center justify-between">
+          <p className="text-sm text-muted-foreground">
+            Showing {(pagination.page - 1) * pagination.pageSize + 1}–{Math.min(pagination.page * pagination.pageSize, pagination.totalItems)} of {pagination.totalItems}
+          </p>
+          <div className="flex items-center gap-2">
+            <Button type="button" variant="outline" size="sm" disabled={pagination.page <= 1} onClick={() => setPage((p) => Math.max(1, p - 1))}>Previous</Button>
+            <span className="text-sm text-muted-foreground">Page {pagination.page} of {pagination.totalPages}</span>
+            <Button type="button" variant="outline" size="sm" disabled={pagination.page >= pagination.totalPages} onClick={() => setPage((p) => Math.min(pagination.totalPages, p + 1))}>Next</Button>
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}