98 lines
6.5 KiB
Markdown
98 lines
6.5 KiB
Markdown
# HANDOFF.md — Session Handoff (OVERWRITE at the end of every phase or when context is getting long)
|
||
|
||
> **Read order for a new session:** `NOTES.md` → `STATUS.md` → this file → then work.
|
||
> If this file disagrees with the code, trust the code and fix this file.
|
||
|
||
## 1. Where we are
|
||
- **Last completed step:** 9.2 (seed-dev script — creates demo account + hero) — TICKED in STATUS.md
|
||
- **Next step:** Phase 9 — 9.3 (Global error pages / friendly UI error toasts. Loading states.)
|
||
- **Updated:** 2026-10-21
|
||
- **Was the last session cut off mid-task?** No
|
||
|
||
## 2. Verified state (run these first)
|
||
| Command | Expected |
|
||
|---|---|
|
||
| `npm install` | succeeds |
|
||
| `npm run migrate` | applies 001–006 / "nothing to do" |
|
||
| `npm test` | **172 passing, 0 failing** (85 unit + 87 integration) |
|
||
| `npm run seed:dev` | creates demo user "demo"/"demo123", hero "Aldric" (warrior), starter gear |
|
||
|
||
## 3. What exists now (files that matter)
|
||
- `public/profile.html` — Public hero profile page (reads ?name=, displays stats/equipment).
|
||
- `public/js/profile.js` — Fetches GET /api/heroes/:name, renders profile, handles 404.
|
||
- `public/game.html` — Dashboard with stats panel, tabbed action panel (Hunt/Inventory/Expedition).
|
||
- `public/js/game.js` — hunt UI + inventory UI + expedition UI.
|
||
- `public/shop.html` — Dedicated shop page.
|
||
- `public/login.html`, `public/register.html`, `public/create-hero.html` — Auth & hero creation.
|
||
- `scripts/seed-dev.js` — Creates demo account + hero + starter gear (idempotent, skips in production).
|
||
- `src/services/heroProfileService.js` — `getHeroProfile(heroName)`.
|
||
- `src/routes/heroProfile.js` — `GET /api/heroes/:name` (public).
|
||
- `src/services/leaderboardService.js` — `getLeaderboard(type, page, limit)`.
|
||
- `src/routes/leaderboard.js` — `GET /api/leaderboard?type=level|gold|kills`.
|
||
- `src/services/expeditionService.js` — start, getActive, claim, listDefinitions.
|
||
- `src/routes/expeditions.js` — 4 expedition endpoints.
|
||
- `src/services/shopService.js` — getStock, buyItem, sellItem.
|
||
- `src/routes/shop.js` — GET/POST shop endpoints.
|
||
- `src/services/inventoryService.js` — listInventory, equipItem, unequipItem, useConsumable.
|
||
- `src/services/huntService.js` — hunt (one transaction).
|
||
- `src/services/characterService.js` — createCharacter, getCharacterProfile, getCharacterIdForUser.
|
||
- `src/services/authService.js` — register, verifyLogin.
|
||
- `src/game/combat.js` — resolveCombat.
|
||
- `src/game/stats.js` — calcDerived, xpToNext, checkLevelUp.
|
||
- `src/game/energy.js` — computeEnergy.
|
||
- `src/utils/time.js` — now()/setNow()/resetNow().
|
||
- `src/app.js` — Express app with helmet, rate limiters (auth + general /api), all routes.
|
||
- `src/middleware/session.js` — session store, requireAuth.
|
||
- `src/config/index.js` — env validation, frozen config.
|
||
- `tests/integration/*.test.js` — 87 integration tests across auth, combat, hunt, inventory, shop, expeditions, profile, leaderboard.
|
||
- `tests/unit/*.test.js` — 85 unit tests for game logic.
|
||
|
||
## 4. Half-finished / fragile things
|
||
- No leaderboard UI yet (Phase 8 API done but no UI).
|
||
- HP never regenerates naturally; only level-up restores it.
|
||
- No restart-persistence test for sessions.
|
||
- `npm run seed` script in package.json points to nonexistent `scripts/seed.js`.
|
||
- Equipment bonuses not yet passed into combat (Issue #5 in STATUS.md).
|
||
- Starter gear (GAME_DESIGN.md §Items) documented but not auto-created on character creation.
|
||
- `GET /api/zones` documented in API.md but not implemented (Issue #2).
|
||
- Step 9.3 (error pages/toasts/loading states) not yet implemented.
|
||
|
||
## 5. Decisions & deviations from the docs
|
||
- D-004..D-007 in `docs/DECISIONS.md` (combat rounds, equipment counted once, session store, clock).
|
||
- Zod query param parsing uses `zod.coerce.number()` because Express query params are strings.
|
||
- Inventory response uses `itemId` (item.id) and `inventoryId` (inventory row id) to avoid confusion.
|
||
- Consumable effect parsing: regex `^(heal|energy):(\d+)$` on items.effect field.
|
||
- Qty decrement avoids CHECK constraint violation: delete directly when qty==1, decrement when qty>1.
|
||
- **D-008:** Shop materials with buy_price=0 sell at `floor(default_rate * character_level / item_min_level)`.
|
||
- **D-009:** `sellItem` checks equipped_slot before material type.
|
||
- **D-010:** `startExpedition` checks active-expedition before energy.
|
||
- **D-011:** `computeEnergy` uses `now()` from utils/time.
|
||
- **D-012:** General `/api` rate limiter at 120 req/min per IP (SECURITY.md spec), 1000 in test mode.
|
||
- **D-013:** All `innerHTML` with dynamic data removed from game.js and profile.js — use createElement/textContent.
|
||
|
||
## 6. Gotchas learned
|
||
- `npm test` must be `node --test` with NO path/glob; files must be named `*.test.js`.
|
||
- better-sqlite3-session-store ignores `expired.clear: false`; that's why the timer is unref'd.
|
||
- Statement caches are per-DB-handle (WeakMap) in huntService; copy that pattern for new services.
|
||
- Verify test COUNT, not just "all passing".
|
||
- Node.js `fetch` doesn't persist cookies across calls — extract `Set-Cookie` header and pass manually in integration tests.
|
||
- SQL `SELECT id` from inventory returns the auto-increment row id; rename with `AS inventory_id` when you also need `item_id`.
|
||
- Transaction callback args must match the call order exactly.
|
||
- Error responses from route-level `AppError`s do NOT include `data` field.
|
||
- `setNow` affects ALL `now()` calls including those in service logic.
|
||
- Shop API returns `{ ok: true, data: { stock: [...], character: {...} } }` — field is `stock`, not `stocks`.
|
||
- Shop stock items have flat fields (`itemId`, `buyPrice`), not nested (`item.id`).
|
||
- New characters have NO inventory items (starter gear not auto-created yet).
|
||
- Hero profile endpoint is PUBLIC — no `requireAuth` middleware.
|
||
- Profile page is public: no auth.js guard needed; uses ?name= query param for lookup.
|
||
- Rate limiters in tests: set `NODE_ENV=test` to get 1000 req/window limit; otherwise tests fail with 429.
|
||
- `seed-dev.js` must check `NODE_ENV=production` before any `require()` that loads config (config throws on placeholder SECRET).
|
||
|
||
## 7. Next-step briefing (9.3)
|
||
- **Goal:** Add global error pages / friendly UI error toasts. Loading states.
|
||
- **Docs:** UI_GUIDE, SECURITY (for error handling), TESTING.
|
||
- Should: add a generic 404/500 error page template in `public/`.
|
||
- Should: add a toast notification system (JS + CSS) for user-facing errors.
|
||
- Should: add loading spinners/states for async operations (hunt, buy, etc.).
|
||
- Should NOT introduce new dependencies — use vanilla HTML/CSS/JS.
|