Skip to content

Clock in and out by tapping a card - #155

Open
wayx112 wants to merge 8 commits into
Team6083:mainfrom
wayx112:feat/card-tap-v2
Open

wayx112 wants to merge 8 commits into
Team6083:mainfrom
wayx112:feat/card-tap-v2

Conversation

@wayx112

@wayx112 wayx112 commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

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.

tap a linked card      ->  clocked in (or out if already in)        green / blue screen
tap an unlinked card   ->  QR code on the reader; scan it signed in   card linked to your account
  • Reader API: POST /api/admin/cards/tap with {"uid": ...}, for a reader program (e.g. a Raspberry Pi). It needs a new permission cards:tap (API_ROLES_CARDS_TAP). Results: clockedIn, clockedOut, locked (after the daily cut-off), tooShort (shorter than OVERHOURS_TIMELOG_MIN_DURATION_SEC, deleted like any clock-out), unbound (with a bindUrl).
  • Kiosk page: /kiosk turns a tablet into the reader. Sign in once with an admin, or an account with a role in API_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.
  • Linking: an unlinked card gets a one-time code, shown as a QR code to /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.
  • Card numbers: hex UIDs (4–10 bytes, any separators), or 8–20 decimal digits, which is what the USB reader we bought types (11 digits for a student ID).
  • Every tap counts: there is no cooldown between taps of the same card. A tap right after clocking in clocks out, and the minimum session length decides whether that session is kept, the same as on the web.
  • Clock-in: the tap uses the same per-user clock-in lock as the web (Stop simultaneous clock-ins from creating two open logs #144), so a tap and a web clock-in at once still make one log.

Evidence

On a local preview with a fake sign-in, typing the numbers like the USB reader (digits then Enter) on /kiosk:

an 11-digit number from the real reader  New card and a QR code (it was refused before)
a 10-digit number, open its bind link    the card is linked
the same number again                    一般成員 / Clocked in
the same number right after              Clocked out; once more: Clocked in
04A1B2C3 (linked hex card)               王小明 / Clocked out
/kiosk from another device on the LAN    loads; Full screen button bottom right

Also tried on a real tablet with the USB reader: tapping, linking and full screen work.

Test Files  26 passed (26)
     Tests  325 passed (325)

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 and npm run build pass.

Merge danger

Door: two-way for the code; adds two collections (Card, CardBindRequest) with unique indexes, so run npx prisma db push once 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 /kiosk works 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

wayx112 and others added 8 commits November 15, 2026 18:27
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

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant