{"id":31687872,"url":"https://github.com/nelcifranmagalhaes/question_api","last_synced_at":"2026-05-05T17:33:38.769Z","repository":{"id":315964801,"uuid":"1056800196","full_name":"NelcifranMagalhaes/Question_API","owner":"NelcifranMagalhaes","description":"Uma solução completa para empresas monitorarem o bem-estar de seus colaboradores através de questionários personalizáveis e métricas em tempo real.","archived":false,"fork":false,"pushed_at":"2025-10-01T02:12:22.000Z","size":20,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-08T10:37:38.512Z","etag":null,"topics":["api-rest","fastapi","mongodb","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NelcifranMagalhaes.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-14T20:33:22.000Z","updated_at":"2025-10-02T20:02:17.000Z","dependencies_parsed_at":"2025-09-21T23:19:44.052Z","dependency_job_id":"72bdb132-a8d0-49e8-affb-f36c5a78a181","html_url":"https://github.com/NelcifranMagalhaes/Question_API","commit_stats":null,"previous_names":["nelcifranmagalhaes/question_api"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/NelcifranMagalhaes/Question_API","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NelcifranMagalhaes%2FQuestion_API","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NelcifranMagalhaes%2FQuestion_API/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NelcifranMagalhaes%2FQuestion_API/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NelcifranMagalhaes%2FQuestion_API/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NelcifranMagalhaes","download_url":"https://codeload.github.com/NelcifranMagalhaes/Question_API/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NelcifranMagalhaes%2FQuestion_API/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32660377,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-05T11:29:49.557Z","status":"ssl_error","status_checked_at":"2026-05-05T11:29:48.587Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-rest","fastapi","mongodb","python"],"created_at":"2025-10-08T10:31:42.834Z","updated_at":"2026-05-05T17:33:38.755Z","avatar_url":"https://github.com/NelcifranMagalhaes.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🎯 HappyTracker API\n\n\u003e **API REST para coleta e análise de dados de bem-estar e satisfação no trabalho**\n\nUma solução completa para empresas monitorarem o bem-estar de seus colaboradores através de questionários personalizáveis e métricas em tempo real.\n\n[![FastAPI](https://img.shields.io/badge/FastAPI-005571?style=for-the-badge\u0026logo=fastapi)](https://fastapi.tiangolo.com/)\n[![MongoDB](https://img.shields.io/badge/MongoDB-%234ea94b.svg?style=for-the-badge\u0026logo=mongodb\u0026logoColor=white)](https://www.mongodb.com/)\n[![Docker](https://img.shields.io/badge/docker-%230db7ed.svg?style=for-the-badge\u0026logo=docker\u0026logoColor=white)](https://www.docker.com/)\n[![Python](https://img.shields.io/badge/python-3670A0?style=for-the-badge\u0026logo=python\u0026logoColor=ffdd54)](https://www.python.org/)\n\n## 🚀 Características Principais\n\n- ✅ **API REST** completa com FastAPI\n- ✅ **Sistema de questionários** flexível e customizável\n- ✅ **Métricas avançadas** de engajamento e respostas\n- ✅ **Banco NoSQL** MongoDB para alta performance\n- ✅ **Containerização** com Docker\n- ✅ **Documentação automática** Swagger/OpenAPI\n- ✅ **Validação robusta** com Pydantic\n- ✅ **Sistema de logs** para auditoria\n- ✅ **Seeding automático** de dados iniciais\n\n## 📋 Índice\n\n- [🏗️ Arquitetura](#️-arquitetura)\n- [🛠️ Tecnologias](#️-tecnologias)\n- [⚡ Quick Start](#-quick-start)\n- [📖 Documentação da API](#-documentação-da-api)\n- [🔧 Configuração](#-configuração)\n- [🎯 Endpoints](#-endpoints)\n- [📊 Métricas e Analytics](#-métricas-e-analytics)\n- [🧪 Desenvolvimento](#-desenvolvimento)\n- [📚 Exemplos de Uso](#-exemplos-de-uso)\n- [🤝 Contribuição](#-contribuição)\n\n## 🏗️ Arquitetura\n\nO projeto segue os princípios de **Clean Architecture** e **Domain-Driven Design**:\n\n```\n📱 Cliente/Frontend\n    ↓ HTTP REST\n🚀 FastAPI (Routers)\n    ↓ Validação\n🔍 Pydantic Schemas\n    ↓ Lógica de Negócio  \n🧠 Beanie Models (ODM)\n    ↓ Persistência\n🗄️ MongoDB Collections\n```\n\nPara ver o diagrama completo da arquitetura, consulte: [ARCHITECTURE.md](./ARCHITECTURE.md)\n\n## 🛠️ Tecnologias\n\n| Categoria | Tecnologia | Versão | Descrição |\n|-----------|------------|--------|-----------|\n| **Framework** | FastAPI | Latest | Framework web moderno e rápido |\n| **Linguagem** | Python | 3.11 | Linguagem de programação |\n| **Banco de Dados** | MongoDB | 8.0 | Banco NoSQL orientado a documentos |\n| **ODM** | Beanie | Latest | Object Document Mapper para MongoDB |\n| **Validação** | Pydantic | Latest | Validação de dados e serialização |\n| **Containerização** | Docker | Latest | Containerização da aplicação |\n| **Servidor ASGI** | Uvicorn | Latest | Servidor ASGI para FastAPI |\n\n## ⚡ Quick Start\n\n### Pré-requisitos\n\n- 🐳 **Docker** e **Docker Compose**\n- 🔧 **Git**\n\n### 1️⃣ Clone o Repositório\n\n```bash\ngit clone https://github.com/NelcifranMagalhaes/Question_API.git\ncd Question_API\n```\n\n### 2️⃣ Configure as Variáveis de Ambiente\n\n```bash\n# O arquivo .env já está configurado com valores padrão\ncat .env\n```\n\n### 3️⃣ Execute a Aplicação\n\n```bash\n# Subir todos os serviços\ndocker compose up -d\n\n# Ver logs em tempo real\ndocker compose logs -f app\n```\n\n### 4️⃣ Acesse a API\n\n- 🌐 **API Base**: http://localhost:8000\n- 📖 **Documentação Swagger**: http://localhost:8000/docs\n- 📚 **ReDoc**: http://localhost:8000/redoc\n\n### 5️⃣ Teste a API\n\n```bash\n# Listar todas as questões\ncurl http://localhost:8000/questions\n\n# Ver métricas\ncurl http://localhost:8000/answers/metrics/all\n```\n\n## 📖 Documentação da API\n\nA API possui documentação automática gerada pelo FastAPI:\n\n- **Swagger UI**: http://localhost:8000/docs\n- **ReDoc**: http://localhost:8000/redoc\n- **OpenAPI JSON**: http://localhost:8000/openapi.json\n\n## 🔧 Configuração\n\n### Variáveis de Ambiente\n\n| Variável | Descrição | Valor Padrão |\n|----------|-----------|--------------|\n| `MONGO_URI` | URI de conexão MongoDB | `mongodb://mongo:27017` |\n| `MONGO_DB` | Nome do banco de dados | `happy_tracker_fast_api_db` |\n\n### Estrutura de Arquivos\n\n```\n📁 Question_API/\n├── 📁 app/                    # Código da aplicação\n│   ├── 📁 models/            # Modelos Beanie (ODM)\n│   ├── 📁 routes/            # Endpoints/Routers\n│   ├── 📁 schemas/           # Schemas Pydantic\n│   ├── 📄 main.py            # Aplicação principal\n│   ├── 📄 database.py        # Configuração do banco\n│   ├── 📄 config.py          # Configurações\n│   └── 📄 seed.py            # Dados iniciais\n├── 📄 docker-compose.yml     # Orquestração Docker\n├── 📄 Dockerfile             # Imagem da aplicação\n├── 📄 requirements.txt       # Dependências Python\n├── 📄 .env                   # Variáveis de ambiente\n├── 📄 ARCHITECTURE.md        # Diagrama de arquitetura\n└── 📄 README.md              # Este arquivo\n```\n\n## 🎯 Endpoints\n\n### 👤 Usuários (`/users`)\n\n| Método | Endpoint | Descrição |\n|--------|----------|-----------|\n| `POST` | `/users` | Criar novo usuário |\n| `GET` | `/users` | Listar todos os usuários |\n| `GET` | `/users/{user_id}` | Buscar usuário específico |\n\n### ❓ Questões (`/questions`)\n\n| Método | Endpoint | Descrição |\n|--------|----------|-----------|\n| `POST` | `/questions` | Criar nova questão |\n| `GET` | `/questions` | Listar questões ordenadas |\n| `GET` | `/questions/{question_id}` | Buscar questão com opções |\n\n### 📝 Opções (`/options`)\n\n| Método | Endpoint | Descrição |\n|--------|----------|-----------|\n| `POST` | `/options` | Criar nova opção |\n| `GET` | `/options/by-question/{question_id}` | Listar opções por questão |\n\n### 💬 Respostas (`/answers`)\n\n| Método | Endpoint | Descrição |\n|--------|----------|-----------|\n| `POST` | `/answers` | Criar nova resposta |\n| `GET` | `/answers` | Listar todas as respostas |\n| `GET` | `/answers/by-user/{user_id}` | Respostas por usuário |\n\n### 📊 Métricas (`/answers/metrics`)\n\n| Método | Endpoint | Descrição |\n|--------|----------|-----------|\n| `GET` | `/answers/metrics/all` | Métricas de todas as questões |\n\n## 📊 Métricas e Analytics\n\n### Funcionalidades de Análise\n\n- 📈 **Contagem de respostas** por opção\n- 🎯 **Filtros inteligentes** (apenas dados com engajamento)\n- 📊 **Métricas agregadas** por questão\n- 🔍 **Análise de participação** dos usuários\n\n### Exemplo de Resposta de Métricas\n\n```json\n{\n  \"question_id\": \"64f8a123b456c789d012e345\",\n  \"question_label\": \"Como você se sente hoje?\",\n  \"total_responses\": 25,\n  \"options\": [\n    {\n      \"option_id\": \"64f8a123b456c789d012e346\",\n      \"option_label\": \"Motivado\",\n      \"count\": 15\n    },\n    {\n      \"option_id\": \"64f8a123b456c789d012e347\", \n      \"option_label\": \"Cansado\",\n      \"count\": 10\n    }\n  ]\n}\n```\n\n## 🧪 Desenvolvimento\n\n### Executar em Modo de Desenvolvimento\n\n```bash\n# Instalar dependências localmente\npip install -r requirements.txt\n\n# Executar com reload automático\nuvicorn app.main:app --reload --host 0.0.0.0 --port 8000\n```\n\n### Comandos Úteis\n\n```bash\n# Ver logs da aplicação\ndocker compose logs -f app\n\n# Acessar container da aplicação\ndocker compose exec app bash\n\n# Acessar MongoDB\ndocker compose exec mongo mongosh\n\n# Parar todos os serviços\ndocker compose down\n\n# Rebuild da aplicação\ndocker compose build --no-cache app\n```\n\n### Estrutura do Banco de Dados\n\n```javascript\n// Collection: users\n{\n  \"_id\": ObjectId,\n  \"name\": \"string\",\n  \"email\": \"string\"\n}\n\n// Collection: questions  \n{\n  \"_id\": ObjectId,\n  \"label\": \"string\",\n  \"ordering\": number\n}\n\n// Collection: options\n{\n  \"_id\": ObjectId,\n  \"label\": \"string\", \n  \"question_id\": ObjectId\n}\n\n// Collection: answers\n{\n  \"_id\": ObjectId,\n  \"user_id\": ObjectId,\n  \"question_id\": ObjectId,\n  \"option_id\": ObjectId\n}\n```\n\n## 📚 Exemplos de Uso\n\n### Criar um Usuário\n\n```bash\ncurl -X POST \"http://localhost:8000/users\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"João Silva\",\n    \"email\": \"joao@empresa.com\"\n  }'\n```\n\n### Criar uma Questão\n\n```bash\ncurl -X POST \"http://localhost:8000/questions\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"label\": \"Como você avalia o clima organizacional?\",\n    \"ordering\": 1\n  }'\n```\n\n### Registrar uma Resposta\n\n```bash\ncurl -X POST \"http://localhost:8000/answers\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"user_id\": \"64f8a123b456c789d012e345\",\n    \"question_id\": \"64f8a123b456c789d012e346\", \n    \"option_id\": \"64f8a123b456c789d012e347\"\n  }'\n```\n\n### Obter Métricas\n\n```bash\ncurl \"http://localhost:8000/answers/metrics/all\"\n```\n\n## 🎯 Casos de Uso\n\n### Para Empresas\n- 📊 **Pesquisas de clima organizacional**\n- 💼 **Avaliação de satisfação dos funcionários**  \n- 🎯 **Monitoramento de bem-estar**\n- 📈 **Análise de engajamento da equipe**\n\n### Para RH\n- 📋 **Questionários personalizáveis**\n- 📊 **Dashboards de métricas**\n- 🔍 **Análise de tendências**\n- 📈 **Relatórios executivos**\n\n## 🚨 Troubleshooting\n\n### Problemas Comuns\n\n#### Container não sobe\n```bash\n# Verificar se as portas estão livres\nnetstat -tulpn | grep :8000\nnetstat -tulpn | grep :27017\n\n# Limpar containers antigos\ndocker system prune -f\n```\n\n#### Erro de conexão com MongoDB\n```bash\n# Verificar se o MongoDB está rodando\ndocker compose ps\n\n# Ver logs do MongoDB\ndocker compose logs mongo\n```\n\n#### Erro 307 Redirect\n- Certifique-se de fazer requisições para URLs sem barra final\n- ✅ Correto: `POST /answers`\n- ❌ Incorreto: `POST /answers/`\n\n## 🤝 Contribuição\n\n1. 🍴 **Fork** o projeto\n2. 🌟 **Crie** uma branch para sua feature (`git checkout -b feature/AmazingFeature`)\n3. 💾 **Commit** suas mudanças (`git commit -m 'Add some AmazingFeature'`)\n4. 📤 **Push** para a branch (`git push origin feature/AmazingFeature`)\n5. 🔄 **Abra** um Pull Request\n\n## 📄 Licença\n\nEste projeto está sob a licença MIT. Veja o arquivo [LICENSE](LICENSE) para mais detalhes.\n\n## 👥 Autores\n\n- **Nelcifran Magalhães** - *Desenvolvimento inicial* - [@NelcifranMagalhaes](https://github.com/NelcifranMagalhaes)\n\n## 🙏 Agradecimentos\n\n- FastAPI pela excelente framework\n- MongoDB pela robustez do banco de dados\n- Beanie pelo ODM elegante e eficiente\n- Docker pela simplicidade de deployment\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**[⬆ Voltar ao topo](#-happytracker-api)**\n\nFeito com ❤️ para melhorar o bem-estar no trabalho\n\n\u003c/div\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnelcifranmagalhaes%2Fquestion_api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnelcifranmagalhaes%2Fquestion_api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnelcifranmagalhaes%2Fquestion_api/lists"}