diff --git a/localisation/pt-br/README.md b/localisation/pt-br/README.md new file mode 100644 index 0000000..73d15f5 --- /dev/null +++ b/localisation/pt-br/README.md @@ -0,0 +1,106 @@ +# Workshop de Codificação GitHub Copilot Vibe + +![GitHub Copilot - Ghiblifiled](../../images/ghcp.jpg) + +Vamos codar com vibe usando o [GitHub Copilot](https://docs.github.com/copilot/about-github-copilot/what-is-github-copilot) e seus recursos mais novos e incríveis em várias linguagens de programação como Python, JavaScript, Java e .NET, além de tornar os aplicativos nativos da nuvem através da containerização. Você está pronto para mergulhar? + +## Contexto + +A Contoso é uma empresa que vende produtos para várias atividades ao ar livre. O departamento de marketing da Contoso gostaria de lançar um site de micro mídia social para promover seus produtos para clientes existentes e potenciais. Como seu primeiro MVP, eles querem construir rapidamente o site. O departamento de TI da Contoso atualmente tem dois desenvolvedores usando Python e JavaScript, respectivamente. A data de lançamento está se aproximando rapidamente, então ambos os desenvolvedores devem entregar a aplicação rapidamente. + +Mas aqui está a situação... + +## Objetivos do Workshop + +- Construir aplicações usando o Modo Agente do GitHub Copilot. +- Adicionar instruções customizadas ao GitHub Copilot para que você tenha mais controle sobre o GitHub Copilot. +- Adicionar vários servidores MCP ao GitHub Copilot para que você construa as aplicações com mais precisão. + +## Workshop no Seu Idioma + +Este material do workshop está atualmente disponível nos seguintes idiomas: + +[English](../../README.md) | [Español](../es-es/) | [Português](./README.md) | [Français](../fr-fr/) | [中文(简体)](../zh-cn/) | [日本語](../ja-jp/) | [한국어](../ko-kr/) + +## Pré-requisitos + +Durante este workshop, [GitHub Codespaces](https://docs.github.com/en/codespaces/about-codespaces/what-are-codespaces) é altamente recomendado porque não há necessidade de preparação, exceto um navegador web. No entanto, se você realmente precisar usar sua máquina, certifique-se de ter instalado tudo identificado abaixo. + +### Comum + +- [Visual Studio Code](https://code.visualstudio.com/) +- Extensão [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) do VS Code +- Extensão [GitHub Copilot Chat](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot-chat) do VS Code +- 💥 Para usuários Windows 👉 [PowerShell 7](https://learn.microsoft.com/powershell/scripting/install/installing-powershell) +- [git CLI](https://git-scm.com/downloads) +- [GitHub CLI](https://cli.github.com/) +- [Docker Desktop](https://docs.docker.com/get-started/introduction/get-docker-desktop/) + +### Python + +- [pyenv](https://github.com/pyenv/pyenv) ou [pyenv for Windows](https://github.com/pyenv-win/pyenv-win) +- Python 3.12+ através do pyenv +- Gerenciador de pacotes `uv` (recomendado) ou `pip` +- Extensão [Python](https://marketplace.visualstudio.com/items/?itemName=ms-python.python) do VS Code +- Extensão [Pylance](https://marketplace.visualstudio.com/items/?itemName=ms-python.vscode-pylance) do VS Code +- Extensão [Python Debugger](https://marketplace.visualstudio.com/items/?itemName=ms-python.debugpy) do VS Code +- Extensão [autopep8](https://marketplace.visualstudio.com/items/?itemName=ms-python.autopep8) do VS Code + +### JavaScript + +- [nvm](https://github.com/nvm-sh/nvm) ou [nvm for Windows](https://github.com/coreybutler/nvm-windows) +- A versão LTS mais recente do [Node.js](https://nodejs.org/) através do nvm + +### Java + +- [SDKMAN](https://sdkman.io/) +- [OpenJDK 21](https://learn.microsoft.com/java/openjdk/download) através do SDKMAN +- [Apache Maven](https://maven.apache.org/download.cgi) através do SDKMAN +- [Gradle Build Tool](https://docs.gradle.org/current/userguide/installation.html) através do SDKMAN +- [Spring Boot Initializr](https://docs.spring.io/spring-boot/cli/installation.html) através do SDKMAN +- Extensão [Extension Pack for Java](https://marketplace.visualstudio.com/items/?itemName=vscjava.vscode-java-pack) do VS Code +- Extensão [Spring Boot Extension Pack](https://marketplace.visualstudio.com/items/?itemName=vmware.vscode-boot-dev-pack) do VS Code + +### .NET + +- [.NET SDK 9](https://dotnet.microsoft.com/download/dotnet/9.0) +- Extensão [VS Code C# Dev Kit](https://marketplace.visualstudio.com/items/?itemName=ms-dotnettools.csdevkit) + +## Documento de Requisitos do Produto + +Em primeiro lugar, o lugar para você começar é este [PRD (Documento de Requisitos do Produto)](./product-requirements.md). Este documento lhe dará uma melhor compreensão do que fazer e como fazer. + +## Instruções do Workshop + +Este é um workshop autoguiado seguindo os links abaixo: + +| Etapa | Link | +|------------------------------------------|---------------------------------------------------------| +| 00: Ambiente de Desenvolvimento | [00-setup.md](./docs/00-setup.md) | +| 01: Backend Python | [01-python.md](./docs/01-python.md) | +| 02: Frontend JavaScript | [02-javascript.md](./docs/02-javascript.md) | +| 03: Migração Java do Python | [03-java.md](./docs/03-java.md) | +| 04: Migração .NET do JavaScript | [04-dotnet.md](./docs/04-dotnet.md) | +| 05: Containerização | [05-containerization.md](./docs/05-containerization.md) | + +## Exemplos Completos + +Confira o exemplo completo de cada aplicação. Eles também foram codificados com vibe usando o GitHub Copilot, portanto, podem não ser perfeitos, e você não precisa seguir o app. + +| Linguagem | Aplicação | Localização | +|---------------------|-------------|--------------------------------------| +| Backend Python | FastAPI | [python](./complete/python/) | +| Frontend JavaScript | React | [javascript](./complete/javascript/) | +| Backend Java | Spring Boot | [java](./complete/java/) | +| Frontend .NET | Blazor | [dotnet](./complete/dotnet/) | +| Containerização | Container | [containerization](./complete/) | + +## Leia Mais... + +- [GitHub Codespaces](https://docs.github.com/en/codespaces/about-codespaces/what-are-codespaces) +- [GitHub Copilot](https://docs.github.com/en/copilot/about-github-copilot/what-is-github-copilot) +- [GitHub Copilot: Agent Mode](https://code.visualstudio.com/blogs/2025/04/07/agentMode) +- [GitHub Copilot: MCP](https://code.visualstudio.com/blogs/2025/05/12/agent-mode-meets-mcp) +- [GitHub Copilot: Custom Instructions](https://code.visualstudio.com/docs/copilot/copilot-customization) +- [GitHub Copilot: Changing AI Models](https://docs.github.com/en/copilot/using-github-copilot/ai-models/changing-the-ai-model-for-copilot-chat?tool=vscode) +- [Curated MCP Servers](https://github.com/modelcontextprotocol/servers) \ No newline at end of file diff --git a/localisation/pt-br/complete/README.md b/localisation/pt-br/complete/README.md new file mode 100644 index 0000000..740b0b5 --- /dev/null +++ b/localisation/pt-br/complete/README.md @@ -0,0 +1,56 @@ +# Exemplos de Aplicações Completas + +Aqui está a lista de exemplos de aplicações completas. Como elas também foram codificadas com vibe, você pode verificar como foram construídas. + +| Aplicação | Localização | +|-------------|-----------------------------| +| FastAPI | [python](./python/) | +| React | [javascript](./javascript/) | +| Spring Boot | [java](./java/) | +| Blazor | [dotnet](./dotnet/) | + +## Exemplo de Containerização + +### Pré-requisitos + +Consulte a documentação [README](../README.md) para preparação. + +### Primeiros Passos + +1. Certifique-se de que o Docker está rodando. + + ```bash + docker info + ``` + +1. Obtenha a raiz do repositório. + + ```bash + # bash/zsh + REPOSITORY_ROOT=$(git rev-parse --show-toplevel) + ``` + + ```powershell + # PowerShell + $REPOSITORY_ROOT = git rev-parse --show-toplevel + ``` + +1. Navegue para o diretório `complete`. + + ```bash + cd $REPOSITORY_ROOT/complete + ``` + +1. Execute as aplicações containerizadas. + + ```bash + docker compose up --build -d + ``` + +1. Abra um navegador web e navegue para `http://localhost:3030`. +1. Verifique se a aplicação web está funcionando adequadamente. +1. Limpe executando o seguinte comando para remover as aplicações containerizadas. + + ```bash + docker compose down --rmi all + ``` \ No newline at end of file diff --git a/localisation/pt-br/complete/dotnet/README.md b/localisation/pt-br/complete/dotnet/README.md new file mode 100644 index 0000000..8eb928b --- /dev/null +++ b/localisation/pt-br/complete/dotnet/README.md @@ -0,0 +1,35 @@ +# Exemplo de Aplicação .NET + +## Pré-requisitos + +Consulte a documentação [README](../../README.md) para preparação. + +## Primeiros Passos + +### Executar Backend Spring Boot + +Use [Exemplo de Aplicação Java](../java/). + +> **NOTA**: Se você usar GitHub Codespaces, certifique-se de que a porta da aplicação Java, `8080`, está definida como **pública**. + +### Executar Frontend Blazor + +1. Obtenha a raiz do repositório. + + ```bash + # bash/zsh + REPOSITORY_ROOT=$(git rev-parse --show-toplevel) + ``` + + ```powershell + # PowerShell + $REPOSITORY_ROOT = git rev-parse --show-toplevel + ``` + +1. Execute a aplicação. + + ```bash + dotnet watch run --project $REPOSITORY_ROOT/complete/dotnet/Contoso.BlazorApp + ``` + +1. Verifique se a aplicação web está funcionando adequadamente. \ No newline at end of file diff --git a/localisation/pt-br/complete/java/socialapp/README.md b/localisation/pt-br/complete/java/socialapp/README.md new file mode 100644 index 0000000..183d3a8 --- /dev/null +++ b/localisation/pt-br/complete/java/socialapp/README.md @@ -0,0 +1,367 @@ +# Aplicação Java de Exemplo + +Uma aplicação REST API Spring Boot abrangente para uma plataforma de mídia social com operações CRUD completas para posts, comentários e curtidas. + +## Visão Geral do Projeto + +Esta é uma aplicação Spring Boot pronta para produção construída com as seguintes especificações: + +- **Nome do Pacote**: `com.contoso.socialapp` +- **ID do Artefato**: `socialapp` +- **ID do Grupo**: `com.contoso` +- **Tipo de Pacote**: `jar` +- **Versão Java**: OpenJDK 21 +- **Ferramenta de Build**: Gradle +- **Banco de Dados**: SQLite (embarcado) +- **Porta**: 8080 + +### Dependências do Projeto + +- **Spring Boot 3.2.5**: Framework principal +- **Spring Web**: Endpoints da RESTful API +- **Spring Data JPA**: Operações de banco de dados +- **Spring Boot Actuator**: Monitoramento da aplicação +- **Spring Boot Validation**: Validação de entrada +- **SQLite**: Banco de dados embarcado +- **Hibernate Community Dialects**: Suporte ao SQLite +- **Springdoc OpenAPI**: Documentação da API (Swagger UI) +- **Lombok**: Redução de código boilerplate + +### Estrutura do Projeto + +```text +src/ +├── main/ +│ ├── java/ +│ │ └── com/ +│ │ └── contoso/ +│ │ └── socialapp/ +│ │ ├── SocialAppApplication.java # Classe principal da aplicação +│ │ ├── config/ +│ │ │ ├── WebConfig.java # Configuração CORS +│ │ │ └── OpenApiConfig.java # Configuração Swagger/OpenAPI +│ │ ├── controller/ +│ │ │ ├── HealthController.java # Endpoints de saúde +│ │ │ ├── PostController.java # Gerenciamento de posts +│ │ │ └── CommentController.java # Gerenciamento de comentários e curtidas +│ │ ├── model/ +│ │ │ ├── Post.java # Entidade Post +│ │ │ ├── Comment.java # Entidade Comment +│ │ │ ├── Like.java # Entidade Like +│ │ │ └── dto/ # Objetos de Transferência de Dados +│ │ ├── repository/ +│ │ │ ├── PostRepository.java # Acesso a dados de posts +│ │ │ ├── CommentRepository.java # Acesso a dados de comentários +│ │ │ └── LikeRepository.java # Acesso a dados de curtidas +│ │ └── service/ +│ │ ├── PostService.java # Lógica de negócio de posts +│ │ └── CommentService.java # Lógica de negócio de comentários +│ └── resources/ +│ ├── application.properties # Configuração da aplicação +│ └── data.sql # Dados de exemplo (opcional) +└── test/ + └── java/ + └── com/ + └── contoso/ + └── socialapp/ + └── SocialAppApplicationTests.java # Testes de integração +``` + +## Funcionalidades + +- ✅ API RESTful completa para operações de mídia social +- ✅ Gerenciamento de posts (Criar, Ler, Atualizar, Excluir) +- ✅ Sistema de comentários com operações CRUD completas +- ✅ Funcionalidade de curtir/descurtir +- ✅ Banco de dados SQLite com JPA/Hibernate +- ✅ Documentação OpenAPI/Swagger +- ✅ CORS habilitado para localhost e GitHub Codespaces +- ✅ Configuração dinâmica de URL do servidor +- ✅ Endpoints de verificação de saúde +- ✅ Integração com Spring Boot Actuator +- ✅ Tratamento abrangente de erros +- ✅ Validação de entrada com Bean Validation + +## Início Rápido + +### Pré-requisitos + +Consulte a documentação [README](../../README.md) para preparação. + +### 1. Configuração do Ambiente + +Primeiro, defina a variável de ambiente `$REPOSITORY_ROOT`. + +```bash +# bash/zsh +REPOSITORY_ROOT=$(git rev-parse --show-toplevel) +``` + +```powershell +# PowerShell +$REPOSITORY_ROOT = git rev-parse --show-toplevel +``` + +Em seguida, navegue até o diretório java. + +```bash +cd $REPOSITORY_ROOT/complete/java +``` + +### 2. Construir a Aplicação + +```bash +# Tornar gradlew executável (se necessário) +chmod +x ./gradlew + +# Construir o projeto +./gradlew build +``` + +### 3. Executar a Aplicação + +```bash +# Iniciar a aplicação usando Gradle +./gradlew bootRun + +# Alternativa: Executar o arquivo JAR diretamente +# java -jar build/libs/socialapp-0.0.1-SNAPSHOT.jar +``` + +### 4. Verificar se a Aplicação está Executando + +```bash +# Verificar endpoint de saúde +curl http://localhost:8080/api/health + +# Resposta esperada: {"status":"healthy"} +``` + +### 5. Acessar Documentação da API + +Abra seu navegador e navegue para: + +- **Swagger UI**: [http://localhost:8080/swagger-ui.html](http://localhost:8080/swagger-ui.html) +- **OpenAPI JSON**: [http://localhost:8080/v3/api-docs](http://localhost:8080/v3/api-docs) + +## Endpoints da API + +### Saúde e Boas-vindas + +- `GET /api/health` - Endpoint personalizado de verificação de saúde +- `GET /api/welcome` - Endpoint de mensagem de boas-vindas + +### Gerenciamento de Posts + +- `GET /api/posts` - Obter todos os posts +- `GET /api/posts/{id}` - Obter post específico por ID +- `POST /api/posts` - Criar um novo post +- `PATCH /api/posts/{id}` - Atualizar um post existente +- `DELETE /api/posts/{id}` - Excluir um post + +### Gerenciamento de Comentários + +- `GET /api/posts/{postId}/comments` - Obter todos os comentários de um post +- `GET /api/posts/{postId}/comments/{commentId}` - Obter comentário específico +- `POST /api/posts/{postId}/comments` - Adicionar um comentário a um post +- `PATCH /api/posts/{postId}/comments/{commentId}` - Atualizar um comentário +- `DELETE /api/posts/{postId}/comments/{commentId}` - Excluir um comentário + +### Gerenciamento de Curtidas + +- `POST /api/posts/{postId}/like` - Curtir um post +- `DELETE /api/posts/{postId}/like` - Descurtir um post + +### Spring Boot Actuator + +- `GET /actuator/health` - Indicador de saúde do Spring Boot +- `GET /actuator/info` - Informações da aplicação + +## Testando a API + +### Usando Exemplos de cURL + +#### Criar um Post + +```bash +curl -X POST http://localhost:8080/api/posts \ + -H "Content-Type: application/json" \ + -d '{ + "title": "Meu Primeiro Post", + "content": "Este é o conteúdo do meu primeiro post!", + "authorName": "João Silva" + }' +``` + +#### Obter Todos os Posts + +```bash +curl http://localhost:8080/api/posts +``` + +#### Adicionar um Comentário + +```bash +curl -X POST http://localhost:8080/api/posts/1/comments \ + -H "Content-Type: application/json" \ + -d '{ + "content": "Ótimo post!", + "authorName": "Maria Santos" + }' +``` + +#### Curtir um Post + +```bash +curl -X POST http://localhost:8080/api/posts/1/like \ + -H "Content-Type: application/json" \ + -d '{ + "userName": "joao_silva" + }' +``` + +### Usando Swagger UI + +1. Abra [http://localhost:8080/swagger-ui.html](http://localhost:8080/swagger-ui.html) +2. Explore os endpoints disponíveis +3. Clique em "Try it out" em qualquer endpoint +4. Preencha os parâmetros e clique em "Execute" + +## Desenvolvimento + +### Executando Testes + +```bash +# Executar todos os testes +./gradlew test + +# Executar com relatório de cobertura +./gradlew test jacocoTestReport + +# Executar classe de teste específica +./gradlew test --tests "SocialAppApplicationTests" +``` + +### Banco de Dados + +A aplicação usa SQLite como banco de dados embarcado: + +- **Arquivo do banco de dados**: `sns_api.db` (criado automaticamente) +- **Localização**: Diretório raiz do projeto +- **Schema**: Gerado automaticamente pelo Hibernate +- **Dados de exemplo**: Carregados de `data.sql` (se presente) + +Para resetar o banco de dados, simplesmente exclua o arquivo `sns_api.db` e reinicie a aplicação. + +## Configuração + +### Propriedades da Aplicação + +Configurações principais em `application.properties`: + +```properties +# Configurações da Aplicação +spring.application.name=socialapp +server.port=8080 + +# Configuração do Banco de Dados +spring.datasource.url=jdbc:sqlite:sns_api.db +spring.jpa.hibernate.ddl-auto=update + +# Configuração OpenAPI/Swagger +springdoc.swagger-ui.path=/swagger-ui.html +springdoc.swagger-ui.operationsSorter=method +``` + +### Configuração CORS + +A aplicação suporta tanto localhost quanto GitHub Codespaces: + +- **Localhost**: `http://localhost:8080` +- **GitHub Codespaces**: Detectado e configurado automaticamente de forma dinâmica + +### Detecção de Ambiente + +A aplicação detecta automaticamente o ambiente de execução: + +- **Desenvolvimento Local**: Usa `http://localhost:8080` +- **GitHub Codespaces**: Usa `https://{codespace-name}-8080.{domain}` + +## Implantação + +### Construindo para Produção + +```bash +# Criar JAR de produção +./gradlew clean build + +# Localização do JAR +ls -la build/libs/socialapp-0.0.1-SNAPSHOT.jar +``` + +### Executando em Produção + +```bash +# Executar com perfil de produção +java -jar build/libs/socialapp-0.0.1-SNAPSHOT.jar --spring.profiles.active=prod + +# Ou com porta personalizada +java -jar build/libs/socialapp-0.0.1-SNAPSHOT.jar --server.port=8081 +``` + +## Solução de Problemas + +### Problemas Comuns + +#### Porta Já em Uso + +```bash +# Encontrar processo usando porta 8080 +lsof -i :8080 + +# Matar o processo (substitua PID) +kill -9 + +# Ou usar uma porta diferente +./gradlew bootRun --args='--server.port=8081' +``` + +#### Falhas de Build + +```bash +# Limpar e reconstruir +./gradlew clean build + +# Atualizar wrapper Gradle +./gradlew wrapper --gradle-version=8.5 +``` + +#### Problemas com Banco de Dados + +```bash +# Resetar banco de dados +rm sns_api.db +./gradlew bootRun +``` + +### Logs e Monitoramento + +- **Logs da aplicação**: Saída do console ao executar `./gradlew bootRun` +- **Verificação de saúde**: `GET /actuator/health` +- **Informações da aplicação**: `GET /actuator/info` + +## Considerações de Segurança + +⚠️ **Configuração de Desenvolvimento**: A configuração atual é otimizada para desenvolvimento com: + +- CORS habilitado para todas as origens +- Banco de dados SQLite (não adequado para escala de produção) +- Sem autenticação/autorização + +Para implantação em produção, considere: + +- Restringir CORS a domínios específicos +- Usar PostgreSQL/MySQL em vez de SQLite +- Implementar Spring Security para autenticação +- Adicionar limitação de taxa e sanitização de entrada +- Usar criptografia HTTPS/TLS \ No newline at end of file diff --git a/localisation/pt-br/complete/javascript/README.md b/localisation/pt-br/complete/javascript/README.md new file mode 100644 index 0000000..9eff94e --- /dev/null +++ b/localisation/pt-br/complete/javascript/README.md @@ -0,0 +1,43 @@ +# Exemplo de Aplicação JavaScript + +## Pré-requisitos + +Consulte a documentação [README](../../README.md) para preparação. + +## Primeiros Passos + +### Executar Backend FastAPI + +Use [Exemplo de Aplicação Python](../python/). + +> **NOTA**: Se você usar GitHub Codespaces, certifique-se de que a porta da aplicação Python, `8000`, está definida como **pública**. + +### Executar Frontend React + +1. Obtenha a raiz do repositório. + + ```bash + # bash/zsh + REPOSITORY_ROOT=$(git rev-parse --show-toplevel) + ``` + + ```powershell + # PowerShell + $REPOSITORY_ROOT = git rev-parse --show-toplevel + ``` + +1. Instale pacotes npm. + + ```bash + cd $REPOSITORY_ROOT/complete/javascript + npm install + ``` + +1. Execute a aplicação. + + ```bash + npm run dev + ``` + +1. Abra um navegador web e navegue para `http://localhost:3000`. +1. Verifique se a aplicação web está funcionando adequadamente. \ No newline at end of file diff --git a/localisation/pt-br/complete/python/README.md b/localisation/pt-br/complete/python/README.md new file mode 100644 index 0000000..12f292c --- /dev/null +++ b/localisation/pt-br/complete/python/README.md @@ -0,0 +1,292 @@ +# Aplicação Python de Exemplo + +Uma implementação completa de backend FastAPI para um Serviço de Rede Social Simples (SNS) que permite aos usuários criar, recuperar, atualizar e excluir posts; adicionar comentários; e curtir/descurtir posts. + +## 🏗️ Visão Geral da Arquitetura + +- **Framework**: FastAPI com Python 3.12+ +- **Banco de Dados**: SQLite (`sns_api.db`) +- **Documentação da API**: Swagger UI + especificação OpenAPI 3.1 +- **CORS**: Habilitado para requisições cross-origin +- **Validação de Dados**: modelos Pydantic com validação abrangente + +## 📁 Estrutura do Projeto + +```text +python/ +├── main.py # Ponto de entrada da aplicação FastAPI +├── models.py # Modelos de dados e esquemas Pydantic +├── database.py # Operações do banco de dados SQLite +├── openapi.yaml # Especificação OpenAPI 3.0.1 +├── sns_api.db # Arquivo de banco de dados SQLite (criado automaticamente) +├── README.md # Esta documentação +└── .venv/ # Ambiente virtual (criado durante a configuração) +``` + +## 🚀 Início Rápido + +### Pré-requisitos + +Consulte a documentação [README](../../README.md) para preparação. + +### 1. Configuração do Ambiente + +Primeiro, defina a variável de ambiente `$REPOSITORY_ROOT`. + +```bash +# bash/zsh +REPOSITORY_ROOT=$(git rev-parse --show-toplevel) +``` + +```powershell +# PowerShell +$REPOSITORY_ROOT = git rev-parse --show-toplevel +``` + +Em seguida, navegue até o diretório python e crie um ambiente virtual: + +```bash +cd $REPOSITORY_ROOT/complete/python +``` + +Crie o ambiente virtual + +```bash +# Usando uv (recomendado) +uv venv .venv +``` + +```bash +# Usando Python padrão (alternativa) +python -m venv .venv +``` + +### 2. Ativar Ambiente Virtual + +```bash +# No Linux/macOS +source .venv/bin/activate +``` + +```bash +# No Windows Command Prompt +.venv\Scripts\activate +``` + +### 3. Instalar Dependências + +```bash +# Usando uv (recomendado) +uv pip install fastapi uvicorn python-multipart pyyaml +``` + +```bash +# Usando pip (alternativa) +pip install fastapi uvicorn python-multipart pyyaml +``` + +### 4. Copiar Especificação OpenAPI + +Copie a especificação OpenAPI do diretório pai. + +```bash +# No Linux/macOS +cp ../openapi.yaml . +``` + +```powershell +# No Windows Command Prompt +xcopy ..\openapi.yaml . +``` + +### 5. Executar a Aplicação + +Inicie o servidor de desenvolvimento + +```bash +uvicorn main:app --host 0.0.0.0 --port 8000 --reload +``` + +A aplicação estará disponível em: + +- **URL Base da API**: `http://localhost:8000/api/` +- **Swagger UI**: `http://localhost:8000/docs` +- **Especificação OpenAPI**: `http://localhost:8000/openapi.json` + +## 📊 Esquema do Banco de Dados + +A aplicação usa SQLite com as seguintes tabelas: + +### Tabela Posts + +- `id` (TEXT, PRIMARY KEY) - UUID +- `username` (TEXT, NOT NULL) - Nome de usuário do autor +- `content` (TEXT, NOT NULL) - Conteúdo do post +- `created_at` (TEXT, NOT NULL) - Timestamp ISO +- `updated_at` (TEXT, NOT NULL) - Timestamp ISO + +### Tabela Comments + +- `id` (TEXT, PRIMARY KEY) - UUID +- `post_id` (TEXT, NOT NULL) - Chave estrangeira para posts +- `username` (TEXT, NOT NULL) - Nome de usuário do autor +- `content` (TEXT, NOT NULL) - Conteúdo do comentário +- `created_at` (TEXT, NOT NULL) - Timestamp ISO +- `updated_at` (TEXT, NOT NULL) - Timestamp ISO + +### Tabela Likes + +- `post_id` (TEXT, NOT NULL) - Chave estrangeira para posts +- `username` (TEXT, NOT NULL) - Usuário que curtiu +- `liked_at` (TEXT, NOT NULL) - Timestamp ISO +- Chave primária: `(post_id, username)` + +## 🔌 Endpoints da API + +### Posts + +- `GET /api/posts` - Listar todos os posts +- `POST /api/posts` - Criar um novo post +- `GET /api/posts/{postId}` - Obter um post específico +- `PATCH /api/posts/{postId}` - Atualizar um post +- `DELETE /api/posts/{postId}` - Excluir um post + +### Comentários + +- `GET /api/posts/{postId}/comments` - Listar comentários de um post +- `POST /api/posts/{postId}/comments` - Criar um comentário +- `GET /api/posts/{postId}/comments/{commentId}` - Obter um comentário específico +- `PATCH /api/posts/{postId}/comments/{commentId}` - Atualizar um comentário +- `DELETE /api/posts/{postId}/comments/{commentId}` - Excluir um comentário + +### Curtidas + +- `POST /api/posts/{postId}/likes` - Curtir um post +- `DELETE /api/posts/{postId}/likes?username={username}` - Descurtir um post + +## 🧪 Testando a API + +### Usando cURL + +#### Criar um Post + +```bash +curl -X POST "http://localhost:8000/api/posts" \ + -H "Content-Type: application/json" \ + -d '{"username": "john_doe", "content": "Olá Mundo! Este é meu primeiro post."}' +``` + +#### Obter Todos os Posts + +```bash +curl -X GET "http://localhost:8000/api/posts" +``` + +#### Adicionar um Comentário + +```bash +curl -X POST "http://localhost:8000/api/posts/{POST_ID}/comments" \ + -H "Content-Type: application/json" \ + -d '{"username": "jane_smith", "content": "Ótimo post!"}' +``` + +#### Curtir um Post + +```bash +curl -X POST "http://localhost:8000/api/posts/{POST_ID}/likes" \ + -H "Content-Type: application/json" \ + -d '{"username": "alice_johnson"}' +``` + +### Usando Swagger UI + +1. Navegue para `http://localhost:8000/docs` +2. Explore e teste todos os endpoints da API interativamente +3. Visualize esquemas e exemplos de request/response + +## 📝 Modelos de Dados + +### Modelos de Request + +- `NewPostRequest`: `{username: str, content: str}` +- `UpdatePostRequest`: `{username: str, content: str}` +- `NewCommentRequest`: `{username: str, content: str}` +- `UpdateCommentRequest`: `{username: str, content: str}` +- `LikeRequest`: `{username: str}` + +### Modelos de Response + +- `Post`: Objeto post completo com metadados e contadores +- `Comment`: Objeto comentário completo com metadados +- `LikeResponse`: Confirmação de curtida com timestamp + +## ⚙️ Configuração + +### Variáveis de Ambiente + +A aplicação usa configurações padrão mas pode ser personalizada: + +- **Banco de Dados**: Arquivo SQLite `sns_api.db` (criado automaticamente) +- **Host**: `0.0.0.0` (todas as interfaces) +- **Porta**: `8000` +- **CORS**: Habilitado para todas as origens + +### Considerações para Produção + +Para implantação em produção, considere: + +1. **Banco de Dados**: Mude para PostgreSQL ou MySQL +2. **Variáveis de Ambiente**: Use para configuração sensível +3. **Segurança**: Adicione autenticação e autorização +4. **CORS**: Restrinja a domínios específicos +5. **Logging**: implemente logging estruturado +6. **Monitoramento**: Adicione verificações de saúde e métricas + +## 🛠️ Desenvolvimento + +### Organização de Arquivos + +- **`main.py`**: Configuração da app FastAPI, middleware e definições de rotas +- **`models.py`**: Modelos Pydantic para validação e serialização de dados +- **`database.py`**: Operações SQLite, gerenciamento de conexão e funções CRUD + +### Estilo de Código + +O projeto segue: + +- Diretrizes de estilo Python PEP 8 +- Melhores práticas do FastAPI +- Padrões de programação funcional +- Type hints em todo o código +- Tratamento de erros abrangente + +### Adicionando Novas Funcionalidades + +1. Defina modelos Pydantic em `models.py` +2. Adicione operações de banco de dados em `database.py` +3. Crie endpoints da API em `main.py` +4. Atualize a especificação OpenAPI se necessário + +## 🐛 Solução de Problemas + +### Problemas Comuns + +1. **Porta já em uso**: Mude a porta com `--port 8001` +2. **Problemas com ambiente virtual**: Recrie com `rm -rf .venv && uv venv .venv` +3. **Banco de dados bloqueado**: Pare todas as instâncias em execução da aplicação +4. **Erros de importação**: Certifique-se de que o ambiente virtual está ativado + +### Modo Debug + +Execute com logging adicional: + +```bash +uvicorn main:app --host 0.0.0.0 --port 8000 --reload --log-level debug +``` + +## 📚 Recursos Adicionais + +- [Documentação do FastAPI](https://fastapi.tiangolo.com/) +- [Documentação do Pydantic](https://docs.pydantic.dev/) +- [Documentação do SQLite](https://sqlite.org/docs.html) +- [Especificação OpenAPI](https://swagger.io/specification/) \ No newline at end of file diff --git a/localisation/pt-br/docs/00-setup.md b/localisation/pt-br/docs/00-setup.md new file mode 100644 index 0000000..ea494ca --- /dev/null +++ b/localisation/pt-br/docs/00-setup.md @@ -0,0 +1,352 @@ +# 00: Ambiente de Desenvolvimento + +Nesta etapa, você está configurando o ambiente de desenvolvimento para o workshop. + +## Pré-requisitos + +Consulte a documentação [README](../README.md) para preparação. + +## Primeiros Passos + +- [Usar GitHub Codespaces](#usar-github-codespaces) +- [Usar Visual Studio Code](#usar-visual-studio-code) + - [Instalar PowerShell 👉 Para Usuários Windows](#instalar-powershell--para-usuários-windows) + - [Instalar git CLI](#instalar-git-cli) + - [Instalar GitHub CLI](#instalar-github-cli) + - [Instalar Docker Desktop](#instalar-docker-desktop) + - [Instalar Visual Studio Code](#instalar-visual-studio-code) + - [Iniciar Visual Studio Code](#iniciar-visual-studio-code) + - [Configurar Servidores MCP](#configurar-servidores-mcp) +- [Verificar o Modo Agente do GitHub Copilot](#verificar-o-modo-agente-do-github-copilot) +- [Preparar Instruções Customizadas](#preparar-instruções-customizadas) +- [Analisar Documento de Requisitos do Produto (PRD) e Projetar API](#analisar-documento-de-requisitos-do-produto-prd-e-projetar-api) + +## Usar GitHub Codespaces + +1. Dê uma olhada na imagem abaixo e siga os passos na ordem de clicar ![a imagem do botão "code"](https://img.shields.io/badge/%3C%3E_Code-green) 👉 ![a imagem do botão "codespaces"](https://img.shields.io/badge/Codespaces-white) 👉 ![a imagem do botão "create codespace on main"](https://img.shields.io/badge/Create_codespace_on_main-green) e criar uma nova instância do GitHub Codespace. Pode levar de 5-10 minutos dependendo do status da rede. + + ![Iniciando com GitHub Codespaces](./images/setup-01.png) + +2. Uma vez que a instância do GitHub Codespace esteja pronta, abra um terminal e execute o seguinte comando para verificar se tudo que você precisa foi devidamente instalado ou não. + + ```bash + # Python + python --version + ``` + + ```bash + # Node.js + node --version + npm --version + + ``` + + ```bash + # JDK + java --version + ``` + + ```bash + # .NET SDK + dotnet --list-sdks + ``` + +3. Verifique o status do seu repositório. + + ```bash + git remote -v + ``` + + Você deve conseguir ver o seguinte. + + ```bash + origin https://github.com/microsoft/github-copilot-vibe-coding-workshop.git (fetch) + origin https://github.com/microsoft/github-copilot-vibe-coding-workshop.git (push) + ``` + + Se você ver algo diferente do acima, delete a instância do GitHub Codespace e recrie-a. + +4. Vá para a seção [Configurar Servidores MCP](#configurar-servidores-mcp). + +**👇👇👇 Ao invés disso, se você gostaria de usar VS Code em sua máquina local, siga as instruções abaixo. A seção abaixo não se aplica àqueles que usam GitHub Codespaces. 👇👇👇** + +## Usar Visual Studio Code + +### Instalar PowerShell 👉 Para Usuários Windows + +1. Verifique se você já instalou o PowerShell ou não. + + ```bash + # Bash/Zsh + which pwsh + ``` + + ```bash + # PowerShell + Get-Command pwsh + ``` + + Se você não vir o caminho do comando `pwsh`, significa que você ainda não instalou o PowerShell. Visite a [página de instalação do PowerShell](https://learn.microsoft.com/powershell/scripting/install/installing-powershell) e siga as instruções. + +1. Verifique a versão do seu PowerShell. + + ```bash + pwsh --version + ``` + + `7.5.0` ou superior é recomendado. Se o seu for inferior a isso, visite a [página de instalação do PowerShell](https://learn.microsoft.com/powershell/scripting/install/installing-powershell) e siga as instruções. + +### Instalar git CLI + +1. Verifique se você já instalou o git CLI ou não. + + ```bash + # Bash/Zsh + which git + ``` + + ```bash + # PowerShell + Get-Command git + ``` + + Se você não vir o caminho do comando `git`, significa que você ainda não instalou o git CLI. Visite a [página de instalação do git CLI](https://git-scm.com/downloads) e siga as instruções. + +1. Verifique a versão do seu git CLI. + + ```bash + git --version + ``` + + `2.39.0` ou superior é recomendado. Se o seu for inferior a isso, visite a [página de instalação do git CLI](https://git-scm.com/downloads) e siga as instruções. + +### Instalar GitHub CLI + +1. Verifique se você já instalou o GitHub CLI ou não. + + ```bash + # Bash/Zsh + which gh + ``` + + ```bash + # PowerShell + Get-Command gh + ``` + + Se você não vir o caminho do comando `gh`, significa que você ainda não instalou o GitHub CLI. Visite a [página de instalação do GitHub CLI](https://cli.github.com/) e siga as instruções. + +1. Verifique a versão do seu GitHub CLI. + + ```bash + gh --version + ``` + + `2.65.0` ou superior é recomendado. Se o seu for inferior a isso, visite a [página de instalação do GitHub CLI](https://cli.github.com/) e siga as instruções. + +1. Verifique se você fez login no GitHub ou não. + + ```bash + gh auth status + ``` + + Se você ainda não fez login, execute `gh auth login` e faça login. + +### Instalar Docker Desktop + +1. Verifique se você já instalou o Docker Desktop ou não. + + ```bash + # Bash/Zsh + which docker + ``` + + ```bash + # PowerShell + Get-Command docker + ``` + + Se você não vir o caminho do comando `docker`, significa que você ainda não instalou o Docker Desktop. Visite a [página de instalação do Docker Desktop](https://docs.docker.com/get-started/introduction/get-docker-desktop/) e siga as instruções. + +1. Verifique a versão do seu Docker CLI. + + ```bash + docker --version + ``` + + `28.0.4` ou superior é recomendado. Se o seu for inferior a isso, visite a [página de instalação do Docker Desktop](https://docs.docker.com/get-started/introduction/get-docker-desktop/) e siga as instruções. + +### Instalar Visual Studio Code + +1. Verifique se você já instalou o VS Code ou não. + + ```bash + # Bash/Zsh + which code + ``` + + ```bash + # PowerShell + Get-Command code + ``` + + Se você não vir o caminho do comando `code`, significa que você ainda não instalou o VS Code. Visite a [página de instalação do Visual Studio Code](https://code.visualstudio.com/) e siga as instruções. + +1. Verifique a versão do seu VS Code. + + ```bash + code --version + ``` + + `1.99.0` ou superior é recomendado. Se o seu for inferior a isso, visite a [página de instalação do Visual Studio Code](https://code.visualstudio.com/) e siga as instruções. + + > **NOTA**: Você pode não conseguir executar o comando `code`. Neste caso, siga [este documento](https://code.visualstudio.com/docs/setup/mac#_launching-from-the-command-line) para configuração. + +### Iniciar Visual Studio Code + +1. Crie um diretório de trabalho. +1. Execute o comando para fazer fork deste repo e cloná-lo em sua máquina local. + + ```bash + gh repo fork microsoft/github-copilot-vibe-coding-workshop --clone + ``` + +1. Navegue para o diretório clonado. + + ```bash + cd github-copilot-vibe-coding-workshop + ``` + +1. Execute o VS Code a partir do terminal. + + ```bash + code . + ``` + +1. Abra um novo terminal dentro do VS Code e execute o seguinte comando para verificar o status do seu repositório. + + ```bash + git remote -v + ``` + + Você deve conseguir ver o seguinte. Se você vir `microsoft` em `origin`, você deve cloná-lo novamente do seu repositório com fork. + + ```bash + origin https://github.com//github-copilot-vibe-coding-workshop.git (fetch) + origin https://github.com//github-copilot-vibe-coding-workshop.git (push) + upstream https://github.com/microsoft/github-copilot-vibe-coding-workshop.git (fetch) + upstream https://github.com/microsoft/github-copilot-vibe-coding-workshop.git (push) + ``` + +1. Verifique se ambas as extensões foram instaladas ou não – [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) e [GitHub Copilot Chat](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot-chat). + + ```bash + # Bash/Zsh + code --list-extensions | grep github.copilot + ``` + + ```powershell + # PowerShell + code --list-extensions | Select-String "github.copilot" + ``` + + Se você não vir nada, significa que você ainda não instalou essas extensões. Execute o seguinte comando para instalar as extensões. + + ```bash + code --install-extension "github.copilot" --force && code --install-extension "github.copilot-chat" --force + ``` + +### Configurar Servidores MCP + +1. Defina a variável de ambiente `$REPOSITORY_ROOT`. + + ```bash + # bash/zsh + REPOSITORY_ROOT=$(git rev-parse --show-toplevel) + ``` + + ```powershell + # PowerShell + $REPOSITORY_ROOT = git rev-parse --show-toplevel + ``` + +1. Copie as configurações do servidor MCP. + + ```bash + # bash/zsh + cp -r $REPOSITORY_ROOT/docs/.vscode/. \ + $REPOSITORY_ROOT/.vscode/ + ``` + + ```powershell + # PowerShell + Copy-Item -Path $REPOSITORY_ROOT/docs/.vscode/* ` + -Destination $REPOSITORY_ROOT/.vscode/ -Recurse -Force + ``` + +1. Abra a Paleta de Comandos digitando F1 ou `Ctrl`+`Shift`+`P` no Windows ou `Cmd`+`Shift`+`P` no Mac OS, e procure `MCP: List Servers`. +1. Escolha `context7` e clique em `Start Server`. + +## Verificar o Modo Agente do GitHub Copilot + +1. Clique no ícone do GitHub Copilot no topo do GitHub Codespace ou VS Code e abra a janela do GitHub Copilot. + + ![Abrir GitHub Copilot Chat](./images/setup-02.png) + +1. Se você for solicitado a fazer login ou se inscrever, faça-o. É gratuito. +1. Certifique-se de que você está usando o Modo Agente do GitHub Copilot. + + ![Modo Agente do GitHub Copilot](./images/setup-03.png) + +1. Selecione o modelo para `GPT-4.1` ou `Claude Sonnet 4`. + +## Preparar Instruções Customizadas + +1. Defina a variável de ambiente `$REPOSITORY_ROOT`. + + ```bash + # bash/zsh + REPOSITORY_ROOT=$(git rev-parse --show-toplevel) + ``` + + ```powershell + # PowerShell + $REPOSITORY_ROOT = git rev-parse --show-toplevel + ``` + +1. Copie as instruções customizadas. + + ```bash + # bash/zsh + cp -r $REPOSITORY_ROOT/docs/custom-instructions/setup/. \ + $REPOSITORY_ROOT/.github/ + ``` + + ```powershell + # PowerShell + Copy-Item -Path $REPOSITORY_ROOT/docs/custom-instructions/setup/* ` + -Destination $REPOSITORY_ROOT/.github/ -Recurse -Force + ``` + +## Analisar Documento de Requisitos do Produto (PRD) e Projetar API + +1. Certifique-se de que você está usando o Modo Agente do GitHub Copilot com o modelo `Claude Sonnet 4` ou `GPT-4.1`. +1. Adicione [`product-requirements.md`](../product-requirements.md) ao GitHub Copilot. +1. Digite o prompt como o seguinte para o Agente GitHub Copilot gerar um documento OpenAPI para você. Este documento OpenAPI será a base de toda a sua aplicação. + + ```text + Aqui está o PRD para você. Leia cuidadosamente todo o PRD e faça o seguinte para mim. + + - Identifique todos os passos primeiro, que você vai fazer. + - Gere um documento OpenAPI em formato YAML. + - O documento OpenAPI deve capturar todos os endpoints da API, parâmetros e payloads de requisição/resposta. + - Assuma que o servidor da API é `http://localhost:8080` e a URL base é `/api`. + - Salve-o no arquivo `openapi.yaml` na raiz do repositório. + ``` + +1. Verifique se o `openapi.yaml` foi gerado na raiz do repositório. +1. Clique no botão `[keep]` do GitHub Copilot para aceitar o arquivo `openapi.yaml`. + +--- + +OK. Você completou a etapa "Ambiente de Desenvolvimento". Vamos seguir para [ETAPA 01: Desenvolvimento de Backend Python](./01-python.md). \ No newline at end of file diff --git a/localisation/pt-br/docs/01-python.md b/localisation/pt-br/docs/01-python.md new file mode 100644 index 0000000..bc178c8 --- /dev/null +++ b/localisation/pt-br/docs/01-python.md @@ -0,0 +1,119 @@ +# 01: Desenvolvimento de Backend Python + +## Cenário + +A Contoso é uma empresa que vende produtos para várias atividades ao ar livre. O departamento de marketing da Contoso gostaria de lançar um site de micro mídia social para promover seus produtos para clientes existentes e potenciais. + +Como desenvolvedor Python, você vai construir uma aplicação backend Python usando FastAPI. Por enquanto, você está usando o recurso em memória do SQLite. + +## Pré-requisitos + +Consulte a documentação [README](../README.md) para preparação. + +## Primeiros Passos + +- [Verificar o Modo Agente do GitHub Copilot](#verificar-o-modo-agente-do-github-copilot) +- [Preparar Instruções Customizadas](#preparar-instruções-customizadas) +- [Preparar Ambiente Virtual](#preparar-ambiente-virtual) +- [Construir Aplicação Backend FastAPI](#construir-aplicação-backend-fastapi) + +### Verificar o Modo Agente do GitHub Copilot + +1. Clique no ícone do GitHub Copilot no topo do GitHub Codespace ou VS Code e abra a janela do GitHub Copilot. + + ![Abrir GitHub Copilot Chat](./images/setup-02.png) + +1. Se você for solicitado a fazer login ou se inscrever, faça-o. É gratuito. +1. Certifique-se de que você está usando o Modo Agente do GitHub Copilot. + + ![Modo Agente do GitHub Copilot](./images/setup-03.png) + +1. Selecione o modelo para `GPT-4.1` ou `Claude Sonnet 4`. +1. Certifique-se de que você configurou os [Servidores MCP](./00-setup.md#configurar-servidores-mcp). + +### Preparar Instruções Customizadas + +1. Defina a variável de ambiente `$REPOSITORY_ROOT`. + + ```bash + # bash/zsh + REPOSITORY_ROOT=$(git rev-parse --show-toplevel) + ``` + + ```powershell + # PowerShell + $REPOSITORY_ROOT = git rev-parse --show-toplevel + ``` + +1. Copie as instruções customizadas. + + ```bash + # bash/zsh + cp -r $REPOSITORY_ROOT/docs/custom-instructions/python/. \ + $REPOSITORY_ROOT/.github/ + ``` + + ```powershell + # PowerShell + Copy-Item -Path $REPOSITORY_ROOT/docs/custom-instructions/python/* ` + -Destination $REPOSITORY_ROOT/.github/ -Recurse -Force + ``` + +### Preparar Ambiente Virtual + +1. Certifique-se de que você está usando o Modo Agente do GitHub Copilot com o modelo `Claude Sonnet 4` ou `GPT-4.1`. +1. Certifique-se de que o servidor MCP `context7` está funcionando. +1. Use um prompt como o abaixo para preparar o ambiente virtual para desenvolvimento de aplicação Python. + + ```text + Gostaria de escrever uma aplicação Python. Mas antes disso, preciso configurar um ambiente virtual. Siga as instruções abaixo. + + - Use context7. + - Seu diretório de trabalho é `python`. + - Identifique todos os passos primeiro, que você vai fazer. + - Use `.venv` para o ambiente virtual. + - Use `uv` como gerenciador de pacotes Python. + ``` + +### Construir Aplicação Backend FastAPI + +1. Certifique-se de que você está usando o Modo Agente do GitHub Copilot com o modelo `Claude Sonnet 4` ou `GPT-4.1`. +1. Certifique-se de que o servidor MCP `context7` está funcionando. +1. Adicione [`product-requirements.md`](../product-requirements.md) e [`openapi.yaml`](../openapi.yaml) ao GitHub Copilot. +1. Use um prompt como o abaixo para construir uma aplicação backend FastAPI. + + ```text + Gostaria de construir uma aplicação FastAPI como API backend. Leia cuidadosamente todo o PRD e `openapi.yaml`. Então, siga as instruções abaixo. + + - Use context7. + - Seu diretório de trabalho é `python`. + - Identifique todos os passos primeiro, que você vai fazer. + - Use FastAPI como framework da aplicação API. + - Use SQLite como banco de dados. + - Use `sns_api.db` como nome do banco de dados SQLite. + - O banco de dados deve sempre ser inicializado sempre que iniciar a aplicação. + - Use `openapi.yaml` que descreve todos os endpoints e esquema de dados. + - Use o número da porta `8000`. + - Certifique-se de permitir CORS de qualquer lugar. + - O ponto de entrada é `main.py`. + - A aplicação API deve renderizar a página Swagger UI através de um endpoint padrão. + - A aplicação API deve renderizar exatamente o mesmo documento OpenAPI através de um endpoint padrão. + - NÃO adicione nada que não esteja definido em `openapi.yaml`. + - NÃO modifique nada definido em `openapi.yaml`. + ``` + +1. Clique no botão ![a imagem do botão "keep"](https://img.shields.io/badge/keep-blue) do GitHub Copilot para aceitar as mudanças. +1. Uma vez que a aplicação seja construída, verifique se está escrita adequadamente ou não. + + ```text + Execute a aplicação FastAPI e verifique se a aplicação está funcionando adequadamente. Também verifique se o endpoint OpenAPI renderiza exatamente o mesmo conteúdo que `openapi.yaml`. + + Se a execução da aplicação falhar, analise os problemas e corrija-os. + ``` + +1. Abra um navegador web e navegue para `http://localhost:8000`. +1. Clique no botão ![a imagem do botão "keep"](https://img.shields.io/badge/keep-blue) do GitHub Copilot para aceitar as mudanças. + +--- + +OK. Você completou a etapa "Python". Vamos seguir para [ETAPA 02: Desenvolvimento de Frontend JavaScript](./02-javascript.md). \ No newline at end of file diff --git a/localisation/pt-br/docs/02-javascript.md b/localisation/pt-br/docs/02-javascript.md new file mode 100644 index 0000000..5e3805d --- /dev/null +++ b/localisation/pt-br/docs/02-javascript.md @@ -0,0 +1,165 @@ +# 02: Desenvolvimento de Frontend JavaScript + +## Cenário + +A Contoso é uma empresa que vende produtos para várias atividades ao ar livre. O departamento de marketing da Contoso gostaria de lançar um site de micro mídia social para promover seus produtos para clientes existentes e potenciais. + +Como desenvolvedor JavaScript, você vai construir uma aplicação frontend JavaScript usando React para se comunicar com a aplicação backend Python API. + +## Pré-requisitos + +Consulte a documentação [README](../README.md) para preparação. + +## Primeiros Passos + +- [Verificar o Modo Agente do GitHub Copilot](#verificar-o-modo-agente-do-github-copilot) +- [Preparar Instruções Customizadas](#preparar-instruções-customizadas) +- [Preparar Projeto da Aplicação](#preparar-projeto-da-aplicação) +- [Preparar Servidor MCP Figma](#preparar-servidor-mcp-figma) +- [Gerar Componentes UI do Figma](#gerar-componentes-ui-do-figma) +- [Executar Aplicação Backend FastAPI](#executar-aplicação-backend-fastapi) +- [Construir Aplicação Frontend React](#construir-aplicação-frontend-react) +- [Verificar Aplicação Frontend React](#verificar-aplicação-frontend-react) + +### Verificar o Modo Agente do GitHub Copilot + +1. Clique no ícone do GitHub Copilot no topo do GitHub Codespace ou VS Code e abra a janela do GitHub Copilot. + + ![Abrir GitHub Copilot Chat](./images/setup-02.png) + +1. Se você for solicitado a fazer login ou se inscrever, faça-o. É gratuito. +1. Certifique-se de que você está usando o Modo Agente do GitHub Copilot. + + ![Modo Agente do GitHub Copilot](./images/setup-03.png) + +1. Selecione o modelo para `GPT-4.1` ou `Claude Sonnet 4`. +1. Certifique-se de que você configurou os [Servidores MCP](./00-setup.md#configurar-servidores-mcp). + +### Preparar Instruções Customizadas + +1. Defina a variável de ambiente `$REPOSITORY_ROOT`. + + ```bash + # bash/zsh + REPOSITORY_ROOT=$(git rev-parse --show-toplevel) + ``` + + ```powershell + # PowerShell + $REPOSITORY_ROOT = git rev-parse --show-toplevel + ``` + +1. Copie as instruções customizadas. + + ```bash + # bash/zsh + cp -r $REPOSITORY_ROOT/docs/custom-instructions/javascript/. \ + $REPOSITORY_ROOT/.github/ + ``` + + ```powershell + # PowerShell + Copy-Item -Path $REPOSITORY_ROOT/docs/custom-instructions/javascript/* ` + -Destination $REPOSITORY_ROOT/.github/ -Recurse -Force + ``` + +### Preparar Projeto da Aplicação + +1. Certifique-se de que você está usando o Modo Agente do GitHub Copilot com o modelo `Claude Sonnet 4` ou `GPT-4.1`. +1. Certifique-se de que o servidor MCP `context7` está funcionando. +1. Use um prompt como o abaixo para criar um projeto de aplicação web React. + + ```text + Gostaria de criar um projeto de aplicação web React. Siga as instruções abaixo. + + - Certifique-se de que é uma aplicação web, não mobile. + - Seu diretório de trabalho é `javascript`. + - Identifique todos os passos primeiro, que você vai fazer. + - Use ViteJS como framework da aplicação frontend. + - Use configurações padrão ao inicializar o projeto. + - Use `SimpleSocialMediaApplication` como nome do projeto durante a inicialização. + - Use o número da porta `3000`. + - Apenas inicialize o projeto. NÃO vá além. + ``` + +1. Clique no botão ![a imagem do botão "keep"](https://img.shields.io/badge/keep-blue) do GitHub Copilot para aceitar as mudanças. + +### Preparar Servidor MCP Figma + +1. Certifique-se de que você configurou os [Servidores MCP](./00-setup.md#configurar-servidores-mcp). +1. Obtenha o token de acesso pessoal (PAT) do [Figma](https://www.figma.com/). +1. Abra a Paleta de Comandos digitando F1 ou `Ctrl`+`Shift`+`P` no Windows ou `Cmd`+`Shift`+`P` no Mac OS, e procure `MCP: List Servers`. +1. Escolha `Framelink Figma MCP` e clique em `Start Server`. +1. Digite o PAT que você obteve do Figma. + +### Gerar Componentes UI do Figma + +1. Certifique-se de que você está usando o Modo Agente do GitHub Copilot com o modelo `Claude Sonnet 4` ou `GPT-4.1`. +1. Certifique-se de que você está executando o servidor MCP Figma. +1. Copie o [template de design Figma](https://www.figma.com/community/file/1495954632647006209) para sua conta. + + ![Página do template de design Figma](./images/javascript-01.png) + +1. Clique com o botão direito em cada seção - `Home`, `Search`, `Post Details`, `Post Modal` e `Name Input Modal` 👉 Selecione `Copy/Paste as` 👉 Selecione `Copy link to selection` para obter o link para cada seção. Anote todos os cinco links. + +### Executar Aplicação Backend FastAPI + +1. Certifique-se de que a aplicação backend FastAPI está funcionando. + + ```text + Execute a API backend FastAPI, que está localizada no diretório `python`. + ``` + + > **NOTA**: Você pode usar a aplicação de exemplo [`complete/python`](../complete/python/) em vez disso. + +1. Se você usar GitHub Codespaces, certifique-se de que o número da porta `8000` está definido como `public` em vez de `private`. Caso contrário, você receberá o erro `401` ao acessar da aplicação frontend. + +### Construir Aplicação Frontend React + +1. Certifique-se de que você está usando o Modo Agente do GitHub Copilot com o modelo `Claude Sonnet 4` ou `GPT-4.1`. +1. Certifique-se de que o servidor MCP `context7` está funcionando. +1. Certifique-se de que você tem todos os links das seções Figma dos 5 recuperados da [seção anterior](#gerar-componentes-ui-do-figma). +1. Adicione [`product-requirements.md`](../product-requirements.md) e [`openapi.yaml`](../openapi.yaml) ao GitHub Copilot. +1. Use um prompt como o abaixo para construir a aplicação baseada nos requisitos e documento OpenAPI. + + ```text + Gostaria de construir uma aplicação web React. Siga as instruções abaixo. + + - Seu diretório de trabalho é `javascript`. + - Identifique todos os passos primeiro, que você vai fazer. + - Há uma aplicação API backend rodando em `http://localhost:8000`. + - Use `openapi.yaml` que descreve todos os endpoints e esquema de dados. + - Use o número da porta `3000`. + - Crie todos os componentes UI definidos neste link: {{FIGMA_SECTION_LINK}}. + - NÃO adicione nada não relacionado aos componentes UI. + - NÃO adicione nada não definido em `openapi.yaml`. + - NÃO modifique nada definido em `openapi.yaml`. + - Forneça indicação visual quando a API backend estiver indisponível ou inacessível por qualquer motivo. + ``` + +1. Repita mais quatro vezes para os outros quatro links de design Figma. +1. Clique no botão ![a imagem do botão "keep"](https://img.shields.io/badge/keep-blue) do GitHub Copilot para aceitar as mudanças. + +### Verificar Aplicação Frontend React + +1. Certifique-se de que a aplicação backend FastAPI está funcionando. + + ```text + Execute a API backend FastAPI, que está localizada no diretório `python`. + ``` + +1. Verifique se foi construída adequadamente ou não. + + ```text + Execute a aplicação React e verifique se a aplicação está funcionando adequadamente. + + Se a execução da aplicação falhar, analise os problemas e corrija-os. + ``` + +1. Abra um navegador web e navegue para `http://localhost:3000`. +1. Verifique se ambas as aplicações frontend e backend estão funcionando adequadamente. +1. Clique no botão `[keep]` do GitHub Copilot para aceitar as mudanças. + +--- + +OK. Você completou a etapa "JavaScript". Vamos seguir para [ETAPA 03: Migração Java do Python](./03-java.md). \ No newline at end of file diff --git a/localisation/pt-br/docs/03-java.md b/localisation/pt-br/docs/03-java.md new file mode 100644 index 0000000..bcbca3b --- /dev/null +++ b/localisation/pt-br/docs/03-java.md @@ -0,0 +1,160 @@ +# 03: Migração Java do Python + +## Cenário + +A Contoso é uma empresa que vende produtos para várias atividades ao ar livre. O departamento de marketing da Contoso gostaria de lançar um site de micro mídia social para promover seus produtos para clientes existentes e potenciais. + +Como um desenvolvedor Python deixou a empresa, os stakeholders pediram para migrar a aplicação backend Python API existente para Java, usando Spring Boot. + +Agora, como desenvolvedor Java, você deve migrar a aplicação FastAPI existente para Spring Boot. Você tem muito pouco conhecimento de Python e FastAPI, a propósito. + +## Pré-requisitos + +Consulte a documentação [README](../README.md) para preparação. + +## Primeiros Passos + +- [Verificar o Modo Agente do GitHub Copilot](#verificar-o-modo-agente-do-github-copilot) +- [Preparar Instruções Customizadas](#preparar-instruções-customizadas) +- [Preparar Projeto Spring Boot](#preparar-projeto-spring-boot) +- [Migrar Aplicação API FastAPI](#migrar-aplicação-api-fastapi) +- [Verificar Aplicação Backend Spring Boot](#verificar-aplicação-backend-spring-boot) + +### Verificar o Modo Agente do GitHub Copilot + +1. Clique no ícone do GitHub Copilot no topo do GitHub Codespace ou VS Code e abra a janela do GitHub Copilot. + + ![Abrir GitHub Copilot Chat](./images/setup-02.png) + +1. Se você for solicitado a fazer login ou se inscrever, faça-o. É gratuito. +1. Certifique-se de que você está usando o Modo Agente do GitHub Copilot. + + ![Modo Agente do GitHub Copilot](./images/setup-03.png) + +1. Selecione o modelo para `GPT-4.1` ou `Claude Sonnet 4`. +1. Certifique-se de que você configurou os [Servidores MCP](./00-setup.md#configurar-servidores-mcp). + +### Preparar Instruções Customizadas + +1. Defina a variável de ambiente `$REPOSITORY_ROOT`. + + ```bash + # bash/zsh + REPOSITORY_ROOT=$(git rev-parse --show-toplevel) + ``` + + ```powershell + # PowerShell + $REPOSITORY_ROOT = git rev-parse --show-toplevel + ``` + +1. Copie as instruções customizadas. + + ```bash + # bash/zsh + cp -r $REPOSITORY_ROOT/docs/custom-instructions/java/. \ + $REPOSITORY_ROOT/.github/ + ``` + + ```powershell + # PowerShell + Copy-Item -Path $REPOSITORY_ROOT/docs/custom-instructions/java/* ` + -Destination $REPOSITORY_ROOT/.github/ -Recurse -Force + ``` + +### Preparar Projeto Spring Boot + +1. Certifique-se de que você está usando o Modo Agente do GitHub Copilot com o modelo `Claude Sonnet 4` ou `GPT-4.1`. +1. Certifique-se de que o servidor MCP `context7` está funcionando. +1. Instale o Spring Boot CLI. + + ```bash + sdk install springboot + ``` + +1. Use um prompt como o abaixo para criar um projeto de aplicação Spring Boot. + + ```text + Gostaria de criar um projeto de aplicação Spring Boot. Siga as instruções abaixo. + + - Use context7. + - Seu diretório de trabalho é `java`. + - Identifique todos os passos primeiro, que você vai fazer. + - Use Spring Boot CLI para criar o projeto de aplicação Spring Boot. + - Use Gradle como gerenciador de pacotes Java. + - Use o nome do pacote `com.contoso.socialapp`. + - Use o artifact ID `socialapp`. + - Use o group ID `com.contoso`. + - Use o tipo de pacote `jar`. + - Use a versão OpenJDK `21`. + - Adicione dependências - `Spring Web`, `Spring Boot Actuator` e `Lombok`. + - Use o número da porta `8080`. + - Certifique-se de permitir CORS de qualquer lugar. + - Construa a aplicação Spring Boot e verifique se a aplicação foi construída adequadamente. + - Execute esta aplicação Spring Boot e verifique se a aplicação está funcionando adequadamente. + - Se construir ou executar a aplicação falhar, analise os problemas e corrija-os. + ``` + +1. Clique no botão ![a imagem do botão "keep"](https://img.shields.io/badge/keep-blue) do GitHub Copilot para aceitar as mudanças. + +### Migrar Aplicação API FastAPI + +1. Certifique-se de que você está usando o Modo Agente do GitHub Copilot com o modelo `Claude Sonnet 4` ou `GPT-4.1`. +1. Certifique-se de que o servidor MCP `context7` está funcionando. +1. Adicione [`product-requirements.md`](../product-requirements.md) e [`openapi.yaml`](../openapi.yaml) ao GitHub Copilot. +1. Use um prompt como o abaixo para migrar FastAPI para Spring Boot. + + ```text + Agora, estamos migrando a aplicação API baseada em FastAPI existente para aplicação API Spring Boot. Siga as instruções abaixo para a migração. + + - Use context7. + - A aplicação FastAPI existente está localizada em `python`. + - Seu diretório de trabalho é `java/socialapp`. + - Identifique todos os passos primeiro, que você vai fazer. + - Analise a estrutura da aplicação da aplicação FastAPI existente. + - Migre todos os endpoints. Ambos os endpoints correspondentes devem ser exatamente iguais um ao outro. + - Use SQLite como banco de dados. + - Use `sns_api.db` como nome do banco de dados SQLite. + - O banco de dados deve sempre ser inicializado sempre que iniciar a aplicação. + - Use `openapi.yaml` que descreve todos os endpoints e esquema de dados. + - A aplicação API deve renderizar a página Swagger UI através de um endpoint padrão. + - A aplicação API deve renderizar exatamente o mesmo documento OpenAPI através de um endpoint padrão. + - NÃO adicione nada não definido em `openapi.yaml`. + - NÃO modifique nada definido em `openapi.yaml`. + - Se necessário, adicione mais pacotes para OpenAPI e Swagger UI. + ``` + +1. Clique no botão ![a imagem do botão "keep"](https://img.shields.io/badge/keep-blue) do GitHub Copilot para aceitar as mudanças. +1. Uma vez que a migração esteja completa, use um prompt como o abaixo para verificar o resultado da migração. + + ```text + Gostaria de construir a aplicação Spring Boot. Siga as instruções. + + - Use context7. + - Construa a aplicação Spring Boot e verifique se a aplicação foi construída adequadamente. + - Se construir a aplicação falhar, analise os problemas e corrija-os. + ``` + + > **NOTA**: + > + > - Até que a construção seja bem-sucedida, itere esta etapa. + > - Se a construção continuar falhando, verifique as mensagens de erro e pergunte ao Agente GitHub Copilot para entendê-las. + +1. Clique no botão ![a imagem do botão "keep"](https://img.shields.io/badge/keep-blue) do GitHub Copilot para aceitar as mudanças. + +### Verificar Aplicação Backend Spring Boot + +1. Uma vez que a aplicação seja construída, verifique se está escrita adequadamente ou não. + + ```text + Execute a aplicação Spring Boot e verifique se a aplicação está funcionando adequadamente verificando todos os endpoints. Também verifique se o endpoint OpenAPI renderiza exatamente o mesmo conteúdo que `openapi.yaml`. + + Se a execução da aplicação falhar, analise os problemas e corrija-os. Use context7. + ``` + +1. Abra um navegador web e navegue para `http://localhost:8080`. +1. Clique no botão ![a imagem do botão "keep"](https://img.shields.io/badge/keep-blue) do GitHub Copilot para aceitar as mudanças. + +--- + +OK. Você completou a etapa "Java". Vamos seguir para [ETAPA 04: Migração .NET do JavaScript](./04-dotnet.md). \ No newline at end of file diff --git a/localisation/pt-br/docs/04-dotnet.md b/localisation/pt-br/docs/04-dotnet.md new file mode 100644 index 0000000..765b193 --- /dev/null +++ b/localisation/pt-br/docs/04-dotnet.md @@ -0,0 +1,173 @@ +# 04: Migração .NET do JavaScript + +## Cenário + +A Contoso é uma empresa que vende produtos para várias atividades ao ar livre. O departamento de marketing da Contoso gostaria de lançar um site de micro mídia social para promover seus produtos para clientes existentes e potenciais. + +Eles já têm uma aplicação frontend escrita em JavaScript, mais especificamente em React. No entanto, de repente, eles enviaram novos requisitos para redesenvolver a aplicação frontend usando .NET, especialmente em Blazor. + +Agora, como desenvolvedor .NET, você deve migrar a aplicação React existente para Blazor. Você tem muito pouco conhecimento de JavaScript e React, a propósito. + +## Pré-requisitos + +Consulte a documentação [README](../README.md) para preparação. + +## Primeiros Passos + +- [Verificar o Modo Agente do GitHub Copilot](#verificar-o-modo-agente-do-github-copilot) +- [Preparar Instruções Customizadas](#preparar-instruções-customizadas) +- [Preparar Projeto de Aplicação Web Blazor](#preparar-projeto-de-aplicação-web-blazor) +- [Executar Aplicação Backend Spring Boot](#executar-aplicação-backend-spring-boot) +- [Migrar Aplicação Web React](#migrar-aplicação-web-react) +- [Verificar Aplicação Frontend Blazor](#verificar-aplicação-frontend-blazor) + +### Verificar o Modo Agente do GitHub Copilot + +1. Clique no ícone do GitHub Copilot no topo do GitHub Codespace ou VS Code e abra a janela do GitHub Copilot. + + ![Abrir GitHub Copilot Chat](./images/setup-02.png) + +1. Se você for solicitado a fazer login ou se inscrever, faça-o. É gratuito. +1. Certifique-se de que você está usando o Modo Agente do GitHub Copilot. + + ![Modo Agente do GitHub Copilot](./images/setup-03.png) + +1. Selecione o modelo para `GPT-4.1` ou `Claude Sonnet 4`. +1. Certifique-se de que você configurou os [Servidores MCP](./00-setup.md#configurar-servidores-mcp). + +### Preparar Instruções Customizadas + +1. Defina a variável de ambiente `$REPOSITORY_ROOT`. + + ```bash + # bash/zsh + REPOSITORY_ROOT=$(git rev-parse --show-toplevel) + ``` + + ```powershell + # PowerShell + $REPOSITORY_ROOT = git rev-parse --show-toplevel + ``` + +1. Copie as instruções customizadas. + + ```bash + # bash/zsh + cp -r $REPOSITORY_ROOT/docs/custom-instructions/dotnet/. \ + $REPOSITORY_ROOT/.github/ + ``` + + ```powershell + # PowerShell + Copy-Item -Path $REPOSITORY_ROOT/docs/custom-instructions/dotnet/* ` + -Destination $REPOSITORY_ROOT/.github/ -Recurse -Force + ``` + +### Preparar Projeto de Aplicação Web Blazor + +1. Certifique-se de que você está usando o Modo Agente do GitHub Copilot com o modelo `Claude Sonnet 4` ou `GPT-4.1`. +1. Certifique-se de que o servidor MCP `context7` está funcionando. +1. Use um prompt como o abaixo para criar um projeto de aplicação web Blazor. + + ```text + Gostaria de criar um projeto de aplicação web Blazor. Siga as instruções abaixo. + + - Use context7. + - Seu diretório de trabalho é `dotnet`. + - Identifique todos os passos primeiro, que você vai fazer. + - Mostre-me a lista de projetos .NET relacionados ao Blazor e peça para eu escolher. + - Gere um projeto Blazor. + - Use o nome do projeto `Contoso.BlazorApp`. + - Atualize `launchSettings.json` para mudar o número da porta para `3031` para HTTP, `43031` para HTTPS. + - Crie uma solução, `ContosoWebApp`, e adicione o projeto Blazor nesta solução. + - Construa a aplicação Blazor e verifique se a aplicação foi construída adequadamente. + - Execute esta aplicação Blazor e verifique se a aplicação está funcionando adequadamente. + - Se construir ou executar a aplicação falhar, analise os problemas e corrija-os. + ``` + +1. Clique no botão ![a imagem do botão keep](https://img.shields.io/badge/keep-blue) do GitHub Copilot para aceitar as mudanças. + +### Executar Aplicação Backend Spring Boot + +1. Certifique-se de que a aplicação backend Spring Boot está funcionando. + + ```text + Execute a API backend Spring Boot, que está localizada no diretório `java`. + ``` + + > **NOTA**: Você pode usar a aplicação de exemplo [`complete/java`](../complete/java/) em vez disso. + +1. Se você usar GitHub Codespaces, certifique-se de que o número da porta `8080` está definido como `public` em vez de `private`. Caso contrário, você receberá o erro `401` ao acessar da aplicação frontend. + +### Migrar Aplicação Web React + +1. Certifique-se de que você está usando o Modo Agente do GitHub Copilot com o modelo `Claude Sonnet 4` ou `GPT-4.1`. +1. Certifique-se de que o servidor MCP `context7` está funcionando. +1. Use um prompt como o abaixo para migrar React para Blazor. + + ```text + Agora, estamos migrando a aplicação web baseada em React existente para aplicação web Blazor. Siga as instruções abaixo para a migração. + + - Use context7. + - A aplicação React existente está localizada em `javascript`. + - Seu diretório de trabalho é `dotnet/Contoso.BlazorApp`. + - Identifique todos os passos primeiro, que você vai fazer. + - Há uma aplicação API backend rodando em `http://localhost:8080`. + - Analise a estrutura da aplicação da aplicação React existente. + - Migre todos os componentes React para componentes Blazor. Ambos os componentes correspondentes devem ser o mais próximo possível um do outro. + - Migre todos os elementos CSS necessários do React para Blazor. + - Ao migrar elementos JavaScript do React para Blazor, maximize o uso dos recursos nativos do Blazor o máximo possível. Se você tiver que usar JavaScript, use os recursos JSInterop do Blazor. + - Se necessário, adicione pacotes NuGet que sejam compatíveis com .NET 9. + ``` + +1. Uma vez que a migração esteja completa, use um prompt como o abaixo para verificar o resultado da migração. + + ```text + Gostaria de construir a aplicação Blazor. Siga as instruções. + + - Use context7. + - Construa a aplicação Blazor e verifique se a aplicação foi construída adequadamente. + - Se construir a aplicação falhar, analise os problemas e corrija-os. + ``` + + > **NOTA**: + > + > - Até que a construção seja bem-sucedida, itere esta etapa. + > - Se a construção continuar falhando, verifique as mensagens de erro e pergunte ao Agente GitHub Copilot para entendê-las. + +1. Clique no botão ![a imagem do botão keep](https://img.shields.io/badge/keep-blue) do GitHub Copilot para aceitar as mudanças. +1. Uma vez que a construção seja bem-sucedida, use um prompt como o abaixo para verificar o resultado da migração. + + ```text + Gostaria de executar a aplicação Blazor. Siga as instruções. + + - Use context7. + - Execute esta aplicação Blazor e verifique se a aplicação está funcionando adequadamente. + - Ignore o erro de conexão da aplicação API backend nesta etapa. + - Se executar a aplicação falhar, analise os problemas e corrija-os. + ``` + +### Verificar Aplicação Frontend Blazor + +1. Certifique-se de que a aplicação backend Spring Boot está funcionando. + + ```text + Execute a API backend Spring Boot, que está localizada no diretório `java`. + ``` + +1. Clique no botão ![a imagem do botão keep](https://img.shields.io/badge/keep-blue) do GitHub Copilot para aceitar as mudanças. +1. Verifique se foi construída adequadamente ou não. + + ```text + Execute a aplicação Blazor e verifique se a aplicação está funcionando adequadamente. + + Se a execução da aplicação falhar, analise os problemas e corrija-os. + ``` + +1. Abra um navegador web e navegue para `http://localhost:3031`. +1. Verifique se ambas as aplicações frontend e backend estão funcionando adequadamente. +1. Clique no botão ![a imagem do botão keep](https://img.shields.io/badge/keep-blue) do GitHub Copilot para aceitar as mudanças. + +--- + +OK. Você completou a etapa ".NET". Vamos seguir para [ETAPA 05: Containerização](./05-containerization.md). \ No newline at end of file diff --git a/localisation/pt-br/docs/05-containerization.md b/localisation/pt-br/docs/05-containerization.md new file mode 100644 index 0000000..163639b --- /dev/null +++ b/localisation/pt-br/docs/05-containerization.md @@ -0,0 +1,182 @@ +# 05: Containerização + +## Cenário + +A Contoso é uma empresa que vende produtos para várias atividades ao ar livre. O departamento de marketing da Contoso gostaria de lançar um site de micro mídia social para promover seus produtos para clientes existentes e potenciais. + +Eles agora têm tanto uma aplicação backend baseada em Java quanto uma aplicação frontend baseada em .NET. Eles querem containerizá-las para que possam ser implantadas em qualquer plataforma. + +Agora, como engenheiro DevOps, você deve containerizar ambas as aplicações. + +## Pré-requisitos + +Consulte a documentação [README](../README.md) para preparação. + +## Primeiros Passos + +- [Verificar o Modo Agente do GitHub Copilot](#verificar-o-modo-agente-do-github-copilot) +- [Preparar Instruções Customizadas](#preparar-instruções-customizadas) +- [Containerizar Aplicação Java](#containerizar-aplicação-java) +- [Containerizar Aplicação .NET](#containerizar-aplicação-net) +- [Orquestrar Contêineres](#orquestrar-contêineres) + +### Verificar o Modo Agente do GitHub Copilot + +1. Clique no ícone do GitHub Copilot no topo do GitHub Codespace ou VS Code e abra a janela do GitHub Copilot. + + ![Abrir GitHub Copilot Chat](./images/setup-02.png) + +1. Se você for solicitado a fazer login ou se inscrever, faça-o. É gratuito. +1. Certifique-se de que você está usando o Modo Agente do GitHub Copilot. + + ![Modo Agente do GitHub Copilot](./images/setup-03.png) + +1. Selecione o modelo para `GPT-4.1` ou `Claude Sonnet 4`. +1. Certifique-se de que você configurou os [Servidores MCP](./00-setup.md#configurar-servidores-mcp). + +### Preparar Instruções Customizadas + +1. Defina a variável de ambiente `$REPOSITORY_ROOT`. + + ```bash + # bash/zsh + REPOSITORY_ROOT=$(git rev-parse --show-toplevel) + ``` + + ```powershell + # PowerShell + $REPOSITORY_ROOT = git rev-parse --show-toplevel + ``` + +1. Copie as instruções customizadas. + + ```bash + # bash/zsh + cp -r $REPOSITORY_ROOT/docs/custom-instructions/containerization/. \ + $REPOSITORY_ROOT/.github/ + ``` + + ```powershell + # PowerShell + Copy-Item -Path $REPOSITORY_ROOT/docs/custom-instructions/containerization/* ` + -Destination $REPOSITORY_ROOT/.github/ -Recurse -Force + ``` + +### Containerizar Aplicação Java + +1. Certifique-se de que você está usando o Modo Agente do GitHub Copilot com o modelo `Claude Sonnet 4` ou `GPT-4.1`. +1. Use um prompt como o abaixo para construir uma imagem de contêiner para a aplicação Java. + + ```text + Gostaria de construir uma imagem de contêiner de uma aplicação Java. Siga as instruções abaixo. + + - A aplicação Java está localizada em `java`. + - Seu diretório de trabalho é a raiz do repositório. + - Identifique todos os passos primeiro, que você vai fazer. + - Crie um Dockerfile, `Dockerfile.java`. + - Use Microsoft OpenJDK 21. + - Use abordagem de construção multi-estágio. + - Extraia JRE do JDK. + - Use o número da porta de destino `8080` para a imagem do contêiner. + ``` + +1. Clique no botão ![a imagem do botão keep](https://img.shields.io/badge/keep-blue) do GitHub Copilot para aceitar as mudanças. + +1. Uma vez que `Dockerfile.java` seja criado, construa a imagem do contêiner com o seguinte prompt. + + ```text + Use `Dockerfile.java` e construa uma imagem de contêiner. + + - Use `contoso-backend` como nome da imagem do contêiner. + - Use `latest` como tag da imagem do contêiner. + - Verifique se a imagem do contêiner foi construída adequadamente. + - Se a construção falhar, analise os problemas e corrija-os. + ``` + +1. Clique no botão ![a imagem do botão keep](https://img.shields.io/badge/keep-blue) do GitHub Copilot para aceitar as mudanças. + +1. Uma vez que a construção seja bem-sucedida, execute a imagem do contêiner com o seguinte prompt. + + ```text + Use a imagem do contêiner recém-construída, execute um contêiner e verifique se a aplicação está funcionando adequadamente. + + - Use a porta do host `8080`. + ``` + +### Containerizar Aplicação .NET + +1. Certifique-se de que você está usando o Modo Agente do GitHub Copilot com o modelo `Claude Sonnet 4` ou `GPT-4.1`. +1. Use um prompt como o abaixo para construir uma imagem de contêiner para a aplicação .NET. + + ```text + Gostaria de construir uma imagem de contêiner de uma aplicação .NET. Siga as instruções abaixo. + + - A aplicação .NET está localizada em `dotnet`. + - Seu diretório de trabalho é a raiz do repositório. + - Identifique todos os passos primeiro, que você vai fazer. + - Crie um Dockerfile, `Dockerfile.dotnet`. + - Use .NET 9. + - Use abordagem de construção multi-estágio. + - Use o número da porta de destino `8080` para a imagem do contêiner. + ``` + +1. Clique no botão ![a imagem do botão keep](https://img.shields.io/badge/keep-blue) do GitHub Copilot para aceitar as mudanças. + +1. Uma vez que `Dockerfile.dotnet` seja criado, construa a imagem do contêiner com o seguinte prompt. + + ```text + Use `Dockerfile.dotnet` e construa uma imagem de contêiner. + + - Use `contoso-frontend` como nome da imagem do contêiner. + - Use `latest` como tag da imagem do contêiner. + - Verifique se a imagem do contêiner foi construída adequadamente. + - Se a construção falhar, analise os problemas e corrija-os. + ``` + +1. Clique no botão ![a imagem do botão keep](https://img.shields.io/badge/keep-blue) do GitHub Copilot para aceitar as mudanças. + +1. Uma vez que a construção seja bem-sucedida, execute a imagem do contêiner com o seguinte prompt. + + ```text + Use a imagem do contêiner recém-construída, execute um contêiner e verifique se a aplicação está funcionando adequadamente. + + - Use a porta do host `3030`. + ``` + +1. Certifique-se de que ambas as aplicações frontend e backend NÃO estão se comunicando uma com a outra porque elas ainda não se conhecem. Execute o prompt como abaixo. + + ```text + Independentemente ou não, remova ambos os contêineres atualmente em execução. + ``` + +### Orquestrar Contêineres + +1. Certifique-se de que você está usando o Modo Agente do GitHub Copilot com o modelo `Claude Sonnet 4` ou `GPT-4.1`. +1. Use um prompt como o abaixo para construir um arquivo Docker Compose. + + ```text + Gostaria de criar um arquivo Docker Compose. Siga as instruções abaixo. + + - Seu diretório de trabalho é a raiz do repositório. + - Use `Dockerfile.java` como aplicação backend. + - Use `Dockerfile.dotnet` como aplicação frontend. + - Crie `compose.yaml` como arquivo Docker Compose. + - Use `contoso` como nome da rede. + - Use `contoso-backend` como nome do contêiner da aplicação Java. Sua porta de destino é 8080, e porta do host é 8080. + - Use `contoso-frontend` como nome do contêiner da aplicação .NET. Sua porta de destino é 8080, e porta do host é 3030. + - Monte o volume para o banco de dados que a aplicação Java usa, `java/socialapp/sns_api.db`. + ``` + +1. Clique no botão ![a imagem do botão keep](https://img.shields.io/badge/keep-blue) do GitHub Copilot para aceitar as mudanças. + +1. Uma vez que o arquivo `compose.yaml` seja criado, execute-o e verifique se ambas as aplicações estão funcionando adequadamente. + + ```text + Agora, execute o arquivo Docker compose e verifique se as aplicações estão funcionando adequadamente. + ``` + +1. Abra um navegador web e navegue para `http://localhost:3030`, e verifique se as aplicações estão funcionando adequadamente. + +--- + +Parabéns! 🎉 Você completou todas as sessões do workshop com sucesso! \ No newline at end of file diff --git a/localisation/pt-br/docs/README.md b/localisation/pt-br/docs/README.md new file mode 100644 index 0000000..2811d53 --- /dev/null +++ b/localisation/pt-br/docs/README.md @@ -0,0 +1,12 @@ +# Instruções de Aprendizado Autoguiado + +Aqui estão os materiais de instrução de aprendizado autoguiado. Use-os e construa aplicações! + +| Etapa | Link | +|------------------------------------------|----------------------------------------------------| +| 00: Ambiente de Desenvolvimento | [00-setup.md](./00-setup.md) | +| 01: Desenvolvimento de Backend Python | [01-python.md](./01-python.md) | +| 02: Desenvolvimento de Frontend JavaScript | [02-javascript.md](./02-javascript.md) | +| 03: Migração Java do Python | [03-java.md](./03-java.md) | +| 04: Migração .NET do JavaScript | [04-dotnet.md](./04-dotnet.md) | +| 05: Containerização | [05-containerization.md](./05-containerization.md) | \ No newline at end of file diff --git a/localisation/pt-br/docs/custom-instructions/containerization/copilot-instructions.md b/localisation/pt-br/docs/custom-instructions/containerization/copilot-instructions.md new file mode 100644 index 0000000..e3535c1 --- /dev/null +++ b/localisation/pt-br/docs/custom-instructions/containerization/copilot-instructions.md @@ -0,0 +1,34 @@ +# Regras DevOps + +Você é um engenheiro DevOps sênior e especialista em containerização, Docker, Dockerfile, Docker Compose e Kubernetes. + +## Diretrizes Gerais + +### Princípios Básicos + +- Use inglês para todo código, documentação e comentários. +- Priorize código modular, reutilizável e escalável. +- Siga convenções de nomenclatura: + - camelCase para variáveis, funções e nomes de métodos. + - PascalCase para nomes de classes. + - snake_case para nomes de arquivos e estruturas de diretório. + - UPPER_CASE para variáveis de ambiente. +- Evite valores hard-coded; use variáveis de ambiente ou arquivos de configuração. +- Aplique princípios de Infrastructure-as-Code (IaC) quando possível. +- Sempre considere o princípio de menor privilégio em acesso e permissões. + +### Princípios DevOps + +- Automatize tarefas repetitivas e evite intervenções manuais. +- Escreva pipelines CI/CD modulares e reutilizáveis. +- Use aplicações containerizadas com registries seguros. +- Gerencie segredos usando Azure Key Vault ou outras soluções de gerenciamento de segredos. +- Construa sistemas resilientes aplicando estratégias de deploy blue-green ou canary. + +## Cenários Específicos + +### Docker e Docker Compose + +- Use builds multi-estágio em Dockerfiles para otimizar o tamanho da imagem. +- Garanta que Dockerfiles sejam idempotentes e possam ser construídos múltiplas vezes sem efeitos colaterais. +- Use Docker Compose para ambientes de desenvolvimento e teste locais. \ No newline at end of file diff --git a/localisation/pt-br/docs/custom-instructions/dotnet/copilot-instructions.md b/localisation/pt-br/docs/custom-instructions/dotnet/copilot-instructions.md new file mode 100644 index 0000000..df9afe4 --- /dev/null +++ b/localisation/pt-br/docs/custom-instructions/dotnet/copilot-instructions.md @@ -0,0 +1,81 @@ +# Regras de Desenvolvimento .NET + +Você é um desenvolvedor .NET sênior e especialista em C#, ASP.NET Core, API Mínima, Blazor e .NET Aspire. + +## Estilo e Estrutura de Código + +- Escreva código C# conciso e idiomático com exemplos precisos. +- Siga convenções e melhores práticas do .NET e ASP.NET Core. +- Use padrões de programação orientada a objetos e funcional conforme apropriado. +- Prefira LINQ e expressões lambda para operações de coleção. +- Use nomes descritivos para variáveis e métodos (ex: 'IsUserSignedIn', 'CalculateTotal'). +- Estruture arquivos de acordo com convenções .NET (Controllers, Models, Services, etc.). +- Use async/await para operações assíncronas sempre que possível para melhorar performance e responsividade. + +## Convenções de Nomenclatura + +- Use PascalCase para nomes de classe, nomes de método e membros públicos. +- Use camelCase para variáveis locais e campos privados. +- Use UPPERCASE para constantes. +- Prefixe nomes de interface com "I" (ex: 'IUserService'). + +## Uso de C# e .NET + +- Use recursos do C# 10+ quando apropriado (ex: record types, pattern matching, null-coalescing assignment). +- Aproveite recursos integrados do ASP.NET Core e middleware. +- Use Entity Framework Core efetivamente para operações de banco de dados. + +## Sintaxe e Formatação + +- Siga as Convenções de Codificação C# (https://docs.microsoft.com/en-us/dotnet/csharp/fundamentals/coding-style/coding-conventions) +- Use sintaxe expressiva do C# (ex: operadores null-conditional, interpolação de string) +- Use 'var' para tipagem implícita quando o tipo for óbvio. + +## Tratamento de Erros e Validação + +- Use exceções para casos excepcionais, não para fluxo de controle. +- Implemente logging adequado de erros usando logging integrado do .NET ou logger de terceiros. +- Use Data Annotations ou Fluent Validation para validação de modelo. +- Implemente middleware global de tratamento de exceções. +- Retorne códigos de status HTTP apropriados e respostas de erro consistentes. + +## Design de API + +- Siga princípios de design de API RESTful. +- Use roteamento por atributo em controllers. +- Implemente versionamento para sua API. +- Use filtros de ação para concerns transversais. + +## Otimização de Performance + +- Use programação assíncrona com async/await para operações I/O-bound. +- Implemente estratégias de cache usando IMemoryCache ou cache distribuído. +- Use consultas LINQ eficientes e evite problemas de consulta N+1. +- Implemente paginação para grandes conjuntos de dados. + +## Convenções Principais + +- Use Injeção de Dependência para baixo acoplamento e testabilidade. +- Implemente padrão repository ou use Entity Framework Core diretamente, dependendo da complexidade. +- Use AutoMapper para mapeamento objeto-para-objeto se necessário. +- Implemente tarefas em background usando IHostedService ou BackgroundService. + +## Testes + +- Escreva testes unitários usando xUnit, NUnit ou MSTest. +- Use Moq ou NSubstitute para mock de dependências. +- Implemente testes de integração para endpoints de API. + +## Segurança + +- Use middleware de Autenticação e Autorização. +- Implemente autenticação JWT para autenticação de API stateless. +- Use HTTPS e force SSL. +- Implemente políticas CORS adequadas. + +## Documentação de API + +- Use pacote OpenAPI integrado para documentação de API. +- Forneça comentários XML para controllers e models para melhorar documentação Swagger. + +Siga a documentação oficial da Microsoft e guias do ASP.NET Core para melhores práticas em roteamento, controllers, models e outros componentes de API. \ No newline at end of file diff --git a/localisation/pt-br/docs/custom-instructions/java/copilot-instructions.md b/localisation/pt-br/docs/custom-instructions/java/copilot-instructions.md new file mode 100644 index 0000000..362c20e --- /dev/null +++ b/localisation/pt-br/docs/custom-instructions/java/copilot-instructions.md @@ -0,0 +1,92 @@ +# Regras de Desenvolvimento Java + +Você é um desenvolvedor Java sênior e especialista em programação Java, Spring Boot, Spring Boot CLI, Spring Framework, Maven, Gradle, JUnit e tecnologias Java relacionadas. + +## Estilo e Estrutura de Código + +- Escreva código Java limpo, eficiente e bem documentado com exemplos precisos de Spring Boot. +- Use melhores práticas e convenções do Spring Boot em todo o seu código. +- Implemente padrões de design de API RESTful ao criar serviços web. +- Use nomes descritivos para métodos e variáveis seguindo a convenção camelCase. +- Estruture aplicações Spring Boot: controllers, services, repositories, models, configurations. + +## Especificidades do Spring Boot + +- Use Spring Boot starters para configuração rápida de projeto e gerenciamento de dependências. +- Implemente uso adequado de anotações (ex: @SpringBootApplication, @RestController, @Service). +- Utilize recursos de auto-configuração do Spring Boot efetivamente. +- Implemente tratamento adequado de exceções usando @ControllerAdvice e @ExceptionHandler. + +## Convenções de Nomenclatura + +- Use PascalCase para nomes de classe (ex: UserController, OrderService). +- Use camelCase para nomes de método e variável (ex: findUserById, isOrderValid). +- Use ALL_CAPS para constantes (ex: MAX_RETRY_ATTEMPTS, DEFAULT_PAGE_SIZE). + +## Uso de Java e Spring Boot + +- Use recursos do Java 17 ou posterior quando aplicável (ex: records, sealed classes, pattern matching). +- Aproveite recursos e melhores práticas do Spring Boot 3.x. +- Use Spring Data JPA para operações de banco de dados quando aplicável. +- Implemente validação adequada usando Bean Validation (ex: @Valid, validadores customizados). + +## Configuração e Propriedades + +- Use application.properties ou application.yml para configuração. +- Implemente configurações específicas por ambiente usando Spring Profiles. +- Use @ConfigurationProperties para propriedades de configuração type-safe. + +## Injeção de Dependência e IoC + +- Use injeção por construtor em vez de injeção por campo para melhor testabilidade. +- Aproveite o container IoC do Spring para gerenciar ciclos de vida de beans. + +## Testes + +- Escreva testes unitários usando JUnit 5 e Spring Boot Test. +- Use MockMvc para testar camadas web. +- Implemente testes de integração usando @SpringBootTest. +- Use @DataJpaTest para testes da camada de repositório. + +## Performance e Escalabilidade + +- Implemente estratégias de cache usando abstração Spring Cache. +- Use processamento assíncrono com @Async para operações não-bloqueantes. +- Implemente indexação adequada de banco de dados e otimização de consultas. + +## Segurança + +- Implemente Spring Security para autenticação e autorização. +- Use codificação adequada de senha (ex: BCrypt). +- Implemente configuração CORS quando necessário. + +## Logging e Monitoramento + +- Use SLF4J com Logback para logging. +- Implemente níveis adequados de log (ERROR, WARN, INFO, DEBUG). +- Use Spring Boot Actuator para monitoramento de aplicação e métricas. + +## Documentação de API + +- Use Springdoc OpenAPI (anteriormente Swagger) para documentação de API. + +## Acesso a Dados e ORM + +- Use Spring Data JPA para operações de banco de dados. +- Implemente relacionamentos adequados de entidade e cascading. +- Use migrações de banco de dados com ferramentas como Flyway ou Liquibase. + +## Build e Deploy + +- Use Maven ou Gradle para gerenciamento de dependências e processos de build. +- Gradle é preferido para novos projetos devido à sua flexibilidade e performance. +- Implemente profiles adequados para diferentes ambientes (dev, test, prod). +- Use Docker para containerização se aplicável. + +## Siga melhores práticas para: + +- Design de API RESTful (uso adequado de métodos HTTP, códigos de status, etc.). +- Arquitetura de microsserviços (se aplicável). +- Processamento assíncrono usando @Async do Spring ou programação reativa com Spring WebFlux. + +Adira aos princípios SOLID e mantenha alta coesão e baixo acoplamento no design da sua aplicação Spring Boot. \ No newline at end of file diff --git a/localisation/pt-br/docs/custom-instructions/javascript/copilot-instructions.md b/localisation/pt-br/docs/custom-instructions/javascript/copilot-instructions.md new file mode 100644 index 0000000..27da3b9 --- /dev/null +++ b/localisation/pt-br/docs/custom-instructions/javascript/copilot-instructions.md @@ -0,0 +1,46 @@ +# Regras de Desenvolvimento JavaScript + +Você é um Desenvolvedor Front-End Sênior e Especialista em ReactJS, NextJS, ViteJS, JavaScript, TypeScript, HTML, CSS e frameworks modernos de UI/UX (ex: TailwindCSS, Shadcn, Radix). + +Você é reflexivo, dá respostas matizadas e é brilhante em raciocínio. Você fornece cuidadosamente respostas precisas, factuais e reflexivas, e é um gênio em raciocínio. + +## Princípios Fundamentais + +- Siga os requisitos do usuário cuidadosamente e à risca. +- Primeiro pense passo a passo - descreva seu plano para o que construir em pseudocódigo, escrito em grande detalhe. +- Confirme, então escreva código! +- Sempre escreva código correto, de melhores práticas, princípio DRY (Don't Repeat Yourself), livre de bugs, totalmente funcional e funcionando, também deve estar alinhado às regras listadas abaixo nas Diretrizes de Implementação de Código. +- Foque em código fácil e legível, em vez de ser performante. +- Implemente totalmente toda a funcionalidade solicitada. +- Não deixe TODOs, placeholders ou peças faltando. +- Garanta que o código está completo! Verifique minuciosamente se está finalizado. +- Inclua todas as importações necessárias e garanta nomenclatura adequada dos componentes chave. +- Seja conciso. Minimize qualquer outra prosa. +- Se você acha que pode não haver uma resposta correta, diga isso. +- Se você não souber a resposta, diga isso, em vez de adivinhar. + +## Ambiente de Codificação + +O usuário faz perguntas sobre as seguintes linguagens de codificação: + +- ReactJS +- NextJS +- ViteJS +- JavaScript +- TypeScript +- TailwindCSS +- HTML +- CSS + +## Diretrizes de Implementação de Código + +Siga essas regras quando escrever código: + +- TypeScript é preferido em vez de JavaScript, a menos que o usuário especificamente solicite JavaScript. +- Escolha NextJS ou ViteJS para o projeto, dependendo dos requisitos. +- Use retornos antecipados sempre que possível para tornar o código mais legível. +- Sempre use classes Tailwind para estilizar elementos HTML; evite usar CSS ou tags. +- Use "class:" em vez do operador ternário em tags de classe sempre que possível. +- Use nomes descritivos para variáveis e funções/const. Além disso, funções de evento devem ser nomeadas com prefixo "handle", como "handleClick" para onClick e "handleKeyDown" para onKeyDown. +- Implemente recursos de acessibilidade em elementos. Por exemplo, uma tag deve ter tabindex="0", aria-label, on:click, e on:keydown, e atributos similares. +- Use consts em vez de functions, por exemplo, "const toggle = () =>". Além disso, defina um tipo se possível. \ No newline at end of file diff --git a/localisation/pt-br/docs/custom-instructions/python/copilot-instructions.md b/localisation/pt-br/docs/custom-instructions/python/copilot-instructions.md new file mode 100644 index 0000000..6530c13 --- /dev/null +++ b/localisation/pt-br/docs/custom-instructions/python/copilot-instructions.md @@ -0,0 +1,70 @@ +# Regras de Desenvolvimento Python + +Você é um desenvolvedor Python sênior e especialista em Python, FastAPI, SQLite e desenvolvimento de API escalável. + +## Princípios Fundamentais + +- Escreva respostas técnicas concisas com exemplos precisos de Python. +- Use programação funcional e declarativa; evite classes quando possível. +- Prefira iteração e modularização em vez de duplicação de código. +- Use nomes de variáveis descritivos com verbos auxiliares (ex: is_active, has_permission). +- Use minúsculas com sublinhados para diretórios e arquivos (ex: routers/user_routes.py). +- Favoreça exportações nomeadas para rotas e funções utilitárias. +- Use o padrão Receive an Object, Return an Object (RORO). + +## Python/FastAPI + +- Use def para funções puras e async def para operações assíncronas. +- Use type hints para todas as assinaturas de função. Prefira modelos Pydantic em vez de dicionários brutos para validação de entrada. +- Estrutura de arquivo: roteador exportado, sub-rotas, utilitários, conteúdo estático, tipos (modelos, esquemas). +- Evite chaves desnecessárias em declarações condicionais. +- Para declarações de linha única em condicionais, omita chaves. +- Use sintaxe concisa de uma linha para declarações condicionais simples (ex: if condition: do_something()). + +## Tratamento de Erros e Validação + +- Priorize tratamento de erros e casos extremos: + - Trate erros e casos extremos no início das funções. + - Use retornos antecipados para condições de erro para evitar declarações if profundamente aninhadas. + - Coloque o caminho feliz por último na função para melhor legibilidade. + - Evite declarações else desnecessárias; use o padrão if-return em vez disso. + - Use cláusulas de guarda para tratar pré-condições e estados inválidos cedo. + - Implemente logging adequado de erros e mensagens de erro amigáveis ao usuário. + - Use tipos de erro customizados ou fábricas de erro para tratamento consistente de erros. + +## Dependências + +- FastAPI +- Pydantic v2 +- Bibliotecas de banco de dados assíncronas como asyncpg ou aiomysql +- SQLAlchemy 2.0 (se usando recursos ORM) + +## Diretrizes Específicas do FastAPI + +- Use componentes funcionais (funções simples) e modelos Pydantic para validação de entrada e esquemas de resposta. +- Use definições de rota declarativas com anotações claras de tipo de retorno. +- Use def para operações síncronas e async def para assíncronas. +- Minimize @app.on_event("startup") e @app.on_event("shutdown"); prefira gerenciadores de contexto lifespan para gerenciar eventos de inicialização e desligamento. +- Use middleware para logging, monitoramento de erros e otimização de performance. +- Otimize para performance usando funções async para tarefas I/O-bound, estratégias de cache e carregamento preguiçoso. +- Use HTTPException para erros esperados e modele-os como respostas HTTP específicas. +- Use middleware para tratar erros inesperados, logging e monitoramento de erros. +- Use BaseModel do Pydantic para validação de entrada/saída consistente e esquemas de resposta. + +## Otimização de Performance + +- Minimize operações I/O bloqueantes; use operações assíncronas para todas as chamadas de banco de dados e requisições de API externa. +- Implemente cache para dados estáticos e frequentemente acessados usando ferramentas como Redis ou stores em memória. +- Otimize serialização e desserialização de dados com Pydantic. +- Use técnicas de carregamento preguiçoso para grandes conjuntos de dados e respostas substanciais de API. + +## Convenções Principais + +1. Confie no sistema de injeção de dependência do FastAPI para gerenciar estado e recursos compartilhados. +2. Priorize métricas de performance da API (tempo de resposta, latência, throughput). +3. Limite operações bloqueantes em rotas: + - Favoreça fluxos assíncronos e não-bloqueantes. + - Use funções async dedicadas para operações de banco de dados e API externa. + - Estruture rotas e dependências claramente para otimizar legibilidade e manutenibilidade. + +Consulte a documentação do FastAPI para Modelos de Dados, Operações de Caminho e Middleware para melhores práticas. \ No newline at end of file diff --git a/localisation/pt-br/docs/custom-instructions/setup/copilot-instructions.md b/localisation/pt-br/docs/custom-instructions/setup/copilot-instructions.md new file mode 100644 index 0000000..b78d659 --- /dev/null +++ b/localisation/pt-br/docs/custom-instructions/setup/copilot-instructions.md @@ -0,0 +1,5 @@ +Você é um especialista como Analista de Negócios. Você é muito capaz de interpretar os requisitos de negócio para detalhes técnicos. + +Quando você está lidando com OpenAPI, sempre está se referindo à versão de especificação 3.0.1. + +Quando você cria um documento OpenAPI, você deve sempre considerar a reutilização do esquema de dados. NÃO duplique estrutura de dados similar. \ No newline at end of file diff --git a/localisation/pt-br/dotnet/README.md b/localisation/pt-br/dotnet/README.md new file mode 100644 index 0000000..d52bffa --- /dev/null +++ b/localisation/pt-br/dotnet/README.md @@ -0,0 +1,5 @@ +# Começando com .NET + +Aqui está o ponto de partida para o desenvolvimento da sua aplicação .NET. + +Se você quiser ver o exemplo completo, confira este diretório, [/complete/dotnet](../complete/dotnet/). \ No newline at end of file diff --git a/localisation/pt-br/java/README.md b/localisation/pt-br/java/README.md new file mode 100644 index 0000000..e9e3948 --- /dev/null +++ b/localisation/pt-br/java/README.md @@ -0,0 +1,5 @@ +# Começando com Java + +Aqui está o ponto de partida para o desenvolvimento da sua aplicação Java. + +Se você quiser ver o exemplo completo, confira este diretório, [/complete/java](../complete/java/). \ No newline at end of file diff --git a/localisation/pt-br/javascript/README.md b/localisation/pt-br/javascript/README.md new file mode 100644 index 0000000..b108c11 --- /dev/null +++ b/localisation/pt-br/javascript/README.md @@ -0,0 +1,5 @@ +# Começando com JavaScript + +Aqui está o ponto de partida para o desenvolvimento da sua aplicação JavaScript. + +Se você quiser ver o exemplo completo, confira este diretório, [/complete/javascript](../complete/javascript/). \ No newline at end of file diff --git a/localisation/pt-br/product-requirements.md b/localisation/pt-br/product-requirements.md new file mode 100644 index 0000000..294a513 --- /dev/null +++ b/localisation/pt-br/product-requirements.md @@ -0,0 +1,148 @@ +# Documento de Requisitos do Produto (PRD) + +## Título do Produto + +Aplicação de Mídia Social Simples + +## Versão do Documento + +1.0.0 + +## Autor + +Product Owner / Tech Lead na Contoso + +## Última Atualização + +2025-05-30 + +--- + +## 1. Visão Geral + +O objetivo deste projeto é construir um Serviço de Rede Social (SNS) básico, mas funcional, que permita aos usuários criar, recuperar, atualizar e excluir postagens; adicionar comentários; e curtir/descurtir postagens. A abordagem API-first garante que pode ser usado como backend para frontends web ou móveis. + +## 2. Contexto + +A Contoso é uma empresa que vende produtos para várias atividades ao ar livre. O departamento de marketing da Contoso gostaria de lançar um site de micro mídia social para promover seus produtos para clientes existentes e potenciais. Como seu primeiro MVP, o departamento de marketing quer construir rapidamente o site. + +## 3. Objetivos e Metas + +* Fornecer operações CRUD para conteúdo gerado pelo usuário (postagens). +* Permitir interação social através de comentários e curtidas. +* Manter simplicidade para casos de uso educacionais e MVP. +* Garantir design de API RESTful e tratamento adequado de erros. + +## 4. Funcionalidades Principais + +### 4.1 Gerenciamento de Postagens + +* **Listar Postagens** + + * **GET** `/api/posts` + * História do Usuário: Como usuário, quero ver todas as postagens recentes para poder navegar pelo que outros estão compartilhando. + +* **Criar Postagem** + + * **POST** `/api/posts` + * Obrigatório: `username`, `content` + * História do Usuário: Como usuário, quero criar uma nova postagem para poder compartilhar algo com outros. + +* **Obter Postagem Específica** + + * **GET** `/api/posts/{postId}` + * História do Usuário: Como usuário, quero ler uma postagem específica em detalhes. + +* **Atualizar Postagem** + + * **PATCH** `/api/posts/{postId}` + * Obrigatório: `username`, `content` + * História do Usuário: Como usuário, quero atualizar minha postagem se cometi um erro ou tenho algo a acrescentar. + +* **Deletar Postagem** + + * **DELETE** `/api/posts/{postId}` + * História do Usuário: Como usuário, quero deletar minha postagem se não quero mais que seja compartilhada. + +### 4.2 Gerenciamento de Comentários + +* **Listar Comentários de uma Postagem** + + * **GET** `/api/posts/{postId}/comments` + * História do Usuário: Como usuário, quero ler todos os comentários de uma postagem. + +* **Criar Comentário** + + * **POST** `/api/posts/{postId}/comments` + * Obrigatório: `username`, `content` + * História do Usuário: Como usuário, quero comentar em uma postagem para compartilhar meus pensamentos. + +* **Obter Comentário Específico** + + * **GET** `/api/posts/{postId}/comments/{commentId}` + * História do Usuário: Como usuário, quero ver um comentário específico em detalhes. + +* **Atualizar Comentário** + + * **PATCH** `/api/posts/{postId}/comments/{commentId}` + * Obrigatório: `username`, `content` + * História do Usuário: Como usuário, quero corrigir ou revisar meu comentário. + +* **Deletar Comentário** + + * **DELETE** `/api/posts/{postId}/comments/{commentId}` + * História do Usuário: Como usuário, quero deletar meu comentário se necessário. + +### 4.3 Sistema de Curtidas + +* **Curtir uma Postagem** + + * **POST** `/api/posts/{postId}/likes` + * Obrigatório: `username` + * História do Usuário: Como usuário, quero curtir uma postagem para mostrar apreço. + +* **Descurtir uma Postagem** + + * **DELETE** `/api/posts/{postId}/likes` + * História do Usuário: Como usuário, quero remover minha curtida se mudar de ideia. + +## 5. Funções de Usuário e Permissões + +* **Usuários Anônimos** + * Podem ler postagens e comentários. + +* **Usuários Autenticados (via campo username)** + * Podem criar, atualizar, deletar suas próprias postagens e comentários. + * Podem curtir/descurtir postagens. + +## 6. Contratos de API + +* Definir o documento OpenAPI com especificação v3.0.1 no mínimo. +* Usa códigos de status HTTP padrão. + * `200 OK`, `201 Created`, `204 No Content`, `400 Bad Request`, `404 Not Found`, `500 Internal Server Error` +* Content-Type: `application/json` + +## 7. Requisitos Não-Funcionais + +* **Documentação**: A API deve ser totalmente documentada usando Swagger UI. +* **Segurança**: Validação de entrada e validação básica de requisições, mesmo que autenticação completa não seja implementada. + +## 8. Suposições e Dependências + +* Usar banco de dados em memória para este produto. +* Nenhum suporte para upload de arquivos ou mídia está incluído. +* Nenhum registro de usuário ou fluxos de login/autenticação. +* Nenhum código de teste é necessário. + +## 9. Métricas de Sucesso + +* Todos os endpoints da API são acessíveis e respondem conforme documentado. +* Capaz de postar, comentar, curtir e deletar recursos de ponta a ponta. +* Documentação Swagger clara gerada a partir do OpenAPI. + +## 10. Fora do Escopo + +* Autenticação de usuário (OAuth, JWT, etc.) +* Atualizações em tempo real ou notificações +* Ferramentas de moderação ou relatórios +* Uploads multimídia (imagens, vídeo) \ No newline at end of file diff --git a/localisation/pt-br/python/README.md b/localisation/pt-br/python/README.md new file mode 100644 index 0000000..3aabf3c --- /dev/null +++ b/localisation/pt-br/python/README.md @@ -0,0 +1,5 @@ +# Começando com Python + +Aqui está o ponto de partida para o desenvolvimento da sua aplicação Python. + +Se você quiser ver o exemplo completo, confira este diretório, [/complete/python](../complete/python/). \ No newline at end of file