Repository navigation
Conversation
Clocking in means opening the site and pressing a button, which people forget or skip when their hands are full. Most members already carry an NFC student ID. A card reader (for example a Raspberry Pi with an NFC module) posts the card's UID to `POST /api/admin/cards/tap` with a Keycloak token that has the new `cards:tap` permission. A linked card clocks its user in, or out if they are clocked in; a second tap within 15 seconds is ignored. An unlinked card gets a link the reader can show as a QR code; the next unlinked tap replaces it, so only the code on screen works. Opening it signed in links the card to yourself, and an admin can link it to any member. Admins see and remove a user's cards on their user page, and merging users moves their cards. `clockIn` / `clockOut` are split into a session check and `clockInUser` / `clockOutUser` so the reader route can reuse them. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A tablet at the door is easier to set up and maintain than a Raspberry Pi with its own program, and it can show who was clocked in and the QR code for a new card. `/kiosk` fills the screen for an account that may tap cards (an admin, or a role in `API_ROLES_CARDS_TAP`, now carried in the session as `canTapCards`). It takes UIDs typed by a USB reader in keyboard mode, or reads cards with Web NFC on Android Chrome. It shows the member's name and whether they were clocked in or out. An unlinked card's QR code stays on screen through linked taps until the card is linked or another unlinked card replaces it. Adds `qrcode` to draw the QR code. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The clock is rendered on the server and again in the browser a moment later, so the seconds differ and React reported a hydration mismatch on every load. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The 15-second cooldown read lastUsedAt and then wrote it, so two taps arriving together (a reader sending twice) both passed: one clocked in and the other either failed or clocked straight back out. The cooldown is now claimed in one conditional update, and a clock-in or clock-out that someone else did at the same moment is reported as clocked in or out instead of an error. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The USB reader for the kiosk types the card as 11 decimal digits (and many such readers do), which isn't 4–10 bytes of hex, so every tap was refused as unreadable. 8–20 digits are now kept as they are. The same reader always gives a card the same number, so binding and tapping match; a card read in hex by another reader won't. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A second tap of the same card within 15 seconds was ignored ("Already tapped just now"), so someone who tapped out by mistake, or tapped again to fix it, had to wait. Every tap now clocks in or out. A session that ends too soon is handled like any other clock-out: shorter than OVERHOURS_TIMELOG_MIN_DURATION_SEC, it is deleted. A reader that sends one tap twice will now clock in and straight back out.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
On a tablet, Chrome keeps its address and status bars over the kiosk, and Android Chrome has no full-screen option of its own. A button in the corner now puts the page in full screen; it hides while in full screen, and Back leaves it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Members clock in and out on the website, which needs a phone and a sign-in each time. This lets them tap an NFC card, such as a student ID, on a reader at the door instead.
POST /api/admin/cards/tapwith{"uid": ...}, for a reader program (e.g. a Raspberry Pi). It needs a new permissioncards:tap(API_ROLES_CARDS_TAP). Results:clockedIn,clockedOut,locked(after the daily cut-off),tooShort(shorter thanOVERHOURS_TIMELOG_MIN_DURATION_SEC, deleted like any clock-out),unbound(with abindUrl)./kioskturns a tablet into the reader. Sign in once with an admin, or an account with a role inAPI_ROLES_CARDS_TAP(session.user.canTapCards, checked at sign-in and on each token refresh). It takes UIDs from a USB reader in keyboard mode (UID then Enter), or the tablet's own NFC on Android Chrome (Web NFC). A full-screen button hides the browser's bars./cards/bind?code=.... Only the latest code works, so a QR code left on someone's phone stops working. Admins see and remove cards on/admin/users/{id}; merging users moves their cards.Evidence
On a local preview with a fake sign-in, typing the numbers like the USB reader (digits then Enter) on
/kiosk:Also tried on a real tablet with the USB reader: tapping, linking and full screen work.
New tests cover the tap API, the kiosk action, card numbers, and
card-dto(binding, codes being replaced, clock in/out, someone else clocking in at the same moment, card moves on user merge).tsc --noEmit, ESLint on the changed files andnpm run buildpass.Merge danger
Door: two-way for the code; adds two collections (
Card,CardBindRequest) with unique indexes, so runnpx prisma db pushonce after deploying. Nothing existing changes shape.Blast radius: new pages and one new API route; clock-in and clock-out only gain session-free entry points (
clockInUser,clockOutUser) that the web paths now call after their own checks.Tested on hardware: a tablet with the USB reader on
/kioskworks end to end. A reader that sends one tap twice would clock in and straight back out; this one doesn't.🤖 Generated with Claude Code