Projeto Profissional

Projeto Profissional — base template for new repos

Pedro's canonical starting point for any new web project. Instead of scaffolding from scratch (and re-deciding security every time), copy the vetted template and adapt it.

Template location: /home/pedro/Repositorios/templates/projeto-profissional (git-initialised, 44 passing tests, boot-verified, load-tested with real k6 numbers).

Origin: distilled from /home/pedro/Repositorios/academicos/sistema-academico, keeping that project's layered architecture but stripping the academic domain.

When to use

• "cria um projeto novo / um repositório novo / o primeiro commit"
• "quero um modelo base pro meu GitHub"
• "preciso de login com admin nesse app"
• Any new Node web app for Pedro — start here, don't hand-roll auth.

Stack (do not swap without being asked)

Node 20 + Express · MongoDB/Mongoose · EJS SSR + vanilla JS (no bundler, no React, no build step) · Zod · JWT HS256 · Jest + Supertest + mongodb-memory-server · Docker Compose.

Procedure

1. Copy, don't regenerate. cp -r /home/pedro/Repositorios/templates/projeto-profissional <destino> then rm -rf <destino>/.git <destino>/app/node_modules and git init.
2. Rename in app/package.json (name, description), .env.example and docker-compose.yml (DB name, APP_NAME), and the brand in app/views/partials/header.ejs + app/views/landing.ejs.
3. Adjust roles if needed — the role enum lives in BOTH src/models/user.model.js and src/schemas/admin.schemas.js. Change together.
4. Add the domain following the chain: model → Zod schema → service → controller → routes → register in routes/index.js → test in tests/. For a domain with several entities, write the layers in that order for ALL entities before touching views — the suite can go green before any UI exists, which is the cheapest place to find modelling mistakes. Money, monthly competence, weighted average cost and CSP-safe SVG charts: references/money-and-charts.md. When Pedro names an app category ("controle financeiro", "gestão de X"), look up the established open-source players first and port their model (Firefly III, Actual Budget, Ghostfolio for finance) instead of inventing entities — then say which ones you drew from. Ship a scripts/seed-demo.js with realistic data so the screens can be inspected for real; guard it like seed-carga.js (pitfall 26). Quando o domínio pedido é "bastante simples" (ex.: task manager board + calendário), use o padrão copy-paste em references/task-manager-simples.md — sem drag-and-drop nem redesenho do shell. If the app has more than one domain, treat them as optional modules from the start (MODULE_<NOME> flags, guard per request, dashboard desacoplado): references/optional-modules.md. Retrofitting modularity later means rewriting the dashboard.
5. Backup do banco de produção: copie templates/backup.sh para <repo>/scripts/backup.sh (mongodump dentro do container → zip com timestamp + MANIFEST de restauração, chmod 600, retenção configurável). Copie também templates/reset-senha.js para <repo>/app/scripts/ — sem ele, perder a senha do admin só se resolve escrevendo hash na mão no banco. Acesso às duas stacks, criação de usuário e o 429 do limiter: references/operacao-e-acesso.md. Todo projeto derivado ganha um docs/operacao.md com esse conteúdo.
6. Verify for real before reporting done: cd app && npm install && npm test (must be green), then boot-smoke it. See scripts/smoke-boot.js — copy it into app/ and run it there (it needs mongodb-memory-server from the app's own node_modules; running it from /tmp fails with MODULE_NOT_FOUND). For the structural invariants Jest can't reach (stack isolation, k6 scenario, CSP, workflows) run scripts/verify-stacks.sh <destino>, and for live brute-force behaviour (which Jest cannot cover at all) run scripts/verify-bruteforce.sh <destino> 3 30 — it boots both stacks, asserts the exact 401 401 401 429 sequence, and tears them down via trap.
7. Commit and confirm git ls-files shows no .env and no node_modules.

Non-negotiable design decisions

Carry these into every derived project; they are the point of the template.

• No public self-registration. Admin creates accounts (POST /api/admin/users); server generates a temp password shown exactly once, account is born with mustChangePassword.
• Strict layers: Route → Controller → Service → Model. Services never receive req; they take validated data + userId explicitly.
• Zod on every POST/PUT/PATCH via validate(schema).
• AppError(msg, status) for expected errors; errorHandler is the only place that formats an error response.
• CSP without unsafe-inline ⇒ zero inline <script> in views; all JS in public/js/, wired through the pageScript footer variable.
• Secrets only via .env read by config/env.js; .env.example holds empty keys, never real values.

Security baseline already wired

bcrypt cost 12 + select:false on the hash · 12-char password policy · account lockout 3 attempts/30min · timing-safe dummy-hash compare (anti-enumeration) · identical /forgot-password response either way · tokenValidAfter for global session revocation · csrfGuard (Origin/Referer) · sanitizeInput (NoSQL injection) · Helmet+CSP · rate limits · CORS allowlist (never *) · 100kB body cap · AuditLog with 180-day TTL · non-root read-only container.

Full rationale: references/security-baseline.md.

Brute-force protection is TWO layers — tune them together

Anti-brute-force lives in two independent places, and changing one without the other silently disables it:

Current default: 3 attempts / 30 min on both. When Pedro asks for "3 tentativas, bloqueio de 30 min", he means the observable behaviour — set both layers. Leaving the account lockout at a higher count than the IP limit means the lockout can never fire (the IP limiter answers 429 first), so the layer that defends against distributed attacks is dead code.

Both are read from config/env.js — no magic numbers in authService.js. Defaults are pinned by tests/config.test.js.

Verify end-to-end, not just by reading config: the limiters are disabled under NODE_ENV=test, so Jest structurally cannot prove the limit. Only a running container can:

for i in 1 2 3 4; do curl -s -o /dev/null -w '%{http_code} ' \
  -X POST localhost:4447/api/auth/login -H 'Content-Type: application/json' \
  -d '{"email":"admin@example.com","password":"errada123456"}'; done
# esperado exatamente: 401 401 401 429
curl -sD- -o /dev/null ... | grep -i ratelimit-policy   # RateLimit-Policy: 3;w=1800

Assert the exact sequence ("401 401 401 429 "), not "contains 429" — the loose version passes even if it locks on the first attempt. Then confirm the correct password still returns 429 (proves real blocking, not error counting), and that lockedUntil is ~30 min ahead in Mongo.

Uma instância, teste de carga via NODE_ENV

O template sobe como uma instância na porta 4450 (docker-compose.yml apenas). Para teste de carga, suba com NODE_ENV=staging (desativa o rate limit) — não há mais um segundo compose de teste. A demo é sempre acessível pela landing. Veja docs/load-testing.md.

NODE_ENV=staging JWT_SECRET=$(openssl rand -base64 48) docker compose up -d --build

Load testing (k6)

Full methodology, measured numbers and capacity planning: references/load-testing.md. Scenario lives at loadtest/carga.js with five profiles (smoke, carga, estresse, pico, auth) and k6 thresholds that fail CI when crossed.

Reference measurements (i5-9400F 6 cores, single instance): 100 VUs → 0% errors, 214 req/s; 200 VUs → still 0% errors but latency over target. The bottleneck is always login (bcrypt cost 12 is CPU-bound by design, ~4.5 logins/s per instance); reads and SSR cost ~3-6 ms. The app is stateless, so the answer is horizontal scaling — never quietly lower the bcrypt cost to win a benchmark.

Pitfalls (all hit for real)

1. JWT iat is in SECONDS, truncated. Comparing payload.iat * 1000 < tokenValidAfter.getTime() rejects legitimate tokens minted in the same second. Normalise both sides to seconds. Covered by a test — keep it.

2. passwordHash has select:false. Any query that must compare a password needs .select('+passwordHash'), or bcrypt.compare silently receives undefined.

3. COOKIE_SECURE=true over plain HTTP ⇒ browser discards the cookie: login returns 200 and the session still doesn't stick. Classic LAN/VPN trap.

4. upgradeInsecureRequests must stay off while serving HTTP, or CSS/JS fail to load and the page renders unstyled.

5. Express 5 makes req.query a getter — sanitizeInput mutates in place; do not "simplify" it to req.query = {...}.

6. Never build a RegExp from user input unescaped (user search) — escape metacharacters or it's a ReDoS.

7. npm ci in CI needs package-lock.json committed.

8. Load-test scripts must reuse the session token. Logging in on every k6 iteration is a login-storm, not realistic traffic: with bcrypt 12 it drove 200 VUs to 60s latency and 6% errors and made the app look broken. Log in once per VU, reuse the token, and isolate the worst case in its own auth profile.

9. grep -q 'app_db' also matches app_test_db. Substring asserts cannot tell the two stacks apart — compare the full resolved URI for equality. Also export a dummy JWT_SECRET before docker compose config, or interpolation fails and the command returns empty (a silent false pass).

10. The container serves the image, not your edited file. After changing a view/CSS, docker restart keeps the stale build-time copy — rebuild (up -d --build) before believing a visual fix didn't work.

11. dotenv loads the project .env and overrides env vars you pass when testing config guards. Run such probes with cwd outside the project (e.g. /tmp) or the guard appears not to fire.

12. The k6 container runs as its own UID and cannot traverse a 0700 home directory to reach a bind mount ("permission denied" reading the script). Set user: "0:0" on that ephemeral test container instead of loosening permissions on the host.

13. A port change is a repo-wide edit, not a compose edit. The host port appears in both compose files, .env.example, the PORT default in config/env.js, the k6 BASE_URL default, the readiness curl in carga.yml, the nginx proxy_pass in docs/deployment.md, and the dev URL in README/AGENTS/CLAUDE/CONTRIBUTING. Grep for the old number and confirm zero hits before committing. Only the host side changes — the container keeps listening on 5000 (4447:5000).

14. Tightening a limit invalidates existing tests. The old "bloqueia após 5 tentativas" loop still passes with a limit of 3 (it just over-shoots), so it silently stops testing anything. When a threshold changes, rewrite the assertion to pin the exact boundary: two failures must still return 401, the third must arm the lockout.

15. 127.0.0.1 in the compose port binding means "this machine only". The page simply won't open from another host and the app logs look perfectly healthy — nothing errors, so it reads like a firewall problem. Publish via ${BIND_ADDR:-127.0.0.1} and set BIND_ADDR to the reachable interface (Pedro's Tailscale IP is 100.120.54.126; 0.0.0.0 only behind a firewall). Update APP_BASE_URL to match, and keep COOKIE_SECURE=false over plain HTTP or the session won't stick (see pitfall 3).

16. A missing JWT_SECRET fails at compose interpolation, not at boot. docker compose up aborts with "required variable JWT_SECRET is missing" and no container is created — easy to misread as an app crash. Create .env (chmod 600, git-ignored) with echo "JWT_SECRET=$(openssl rand -base64 48)" >> .env first.

17. Once a real .env exists, it poisons default-value checks. docker compose config merges it, so a probe asserting the template's built-in fallback (e.g. BIND_ADDR defaulting to 127.0.0.1) reads Pedro's local value and reports a false failure. Isolate with docker compose --env-file /dev/null ... when verifying defaults. Same family as pitfall 11.

18. Inserting prose into a markdown table splits it in two. Patching a README by anchoring on a | row | and appending a paragraph lands the text between rows and silently breaks the table. Anchor on the sentence after the table instead, then re-read the rendered section to confirm.

19. A new <%= var %> in a view is a runtime 500, not a lint error. Routes call bare res.render('landing'), so an EJS variable nobody passes only explodes when the page is requested. Register shared values once with app.locals.appName = env.appName in app.js instead of threading them through every route, and verify by compiling the template directly: node -e "require('ejs').render(fs.readFileSync('views/landing.ejs','utf8'),{appName:'X'})".

20. An in-page anchor needs its target to exist. href="#topo" silently does nothing unless some element carries id="topo" — put it on <body> in the header partial. Prefer the pure-anchor + scroll-behavior: smooth combo over JS: the CSP forbids inline scripts anyway.

21. The template's .field/.card rules defeat the hidden attribute. hidden only sets display:none through the UA stylesheet, so any class rule with display: block wins and a field you "hid" from JS stays on screen — the JS looks broken while el.hidden === true. Add [hidden] { display: none !important; } to main.css once per derived project. Diagnose this class of bug by comparing el.hidden against getComputedStyle(el).display, not by re-reading the JS.

22. A new derived project collides with the template's own ports/project name. The template stack is usually still up on 4447/4446 under compose project pp. Before the first up -d, pick fresh host ports AND a fresh project name (name: key + -p), then do pitfall 13's repo-wide sweep in one pass over the known file list: perl -pi -e 's/4447/4451/g; s/4446/4450/g; s/-p pp\b/-p fa/g; s/app_db/<novo>_db/g' <files> Rename the DB too — two projects sharing app_db in your head is how a demo seed lands in the wrong volume. Then grep for the old numbers/names and confirm zero hits, INCLUDING inside tests/config.test.js, whose seed guard asserts a literal DB name.

23. Point a booted stack at a scratch DB with an override file, not by editing the committed compose. Write three lines to /tmp/<proj>-demo.override.yml setting MONGO_URI to a *_demo database and boot with -f docker-compose.yml -f /tmp/....yml. Keeps the repo clean and the demo reproducible.

24. docker compose must run from the repo root, not from app/. From the Node subdirectory it fails with open .../app/docker-compose.yml: no such file or directory, which reads like a missing file rather than a wrong cwd.

25. After a rebuild the browser still serves the old CSS/JS. Pitfall 10 covers the container; the other half is client cache, and it produces the exact same symptom ("my fix did nothing"). Confirm the served bytes with curl -s host/css/main.css | tail, and in the page use fetch(url,{cache:'reload'}) before concluding the fix failed.

26. Any destructive seed needs a DB-name guard and a test for it. A demo seeder that deleteMany({}) on every collection is total data loss if pointed at production. Copy the seed-carga.js pattern — refuse unless the URI matches /test|demo/i — and pin it in tests/config.test.js alongside the existing guard.

    27. Página vs JSON de mapeamento moram em prefixes de montagem diferentes. routes/index.js é montado sob /api no app.js; pages.routes.js é montado sob /. Uma rota router.get('/status') dentro de um arquivo sob /api vira /api/status, não /status. Por isso o mapeamento HTTP se divide: o JSON GET /api/status/:code fica em status.routes.js (definido como router.get('/:code') e montado em routes/index.js sob /status → resultado /api/status/:code); a página GET /status fica em pages.routes.js. Misturar os dois num só arquivo faz a página ou o JSON sumirem (vieram 404 até acertar esse split).

    28. Catálogos separados: importe de onde cada um vive. HTTP_CATALOG está em status.routes.js; ERROR_CATALOG/catalogFor estão em errorHandler.js. Um teste que faz require('../src/routes/status.routes').ERROR_CATALOG recebe undefined e quebra com Cannot read properties of undefined. Importe cada um do seu módulo.

    29. Testar variante de erro exige mini-app com handler DEPOIS da rota de teste. Para renderizar cada status 4xx/5xx, monte um express() isolado, registre app.get('/_e_:code', (req,res,next)=>next(new AppError('x',Number(req.params.code)))) e SÓ DEPOIS app.use(notFoundHandler); app.use(errorHandler). Se o notFoundHandler vier antes, ele responde 404 para a rota de teste e o status forçado nunca chega ao errorHandler.

    30. Botão "Voltar" não pode usar javascript: — a CSP bloqueia. href= "javascript:history.back()" é script inline disfarçado e a CSP (script-src 'self') o impede; o clique não faz nada. Passe backUrl do servidor usando o Referer same-origin (cai em / se ausente/externo). Mesma regra do "Voltar ao topo", que é âncora pura #topo.

    31. Script de verificação ad-hoc precisa rodar de dentro de app/. Rodar de /tmp falha com MODULE_NOT_FOUND (mongodb-memory-server, supertest etc. estão em app/node_modules). Copie o script para app/ com nome hermes-verify-*.js ou use cwd em app/. Vale para smoke-boot.js e qualquer probe que exija os deps do app — não confunda com o pitfall 11, que manda rodar probe de config de /tmp justamente para o .env não sobrescrever o ambiente.

    32. README não é só 'como rodar' — Pedro quer que ensine a DESENVOLVER, RODAR e DOCUMENTAR. Ao tocar no README do template (ou de projeto derivado), inclua: (a) seção Desenvolvimento — fluxo de branch feat/*/fix/*, .env, loop dev→test→verify, lint DESIGN.md e npm audit, Conventional Commits e arquitetura em camadas; (b) seção Documentação — tabela de responsabilidade dos arquivos de doc (README/AGENTS/CLAUDE/CONTRIBUTING/SECURITY/CHANGELOG/DESIGN/docs) e regras práticas (métrica só real, CSP na view, tokens no DESIGN.md, CHANGELOG humano). Não entregue README que só lista comandos de instalação.

    33. O status de validação deste template é 422, não 400. Testes novos escritos por instinto (expect(res.status).toBe(400)) falham em massa contra Zod/validate(). Confirme com uma chamada real antes de escrever a bateria inteira. Idem para idParamSchema: id malformado dá 422.

    34. Fixture curta demais vira "Cannot read properties of undefined". Schemas usam .min(2) em description/nickname, então um helper de teste que manda 'X'/'A' recebe 422 e res.body.<entidade> fica undefined — o erro estoura três linhas depois, ao ler ._id, e parece bug do service. Ao ver undefined lendo o corpo de um POST no teste, cheque o status da resposta ANTES de investigar o código.

    35. A suíte precisa de --forceExit. npx jest sozinho pendura após o último teste (handle aberto do mongodb-memory-server/app) e estoura o timeout do comando — parece suíte travada ou falhando quando na verdade passou. Rode npx jest --forceExit e leia a linha Tests:.

    36. jest.resetModules() para recarregar flags mata a conexão do mongoose. Remontar o app por teste (para reler env) cria uma instância nova do mongoose que não enxerga a conexão do setupDb; cada teste morre em timeout de 5s sem mensagem útil. A saída não é remontar — é fazer a config ser lida por getter e o guard rodar por request (ver "Módulos opcionais"), aí um único app cobre todas as combinações só mexendo em process.env.

    37. Rota transversal não pode morar sob o prefixo de um módulo. GET /api/financas/dashboard some junto quando finanças é desligado, mesmo que ele agregue os outros módulos. Monte-a na raiz da API (GET /api/dashboard, em routes/index.js) e atualize o fetch da view.

    38. PUT vs POST: confira a rota real antes de escrever o inventário. Orçamento é upsert de envelope, logo PUT /api/financas/orcamentos. Um teste de inventário que assume POST recebe 404 e parece rota faltando.

    39. O container é read-only: script novo entra pela IMAGEM, não por cp. O baseline roda o container com rootfs read-only, então docker compose cp arquivo app:/app/scripts/ falha com "container rootfs is marked read-only" — parece permissão do host, mas é o hardening funcionando. Commite o arquivo e rode up -d --build app.

    40. Guard que responde antes do roteamento cega o teste de 404. Em /api/admin/* o requireRole devolve 403 antes de o Express concluir que a rota não existe, então um caminho ERRADO (/usuarios em vez de /users) passa no not.toBe(404) e no toContain(403). O inventário fica verde testando rota inexistente, e o defeito só aparece num curl real. Copie os caminhos de admin do admin.routes.js; nunca os digite de memória.

    41. AppError expõe statusCode, não status. Um probe que assere (e) => e.status === 409 recebe undefined, o assert.rejects reprova com "validation function is expected to return true" e parece que o service não lançou o erro — quando lançou o certo. Use e.statusCode. (Nos testes de rota isso não aparece, porque lá se lê res.status do Supertest — daí o instinto errado.)

    42. Ampliar um módulo para o domínio genérico é renomeação em ~8 arquivos. moto → veiculos (carro + moto) toca service/controller/rotas/schemas, mas também routes/index.js, config/env.js (getter e toJSON), pages.routes.js, o bloco do relatorioService.dashboard() (a chave do payload muda e quebra a view que lia d.moto), .env.example e a doc. Receita completa, incluindo o discriminador type, o filtro por tipo em coleções filhas e o consumo por combustível de carro flex: references/optional-modules.md, seção "Renomear ou ampliar um módulo".

    43. "Melhore o X" pode se referir a algo que NÃO EXISTE. Pedro pediu "o pdf de extrato tem que ficar melhor" — não havia exportação nenhuma no projeto, era item de roadmap (issue #2). Sair "melhorando" vira construir do zero uma feature com escopo adivinhado. Antes de aceitar um verbo de melhoria, grep pela feature; se não existir, diga isso e pergunte o escopo em vez de assumir. (Ele não respondeu no tempo do clarify, e aí seguir com a opção mais completa foi o certo — mas o aviso explícito de que era construção, não ajuste, é obrigatório no relatório.)

    44. Agregado sobre coleção heterogênea precisa de teste com DOIS donos. $group: {_id: null, min/max} de odômetro somando carro + moto inventou "34.410 km rodados, 237 km/l" e passou em toda a suíte, porque todo teste existente tinha um veículo só. Sempre que um número derivar de min/max/ amplitude sobre linhas de entidades diferentes, escreva o caso com dois registros distintos — é a única fixture que reprova a fórmula errada. Detalhe e o snippet corrigido em references/optional-modules.md (item 6).

    45. pageScript recebe o NOME da página, não o caminho. O footer monta <script src="/js/<%= pageScript %>.js">. Passar '/js/veiculos.js' gera /js//js/veiculos.js.js → 404 do script. Sintoma cruel: a página renderiza inteira (é SSR), a API responde 200 em todo endpoint, o console não registra erro nenhum — só as tabelas ficam vazias, o que parece bug de service ou de banco. Confira com [...document.querySelectorAll('script')].map(s=>s.src) antes de investigar o backend. Convenção: { pageScript: 'veiculos' }; página sem JS chama include('partials/footer') sem argumento (passar null também quebra).

    46. O front recebe vehicleId populado como OBJETO nas listagens. O service faz .populate('vehicleId', 'nickname type'), então veiculos.find(v => v._id === String(item.vehicleId)) nunca casa e a coluna inteira vira —. Escreva um helper que aceite os dois formatos: const nome = (ref) => !ref ? '—' : (typeof ref === 'object' ? ref.nickname : lista.find(v => v._id === String(ref))?.nickname ?? '—').

    47. new Date(iso).toLocaleDateString('pt-BR') volta um dia. A data é gravada como 2026-07-05T00:00:00.000Z; no fuso do Brasil (UTC-3) o browser renderiza 04/07. A tabela inteira fica um dia atrás do que a pessoa digitou. Formate sempre em UTC: new Date(iso).toLocaleDateString('pt-BR', { timeZone: 'UTC' }). Vale para toda view que exibe data vinda do Mongo.

    48. Item ativo da navbar: injete currentPath uma vez, não rota a rota. app.use((req, res, next) => { res.locals.currentPath = req.path; next(); }) no app.js (logo após app.locals.modules) evita repetir a variável em cada res.render — e um res.render esquecido é um item de menu que nunca acende.

    49. doc.text() no rodapé do pdfkit CRIA página nova — e são DUAS causas. Escrever o rodapé avança o cursor, então um extrato de 1 página sai com 3 (uma para o conteúdo, uma para "Página N de M", uma para "Gerado em"). Corrigir só metade não resolve, e o sintoma é idêntico: (a) passe { lineBreak: false, width: larguraUtil } em toda escrita posicionada de rodapé; (b) o rodapeY tem de cair DENTRO da área útil — pageAltura - margins.bottom + 14 fica abaixo dela e pagina mesmo com lineBreak:false; use - 12. Arrume as duas de uma vez e reconte. Conte com extrator de verdade (pymupdf: d.page_count), não com grep -c '/Type /Page' no binário, que erra por causa dos streams. Demais armadilhas de diagramação (cabeçalho truncado em 1 letra, data ISO quebrando a coluna, acento que é dado e não fonte) estão na skill document-exports, com script scripts/verify-pdf-export.sh.

    50. Validar seed/guard ANTES de qualquer I/O. Um script cuja trava roda depois do mongoose.connect falha com ECONNREFUSED quando apontado para um host inacessível — mensagem que esconde o motivo real e derruba o teste que casa com /Recusado/. A checagem de nome de banco é a primeira linha executável do arquivo, antes de conectar. (Complementa o pitfall 26.)

    51. Extrair lógica de um script para um módulo quebra o teste do script. tests/config.test.js executa scripts/seed-*.js como subprocesso e casa com a mensagem de erro. Ao mover a lógica para src/seeds/*.seed.js, re-rode aquele arquivo de teste especificamente — a suíte de domínio passa e esconde a regressão do guard de segurança.

    52. Para testar flags de boot, monte vários apps — nunca jest.resetModules(). Quando a flag é lida em createApp() (e não por getter), cada cenário precisa da sua instância. jest.resetModules() recarrega o mongoose num registro novo, perde a conexão do setupDb e todo teste morre em timeout de 5s sem mensagem útil — parece deadlock. A saída é require do createApp UMA vez no topo e uma fábrica que só troca process.env ao redor da chamada:

    const { createApp } = require('../src/app');
    function appCom(flags = {}) {
      const antes = { FLAG_A: process.env.FLAG_A };   // salve só as chaves usadas
      Object.assign(process.env, flags);
      const app = createApp();
      Object.assign(process.env, antes);              // nunca `process.env = antes`
      return app;
    }
    

    Complementa o pitfall 36: lá a solução foi getter + guard por request; aqui, quando a leitura é mesmo no boot, é esta fábrica.

    53. Middleware de autenticação montado em / engole a landing. Um autologin registrado como app.use('/', mw) autentica o visitante ANTES de a rota / rodar; ela então vê req.user e redireciona para /app — a página que explica o produto fica inalcançável justamente na instância de demonstração. Cada rota passa isoladamente no teste, então só aparece navegando. Exclua a raiz: app.use(/^(?!\/$).*/, mw). Regra geral: middleware que muda o estado de autenticação precisa declarar de quais rotas ele fica de fora, e a landing é sempre uma delas.

    54. Ao "melhorar" texto de UI, cheque se o dado também precisa mudar. Um modelo de visão acusou "acentos errados" num PDF já corrigido — os acentos que faltavam estavam nos dados do seed (Salario, Condominio), não no gerador. Renderização e conteúdo são camadas distintas: grep nas strings do serviço E no seed antes de concluir.

• 94. Para subir o app NO HOST (fora do Docker) e testar na 4450, o Mongo fica INATINGÍVEL em localhost:27017. O container projeto-profissional-mongo-1 NÃO publica a porta 27017 no host — só expõe para a rede interna do compose (docker inspect mostra "27017/tcp": null). Então npm start do app/ falha com ECONNREFUSED 127.0.0.1:27017. O host ALCANÇA o Mongo pelo IP do container (docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' → ex.: 192.168.112.3, confirme a cada máquina). Receita de subida local (sem Docker, apontando pro Mongo do container):

  cd /home/pedro/Repositorios/templates/projeto-profissional/app
  ln -sf ../.env .env          # o .env REAL está na RAIZ do repo, não em app/ (dotenv do app só lê app/.env); linka ou defina as env abaixo
  export NODE_ENV=development   # development pula a exigência de JWT_SECRET forte (NODE_ENV=production exigiria JWT >32 chars)
  export MONGO_URI="mongodb://192.168.112.3:27017/app_db"   # IP do container, não localhost
  export SEED_PASSWORD_FILE="/home/pedro/Documentos/comum/senhas-projetos.md"
  export PORT=4450
  npm start
  

  Verificação: curl -s -o /dev/null -w '%{http_code}' http://localhost:4450/ → 200; /demo/start → 302 com Set-Cookie; /demo → 200 com id="board". Atenção: esse processo roda no shell do agente e MORRE se a sessão fechar — para deixar permanente use docker compose up --build (precisa de JWT_SECRET no .env). Os node_modules já têm dompurify/katex/marked vendored em public/vendor/, então npm install não é estritamente necessário se já existirem. config/env.js usa PORT default 4450, então sem .env de PORT sobe em 4450 mesmo assim.
• 95. handoff-resume SEM HANDOFF.md: o working tree sujo É o documento de continuidade. Esta base costuma ser deixada com dezenas de arquivos modificados + não rastreados (feature de domínio incompleta, ex.: task manager com board/painel/profissionais). Não há HANDOFF.md — o skill handoff-resume assume que existe, mas aqui não existe. Procedimento: (1) git status --short + git diff --stat para ver o real estado; (2) leia os diffs e os arquivos novos (models/service/controller/routes/views/js) para reconstruir o que ficou pendente; (3) cruze com os sintomas relatados ("não está no ar na 4450" = processo nunca subiu, ver pitfall 94). Não invente um HANDOFF do zero — o git é a fonte. Dica: git diff --stat HEAD + git ls-files --others --exclude-standard dá o panorama completo em duas linhas.
• 96. Verificação SSR de tabela populada por JS dá falso FAIL. Páginas como Projetos/Profissionais entregam o <tbody> VAZIO no servidor (o SSR monta só o shell + <table>/<tbody id=...>); as linhas são geradas pelo public/js/*.js após o fetch. Um curl/http.get no HTML servido NÃO acha os botões icon-btn js-edit — mas o browser (pós-JS) os renderiza. Ao verificar, confirme (a) o shell no SSR (id="proj-rows", class="dom-table") e (b) o JS no disco gera os botões (pjs.includes('icon-btn js-edit')), ou navegue no browser e confira o snapshot. Não marque como bug só porque o HTML cru não tem as linhas. Mesma razão pela qual um hermes-verify-*.js que lê o HTML servido não vê a tabela — ele precisa ler o JS ou navegar. (Complementa o pitfall 19/45: ache o gerador, não confie no HTML cru.)

Todo projeto derivado ganha um mapeamento elegante de status HTTP e uma página de erro rericada (código grande, título, mensagem, ação de recuperação e botão Voltar). É usado internamente e pelo suporte futuro.

Onde vive:

• src/routes/status.routes.js — catálogo HTTP_CATALOG (código, nome, classe success/redirect/client/server, retryable, descrição) + rota GET /api/status/:code (JSON estruturado, 404 se não mapeado). Exporta HTTP_CATALOG para a view reusar. Montada em routes/index.js sob /status → vira /api/status/:code.
• src/routes/pages.routes.js — rota GET /status que renderiza views/status.ejs (tabela filtrável via ?q=, form GET, sem JS inline).
• src/middleware/errorHandler.js — além do mapeamento de erro existente, exporta ERROR_CATALOG (por status: title + action de recuperação) e catalogFor(status). A view error.ejs agora recebe title, action, details e backUrl. O botão Voltar aponta para o Referer same-origin (ou /), nunca javascript: (bloqueado pela CSP).
• views/status.ejs, views/error.ejs + regras .status-*/.error-* em public/css/main.css.
• tests/paginas.test.js — cobre /status (lista, filtro, JSON, 404, ausência de script inline) e renderiza cada status 4xx/5xx forçando um AppError num mini-app isolado (rota de teste ANTES dos handlers, senão o notFoundHandler come 404).

Regras ao estender:

• Adicionar um status novo = só acrescentar a entrada em HTTP_CATALOG (status.routes) e, se for erro, em ERROR_CATALOG (errorHandler). Nunca espalhar ifs pelo handler.
• ERROR_CATALOG deve cobrir todo 4xx/5xx presente em HTTP_CATALOG (há teste de consistência).
• Manter tokens do DESIGN.md (cores, raio, elevação única). Botão Voltar e "Página inicial" usam .btn-primary/.btn-outline.

Três bancos isolados (produção / teste / demo) — um app, vários databases

Todo projeto derivado sobe três bancos físicos isolados numa só aplicação: app_db (produção), app_test_db (teste) e app_demo_db (demo). Cada banco é uma connection própria (via connection.useDb) e os models são registrados por connection num registry — não há model global. O acesso é por prefixo de rota (/app, /test, /demo); um único cookie token carrega o mode (banco) no payload do JWT e o auth recusa token de modo diferente (um token de demo não abre a produção).

Quando Pedro pedir botão de demonstração na landing ou três bancos, use use este padrão (e não um usuário de demo dentro da produção): references/ambiente-demo-publico.md. Padrão de i18n (PT/EN/ES/FR) + tema claro/escuro + landing por instância: references/i18n-e-tema.md.

Arquitetura (padrão implementado e testado)

• config/db.js → connectDb(): mongoose.createConnection(baseUri) (sem DB no final) e getModeConn(mode) faz mainConn.useDb(MODE_DB[mode], {useCache:true}) (cacheado). MODE_DB = { production:'app_db', test:'app_test_db', demo:'app_demo_db' }. O nome do database é derivado do final da MONGO_URI (tira tudo após a última /), então MONGO_URI=mongodb://.../app_demo_db → banco app_demo_db.
• models/registry.js → getModels(conn): registra {User, Project, CatalogItem, AuditLog} na connection (cache por WeakMap de conn) e devolve o objeto. Os *.model.js exportam o SCHEMA, não o model — o registry cria o model na connection certa.
• middleware/selectDb.js → selectDb(mode): injeta em req mode, conn (getModeConn(mode)) e models (getModels(conn)). Montado ANTES de cada grupo de rotas: app.use('/api/app', selectDb('production'), apiRoutes) etc.
• middleware/auth.js → signToken(user, mode) assina com payload.mode; resolveUser(token, mode, models) bate payload.mode === mode e usa req.models.User (não o model global). pageAuth também passa req.mode/ req.models.
• Services recebem models via req (não require('../models/x') global): controllers passam req.models para o service. É a mudança mais invasiva — fazer o registry + selectDb e depois catar cada require('../models/...') nos services/controllers.
• server.js semeia os 3 bancos no boot: produção só admin; teste admin + demo; demo banco completo (carregarDemo). NODE_ENV=production NUNCA popula demo.
• app.js monta as rotas em /api/app, /api/test, /api/demo mais um alias /api que aponta para produção (preserva testes antigos que usavam /api/auth/login). Páginas iguais em /app, /test, /demo + alias /.

Tabela de ambientes

Arquitetura FINAL (confirmada pelo Pedro): UMA instância, porta 4450, os 3 bancos rodam SIMULTÂNEOS. Não são 3 instâncias/processos/portas — é um só docker-compose.yml que sobe a app na 4450 e semeia app_db + app_test_db

• app_demo_db no mesmo Mongo. A landing (/) oferece os 3 botões; o .env (NODE_ENV) controla production/staging (testes), mas a demo é sempre acessível pela landing, independente do modo. O usuário demo (demo1) é criado só em app_demo_db (ver carregarDemo({ skipAutoUser })).

NÃO volte a 3 instâncias/3 portas salvo o Pedro pedir explicitamente de novo — esta foi a correção dele após eu ter implementado 3 composes separados (4450 teste / 4451 produção / 4452 demo) que ele rejeitou ("uma porta só ag

…(truncated)