minigame

name

minigame

description

Work on the Minigame tool — the Jackpot slot-machine game (and four scaffolded-but-unimplemented types: luckyWheel, gashapon, drawLots, scratchOff) that workspaces create, share a public play link for, and track plays/prizes for. Use when touching minigame CRUD, the type picker, prize/draw logic, the public play page or play token, the jackpot preview UI, or extending gameplay to a new minigame type. Read this BEFORE editing anything under `features/minigames`, `business/src/minigame`, or `minigame-play-token` to avoid the silent "only jackpot works" traps.

Minigame (Jackpot)

Where things live

Concern	Path
DB tables (Minigame, MinigameContact, MinigamePlay)	packages/database/src/schema/minigame{,-contact,-play}.ts
Relations	packages/database/src/relations/minigame{,-contact,-play}.ts, wired into relations/index.ts
Zod partials (single source for all 6 jsonb settings columns)	packages/database/src/partials/minigame.ts
CRUD + prize-quantity reconciliation	packages/business/src/minigame/service.ts (minigameService)
Prize draw math	packages/business/src/minigame/resolve-prize.ts (resolveMinigamePrize)
Play state, draw, dispatch (concurrency-critical)	packages/business/src/minigame/minigame-contact-service.ts (minigameContactService)
Play token sign/verify (24h TTL)	packages/encryption/src/minigame-play-token.ts
{{minigame_play_token}} system variable	packages/variables/src/utils.ts (systemFieldTypes.enum.minigame_play_token), enum in packages/database/src/partials/contact.ts
Builder feature (admin CRUD, form, dialogs)	apps/builder/src/features/minigames/
Type picker dialog	apps/builder/src/features/minigames/components/create-minigame-type-dialog.tsx
Public play page (auth-bypassed)	apps/builder/src/app/minigames/page.tsx, registered in apps/builder/src/proxy.ts (publicRoutes)
Public play action	apps/builder/src/features/minigames/actions/play-minigame.action.ts (actionClient, NOT workspace-scoped)
Jackpot play screen (client, slot animation)	apps/builder/src/features/minigames/components/play/jackpot-play-screen.tsx
Jackpot SVG art + start button	packages/minigame-ui/ (JackpotMachineArt, JackpotStartButton)
Admin/type-picker previews	apps/builder/src/features/minigames/components/preview/ (MinigamePreview dispatches jackpot → JackpotPreview, else GenericMinigamePreview)
Default settings + type config	apps/builder/src/features/minigames/constants.ts
Tests	packages/business/__tests__/{minigame-service-update,resolve-minigame-prize}.test.ts, packages/encryption/__tests__/minigame-play-token.test.ts

No worker/queue code exists for minigames — grep confirms zero hits in apps/worker/packages/worker-config. Everything runs synchronously in builder server actions/pages; outcome messages are dispatched via the pre-existing chatQueue/integrationQueue from inside recordPlayAndDispatch, not a dedicated queue.

Data flow in one line

create/edit minigame (builder) → {{minigame_play_token}} resolved into a shared link at message-send time → public /minigames?minigameId&token page → verify token → resolvePlayState → JackpotPlayScreen → playMinigameAction → recordPlayAndDispatch (draw prize, decrement stock, send outcome message).

The traps (read before editing)

1. "Only Jackpot is playable" is enforced in FOUR separate un-linked places, with no compiler-enforced fan-out. Unlike the ChannelType cascade (repo invariant #3, a Record<ChannelType,...> breaks the build if you miss a case), MinigameType has no such guard:

   • MINIGAME_TYPES_ENABLED_FOR_CREATION = ["jackpot"] in constants.ts — gates the type picker only.
   • play-minigame.action.ts — if (minigame.type !== minigameTypes.enum.jackpot) throw ....
   • apps/builder/src/app/minigames/page.tsx — if (minigame.type !== "jackpot") return <MinigameNotice comingSoon>.
   • MinigamePreview — if (type === "jackpot") return <JackpotPreview> else generic placeholder. Extending gameplay to a second type means updating all four, and forgetting one compiles fine and fails silently (wrong UI shown, or a 403 that looks like a bug). If you add a type, search for every === "jackpot" / !== "jackpot" / minigameTypes.enum.jackpot literal first — do not assume the list above is exhaustive by the time you read this.

2. Concurrency-critical code lives in minigame-contact-service.ts — read reliability-concurrency skill before touching it. drawPrize, resolvePlayState, and MinigameService.update's prize-quantity reconciliation all depend on SELECT ... FOR UPDATE locks taken inside the caller's transaction, plus insert().onConflictDoNothing() for the first-play race on MinigameContact_minigameId_contactId_key. Do not replace these with an application-level check-then-write — that's exactly the race these patterns close. recordPlayAndDispatch deliberately sends the outcome message outside the transaction (fire-and-forget, .catch(() => {})) so a failed message send never rolls back an already-recorded play — don't move message dispatch inside the transaction "to be safe."

3. No probability redistribution when a prize sells out. drawPrize filters out prizes with quantity <= 0 before drawing, but does not rescale the remaining winRates — the excluded prize's share silently becomes extra lose-rate. This is intentional and tested ('s sold-out case) — don't "fix" it by redistributing without checking that test first.

Adding gameplay for a new minigame type (recipe)

1. Add the type's UI (preview, form fields, play screen) — mirror the jackpot components under components/preview/ and components/play/.
2. Flip MINIGAME_TYPES_ENABLED_FOR_CREATION in constants.ts to include it.
3. Update the type gate in play-minigame.action.ts and app/minigames/page.tsx (trap #1 — grep for every "jackpot" literal, don't trust this list to be complete).
4. Extend MinigamePreview's dispatch to route to the new type's preview.
5. If the new type needs its own appearance/settings shape, extend the discriminated unions in packages/database/src/partials/minigame.ts rather than overloading the jackpot-shaped fields.
6. Add/extend tests mirroring resolve-minigame-prize.test.ts if draw logic changes.

i18n

Namespace minigames.* in apps/builder/messages/en.json. This repo's invariant applies in full: update all locale files under apps/builder/messages/ (19 translated locales + en.json), not just English — see the minigames.* keys added across all of them in the feature's introducing commit as the reference pattern.

Verify

pnpm --filter @chatbotx.io/business vitest run __tests__/minigame-service-update.test.ts __tests__/resolve-minigame-prize.test.ts
pnpm --filter @chatbotx.io/encryption vitest run __tests__/minigame-play-token.test.ts
pnpm --filter builder check-types
pnpm lint

No automated test covers the public play page/action or the builder CRUD UI — verify those manually: create a jackpot minigame, open the public /minigames?minigameId=...&token=... link, play until draws run out, and confirm the history table in the builder reflects the plays.