Microservice Facilities

1. OBJETIVO DO REPOSITÓRIO

O microservice-facilities é um microserviço que atua como facilitador central para operações comuns do ecossistema Aster/UVA. Seu objetivo principal é gerenciar e facilitar diversas operações e processos essenciais, incluindo:

• Upload assíncrono de arquivos para AWS S3 com organização por tenant
• Sistema de notificações personalizadas por usuário com controle de leitura
• Consulta e importação de dados de concessionárias de energia elétrica via API da ANEEL
• Gerenciamento de dicas e notícias do sistema com personalização por usuário/tenant
• Dashboard centralizado com dados agregados e placeholders dinâmicos
• Processamento assíncrono via filas para melhor performance e escalabilidade

2. ÚLTIMA REVISÃO

• 15/09/2025 - Revisão e atualização da documentação (Equipe)

3. TECNOLOGIAS UTILIZADAS

Backend:

.NET 8.0, ASP.NET Core Web API, Entity Framework Core com PostgreSQL, Serilog (logging estruturado com múltiplos outputs), Swagger/OpenAPI (documentação automática), AWS SDK (S3 para armazenamento, SES para emails), HttpClient (integração com API ANEEL), Newtonsoft.Json (serialização JSON), Background Services (processamento assíncrono)

Frontend:

Não aplicável (API pura sem frontend próprio)

Banco de Dados:

PostgreSQL (banco principal - facilities-db), AWS S3 (armazenamento de arquivos - aster-attachments-prod), AWS SES (envio de emails transacionais)

Ferramentas de Conexão e Infraestrutura:

Docker (containerização), Health Checks (monitoramento de saúde), CORS (configuração de origens permitidas), Memory Cache (cache em memória), AWS SQS (filas para processamento assíncrono), Kestrel (servidor web com configurações customizadas)

4. FUNCIONALIDADES E DOMÍNIOS

O microservice-facilities gerencia os seguintes domínios principais:

Dashboard:

Exibição de tips e news personalizadas por usuário/tenant, Substituição de placeholders (#user, #tenant) em tempo real, Suporte a pods, charts e tables (estrutura preparada), Agregação de dados de múltiplas fontes

Upload de Arquivos:

Upload assíncrono para AWS S3 com validação de tamanho, Organização por tenant e estrutura de pastas customizável, Processamento via fila SQS para melhor performance, Suporte a múltiplos formatos de arquivo

Notificações:

Sistema de notificações por usuário com controle de leitura, Paginação de resultados para performance, Contagem de notificações não lidas, Processamento assíncrono via filas

Concessionárias de Energia:

Consulta de dados da ANEEL via API oficial, Importação em lote de tarifas (TUSD_FioB, TUSD, TE), Filtros por CNPJ, subgrupo, modalidade, classe de consumidor, Cache de dados para otimização de performance

Dicas e Notícias:

Gerenciamento de conteúdo personalizado por categoria, Suporte a placeholders dinâmicos, Organização por tenant e usuário, Controle de visibilidade e acesso

5. ARQUITETURA FRONTEND

Não aplicável - API pura sem frontend próprio

6. ARQUITETURA BACKEND

Clean Architecture com separação de responsabilidades:

Controllers (V1):

DashboardController: Endpoint para dados do dashboard inicial com placeholders dinâmicos
ElectricityCompaniesController: Gestão completa de concessionárias de energia
UserNotificationsController: Gerenciamento de notificações do usuário
AttachmentsController: Upload assíncrono de arquivos para S3

Services:

ElectricityCompanyService: Lógica de negócio para concessionárias e integração ANEEL
FileQueueService: Processamento assíncrono de uploads via SQS
FileUploadService: Upload de arquivos para AWS S3
NotificationQueueService: Processamento assíncrono de notificações
NotificationService: Gerenciamento de notificações
SESEmailService: Envio de emails via AWS SES
SMTPEmailService: Envio de emails via SMTP
TipsAndNewsService: Gerenciamento de dicas e notícias

Repositories:

ElectricityCompanyRepository: Acesso a dados de concessionárias
NotificationRepository: Acesso a dados de notificações
TipsAndNewsRepository: Acesso a dados de dicas e notícias

Gateways:

AneelApiGateway: Integração com API da ANEEL para dados de tarifas

Entities/DTOs:

ElectricityCompany: Modelo de concessionária de energia
UserNotification: Modelo de notificação do usuário
TipsAndNews: Modelo de dicas e notícias
DashboardDTO: DTO para dados do dashboard
FileUploadRequestDTO: DTO para upload de arquivos

Background Services:

FileUploadBackgroundService: Processamento assíncrono de uploads
SqsConsumerBackgroundService: Consumo de mensagens SQS

Helper/Utilities:

Configurações de CORS, Health Checks, Swagger, Exception handling global, Logging estruturado com Serilog, Mapeamentos entre entidades e DTOs

7. ROTAS E ENDPOINTS

Base URL: /api/v1 | Porta: 3010

Dashboard:

Electricity Companies:

User Notifications:

Attachments:

Health Check:

8. ESTRUTURA DE DADOS, TABELAS E VIEWS

PostgreSQL (facilities-db) com as seguintes tabelas:

UserNotification:

Id (Guid, PK, auto-generated), UserId (string, required), Subject (string, max 150, required), Body (string, required), IsRead (boolean, default false), CreatedAt (DateTime)

TipsAndNews:

Id (Guid, PK, auto-generated), Category (int, required), Title (string, required), Text (string, required), BackgroundImgUrl (string, nullable), BackgroundColor (string, nullable), Link (string, nullable), UserId (string, nullable), TenantId (string, nullable), CreatedAt (DateTime)

ElectricityCompany:

Id (Guid, PK, auto-generated), DatGeracaoConjuntoDados (DateTime), DatInicioVigencia (DateTime), DatFimVigencia (DateTime), SigNomeAgente (string, required), NumCPFCNPJ (string, required), DscBaseTarifaria (string, nullable), DscSubGrupoTarifario (string, nullable), DscModalidadeTarifaria (string, nullable), DscClasseConsumidor (string, nullable), DscSubClasseConsumidor (string, nullable), DscDetalheConsumidor (string, nullable), DscPostoTarifario (string, nullable), DscUnidade (string, nullable), SigNomeAgenteAcessante (string, nullable), TUSD_FioB (decimal, nullable), TUSD (decimal, nullable), TE (decimal, nullable)

Índices:

Índice único composto em ElectricityCompany para evitar duplicatas baseado em: SigNomeAgente, NumCPFCNPJ, DatInicioVigencia, DatFimVigencia, DscSubGrupoTarifario, DscModalidadeTarifaria, DscClasseConsumidor, DscSubClasseConsumidor, DscDetalheConsumidor, DscPostoTarifario, SigNomeAgenteAcessante

Configuração do Banco:

Servidor: 44.221.102.69:5435, Database: facilities-db, Usuário: user_ms_facilities, Connection string configurável via appsettings

9. CONFIGURAÇÃO E VARIÁVEIS

Configurações principais via appsettings.json:

AllowedHosts:

"*"

AllowedOrigins:

["http://54.235.19.206", "http://aster.app.br", "https://aster.app.br"]

Serilog:

Console output com template customizado, HTTP logging para http://44.221.102.69:5001, File logging em ./logs/facilities_api-.log (rolling daily), Enrichment: MachineName, ProcessId, ThreadId

AwsSettings:

Region: us-east-1, AccessKeyId e AccessKeySecret (configuráveis via variáveis de ambiente)

QueueSettings:

SQSNotificationQueue: "ms-infrastructure-notification-events", SQSFileUploadQueue: "file-upload-queue", WaitTimeSeconds: 10, MaxNumberOfMessages: 10

FileSettings:

FileSizeInMb: 20, S3BucketName: "aster-attachments-prod"

EmailSettings:

Host: smtp.gmail.com, Port: 587, SenderEmail: contato@aster.app.br, SenderName: Aster, EnableSsl: true, Timeout: 30000ms

DatabaseSettings:

Server: 44.221.102.69, Port: 5435, DatabaseName: facilities-db, Username: user_ms_facilities

AneelSettings:

UrlBase: "https://dadosabertos.aneel.gov.br/api/3/action/datastore_search_sql", TableName: "70ac08d1-53fc-4ceb-9c22-3a3a2c70e9fa", TimeoutInSeconds: 600

Configurações do Kestrel:

Porta: 3010, MaxRequestBodySize: 20MB, KeepAliveTimeout: 10 minutos, RequestHeadersTimeout: 10 minutos

10. TREEVIEW DA ARQUITETURA

microservice-facilities/
├── Dockerfile
├── FacilitiesApi.sln
├── README.md
├── Src/
│   ├── Application.DTO/
│   │   ├── Application.DTO.csproj
│   │   ├── DashboardDto.cs
│   │   ├── ElectricityCompanyDTO.cs
│   │   ├── FileUploadRequestDto.cs
│   │   ├── NotificationMessageDto.cs
│   │   ├── TipsAndNewsDto.cs
│   │   └── UserNotificationDto.cs
│   ├── Application.Services/
│   │   ├── Application.Services.csproj
│   │   ├── Interfaces/
│   │   │   ├── IElectricityCompanyService.cs
│   │   │   ├── IFileQueueService.cs
│   │   │   ├── IFileUploadService.cs
│   │   │   ├── INotificationQueueService.cs
│   │   │   ├── INotificationService.cs
│   │   │   ├── ISESEmailService.cs
│   │   │   └── ITipsAndNewsService.cs
│   │   ├── Mappings/
│   │   │   ├── ElectricityCompanyMapping.cs
│   │   │   ├── NotificationMapping.cs
│   │   │   └── TipsAndNewsMapping.cs
│   │   └── Services/
│   │       ├── ElectricityCompanyService.cs
│   │       ├── FileQueueService.cs
│   │       ├── FileUploadService.cs
│   │       ├── NotificationQueueService.cs
│   │       ├── NotificationService.cs
│   │       ├── SESEmailService.cs
│   │       ├── SMTPEmailService.cs
│   │       └── TipsAndNewsService.cs
│   ├── Data.Core/
│   │   ├── AppDbContext.cs
│   │   ├── Data.Core.csproj
│   │   └── Migrations/
│   │       ├── 20240813165519_InitialCreate.cs
│   │       ├── 20240816234017_CreateElectricity.cs
│   │       ├── 20240821103704_ChangeElectricity.cs
│   │       ├── 20240821112911_ChangeElectricityIndex.cs
│   │       └── AppDbContextModelSnapshot.cs
│   ├── Data.Gateway/
│   │   ├── AneelAPI/
│   │   │   ├── AneelApiGateway.cs
│   │   │   ├── AneelApiResponse.cs
│   │   │   └── AneelRecord.cs
│   │   └── Data.Gateway.csproj
│   ├── Data.Repository.PostgreSQL/
│   │   ├── Data.Repository.PostgreSQL.csproj
│   │   ├── ElectricityCompanyRepository.cs
│   │   ├── NotificationRepository.cs
│   │   └── TipsAndNewsRepository.cs
│   ├── Domain.Core/
│   │   ├── Domain.Core.csproj
│   │   ├── IAneelApiGateway.cs
│   │   ├── IElectricityCompanyRepository.cs
│   │   ├── IRepository.cs
│   │   ├── ITipsAndNewsRepository.cs
│   │   └── IUserNotificationRepository.cs
│   ├── Domain.Model/
│   │   ├── Domain.Model.csproj
│   │   ├── ElectricityCompany.cs
│   │   ├── Stats.cs
│   │   ├── TipsAndNews.cs
│   │   └── UserNotification.cs
│   ├── Facilities.Api/
│   │   ├── Controllers/
│   │   │   └── V1/
│   │   │       ├── AttachmentsController.cs
│   │   │       ├── DashboardController.cs
│   │   │       ├── ElectricityCompaniesController.cs
│   │   │       └── UserNotificationsController.cs
│   │   ├── Configurations/
│   │   ├── Exceptions/
│   │   ├── Facilities.Api.csproj
│   │   ├── Program.cs
│   │   ├── appsettings.json
│   │   └── appsettings.Development.json
│   └── Facilities.Crosscutting/
│       ├── Facilities.Crosscutting.csproj
│       ├── Enums/
│       ├── Extensions/
│       ├── Settings/
│       │   └── AppSettings.cs
│       └── Utilities/
└── Tests/
    └── TestFacilitiesApi/
        ├── TestFacilitiesApi.csproj
        └── UnitTest1.cs

11. INTEGRAÇÕES E DEPENDÊNCIAS

Dependências principais:

.NET 8.0, ASP.NET Core Web API, Entity Framework Core com PostgreSQL, Serilog (logging estruturado), Swagger/OpenAPI (documentação), AWS SDK (S3, SES, SQS), HttpClient (integração com API ANEEL), Newtonsoft.Json (serialização), Background Services (processamento assíncrono)

Banco de Dados:

PostgreSQL (principal - facilities-db), AWS S3 (armazenamento - aster-attachments-prod), AWS SES (emails transacionais)

Ferramentas e Infraestrutura:

Docker (containerização), Health Checks (monitoramento), CORS (configuração de origens), Memory Cache (cache em memória), AWS SQS (filas para processamento assíncrono), Kestrel (servidor web)

12. INTEGRAÇÕES EXTERNAS

ANEEL API:

URL: https://dadosabertos.aneel.gov.br/api/3/action/datastore_search_sql, Tabela: 70ac08d1-53fc-4ceb-9c22-3a3a2c70e9fa, Timeout: 600 segundos, Consulta de dados de concessionárias de energia elétrica, Importação de tarifas (TUSD_FioB, TUSD, TE), Filtros por subgrupo tarifário, modalidade, classe de consumidor

AWS S3:

Bucket: aster-attachments-prod, Região: us-east-1, Armazenamento de arquivos enviados, Organização por tenant e estrutura de pastas, Upload assíncrono via fila SQS

AWS SES:

Região: us-east-1, Envio de emails transacionais, Configuração de templates e destinatários, Integração com SMTP como fallback

AWS SQS:

Filas: ms-infrastructure-notification-events, file-upload-queue, Processamento assíncrono de notificações e uploads, Configuração de timeout e número máximo de mensagens

13. CONTROLE DE VERSÃO

• Repositórios hospedados no GitHub
• Versionamento seguindo semântica de releases
• Migrações do Entity Framework para controle de schema
• Docker para containerização e deploy
• Health checks para monitoramento de saúde

14. SEGURANÇA E ACESSO

• Headers obrigatórios: x-user-id, x-tenant-id
• Validação de origens CORS configurável
• Exception handling global com GlobalExceptionHandler
• Logging estruturado para auditoria e monitoramento
• Health checks para monitoramento de saúde do serviço
• Validação de tamanho de arquivo (máximo 20MB)
• Timeout configurável para operações de rede
• Configuração de SSL/TLS para emails

15. CONSIDERAÇÕES FINAIS

Este documento serve como referência única para entendimento técnico do projeto microservice-facilities. O serviço atua como facilitador central para operações comuns do ecossistema Aster/UVA, incluindo:

• Upload assíncrono de arquivos com organização por tenant
• Sistema de notificações personalizadas por usuário
• Integração com API da ANEEL para dados de energia elétrica
• Dashboard centralizado com placeholders dinâmicos
• Processamento assíncrono via filas para melhor performance

O microserviço implementa Clean Architecture com separação clara de responsabilidades, utiliza tecnologias modernas como .NET 8, PostgreSQL, AWS S3/SES/SQS, e possui logging estruturado para facilitar o monitoramento e debugging.

Alterações futuras devem respeitar o fluxo de versionamento e atualização descritos no histórico de revisões, mantendo a compatibilidade com os clientes existentes.