<!-- BEGIN CHANGE: playbook de desenvolvimento do Novo Portal -->

# Portal dev playbook

## Stack real (2026)

| Camada | Tecnologia | Path |
|---|---|---|
| Front | Next.js 16 static export | `html/portal/` -> `out/` |
| API | PHP 8.3 PDO | `html/portal/api/` |
| i18n | Client `messages.ts` pt/en/es | nao e next-intl |
| Auth | HMAC Bearer 7d | `secret.key` no servidor |
| Deploy | `deploy/deploy.ps1` | `dev.whiteantidote.com` |

Docs antigos que citam `portal-api/` ou SSR Node no servidor estao **desatualizados** -- a API vive em `portal/api` e o front e estatico.

## Fluxo feature tipico

1. Ler `docs/portal-api-map.md` + regra `portal-security.mdc` se sensivel
2. API: endpoint novo ou estender existente; `waHeaders` + auth correta
3. Front: page + i18n (type + 3 locales) + Navbar se menu
4. Marcar `BEGIN CHANGE` / `END CHANGE`
5. `npm run build` local; `./deploy/deploy.ps1` ou `-Target test|beta` (ver `docs/portal-multi-env.md`)

## Espelhar legado

| Portal | Gesior |
|---|---|
| `/shop` | `shopsystem.php` + `shopguild.php` |
| `/character-market` | (novo; PP transfer) |
| `/donate` | donate + webhooks raiz |
| `/admin` | cpanel + shopadmin + CMS |
| `/character` | `characters.php` |
| `/guild` | `guilds.php` / manage |

Paridade ampla: `docs/parity-inventory.md`.

## Gaps conhecidos (UX)

- Nav `/guilds` sem page App Router (so `/guild?name=`)
- Hero/footer ainda com copy "em construcao" em partes
- Sem forum / houses list dedicada / item-serial page
- Download links estaticos

## Footguns Windows

- Em-dash / fancy quotes viram `?` -- use ASCII
- Nao colar Unicode via PowerShell inline; preferir `.py` UTF-8
- Comentarios em `config.lua` do OTX quebram parser do site -- so documentar em `docs/`

## Checklist PR / commit

- [ ] ACL correta se admin/money
- [ ] i18n pt/en/es + acentos
- [ ] Sem em-dash na UI
- [ ] Deploy API se mudou `.php`
- [ ] Testar conta de teste no DB live

<!-- END CHANGE -->