{"id":37605735,"url":"https://github.com/robertolima-dev/django-usecases","last_synced_at":"2026-01-16T10:08:57.532Z","repository":{"id":286121436,"uuid":"960006958","full_name":"robertolima-dev/django-usecases","owner":"robertolima-dev","description":null,"archived":false,"fork":false,"pushed_at":"2025-06-26T15:36:34.000Z","size":442,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-26T16:41:12.186Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/robertolima-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2025-04-03T17:52:58.000Z","updated_at":"2025-06-26T15:36:38.000Z","dependencies_parsed_at":null,"dependency_job_id":"5cf333a7-8549-4896-9b46-be2b57525340","html_url":"https://github.com/robertolima-dev/django-usecases","commit_stats":null,"previous_names":["robertolima-dev/django-usecases"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/robertolima-dev/django-usecases","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robertolima-dev%2Fdjango-usecases","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robertolima-dev%2Fdjango-usecases/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robertolima-dev%2Fdjango-usecases/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robertolima-dev%2Fdjango-usecases/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/robertolima-dev","download_url":"https://codeload.github.com/robertolima-dev/django-usecases/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robertolima-dev%2Fdjango-usecases/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28478049,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T06:30:42.265Z","status":"ssl_error","status_checked_at":"2026-01-16T06:30:16.248Z","response_time":107,"last_error":"SSL_read: 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":[],"created_at":"2026-01-16T10:08:57.414Z","updated_at":"2026-01-16T10:08:57.501Z","avatar_url":"https://github.com/robertolima-dev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Django Use Cases - Advanced Django Learning Project\n\n[![Python](https://img.shields.io/badge/Python-3.8+-blue.svg)](https://www.python.org/downloads/)\n[![Django](https://img.shields.io/badge/Django-4.2+-green.svg)](https://www.djangoproject.com/)\n[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## 🚀 **Advanced Django Learning Repository with Real-World Solutions**\n\nA comprehensive Django project showcasing **19 specialized apps** covering advanced topics like **real-time communication**, **performance optimization**, **concurrency handling**, **search engines**, **asynchronous processing**, and **enterprise patterns**.\n\n### ✨ **Key Features**\n\n- 🔥 **Real-time WebSocket** applications (Chat, Notifications, Dashboard, Presence)\n- 🚀 **Performance optimization** with Redis caching, Elasticsearch, and query optimization\n- ⚡ **Asynchronous processing** with Celery, Redis, and background tasks\n- 🔒 **Advanced security** with custom middleware, rate limiting, and permission systems\n- 📊 **Monitoring \u0026 Analytics** with MongoDB integration and comprehensive logging\n- 🐳 **Containerized** with Docker and production-ready configurations\n- 🔍 **Semantic search** with Elasticsearch and dense vector embeddings\n- 📱 **Multi-tenant architecture** with isolated data and user management\n- 🎯 **Design patterns** implementation (Factory, Observer, Strategy, Proxy, Command)\n- 📈 **Scalable architecture** ready for production deployment\n\n### 🏗️ **Architecture Highlights**\n\n- **Microservices-ready** with modular app structure\n- **Event-driven** with Kafka integration and fallback mechanisms\n- **API-first** design with comprehensive REST endpoints\n- **Real-time capabilities** using Django Channels and WebSockets\n- **Multi-database** support (PostgreSQL, MongoDB, Redis)\n- **Search optimization** with Elasticsearch and semantic vectors\n- **Task scheduling** with Celery Beat and periodic tasks\n- **File management** with cloud storage providers (AWS S3, Google Cloud)\n\n### 🎓 **Perfect For**\n\n- **Django developers** wanting to learn advanced patterns\n- **Full-stack engineers** building real-time applications\n- **DevOps engineers** working with containerized Django apps\n- **Backend developers** implementing enterprise features\n- **Students** learning Django best practices and scalability\n\n---\n\n# Projeto Django\n\n## Estudos Avançados com ElasticSearch, Concorrência, Filtros Complexos, Permissões, WebSocket, Logs, Redis, Kafka, SQS, MongoDB, Throttle, Security Headers, Celery Worker, Celery Beat, Retry Mechanism e Circuit Breaker \n\nEste projeto é um repositório de estudos organizados em 19 apps Django distintos, com foco em soluções reais de performance, concorrência e boas práticas.\n\n## 📁 Estrutura dos Apps\n\n### `book` – Consultas Otimizadas, Comentários, Agregações e Cache Redis\n- Modela livros com autor, tags e comentários\n- Usa `select_related`, `prefetch_related` e `annotate` para otimizar queries\n- Permite filtros por título, autor, tags e número de comentários\n- Conta e ordena livros por número de comentários (`comments_count`)\n- Utiliza `SerializerMethodField` apenas quando necessário\n- **Integração com Cache Redis**:\n  - Cacheia listagem de livros (`/books/`) sensível a filtros, ordenação e paginação\n  - Cacheia detalhes de livros individuais (`/books/{id}/`)\n  - Geração automática de chaves únicas de cache baseadas nos parâmetros da URL\n  - Expiração automática dos caches em 5 minutos\n  - Invalidação de cache nas operações de criação e atualização de livros\n- Comandos para gerar dados fictícios:\n  ```bash\n  python manage.py populate_books          # Cria livros com tags e autores\n  python manage.py populate_comments       # Gera comentários aleatórios\n  python manage.py reindex_semantic_books  # Gera indice busca semantica\n  ```\n\n### `chat` - sistema de mensagens em tempo real com salas privadas e em grupo\n- Salas privadas (1-1) ou em grupo (2+ usuários)\n- Envio de mensagens via WebSocket e fallback por API REST\n- Histórico completo por sala\n- Suporte a diferentes tipos de mensagem (`text`, `image`, `link`, etc.)\n- Avatar dos usuários no retorno das mensagens e salas\n- Integração com Channels (WebSocket) e Celery (opcional para notificações)\n\n### `ecommerce` - Concorrência e Transações Atômicas\n- Simula checkout com ajuste de estoque seguro\n- Usa `select_for_update` com `transaction.atomic()`\n- Permite testes de concorrência com Celery ou scripts externos\n- Integração com `Elasticsearch` via `django-elasticsearch-dsl` somente local\n- Indexação automática de produtos ao criar, editar ou remover\n- Comando para indexação em massa:  \n  ```bash\n  python manage.py index_products\n  ```\n\n### `report` - Processamento Assíncrono com Celery\n- Gera relatórios CSV de usuários ativos\n- Executa a geração de arquivos via Celery + Redis\n- Atualiza status (`pending`, `processing`, `done`, `failed`)\n\n### `course` - Filtros Avançados, Busca Otimizada e Integração com Elasticsearch\n- Filtros completos: textos, datas, números, booleanos e relacionamentos\n- Ordenações dinâmicas: order_by=rating, order_by=purchases, ordering=-price, etc.\n- **Filtros especiais**: avg_rating_min, min_purchases, only_free, is_featured\n- Busca full-text otimizada usando Elasticsearch:\n- Busca léxica com multi_match (boost em title)\n- Autocomplete inteligente (edge_ngram) no título dos cursos\n- Facets dinâmicos (agregações) para categorias, tags e faixas de preço\n- Integração flexível local com Elasticsearch apenas em ambiente de desenvolvimento(USE_ELASTIC configurado via settings.PROJECT_ENV)\n- Fallback automático para consultas Django ORM em ambientes sem Elasticsearch\n- **Notificações em tempo real** para novos cursos publicados, usando WebSocket (Django Channels)\n\n### `permissions` - Sistema de Permissões por Perfil de Acesso\n- Baseado no campo `access_level` do model `Profile`\n- Permissões com `IsAdmin`, `IsSupport`, `IsUser`, etc.\n- Controle de acesso por papel via DRF (`has_permission`)\n- Pode ser expandido para RBAC ou ACL no futuro\n\n### `notifications` - Notificações em Tempo Real com WebSocket\n- WebSocket com autenticação via token `/ws/notifications/`\n- Suporte a **notificações globais** (`obj_code='platform'`, `obj_id=None`) e **individuais** (`obj_code='user'`, `obj_id=user.id`)\n- Broadcast da mensagem para todos os usuários online, mas com **uma única instância persistida**\n- Modelos auxiliares:\n  - `UserNotificationRead`: marca notificações como lidas por usuário\n  - `UserNotificationDeleted`: armazena quais usuários \"excluíram\" notificações\n- Notificações retornadas já indicam se foram lidas (`read: true/false`) e ocultam as que foram marcadas como excluídas\n- Integração com `course`: ao criar um novo curso, é disparada uma notificação em tempo real\n- Método PATCH para marcar como lida:  \n  `PATCH /api/v1/notifications/\u003cid\u003e/mark-as-read/`\n\n### `auditlog` - Sistema de Auditoria e Logs de Eventos\n- Captura automaticamente ações de `create`, `update` e `delete`\n- Armazena: usuário, modelo afetado, ID, representação e mudanças\n- Uso de `signals` genéricos e `model_to_dict` com `DjangoJSONEncoder`\n- Visualização somente leitura no Django Admin\n- Ideal para rastreabilidade e conformidade de segurança\n\n### `tenants` - Suporte a Multitenancy (multi-clientes)\n- Model `Tenant` com vínculo a múltiplos usuários\n- Middleware que injeta `request.tenant` automaticamente\n- Mixin `TenantQuerysetMixin` para isolamento por queryset\n- Exemplo de uso com model `Project`, vinculado ao tenant\n\n### `throttle` - Sistema de Cotas e Limites por Usuário (Rate Limiting)\n- Criação de **cotas de uso por tipo de ação** (ex: `upload`)\n- Validação automática via `middleware` e/ou `throttle` do DRF\n- **Rate Limiting com planos dinâmicos**:\n  - `free`: 50 requisições/minuto\n  - `pro`: 200 requisições/minuto\n  - `admin`: 1000 requisições/minuto\n- Implementado via `CustomUserRateThrottle` com base em `user.profile.plan`\n- Middleware consulta e bloqueia se limite for atingido\n- Armazena consumo diário em `UserQuota` (opcional)\n- Reset diário automático (se implementado com cron ou Celery)\n- Exemplo prático: limitar **acesso à API pública** ou **operações sensíveis**\n- Comando para testar limites via terminal:\n  ```bash\n  python manage.py test_throttle --token=SEU_TOKEN_JWT\n  ```\n\n### `presence` - Presença Online com WebSocket\n- WebSocket com autenticação via token `/ws/presence/`\n- Rastreia usuários online\n- API: `GET /api/v1/online-users/`\n- Model `UserPresence`: `user`, `is_online`, `last_seen`\n\n### `dashboard` - Painel Administrativo em Tempo Real\n- WebSocket com autenticação via token `/ws/dashboard/`\n- Envia dados agregados: total de users, cursos, livros, relatórios\n- Atualiza automaticamente ao criar `user`, `course`, `book`, `report` ou `notification`\n- Ideal para visualização de métricas sem recarregar a página\n\n### `mailer` - Envio de Emails Assíncronos\n- Tecnologias Utilizadas:\n  - Celery para tarefas assíncronas\n  - Backend SMTP (AWS SES) para envio seguro e confiável\n  - Django EmailMessage para construção e envio dos e-mails\n  - Banco de Dados para armazenamento dos templates de e-mail\n\n- Funcionalidades:\n  - Envio de e-mail para todos os usuários desacoplado via send_email()\n  - Integração com templates dinâmicos, permitindo o uso de variáveis no corpo do e-mail\n  - Pronto para integração com sistemas de alertas e notificações\n  - Cadastro de Books e Courses com notificações automáticas\n  - Encadeamento de Tarefas: Chamadas de uma task para outra, como no caso do envio d e-mail para todos os administradores após um evento.\n\n### `image_processing` - Upload e Processamento com Thumbnails\n- Upload de imagens vinculado ao usuário autenticado\n- **Validação automática** no upload:\n  - Formatos permitidos: `JPEG`, `JPG`, `PNG`, `WEBP`\n  - Tamanho máximo: 5MB\n  - Dimensões mínimas: 300x300 px\n- **Processamento assíncrono com Celery** após upload:\n  - Geração de 3 tamanhos: `thumbnail` (150x150), `medium` (600px), `large` (1200px)\n  - Conversão automática da imagem para `JPEG` ou `WEBP`\n- Campo `output_format` para o usuário escolher o formato de saída\n- Campos disponíveis:\n  - `original_image`, `thumbnail`, `medium`, `large`, `output_format`, `uploaded_at`\n- Integração com SQS, não é possível testar localmente.\n\n### `scheduler` – agendamento de tarefas com Celery Beat\n- Agendamento automático de tarefas recorrentes com `django-celery-beat`\n- Task periódica para **resetar cotas diárias** do app `throttle`\n- Execução programada via `CrontabSchedule`\n- Integração com Celery Worker e Beat\n- Script automatizado no `apps.py` registra a `PeriodicTask` no primeiro load\n- Totalmente compatível com ambientes de produção no ECS\n\n### `monitor` – Painel de monitoramento de tarefas Celery no Django Admin\n- Visualização completa do histórico de execuções de tarefas Celery\n- Exibe: `task_id`, `task_name`, `status`, tempo de execução (`runtime`), data de criação e conclusão\n- Filtros por status (`SUCCESS`, `FAILURE`, `PENDING`, etc.) e busca por nome ou ID\n- Integração com `django-celery-results`, com backend de resultados armazenados no banco de dados\n- Task fallback inteligente: preenche automaticamente o `task_name` se ausente\n- Ideal para ambientes com múltiplas workers e tarefas periódicas programadas\n\n### `search` - Busca Semântica Avançada com Elastic e Dense Vectors\n- Implementa **busca semântica** baseada em **Dense Vectors** usando `cosine similarity`\n- Integração local com **`sentence-transformers`** (`all-MiniLM-L6-v2`) para geração de embeddings\n- Utiliza **ElasticSearch 8+** para suporte a `dense_vector` nativo\n- Cria um índice dedicado `semantic_books` para armazenar vetores de significado\n- **Busca híbrida** combinando:\n  - **Semântica** (similaridade de vetores)\n  - **Lexical** (`multi_match` textual) com boost no título\n- Filtro automático para retornar apenas resultados relevantes (`score ≥ 6.0`)\n- APIs disponíveis:\n  ```bash\n  GET /api/semantic-search/?q=termo_de_busca\n  ```\n\n### `kafka_events` - Integração Django com Apache Kafka para Eventos Assíncronos e Resilientes\n- Implementa **envio e consumo de eventos Kafka** diretamente do Django\n- Configuração dinâmica de **broker** e **tópicos** via `.env` (`KAFKA_BROKER_URL`, `KAFKA_COURSE_TOPIC`)\n- **Producer resiliente** com:\n  - `retry` com backoff exponencial (`tenacity`)\n  - `circuit breaker` com auto-recovery (`pybreaker`)\n  - **fallback local**: eventos salvos em disco se Kafka estiver offline\n- **Comando para reenviar eventos salvos** em fallback:\n  ```bash\n  python manage.py resend_kafka_fallback\n  ```\n- Estrutura modular:\n  - **Producers**: envio de eventos por domínio (`course`, `book`)\n  - **Consumers**: escutam tópicos de forma desacoplada\n  - **Utils**: cliente Kafka, producer resiliente, fallback\n- Integração com o app `course` via **Django Signals**\n- Fluxo completo com logs e tolerância a falhas\n- APIs e comandos disponíveis:\n  ```bash\n  # Producer interno via Signal\n  send_course_created_event(course_instance)\n\n  # Envio manual em lote (teste fila Kafka)\n  python manage.py kafka_test\n\n  # Consumer manual\n  from kafka_events.consumers.course_consumer import consume_course_created_events\n  consume_course_created_events()\n  ```\n\n### `knowledge` - Tópicos Avançados para Django Admin\n- Modela tópicos com título, descrição, nível (`fundamental`, `intermediate`, `advanced`)\n- Admin com coloração dinâmica do campo `nível` usando `format_html`\n- Suporte a `inlines` de estudo com o modelo `KnowledgeStudy`\n- Registro de estudos realizados por usuários (com notas e data)\n- Ações em lote no admin para marcar tópicos como recomendados\n- Comando para popular tópicos avançados com `populate_knowledge`\n- Comando para simular estudos com usuários via `populate_knowledge_studies`\n- Pronto para servir como referência didática ou base para sistema de aprendizado interno\n\n### `security` – Middleware de Segurança com Headers HTTP\n- **Proteções ativas com headers HTTP**:\n- `X-Frame-Options: DENY` → bloqueia *clickjacking* ao proibir iframes externos\n- `X-Content-Type-Options: nosniff` → evita que o navegador interprete arquivos como scripts (MIME sniffing)\n- `Strict-Transport-Security: max-age=63072000; includeSubDomains` → força o uso de HTTPS (requer ambiente seguro)\n- `Content-Security-Policy: default-src 'self'` → impede carregamento de scripts e recursos de terceiros não autorizados (protege contra XSS)\n- **Como testar**:\n- Acesse qualquer rota autenticada\n- Verifique os headers no navegador (DevTools → Network → Headers) ou via `curl`:\n    ```bash\n    curl -I http://localhost:8000/\n    ```\n\n### `analytics` - Monitoramento de Eventos com MongoDB\n- Armazenamento eficiente de eventos usando MongoDB\n- Paginação padrão DRF com suporte a grandes volumes de dados\n- API REST para listagem e consulta de eventos\n- Integração com o projeto Django utilizando o driver pymongo\n- Paginação customizada utilizando o padrão LimitOffsetPagination\n- Suporte a ordenação por campos específicos\n\n\n### `mediahub` – Armazenamento de arquivos com suporte a múltiplos providers - Django Storage\n* Upload de arquivos de forma desacoplada, segura e escalável\n* Suporte a múltiplos storages: **AWS S3** ou **Google Cloud Storage**\n* Escolha do provedor via variável de ambiente (`USE_AWS`)\n* Geração de nomes de arquivos com **hash único** via `upload_to`\n* URLs automáticas compatíveis com CDN (`CloudFront`, `GCP CDN`)\n* Extensível para uso de `signed URLs` e integração com cache\n* Preparado para produção com **storages externos desacoplados do backend**\n\n### `integrations` – Integração com APIs externas e Logs HTTP\n* Cliente HTTP robusto com suporte a **retries automáticos** e **exponencial backoff**\n* Registro completo de chamadas HTTP: método, URL, tempo de resposta, status e payload\n* Suporte nativo a headers customizados e payloads JSON\n* Centraliza interações com serviços externos (ex: OpenAI, APIs públicas, webhooks)\n* Armazena falhas para auditoria e facilita troubleshooting\n* Integração fácil com `requests` + `Retry` do `urllib3`\n\n---\n\n## ⚙️ Como rodar o projeto\n\n```bash\npython -m venv .env\nsource .env/bin/activate\n```\n\nCrie um arquivo venv.sh baseado no venv_example.sh e rode:\n```bash\nchmod +x venv.sh\nsource venv.sh\n```\n\n```bash\npip install -r requirements.txt\npython manage.py migrate\npython manage.py createsuperuser\n```\n\n\n### Rodar com WebSocket (Daphne):\n```bash\ndaphne api_core.asgi:application\n```\n\n\u003e O projeto usa Django Channels com ASGI, necessário para WebSockets.\n\n---\n\n## 🚀 Rode o docker compose\n\n```bash\ndocker-compose up -d\n```\n\n## 🚀 Como rodar o Celery + Redis\n\n1. Rode o worker Celery:\n```bash\ncelery -A api_core worker --loglevel=info\n```\n\n2. Rode o beat Celery:\n```bash\ncelery -A api_core beat --loglevel=info\n```\n\n---\n## 🚀 Integração Elasticsearch – Ambiente Local\n\nEste projeto utiliza **Elasticsearch** para otimizar buscas avançadas no app `course`, disponível **apenas em ambiente de desenvolvimento** (`USE_ELASTIC` configurado via `settings.PROJECT_ENV`).\n\n### 📦 Requisitos para uso local\n\n- Docker instalado\n- Compose disponível (`docker-compose`)\n- Elasticsearch 8.x ou superior\n\n### 🐳 Rodando o Elasticsearch no ambiente local\n\nPara utilizar a busca com Elasticsearch localmente, execute o seguinte comando (apenas uma vez):\n\n```bash\ndocker run -d \\\n  --name elastic \\\n  -p 9200:9200 \\\n  -e \"discovery.type=single-node\" \\\n  -e \"xpack.security.enabled=false\" \\\n  docker.elastic.co/elasticsearch/elasticsearch:8.12.1\n```\n\n```bash\ncurl http://localhost:9200\n```\n\n### ⚙️ Configuração no Django\n\n**settings.py**\n\n```python\n# Usar Elastic apenas em ambiente local\nUSE_ELASTIC = PROJECT_ENV == \"local\"\n\n# Config Elasticsearch\nELASTICSEARCH_DSL = {\n    'default': {\n        'hosts': 'localhost:9200'\n    },\n}\n```\n\n### 📚 Comandos Úteis para Gerenciar o Índice\n\n#### 1. Deletar índice\n```bash\npython manage.py search_index --delete --models course.Course\n```\n\n#### 2. Criar índice\n```bash\npython manage.py search_index --create --models course.Course\n```\n\n#### 3. Reindexar cursos\n```bash\npython manage.py index_courses\n```\n\nEsses comandos garantem que o índice `courses` esteja atualizado conforme o `CourseDocument`.\n\n### 🔍 Funcionalidades Ativadas com Elasticsearch\n\n- Busca **full-text** (`multi_match`) com boost para `title`\n- **Autocomplete** inteligente com `edge_ngram`\n- Fallback automático para consultas ORM caso `USE_ELASTIC = False`\n\n---\n\n## 📝 Documentação da API – `django-usecases`\n\nO projeto está integrado com dois geradores de documentação OpenAPI para APIs REST:\n\n- 🔍 **Swagger UI e ReDoc com drf-spectacular**\n- 📄 **Swagger UI com drf-yasg**\n\n### 🔗 Endpoints de documentação\n\n- **drf-spectacular**\n  - `/schema/` → OpenAPI JSON\n  - `/schema/swagger/` → Swagger UI\n  - `/schema/redoc/` → ReDoc\n\n- **drf-yasg**\n  - `/swagger/` → Swagger UI\n  - `/redoc/` → ReDoc\n  - `/swagger.json` → JSON do schema\n\n### ✅ Organização por módulos\n\nOs endpoints estão organizados por aplicação no Swagger e ReDoc através da propriedade `tags`, permitindo fácil navegação por áreas da plataforma:\n\n- `Books` → Endpoints de livros (`/api/v1/books/`)\n- `Courses` → Endpoints de cursos (`/api/v1/courses/`)\n- `Chat` → Sistema de mensagens privadas (`/api/v1/message/`)\n- `Ecommerce` → Produtos e pedidos com controle de estoque (`/api/v1/ecommerce/`)\n- `Throttle` → Limites de uso da API (`/api/v1/throttle/`)\n- `Scheduler` → Agendamentos periódicos com Celery Beat\n- `Image Processing` → Upload e conversão de imagens\n- `Monitor` → Painel de tarefas assíncronas com Celery\n- ...entre outros módulos\n\n### 🛠️ Anotações nos endpoints\n\nA documentação foi incrementada com:\n\n- `@extend_schema` (`drf-spectacular`) para descrições, exemplos e parâmetros\n- `@swagger_auto_schema` (`drf-yasg`) para personalização individual de métodos\n- Exemplo de resposta (`OpenApiExample`)\n- Parâmetros de consulta (`OpenApiParameter`), como `?ordering=-created_at`\n\n\n---\n\n## 📚 `search` - Busca Semântica Avançada com Elastic e Dense Vectors\n\n### Exemplo de resposta\n\n```json\n[\n  {\n    \"id\": 94,\n    \"title\": \"Métodos Django\",\n    \"score\": 8.92\n  },\n  {\n    \"id\": 95,\n    \"title\": \"Django Queries\",\n    \"score\": 8.94\n  },\n  {\n    \"id\": 96,\n    \"title\": \"Django OOP\",\n    \"score\": 9.05\n  }\n]\n```\n\n### Tecnologias utilizadas\n- ElasticSearch 8.11+\n- Kibana 8.11+\n- Django REST Framework\n- django-elasticsearch-dsl\n- sentence-transformers (Hugging Face)\n\n### Comando de reindexação\n\n```bash\npython manage.py reindex_semantic_books\n```\n\n- Gera embeddings e reindexa todos os livros semanticamente no Elastic.\n\n---\n\n### Casos de uso típicos de retries (integrations)\n\n* 📡 **Chamada a APIs com instabilidade**: como GPT-4 ou serviços externos que demandam tolerância a falhas\n* 🔁 **Retentativas seguras** em chamadas que podem retornar 500, 502 ou 429\n* 📊 **Observabilidade**: monitoramento de latência e análise de padrões de erro\n* 🔐 **Interação com serviços autenticados**, como envio de payloads via `Authorization Bearer`\n* 🛠️ **Ambiente de testes**: integração com endpoints de simulação como `httpbin.org` para validação de lógica HTTP\n* 🔍 **Auditoria**: armazenar requisições feitas e seus resultados para futura análise, especialmente em operações críticas\n\n---\n\n## 🧩 Design Patterns no projeto `django-usecases`\n\nEste projeto aplica diversos **Design Patterns** clássicos da engenharia de software, tanto de forma implícita (como boas práticas do Django) quanto explicitamente por meio da organização modular, tasks assíncronas e arquitetura desacoplada.\n\n### 1. **Factory Pattern**\n- **Onde**: Serializers (`serializer.create()`)\n- **Exemplo**: `UploadedImageSerializer`, `CourseSerializer`\n- **Descrição**: Os serializers funcionam como fábricas para criação de objetos com lógica de validação e instanciamento encapsulada.\n\n### 2. **Observer Pattern**\n- **Onde**: Celery + Django Signals\n- **Exemplo**: `create_thumbnail` (task assíncrona), `monitor.signals.fill_task_name_if_missing`\n- **Descrição**: Eventos disparam ações subsequentes como notificações ou transformações de dados, desacopladas da lógica principal.\n\n### 3. **Command Pattern**\n- **Onde**: `manage.py` custom commands\n- **Exemplo**: `python manage.py reset_user_quotas`\n- **Descrição**: Lógica encapsulada em comandos reutilizáveis e automatizáveis.\n\n### 4. **Strategy Pattern**\n- **Onde**: Filtros dinâmicos, Permissões, WebSocket Consumers\n- **Exemplo**: `CourseFilter`, `IsOwnerPermission`, `ChatConsumer`\n- **Descrição**: Algoritmos intercambiáveis selecionados em tempo de execução com base no contexto.\n\n### 5. **Proxy Pattern**\n- **Onde**: Serializers com campos computados e propriedades em models\n- **Exemplo**: `UserMiniSerializer`, `Room.last_message` (no `chat`)\n- **Descrição**: Encapsula acesso a objetos complexos com interface simplificada.\n\n---\n\n## 🎯 Decorators personalizados\n\nEste projeto implementa o **Decorator Pattern** para encapsular comportamentos reutilizáveis em torno de views, tasks, actions administrativas e consumers WebSocket.\n\n### ✅ Lista de decorators aplicados\n\n| Decorator | Objetivo | Aplicado em |\n|----------|----------|-------------|\n| `@log_task_execution` | Loga início/fim/erro de tasks Celery | `image_processing`, `scheduler` |\n| `@check_quota(action=\"...\")` | Valida se o usuário tem cota para realizar a ação | `throttle`, `chat`, `upload` |\n| `@admin_action_log(\"msg\")` | Registra e notifica actions feitas no Django Admin | `admin.py` de qualquer app |\n| `@ensure_room_participant` | Garante que o usuário está em uma `Room` antes de conectar via WebSocket | `chat/consumers.py` |\n\n---\n\n### 📌 Exemplos de uso\n\n#### 📦 `log_task_execution`\n\n```python\n@shared_task(name='image_processing.create_thumbnail')\n@log_task_execution\ndef create_thumbnail(image_id):\n  pass\n```\n\n---\n\n### 💳 App `ecommerce`: concorrência com `select_for_update`\n\n### Objetivo:\nSimular compras simultâneas com ajuste seguro de estoque.\n\n### Testar concorrência:\n1. Gere um produto com `stock=1`\n2. Use script com threads e dois tokens diferentes:\n\n```python\nimport threading, requests\n\ndef comprar(token):\n    r = requests.post(\"http://localhost:8000/api/v1/orders/\", headers={\"Authorization\": f\"Bearer {token}\"}, json={\"product_id\": 1, \"quantity\": 1})\n    print(r.status_code, r.json())\n\nthreading.Thread(target=comprar, args=(token1,)).start()\nthreading.Thread(target=comprar, args=(token2,)).start()\n```\n\n### Garantias:\n- O primeiro pedido finaliza\n- O segundo falha com \"Estoque insuficiente\"\n\n---\n\n### 📊 App `report`: tarefas assíncronas com Celery\n\n### Objetivo:\nGerar relatórios de usuários ativos em background\n\n### Como usar:\n- `POST /api/v1/reports/` com payload vazio\n- Task Celery é disparada: `generate_user_report`\n- Gera CSV em `media/reports/` e atualiza o campo `file_path`\n\n### Exemplo de resposta:\n```json\n{\n  \"status\": \"done\",\n  \"file_path\": \"/media/reports/users_report_1.csv\"\n}\n```\n\n---\n\n### 📖 App `book`: consultas com relacionamentos\n\n### Errado:\n```python\nBook.objects.all()  # causa N+1\n```\n\n### Correto:\n```python\nBook.objects.select_related(\"author\").prefetch_related(\"tags\", \"comments\").annotate(\n    comments_count=Count(\"comments\")\n)\n```\n\n#### Resposta:\n```json\n{\n  \"id\": 1,\n  \"title\": \"Harry Potter\",\n  \"author\": {\n    \"id\": 2,\n    \"username\": \"autor\"\n  },\n  \"tags\": [\n    {\"id\": 1, \"name\": \"Fantasia\"},\n    {\"id\": 2, \"name\": \"Magia\"}\n  ],\n  \"comments_count\": 12\n}\n```\n\n### Serializer otimizado:\nEvite `SerializerMethodField` com queries internas. Use dados pré-carregados ou `annotate()`.\n\n---\n\n### 🚦 App `throttle`: limites de requisições\n\n```python\nfrom apps.throttle.utils import check_and_increment_quota\n\n\nclass UploadViewSet(ModelViewSet):\n    serializer_class = ReportRequestSerializer\n    permission_classes = [IsAuthenticated]\n    http_method_names = ['post']\n\n    def create(self, request, *args, **kwargs):\n        # função =\u003e check_and_increment_quota(request.user, \"upload\") \n        check_and_increment_quota(request.user, \"upload\")\n        return Response({\"message\": \"Upload feito com sucesso!\"}, status=status.HTTP_201_CREATED)\n```\n\n---\n\n### 🎓 App `course`: filtros avançados e ordenações inteligentes\n\nListagem de cursos com suporte completo a filtros dinâmicos, relacionamentos e ordenação por popularidade ou avaliação.\n\n### Filtros suportados:\n- `title=django` (busca no título)\n- `description=avançado` (busca na descrição)\n- `price_min=100\u0026price_max=300`\n- `start_date_from=2025-04-01\u0026start_date_to=2025-04-30`\n- `workload_min=10\u0026workload_max=40`\n- `tags=1,3` ou `tag=python`\n- `is_active=true`, `is_free=false`, `is_featured=true`\n- `category=2`, `instructor=1`\n- `avg_rating_min=4` (média mínima de avaliação)\n- `min_purchases=10` (mínimo de compras pagas)\n- `only_free=true` (gratuitos apenas)\n\n### 📊 Ordenações especiais:\n\nUse o parâmetro `order_by` ou `ordering`:\n\n- `order_by=rating` → cursos com melhor avaliação média\n- `order_by=purchases` → cursos mais comprados\n- `ordering=-created_at` → mais recentes\n- `ordering=-price` → mais caros primeiro\n\n### Exemplo:\n```http\nGET /api/v1/courses/?price_min=50\u0026tags=1,3\u0026is_free=false\u0026order_by=rating\n```\n\n---\n\n### 🔔 App `notifications`: Notificações automáticas:\n\nAo criar um curso via `POST /api/v1/courses/`, todos os usuários conectados via `/ws/notifications/` recebem notificações em tempo real com o título do curso!\n\nUtilize o wscat para testar no terminal:\n\n```bash\nwscat -c \"ws://localhost:8000/ws/notifications/?token=TOKEN_DO_USUARIO\"\n```\n\n---\n\n### 📤 App `image_processing`: Upload de imagem\n\n```http\nPOST /api/v1/uploads-images/\nAuthorization: Token SEU_TOKEN\n\nFormData:\n- original_image: arquivo (.jpg, .png, .webp, etc.)\n- output_format: JPEG ou WEBP (opcional, padrão: JPEG)\n```\n\n---\n\n### 👥 App `presence`: lista de presença de usuários online\n\nUma lista usuários online no `GET /api/v1/online-users/`, todos os usuários conectados via `/ws/presence/` entram numa lista de users online!\n\nUtilize o wscat para conectar um usário:\n\n```bash\nwscat -c \"ws://localhost:8000/ws/presence/?token=TOKEN_DO_USUARIO\"\n```\n--- \n\n### 💬 App `chat`: sistema de mensagens em tempo real com salas privadas e em grupo\n\nEnvie mensagens entre usuários autenticados em tempo real via WebSocket, com fallback por API REST.\n\nO chat privado é baseado em salas (`Room`) que conectam N usuários.\n\n### 🔧 Como funciona\n\nCrie (ou recupere) uma sala com outro usuário via:\n\n```http\nPOST /api/v1/rooms/\nAuthorization: Token TOKEN_DO_USUARIO\n{\n  \"user_ids\": [4, 5],\n  \"name\": \"Grupo de Estudos\"\n}\n```\n\n```bash\nwscat -c \"ws://localhost:8000/ws/chat/room/ROOM_ID/?token=TOKEN_DO_USUARIO\"\n```\n\nEnvie uma mensagem assim via websocket:\n\n```json\n{\n  \"type_message\": \"text\",\n  \"content\": {\n    \"text\": \"Olá, tudo bem?\"\n  }\n}\n```\n\nEnviar mensagens via API REST (opcional):\n\n```http\nPOST /api/v1/message/send/\nAuthorization: Token TOKEN_DO_USUARIO\n{\n  \"room_id\": 12,\n  \"type_message\": \"image\",\n  \"content\": {\n    \"url\": \"https://meu-bucket.s3.amazonaws.com/foto.jpg\",\n    \"caption\": \"Foto da reunião\"\n  }\n}\n```\n---\n\n### 📊 App `dashboard`: Painel Administrativo em Tempo Real\n\nEste app fornece dados agregados de forma dinâmica para um painel administrativo, usando **WebSocket** para envio de informações em tempo real.\n\n### ✅ Casos de Uso\n\n#### 📡 Conexão via WebSocket\n\nO WebSocket do painel administrativo pode ser acessado com:\n\n```bash\nwscat -c \"ws://localhost:8000/ws/dashboard/?token=TOKEN_DO_USUARIO\"\n```\n\n#### Resposta:\n\n```json\n{\n  \"type\": \"dashboard_data\",\n  \"users_count\": 51,\n  \"courses_count\": 40,\n  \"reports_count\": 21,\n  \"books_count\": 85\n}\n```\n\n---\n\n## 📆 Populando dados\n\n```bash\npython manage.py populate_users               # Cria 100 usuarios com faker\npython manage.py populate_books               # Cria 100 livros aleatórios\npython manage.py populate_comments            # Cria comentários aleatórios nos livros\npython manage.py populate_courses             # Cria 30 cursos aleatórios\npython manage.py populate_rating              # Cria avaliações para cursos\npython manage.py populate_payment             # Cria pagamentos de cursos\npython manage.py populate_tenants             # Cria tenants com usuários\npython manage.py populate_projects            # Cria projetos associados aos tenants\npython manage.py populate_rooms_and_messages  # Cria rooms e messages aleatórias\npython manage.py reindex_semantic_books       # Cria indice de busca semantica\npython manage.py index_courses                # Cria indice de cursos ElasticSearch\npython manage.py index_products               # Cria indice de produtos ElasticSearch\npython manage.py populate_knowledge           # Cria lista de knowledge\npython manage.py populate_knowledge_studies   # Cria alunos para knowledge (inlines)\npython manage.py populate_analytics           # Cria 1000 dados no mongodb\n```\n\n---\n\n## 📄 Utilidade\nDesenvolvido para estudos aprofundados em Django com casos reais e foco em performance, concorrência, boas práticas e comunicação em tempo real.\n\n---\n\n## 🧠 Autor\n**Roberto Lima**  \n- 📧 **Email**: robertolima.izphera@gmail.com\n- 🔗 [GitHub Roberto Lima](https://github.com/robertolima-dev)  \n- 💼 [Linkedin Roberto Lima](https://www.linkedin.com/in/robertolima-dev/)\n- 🌐 [Website Roberto Lima](https://robertolima-developer.vercel.app/)\n- 👤 [Gravatar Roberto Lima](https://gravatar.com/deliciouslyautomaticf57dc92af0)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobertolima-dev%2Fdjango-usecases","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frobertolima-dev%2Fdjango-usecases","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobertolima-dev%2Fdjango-usecases/lists"}