11. Estudo de caso: a aplicação RdvMedecins
11.1. O problema
A aplicação RdvMedecins gerencia as consultas de um consultório médico. Cada médico tem horários (das 8h às 12h, em intervalos de 20 minutos, por exemplo); uma consulta é composta por um dia, um horário e um cliente (um paciente). Trata-se da implementação exata, em [ASP.NET Core MVC], da aplicação [NestJS] da lição anterior: mesmo banco de dados, mesmas regras de negócio, mesmas páginas, mesmos dicionários de tradução. As páginas HTML são geradas pelo servidor por meio de views [Razor].
Três papéis de usuário compartilham a aplicação:
Papel | Quem | O que pode fazer |
ADMIN | O administrador ([admin]) | Ver agendas, fazer e cancelar consultas para qualquer paciente; gerenciar (listar, adicionar, editar, excluir) médicos e clientes |
DOCTOR | Médicos | Ver agendas, fazer consultas e cancelar consultas de qualquer paciente |
USER | clientes (pacientes) | ver agendas sem ver os nomes dos outros pacientes; marcar uma consulta para si mesmos; cancelar sua consulta; gerenciar sua conta; criar uma conta |
Principais regras de gestão:
- nenhuma consulta no passado;
- um horário só pode ser reservado uma vez por dia;
- um paciente só pode ter uma consulta futura por vez;
- dois médicos (ou dois clientes) não podem ter o mesmo nome e sobrenome, e um login pertence a uma única conta;
- um médico com consultas não pode ser excluído; um cliente é excluído junto com suas consultas;
- a página de login é protegida contra bots (CAPTCHA, tentativas limitadas), e a criação de uma conta de cliente exige antes resolver o CAPTCHA dessa página.
11.2. Usando a aplicação
11.2.1. A página de login

A página apresenta dois botões: Log in e Create a patient account. Ambos exigem que você digite os caracteres exibidos na imagem. Os botões FR / EN mudam o idioma:

Um erro (neste caso, um CAPTCHA digitado incorretamente) é exibido na parte inferior da página, sobre um fundo rosa-claro:

11.2.2. A agenda, vista pelo administrador e pelos médicos
Depois de fazer login, o administrador é levado à página da agenda. Ele seleciona um médico e um dia:


Cada horário está disponível (botão Book) ou ocupado (nome do paciente, botão Cancel). Clicar em Book abre uma janela que solicita as informações do paciente:

Clicar em “Cancel” solicita uma confirmação (aqui pelo Dr. Pélissier, cuja barra de navegação não inclui os menus de administração):

11.2.3. O painel do paciente
Um paciente (papel USER) chega a My area: sua consulta futura, que ele pode cancelar, e links para o gerenciamento de sua conta e para a agenda:

Na agenda, ele vê a própria consulta, mas não os nomes dos outros pacientes. Como já tem uma consulta futura, não pode marcar outra:

Um paciente sem consulta pode reservar para si um horário disponível:

Gerenciamento da conta: editar os dados pessoais, alterar a senha ou excluir a conta (e suas consultas). A senha atual é exigida para qualquer alteração:

Um paciente que tenta abrir uma página reservada ao administrador recebe uma página de erro:

11.2.4. Gerenciamento de médicos e clientes
O administrador tem dois menus adicionais, “Doctors” e “Patients”:


O formulário de adição de um médico, enviado com erros:

Um nome que coincide com o de um médico existente é rejeitado:

A exclusão de um cliente exige confirmação:

11.2.5. Criação de uma conta de cliente
A partir da página de login, o botão "Create a patient account" só abre o formulário se o CAPTCHA tiver sido digitado corretamente:


11.3. Instalação e execução
As etapas de instalação foram apresentadas no início deste documento (na seção “Running the Case Study” da introdução): criar o banco de dados usando o script SQL, verificar a string de conexão em [appsettings.json] e, em seguida, executar [dotnet run] na pasta da aplicação. A pasta da aplicação:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 | |
Cada pasta contém um arquivo chamado [README.md] que lista seus arquivos. O console na inicialização:
No modo de desenvolvimento (veja [Properties/launchSettings.json]), o console também exibe cada comando SQL enviado ao banco de dados pelo EF Core. Você também pode:
- iniciar a aplicação com [dotnet watch]: ela é recompilada e reiniciada sempre que um arquivo é modificado;
- executá-la passo a passo no [Visual Studio Code]: com a extensão [C# Dev Kit], a tecla F5 inicia a aplicação sob o controle do depurador; defina um ponto de interrupção com um único clique na margem de uma linha de código.
11.4. A arquitetura da aplicação

- [Program.cs] configura a aplicação: serviços (injeção de dependência), middleware (arquivos estáticos, páginas de erro, idioma, autenticação), controllers;
- [Auth]: conexão, tokens JWT, papéis, CAPTCHA e limites de tentativas;
- [Controllers]: controllers da camada web. Todos passam por um único serviço, [ApplicationModel] (pasta [Web]), que armazena na memória as listas de médicos e clientes e encaminha as demais requisições à camada de negócio;
- [Web]: elementos comuns da camada web: tradução, mensagens flash, validação, classe-mãe das views, filtro de exceções; [Models]: templates de formulários e de views;
- [Business]: regras de negócio;
- [Repositories]: a camada DAO, uma classe por tabela; [Data]: o [DbContext] do EF Core;
- [Entities]: as entidades do EF Core; [Domain]: os objetos da agenda, calculados pela camada de negócio;
- [Views]: as views [Razor]; [i18n]: dicionários; [wwwroot]: a folha de estilo, o script da página e o [Bootstrap].
A sequência comenta todos os arquivos, das camadas inferiores (banco de dados) às camadas superiores (views).
11.5. O banco de dados
O banco de dados [dbrdvmedecins2] é criado pelo script [database/dbrdvmedecins2.sql], que é executado da mesma forma que no Exemplo 28 (a ferramenta [HeidiSQL] do [Laragon], ou o comando [mysql -u root < database/dbrdvmedecins2.sql]). É, palavra por palavra, o script da aplicação [NestJS]: ambas as aplicações podem trabalhar sobre o mesmo banco de dados, e uma pode substituir a outra sem nenhuma alteração.
11.5.1. database/dbrdvmedecins2.sql
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 | |
Vamos percorrer este script:
- Linha 30: o banco de dados é criado se ainda não existir, com o conjunto de caracteres [utf8mb4] e a collation [utf8mb4_unicode_ci], como no Exemplo 28: as comparações de cadeias não distinguem maiúsculas de minúsculas e ignoram acentos. Isso vale também para as restrições de unicidade: [Hélène DUPONT] e [helene dupont] são, para o [MySQL], duas ocorrências da mesma pessoa;
- Linhas 34–38: o script parte de um banco de dados vazio a cada execução. As tabelas são excluídas das tabelas “filhas” para as tabelas “pais”: uma tabela referenciada por uma chave estrangeira ([users], por exemplo, referenciada por [doctors] e [clients]) não pode ser excluída enquanto outra tabela ainda a referenciar. As tabelas são criadas na ordem inversa;
- linhas 43–52: contas de usuário. Cada tabela começa com uma chave primária [id], atribuída pelo banco de dados ([AUTO_INCREMENT]), e uma coluna [version], que é definida como 0 quando a linha é criada;
- linhas 46–49: o login, a senha, o nome de exibição após o login e o papel ([ADMIN], [DOCTOR], ou [USER]). A coluna [password] nunca contém a senha em si, mas seu hash, [bcrypt] (veja o Exemplo 25): 60 caracteres, daí a largura da coluna;
- Linha 51: um login pertence a uma única conta. Como no Exemplo 28, a restrição é nomeada: quando o [MySQL] rejeita uma operação de escrita, sua mensagem de erro indica o nome da restrição violada, e a camada de negócio usa isso para selecionar a mensagem a exibir (veja [Business/BusinessService.cs]);
- linhas 57–69: médicos: título, sobrenome, nome;
- Linha 59: a coluna [version] é usada para o bloqueio otimista (veja o Exemplo 28): ela é incrementada a cada modificação da linha, o que permite detectar se outro usuário modificou a linha entre o momento em que ela foi lida e o momento em que foi gravada. Como no Exemplo 28, a aplicação incrementa esse valor (veja [DbContext], adiante);
- linhas 63–64: cada médico tem uma conta: a coluna [user] é uma chave estrangeira que referencia [users(id)]. O banco de dados rejeita um valor que não se refira a nenhuma conta e se recusa a excluir uma conta que ainda seja referenciada por um médico. Como [user] é uma palavra reservada no [MySQL], o nome da coluna é colocado entre crases;
- linha 66: uma conta pertence a um único médico: a relação entre [doctors] e [users] é uma relação “um para um”;
- linha 68: dois médicos não podem ter o mesmo nome e sobrenome. A restrição se aplica ao par de colunas: dois médicos podem ter o mesmo sobrenome se não tiverem o mesmo nome;
- Linhas 74–86: clientes (pacientes), seguindo o mesmo padrão: uma conta por cliente (chave estrangeira [fk_clients_user], restrição de unicidade [unq_clients_user]); dois clientes não podem ter o mesmo nome e sobrenome;
- linhas 91–100: os horários de cada médico (chave estrangeira [doctor_id]): hora e minuto de início, hora e minuto de término. Um horário não tem data; ele se repete todos os dias;
- linhas 105–115: consultas: uma data (tipo [DATE], sem hora), um horário e um cliente, identificados por duas chaves estrangeiras;
- linha 114: o mesmo horário só pode ser reservado uma vez por dia. O próprio banco de dados impõe essa regra: se dois usuários reservarem o mesmo horário ao mesmo tempo, o segundo [INSERT] é rejeitado, independentemente do que a aplicação tenha verificado imediatamente antes;
- Linhas 127–137: contas de demonstração: o administrador, três médicos (papel [DOCTOR]) e quatro clientes (papel [USER]). A senha de cada usuário é o seu login ([admin] / [admin], [pelissier] / [pelissier]...). Os hashes começam com [$2b$10$]: o algoritmo [bcrypt], com custo 10 (veja o Exemplo 25); a biblioteca [BCrypt.Net-Next] da aplicação sabe verificá-los;
- linhas 141–144: a coluna [user] de cada médico é obtida por meio de uma subconsulta sobre o login, em vez de presumir os identificadores atribuídos pelo banco de dados às contas;
- linhas 146–150: os clientes são tratados da mesma forma;
- linhas 153–157: doze horários de 20 minutos, das 8h às 12h, para o Dr. PELISSIER. Aqui, o ID do médico (1) está fixado no código: a tabela [doctors] acabou de ser criada, portanto seus IDs começam em 1;
- linhas 160–164: doze horários, das 14h às 18h, para o Dr. TATOU. O Dr. DUPONT não tem horários: sua agenda está vazia;
- linhas 167–168: já há uma consulta marcada para Brigitte BISTROU (cliente nº 3) no segundo horário do Dr. PELISSIER (8h20). [CURDATE()] é a data de execução do script: no primeiro login, a agenda de hoje mostra um horário já reservado.
11.6. Configuração do projeto
11.6.1. RdvMedecins.csproj
Vamos percorrer este arquivo:
- linha 12: o SDK para aplicações web, como em todos os exemplos (veja a introdução);
- linhas 14–23: as configurações que os exemplos encontravam no arquivo compartilhado [examples/Directory.Build.props]: [.NET] 10, tipos de referência “nullable”, [using] implícitos. O estudo de caso é um projeto autônomo: ele mesmo escreve esses arquivos. [RootNamespace] é o namespace raiz do projeto, aquele que o [Visual Studio Code] propõe para um novo arquivo;
- linha 29: o provider [MySQL] do EF Core, que inclui o EF Core e o driver [MySqlConnector] (veja o Exemplo 28);
- linhas 31–34: os dois pacotes de autenticação, já usados no Capítulo 8: verificação de tokens JWT e hash de senhas;
- linha 41: os dicionários de tradução [i18n/*.json] são lidos do disco na inicialização. Ao preparar a aplicação para um servidor de produção (comando [dotnet publish]), eles precisam ser copiados junto com ela: é o que [CopyToPublishDirectory] faz;
- linhas 43–44: o script SQL não é um arquivo da aplicação; ele é excluído dos arquivos publicados, como mostrado no Exemplo 28.
11.6.2. appsettings.json
O arquivo [appsettings.json] tem a mesma finalidade do arquivo [.env] da aplicação [NestJS]. Uma diferença importante: o arquivo [.env] nunca era compartilhado, e um arquivo chamado [.env.example] servia de modelo para ele. Aqui, [appsettings.json] faz parte do projeto; valores específicos da máquina (como uma senha) podem ser fornecidos de outra forma, sem modificá-lo (veja adiante).
Vamos percorrer este arquivo:
- linhas 1–9: ao contrário do JSON padrão, o [ASP.NET Core] permite comentários em seus arquivos de configuração;
- linha 13: o endereço e a porta de escuta. Os exemplos escutavam na porta 5000, a porta padrão; a aplicação escuta na porta 8081, como a versão [NestJS];
- linhas 16–18: a string de conexão com o banco de dados [dbrdvmedecins2], usando os valores padrão do [Laragon] (usuário [root], sem senha); veja o Exemplo 28;
- linhas 19–23: a versão do servidor, que informa ao provider [Pomelo] qual dialeto SQL gerar (veja o Exemplo 28);
- linhas 26–36: a seção de autenticação: a chave secreta que assina os tokens (pelo menos 32 caracteres; deve ser substituída em produção), a duração do token (duas horas) e a opção [Secure] do cookie que o transporta. Em produção, o site é servido em HTTPS, e o cookie nunca deve trafegar por uma conexão não criptografada: a opção é definida como [true];
- linhas 39–49: limites de proteção contra bots (veja o Exemplo 27): número de tentativas de login malsucedidas permitidas e duração do bloqueio resultante; número de contas de cliente criadas por hora a partir do mesmo endereço IP;
- linhas 51–57: níveis de log (veja a introdução). As mensagens do EF Core só são exibidas a partir do nível [Warning]: os comandos SQL, que estão no nível [Information], não aparecem (veja o Exemplo 28);
- Linha 58: todos os nomes de domínio são aceitos.
As seções [Auth] e [Protection] são interpretadas como classes tipadas (veja [Config/AuthOptions.cs], adiante). Cada valor é designado por seu caminho, com os níveis separados por [:]: [Auth:JwtSecret], [ConnectionStrings:RdvMedecins], [MySql:ServerVersion]. O [ASP.NET Core] lê a configuração de várias fontes sucessivas, cada uma das quais pode sobrescrever os valores das anteriores: [appsettings.json], depois [appsettings.{environment}.json] (veja o próximo arquivo), depois, em desenvolvimento, os “user secrets” (valores armazenados fora do projeto, no perfil do usuário), depois as variáveis de ambiente e, por fim, os argumentos de linha de comando. Uma senha pode assim ser fornecida por uma variável de ambiente, em que [:] é escrito como [__]:
O arquivo [README.md] da aplicação detalha essas opções.
11.6.3. appsettings.Development.json
- Linha 10: o [ASP.NET Core] conhece o ambiente em que a aplicação está sendo executada: [Development], [Production]... Ele o lê da variável de ambiente [ASPNETCORE_ENVIRONMENT] (veja o arquivo seguinte); caso contrário, usa [Production]. Depois de [appsettings.json], ele lê o arquivo [appsettings.{environment}.json], se existir, e mescla os dois: as chaves presentes no segundo arquivo substituem as do primeiro, enquanto as demais são mantidas. Durante o desenvolvimento, adicionamos portanto o nível [Information] para a categoria [Microsoft.EntityFrameworkCore.Database.Command]: a regra mais específica prevalece sobre a mais geral do [appsettings.json] ([Warning] para todo o [Microsoft.EntityFrameworkCore]), e cada comando SQL enviado ao banco de dados é exibido no console. Isso equivale à opção [logging] do [TypeORM], que a versão [NestJS] habilitava fora de produção. Todos os demais valores (conexão, autenticação etc.) permanecem iguais aos do [appsettings.json].
11.6.4. Properties/launchSettings.json
Este arquivo é usado apenas durante o desenvolvimento pelo [dotnet run], pelo [dotnet watch] e pelo [Visual Studio Code]; ele não é publicado. Vamos comentá-lo:
- linhas 3–4: um perfil de inicialização descreve uma forma de iniciar a aplicação. Há apenas um aqui; o [dotnet run] usa o primeiro;
- linha 5: a aplicação é iniciada diretamente, com seu próprio servidor web;
- linhas 6–7: o [dotnet run] exibe suas mensagens de compilação, e o navegador abre a aplicação quando ela está pronta;
- linha 8: o endereço de escuta, o mesmo da chave [Urls] do arquivo [appsettings.json]. Quando iniciada por este perfil, a aplicação usa este endereço; quando iniciada fora do perfil (por exemplo, depois de publicada), ela usa o endereço do arquivo [appsettings.json];
- Linhas 9–10: as variáveis de ambiente passadas à aplicação. [ASPNETCORE_ENVIRONMENT=Development] define o ambiente: [appsettings.Development.json] é lido, e os comandos SQL são exibidos. Em um servidor de produção, sem este arquivo nem esta variável, o ambiente é [Production].
11.6.5. Config/AuthOptions.cs
Vamos comentar este código:
- linha 15: a seção [Auth] do [appsettings.json], na forma de uma classe comum: uma propriedade por chave, com o mesmo nome. Este é o padrão de opções ([options pattern]) do [ASP.NET Core]. No [Program.cs], [Configure<AuthOptions>(...)] vincula a seção à classe: o framework cria um objeto [AuthOptions] e preenche suas propriedades com os valores da seção, convertendo-os para o tipo correto (["7200"] torna-se o inteiro 7200, [false] torna-se o booleano [false]). Uma classe que precisa dele o recebe por injeção de dependência, na forma de um
***[IOptions<AuthOptions>], cuja propriedade***[Value]é o objeto preenchido: é o que faz o [Auth/AuthService.cs], com seu parâmetro [IOptions<AuthOptions> options] e seu campo [auth = options.Value]. Isso evita ter de ler cadeias de caracteres por toda parte, como fazia [process.env.JWT_SECRET] na versão [NestJS]: os nomes das chaves são verificados pelo compilador, e os valores já vêm convertidos; - linha 17: o nome da seção, escrito uma única vez;
- Linhas 21–29: os três valores desta seção. Os valores padrão ([7200], [false] para um booleano) são os usados caso a chave esteja ausente da configuração.
11.6.6. Config/ProtectionOptions.cs
- Linhas 10–25: a seção [Protection] do [appsettings.json], seguindo o mesmo padrão. Ela é injetada, na forma de um [IOptions<ProtectionOptions>], no [Auth/AttemptLimiterService.cs], que lê dela seus limites.
11.7. Inicialização da aplicação
11.7.1. Program.cs
O arquivo [Program.cs] exerce tanto o papel do [main.ts] (inicialização, middleware) quanto o do [app.module.ts] (qual serviço fornece o quê) da versão [NestJS]. Ele segue a estrutura de todos os exemplos: primeiro registrar os serviços, depois montar o pipeline de middleware. Vamos analisá-lo por seções.
11.7.1.1. A configuração
- linhas 21–31: os namespaces usados, além dos [using] implícitos: os do framework (localização, EF Core, codificação de HTML) e os da aplicação, um por pasta;
- linha 33: o construtor da aplicação, como em todos os exemplos. Ele já leu a configuração ([appsettings.json], [appsettings.Development.json], variáveis de ambiente...), acessível por meio de [builder.Configuration];
- Linhas 40–41: o padrão de opções (veja [Config/AuthOptions.cs]): cada seção é vinculada à sua classe. [GetSection("Auth")] designa a seção; [Configure<T>] registra o serviço [IOptions<T>] correspondente, que os serviços de autenticação receberão por injeção;
- Linha 42: a mesma seção, desta vez lida diretamente como um objeto ([Get<AuthOptions>()]), ou um objeto com valores padrão se a seção estiver ausente. A configuração do [JwtBearer] (adiante) precisa da chave secreta agora, durante o registro dos serviços: neste momento, o contêiner de injeção de dependência ainda não foi construído, e nenhum [IOptions<AuthOptions>] pode ser injetado.
11.7.1.2. O banco de dados e as camadas DAO e de negócio
- Linhas 4–5: a string de conexão, como no Exemplo 28. O operador [??] retorna o valor da esquerda se ele não for [null]; caso contrário, retorna o valor da direita: se a chave estiver ausente, a aplicação para imediatamente, exibindo uma mensagem que indica o que está faltando, em vez de retornar um erro obscuro na primeira requisição;
- linha 6: a versão do servidor [MySQL], com um valor padrão se a chave estiver ausente;
- linha 7: o [DbContext] da aplicação (veja [Data/RdvMedecinsDbContext.cs]), um por requisição ([Scoped]), com o provider [MySQL] (veja o Exemplo 28);
- Linhas 11–15: a camada DAO: uma classe por tabela (exceto [users], cujo repositório é usado para a autenticação). Ela é [Scoped], assim como o [DbContext] que utiliza. Um serviço nunca deve viver mais do que suas dependências: um DAO [Singleton] reteria indefinidamente o [DbContext] da primeira requisição, embora ele seja destruído ao final dessa requisição (veja o Capítulo 6);
- Linha 19: a camada de negócio. [AddScoped<IBusiness, BusinessService>()] lê-se: “quando um serviço solicitar um [IBusiness], forneça-lhe um [BusinessService].” Quem usa a camada de negócio depende da interface, não da classe: poderíamos substituir a implementação (por uma versão de teste, por exemplo) modificando apenas esta linha. A versão [NestJS] exigia um token ([BUSINESS_TOKEN]) para isso, já que as interfaces do [TypeScript] desaparecem em tempo de compilação; em [C#], a própria interface serve de token;
- Linhas 22–23: o cache da camada web (as listas de médicos e clientes) tem escopo de aplicação: [Singleton], uma única instância compartilhada por todas as requisições (veja o Exemplo 23). Sua fachada, [ApplicationModel], pela qual passam todos os controllers, usa a camada de negócio: ela é portanto [Scoped]. O cache em si, que é independente de qualquer outra coisa, pode viver mais do que a fachada.
11.7.1.3. Autenticação, tradução e codificação HTML
- linha 2: o serviço de login (verificação do nome de usuário e da senha, geração do token; veja o Exemplo 25). Ele usa o repositório de contas: é [Scoped];
- Linhas 3–5: CAPTCHAs pendentes, contadores de falhas e códigos de criação de conta (veja o Exemplo 27). Esses dados são mantidos na memória e devem ser os mesmos para todas as requisições: os três serviços são [Singleton]. A desvantagem: eles são perdidos a cada reinicialização do servidor;
- linha 6: a configuração do [JwtBearer] (token lido do cookie, redirecionamento para a página de login...), como mostrado no Exemplo 25. Ela fica em um método de extensão de [IServiceCollection] (veja [Auth/JwtAuthentication.cs]), que é chamado como um método do framework e assim alivia o [Program.cs];
- linha 7: os serviços de autorização, usados por [[Authorize]] e pelo middleware [UseAuthorization];
- linha 10: o serviço de tradução, que lê os dicionários uma única vez (veja o Exemplo 22);
- linha 16: o codificador de HTML do [Razor] deixa passar caracteres de todos os idiomas, como no Exemplo 15.
11.7.1.4. MVC e suas opções
- linha 2: os controllers e as views [Razor]. A função passada como parâmetro define as opções do MVC;
- linha 5: um filtro de exceção global (veja o Exemplo 24), que se aplica a todas as ações. Ele trata apenas um caso: uma [InvalidSessionException] (o token é válido, mas a conta a que ele se refere foi excluída desde então) leva à página de login. As demais exceções seguem seu caminho até o middleware [UseExceptionHandler] (adiante);
- linha 10: uma armadilha dos tipos “nullable”. Quando habilitados, o MVC trata uma propriedade [string] (não anulável) de um modelo como obrigatória, exatamente como se ela tivesse o atributo [[Required]], com uma mensagem de erro em inglês que não queremos. Esta opção remove esse comportamento padrão: um campo só é obrigatório se tiver explicitamente o atributo [[Required]], com nossa própria mensagem (veja [Models/Forms.cs]);
- Linhas 14–25: mensagens de erro de binding (veja o Exemplo 19): texto onde se espera um número ([version=abc]), um valor ausente... O Exemplo 19 redefiniu apenas duas delas, em inglês; o estudo de caso redefine todas, e cada uma retorna a mesma chave de tradução, [ERRORS.INVALID_FORM], em vez de um texto: a mensagem é traduzida no momento da exibição, no idioma do usuário. O caractere [_] refere-se a um parâmetro não utilizado (o nome do campo, o valor digitado): a mensagem é a mesma qualquer que seja o campo. Esses erros nunca deveriam ocorrer com os formulários da aplicação: eles indicam uma requisição construída manualmente.
11.7.1.5. Carregamento do cache
- Linha 1: construção da aplicação. O contêiner de injeção de dependência agora foi criado: não é mais possível registrar serviços, mas é possível obtê-los;
- Linhas 9–12: as listas de médicos e clientes são carregadas no cache antes de o servidor começar a escutar. [ApplicationModel] é um serviço [Scoped]: ele só pode ser criado dentro de um escopo, e fora de uma requisição não há escopo. [CreateScope()] cria um; [GetRequiredService<ApplicationModel>()] obtém o serviço a partir dele (junto com a camada de negócio, os repositórios e o [DbContext] dos quais ele depende), e [LoadAsync()] preenche o cache, que é um [Singleton] e, portanto, sobrevive ao escopo. A instrução [using] destrói o escopo, e o [DbContext] junto com ele, quando o bloco termina. Se o banco de dados estiver inacessível, a exceção do EF Core não é capturada: a aplicação termina, com uma mensagem de erro exibida no console. Este é o primeiro sinal de uma string de conexão incorreta ou de um servidor [MySQL] parado.
11.7.1.6. O pipeline de middleware
Cada requisição passa pelos componentes de middleware na ordem em que eles são declarados (veja o Capítulo 7): essa ordem é, portanto, importante.
- Linha 8: o primeiro middleware envolve todos os outros. Se uma exceção não foi tratada por ninguém (um erro de programação, um banco de dados que se tornou inacessível etc.), ele registra a exceção em log e reexecuta a requisição com o endereço [/error/500]: o usuário vê uma página de erro da aplicação, e não uma mensagem técnica (veja o Capítulo 7);
- Linha 9: uma resposta de erro vazia (400, 403, 404) é convertida em uma página da mesma forma, por meio da ação [/error/{code}] do controller [ErrorController] (veja os Exemplos 24 e 26). A requisição reexecutada passa novamente pelos middlewares seguintes: a página de erro é, portanto, renderizada e reconhece o usuário conectado;
- linha 12: os arquivos estáticos da pasta [wwwroot] (veja o Exemplo 15): a folha de estilo, o script da página e o [Bootstrap], armazenado aqui em [wwwroot/lib/bootstrap]. Colocado no início do pipeline, esse middleware responde às requisições de arquivos sem fazê-las passar pelo roteamento, pela localização ou pela autenticação;
- linhas 17–23: a configuração de localização, como no Exemplo 22. Os idiomas suportados e o idioma padrão são os do serviço de tradução ([Translator.Languages], [Translator.DefaultLanguage]): eles são definidos em um único lugar;
- linha 25: somente o cookie definido pelo [LanguageController] determina o idioma (veja o Exemplo 22). A sintaxe [[...]] é uma expressão de coleção: neste caso, uma lista com um único elemento;
- linha 26: o middleware de localização, que define o idioma de cada requisição;
- linhas 30–32: roteamento, seguido de autenticação, seguida de autorização. O roteamento seleciona a ação que tratará a requisição, com base nas rotas declaradas por atributos. Os exemplos não o chamavam: o [WebApplication] o adiciona, portanto, automaticamente no início do pipeline. Chamá-lo explicitamente torna a ordem visível: a autorização deve vir depois do roteamento, porque é a ação selecionada que carrega o atributo [[Authorize]] a ser verificado; e depois da autenticação, que determina, com base no token, quem é o usuário (veja o Exemplo 25);
- linha 35: os controllers e suas rotas, declaradas por atributos ([[Route("schedule")]]...);
- linha 37: o servidor inicia e aguarda requisições na porta 8081.
11.8. As entidades
As entidades do EF Core correspondem às tabelas do banco de dados e às classes [C#] (veja o Exemplo 28). Elas replicam, uma a uma, as entidades do [TypeORM] da versão [NestJS]: os atributos [[Table]], [[Column]], [[Key]], [[ForeignKey]] fazem o papel dos decoradores [@Entity], [@Column], [@PrimaryGeneratedColumn] e [@JoinColumn]. O banco de dados não é criado pelo EF Core, mas pelo script SQL [database/dbrdvmedecins2.sql]: as entidades só precisam descrever com exatidão as tabelas que já existem.
11.8.1. Entities/AbstractEntity.cs
- linha 23: uma classe abstrata sem o atributo [[Table]]: ela não corresponde a nenhuma tabela, mas suas propriedades são adicionadas às das tabelas de suas classes filhas. Todas as entidades da aplicação herdam dela e, portanto, têm um identificador e uma versão;
- Linhas 28–30: a chave primária ([[Key]]), coluna [id]. Por convenção no EF Core, uma chave inteira é gerada pelo banco de dados ([AUTO_INCREMENT]): o EF Core relê seu valor após cada [INSERT];
- Linhas 40–42: a versão da linha para o bloqueio otimista (veja o Exemplo 28). [[ConcurrencyCheck]] adiciona a condição [AND version = <value read>] a cada [UPDATE]. Ao contrário do [@VersionColumn] do [TypeORM], o EF Core não incrementa a versão por conta própria: o [DbContext] cuida disso (veja adiante).
11.8.2. Entities/Person.cs
- Linha 17: a classe-mãe, também abstrata, de [Doctor] e [Client], ela própria filha de [AbstractEntity]. Médicos e clientes têm as mesmas colunas: elas são definidas uma única vez;
- Linhas 19–29: o título (Mme, Mr, Melle), o sobrenome e o nome. [[MaxLength]] especifica a largura da coluna. Essas propriedades são do tipo [string] (e não [string?]): elas nunca devem ser definidas como [null], e o compilador exige, portanto, um valor inicial, neste caso a cadeia vazia [""];
- linhas 42–43: a chave estrangeira para a conta de usuário, coluna [user]. O ID da conta pode ser lido sem carregar a própria conta: é o que [@RelationId] fazia na versão [NestJS];
- linhas 47–48: a propriedade de navegação: o próprio objeto [User]. [[ForeignKey(nameof(UserId))]] indica qual propriedade contém a chave estrangeira ([nameof(UserId)] é igual à cadeia ["UserId"], mas o compilador verifica que a propriedade existe). Uma propriedade de navegação só é preenchida se a consulta o solicitar ([Include]; veja a camada DAO); caso contrário, ela é definida como [null]. A notação [= null!] suprime o aviso do compilador: ela garante que a propriedade só será lida depois de carregada. A natureza “um para um” da relação é especificada no [DbContext]. Uma relação declarada em uma classe-mãe é herdada, assim como as colunas: as tabelas [doctors] e [clients] têm, cada uma, sua própria relação com [users].
11.8.3. Entities/Doctor.cs
- Linha 15: a classe [Doctor] corresponde à tabela [doctors]. Ela herda todas as suas propriedades de [Person]. A restrição de unicidade [unq_doctors_first_name_last_name], mencionada no comentário, é criada pelo script SQL; a camada de negócio a reconhece pelo nome (veja o Exemplo 28);
- linha 21: a relação inversa da de [Slot] para seu médico: os horários de atendimento deste médico. O EF Core associa automaticamente as duas navegações ([Doctor.Slots] e [Slot.Doctor]), que descrevem a mesma relação “um médico, vários horários” vista de cada lado. Como qualquer navegação, ela só é preenchida sob demanda; a aplicação, na verdade, não a usa: ela lê os horários pela camada DAO. [[]] é uma expressão de coleção: neste caso, uma lista vazia.
11.8.4. Entities/Client.cs
Um cliente, isto é, um paciente do consultório (não um cliente HTTP): uma [Person] da tabela [clients] (linha 15), sem propriedades adicionais.
11.8.5. Entities/Slot.cs
- linhas 14–17: a hora e o minuto de início e de término do horário. O atributo e a propriedade são escritos na mesma linha: isso é permitido e mais compacto para essas quatro colunas semelhantes;
- Linhas 21–25: a relação “muitos para um” com o médico: vários horários para um médico. Mesma técnica de [Person]: a chave estrangeira [DoctorId] (coluna [doctor_id]) e a propriedade de navegação [Doctor], vinculadas por [[ForeignKey]]. O EF Core não exige mais nenhum esclarecimento: uma referência de um lado, uma lista do outro: esta é uma relação “um para muitos”.
11.8.6. Entities/Appointment.cs
- Linha 15: a tabela de consultas. Sua restrição de unicidade [unq1_appointments (day, slot_id)] garante que um horário seja reservado apenas uma vez por dia;
- Linhas 22–23: o dia da consulta. O tipo [DateOnly] (uma data sem hora) corresponde exatamente ao tipo SQL [DATE]: sem hora, portanto sem problemas de fuso horário. A versão [NestJS] manipulava uma cadeia do tipo [yyyy-mm-dd], já que não existia um tipo equivalente em [JavaScript]. Dois valores [DateOnly] são comparados diretamente com [<], [>=]..., tanto em [C#] quanto nas consultas [LINQ];
- Linhas 25–35: o cliente e o horário da consulta: duas relações “muitos para um”, cada uma definida com uma chave estrangeira e uma navegação. Para criar uma consulta, basta preencher as chaves estrangeiras [ClientId] e [SlotId]: é o que faz a camada de negócio.
11.8.7. Entities/Role.cs
- linhas 17–21: os três papéis, na forma de uma enumeração ([enum]): uma variável do tipo [Role] só pode assumir os valores [Role.ADMIN], [Role.DOCTOR] ou [Role.USER], e o compilador rejeita qualquer outro valor. Isso equivale ao tipo união de cadeias ['ADMIN' | 'DOCTOR' | 'USER'] da versão [NestJS]. Por padrão, o EF Core armazenaria uma enumeração de base como um número (0, 1, 2); a coluna [role] contém texto: a conversão é solicitada no [DbContext].
11.8.8. Entities/User.cs
- Linha 18: as contas dos usuários autorizados a fazer login: o administrador, cada médico e cada cliente. A restrição [unq_users_login] proíbe duas contas com o mesmo login;
- Linhas 21–23: o nome de usuário;
- linhas 26–28: o hash [bcrypt] da senha, nunca a senha em si (veja o exemplo 25);
- linhas 32–34: o nome exibido na barra de navegação depois do login (“Marie PELISSIER”);
- linhas 37–38: o papel, do tipo [Role]. Como a classe [User] não declara uma navegação para o médico ou cliente que a possui, a relação é conhecida apenas do lado de [Person].
11.9. O DbContext
O [DbContext] da aplicação é baseado no do Exemplo 28, com cinco tabelas em vez de uma e alguns esclarecimentos sobre o modelo que os atributos não conseguem expressar.
11.9.1. Data/RdvMedecinsDbContext.cs
Vamos comentar este código:
- linha 29: como no Exemplo 28, o [DbContext] recebe suas opções ([MySQL] provider, string de conexão) de [AddDbContext], dentro de [Program.cs]. Ele é registrado com o tempo de vida [Scoped]: um [DbContext] por requisição, compartilhado por todos os repositórios dessa requisição, o que significa uma única conexão e, se for o caso, uma única transação. Ele cumpre assim os papéis do [DataSource] e do [Repository<T>] do [TypeORM];
- linhas 33–37: um [DbSet] por tabela. Não há nenhum para [AbstractEntity] nem para [Person]: essas classes abstratas não têm tabelas. O EF Core não as inclui no modelo como entidades; ele apenas soma suas propriedades às das classes filhas;
- linha 39: [OnModelCreating] é chamado uma única vez, quando o EF Core constrói seu modelo (a descrição das tabelas e dos relacionamentos). Ele complementa os atributos das entidades com uma API fluente: uma cadeia de chamadas de método;
- linhas 47–48: o relacionamento entre um médico (um cliente) e sua conta é “um para um”: [HasOne(d => d.User)] (um médico tem uma conta), [WithOne()] (uma conta tem no máximo um médico; os parênteses vazios indicam que [User] não tem navegação inversa), [HasForeignKey<Doctor>(d => d.UserId)] (a chave estrangeira está na tabela [doctors]). Sem essas linhas, o EF Core presumiria um relacionamento “muitos para um” (vários médicos para uma única conta), que também funcionaria, mas descreveria o modelo de forma imprecisa: no banco de dados, a coluna [user] é única;
- linha 52: [HasConversion<string>()] armazena o papel no banco de dados como texto (['ADMIN']...) e o converte de volta para [Role] na leitura;
- linhas 68–77: o número de versão de cada entidade modificada é incrementado logo antes da gravação, como no Exemplo 28. [ChangeTracker.Entries<AbstractEntity>()] percorre todas as entidades rastreadas cuja classe deriva de [AbstractEntity]: graças à classe-pai comum, esse único laço se aplica às cinco tabelas. A variante de [SaveChangesAsync] é redefinida com dois parâmetros, porque é essa variante que, em última instância, chama [SaveChangesAsync()] sem parâmetros. O EF Core compara a versão antiga na cláusula [WHERE] do [UPDATE] e grava a nova: se a linha mudou nesse meio-tempo, nenhuma linha é modificada e o EF Core lança uma [DbUpdateConcurrencyException].
11.10. O domínio: a agenda
A pasta [Domain] contém duas classes que não correspondem a nenhuma tabela: elas descrevem a agenda de um médico em um único dia, calculada pela camada de negócio ([BusinessService.GetDoctorDayScheduleAsync]) e exibida pelo controller da agenda.
11.10.1. Domain/DoctorDaySlot.cs
- Linha 17: um horário e a consulta marcada para esse horário nesse dia, [null] se o horário estiver livre (daí o tipo [Appointment?]). Um [record] escrito dessa maneira, com seus parâmetros entre parênteses (record posicional), declara em uma única linha uma classe, seu construtor e suas propriedades [Slot] e [Appointment], que não podem ser modificadas após a construção: isso equivale à sintaxe [constructor(public slot: Slot, ...)] da versão [NestJS]. Já encontramos os records para os dados passados à camada de negócio (veja o Exemplo 28).
11.10.2. Domain/DoctorDaySchedule.cs
A agenda (linha 14): um médico, um dia e a lista de seus horários livres ou ocupados, em ordem cronológica.
11.11. A camada DAO
Uma classe por tabela, como no Exemplo 28: métodos curtos, sem lógica de negócio, que apenas consultam ou modificam o banco de dados. Aqui, elas são chamadas de “repositórios”, como na versão [NestJS]. Duas diferenças em relação a essa versão:
- as consultas são escritas em [LINQ], que o EF Core traduz para SQL: você navega de uma entidade para outra por meio de propriedades de navegação, e o próprio EF Core escreve os joins;
- os métodos não têm parâmetro [manager] para transações: todos os repositórios de uma requisição compartilham o mesmo [DbContext], e uma transação aberta nesse [DbContext] pela camada de negócio abrange automaticamente todas as suas consultas.
Todos os métodos são assíncronos e retornam uma [Task]: o chamador a aguarda com [await]. Muitos são escritos na forma [=> expression]: eles retornam diretamente a [Task] da consulta, sem [async] ou [await], já que não têm mais nada a fazer depois.
11.11.1. Repositories/PersonRepository.cs
Na versão [NestJS], os repositórios de médicos e de clientes eram idênticos, exceto por uma única linha. Em [C#], uma classe genérica os escreve uma só vez.
Vamos comentar este código:
- Linha 24: [PersonRepository<T>] é uma classe genérica; [T] é um parâmetro de tipo, substituído por um tipo real ([Doctor] ou [Client]) quando a classe é usada, como o [T] em [List<T>]. A restrição [where T : Person] aceita apenas [Person] ou suas classes filhas para [T]: o compilador passa então a saber que um [T] contém [Id], [LastName], [FirstName], [UserId], [User]... e aceita [p.LastName] nas consultas. A classe é abstrata: apenas suas duas classes filhas, listadas a seguir, são usadas;
- linha 26: o parâmetro [db] do construtor principal é visível apenas dentro desta classe. Ele é copiado para um campo [protected] para que as classes filhas ([ClientRepository]) possam acessá-lo;
- linha 29: a tabela de pessoas do tipo [T]. [db.Set<T>()] associa [DbSet] a este tipo: [db.Doctors] para [T = Doctor], [db.Clients] para [T = Client];
- linhas 38–39: todas as pessoas, ordenadas por sobrenome e depois por nome ([OrderBy], depois [ThenBy] para desempatar sobrenomes idênticos). [Include(p => p.User)] também carrega a conta de cada pessoa por meio de um join ([INNER JOIN users]): sem ele, [p.User] seria equivalente a [null]. A conta é usada para exibir o login nas listas. [AsNoTracking()] (veja o Exemplo 28): essas listas são mantidas na memória pelo [ApplicationModel] muito tempo depois do término da consulta; não há necessidade de o [DbContext] processá-las. Expressões como [p => p.LastName] não são executadas em [C#]: o EF Core as analisa para traduzi-las em SQL ([ORDER BY last_name, first_name]);
- linhas 41–42: uma pessoa e sua conta, ou [null]. Aqui, não há [AsNoTracking()]: a camada de negócio modifica a pessoa recuperada (e sua conta) e depois chama [SaveAsync]; o [DbContext], que rastreia os dois objetos, sabe o que mudou;
- linhas 45–46: a pessoa cuja conta é [userId]. É assim que um paciente logado, cujo token contém o ID da conta, recupera seu registro de cliente. O filtro age sobre a própria chave estrangeira ([WHERE clients.user = ...]); o join com [users] serve apenas para carregar a conta ([Include]);
- linhas 52–53: um possível homônimo. O operador [==] é convertido no [=] do SQL: a comparação é feita pelo [MySQL], de acordo com a collation do banco de dados, sem distinguir maiúsculas nem acentos, exatamente como na restrição de unicidade (veja o Exemplo 28). Uma comparação feita em [C#] levaria as maiúsculas em conta;
- linhas 57–64: criação ou modificação, como no Exemplo 28: uma nova pessoa ([Id] igual a 0) é adicionada ao [DbSet]; uma pessoa já existente não requer nenhuma ação. Observe: [SaveChangesAsync] grava todas as alterações pendentes do [DbContext], e não apenas as de [person]: a conta modificada ao mesmo tempo é incluída na mesma chamada;
- linha 69: exclusão via [ExecuteDeleteAsync] (veja o Exemplo 28): um [DELETE] enviado diretamente ao banco de dados, sem leitura prévia. Ele não passa pelo rastreamento de alterações e, portanto, tampouco pelo bloqueio otimista;
- linha 73: o repositório dos médicos: [PersonRepository<Doctor>], sem nada além disso. Ele repassa o [DbContext] recebido ao construtor de sua classe-pai; o ponto e vírgula final substitui um corpo de classe vazio;
- linha 75: o repositório dos clientes, com um método adicional;
- linhas 89–92: leitura de um cliente com um bloqueio: [SELECT ... FOR UPDATE] coloca um bloqueio na linha até o fim da transação atual; outra transação que peça o mesmo bloqueio espera até que a primeira termine. O método de agendamento de consultas ([BusinessService.AddAppointmentAsync]) usa isso para processar, uma após a outra, duas reservas simultâneas para o mesmo paciente: a segunda reserva enxerga a consulta criada pela primeira e, assim, respeita a regra “apenas uma consulta futura”. [LINQ] não consegue expressar [FOR UPDATE]: é preciso escrever você mesmo o SQL da consulta usando [FromSqlInterpolated]. A string [$"..."] é uma string interpolada; [FromSqlInterpolated] não a copia como está: cada valor entre chaves ([{id}]) torna-se um parâmetro SQL. Portanto, não há concatenação de strings e nenhuma injeção de SQL é possível. A consulta é executada como está ([ToListAsync]), e o primeiro cliente da lista resultante é obtido ([FirstOrDefault], em memória): um operador [LINQ] adicionado após [FromSqlInterpolated] faria o EF Core envolver nosso SQL em uma subconsulta.
11.11.2. Repositories/SlotRepository.cs
- linhas 15–16: um horário de consulta, com seu médico ([Include]);
- linhas 19–24: os horários de um médico, em ordem cronológica: [Where] filtra, [OrderBy] e [ThenBy] ordenam (por hora e depois por minuto de início). A consulta é construída método a método, como com o QueryBuilder do [TypeORM], e só é executada quando [ToListAsync] é chamado: [SELECT ... FROM slots WHERE doctor_id = @p ORDER BY start_hour, start_minute]. O valor [doctorId] também é passado como parâmetro ao SQL;
- linhas 28–29: exclusão dos horários de um médico com um único [DELETE]. A camada de negócio o chama antes de excluir o médico; caso contrário, a chave estrangeira [slots.doctor_id] impediria a exclusão.
11.11.3. Repositories/AppointmentRepository.cs
Vamos comentar este código:
- linhas 19–20: uma consulta com seu cliente e seu horário: dois registros [Include], portanto dois joins;
- linhas 22–29: mesmo padrão que o das pessoas. Na prática, é usado apenas para criação: a camada de negócio gera um [Appointment] no qual apenas as chaves estrangeiras estão preenchidas; após [SaveChangesAsync], [appointment.Id] contém o identificador atribuído pelo banco de dados;
- linha 32: cancelamento de uma consulta;
- linhas 37–42: as consultas de um médico em um determinado dia, cada uma com seu paciente e seu horário (o equivalente a [leftJoinAndSelect] na versão [NestJS]). A tabela [appointments] não referencia diretamente os médicos: o filtro [a.Slot.DoctorId == doctorId] passa pela navegação [Slot], e o EF Core adiciona o join com [slots]. É importante distinguir os dois usos de uma navegação: em [Where], ela serve para filtrar; apenas [Include] carrega o objeto no resultado;
- linhas 47–54: as consultas de um cliente a partir do dia [fromDay], junto com seu horário e o médico desse horário: [Include(a => a.Slot)] carrega o horário e, em seguida, [ThenInclude(s => s.Doctor)] carrega o médico desse horário (dois joins em cascata). A ordenação é feita primeiro pelo dia e depois pela hora do horário. É isso que é exibido em “Minha área”;
- linhas 57–58: o número dessas consultas ([SELECT COUNT(*)]), para a regra “apenas uma consulta futura”. [CountAsync] aceita diretamente a condição, assim como [FirstOrDefaultAsync];
- linhas 62–63: a exclusão de todas as consultas de um cliente, passadas e futuras: a camada de negócio a chama antes de excluir o cliente, o que a chave estrangeira [appointments.client_id] caso contrário protegeria;
- linhas 67–68: o número de consultas de um médico, para impedir a exclusão de um médico que tenha alguma. Mais uma vez, a navegação [a.Slot] gera um join ([INNER JOIN slots]) sem carregar nada: este é o [innerJoin] da versão [NestJS].
11.11.4. Repositories/UserRepository.cs
- linha 17: a conta associada a este login, ou [null]. Ela é usada para o login ([AuthService]) e para verificar se um login está disponível antes de atribuí-lo;
- Linhas 19–26: criação ou modificação de uma conta. Para criar um médico ou um cliente, é preciso primeiro criar sua conta: a pessoa precisa do ID da conta para sua chave estrangeira;
- linha 29: exclusão de uma conta. A ordem é inversa à da criação: a camada de negócio exclui primeiro a pessoa, que referencia a conta, e depois exclui a conta.
11.12. A camada de negócio
A camada de negócio contém as regras de negócio da aplicação: nenhuma consulta no passado, apenas uma consulta futura por paciente, logins e pessoas únicos, e a exclusão de um médico ou de um cliente. Ela se apoia na camada DAO (pasta [Repositories]) para leitura e gravação, e não sabe nada sobre HTML nem sobre o idioma da interface. Mais especificamente, esta é a camada [PersonsBusiness] do Exemplo 28.
11.12.1. Business/Dates.cs
- linha 11: uma classe [static] não é instanciada; ela apenas agrupa métodos, que são chamados pelo nome da classe ([Dates.Today()]);
- linha 14: a data de hoje, no fuso horário do servidor. [DateTime.Now] retorna data e hora; [DateOnly.FromDateTime] retorna apenas a data (o tipo [DateOnly] foi abordado no Exemplo 12; este é o formato da coluna [appointments.day]). Dois [DateOnly] valores podem ser comparados diretamente com [<] ou [>=]; a versão [NestJS], que processava strings [yyyy-mm-dd], precisava gerar esse formato por conta própria. A data atual é usada nas regras de negócio e, por isso, reside na camada de negócio; a camada web a reutiliza (por exemplo, em [ScheduleController], para determinar se um dia ainda pode ser reservado).
11.12.2. Business/BusinessException.cs
- Linha 18: a exceção lançada quando uma regra de negócio rejeita uma transação (veja o Exemplo 28). A classe usa um construtor primário (os parâmetros [key] e [messageParams] são listados após o nome da classe); [: Exception(key)] passa a chave ao construtor da classe-pai [Exception], que a define como a propriedade [Message] (útil nos logs de erro). Diferença em relação ao Exemplo 28: a exceção não carrega um texto em inglês, mas sim uma chave de tradução ([ERRORS.LOGIN_TAKEN]). A camada de negócio ignora, assim, o idioma da interface: é a camada web que traduzirá a chave, usando os dicionários [i18n/fr.json] e [i18n/en.json] (veja o Capítulo 5);
- linha 21: a chave de tradução, somente leitura ([get] sem [set]);
- linha 24: os eventuais parâmetros da mensagem, que substituirão marcadores como [{minutes}] no texto traduzido. [IReadOnlyDictionary] é um dicionário somente leitura. O operador [??] retorna um dicionário vazio quando nenhum parâmetro é fornecido: a camada web nunca precisa verificar [null]. As exceções lançadas pelo [BusinessService] na verdade só usam chaves sem parâmetros.
Uma [BusinessException] não é um erro: é uma resposta normal (“este login já está em uso”), que os controllers interceptam para exibir ao usuário, seja na página, seja em uma mensagem pop-up. Qualquer outra exceção é um erro verdadeiro, que resulta em uma página de erro 500.
11.12.3. Business/IBusiness.cs
- Linhas 17–33: os dados de um médico ou cliente a ser criado ou modificado, conforme transmitidos pela camada web (veja o Exemplo 28). [required] exige o título, o sobrenome e o nome; [init] impede que eles sejam modificados depois (veja o Exemplo 18). Login e senha são opcionais ([string?]): na criação, o padrão é o nome em minúsculas; na modificação, só mudam se tiverem sido informados. [Version] é a versão do registro lido quando o formulário de edição é exibido: ela é usada para o bloqueio otimista (veja a seguir);
- linha 36: o contrato da camada de negócio: o que as outras camadas podem solicitar a ela, sem especificar como isso é feito (as interfaces foram discutidas no Exemplo 06). Por convenção, em [.NET], um método assíncrono retorna uma [Task<T>] (o equivalente a uma [Promise<T>] de [JavaScript]) e seu nome termina com [Async];
- linhas 39–53: as leituras. Um tipo seguido de [?] ([Task<Client?>]) indica que o método pode retornar [null]: ninguém tem esse identificador. Os comentários [/// <summary>] são comentários de documentação: o [Visual Studio Code] os exibe quando você passa o mouse sobre o método;
- linhas 57–64: consultas. O comentário de [AddAppointmentAsync] lista os possíveis códigos de erro: isso faz parte do contrato que os testadores precisam conhecer;
- linhas 68–74: gerenciamento de médicos (reservado ao ADMIN). Cada médico é criado, modificado e excluído junto com sua conta de usuário;
- linhas 80–88: gerenciamento de clientes, seguindo a mesma lógica. [AddClientAsync] também é usado para cadastrar um paciente, enquanto [EditClientAsync] e [DeleteClientAsync] servem para os pacientes que gerenciam suas próprias contas.
A implementação é registrada em [Program.cs] pela linha [builder.Services.AddScoped<IBusiness, BusinessService>()]: “quando um construtor solicitar um [IBusiness], forneça a ele um [BusinessService]”, um por requisição ([Scoped]), assim como o [DbContext] e os DAOs que ele usa (veja o Exemplo 28 e o Capítulo 6). Com o [NestJS], uma interface [TypeScript] desaparecia em tempo de compilação: eram necessários um token ([BUSINESS_TOKEN]) e [@Inject(BUSINESS_TOKEN)]. Em [C#], as interfaces existem em tempo de execução: a própria interface serve de token. O único serviço que recebe um [IBusiness] é o [ApplicationModel] (pasta [Web]), que também implementa [IBusiness]: os controllers veem, portanto, o mesmo contrato, enriquecido com um cache das listas de médicos e clientes.
11.12.4. Business/BusinessService.cs
Este é o arquivo mais completo da aplicação. Vamos mostrá-lo em cinco trechos sucessivos.
11.12.4.1. Os descritores
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 | |
- linhas 6–29: o comentário de cabeçalho resume as cinco regras de negócio aplicadas pela classe;
- linha 34: o driver [MySQL] (veja o Capítulo 9): a classe usa sua exceção [MySqlException] para detectar violações de restrições de unicidade;
- linha 42: a classe implementa a interface; ela deve fornecer todos os seus métodos;
- linha 45: o custo do [bcrypt] (veja o Exemplo 25), que é o mesmo das senhas do script SQL (prefixo [$2b$10$]);
- linhas 49–60: tudo o que distingue um médico de um cliente em termos de regras de negócio: seu DAO, o papel de sua conta ([DOCTOR] ou [USER]), suas mensagens de erro e o que acontece quando são excluídos. Como médicos e clientes seguem as mesmas regras, o código dessas regras é escrito uma única vez, em métodos genéricos (parametrizados por um tipo [T]) que aceitam um descritor. A restrição [where T : Person, new()] exige que [T] herde de [Person] (poderíamos ler [LastName], [FirstName], [User]...) e tenha um construtor sem parâmetros (poderíamos escrever [new T()]). [Func<int, Task<int>>] é o tipo de uma função que recebe um [int] e retorna uma [Task<int>]; [Func<int, Task>] é o tipo de uma função assíncrona que não retorna nada. Esses parâmetros têm um valor padrão ([= null]): são opcionais;
- linhas 62–69: os campos da classe: o [DbContext], os cinco DAOs e os dois descritores. [readonly] impede que sejam modificados após o construtor;
- linhas 74–87: todas as dependências são fornecidas por injeção de dependência. O [DbContext] é usado aqui apenas para abrir transações: as consultas permanecem na camada DAO. Como no Exemplo 28, os DAOs e a camada de negócio recebem o mesmo [DbContext] durante uma requisição e, portanto, a mesma conexão e a mesma transação;
- linhas 89–99: o descritor do médico. Os argumentos nomeados ([CountAppointments:], [HasAppointmentsKey:]...) referem-se a um parâmetro pelo nome, o que permite pular parâmetros opcionais (o descritor do cliente, mais adiante, omite assim [CountAppointments] e [HasAppointmentsKey]). [appointmentRepository.CountByDoctorAsync] não é chamado aqui: o próprio método é passado e será chamado depois (um método pode, assim, servir como valor do tipo [Func]). A exclusão de um médico será negada enquanto ele tiver consultas; seus horários, porém, serão excluídos antes da exclusão do médico;
- linhas 101–109: o descritor do cliente. Sem [CountAppointments]: a exclusão de um cliente nunca é negada, e suas consultas (passadas e futuras) são excluídas antes do próprio cliente; caso contrário, a chave estrangeira [appointments.client_id] impediria a exclusão.
11.12.4.2. Operações de leitura e a agenda
- linhas 5–22: as operações de leitura simplesmente delegam à camada DAO. A sintaxe [=> expression] (um corpo de expressão) substitui um bloco [{ return expression; }]. Esses métodos não são [async]: eles retornam diretamente a [Task] do DAO, sem aguardá-la;
- linhas 24–25: as consultas futuras de um paciente: a camada de negócio fornece a data atual ao DAO;
- linhas 28–42: cálculo da agenda de um médico em um determinado dia, usando o mesmo algoritmo da versão [NestJS]. Um médico desconhecido resulta em [null]; caso contrário, são lidos os horários e as consultas do médico para o dia;
- linha 38: [ToDictionary] armazena as consultas em um dicionário cuja chave é o ID do horário (equivalente ao [Map] da versão [NestJS]). O dicionário elimina a necessidade de percorrer a lista de consultas para cada horário;
- linhas 39–41: cada horário é associado à sua consulta, ou a [null] ([GetValueOrDefault] retorna o valor padrão, [null], quando a chave não existe). [Select] transforma cada item de uma lista (veja [LINQ], Capítulo 9). O resultado é um objeto [DoctorDaySchedule] da pasta [Domain], que a view da agenda exibirá.
11.12.4.3. Agendamento de uma consulta
- linhas 17–18: todo o agendamento ocorre dentro de uma única transação: o método passa uma função anônima assíncrona, [async () => { ... }], para [TransactionAsync] (veja a seguir), que executa a tarefa;
- linhas 20–23: nenhuma consulta no passado. A regra é verificada aqui independentemente do papel de quem faz a reserva (ADMIN, DOCTOR ou o paciente), mesmo que a camada web já tenha ocultado os botões “Reservar” para datas passadas: uma requisição pode ser criada manualmente;
- linhas 25–27: o registro do paciente é bloqueado: [LockAsync] executa [SELECT * FROM clients WHERE id = ... FOR UPDATE] (veja [Repositories/PersonRepository.cs]). Trata-se de um bloqueio pessimista: ele é adquirido antes do início do processamento, presumindo um possível conflito, e permanece até o fim da transação. Sem ele, duas reservas do mesmo paciente enviadas exatamente ao mesmo tempo (duas abas, um clique duplo) poderiam ambas passar no teste seguinte antes que qualquer uma delas tivesse gravado sua consulta no banco de dados. Com esse bloqueio, a segunda transação espera a primeira terminar e então enxerga a consulta que ela criou. Um paciente que não é encontrado (excluído nesse meio-tempo) é rejeitado;
- linhas 29–31: apenas uma consulta futura por paciente;
- linhas 35–36: a inserção. Apenas as chaves estrangeiras [SlotId] e [ClientId] são especificadas: não há necessidade de vincular os objetos [Slot] e [Client] para gravar a linha [appointments]. Se outro paciente acabou de reservar o mesmo horário, o bloqueio não impediu isso (o bloqueio se aplica à linha do paciente): é a restrição de unicidade [unq1_appointments (day, slot_id)] do banco de dados que rejeita a inserção, e [TransactionAsync] traduz o erro em [BusinessException] com a chave [ERRORS.SLOT_ALREADY_BOOKED];
- linha 39: cancelamento de uma consulta: um simples [DELETE], sem regras específicas.
11.12.4.4. Gerenciamento de médicos e clientes
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 | |
- linhas 6–20: os seis métodos públicos delegam aos três métodos genéricos privados, usando o descritor correto. O compilador infere [T] a partir do descritor: [Doctor] para [doctorDescriptor], [Client] para [clientDescriptor];
- Linhas 26–50: criação de uma pessoa e de sua conta;
- linhas 28–33: preparação dos dados, fora de uma transação. [Trim] remove os espaços no início e no fim da string; o nome é colocado em maiúsculas. Por padrão, o login é igual ao nome e fica sempre em minúsculas; por padrão, a senha é igual ao login: essas são as regras de contas do script SQL;
- linhas 37–38: dentro da transação, as duas regras de unicidade: sem nomes duplicados e com livre escolha de login. Elas são verificadas antes da gravação no banco de dados para fornecer uma mensagem clara (veja o Exemplo 28);
- linhas 40–47: a conta de usuário é criada primeiro, já que a pessoa a referencia (chave estrangeira). A senha nunca é armazenada em texto puro: [BCrypt.Net.BCrypt.HashPassword] calcula seu hash (veja o Exemplo 25). [$"{firstName} {lastName}"] é uma string interpolada: o nome exibido da conta;
- Linhas 49–50: em seguida, com base na restrição [new()], a pessoa usa [new T] para gerar um [Doctor] ou um [Client]. Se esta segunda operação de gravação falhar, a transação também desfaz a primeira: uma conta nunca pode existir sem uma pessoa;
- linhas 59–95: modificação da pessoa e de sua conta em uma única transação;
- linha 63: uma pessoa não encontrada é uma [BusinessException], com a chave do descritor. [?? throw] foi visto no Exemplo 28;
- linhas 70–72: o bloqueio otimista (veja o Exemplo 28): o formulário carregou consigo a versão do registro lido na sua exibição; se a versão no banco de dados for diferente, alguém modificou o registro nesse meio-tempo, e o sistema rejeita a atualização em vez de sobrescrever silenciosamente o trabalho dessa pessoa. Ao contrário do bloqueio pessimista usado nas reservas, nada é bloqueado: presumimos que os conflitos são raros e simplesmente os detectamos. Se a modificação concorrente ocorrer depois dessa leitura, é a condição [WHERE version = ...] do [UPDATE] que a detectará (veja [TranslateDatabaseError], mais adiante);
- linhas 77–80: o objeto lido é simplesmente modificado: o [DbContext] enviará o [UPDATE] necessário no próximo [SaveChangesAsync]. A verificação do nome transmite o identificador da pessoa: ela tem, é claro, o direito de manter seu próprio nome e sobrenome;
- linhas 82–88: a conta acompanha a pessoa (propriedade de navegação [User], carregada pelo DAO): seu nome exibido é recalculado. O login só muda se tiver sido informado e for diferente do atual; nesse caso, ele precisa estar disponível;
- linhas 90–92: a senha só muda se tiver sido informada; nesse caso, é gerado o seu hash;
- linhas 94–95: gravação da conta e da pessoa. Nosso [DbContext] incrementa o número de versão de cada entidade modificada (veja [Data/RdvMedecinsDbContext.cs]);
- linhas 107–121: exclusão, dentro de uma única transação, na ordem ditada pelas chaves estrangeiras;
- linhas 111–113: possível rejeição: um médico com consultas agendadas não pode ser excluído (seus pacientes perderiam as consultas sem serem avisados). [d.CountAppointments(id)] chama a função armazenada no descritor;
- linhas 115–117: exclusão do que referencia a pessoa: os horários de um médico, as consultas de um cliente;
- linhas 119–120: a pessoa e depois sua conta, que a pessoa referenciava;
- linha 121: [TransactionAsync] espera uma função que retorne um resultado: um é retornado, mas ninguém o usará;
- linhas 127–133: um homônimo é rejeitado, a menos que seja a pessoa que está sendo editada no momento ([currentId], [null] em uma nova criação). O método é [static]: ele não usa nenhum campo do objeto;
- Linhas 137–141: um login já em uso — por um médico, um cliente ou o administrador — é rejeitado.
11.12.4.5. Transações e restrições de unicidade
- linha 15: todas as gravações em várias etapas passam por este método genérico: [R] é o tipo do resultado da operação ([Appointment], [Doctor], [Client], [bool]), e [Func<Task<R>>] é o tipo de uma função assíncrona sem parâmetros que retorna um [R]. Este é o método [TransactionAsync] do Exemplo 28, ampliado;
- linha 17: [BeginTransactionAsync] abre uma transação ([START TRANSACTION]). [await using var] declara uma variável que será fechada automaticamente ao sair do bloco que a contém, aconteça o que acontecer (término normal ou exceção); a versão [await] permite o fechamento assíncrono. Uma transação que é fechada sem ter sofrido commit é desfeita ([ROLLBACK]);
- linhas 20–22: a tarefa é executada; se for bem-sucedida, [CommitAsync] confirma a transação ([COMMIT]). Se uma exceção for lançada — inclusive [BusinessException] — [CommitAsync] nunca é alcançado: tudo o que foi gravado é desfeito;
- linha 24: o Exemplo 28 capturava dois tipos específicos de exceção; aqui, capturamos todas as exceções para fazer a limpeza antes de relançá-las;
- linha 29: a limpeza. O banco de dados desfez tudo, mas o [DbContext] ainda está rastreando entidades que não correspondem mais a nada: por exemplo, o médico cuja inserção falhou permanece no estado [Added]. Como o [DbContext] persiste durante toda a requisição, ele seria enviado de volta ao banco de dados no próximo [SaveChangesAsync] dessa requisição. [ChangeTracker.Clear()] faz o [DbContext] esquecer todas as entidades que rastreava;
- linhas 30–32: se o erro for um erro conhecido do banco de dados, a [BusinessException] correspondente é lançada em seu lugar. [is { } businessError] é um filtro de padrão: ele verifica se o valor não é [null] e o armazena na variável [businessError];
- linha 34: caso contrário, a exceção original é relançada como está. [throw;] sozinho, dentro de um [catch], mantém intacta sua pilha de chamadas (a que indica onde o erro ocorreu), ao passo que [throw e;] a reiniciaria. Uma [BusinessException] lançada pela tarefa é assim repassada, sem alteração, ao controller; qualquer outro erro é uma anomalia, que gerará uma página de erro 500;
- linhas 51–56: para cada restrição de unicidade nomeada no script SQL, sua chave de tradução. É por isso que o script SQL dá nome a todas as suas restrições. [new()] sem um nome de tipo é permitido quando o tipo já foi especificado à esquerda; [["key"] = value] preenche o dicionário;
- linhas 59–77: tradução de um erro do banco de dados em [BusinessException], ou em [null] se o erro não for reconhecido;
- linhas 62–64: [UPDATE ... WHERE id = ... AND version = ...] não modificou nenhuma linha: o EF Core lança uma [DbUpdateConcurrencyException] (bloqueio otimista; veja o Exemplo 28). Este teste vem primeiro porque [DbUpdateConcurrencyException] herda de [DbUpdateException]: se fosse colocado depois, o teste seguinte a teria interceptado;
- linha 68: uma violação de restrição de unicidade. O erro do [MySQL] (código [DuplicateKeyEntry], nº 1062) ocorre aninhado dentro de uma [DbUpdateException], em sua propriedade [InnerException]. O filtro de padrão verifica tudo em uma única expressão, em dois níveis: [e] é uma [DbUpdateException], cuja [InnerException] é uma [MySqlException], que tem um [ErrorCode] igual a [DuplicateKeyEntry]; esta [MySqlException] é armazenada em [sqlError]. A versão [NestJS] também testava o código [ER_DUP_ENTRY] de uma [QueryFailedError];
- linha 71: a mensagem de erro lista o nome da restrição, por exemplo, [Duplicate entry 'marie-pelissier' for key 'doctors.unq_doctors_first_name_last_name']. A expressão regular o extrai: [(?:[^'.]*\.)?] ignora o prefixo opcional [doctors.] (escrito pelo [MySQL] 8, e não pelo [MariaDB]), e o grupo [([^']+)] captura o nome até o apóstrofo. O [@] no início da string a transforma em uma string verbatim, na qual [\] não é um caractere de escape;
- Linhas 72–74: se o nome foi encontrado e consta no dicionário, [TryGetValue] armazena a chave de tradução em [key], e o erro se torna uma [BusinessException]. Qualquer outro erro, inclusive a violação de uma restrição ausente do dicionário, fica sem tradução: trata-se de uma anomalia verdadeira.
11.13. Autenticação
A pasta [Auth] reúne, de forma mais completa, os exemplos 25 a 27: o token JWT em um cookie, os papéis, o CAPTCHA e os limites de tentativas. Ela inclui também um “passe” para a criação de uma conta de cliente. O controller [AuthController], discutido no final desta seção, reúne esses componentes para a página de login.
11.13.1. Auth/ConnectedUser.cs
- linhas 24–29: os nomes das claims do token, agrupados em constantes: um erro de digitação em [JwtClaims.Name] é sinalizado pelo compilador, ao passo que um erro na string ["name"] só seria descoberto em tempo de execução;
- linha 33: o usuário logado em uma forma tipada: um identificador inteiro, um papel do tipo [Role] (a enumeração ADMIN, DOCTOR, USER da pasta [Entities]), em vez da lista de pares de strings que constituem as claims. Isso equivale ao objeto [req.user] criado pela estratégia [Passport] do projeto [NestJS];
- linhas 39–42: um método de extensão (veja o Exemplo 06) em
***[ClaimsPrincipal], o tipo da propriedade***[User]dos controllers e das views (veja o Exemplo 25). As páginas simplesmente escrevem [User.CurrentUser()]; - linhas 44–48: o método retorna [null] se a requisição não estiver autenticada ou se as claims não forem as esperadas. [Identity?.IsAuthenticated] é igual a [null] se [Identity] estiver ausente: a comparação [!= true] trata esse caso como “não autenticado”. [int.TryParse] e [Enum.TryParse<Role>] tentam uma conversão e retornam [false] se ela falhar, em vez de lançar uma exceção; o resultado é armazenado na variável declarada por [out var];
- linhas 50–54: [FindFirstValue] retorna o valor da primeira claim do tipo solicitado, ou [null]; o operador [??] então o substitui por uma string vazia.
11.13.2. Auth/AuthService.cs
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 | |
Vamos comentar este código:
- linha 38: o serviço recebe, por injeção, o DAO que contém as contas de usuário ([UserRepository], discutido junto com a camada DAO) e a configuração de autenticação. [IOptions<AuthOptions>] fornece a seção [Auth] do [appsettings.json] na forma de um objeto [AuthOptions] (pasta [Config]): sua propriedade [Value] contém a chave secreta, o tempo de vida do token e a opção [CookieSecure]. O serviço é registrado como [Scoped] em [Program.cs], assim como o DAO que ele usa (veja o Capítulo 6);
- linha 41: o nome do cookie que transporta o token;
- linhas 47–56: a chave de assinatura (veja o Exemplo 25). Novidade: uma chave curta demais é rejeitada com uma exceção clara. O método é static: ele depende apenas de seu parâmetro e é chamado quando a aplicação inicia, pelo [JwtAuthentication] (próximo arquivo), em um momento em que ainda não existem serviços. Como a verificação do tamanho ocorre nesse ponto, uma configuração incorreta impede a aplicação de iniciar, em vez de fazer o primeiro login falhar;
- linhas 62–69: a conta, se o login e a senha estiverem corretos; caso contrário, [null] (veja o Exemplo 25). O método é assíncrono: a busca da conta é uma consulta ao banco de dados (veja o Capítulo 9);
- linhas 78–92: o token, gerado como no Exemplo 25. Ele contém o ID da conta, o login, o nome exibido na barra de navegação e o papel; seu tempo de vida é determinado pela configuração (duas horas por padrão);
- linhas 94–100: o cookie, com as opções do Exemplo 25 ([HttpOnly], [SameSite = Lax]) e mais duas: [Secure], habilitada em produção (o site é servido com [HTTPS]), impede que o navegador envie o cookie por uma conexão não criptografada; [Path = "/"] garante que ele seja incluído em toda requisição ao site. [MaxAge] exclui o cookie quando o token expira;
- linhas 104–105: o logout exclui o cookie. Para que o navegador reconheça o cookie a ser excluído, o caminho ([Path]) deve ser o do local onde ele foi armazenado. O método é estático: ele também é usado pelo handler [JwtBearer] (próximo arquivo) e pelo filtro de exceção [HtmlExceptionFilter] (pasta [Web]), que não têm uma instância de [AuthService] disponível.
11.13.3. Auth/JwtAuthentication.cs
No Exemplo 25, a configuração do [JwtBearer] era escrita em [Program.cs]. Aqui, ela fica armazenada em um método de extensão, que o [Program.cs] chama em uma única linha: [builder.Services.AddJwtAuthentication(authOptions)]. Vamos comentar este código:
- Linhas 32–34: o método de extensão (veja o Exemplo 06). Ele recebe diretamente um objeto [AuthOptions], lido da configuração pelo [Program.cs]: quando os serviços são registrados, a injeção de dependência ainda não está disponível, portanto não podemos solicitar um [IOptions<AuthOptions>];
- linhas 37–42: o esquema de autenticação [JwtBearer], que armazena os nomes das claims do token (veja o Exemplo 25);
- linhas 44–54: as verificações realizadas em cada token: a assinatura, usando a chave gerada por [AuthService.SigningKey], e a data de expiração. Novidade em relação ao Exemplo 25: [ClockSkew = TimeSpan.Zero]. Por padrão, o [JwtBearer] ainda aceita um token por cinco minutos após sua expiração, para compensar uma pequena discrepância entre os relógios do servidor que gera o token e do que o verifica. Aqui, é o mesmo servidor: um token expirado é rejeitado imediatamente;
- linhas 57–58: a claim [name] resulta em [User.Identity.Name], a claim [role] é a verificada por [[Authorize(Roles = "ADMIN")]] e por [User.IsInRole] (veja o Exemplo 26);
- linhas 64–67: o token é lido do cookie, e não do cabeçalho [Authorization] (veja o Exemplo 25);
- linhas 71–82: uma requisição a uma página protegida sem um token válido redireciona para a página de login (veja o Exemplo 25). Novidade (linhas 77–80): se a requisição incluía um cookie de token, significa que o usuário estava logado, mas seu token expirou (ou foi adulterado). Excluímos esse cookie agora inútil e exibimos uma mensagem flash (veja o Exemplo 20; a classe [Flash] é discutida junto com a pasta [Web]): a página de login exibirá “Sua sessão expirou”, em vez de deixar o usuário sem entender por que está ali. A mensagem é uma chave de tradução (veja o Exemplo 22).
Uma resposta 403 Forbidden (papel insuficiente) não requer um evento: como no Exemplo 26, a resposta vazia é convertida em uma página de erro por [UseStatusCodePagesWithReExecute]. No projeto [NestJS], essa tarefa era dividida entre as estratégias [Passport] e [jwt] (ler e verificar o token), o guard [JwtAuthGuard] (exigir um token) e o filtro de exceção (converter a negação em um redirecionamento); aqui, o handler [JwtBearer], seus eventos e o atributo [[Authorize]] são suficientes.
11.13.4. Auth/InvalidSessionException.cs
- Linha 13: um token pode ser válido (corretamente assinado, não expirado) mesmo que a conta a que ele se refere tenha sido excluída desde o login. As páginas do paciente detectam isso buscando o cliente associado à conta (método [ConnectedPatientAsync] no arquivo [Web/Utils.cs]) e então lançam esta exceção; o filtro de exceção [HtmlExceptionFilter] (veja o Exemplo 24 sobre filtros) a intercepta, exclui o cookie e redireciona para a página de login com a mensagem “sessão expirada”. A classe tem um construtor principal sem parâmetros, que repassa sua mensagem ao construtor da classe-pai [Exception].
11.13.5. Auth/CaptchaService.cs
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 | |
O arquivo contém duas classes: a classe de serviço, que é idêntica à do Exemplo 27 exceto por uma salvaguarda, e a classe [CaptchaDrawing] que gera a imagem, já discutida no Exemplo 27 (arquivo [Auth/CaptchaDrawing.cs]). Vamos percorrer este código:
- linha 44: um CAPTCHA, como recebido pela página: o identificador, a ser colocado em um campo oculto do formulário, e a imagem [SVG];
- linhas 49–52: uma imagem é válida por dez minutos, e há um limite para o número de CAPTCHAs pendentes. Cada vez que a página de login é exibida, um CAPTCHA é adicionado à memória; sem um limite, um bot que solicitasse essa página milhões de vezes sem nunca responder acabaria esgotando a memória do servidor;
- linha 55: id → (resposta esperada, data de expiração). O par é uma tupla cujos elementos são nomeados ([Text], [Expires]). O serviço é um singleton, usado por requisições concorrentes: daí o [ConcurrentDictionary] (veja o Exemplo 27);
- linhas 57–63: a limpeza, seguida de um texto de cinco caracteres gerado aleatoriamente, armazenado sob um identificador aleatório ([Guid.NewGuid()], impossível de adivinhar) e exibido;
- linhas 70–77: verificação, idêntica à do Exemplo 27: o CAPTCHA é consumido em todos os casos ([TryRemove]); em seguida, o sistema verifica se ele não expirou e se o texto digitado, sem espaços, está correto, independentemente de maiúsculas e minúsculas. [TryRemove] é atômico: se duas requisições apresentarem o mesmo CAPTCHA ao mesmo tempo, apenas uma o remove;
- linhas 80–87: os CAPTCHAs expirados são descartados; se o limite for atingido, os CAPTCHAs válidos também são removidos até que a contagem fique abaixo do limite. Um [ConcurrentDictionary] pode ser modificado enquanto está sendo percorrido, o que não é permitido com um [Dictionary] comum (veja [AttemptLimiterService], mais adiante). No entanto, ele não preserva a ordem de inserção: os CAPTCHAs removidos dessa forma não são necessariamente os mais antigos, ao passo que o [Map] do projeto [NestJS] permitia remover primeiro os mais antigos. Essa situação só ocorre em caso de ataque: a aproximação é suficiente;
- linha 96: o desenho da imagem. [internal]: a classe só é visível dentro da própria aplicação;
- linhas 104–136: a “fonte”: para cada caractere, uma lista de traços, sendo cada traço uma sequência de coordenadas (x, y) em uma grade de 4 × 6. Os colchetes [[...]] são expressões de coleção ([C#] 12), uma notação compacta para arrays;
- linha 139: os caracteres utilizáveis, isto é, as chaves da fonte. [..] espalha uma coleção dentro de outra;
- linhas 146–147 e linhas 149–150: a aleatorização usa [RandomNumberGenerator], um gerador criptográfico cujas saídas são imprevisíveis;
- linhas 152–194: a imagem é um texto [SVG], montado em um [StringBuilder] (uma string que é estendida sem ser reescrita a cada elemento adicionado). Cada caractere (linhas 160–181) torna-se um caminho [<path>]: cada ponto da grade é ligeiramente deslocado, ampliado, girado e posicionado na imagem, com uma cor e uma espessura de linha escolhidas aleatoriamente. Os caracteres são linhas, nunca texto: um bot não consegue lê-los no código da imagem. Três curvas de embaralhamento cruzam então a imagem (linhas 185–190);
- linha 199: os números em [SVG] são escritos com ponto decimal. [CultureInfo.InvariantCulture] impõe essa notação independentemente do idioma do servidor: em francês, [ToString()] usaria uma vírgula (veja o Capítulo 5).
11.13.6. Auth/AttemptLimiterService.cs
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 | |
Em comparação com o Exemplo 27, o limitador protege duas operações (o login e a criação de contas); o bloqueio de login se aplica ao par (endereço IP, login), e os limites são configuráveis em [appsettings.json]. Vamos detalhar este código:
- linha 31: [IOptions<ProtectionOptions>] especifica a seção [Protection] do [appsettings.json] (pasta [Config]): o número de tentativas de login malsucedidas permitidas (5 por padrão), a duração do bloqueio (15 minutos) e o número de contas criadas por hora (10);
- linhas 33–37: um contador: o número de tentativas, o início da janela de contagem e o fim do bloqueio ([DateTime.MinValue], a data mais antiga possível, se não houver bloqueio). Esta é uma classe aninhada e privada: ela existe apenas para este serviço. É uma classe, e não um [record] ou uma estrutura: um contador lido do dicionário é modificado no local;
- linhas 42–43: um [Dictionary] comum, protegido por um lock (veja o Exemplo 27). Um [ConcurrentDictionary] não seria suficiente: contar uma tentativa envolve ler um contador, modificá-lo e possivelmente substituí-lo, e toda essa sequência de operações deve ser executada sem que outra requisição a interrompa. Cada método público executa, portanto, sua tarefa dentro de um bloco [lock (syncLock)];
- linhas 45–47: os limites, lidos uma vez por todas. O parâmetro do construtor principal pode ser usado para inicializar os campos;
- linhas 52–56: o tempo de bloqueio restante para uma tentativa de login: o maior dos dois períodos de bloqueio possíveis, o do par (endereço IP, login) e o do endereço IP isolado;
- linhas 60–65: uma tentativa malsucedida é contada duas vezes. Para o par (endereço IP, login): cinco tentativas malsucedidas com o mesmo login bloqueiam esse login, apenas a partir desse endereço. Para o endereço IP isolado, com um limite cinco vezes maior: um bot que tenta um grande número de logins diferentes também é bloqueado. Em uma sala de aula, todos os computadores costumam se conectar à Internet pelo mesmo endereço IP: um aluno que digita a senha errada não deve bloquear seus colegas, daí o bloqueio por par;
- linhas 70–74: um login bem-sucedido zera o contador desse login específico (e não o do endereço IP);
- linhas 80–84 e linhas 89–93: para a criação de contas, apenas as tentativas bem-sucedidas são contadas: no máximo dez contas por hora a partir do mesmo endereço IP. Quando a cota é atingida, o endereço fica bloqueado por uma hora;
- linhas 100–107: os minutos restantes do bloqueio, arredondados para cima até o próximo número inteiro ([Math.Ceiling]): exibe-se “1 minuto” em vez de “0 minuto” quando faltam 20 segundos. Esses métodos privados não adquirem o lock: eles são sempre chamados por um método público que já o detém;
- linhas 111–125: a contagem. Uma chave desconhecida, ou cuja janela de contagem expirou, começa com um novo contador. Quando o limite é atingido, a chave é bloqueada, e a contagem recomeça do zero ao fim do bloqueio;
- linhas 130–140: limpeza dos contadores que não são mais necessários (nem bloqueados nem recentes), feita apenas quando o dicionário ultrapassa 1.000 entradas. Percorremos uma cópia das entradas ([ToList()]): um [Dictionary] não pode ser modificado enquanto está sendo percorrido;
- linhas 145–147: geração das chaves do dicionário. Os espaços são removidos do login, que é convertido para minúsculas: [Admin] e [admin] compartilham o mesmo contador; um bot não consegue contornar o bloqueio trocando entre maiúsculas e minúsculas.
11.13.7. Auth/RegistrationPassService.cs
É possível criar uma conta de cliente a partir da página de login, desde que o CAPTCHA tenha sido resolvido. O formulário de cadastro é exibido e enviado por meio de requisições subsequentes: essas requisições precisam saber que uma requisição anterior resolveu o CAPTCHA com sucesso. Este é o papel do passe, emitido e verificado por [RegistrationController] (documentado na parte dos controllers):
- linha 29: o nome do cookie que transporta o passe;
- linhas 31–35: um passe é válido por quinze minutos; os passes pendentes são mantidos na memória, como os CAPTCHAs, com o mesmo limite de tempo;
- linhas 38–43: um passe é um identificador aleatório, armazenado junto com sua data de expiração; o controller o coloca em um cookie;
- linhas 47–48: o formulário de cadastro é exibido — e aceito — apenas com um passe válido. A verificação não consome o passe ([TryGetValue], e não [TryRemove]): o usuário pode reenviar o formulário várias vezes se cometeu erros de digitação;
- linhas 51–55: a criação de uma conta consome o passe: resolver um CAPTCHA dá direito a uma conta, e não mais;
- linhas 60–65: opções do cookie. [new()] cria um objeto do tipo declarado pelo método ([CookieOptions]). A opção [Path = "/register"] limita o envio do cookie às URLs que começam com [/register]: as outras requisições não o carregam desnecessariamente;
- linhas 68–75: o processo de limpeza, idêntico ao do CAPTCHA.
11.13.8. Controllers/AuthController.cs
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 | |
Vamos comentar este código:
- linhas 31–34: o controller recebe os três serviços de que precisa. Sem atributos [[Authorize]]: suas páginas são acessíveis sem estar logado;
- linha 37: a página inicial depende do papel: “Minha área” para um paciente, a agenda para os demais;
- linhas 39–45: a raiz do site redireciona para a página inicial específica do papel ou para a página de login. O middleware de autenticação é executado para todas as requisições, protegidas ou não: se o cookie contiver um token válido, [User] é preenchido, mesmo aqui. O projeto [NestJS], por outro lado, precisava verificar o token por conta própria (método [readToken]), já que a verificação do token não se aplica a essa rota;
- linhas 50–59: um usuário que já está logado é redirecionado para sua página inicial. O parâmetro opcional [login], que vem da URL (veja o Exemplo 07), preenche previamente o campo após a criação de uma conta. [login[..n]] (operador de intervalo) preserva os primeiros [n] caracteres: seu tamanho é limitado a 30, porque os dados de uma requisição nunca são usados sem tomar precauções;
- Linhas 65–70: os campos do formulário de login (veja o Exemplo 11), incluindo o ID do CAPTCHA, transmitido por um campo oculto, e o texto digitado pelo usuário. Todos são declarados como [string?]: um campo ausente resulta em [null], e é a action que decide o que fazer com ele;
- linhas 72–74: um login ausente torna-se uma string vazia; [password ??= ""] só atribui a string vazia se [password] for [null];
- linhas 77–80: 1. um par bloqueado nem chega a ser processado: nem o CAPTCHA nem a senha são verificados. O erro é uma chave de tradução com um parâmetro: o número de minutos a esperar;
- linhas 84–87: 2. o CAPTCHA. Um CAPTCHA incorreto conta como uma falha (veja o Exemplo 27);
- linhas 91–95: 3. Só então a senha é verificada. Um login ou uma senha vazios não são submetidos ao cálculo de [bcrypt] computacionalmente caro. Login desconhecido ou senha incorreta: a mesma mensagem deliberadamente vaga (veja o Exemplo 25) e mais uma falha;
- linhas 98–100: sucesso: contador zerado, token armazenado no cookie, redirecionamento para a página inicial do papel;
- linhas 105–109: logout, usando POST (veja o Exemplo 25);
- linha 115: o endereço IP do cliente, fornecido pela conexão de rede ([RemoteIpAddress], que pode ser [null], daí [?.] e [??]). O método é público e estático: [RegistrationController] e [PatientAreaController] também o usam para o limitador. Atrás de um servidor intermediário (um proxy reverso como o [nginx]), esse endereço seria o do proxy: o comentário especifica o middleware a ser habilitado nesse caso;
- linhas 118–125: a página de login, sempre com um novo CAPTCHA: cada imagem é usada apenas uma vez. Seu template, [LoginModel] (pasta [Models]), contém o título da página (uma chave de tradução), o login digitado (nunca a senha), o CAPTCHA e as eventuais mensagens de erro, com a chave de tradução e os parâmetros. [error] e [errorParams] são parâmetros opcionais: seu valor padrão é [null] quando a chamada não os fornece.
11.14. A camada web: serviços compartilhados
Antes de passarmos aos controllers e às views, eis o que eles têm em comum: a tradução, a classe-pai das views, as mensagens flash, o filtro de exceção, o cache das listas de médicos e clientes, a preparação dos formulários a serem reexibidos e algumas funções utilitárias. Todos esses arquivos estão na pasta [Web]. Ela reúne a maioria das técnicas dos Exemplos 16 a 24.
11.14.1. Web/Translator.cs
Este é o serviço de tradução do Exemplo 22, registrado como singleton em [Program.cs]: os dicionários [i18n/fr.json] e [i18n/en.json] são os mesmos arquivos da versão [NestJS], lidos uma única vez na inicialização. Há apenas uma diferença:
- linhas 65–67: uma chave ausente do dicionário francês é procurada no dicionário inglês ([DefaultLanguage]); se estiver ausente em todos, a própria chave é exibida. Os dois operadores [??] são encadeados: o primeiro valor que não for [null] é o escolhido.
11.14.2. Web/ViewPage.cs
Vamos detalhar este código:
- linha 25: a classe-pai de todas as views, designada pela diretiva [@inherits] de [Views/_ViewImports.cshtml], como no Exemplo 22. Ela serve ao mesmo propósito que [res.locals] na versão [NestJS]: fornece a cada view o que todas as páginas precisam;
- linhas 29–30: o serviço de tradução, injetado na propriedade (veja o Exemplo 22);
- linhas 39–40: o método [T] do Exemplo 22: [@T("KEY", ("name", value))]. O texto renderizado é escapado pelo [Razor]: um nome digitado por um usuário não pode injetar HTML na página;
- linha 43: uma segunda versão de [T], que aceita diretamente um dicionário: é a forma em que são passados os parâmetros de uma mensagem flash ou de uma [BusinessException]. Dois métodos com o mesmo nome, que diferem em seus parâmetros, são métodos sobrecarregados: o compilador seleciona o correto de acordo com os argumentos;
- linha 45: o idioma atual ([fr] ou [en]), para o atributo [lang] da página e o FR / EN;
- linha 47: o usuário logado, para a barra de navegação, ou [null] se não houver nenhum. [Context.User] é o usuário da requisição, reconstruído a partir do token JWT pelo middleware de autenticação (veja o Capítulo 8); o método [CurrentUser()] (arquivo [Auth/ConnectedUser.cs]) extrai a conta dele. Na versão [NestJS], era necessário um interceptor para copiar [req.user] para [res.locals] após os guards; aqui, a propriedade é calculada quando a view a lê, bem depois da autenticação;
- linha 49: a mensagem flash da requisição (veja [Web/Flash.cs], a seguir);
- linhas 51–54: o caminho da URL requisitada e o método que retorna [active] se a página atual estiver sob um determinado caminho: é assim que a barra de navegação destaca o item de menu atual, por exemplo [@Active("/my-")] (veja o Exemplo 16). [StringComparison.Ordinal] compara os caracteres um a um, independentemente do idioma;
- linhas 60–70: o usuário logado como visto pelas views: login, nome, papel e dois booleanos, [IsAdmin] e [IsPatient], que evitam que as views comparem papéis. O método estático [Of] cria esse objeto a partir da conta logada, ou retorna [null]; o operador [? :] escolhe entre os dois. Os argumentos [IsAdmin:] e [IsPatient:] são nomeados: o nome do parâmetro é escrito antes do valor, o que torna a chamada mais legível.
11.14.3. Web/Flash.cs
Vamos comentar este código:
- linhas 23–26: os dois tipos de mensagens: uma mensagem de sucesso, exibida no topo da página (view parcial [_Flash.cshtml]), e uma mensagem de erro, exibida na parte inferior (view parcial [_Errors.cshtml]);
- linha 30: uma mensagem flash consiste em uma chave de tradução e seus parâmetros, e não em um texto já traduzido; ela será traduzida na próxima página, no idioma dessa página;
- linha 32: uma classe estática que contém apenas funções (veja [Web/Utils.cs]). [TempData] (veja o Exemplo 20) faz a maior parte do trabalho: ele armazena o valor em um cookie criptografado até a próxima requisição e o exclui depois que é lido. Na versão [NestJS], esse cookie de curta duração era programado manualmente;
- linhas 43–51: define uma mensagem. [TempData] só pode armazenar valores simples (texto, números): a mensagem é armazenada como texto JSON ([JsonSerializer.Serialize]). O método recebe o [HttpContext] e não a propriedade [TempData] de um controller: ele pode, portanto, ser chamado de fora do MVC, por exemplo pela autenticação JWT, quando uma sessão expirou (veja [Auth/JwtAuthentication.cs]). Fora do MVC, ninguém salvaria o [TempData] ao final da requisição: [Save()] grava o cookie imediatamente;
- linhas 60–79: lê a mensagem da requisição. A leitura de [TempData] o marca como consumido; no entanto, a página o solicita duas vezes (no topo para um sucesso, na parte inferior para um erro). A primeira chamada armazena, portanto, o resultado em [HttpContext.Items], o dicionário de escopo da requisição (veja o Capítulo 6), de onde a segunda chamada o recupera (linha 62);
- linhas 71–73: [Deserialize] reconstrói o objeto [FlashMessage] a partir do JSON. Um texto ilegível não deve fazer a página falhar: a exceção é capturada e a mensagem é ignorada;
- linhas 82–83: o [TempData] da requisição, obtido do serviço [ITempDataDictionaryFactory]. [RequestServices] dá acesso à injeção de dependência a partir de uma classe estática, que não pode receber serviços por meio de seu construtor.
11.14.4. Web/HtmlExceptionFilter.cs
Vamos comentar este código:
- Linha 25: um filtro de exceção, como no Exemplo 24, adicionado como filtro global em [Program.cs]. Na versão [NestJS], um único filtro convertia todos os erros em páginas HTML. Aqui, o trabalho é dividido entre dois componentes de middleware do framework, configurados em [Program.cs]: [UseStatusCodePagesWithReExecute] substitui as respostas 400, 403 e 404 sem conteúdo pela página de erro correspondente (veja o Exemplo 24), e [UseExceptionHandler("/error/500")] intercepta todas as outras exceções: o erro é registrado no log do servidor, junto com sua pilha de chamadas, mas o usuário vê apenas a página de erro 500, já que esses detalhes poderiam ajudar um invasor;
- linhas 29–34: o filtro trata apenas um cenário: a conta do usuário logado foi excluída desde o login, embora seu token ainda seja válido (veja [Web/Utils.cs], abaixo). O cookie do token é apagado, uma mensagem flash de “sessão expirada” é exibida e o usuário é redirecionado para a página de login. As demais exceções não são marcadas como tratadas: elas seguem para [UseExceptionHandler].
11.14.5. Web/ApplicationModel.cs
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 | |
As listas de médicos e de clientes são exibidas em quase todas as páginas (listas suspensas da agenda, páginas de administração). Em vez de recuperá-las do banco de dados a cada requisição, elas são mantidas em memória: são dados de escopo de aplicação (veja o Capítulo 6). A versão [NestJS] atribuía esse papel a um único serviço, que era um singleton como todos os serviços [NestJS]. Em [ASP.NET Core], isso é impossível: a camada de negócio usa [DbContext], que existe apenas durante uma requisição (serviço [Scoped]; veja o Capítulo 9), e um singleton não pode receber um serviço [Scoped]. Por isso separamos os dois papéis em duas classes.
Vamos comentar este código:
- linha 39: o cache propriamente dito, registrado como singleton ([AddSingleton<ListCache>()] em [Program.cs]). Ele contém apenas as duas listas;
- Linhas 41–42: o [ASP.NET Core] processa requisições em paralelo em várias threads ([threads]), enquanto o [Node.js] tem apenas uma. Uma lista compartilhada nunca deve, portanto, ser modificada enquanto outra requisição a percorre. A regra que adotamos é simples: nunca modificamos uma lista; nós a substituímos por uma nova. Substituir uma referência é uma operação única, e a palavra-chave [volatile] garante que todas as threads vejam imediatamente a nova lista. [IReadOnlyList] permite apenas leitura: o compilador proíbe adicionar ou remover um elemento;
- Linha 60: a fachada, registrada como serviço [Scoped] ([AddScoped<ApplicationModel>()]). Ela recebe a camada de negócio da requisição atual e o cache compartilhado. Implementa a mesma interface [IBusiness] que a camada de negócio: para os controllers, ela é a camada de negócio, e é a única que eles recebem;
- Linhas 65–68: o carregamento inicial das duas listas. Ele é chamado uma única vez, por [Program.cs], antes de o servidor iniciar. Um serviço [Scoped] existe apenas dentro de um escopo: [Program.cs] cria um para essa finalidade ([CreateScope]). Se o banco de dados estiver inacessível, a exceção encerra a aplicação com uma mensagem explícita, o que é melhor do que iniciar um servidor com listas vazias;
- linhas 71–73: recarga de uma lista: a lista inteira é lida do banco de dados e substitui a que está no cache;
- linhas 77–79: as listas são servidas a partir da memória. A interface [IBusiness] declara um método assíncrono: [Task.FromResult] cria uma tarefa já concluída, que carrega o resultado. [ToList()] devolve uma cópia da lista: quem a chamou pode modificá-la sem afetar o cache;
- linha 83: o médico associado a uma conta, recuperado do cache: um médico logado vê imediatamente a sua própria agenda;
- linhas 87–110: as demais requisições são encaminhadas como estão para a camada de negócio;
- linha 104: um cliente associado a uma conta intencionalmente não é buscado no cache; um paciente que acabou de modificar ou excluir sua conta deve ser exibido tal como aparece no banco de dados;
- linhas 114–151: toda operação de escrita envolvendo médicos ou clientes é seguida de uma atualização da lista correspondente. Como este serviço é o único ponto de entrada dos controllers para a camada de negócio, a regra “escrita = atualização do cache” é implementada somente aqui, e o cache não pode ficar desatualizado. Se a camada de negócio rejeitar a operação ([BusinessException]), a exceção encerra o método antes de o cache ser recarregado, já que essa etapa deixa de ser necessária.
11.14.6. Web/Validation.cs
Vamos comentar este código:
- Linhas 20–31: converte o [ModelState] (veja os exemplos 07 e 19) em um simples dicionário “campo → chave de mensagem”. Apenas a primeira mensagem de cada campo é mantida: uma única mensagem é exibida sob o campo. O dicionário ignora a diferença entre maiúsculas e minúsculas (linha 22): o [ModelState] nomeia os campos com base nas propriedades ([LastName], [Login]), enquanto as views os solicitam com base nos campos HTML ([lastName], [login]);
- linhas 27–28: por precaução, um erro sem mensagem (como o causado por uma exceção) recebe a mensagem genérica [ERRORS.INVALID_FORM];
- linhas 38–42: certos erros da camada de negócio dizem respeito a campos específicos: um nome de usuário já em uso, ou um médico ou cliente com o mesmo nome. Esses campos serão destacados em vermelho, com a mensagem exibida na parte inferior da página. A sintaxe [["key"] = value] preenche o dicionário assim que ele é criado;
- linhas 53–64: prepara um template de formulário para exibição ou reexibição: as mensagens abaixo dos campos ([Errors]), os campos a serem contornados em vermelho ([InvalidFields]: os que têm uma mensagem, mais os campos de [otherFields], linha 61), a mensagem na parte inferior da página e seus parâmetros. Na ausência de uma mensagem explícita, os erros de campo resultam na mensagem “O formulário contém erros” (linha 62). O método é genérico: a restrição [where T : FormView] (linha 58) aceita qualquer modelo derivado de [FormView] (veja [Models/ViewModels.cs]), e devolve o modelo com seu tipo exato, pronto para ser passado a [View]. Os parâmetros têm valores padrão ([= null]): quem chama informa apenas os de que precisa.
11.14.7. Web/Utils.cs
Vamos detalhar este código:
- linha 24: o nome de um médico ou de um cliente: “Mme Alice DURAND”. O parâmetro é do tipo [Person], a classe-mãe das entidades [Doctor] e [Client]: a mesma função serve para ambos;
- linha 30: o formato de data nas URLs e no campo [<input type="date">];
- Linhas 34–35: verdadeiro se o texto for uma data existente no formato [yyyy-MM-dd]; [2026-02-30] é rejeitada (veja o Exemplo 12). O resultado é devolvido no parâmetro [out day]. [CultureInfo.InvariantCulture] torna a análise independente do idioma da requisição;
- linha 37: a operação inversa: uma data para o texto [yyyy-MM-dd];
- linhas 40–42: um horário no formato [8:05] (o formato [00] exige dois dígitos para os minutos) e o horário de um intervalo: [8:00 - 8:20];
- linhas 47–48: um dia escrito por extenso, de acordo com o locale da requisição, determinado pelo middleware de localização (veja o Exemplo 22): “mercredi 23 septembre 2026” ou “Wednesday 23 September 2026”;
- linhas 54–55: um identificador enviado pelo navegador (na URL ou em um campo de formulário): um inteiro estritamente positivo, ou [null]. [NumberStyles.None] aceita apenas dígitos: sem sinais, espaços ou separadores de milhar. O controller só precisa testar [null];
- linhas 70–73: o paciente (entidade [Client]) associado ao usuário logado. O token JWT contém apenas o ID da conta; buscamos o cliente associado a essa conta. Se ele não existir mais, significa que a conta foi excluída desde o login do usuário: [InvalidSessionException] será tratada pelo filtro [HtmlExceptionFilter] descrito acima, que redireciona para a página de login. [?? throw] lança uma exceção quando o valor à esquerda é [null] (veja o Capítulo 9).
11.15. Templates de formulário e de view
Dois tipos de classes transportam dados entre o navegador, os controllers e as views: os formulários, preenchidos pelo model binding com base no que o navegador envia, e os view models, preparados pelos controllers para as views. Os primeiros correspondem aos objetos DTO na versão [NestJS], enquanto os últimos correspondem aos objetos passados a [res.render].
11.15.1. Models/Forms.cs
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 | |
Vamos discutir este código:
- linha 43: títulos possíveis;
- linha 46: o formato de um nome de usuário, descrito por uma expressão regular: de 1 a 30 caracteres compostos por letras minúsculas, dígitos, ponto, hífen e sublinhado;
- linha 49: o comprimento mínimo da senha escolhida por um paciente. É uma constante ([const]), portanto pode ser usada como argumento de um atributo, como [[MinLength(InputRules.PasswordMin)]] abaixo;
- linha 52: limpeza de uma entrada: espaços no início e no fim são removidos, e um campo composto apenas por espaços torna-se [null], ou seja, é inválido;
- linhas 59–62: um atributo de validação escrito por nós: o valor deve constar de uma lista. Basta derivá-lo de [ValidationAttribute] e redefinir [IsValid]. [null] é aceito: cabe a [[Required]] rejeitar um campo ausente. Nós o usamos com o nome [[OneOf]]: por convenção, o sufixo [Attribute] pode ser omitido;
- Linha 66: os campos de identidade, comuns aos três formulários. Todas as propriedades são do tipo [string?]: um campo pode sempre estar ausente nos dados enviados pelo navegador, e é [[Required]] que o exige. As mensagens de erro são chaves de tradução (veja o Exemplo 22);
- Linhas 68–70: o título, que é obrigatório e escolhido na lista. Os valores são repetidos em [[OneOf(...)]]: o argumento de um atributo deve ser conhecido em tempo de compilação, o que não é o caso do array [InputRules.Titles] (um campo [static readonly], criado em tempo de execução);
- linhas 73–80 e linhas 83–90: o nome e o sobrenome, que são obrigatórios e podem ter até 20 caracteres (a largura das colunas SQL). Essas propriedades têm um corpo: seu valor é armazenado em um campo privado, e [set] o limpa ao passar. Como o model binding atua sobre as propriedades antes da validação, é o valor já limpo que é validado. Isso equivale ao [@Transform] da versão [NestJS]; [ASP.NET Core MVC] já converte automaticamente um campo vazio em [null];
- linha 95: o formulário ADMIN, para adicionar ou editar um médico ou um cliente. A classe herda os campos de identidade e seus atributos de validação;
- linhas 97–104: o login, que aqui é opcional, mas deve estar no formato correto se presente (linha 100); ele é higienizado e convertido para minúsculas. [?.] chama [ToLowerInvariant] somente se o valor não for [null];
- linhas 108–109: a senha, também opcional, com no máximo 72 caracteres: o algoritmo [bcrypt], que a criptografa, ignora quaisquer caracteres além desse limite. Uma senha não é higienizada: os espaços fazem parte dela;
- linha 114: a versão do registro, em um campo oculto do formulário de atualização (bloqueio otimista; veja o Exemplo 28). Um campo ausente ou vazio resulta em [null]; um texto que não seja um número produz um erro de binding, cuja mensagem é configurada em [Program.cs] (veja o Exemplo 19);
- Linha 118: um paciente cria uma conta: nome de usuário, senha (de 6 a 72 caracteres, linha 131) e confirmação (linhas 135–136) são obrigatórios. Verificar se a senha coincide com sua confirmação envolve dois campos: isso é verificado pelo validador ([Controllers/RegistrationController.cs]);
- Linha 140: um paciente modificando sua conta. A nova senha é opcional (linha 153): se deixada em branco, a senha permanece inalterada; sua confirmação (linha 157) portanto não é obrigatória aqui. A senha atual, porém, é obrigatória para qualquer alteração (linhas 160–161), e a versão do registro é armazenada em um campo oculto (linha 163).
11.15.2. Models/ViewModels.cs
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 | |
Os templates de view seguem a regra já aplicada com [Handlebars]: nenhuma lógica nas views. Os controllers preparam dados já formatados (“Mme Marie PELISSIER”, “8:00 – 8:20”) e já filtrados de acordo com o papel do usuário; as views apenas colocam esses dados no HTML. Cada view declara o tipo de seu template ([@model ScheduleModel], veja o Exemplo 13): o compilador verifica cada [@Model.Xxx], e um erro de digitação resulta em um erro de compilação.
Vamos comentar este código:
- linhas 22–31: o que todas as páginas têm em comum, lido pelo template [_Layout.cshtml]: a chave de tradução do título da página (linha 25) e a mensagem de erro da página, exibida na parte inferior, junto com seus parâmetros. A classe é abstrata: cada página tem seu próprio template, que deriva dela;
- linha 35: uma opção de uma lista suspensa (um médico, um paciente), já marcada como selecionada ou não (veja o Exemplo 18);
- linhas 38–41: a página de login: o nome de usuário já digitado e o CAPTCHA a ser exibido. A palavra-chave [required] obriga quem cria o objeto a atribuir um valor à propriedade; não fazê-lo resulta em um erro de compilação;
- linhas 45–54: uma entrada da agenda, isto é, um intervalo de horário. O controller já determinou tudo: se o nome do paciente é exibido (um paciente não pode ver os nomes dos outros), se o botão “Reservar” é exibido e se o botão “Cancelar” é exibido ([AppointmentId] está definido). As propriedades [init] só podem receber um valor quando o objeto é criado;
- Linha 57: a agenda de um médico para um único dia: o nome do médico, o dia por extenso e as linhas;
- Linhas 59–66: a janela de consulta: a lista de pacientes para o ADMIN e os médicos, ou apenas o nome do paciente logado;
- linhas 69–79: a página da agenda: a lista de médicos, o médico e o dia selecionados, a agenda ([null] enquanto nenhum médico estiver selecionado), a janela de reserva (se presente), a URL da agenda sem essa janela (linha 76) e a mensagem que explica a um paciente por que ele não pode marcar uma consulta;
- linhas 85–91: os valores exibidos nos campos de um formulário de “pessoa”, nunca a senha: uma senha não é reenviada ao navegador;
- linha 95: a classe-mãe dos templates dos três formulários de “pessoa”, aquela exigida por [Validation.Prepare]: os valores dos campos, as mensagens abaixo dos campos (linha 100) e os campos a serem destacados em vermelho (linha 104). Um [HashSet] é um conjunto: cada elemento aparece uma única vez, e o teste de pertinência é rápido;
- Linhas 106–108: dois métodos para as views: a mensagem de um campo (ou [null]) e a classe [Bootstrap] [is-invalid], que contorna um campo em vermelho. As views os chamam, por exemplo, assim: [@Model.InvalidClass("login")];
- linhas 110–111: as opções da lista de títulos, com a opção selecionada marcada (veja o Exemplo 18). Cada opção é uma tupla [(Value, Selected)];
- linhas 114–118: o formulário ADMIN, usado para adicionar e modificar entradas (veja o Exemplo 28): o modo, a URL de envio do formulário e a URL da lista para o botão de voltar;
- linhas 121–128: os formulários de cadastro e de gerenciamento de conta; eles passam à view o comprimento mínimo da senha, usado como parâmetro [{min}] da mensagem de erro do campo e, no cadastro, do texto de ajuda;
- linhas 134–142: as páginas de gerenciamento de médicos e de clientes usam as mesmas views; apenas seu texto difere. Este [record] contém as chaves de tradução específicas de cada tipo de pessoa;
- linhas 144–150: uma linha da lista de médicos ou de clientes, com os endereços de seus botões Editar e Excluir, e o template da página de lista;
- linhas 154–159: a área do paciente: seu nome e suas próximas consultas, cada uma com um link para a agenda do dia;
- linhas 163–166: a página de erro: o código HTTP e a chave da mensagem, que por padrão é a de um erro de servidor.
11.16. A camada web: os controllers
Os controllers são a parte visível da camada web: cada um recebe as requisições de um grupo de páginas, lê seus parâmetros, consulta a camada de negócio (sempre por meio do serviço [ApplicationModel]), depois seleciona uma view e lhe passa um modelo tipado, ou redireciona a requisição. Todos os formulários POST seguem o padrão Post/Redirect/Get (veja o Exemplo 20); todas as mensagens são chaves de tradução, traduzidas pela view. O controller de login, [AuthController], foi discutido junto com a autenticação.
11.16.1. Controllers/LanguageController.cs
Este é, exceto por uma linha, o controller do Exemplo 22: mesma rota [/language/{language}], mesmo cookie do middleware de localização, mesmo retorno à página de origem por meio do cabeçalho [Referer]. Dois esclarecimentos:
- linha 34: a opção [Path = "/"] torna o cookie válido para todos os endereços do site, independentemente da página em que o idioma foi alterado;
- linha 49: se a página de origem for ela própria uma página [/language/...], o usuário é redirecionado para a raiz do site em vez de voltar a essa página, o que faria o navegador entrar em loop.
11.16.2. Controllers/ScheduleController.cs
A página principal da aplicação e o controller mais rico em funcionalidades. Vamos detalhá-lo seção por seção.
11.16.2.1. As URLs da página
- Linhas 7–12: as rotas da página. Observe que a janela de reserva não é aberta por [JavaScript]: ela é um parâmetro da URL ([book=7]) que instrui o servidor a renderizar a página com a janela aberta. O botão “Reservar” é, portanto, simplesmente um link. A página inteira é descrita por sua URL: é possível recarregá-la, adicioná-la aos favoritos ou usar o botão “Voltar” do navegador;
- linhas 18–28: o que cada papel vê e pode fazer. Esta tabela é a “especificação” da página: o restante do controller a implementa;
- linhas 30–33: a regra de privacidade, à qual voltaremos: os nomes dos demais pacientes não são ocultados pela view; eles nunca são enviados ao navegador;
- linhas 55–57: [[Authorize]] na classe: todas as ações exigem um usuário logado, qualquer que seja o seu papel (veja o Exemplo 25). [[Route("schedule")]] é o prefixo de todas as rotas do controller (veja o Exemplo 02). O controller recebe o serviço [ApplicationModel] por injeção (veja o Exemplo 06) por meio de seu construtor primário: os parâmetros escritos entre parênteses após o nome da classe são acessíveis em todos os seus métodos;
- linhas 60–63: o que o controller sabe sobre o usuário logado, calculado uma vez por requisição (veja [RightsAsync], abaixo). Um [record] privado, declarado dentro da classe: é usado apenas por essa classe. [Manager] é verdadeiro para um ADMIN ou um DOCTOR; [Patient] é preenchido apenas para um cliente (papel USER).
11.16.2.2. GET /schedule
- Linhas 6–7: a rota [GET /schedule] (prefixo do controller, seguido de uma string vazia). A ação não tem parâmetros: ela lê automaticamente a URL como [Request.Query] (veja o Exemplo 05). O model binding converteria um parâmetro [int? doctorId] em [null] tanto se ele estivesse ausente quanto vazio; no entanto, esses dois casos precisam ser distinguidos (veja abaixo);
- Linhas 10–11: o usuário logado e suas permissões. [CurrentUser()] é um método de extensão (veja o Exemplo 06) definido em [Auth/ConnectedUser.cs]: ele lê as claims do token e as converte em um objeto tipado. [!] informa ao compilador que o resultado não é [null]: isso é certo, já que [[Authorize]] filtrou as requisições não autenticadas;
- linhas 14–26: o dia solicitado, se válido; hoje, caso contrário. [TryGetValue] devolve [false] se o parâmetro [day] estiver ausente: nesse caso, devolve hoje, sem mensagem. Se estiver presente, mas inválido ([day=2026-02-30]), gera uma mensagem de erro. Só é possível fazer reservas a partir de hoje ([dayBookable]);
- linhas 29–32: o médico solicitado. [Input.PositiveInteger] (pasta [Web]) devolve um inteiro estritamente positivo, ou [null] se o valor estiver ausente, vazio ou inválido. Se o parâmetro [doctorId] estiver ausente da URL, um médico logado vê a sua própria agenda: essa é a sua página inicial. Se estiver vazio ([doctorId=], a opção “-- choose a doctor --” da lista), nenhuma agenda é exibida;
- linhas 35–37: as opções da lista suspensa de médicos, lidas do cache de [ApplicationModel]; a opção do médico solicitado é selecionada (veja a função [Option] no final do arquivo e o Exemplo 18);
- linhas 40–46: a agenda só é calculada se um médico estiver selecionado e a data for válida. [doctorId is int id] verifica que o valor (do tipo [int?]) não é [null] e armazena seu valor em uma nova variável [id], do tipo [int]. Um ID de médico desconhecido dispara uma mensagem, não uma página de erro;
- linhas 50–56: a agenda calculada pela camada de negócio (um objeto [DoctorDaySchedule] da pasta [Domain]) é convertida em elementos de array, um por intervalo de horário. [var (slot, appointment) = ...] decompõe um par de valores em duas variáveis. [mine] determina se a consulta pertence ao paciente logado;
- Linhas 58–59: a view recebe apenas dados já formatados ([8:00 - 8:20]); ela não tem mais nada a calcular;
- linha 63: o controle de privacidade da aplicação. O nome do paciente é incluído no modelo apenas para um administrador ou para o paciente a quem a consulta pertence. Para todos os demais, o modelo contém [null], e a view exibe “Reservado”. O nome não é simplesmente ocultado pela view: ele nunca é enviado ao navegador, e “Exibir código-fonte da página” não o revelaria;
- linhas 65–67: o que a view deve exibir, conforme determinado pelo controller: o botão “Reservar” (intervalo disponível, data não passada e usuário autorizado a reservar), seu link (a URL da página, com [book]) e o botão “Cancelar” ([AppointmentId] é preenchido apenas para um administrador). A view não toma nenhuma decisão: ela segue essas instruções;
- linha 70: a agenda completa: o médico, o dia, as linhas.
11.16.2.3. A janela de consulta e o template da view
- linhas 3–5: o intervalo de horário para o qual a URL solicita uma reserva ([book=7]). Ele deve constar da agenda exibida e poder ser reservado por este usuário: uma URL criada manualmente (um intervalo passado, um intervalo já reservado ou um intervalo de outro médico) não abre a janela. [schedule?.Rows] equivale a [null] se [schedule] for [null] (operador [?.]);
- linhas 6–15: o template da janela. Um administrador seleciona um paciente em uma lista (todos os clientes, lidos do cache); um paciente faz uma reserva para si mesmo: a janela simplesmente exibe seu nome. [[]] é uma lista vazia;
- linhas 19–29: o template da página. Suas classes ([ScheduleModel], [ScheduleView], [ScheduleRowView], [BookingView], [OptionView]) são definidas em [Models/ViewModels.cs]; [PageTitle] e [Error] derivam de sua classe-mãe comum [ViewModel]. [PageTitle] é, como todos os textos, uma chave de tradução;
- linha 27: o endereço da agenda exibida, sem a janela de reserva — é o endereço do botão que fecha a janela;
- linha 28: uma mensagem informativa para pacientes que já têm uma consulta futura: ela explica por que eles não veem um botão “Reservar”.
11.16.2.4. POST /schedule/book
- Linhas 12–13: [[Authorize(Roles = ...)]] na ação é somado ao [[Authorize]] da classe: os três papéis podem fazer reservas (veja o Exemplo 26). Aqui, esse atributo não impõe nenhuma restrição adicional; ele documenta a regra e a protegeria caso surgisse um quarto papel;
- linhas 15–18: os campos do formulário da janela de reserva (veja o Exemplo 11). Eles são recebidos como strings e depois convertidos com cuidado;
- linhas 20–23: o médico e o dia são campos ocultos do formulário; eles permitem ao usuário voltar à agenda exibida. Se forem inválidos, a requisição não se originou da nossa página: foi criada manualmente. [BadRequest()] devolve uma resposta 400 sem conteúdo, que o middleware [UseStatusCodePagesWithReExecute] transforma em uma página de erro (veja o Exemplo 24). [is not int sltId] é o oposto de [is int]: verdadeiro se o valor for [null]; caso contrário, [sltId] recebe o valor;
- Linhas 27–29: para um paciente, o campo [clientId] é ignorado — o sistema sempre faz a reserva para o próprio paciente. Confiar nesse campo, enviado pelo navegador, permitiria a um paciente malicioso fazer uma reserva em nome de outra pessoa. [Patient.ConnectedPatientAsync] (pasta [Web]) identifica o cliente por meio do token; [nameof(Role.USER)] é a string ["USER"], verificada pelo compilador;
- Linhas 33–39: um gerente que não selecionou um paciente é redirecionado para a janela de reserva (URL com [book]), acompanhado de uma mensagem de erro em pop-up. [Flash.Put] (pasta [Web]) armazena a mensagem em [TempData] (veja o Exemplo 20);
- linhas 42–49: o paciente deve existir, e o intervalo deve existir e pertencer ao médico da agenda: não é possível reservar um intervalo pertencente a um médico para outro;
- linhas 57–58: as regras de negócio (não estar no passado, intervalo disponível, apenas uma consulta futura por paciente) são verificadas pela camada de negócio, que lança uma [BusinessException] em caso de rejeição;
- Linhas 63–65: [when] adiciona uma condição a [catch]: é um filtro de exceção [C#]. Este bloco só captura a [BusinessException] se a condição for verdadeira: para um paciente, a mensagem “este paciente já tem uma consulta” é substituída por uma mensagem em segunda pessoa. Caso contrário, a exceção segue para o próximo [catch];
- linhas 69–71: qualquer outra [BusinessException] se torna uma mensagem flash, junto com sua chave e seus parâmetros ([e.Params] é um dicionário somente leitura: é feita uma cópia dele, do tipo esperado por [Flash.Put]). As demais exceções não são capturadas: são erros verdadeiros, que resultam em uma página de erro 500;
- Linha 74: o esquema PRG: seja qual for o resultado, uma mensagem flash é exibida e o usuário é redirecionado para a agenda, que exibirá a mensagem. Na versão [NestJS], uma função utilitária cuidava dessa conversão de erros de negócio; aqui, os dois blocos [catch] bastam.
11.16.2.5. POST /schedule/cancel
- linhas 5–7: o cancelamento é restrito aos administradores; um paciente cancela sua consulta em “Minha área” (veja [PatientAreaController]). Um paciente que enviar esta requisição receberá uma página 403;
- Linhas 9–12: as mesmas verificações da reserva;
- linhas 14–18: uma consulta que já foi cancelada (por duplo clique ou por outro administrador) dispara uma mensagem de erro, não uma página de erro;
- linhas 22–25: exclusão, seguida do esquema PRG.
11.16.2.6. Permissões e funções utilitárias
- linhas 4–12: um administrador tem todas as permissões; um paciente pode fazer uma reserva se não tiver consultas futuras. Os argumentos nomeados ([Manager: true]) tornam legível a chamada ao construtor do [record];
- linhas 18–21: leitura dos dois campos ocultos comuns aos formulários POST. Os parâmetros [out] são resultados adicionais do método: ele devolve um booleano (os campos são válidos?) e, por meio de seus parâmetros [out], os valores convertidos. É o mesmo processo de [int.TryParse];
- linhas 24–27: a URL da agenda de um médico em um determinado dia, possivelmente com a janela de reserva aberta. Todos os redirecionamentos dos controllers a geram por meio desta função: as URLs da página são escritas em um único lugar;
- linha 30: uma opção de lista suspensa (ID, rótulo, seleção), tanto para um médico quanto para um cliente: o parâmetro é do tipo [Person], a classe-mãe de ambas as entidades.
11.16.3. Controllers/PersonsControllerBase.cs
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 | |
O gerenciamento de médicos e de clientes é idêntico. Em vez de escrever dois controllers semelhantes, escrevemos suas ações uma só vez, em uma classe-mãe abstrata e genérica. Vamos comentar este código:
- linhas 15–20: as rotas dos médicos; as mesmas existem em [/clients];
- linhas 22–23: as views também são compartilhadas (pasta [Views/Persons]);
- linhas 25–26: o MVC aceita apenas classes concretas como controllers: somente [DoctorsController] e [ClientsController] recebem requisições;
- linhas 38–45: a configuração fornecida por cada subclasse: a URL base, os textos (chaves de tradução, agrupadas em [record] e [PersonKeys] de [Models/ViewModels.cs]) e as funções a serem chamadas para listar, buscar, adicionar, modificar e excluir. [Func<int, Task<T?>>] é o tipo de uma função que recebe um [int] e devolve um [Task<T?>]: é assim que métodos são armazenados em propriedades, para serem chamados depois. [where T : Person] é uma restrição ao tipo genérico: [T] será [Doctor] ou [Client], duas classes derivadas de [Person]; o código pode, portanto, usar [p.FirstName] ou [p.User], que são comuns a todas as pessoas;
- Linha 47: a classe-mãe, que é genérica (veja a classe [ViewPage<TModel>] no Exemplo 22) e abstrata. Ela recebe [ApplicationModel] por meio de seu construtor primário e o repassa às suas subclasses por meio da propriedade protegida [Application] ([protected]: visível apenas para as subclasses);
- linha 51: uma propriedade abstrata: cada subclasse deve defini-la;
- linhas 56–69: a listagem. Os atributos de rota definidos nos métodos de uma classe-mãe são herdados: combinados com o [[Route("doctors")]] da subclasse, resultam em [GET /doctors]. Para cada pessoa, o modelo contém a URL de seus botões Editar e Excluir. [p.User?.Login ?? ""]: o login da conta associada, ou uma string vazia se a pessoa não tiver conta;
- linha 60: a view é especificada por seu caminho completo. Se apenas o nome fosse usado, o MVC a procuraria na pasta do controller ([Views/Doctors] ou [Views/Clients], veja o Exemplo 13), enquanto ela é compartilhada por ambos;
- linhas 75–76: o formulário vazio;
- linhas 83–98: a adição, em três etapas, como no Exemplo 28. O parâmetro [form] foi preenchido e validado pelo MVC antes da chamada (veja o Exemplo 19): uma entrada inválida reexibe o formulário, mostrando os valores digitados e uma mensagem abaixo de cada campo incorreto; uma entrada válida é passada à camada de negócio, e então o navegador é redirecionado para a lista, com uma mensagem flash (PRG); uma rejeição pela camada de negócio (um homônimo, um login já em uso) reexibe o formulário;
- Linhas 107–121: o formulário de modificação pré-preenchido. A restrição de rota [:int] (veja o Exemplo 02) só aceita um identificador inteiro: [/doctors/abc/edit] não corresponde a nenhuma rota, resultando em uma página 404 ([ParseIntPipe] derivado de [NestJS] resultava em um erro 400). Uma pessoa inexistente também resulta em um 404. O número de versão, um campo oculto do formulário, será usado para o bloqueio otimista (veja o Exemplo 28);
- linhas 128–143: a atualização, seguindo o mesmo padrão da inserção;
- linhas 152–165: a exclusão. A pessoa é recuperada antes para exibir seu nome na mensagem de confirmação. Uma rejeição da camada de negócio (por exemplo, um médico que tem consultas) resulta em uma mensagem flash de erro na página de listagem;
- linhas 171–188: o formulário de criação ([id] equivale a [null]), como o de modificação: apenas o título e o endereço de envio ([Action]) mudam. [Validation.Prepare] (pasta [Web]) preenche o template com as mensagens de erro específicas de cada campo, a mensagem do rodapé e os campos a serem destacados em vermelho;
- linhas 193–203: uma pessoa que foi excluída entretanto (por outro administrador) volta a ser listada; os demais erros de negócio reexibem o formulário, com a mensagem do rodapé e os campos afetados destacados em vermelho ([Validation.BusinessErrorFields] associa cada código de erro aos campos correspondentes: [firstName] e [lastName] para um homônimo). [is "A" or "B"] compara um valor com várias constantes;
- linhas 207–213: os valores a serem reexibidos — nunca a senha;
- linhas 217–224: os dados transmitidos à camada de negócio. Os campos [!] não representam risco: a validação verificou a presença desses campos;
- linhas 228–230: os parâmetros [{name}] e [{login}] nas mensagens de sucesso: o nome e o sobrenome da pessoa, e seu login.
11.16.4. Controllers/DoctorsController.cs
- Linhas 20–22: reservado ao ADMIN. O atributo definido na classe vale para todas as suas ações, inclusive as herdadas. O controller herda de [PersonsControllerBase<Doctor>]: o tipo da classe-mãe, [T], passa a ser [Doctor]. Seu construtor primário repassa [application] ao construtor da classe-mãe. (Em [TypeScript], era preciso escrever um construtor explícito para que o [NestJS] soubesse o que injetar; aqui isso não é necessário);
- linhas 24–34: a configuração. [override] redefine a propriedade abstrata da classe-mãe; [=>] a transforma em uma propriedade calculada, que cria o objeto a cada leitura. Os argumentos nomeados ([Url:], [Keys:]...) tornam a lista legível;
- linhas 35–39: as funções a serem chamadas, que são métodos de [ApplicationModel]. [Application.GetAllDoctorsAsync], escrito sem parênteses, não chama o método: refere-se a ele, e o compilador o converte em um valor do tipo esperado [Func].
11.16.5. Controllers/ClientsController.cs
O mesmo controller, para os clientes: rota diferente, chaves de tradução diferentes, métodos diferentes de [ApplicationModel].
11.16.6. Controllers/RegistrationController.cs
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 | |
Vamos comentar este código:
- linhas 14–24: proteção contra bots, em quatro etapas. O CAPTCHA e o limitador de tentativas foram apresentados no Exemplo 27;
- linhas 40–45: o controller não tem o atributo [[Authorize]]; suas páginas estão abertas a todos. Ele recebe quatro serviços por injeção;
- linhas 51–52: o botão “Criar uma conta de paciente” da página de login envia o formulário de login para este endereço (atributo [formaction]; veja o Exemplo 20). Apenas os campos do CAPTCHA são lidos;
- linha 54: o endereço IP do navegador, obtido por meio de um método estático de [AuthController];
- linhas 57–61: contas demais foram criadas a partir deste endereço na última hora: o usuário é redirecionado para a página de login, com uma mensagem em pop-up indicando o número de minutos a esperar. [new() { ["minutes"] = ... }] cria o dicionário de parâmetros da mensagem: seu tipo é inferido a partir do parâmetro de [Flash.Put];
- linhas 66–70: um CAPTCHA ausente ou incorreto conta como uma tentativa de login malsucedida (com nome de usuário vazio): um bot não pode continuar tentando indefinidamente. O retorno à página de login exibe uma nova imagem;
- linhas 74–75: o CAPTCHA está correto: um passe (veja [Auth/RegistrationPassService.cs]) é armazenado em um cookie, e o navegador é redirecionado para o formulário;
- Linhas 81–88: o formulário, somente com um passe válido. Digitar diretamente o endereço [/register] é inútil;
- linhas 96–97: a criação. O formulário [RegistrationForm] (pasta [Models]) foi vinculado e validado pelo MVC;
- linhas 99–101: o passe é verificado novamente: a requisição POST pode ter sido enviada sem passar pelo formulário;
- linhas 104–109: os valores a serem reexibidos em caso de erro, sem a senha. O título padrão é [Mr];
- linhas 113–116: o limite de tempo, verificado novamente no momento da criação;
- linhas 121–128: erros de entrada, campo por campo (veja o Exemplo 19). A correspondência entre a senha e sua confirmação — que envolve dois campos — é verificada aqui manualmente; ela só é testada se esses dois campos estiverem corretos nos demais aspectos. Todos os erros são informados juntos: o usuário os corrige de uma só vez;
- linhas 136–148: criação do cliente e de sua conta USER, usando o método da camada de negócio empregado pelo ADMIN. Se um nome de usuário ou uma combinação de nome e sobrenome já estiver em uso, o formulário é reexibido com os campos relevantes destacados em vermelho; o passe continua válido;
- Linhas 152–154: o passe foi usado: ele é consumido no lado do servidor, e seu cookie é excluído. Para excluir um cookie, é preciso especificar o mesmo caminho ([Path]) usado quando ele foi criado: o cookie do passe é enviado apenas para os endereços [/register...]. A criação é, por fim, contabilizada no limite por hora;
- linhas 157–158: retorno à página de login, com o nome de usuário preenchido e uma mensagem de sucesso. [Uri.EscapeDataString] codifica o nome de usuário para que possa ser incluído em uma URL;
- linha 163: o passe é lido do cookie da requisição;
- linhas 166–169: se nenhum passe estiver presente, retorna-se à página de login com uma mensagem;
- linhas 173–181: o formulário, preparado por [Validation.Prepare], é o mesmo dos médicos e dos clientes. [errorParams] é usado para os parâmetros da mensagem do rodapé (o número de minutos).
11.16.7. Controllers/PatientAreaController.cs
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 | |
Vamos detalhar este código:
- linhas 14–17: a regra de ouro deste controller: o paciente em questão é sempre o associado ao token, nunca um identificador enviado pelo navegador;
- linhas 35–39: reservado aos pacientes. O controller não tem o atributo [[Route]]: cada ação fornece seu endereço completo, já que elas não compartilham um prefixo ([/my-area], [/my-account]);
- linhas 44–59: a página “Minha área”. [Patient.ConnectedPatientAsync] identifica o usuário com base no token; se sua conta tiver sido excluída desde o login, dispara uma [InvalidSessionException], que o filtro [Web/HtmlExceptionFilter.cs] redireciona de volta para a página de login. A data é formatada por [WebDates.FormatDay] de acordo com o idioma da requisição, definido pelo middleware de localização (veja o Exemplo 22); cada consulta inclui um link para a agenda do médico naquele dia;
- linhas 66–82: cancelamento da consulta do paciente. [condition ? value1 : value2] devolve aqui a consulta, ou [null] se o ID for inválido. Uma consulta inexistente e uma pertencente a outro paciente (linha 73) recebem a mesma resposta: nenhuma informação é revelada sobre as consultas de outros pacientes;
- linhas 88–98: o formulário da conta, pré-preenchido, com o número de versão (bloqueio otimista);
- linhas 105–106: o processo de modificação, em três etapas: validação, verificação da senha atual, lógica de negócio;
- linhas 109–115: os valores a serem reexibidos em caso de erro, nunca as senhas;
- linhas 118–125: erros de entrada. A nova senha é opcional (em branco: inalterada); sua confirmação só é comparada se tiver sido informada;
- linhas 129–138: a senha atual. [var (key, messageParams) = ...] decompõe o par devolvido pela verificação. Uma senha incorreta é exibida abaixo de seu campo e na parte inferior da página; um bloqueio (tentativas demais) é exibido apenas na parte inferior da página, junto com o número de minutos;
- linhas 143–150: modificação pela camada de negócio, que aplica as mesmas regras do ADMIN (unicidade, bloqueio otimista);
- linha 154: o token contém o login e o nome de exibição: após uma alteração, um novo token é emitido; caso contrário, a barra de navegação manteria o nome antigo;
- linhas 158–160: uma rejeição pela camada de negócio reexibe o formulário, com os campos relevantes destacados em vermelho;
- linhas 169–183: exclusão da conta, que também exige a senha atual. Um erro é indicado por uma mensagem em pop-up na página da conta (PRG);
- linhas 180–181: exclusão do registro, da conta e de todas as consultas (o método da camada de negócio usado pelo ADMIN), seguida de logout: o cookie do token é apagado;
- linhas 190–191: verificação da senha atual. O método devolve [null] se a senha estiver correta; caso contrário, devolve uma tupla: um par de valores nomeados (a chave da mensagem e seus parâmetros). O [?] final torna essa tupla “anulável”;
- linhas 195–198: a senha atual está sujeita ao mesmo limitador do login (veja o Exemplo 27). Quem encontrasse uma sessão deixada aberta não conseguiria alterar a senha, excluir a conta nem tentar senhas indefinidamente;
- linhas 200–204: o processo de autenticação propriamente dito, tratado por [AuthService]; uma tentativa de autenticação malsucedida é contada como uma tentativa de login malsucedida;
- linhas 209–217: o formulário da conta.
11.16.8. Controllers/ErrorController.cs
Este é o controller do Exemplo 24, com as mensagens traduzidas:
- linhas 23–28: a chave de mensagem para cada código de erro. [static readonly]: um único dicionário, criado quando a classe é carregada e nunca substituído;
- linhas 30–31: [[Route]], que não especifica o método HTTP, aceita todos os métodos: uma requisição POST reexecutada (por exemplo, um paciente tentando um cancelamento reservado aos administradores) continua sendo uma requisição POST;
- linhas 35–37: um código HTTP que não seja de erro (um endereço [/error/200] digitado manualmente) torna-se um erro 500;
- linha 39: a página conserva o código de erro original;
- linhas 40–44: o template da página. [GetValueOrDefault] devolve a chave associada ao código, ou [ERRORS.SERVER_ERROR] para qualquer outro código (500, em particular).
11.17. As views
As views quase não têm nada a decidir: seu template foi preparado pelos controllers nas classes do arquivo [Models/ViewModels.cs] (quais botões exibir, quais elementos de URL, quais chaves de tradução). Cada view declara o tipo de seu template ([@model], veja o Exemplo 13): um erro de digitação em [@Model.Xxx] causará um erro de compilação. Cada view também começa com um comentário [Razor] [@* ... *@] que descreve seu papel; esses comentários não aparecem nas páginas enviadas ao navegador.
Uma diferença em relação aos exemplos do Capítulo 4: o estudo de caso não usa Tag Helpers. As views parciais são inseridas por meio de [@await Html.PartialAsync("_Name")], o equivalente da tag [<partial name="_Name">] do Exemplo 15. Um segundo argumento, opcional, fornece o modelo da view parcial; sem ele, a view parcial recebe o modelo da página. O método é assíncrono (a view parcial pode precisar ser compilada ou lida do disco): [await] aguarda seu resultado.
11.17.1. O template e as views parciais
11.17.1.1. Views/_ViewImports.cshtml
- linhas 9–11: os namespaces cujos tipos são usados pelas views: os templates de view ([RdvMedecins.Models]), as mensagens flash ([RdvMedecins.Web]);
- linha 12: a classe-mãe de todas as views, [Web/ViewPage.cs], como no Exemplo 22. Ela lhes fornece a tradução [@T("KEY")], o idioma [Language], o usuário logado [CurrentUser], a mensagem flash [FlashMessage], o caminho solicitado [CurrentPath], e o método [Active] (item de menu ativo na barra de navegação). Na versão [NestJS], essas informações eram passadas por meio de [res.locals]. Não há nenhuma diretiva [@addTagHelper]: a aplicação não usa Tag Helpers.
11.17.1.2. Views/_ViewStart.cshtml
- Linha 9: todas as páginas usam o template [Views/Shared/_Layout.cshtml] (veja o Exemplo 15). O [Handlebars] usava automaticamente [views/layout.hbs]; o [Razor] exige que isso seja especificado.
11.17.1.3. Views/Shared/_Layout.cshtml
- Linha 20: o template compartilha o modelo da página, acessível por meio de [ViewData.Model] (do tipo [object]). Todos os templates de página derivam da classe abstrata [ViewModel], que contém a chave do título ([PageTitle]) e o erro da página ([Error]). [as ViewModel] devolve [null] se o template não for um [ViewModel]: o template funciona com qualquer página;
- linha 23: o idioma da página (veja o Exemplo 22);
- Linha 27: o título, traduzido, por exemplo, “Agenda - RdvMedecins”. Diferentemente do Exemplo 22, a chave não é definida pela view em [ViewData]: ela é fornecida pelo controller no modelo tipado. [page?.PageTitle] é igual a [null] se [page] for [null], e o operador [??] então substitui a chave por [APP.TITLE];
- linhas 28–29: as folhas de estilo, servidas por [UseStaticFiles] a partir da pasta [wwwroot]: [Bootstrap] ([wwwroot/lib/bootstrap]) e a folha de estilo específica da aplicação;
- linhas 33–36: a barra de navegação, a mensagem de sucesso (no topo), a página solicitada ([@RenderBody()]) e a área de erro (na parte inferior);
- linhas 39–40: a janela de confirmação (oculta) e seu script (veja o Exemplo 21), carregados na parte inferior da página.
11.17.1.4. Views/Shared/_Navbar.cshtml
- linha 12: o usuário logado, conforme descrito pela classe [ViewUser] de [Web/ViewPage.cs] (login, nome, papel, [IsAdmin], [IsPatient]), derivado do token JWT. Ele é definido como [null] nas páginas públicas (login, criação de conta);
- linhas 17–31: os menus dependem do papel: “Minha área” para um paciente, “Médicos” e “Pacientes” para o ADMIN. Isso é apenas por conveniência: a segurança é garantida pelos atributos [[Authorize(Roles = ...)]] dos controllers (um paciente que digitar manualmente [/doctors] receberá uma página 403). [Active("/doctors")] devolve [active] se o caminho solicitado começar com [/doctors]: o [Bootstrap] então destaca esse menu. O prefixo [/my-] cobre as duas páginas do paciente, [/my-area] e [/my-account];
- linha 34: sem menus, um bloco vazio ocupa o lugar ([me-auto]: margem direita automática), de modo que o restante do conteúdo permaneça à direita da barra;
- linhas 40–41: os links FR / EN do Exemplo 22. A expressão [@( ... )] está entre parênteses porque contém espaços (veja o Exemplo 14);
- linhas 44–52: o papel, o nome e o botão de logout em um formulário POST (veja o Exemplo 21).
11.17.1.5. Views/Shared/_Flash.cshtml
- linha 9: a mensagem flash postada pela ação anterior (veja o Exemplo 20 e [Web/Flash.cs]). Ler uma mensagem flash a apaga; como a página a lê duas vezes (aqui e em [_Errors.cshtml]), a classe [Flash] a armazena, depois de lida, em [HttpContext.Items] (veja o Capítulo 6);
- linha 11: [flash is { Type: FlashType.Success }] é um padrão de propriedade: a condição é verdadeira se [flash] não for [null] e se sua propriedade [Type] for igual a [FlashType.Success]. Apenas uma mensagem de sucesso é exibida aqui;
- linha 14: a mensagem é uma chave; seus possíveis parâmetros ([name], [login], [minutes]) formam um dicionário, passado à segunda forma do método [T]. [role="status"]: um leitor de tela anuncia a mensagem sem interromper o usuário.
11.17.1.6. Views/Shared/_Errors.cshtml
- Linhas 15–18: as duas fontes de erro: o erro da página exibida (propriedade [Error] do template: formulário rejeitado, senha incorreta etc.) e uma mensagem flash de erro exibida antes de um redirecionamento (intervalo já reservado, exclusão rejeitada etc.);
- Linhas 20–22: a área é exibida se qualquer uma das duas estiver presente. [role="alert"]: um leitor de tela anuncia a mensagem assim que a página é exibida, mesmo que ela esteja na parte inferior. A classe [error-zone] é definida em [wwwroot/css/styles.css];
- linha 25: o operador [!] informa ao compilador que [page] não é [null]: ele não consegue deduzir isso sozinho, embora seja certo, porque [error], lido de [page], não é.
11.17.1.7. Views/Shared/_Confirmation.cshtml
A janela do Exemplo 21, com rótulos traduzidos pelo servidor — como o restante da página — e atributos de acessibilidade:
- linha 16: uma única janela para a página inteira, inicialmente oculta ([d-none]);
- linhas 18–19: [role="alertdialog"] indica uma janela que aguarda uma resposta; [aria-modal="true"] indica que o restante da página está inativo; [aria-labelledby] e [aria-describedby] designam o título e a mensagem lidos por um leitor de tela;
- linha 24: o botão de fechar, que significa “Não” ([data-action="no"]). Ele não tem texto: [aria-label] fornece um nome para os leitores de tela;
- Linhas 32–33: “Não, voltar” em vez de “Cancelar”: a pergunta às vezes é “Cancelar esta consulta?”, e um botão “Cancelar” seria ambíguo nesse contexto.
11.17.1.8. Views/Auth/_Captcha.cshtml
- linha 15: a view parcial tem seu próprio template, o CAPTCHA gerado por [Auth/CaptchaService.cs] (veja o Exemplo 27): seu ID e sua imagem;
- linha 19: a imagem SVG é inserida como está (veja o Exemplo 14): ela é gerada pelo servidor, sem nenhuma entrada do usuário. [role="img"] e [aria-label] fazem com que ela seja tratada como imagem pelos leitores de tela;
- Linha 20: “Outra imagem” simplesmente recarrega a página atual: um novo CAPTCHA é gerado;
- linha 22: o ID do captcha, em um campo oculto: ele informa ao servidor qual captcha verificar. A resposta correta, porém, nunca sai do servidor;
- linhas 23–24: o campo de entrada. [autocomplete="off"], [autocapitalize="off"] e [spellcheck="false"] impedem que o navegador sugira, coloque em maiúsculas ou corrija os caracteres copiados.
11.17.1.9. Views/Shared/_PersonFields.cshtml
Os campos de identidade (título, nome, sobrenome), comuns a três formulários: médico ou cliente do ADMIN, criação de conta e gerenciamento da conta do paciente.
- Linha 11: [FormView] é a classe-mãe (abstrata) dos templates desses três formulários. Ela contém os valores digitados ([Values]), a mensagem de erro de cada campo rejeitado ([Errors]) e os campos a serem destacados em vermelho ([InvalidFields]). A view parcial aceita, portanto, o template de cada uma das três páginas;
- linhas 14–19: a lista de títulos. [Model.Titles] devolve tuplas (valor, selecionado?); [var (value, selected)] decompõe cada tupla em duas variáveis. [selected="@selected"] é um atributo booleano, escrito apenas se o valor for verdadeiro (veja o Exemplo 17). [InvalidClass("title")] devolve [is-invalid] se o campo deve ser contornado em vermelho (veja o Exemplo 19);
- linhas 20–23: a mensagem de erro do campo, se houver. [ErrorOf] devolve a mensagem, ou [null]; a condição [is { } titleError] é verdadeira se o valor não for [null], e então o armazena na nova variável [titleError];
- Linhas 26–45: o nome e o sobrenome, seguindo o mesmo formato, lado a lado em uma tela suficientemente larga (grid [Bootstrap]: [col-sm-6]). Os atributos [maxlength] e [required] são apenas por conveniência: os formulários que inserem esta view parcial têm o atributo [novalidate], e o servidor cuida da validação.
11.17.1.10. Views/Schedule/_Booking.cshtml
- Linha 11: a view parcial recebe o template da página da agenda. [Model.Booking!]: a página só a insere se [Booking] não for [null], o que o operador [!] garante ao compilador;
- linhas 15–16: as classes [Bootstrap] de uma janela modal e de seu fundo cinza, tornadas visíveis “diretamente no código” ([show d-block]): o servidor decide exibir a janela quando a URL contém o parâmetro [book]. O [JavaScript] do [Bootstrap] não é usado (nem sequer é carregado);
- linha 18: o conteúdo da janela é o próprio formulário de reserva;
- linha 21: fechar a janela segue um link para a mesma agenda, sem o parâmetro [book] ([BackUrl], preparado pelo controller);
- linha 25: “Intervalo 8:00 - 8:20”: um parâmetro de tradução;
- linhas 28–30: campos ocultos: informações adicionais de que o servidor precisa além do paciente selecionado;
- linhas 32–48: um paciente vê seu nome; um administrador (ADMIN, DOCTOR) seleciona o paciente em uma lista. A primeira opção tem valor vazio: com [required], o navegador exige que um paciente real seja selecionado. [autofocus] coloca o cursor na lista;
- linhas 52–53: “Cancelar” é um link, assim como o X; “Confirmar” envia o formulário.
11.17.2. As páginas
11.17.2.1. Views/Auth/Login.cshtml
- linha 13: após uma falha, o controller devolve esta página com o nome de usuário já digitado;
- linha 20: um formulário HTML padrão: o navegador envia por conta própria o nome de usuário, a senha e a resposta do CAPTCHA;
- linhas 23–29: [autofocus] é um atributo booleano: apenas um dos dois campos o recebe. O cursor é colocado no campo do nome de usuário, ou no campo da senha se o nome de usuário já for conhecido. Os valores de [autocomplete] ([username], [current-password]) auxiliam os gerenciadores de senhas dos navegadores;
- linha 32: o CAPTCHA; o segundo argumento fornece o template da view parcial;
- linhas 45–46: o segundo botão envia o mesmo formulário para [/register/access] (atributo [formaction], veja o Exemplo 20): o servidor verifica o CAPTCHA ali antes de abrir a página de criação de conta. [formnovalidate]: o navegador não exige nome de usuário e senha, pois eles não são necessários para criar uma conta. Pressionar a tecla Enter em um campo sempre aciona o primeiro botão do formulário: “Entrar”;
- linhas 51–56: contas de demonstração (senha = nome de usuário).
11.17.2.2. Views/Schedule/Schedule.cshtml
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 | |
Vamos comentar este código:
- linhas 14–34: seleção do médico e do dia: um formulário GET (veja o Exemplo 17), que recarrega a página com [?doctorId=...&day=...] na URL. Cada médico é um [OptionView] que indica se ele está selecionado. Um campo [type="date"] envia a data no formato [yyyy-mm-dd] (veja o Exemplo 18);
- linhas 37–42: uma mensagem para um paciente que já tem uma consulta futura: ela explica por que os botões “Reservar” estão ausentes;
- linha 45: a agenda, se solicitada. A condição [is { } schedule] verifica que a propriedade não é [null] e armazena seu valor na variável [schedule];
- linha 48: o título: “Agenda de 2026-09-25 – Mme Marie PELISSIER”;
- linha 63: um intervalo reservável muda de cor ao passar o mouse (classe [free-slot], veja [styles.css]). Quando o valor de um atributo é [null], o [Razor] não escreve o atributo: as outras linhas não têm o atributo [class];
- Linhas 69–80: três casos: disponível; reservado, com o nome do paciente (em azul se for a consulta do paciente logado, [Mine]); reservado sem nome visível, “Reservado”. O controller só preenche [Patient] se o usuário tiver permissão para ver esse nome;
- Linhas 85–90: “Reservar” é um link: ele reabre esta página, exibindo a janela de reserva para este intervalo ([BookUrl], preparado pelo controller);
- linhas 91–101: “Cancelar” modifica dados: é um formulário POST, com confirmação ([data-confirmation], veja o Exemplo 21). Os campos ocultos [doctorId] e [day] permitem ao controller redirecionar para a mesma agenda. No loop, [Model] sempre se refere ao template da página: não é preciso o equivalente de [@root] ou [Handlebars];
- linhas 110 e 116: um médico sem intervalos disponíveis, ou nenhuma agenda foi solicitada ainda;
- linhas 120–123: a janela de reserva, se o controller a tiver preparado.
11.17.2.3. Views/Persons/List.cshtml
Uma única view para médicos e clientes:
- Linhas 8–9: os textos específicos de cada tipo de pessoa aparecem como chaves ([Model.Keys], do tipo [PersonKeys]), fornecidas por [DoctorsController] ou [ClientsController]: [DOCTORS.TITLE] ou [CLIENTS.TITLE], etc.;
- Linhas 26–45: uma linha por pessoa, com dois botões;
- linha 35: “Editar” é um link para o formulário;
- linhas 38–41: “Excluir” é um formulário POST, com confirmação;
- linha 51: “Nenhum médico.” ou “Nenhum paciente.”
11.17.2.4. Views/Persons/Form.cshtml
Vamos comentar este código:
- linha 17: o título (“Adicionar um médico”, “Editar um paciente” etc.) é a chave do título da página, fornecida pelo controller;
- linha 22: a URL é fornecida pelo controller: a mesma view é usada tanto para adicionar quanto para editar médicos e clientes. [novalidate]: o servidor cuida da validação (veja o Exemplo 19);
- linhas 23–25: em uma edição, a versão do registro, em um campo oculto: é o bloqueio otimista do Exemplo 28;
- linha 29: os campos de identidade;
- linhas 34–44: o login, com uma mensagem de erro ou, se não houver, um texto de ajuda. O texto de ajuda difere conforme se trate de uma adição (“Opcional: por padrão, o sobrenome em minúsculas.”) ou de uma edição;
- linhas 48–59: a senha, que nunca é preenchida previamente; ela nunca é reenviada ao navegador. [autocomplete="new-password"]: o navegador não sugere a senha salva do administrador. O comprimento é limitado a 72 caracteres porque o algoritmo [bcrypt] ignora os caracteres seguintes;
- Linha 64: o link de volta para a listagem é um hiperlink.
11.17.2.5. Views/Registration/Registration.cshtml
Criação de uma conta de cliente, página pública. Aqui não há CAPTCHA: só é possível chegar a esta página depois de resolver o CAPTCHA da página de login.
- linha 17: os mesmos campos de identidade do formulário do ADMIN;
- Linhas 22–32: o nome de usuário, que desta vez é obrigatório;
- linhas 37–47: o texto de ajuda e a mensagem de “muito curta” têm um parâmetro, [{min}], que é o comprimento mínimo da senha fornecido pelo template ([PasswordMin]). Uma mensagem sem o parâmetro [{min}] simplesmente ignora o valor fornecido;
- linhas 50–56: confirmação da senha;
- linha 62: retorno à página de login.
11.17.2.6. Views/PatientArea/Area.cshtml
- linha 8: “Olá, Sr. Jean MARTIN”;
- linhas 12–21: as duas opções são links, exibidos como cartões (classe [option-card], veja [styles.css]);
- linhas 31–46: próximas consultas (normalmente apenas uma). Dentro de um bloco [@if], o formato é [C#]: o loop [for] é escrito sem [@]. Uma borda ([border-bottom]) separa as consultas, exceto após a última;
- linhas 40–44: o cancelamento, um formulário POST com confirmação.
11.17.2.7. Views/PatientArea/Account.cshtml
- linhas 16–76: modificação da conta: identidade, login, nova senha (opcional) e sua confirmação;
- linha 17: a versão do registro do cliente (bloqueio otimista);
- linhas 59–69: a senha atual, obrigatória para qualquer alteração;
- Linhas 83–91: a exclusão, com confirmação. Dois formulários independentes na mesma página: cada um envia apenas os seus próprios campos. O campo de senha tem, portanto, um nome diferente aqui ([deletePassword]) e um identificador diferente. Este formulário não tem o atributo [novalidate]: o navegador exige a senha ([required]) antes mesmo de disparar o evento [submit] — ou seja, antes de fazer a pergunta de confirmação.
11.17.2.8. Views/Shared/Error.cshtml
- Linhas 9–10: a página de erro gerada por [ErrorController] (400, 403, 404, 500): o código HTTP e a mensagem traduzida. Armazenada em [Views/Shared], ela é encontrada independentemente de qual controller a solicite.
11.18. Os dicionários
Os dicionários são os da versão [NestJS], sem alterações: eles são lidos pelo serviço [Translator] (veja o Exemplo 22).
11.18.1. i18n/fr.json
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 | |
- As seções agrupam os textos por página ([LOGIN], [SCHEDULE], [AREA]...) ou por tema ([ERRORS], [CONFIRMATION]). Alguns nomes ([DOCTOR_DAY_PICKER], [BOOKING_DIALOG]) correspondem a componentes do cliente [Angular], cujos dicionários foram herdados pela versão [NestJS];
- linha 80: um texto com dois parâmetros, [{name}] e [{login}], que são substituídos durante a tradução;
- Linhas 98–136: mensagens de erro. São as chaves usadas pelos componentes [BusinessException] na camada de negócio, pelos atributos de validação dos formulários ([ErrorMessage = "ERRORS.FIRSTNAME_REQUIRED"]), pelos controllers e pelo filtro de exceção. Três delas têm um parâmetro: [{minutes}] e [{min}].
11.18.2. i18n/en.json
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 | |
O dicionário em inglês tem exatamente as mesmas chaves.
11.19. Arquivos estáticos
A pasta [wwwroot] é servida por [UseStaticFiles] (veja o Exemplo 15). A pasta [wwwroot/lib/bootstrap] contém o [Bootstrap] (sua folha de estilo [css/bootstrap.min.css] e sua licença), que não são exibidos.
11.19.1. wwwroot/css/styles.css
- linhas 10–12: um intervalo reservável muda de cor ao passar o mouse;
- linhas 23–33: a área de erro, sobre um fundo rosa claro. [position: sticky] e [bottom: 1rem]: se a página for mais alta que a janela, a área permanece na parte inferior da janela em vez de desaparecer da tela; [z-index] a coloca acima do fundo cinza da janela de reserva;
- linhas 36–43: as duas opções “My area” respondem ao mouseover;
- linhas 46–50: a moldura da imagem do CAPTCHA.
11.19.2. wwwroot/js/app.js
O script da janela de confirmação do exemplo 21, enriquecido com o tratamento do teclado. Ele segue o mesmo princípio de aprimoramento progressivo: sem [JavaScript], os formulários são enviados sem confirmação, e a aplicação continua funcionando.
- Linhas 16–19: uma página sem janela de confirmação não tem nada a fazer;
- linha 24: o elemento que tinha o foco do teclado (aquele que recebe as teclas digitadas) antes da abertura da janela: o foco é devolvido a ele quando a janela é fechada;
- Linhas 26–35: o foco é colocado em “No, go back”; pressionar Enter por engano não exclui nada;
- linhas 37–43: a janela é ocultada e o foco é restaurado;
- linhas 46–51: interceptamos o envio dos formulários que possuem o atributo [data-confirmation], como no exemplo 21;
- Linhas 54–67: “Yes”, “No”, o botão de fechar e o clique fora da janela. [closest('[data-action]')] encontra o elemento que contém o atributo, mesmo que o clique tenha ocorrido em um elemento interno a ele. O operador [?.] retorna [undefined] em vez de falhar quando nenhum elemento é encontrado;
- linhas 71–86: a tecla Esc fecha a janela; a tecla Tab (e Shift+Tab) faz o foco circular entre os botões da janela, em vez de deixá-lo passar para a página acinzentada ao fundo.