fffcb73ea4
Google-SSO PWA for bistro employee clock-in/out, admin employee management, and stats with CSV export. Express + SQLite backend, React + Zustand frontend in the light-mono-tui design language. Multi-stage Dockerfile, compose.yaml for image-based deploys, nginx reverse-proxy template, and an OKF documentation bundle in docs/. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
63 lines
2.9 KiB
Markdown
63 lines
2.9 KiB
Markdown
---
|
|
type: Frontend Module
|
|
title: Zustand stores
|
|
description: authStore, attendanceStore, and adminStore — where all app/fetch logic lives, keeping components thin.
|
|
resource: frontend/src/store
|
|
tags: [frontend, zustand, state]
|
|
timestamp: 2026-08-12T00:00:00Z
|
|
---
|
|
|
|
# Zustand stores
|
|
|
|
Convention (matching the user's other `~/mywork` projects): one flat
|
|
`create<State>()` per concern in `frontend/src/store/<name>Store.ts`,
|
|
default-exported as `use<Name>Store`. State and actions live together;
|
|
async/API calls are colocated directly in the actions via `set`/`get` — no
|
|
separate service layer. No `persist`/`devtools`/`immer`/slices are used
|
|
here. Components read via selectors (`useXStore(s => s.field)`) and call
|
|
actions; they don't own fetch/interval logic themselves.
|
|
|
|
# `authStore.ts`
|
|
|
|
`{ user, loading, loginError }` + `init()` (calls `GET /auth/me` once on
|
|
app mount, from `App.tsx`), `loginWithGoogle(credential)`, `logout()`. No
|
|
persistence — the real session lives in the httpOnly cookie, so on reload
|
|
the store just re-asks the backend via `init()`.
|
|
|
|
# `attendanceStore.ts`
|
|
|
|
Employee's own clock state. `{ status, stats, live, busy, error }` plus
|
|
`load()`, `recordEvent(type)`, `startPolling()`/`stopPolling()`.
|
|
|
|
- `startPolling` sets two intervals: one that calls `load()` every 60s
|
|
(keeps the server truth in sync), and one that recomputes `live` every
|
|
1s from the last-fetched `stats` against a fresh `Date` — via
|
|
`withLiveTime` (`frontend/src/lib/liveSession.ts`) — so an open shift's
|
|
duration counts up smoothly instead of freezing until the next poll.
|
|
`EmployeeApp.tsx` starts/stops this based on `status` (only polls while
|
|
`working`/`on_break`).
|
|
- **Gotcha this hit in practice**: `live` is a plain cached field, updated
|
|
by `set()` inside the tick/poll callbacks — it is deliberately *not* a
|
|
selector method like `liveStats: () => withLiveTime(...)` called as
|
|
`useAttendanceStore(s => s.liveStats())`. That pattern returns a new
|
|
object on every call, which breaks React's `useSyncExternalStore`
|
|
(used internally by zustand v5) — "Maximum update depth exceeded" from an
|
|
infinite render loop, since the snapshot is never referentially stable
|
|
between renders even when nothing actually changed.
|
|
|
|
# `adminStore.ts`
|
|
|
|
Employee list + org/individual stats + the shared `month` ("YYYY-MM") used
|
|
by both the summary table and the selected employee's detail chart.
|
|
`setMonth`/`prevMonth`/`nextMonth` update `month` and re-fetch `loadStats()`
|
|
plus (if an employee is selected) `selectEmployee()` together, so the
|
|
summary and the detail chart always show the same period. `removeEmployee`
|
|
calls the soft-delete endpoint — see [employees](/docs/data-model/employees.md).
|
|
|
|
# Related
|
|
|
|
- [attendance_events](/docs/data-model/attendance-events.md) — the state
|
|
machine and `Session` shape these stores fetch
|
|
- [Attendance API](/docs/api/attendance-routes.md)
|
|
- [Admin API](/docs/api/admin-routes.md)
|