AGENTS.md

1# AGENTS.md
2 
3## Visão Geral do Projeto
4 
5Este é um repositório de currículo educativo para ensinar fundamentos do desenvolvimento web a iniciantes. O currículo é um curso abrangente de 12 semanas desenvolvido pelos Microsoft Cloud Advocates, apresentando 24 lições práticas que cobrem JavaScript, CSS e HTML.
6 
7### Componentes Principais
8 
9- **Conteúdo Educativo**: 24 lições estruturadas organizadas em módulos baseados em projetos
10- **Projetos Práticos**: Terrarium, Jogo de Digitação, Extensão de Navegador, Jogo Espacial, Aplicação Bancária, Editor de Código e Assistente de Chat IA
11- **Questionários Interativos**: 48 questionários com 3 perguntas cada (avaliações pré/pós-lição)
12- **Suporte Multilíngue**: Traduções automáticas para mais de 50 idiomas via GitHub Actions
13- **Tecnologias**: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (para projetos de IA)
14 
15### Arquitetura
16 
17- Repositório educativo com estrutura baseada em lições
18- Cada pasta de lição contém README, exemplos de código e soluções
19- Projetos independentes em diretórios separados (quiz-app, vários projetos de lição)
20- Sistema de tradução usando GitHub Actions (co-op-translator)
21- Documentação servida via Docsify e disponível em PDF
22 
23## Comandos de Configuração
24 
25Este repositório destina-se principalmente ao consumo de conteúdo educativo. Para trabalhar com projetos específicos:
26 
27### Configuração Principal do Repositório
28 
29```bash
30git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
31cd Web-Dev-For-Beginners
32```
33 
34### Configuração do Quiz App (Vue 3 + Vite)
35 
36```bash
37cd quiz-app
38npm install
39npm run dev        # Iniciar servidor de desenvolvimento
40npm run build      # Construir para produção
41npm run lint       # Executar ESLint
42```
43 
44### API do Projeto Bancário (Node.js + Express)
45 
46```bash
47cd 7-bank-project/api
48npm install
49npm start          # Iniciar servidor API
50npm run lint       # Executar ESLint
51npm run format     # Formatar com Prettier
52```
53 
54### Projetos de Extensão de Navegador
55 
56```bash
57cd 5-browser-extension/solution
58npm install
59# Siga as instruções específicas do navegador para carregar extensões
60```
61 
62### Projetos de Jogo Espacial
63 
64```bash
65cd 6-space-game/solution
66npm install
67# Abra index.html no navegador ou use o Live Server
68```
69 
70### Projeto de Chat (Backend em Python)
71 
72```bash
73cd 9-chat-project/solution/backend/python
74pip install openai
75# Definir variável de ambiente GITHUB_TOKEN
76python api.py
77```
78 
79## Fluxo de Trabalho de Desenvolvimento
80 
81### Para Contribuidores de Conteúdo
82 
831. **Faça fork do repositório** na sua conta GitHub
842. **Clone o seu fork** localmente
853. **Crie uma nova branch** para as suas alterações
864. Faça alterações no conteúdo da lição ou nos exemplos de código
875. Teste quaisquer alterações de código nos diretórios de projeto relevantes
886. Submeta pull requests seguindo as diretrizes de contribuição
89 
90### Para Aprendizes
91 
921. Faça fork ou clone o repositório
932. Navegue sequencialmente pelos diretórios das lições
943. Leia os ficheiros README de cada lição
954. Complete os quizzes pré-lição em https://ff-quizzes.netlify.app/web/
965. Trabalhe os exemplos de código nas pastas das lições
976. Complete trabalhos e desafios
987. Realize os quizzes pós-lição
99 
100### Desenvolvimento ao Vivo
101 
102- **Documentação**: Execute `docsify serve` na raiz (porta 3000)
103- **Quiz App**: Execute `npm run dev` no diretório quiz-app
104- **Projetos**: Use a extensão Live Server do VS Code para projetos HTML
105- **Projetos API**: Execute `npm start` nos diretórios API respetivos
106 
107## Instruções de Teste
108 
109### Teste do Quiz App
110 
111```bash
112cd quiz-app
113npm run lint       # Verificar problemas de estilo de código
114npm run build      # Verificar se a compilação é bem-sucedida
115```
116 
117### Teste da API Bancária
118 
119```bash
120cd 7-bank-project/api
121npm run lint       # Verificar problemas de estilo de código
122node server.js     # Verificar se o servidor inicia sem erros
123```
124 
125### Abordagem Geral de Testes
126 
127- Este é um repositório educativo sem testes automatizados abrangentes
128- O teste manual foca-se em:
129  - Exemplos de código que executam sem erros
130  - Links na documentação funcionam corretamente
131  - Builds dos projetos completam com sucesso
132  - Exemplos seguem as boas práticas
133 
134### Verificações Pré-Submissão
135 
136- Execute `npm run lint` nos diretórios com package.json
137- Verifique que os links markdown são válidos
138- Teste exemplos de código no navegador ou Node.js
139- Confirme que as traduções mantêm a estrutura adequada
140 
141## Diretrizes de Estilo de Código
142 
143### JavaScript
144 
145- Use sintaxe moderna ES6+
146- Siga as configurações padrão do ESLint fornecidas nos projetos
147- Use nomes significativos de variáveis e funções para clareza educativa
148- Adicione comentários explicativos para os conceitos
149- Formate com Prettier onde estiver configurado
150 
151### HTML/CSS
152 
153- Elementos semânticos HTML5
154- Princípios de design responsivo
155- Convenções claras de nomeação de classes
156- Comentários explicando técnicas CSS para aprendizes
157 
158### Python
159 
160- Diretrizes de estilo PEP 8
161- Exemplos de código claros e educativos
162- Anotações de tipo onde ajudarem na aprendizagem
163 
164### Documentação Markdown
165 
166- Hierarquia clara de títulos
167- Blocos de código com especificação de linguagem
168- Links para recursos adicionais
169- Capturas de ecrã e imagens nas pastas `images/`
170- Texto alternativo para imagens para acessibilidade
171 
172### Organização de Ficheiros
173 
174- Lições numeradas sequencialmente (1-getting-started-lessons, 2-js-basics, etc.)
175- Cada projeto tem diretórios `solution/` e frequentemente `start/` ou `your-work/`
176- Imagens guardadas nas pastas `images/` específicas da lição
177- Traduções em estrutura `translations/{language-code}/`
178 
179## Construção e Implementação
180 
181### Deploy do Quiz App (Azure Static Web Apps)
182 
183O quiz-app está configurado para deploy em Azure Static Web Apps:
184 
185```bash
186cd quiz-app
187npm run build      # Cria a pasta dist/
188# Faz o deploy através do fluxo de trabalho do GitHub Actions ao fazer push para a main
189```
190 
191Configuração Azure Static Web Apps:
192- **Localização da app**: `/quiz-app`
193- **Localização de saída**: `dist`
194- **Workflow**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`
195 
196### Geração de PDF da Documentação
197 
198```bash
199npm install                    # Instalar docsify-to-pdf
200npm run convert               # Gerar PDF a partir do docs
201```
202 
203### Documentação Docsify
204 
205```bash
206npm install -g docsify-cli    # Instalar Docsify globalmente
207docsify serve                 # Servir em localhost:3000
208```
209 
210### Builds Específicos por Projeto
211 
212Cada diretório de projeto pode ter seu próprio processo de build:
213- Projetos Vue: `npm run build` cria bundles para produção
214- Projetos estáticos: Sem etapa de build, servir ficheiros diretamente
215 
216## Diretrizes para Pull Requests
217 
218### Formato do Título
219 
220Use títulos claros e descritivos indicativos da área de alteração:
221- `[Quiz-app] Adicionar novo quiz para lição X`
222- `[Lesson-3] Corrigir erro tipográfico no projeto terrarium`
223- `[Translation] Adicionar tradução para espanhol na lição 5`
224- `[Docs] Atualizar instruções de configuração`
225 
226### Verificações Necessárias
227 
228Antes de submeter um PR:
229 
2301. **Qualidade do Código**:
231   - Execute `npm run lint` nos diretórios de projeto afetados
232   - Corrija todos os erros e avisos de lint
233 
2342. **Verificação do Build**:
235   - Execute `npm run build` se aplicável
236   - Garanta ausência de erros no build
237 
2383. **Validação de Links**:
239   - Teste todos os links markdown
240   - Verifique referências de imagens
241 
2424. **Revisão de Conteúdo**:
243   - Revise ortografia e gramática
244   - Confirme que os exemplos de código estão corretos e educativos
245   - Verifique que as traduções mantêm o significado original
246 
247### Requisitos de Contribuição
248 
249- Concordar com o CLA da Microsoft (verificação automática no primeiro PR)
250- Seguir o [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/)
251- Consultar [CONTRIBUTING.md](./CONTRIBUTING.md) para diretrizes detalhadas
252- Referenciar números de issues na descrição do PR, se aplicável
253 
254### Processo de Revisão
255 
256- PRs revistos por mantenedores e comunidade
257- Clareza educativa é prioridade
258- Exemplos de código devem seguir as melhores práticas atuais
259- Traduções revisadas quanto a exatidão e adequação cultural
260 
261## Sistema de Tradução
262 
263### Tradução Automática
264 
265- Usa GitHub Actions com workflow co-op-translator
266- Traduz para mais de 50 idiomas automaticamente
267- Ficheiros fonte nos diretórios principais
268- Ficheiros traduzidos em `translations/{language-code}/`
269 
270### Adição de Melhorias Manuais de Tradução
271 
2721. Localize o ficheiro em `translations/{language-code}/`
2732. Faça melhorias preservando a estrutura
2743. Garanta que exemplos de código permanecem funcionais
2754. Teste qualquer conteúdo de quizzes localizado
276 
277### Metadados de Tradução
278 
279Ficheiros traduzidos incluem cabeçalho de metadados:
280```markdown
281<!--
282CO_OP_TRANSLATOR_METADATA:
283{
284  "original_hash": "...",
285  "translation_date": "...",
286  "source_file": "...",
287  "language_code": "..."
288}
289-->
290```
291 
292## Depuração e Resolução de Problemas
293 
294### Problemas Comuns
295 
296**App do Quiz não inicia**:
297- Verifique a versão do Node.js (recomendado v14+)
298- Apague `node_modules` e `package-lock.json`, execute `npm install` novamente
299- Verifique conflitos de porta (padrão: Vite usa porta 5173)
300 
301**Servidor API não inicia**:
302- Confirme que a versão do Node.js é mínima (node >=10)
303- Verifique se a porta já está em uso
304- Certifique-se de que todas as dependências foram instaladas com `npm install`
305 
306**Extensão de navegador não carrega**:
307- Verifique se o manifest.json está formatado corretamente
308- Consulte o console do navegador para erros
309- Siga as instruções específicas do navegador para instalação de extensões
310 
311**Problemas no projeto de chat em Python**:
312- Certifique-se de que o pacote OpenAI está instalado: `pip install openai`
313- Verifique se a variável de ambiente GITHUB_TOKEN está definida
314- Confirme as permissões de acesso aos GitHub Models
315 
316**Docsify não serve documentação**:
317- Instale docsify-cli globalmente: `npm install -g docsify-cli`
318- Execute desde o diretório raiz do repositório
319- Verifique se `docs/_sidebar.md` existe
320 
321### Dicas para o Ambiente de Desenvolvimento
322 
323- Use VS Code com a extensão Live Server para projetos HTML
324- Instale extensões ESLint e Prettier para formatação consistente
325- Utilize DevTools do navegador para depurar JavaScript
326- Para projetos Vue, instale a extensão Vue DevTools no navegador
327 
328### Considerações de Performance
329 
330- Grande quantidade de ficheiros traduzidos (50+ idiomas) torna os clones completos pesados
331- Use clone superficial se trabalhar apenas com conteúdo: `git clone --depth 1`
332- Exclua traduções de pesquisas ao trabalhar com conteúdo em inglês
333- Processos de build podem ser lentos na primeira execução (npm install, build Vite)
334 
335## Considerações de Segurança
336 
337### Variáveis de Ambiente
338 
339- Chaves API nunca devem ser commitadas no repositório
340- Use ficheiros `.env` (já listados no `.gitignore`)
341- Documente as variáveis de ambiente necessárias nos READMEs dos projetos
342 
343### Projetos Python
344 
345- Utilize ambientes virtuais: `python -m venv venv`
346- Mantenha dependências atualizadas
347- Tokens GitHub devem ter permissões mínimas necessárias
348 
349### Acesso aos GitHub Models
350 
351- São necessários tokens de acesso pessoal (PAT) para GitHub Models
352- Armazene os tokens como variáveis de ambiente
353- Nunca faça commit de tokens ou credenciais
354 
355## Notas Adicionais
356 
357### Público-Alvo
358 
359- Iniciantes completos em desenvolvimento web
360- Estudantes e autodidatas
361- Professores que usam o currículo em sala de aula
362- Conteúdo desenhado para acessibilidade e construção gradual de competências
363 
364### Filosofia Educativa
365 
366- Abordagem de aprendizagem baseada em projetos
367- Verificação frequente do conhecimento (quizzes)
368- Exercícios práticos de codificação
369- Exemplos de aplicação real
370- Foco nos fundamentos antes dos frameworks
371 
372### Manutenção do Repositório
373 
374- Comunidade ativa de aprendizes e contribuidores
375- Atualizações regulares de dependências e conteúdo
376- Issues e discussões monitorizadas por mantenedores
377- Atualizações de tradução automatizadas via GitHub Actions
378 
379### Recursos Relacionados
380 
381- [Módulos Microsoft Learn](https://docs.microsoft.com/learn/)
382- [Recursos do Student Hub](https://docs.microsoft.com/learn/student-hub/)
383- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) recomendado para aprendizes
384- Cursos adicionais: AI Generativa, Ciência de Dados, ML, IoT disponíveis
385 
386### Trabalhar com Projetos Específicos
387 
388Para instruções detalhadas sobre projetos individuais, consulte os ficheiros README em:
389- `quiz-app/README.md` - Aplicação de quiz Vue 3
390- `7-bank-project/README.md` - Aplicação bancária com autenticação
391- `5-browser-extension/README.md` - Desenvolvimento de extensão de navegador
392- `6-space-game/README.md` - Desenvolvimento de jogo em canvas
393- `9-chat-project/README.md` - Projeto de assistente de chat IA
394 
395### Estrutura Monorepo
396 
397Embora não seja um monorepo tradicional, este repositório contém múltiplos projetos independentes:
398- Cada lição é autocontida
399- Projetos não partilham dependências
400- Trabalhe em projetos individuais sem afetar outros
401- Clone todo o repositório para a experiência completa do currículo
402 
403---
404 
405<!-- CO-OP TRANSLATOR DISCLAIMER START -->
406**Aviso Legal**:  
407Este documento foi traduzido utilizando o serviço de tradução automática [Co-op Translator](https://github.com/Azure/co-op-translator). Embora nos esforcemos pela precisão, esteja ciente de que traduções automáticas podem conter erros ou imprecisões. O documento original na sua língua nativa deve ser considerado a fonte oficial. Para informações críticas, recomenda-se tradução profissional humana. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações erradas decorrentes do uso desta tradução.
408<!-- CO-OP TRANSLATOR DISCLAIMER END -->