# Aula 5.8 — Compilação e projeto final

## Identificação

- **Módulo:** 5 — Node.js, NestJS e APIs
- **Duração:** 2 horas
- **Tipo:** oficina integradora
- **Entrega:** API REST documentada, testada e reproduzível
- **Laboratório:** [`../exemplos/aula-5.8/index.html`](../exemplos/aula-5.8/index.html)

## Introdução

Chegamos ao fechamento do primeiro back-end do curso. As aulas anteriores criaram
processo, módulos, rotas, DTOs, validação, erros, configuração, documentação, registros
e testes. Agora precisamos verificar se essas partes formam uma entrega reproduzível.

**Compilar** significa transformar o TypeScript em JavaScript que o Node.js consegue
executar. **Publicar** significa colocar o resultado em um ambiente onde a aplicação
ficará disponível. Compilar não publica automaticamente.

O aluno não precisa de uma VPS para concluir este módulo. Todo o projeto pode ser
executado localmente no Windows. XAMPP pode continuar servindo as páginas estáticas e o
Angular, enquanto a API NestJS executa em outro processo e outra porta.

Nesta aula responderemos:

- `npm run build` inicia a API?
- precisamos copiar `src` para produção?
- XAMPP executa NestJS?
- o Git atrapalha a publicação?
- é obrigatório usar VPS para concluir o curso?
- o que deve entrar no arquivo README?
- quais evidências demonstram que o módulo foi concluído?

## Objetivos

Ao concluir a aula, você será capaz de:

1. diferenciar desenvolvimento, compilação, execução e publicação;
2. gerar JavaScript a partir do projeto NestJS;
3. inspecionar o diretório de saída;
4. executar o resultado compilado;
5. preparar configuração sem incluir segredos;
6. organizar scripts reproduzíveis;
7. criar um README para Windows;
8. auditar contrato, testes, registros e segurança;
9. explicar a convivência entre XAMPP, Angular, NestJS e MySQL;
10. apresentar e defender o projeto final do módulo.

## Pré-requisitos

- aulas 5.1 a 5.7 concluídas;
- Node.js e npm instalados;
- terminal PowerShell ou Prompt de Comando;
- Knowledge API executando localmente;
- documentação OpenAPI e testes essenciais.

## 1. Quatro etapas diferentes

| Etapa | O que acontece |
|---|---|
| desenvolvimento | acompanha alterações e reinicia a API |
| compilação | transforma TypeScript em JavaScript |
| execução | inicia o processo Node.js |
| publicação | envia artefatos e configuração a outro ambiente |

Confundir essas etapas dificulta o diagnóstico.

## 2. Scripts principais

```json
{
  "scripts": {
    "start:dev": "nest start --watch",
    "build": "nest build",
    "start:prod": "node dist/main.js",
    "test": "jest",
    "test:watch": "jest --watch",
    "test:e2e": "jest --config ./test/jest-e2e.json"
  }
}
```

Os nomes à esquerda são atalhos do projeto. Os comandos à direita executam ferramentas.

## 3. Comandos no Windows

Abra o terminal na pasta que contém `package.json`:

```powershell
npm install
npm test
npm run build
npm run start:prod
```

Os mesmos comandos funcionam no PowerShell e no Prompt de Comando. A forma de definir
variáveis de ambiente muda entre terminais, por isso prefira configuração documentada e
arquivos locais ignorados pelo Git.

## 4. O que `nest build` produz?

Em uma aplicação padrão, a saída fica em `dist`:

```text
dist/
├── main.js
├── app.module.js
└── tasks/
    ├── tasks.controller.js
    ├── tasks.service.js
    └── tasks.module.js
```

O formato exato depende da configuração. Não escreva caminhos rígidos sem confirmar a
saída real.

## 5. O que não entra em `dist` automaticamente?

Podem exigir tratamento explícito:

- arquivos estáticos;
- modelos de e-mail;
- certificados;
- arquivos de tradução;
- documento OpenAPI exportado;
- qualquer recurso não importado pela compilação.

Configure cópia de recursos somente quando o projeto realmente precisar.

## 6. Compilação não valida tudo

Uma compilação aprovada confirma principalmente tipos e transformação. Ela não garante:

- conexão com serviços externos;
- presença de variáveis de ambiente;
- regras corretas;
- segurança;
- documentação coerente;
- funcionamento de todos os endpoints.

Por isso, a porta de qualidade inclui mais etapas.

## 7. Porta de qualidade local

```text
instalação
   ↓
formatação e análise estática
   ↓
testes
   ↓
compilação
   ↓
auditoria de segurança e documentação
   ↓
execução do artefato
```

Interrompa a entrega quando uma etapa obrigatória falhar.

## 8. Limpeza da saída

Evite misturar arquivos antigos com a compilação atual. O Nest CLI normalmente gerencia
a saída, mas o projeto deve confirmar sua configuração. Nunca apague pastas amplas ou
fora do projeto por meio de um script de limpeza mal definido.

## 9. Configuração de produção

Produção precisa fornecer valores como:

```text
NODE_ENV=production
PORT=3000
DATABASE_URL=...
```

O arquivo `.env.example` documenta nomes sem valores secretos:

```text
NODE_ENV=development
PORT=3000
DATABASE_URL=mysql://USUARIO:SENHA@HOST:3306/BANCO
```

Nunca envie `.env` real ao repositório ou ao navegador.

## 10. O Git atrapalha a publicação?

Não. Git registra versões do código e pode ajudar a transportar mudanças. O ambiente de
destino pode:

- clonar um repositório autorizado;
- receber um pacote já compilado;
- receber uma imagem de contêiner;
- usar um serviço de implantação integrado ao repositório.

Git não executa a API sozinho e não substitui configuração, Node.js ou processo de
publicação.

## 11. É obrigatório ter VPS?

Não para desenvolver e concluir o curso. Localmente, o Windows pode executar:

```text
navegador
├── site estático pelo Apache/XAMPP
├── Angular em servidor de desenvolvimento ou compilado
├── API NestJS em localhost:3000
└── MySQL local pelo XAMPP ou instalação própria
```

Uma VPS ou hospedagem compatível é necessária apenas quando você quiser manter o sistema
disponível publicamente e controlar o processo Node.js no servidor.

## 12. XAMPP executa a API NestJS?

O Apache do XAMPP não executa o processo NestJS. São programas diferentes:

```text
Apache/XAMPP  → arquivos web e, se necessário, proxy
Node.js       → processo da API NestJS
MySQL         → banco de dados
```

Eles podem coexistir no mesmo computador, desde que utilizem portas compatíveis.

## 13. Hospedagem compartilhada

Uma hospedagem comum pode oferecer Git e ainda não permitir um processo Node.js
permanente. Antes de contratar ou publicar, verifique:

- suporte à versão necessária do Node.js;
- possibilidade de manter processo ativo;
- configuração de porta ou proxy;
- variáveis de ambiente;
- acesso a registros;
- reinício automático;
- banco MySQL;
- limites de memória e CPU.

Não confunda “possui Git” com “hospeda NestJS”.

## 14. Gerenciador de processo

Em servidor próprio, a API precisa reiniciar após falha ou reinicialização da máquina.
Um gerenciador de processo ou a plataforma de hospedagem cumpre esse papel. A escolha
será detalhada no Módulo 15.

## 15. Verificação de saúde

O endpoint de saúde deve confirmar que o processo responde:

```http
GET /api/health
```

```json
{
  "status": "ok",
  "service": "knowledge-api"
}
```

Quando MySQL for conectado, a estratégia deverá diferenciar saúde do processo e
disponibilidade de dependências.

## 16. README reproduzível

O README precisa responder:

1. o que é o projeto;
2. quais tecnologias utiliza;
3. quais versões são esperadas;
4. como instalar dependências;
5. como criar a configuração local;
6. como executar em desenvolvimento;
7. como testar;
8. como compilar;
9. como executar a compilação;
10. onde abrir a documentação;
11. quais dados são mantidos apenas em memória.

## 17. Exemplo de início rápido

```markdown
## Execução local no Windows

1. Copie `.env.example` para `.env`.
2. Execute `npm install`.
3. Execute `npm run start:dev`.
4. Abra `http://localhost:3000/docs`.

## Verificações

- `npm test`
- `npm run test:e2e`
- `npm run build`
```

Não escreva “execute normalmente”. Forneça comandos e resultados esperados.

## 18. Projeto final do módulo

A Knowledge API deve incluir:

- `GET /api/health`;
- `GET /api/tasks`;
- `GET /api/tasks/:id`;
- `POST /api/tasks`;
- `PATCH /api/tasks/:id`;
- `DELETE /api/tasks/:id`;
- módulo de tarefas;
- controlador fino e serviço de aplicação;
- repositório em memória;
- DTOs por operação;
- validação global;
- erros HTTP padronizados;
- correlação e registros seguros;
- documentação OpenAPI;
- testes essenciais;
- compilação executável;
- README reproduzível.

## 19. Estrutura sugerida

```text
knowledge-api/
├── src/
│   ├── common/
│   │   ├── filters/
│   │   ├── interceptors/
│   │   └── middleware/
│   ├── config/
│   ├── health/
│   ├── tasks/
│   │   ├── dto/
│   │   ├── domain/
│   │   └── repositories/
│   ├── app.module.ts
│   └── main.ts
├── test/
├── .env.example
├── .gitignore
├── nest-cli.json
├── package.json
├── tsconfig.json
└── README.md
```

Estrutura serve à compreensão. Não crie pastas vazias apenas para parecer arquitetural.

## 20. Auditoria do contrato HTTP

Para cada operação, confirme:

- verbo e caminho;
- status de sucesso;
- DTO de entrada;
- formato de saída;
- erros esperados;
- idempotência quando relevante;
- documentação OpenAPI;
- teste correspondente.

## 21. Auditoria de segurança

- `.env` real está ignorado;
- nenhum segredo aparece no Angular;
- erros não devolvem stack trace;
- registros não contêm senha ou token;
- documentação não possui credencial real;
- entrada externa passa por validação;
- CORS não foi confundido com autorização;
- dependências não foram instaladas de fonte desconhecida.

## 22. Auditoria de qualidade

- módulos possuem responsabilidade clara;
- controladores delegam regras;
- serviços recebem dependências;
- testes são independentes;
- compilação não possui erro;
- aplicação fecha corretamente em testes;
- comandos do README foram reproduzidos em pasta limpa;
- saída compilada inicia com configuração válida.

## 23. Evidências da entrega

Guarde:

- resultado da suíte de testes;
- resultado da compilação;
- captura ou exportação do contrato OpenAPI;
- lista de endpoints;
- exemplo de registro sem dado sensível;
- README;
- roteiro de apresentação;
- limitações conhecidas.

Evidência não significa publicar segredos ou todo o conteúdo do terminal.

## 24. Roteiro de apresentação

### Minuto 1 — problema

Explique por que a Knowledge AI precisa de uma API.

### Minutos 2 e 3 — arquitetura

Mostre módulo, controlador, serviço e repositório.

### Minutos 4 e 5 — contrato

Apresente documentação, DTOs, validação e erros.

### Minuto 6 — qualidade

Mostre correlação, testes e compilação.

### Minuto 7 — limites e evolução

Explique que o armazenamento ainda é em memória e será substituído por MySQL no Módulo 6.

## 25. Perguntas para defesa técnica

- por que o Angular não acessa MySQL diretamente?
- qual diferença entre DTO e entidade?
- por que documentação não substitui validação?
- onde uma regra de negócio deve ficar?
- como localizar eventos da mesma requisição?
- por que o projeto usa repositório em memória agora?
- como o sistema será publicado no futuro?

## 26. Laboratório guiado

Abra o [painel de entrega da Knowledge API](../exemplos/aula-5.8/index.html).

### Etapa 1 — Escolha um estado

Compare projeto incompleto, regressão e versão pronta.

### Etapa 2 — Execute as verificações

Rode testes, compilação, auditoria de contrato e segurança.

### Etapa 3 — Examine bloqueadores

O painel explica por que uma entrega não deve avançar.

### Etapa 4 — Gere o parecer

Produza um resumo com pontuação, evidências e próximos passos.

## 27. Erros comuns

### Executar `start:prod` antes de compilar

O arquivo esperado pode não existir ou estar desatualizado.

### Copiar `.env` para `dist`

Segredo não pertence ao artefato público.

### Publicar somente `src`

O servidor precisa de estratégia de instalação e compilação ou de artefato pronto.

### Achar que Git mantém o processo vivo

Git transporta versões. Um serviço ou gerenciador executa a aplicação.

### Testar apenas no Swagger UI

Isso é útil, mas não substitui suíte automatizada.

### Ignorar limitações conhecidas

O armazenamento em memória perde dados ao reiniciar. Documente essa decisão.

## 28. Exercícios

1. explique a diferença entre `npm run build` e `npm run start:prod`;
2. liste os processos locais usados com XAMPP;
3. escreva o início rápido do README;
4. produza uma lista de seis endpoints;
5. identifique cinco dados que não podem aparecer nos registros;
6. execute testes e compilação em uma pasta nova;
7. explique por que uma VPS não é necessária durante o curso.

## 29. Desafio individual

Prepare uma entrega reproduzível da Knowledge API:

- repositório Git local limpo;
- `.env.example` sem segredo;
- instruções para Windows;
- suíte aprovada;
- compilação aprovada;
- documentação OpenAPI;
- exemplo de erro seguro;
- exemplo de correlação;
- roteiro de apresentação de sete minutos;
- registro explícito da limitação de armazenamento em memória.

## 30. Lista de verificação de conclusão

- [ ] Diferencio compilação, execução e publicação.
- [ ] Executo comandos na pasta que contém `package.json`.
- [ ] A suíte de testes está aprovada.
- [ ] A compilação está aprovada.
- [ ] O resultado compilado inicia corretamente.
- [ ] Nenhum segredo está versionado ou documentado.
- [ ] O README permite reproduzir a execução no Windows.
- [ ] A documentação corresponde aos endpoints.
- [ ] Sei explicar como XAMPP e NestJS coexistem.
- [ ] Sei que não preciso de VPS para concluir o curso.
- [ ] Consigo apresentar decisões e limitações.

## 31. Rubrica do projeto final

| Critério | Pontos |
|---|---:|
| Arquitetura modular | 15 |
| Contratos REST e validação | 15 |
| Erros e configuração | 15 |
| OpenAPI | 10 |
| Registros e segurança | 15 |
| Testes | 15 |
| Compilação e reprodução | 10 |
| Apresentação técnica | 5 |
| **Total** | **100** |

Para concluir o módulo, obtenha pelo menos 70 pontos e não possua falha crítica de
segurança, compilação ou reprodução.

## 32. Resumo

- TypeScript precisa ser compilado para JavaScript executável;
- compilar não publica nem inicia automaticamente;
- Git ajuda a versionar e transportar, mas não executa a API;
- XAMPP e NestJS são processos diferentes e podem coexistir;
- todo o módulo pode ser concluído localmente no Windows;
- uma entrega profissional inclui testes, contrato, segurança e documentação;
- MySQL substituirá o armazenamento em memória sem mudar a responsabilidade do Angular.

## Próximo módulo

No Módulo 6, conectaremos a API ao MySQL com Prisma, criaremos modelos, migrações,
consultas, transações e paginação sem permitir que o Angular acesse o banco diretamente.

## Fontes oficiais

- [NestJS — publicação](https://docs.nestjs.com/deployment)
- [NestJS CLI — uso](https://docs.nestjs.com/cli/usages)
- [NestJS — testes](https://docs.nestjs.com/fundamentals/testing)
- [Node.js — execução de TypeScript](https://nodejs.org/en/learn/typescript/run-natively)