Check-in Cooldown Scoping
Check-ins are deduplicated within a configurable window (default: 4 hours). The dedup key varies by method so that different kinds of interactions don’t block each other.
Dedup keys by method
| Method | Dedup key | Rationale |
|---|---|---|
nfc, phone, manual | member + shop | One physical visit per window |
purchase | member + shop | Auto check-in from in-store purchase, same as a visit |
qr | member + qrCodeId | Each QR code is a distinct waypoint — scanning two different codes is two valid check-ins |
event | member + externalEventId | One check-in per event, independent of shop visits |
Why per-method scoping
Off-site events
Dungeon Books runs events at the park, a partner cafe, etc. A QR code printed for the event acts as a mobile waypoint — members scan it to check in. This doesn’t share a cooldown with the shop kiosk, so they can visit the shop the same day and still check in there.
QR codes are the portable check-in primitive — no hardware, no kiosk setup. Print one, stick it on a table, and it’s a waypoint.
Scavenger hunts / quests
Multiple QR codes placed around the shop or neighborhood each have a unique qrCodeId. Members can scan all of them independently within the same cooldown window.
Hi.Events integration
Event attendance synced from Hi.Events uses externalEventId for dedup. A member attending an evening event at the shop can have both a daytime kiosk check-in and an event check-in.
Partner kiosks (quest hub)
Partner locations are separate shops, so kiosk check-ins already dedup independently. But if a partner uses a QR code instead of a kiosk, the QR dedup path keeps things clean without requiring a full shop record.
Buffs and events
The XP buff (issue #30) interacts well with the independent cooldown scoping. A typical event night flow:
- Member taps kiosk on the way in → 100 XP + “XP Surge” buff (2x, 60 min)
- Member buys something at the shop → purchase XP is doubled by the active buff
- Event starts, Hi.Events logs attendance → event check-in awards its own XP independently
The buff is a nice-to-have perk for showing up early, not a requirement. Members who skip the kiosk and go straight to the event still get their event XP — they just don’t get the bonus multiplier window. No one should feel forced to check in at the kiosk; it shouldn’t create a line before events.
This also naturally incentivizes event signups: members learn that events = more XP-earning opportunities while a buff is active.
Current state
The cooldown logic lives in src/lib/check-in.ts. Currently all methods dedup on member + shop. The qrCodeId and externalEventId fields exist on the CheckIns collection but aren’t used in the dedup query yet.
Related
- guild-kiosk: kiosk spec, NFC check-in flow
- guild-hi-events-integration: event attendance webhook
- guild-quest-hub-network: partner kiosks, QR as mobile waypoints
- Issue #30: XP buff system — different buff types per check-in method (kiosk → “XP Surge”, QR → “Merchant’s Blessing”, event → “Scholar’s Focus”)
- Issue #29: per-method check-in lingo (QR default: “Discovered a waypoint”)