Skip to content

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

Image

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:

Image

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

Image

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:

Image

Image

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:

Image

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):

Image

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:

Image

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:

Image

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

Image

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:

Image

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

Image

11.2.4. Gerenciamento de médicos e clientes

O administrador tem dois menus adicionais, “Doctors” e “Patients”:

Image

Image

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

Image

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

Image

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

Image

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:

Image

Image

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:

rdvmedecins2-aspnetcore-mvc/
├── Auth/
│   ├── AttemptLimiterService.cs
│   ├── AuthService.cs
│   ├── CaptchaService.cs
│   ├── ConnectedUser.cs
│   ├── InvalidSessionException.cs
│   ├── JwtAuthentication.cs
│   ├── README.md
│   └── RegistrationPassService.cs
├── Business/
│   ├── BusinessException.cs
│   ├── BusinessService.cs
│   ├── Dates.cs
│   ├── IBusiness.cs
│   └── README.md
├── Config/
│   ├── AuthOptions.cs
│   ├── ProtectionOptions.cs
│   └── README.md
├── Controllers/
│   ├── AuthController.cs
│   ├── ClientsController.cs
│   ├── DoctorsController.cs
│   ├── ErrorController.cs
│   ├── LanguageController.cs
│   ├── PatientAreaController.cs
│   ├── PersonsControllerBase.cs
│   ├── README.md
│   ├── RegistrationController.cs
│   └── ScheduleController.cs
├── Data/
│   ├── RdvMedecinsDbContext.cs
│   └── README.md
├── database/
│   ├── dbrdvmedecins2.sql
│   └── README.md
├── Domain/
│   ├── DoctorDaySchedule.cs
│   ├── DoctorDaySlot.cs
│   └── README.md
├── Entities/
│   ├── AbstractEntity.cs
│   ├── Appointment.cs
│   ├── Client.cs
│   ├── Doctor.cs
│   ├── Person.cs
│   ├── README.md
│   ├── Role.cs
│   ├── Slot.cs
│   └── User.cs
├── i18n/
│   ├── en.json
│   └── fr.json
├── Models/
│   ├── Forms.cs
│   ├── README.md
│   └── ViewModels.cs
├── Properties/
│   └── launchSettings.json
├── Repositories/
│   ├── AppointmentRepository.cs
│   ├── PersonRepository.cs
│   ├── README.md
│   ├── SlotRepository.cs
│   └── UserRepository.cs
├── Views/
│   ├── Auth/
│   │   ├── _Captcha.cshtml
│   │   └── Login.cshtml
│   ├── PatientArea/
│   │   ├── Account.cshtml
│   │   └── Area.cshtml
│   ├── Persons/
│   │   ├── Form.cshtml
│   │   └── List.cshtml
│   ├── Registration/
│   │   └── Registration.cshtml
│   ├── Schedule/
│   │   ├── _Booking.cshtml
│   │   └── Schedule.cshtml
│   ├── Shared/
│   │   ├── _Confirmation.cshtml
│   │   ├── _Errors.cshtml
│   │   ├── _Flash.cshtml
│   │   ├── _Layout.cshtml
│   │   ├── _Navbar.cshtml
│   │   ├── _PersonFields.cshtml
│   │   └── Error.cshtml
│   ├── _ViewImports.cshtml
│   ├── _ViewStart.cshtml
│   └── README.md
├── Web/
│   ├── ApplicationModel.cs
│   ├── Flash.cs
│   ├── HtmlExceptionFilter.cs
│   ├── README.md
│   ├── Translator.cs
│   ├── Utils.cs
│   ├── Validation.cs
│   └── ViewPage.cs
├── wwwroot/
│   ├── css/
│   │   └── styles.css
│   ├── js/
│   │   └── app.js
│   └── lib/
│       └── bootstrap/
│           ├── css/
│           │   └── bootstrap.min.css
│           └── LICENSE
├── .gitignore
├── appsettings.Development.json
├── appsettings.json
├── Program.cs
├── RdvMedecins.csproj
└── README.md

Cada pasta contém um arquivo chamado [README.md] que lista seus arquivos. O console na inicialização:

dotnet run
Using launch settings from Properties/launchSettings.json...
Building...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:8081
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development
info: Microsoft.Hosting.Lifetime[0]
      Content root path: C:\course\rdvmedecins2-aspnetcore-mvc

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

Image

  • [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

-- =========================================================================
-- Banco de dados [dbrdvmedecins2] - MySQL 8
--
-- Evolução de [dbrdvmedecins]:
--   1. as tabelas [doctors] e [clients] ganham uma coluna [user],
--      chave estrangeira para users(id): todo médico e todo cliente é
--      agora também um usuário capaz de fazer login;
--   2. surge um terceiro papel: DOCTOR (além de ADMIN e USER);
--   3. o script cria uma linha em [users] para cada médico (papel DOCTOR)
--      e para cada cliente (papel USER):
--        - login        = sobrenome em minúsculas
--        - senha        = sobrenome em minúsculas, com hash bcrypt (10 rodadas)
--        - nome exibido = nome + sobrenome
--
--   4. restrições de unicidade, todas NOMEADAS (a aplicação reconhece
--      o nome da restrição violada na mensagem de erro do MySQL):
--        - unq_users_login                   : um login pertence a uma única conta;
--        - unq_doctors_first_name_last_name  : dois médicos não podem ter o
--                                              mesmo nome e sobrenome;
--        - unq_clients_first_name_last_name  : o mesmo para os clientes.
--      Atenção: a collation utf8mb4_unicode_ci compara sem considerar
--      maiúsculas/minúsculas nem acentos - "Hélène DUPONT" e "helene dupont"
--      são, portanto, consideradas idênticas.
--
-- A tabela [users] agora deve ser criada ANTES de [doctors] e [clients]
-- (elas a referenciam) e removida DEPOIS delas.
-- =========================================================================

-- recomeçamos de um banco de dados vazio a cada execução do script (prático em desenvolvimento)
CREATE DATABASE IF NOT EXISTS dbrdvmedecins2 CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
USE dbrdvmedecins2;

-- ordem de remoção: das tabelas "filhas" para as tabelas "mães"
DROP TABLE IF EXISTS appointments;
DROP TABLE IF EXISTS slots;
DROP TABLE IF EXISTS clients;
DROP TABLE IF EXISTS doctors;
DROP TABLE IF EXISTS users;

-- -------------------------------------------------------------------------
-- tabela [users]: os usuários autorizados a fazer login na aplicação
-- -------------------------------------------------------------------------
CREATE TABLE users (
  id       INT AUTO_INCREMENT PRIMARY KEY,
  version  INT NOT NULL DEFAULT 0,
  login    VARCHAR(30) NOT NULL,                 -- login identifier
  password VARCHAR(100) NOT NULL,                -- HASHED password (bcrypt) - never in clear
  name     VARCHAR(40) NOT NULL,                 -- name displayed once logged in
  role     VARCHAR(10) NOT NULL,                 -- 'ADMIN', 'DOCTOR' or 'USER'
  -- um login só pode pertencer a uma única conta
  CONSTRAINT unq_users_login UNIQUE (login)
);

-- -------------------------------------------------------------------------
-- tabela [doctors]: os médicos do consultório
-- -------------------------------------------------------------------------
CREATE TABLE doctors (
  id         INT AUTO_INCREMENT PRIMARY KEY,   -- primary key (technical identifier)
  version    INT NOT NULL DEFAULT 0,            -- row version number (optimistic lock)
  title      VARCHAR(5)  NOT NULL,              -- Melle, Mme, Mr
  last_name  VARCHAR(20) NOT NULL,
  first_name VARCHAR(20) NOT NULL,
  `user`     INT NOT NULL,                      -- foreign key -> users(id)
  CONSTRAINT fk_doctors_user FOREIGN KEY (`user`) REFERENCES users(id),
  -- uma conta por médico e um médico por conta
  CONSTRAINT unq_doctors_user UNIQUE (`user`),
  -- dois médicos não podem ter o mesmo nome e sobrenome
  CONSTRAINT unq_doctors_first_name_last_name UNIQUE (first_name, last_name)
);

-- -------------------------------------------------------------------------
-- tabela [clients]: os pacientes dos médicos
-- -------------------------------------------------------------------------
CREATE TABLE clients (
  id         INT AUTO_INCREMENT PRIMARY KEY,
  version    INT NOT NULL DEFAULT 0,
  title      VARCHAR(5)  NOT NULL,
  last_name  VARCHAR(20) NOT NULL,
  first_name VARCHAR(20) NOT NULL,
  `user`     INT NOT NULL,                      -- foreign key -> users(id)
  CONSTRAINT fk_clients_user FOREIGN KEY (`user`) REFERENCES users(id),
  -- uma conta por cliente e um cliente por conta
  CONSTRAINT unq_clients_user UNIQUE (`user`),
  -- dois clientes não podem ter o mesmo nome e sobrenome
  CONSTRAINT unq_clients_first_name_last_name UNIQUE (first_name, last_name)
);

-- -------------------------------------------------------------------------
-- tabela [slots]: os horários de cada médico
-- -------------------------------------------------------------------------
CREATE TABLE slots (
  id           INT AUTO_INCREMENT PRIMARY KEY,
  version      INT NOT NULL DEFAULT 0,
  doctor_id    INT NOT NULL,                     -- foreign key -> doctors(id)
  start_hour   INT NOT NULL,                     -- start hour of the slot
  start_minute INT NOT NULL,                     -- start minute of the slot
  end_hour     INT NOT NULL,                     -- end hour of the slot
  end_minute   INT NOT NULL,                     -- end minute of the slot
  CONSTRAINT fk_slots_doctor FOREIGN KEY (doctor_id) REFERENCES doctors(id)
);

-- -------------------------------------------------------------------------
-- tabela [appointments]: as consultas marcadas pelos clientes
-- -------------------------------------------------------------------------
CREATE TABLE appointments (
  id         INT AUTO_INCREMENT PRIMARY KEY,
  version    INT NOT NULL DEFAULT 0,
  day        DATE NOT NULL,                      -- day of the appointment
  slot_id    INT NOT NULL,                       -- foreign key -> slots(id)
  client_id  INT NOT NULL,                       -- foreign key -> clients(id)
  CONSTRAINT fk_appointments_slot   FOREIGN KEY (slot_id)   REFERENCES slots(id),
  CONSTRAINT fk_appointments_client FOREIGN KEY (client_id) REFERENCES clients(id),
  -- o mesmo horário, no mesmo dia, só pode ser reservado uma vez
  CONSTRAINT unq1_appointments UNIQUE (day, slot_id)
);

-- =========================================================================
-- Dados de demonstração
-- =========================================================================

-- os usuários: senhas com hash bcrypt (10 rodadas de salt)
--   admin/admin (ADMIN)
--   uma conta DOCTOR por médico, uma conta USER por cliente
--   (a conta de demonstração user/user não existe mais: uma conta USER é
--   agora SEMPRE a conta de um cliente, que pode marcar consultas e gerenciar a conta)
--   (login = senha = sobrenome em minúsculas)
INSERT INTO users (login, password, name, role) VALUES
  ('admin',     '$2b$10$YSNBJXXHX9mp13nPZb6YGu8M1jR6uvPwO1s2X73z0QAqBR7TOQjoq', 'Administrator',    'ADMIN'),
  -- doctors
  ('pelissier', '$2b$10$DnSDOK5ONrdMxTTr1NKCHOphR3WSp5QAyG9S9ueruw9HwlxI.16ba', 'Marie PELISSIER',  'DOCTOR'),
  ('tatou',     '$2b$10$PeovBO.gmJUKP4PglI/fwu4xtWOYSxoM5VTWjTj7uQ4wcd9P9.htS', 'Paul TATOU',       'DOCTOR'),
  ('dupont',    '$2b$10$az7wvPKC1h0EiAxXwu/PU.vYjzmB04rd5B7QnK0mvxp4niYIHVoc.', 'Sophie DUPONT',    'DOCTOR'),
  -- clients
  ('martin',    '$2b$10$GT6S5pp.WdGapFw/UmocXesbC6LEjJfZzgatCUyG9Sf4o1iBNlqZW', 'Jean MARTIN',      'USER'),
  ('durand',    '$2b$10$l2gl/zCder8E7Nh4VxGRX.0.SsO3FDiXt6YwqYq3v9nFzgC/jQCy6', 'Alice DURAND',     'USER'),
  ('bistrou',   '$2b$10$naeRp2YUU6c.QDl5itJMAum3Y5aHdUV6jwIcsbp0D.64jPG4F6E9m', 'Brigitte BISTROU', 'USER'),
  ('german',    '$2b$10$tTWxh3ROWF7NjhZOMnWDMOsZcnSWUiwwfy5C3G0.xhccTXALKyLeW', 'Luc GERMAN',       'USER');

-- os médicos: a coluna [user] é obtida a partir do login,
-- em vez de presumir os valores das chaves primárias de [users]
INSERT INTO doctors (title, last_name, first_name, `user`) VALUES
  ('Mme',  'PELISSIER', 'Marie',  (SELECT id FROM users WHERE login = 'pelissier')),
  ('Mr',   'TATOU',     'Paul',   (SELECT id FROM users WHERE login = 'tatou')),
  ('Melle','DUPONT',    'Sophie', (SELECT id FROM users WHERE login = 'dupont'));

INSERT INTO clients (title, last_name, first_name, `user`) VALUES
  ('Mr',   'MARTIN',  'Jean',     (SELECT id FROM users WHERE login = 'martin')),
  ('Mme',  'DURAND',  'Alice',    (SELECT id FROM users WHERE login = 'durand')),
  ('Melle','BISTROU', 'Brigitte', (SELECT id FROM users WHERE login = 'bistrou')),
  ('Mr',   'GERMAN',  'Luc',      (SELECT id FROM users WHERE login = 'german'));

-- horários do médico PELISSIER (doctor_id = 1): das 8:00 às 12:00 em intervalos de 20 minutos
INSERT INTO slots (doctor_id, start_hour, start_minute, end_hour, end_minute) VALUES
  (1, 8, 0, 8, 20), (1, 8, 20, 8, 40), (1, 8, 40, 9, 0),
  (1, 9, 0, 9, 20), (1, 9, 20, 9, 40), (1, 9, 40, 10, 0),
  (1, 10, 0, 10, 20), (1, 10, 20, 10, 40), (1, 10, 40, 11, 0),
  (1, 11, 0, 11, 20), (1, 11, 20, 11, 40), (1, 11, 40, 12, 0);

-- horários do médico TATOU (doctor_id = 2): das 14:00 às 18:00 em intervalos de 20 minutos
INSERT INTO slots (doctor_id, start_hour, start_minute, end_hour, end_minute) VALUES
  (2, 14, 0, 14, 20), (2, 14, 20, 14, 40), (2, 14, 40, 15, 0),
  (2, 15, 0, 15, 20), (2, 15, 20, 15, 40), (2, 15, 40, 16, 0),
  (2, 16, 0, 16, 20), (2, 16, 20, 16, 40), (2, 16, 40, 17, 0),
  (2, 17, 0, 17, 20), (2, 17, 20, 17, 40), (2, 17, 40, 18, 0);

-- uma consulta já marcada, para ver de imediato um horário ocupado na agenda
INSERT INTO appointments (day, slot_id, client_id) VALUES
  (CURDATE(), 2, 3);

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

<!--
  =========================================================================
  RdvMedecins.csproj - o arquivo de projeto (o equivalente a package.json).

  Microsoft.NET.Sdk.Web: o SDK das aplicações ASP.NET Core. Por si só ele
  traz todo o framework web (MVC, views Razor, autenticação,
  localização, arquivos estáticos...): somente as bibliotecas
  EXTERNAS ao framework são listadas abaixo (PackageReference) e
  baixadas de nuget.org por [dotnet restore] / [dotnet build].
  =========================================================================
-->
<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <!-- .NET 10, versão LTS (suporte de longo prazo) -->
    <TargetFramework>net10.0</TargetFramework>
    <!-- tipos de referência "nullable": o compilador sinaliza os riscos de
         NullReferenceException (o equivalente a strictNullChecks no TypeScript) -->
    <Nullable>enable</Nullable>
    <!-- implicit usings: System, System.Linq, System.Threading.Tasks... -->
    <ImplicitUsings>enable</ImplicitUsings>
    <RootNamespace>RdvMedecins</RootNamespace>
  </PropertyGroup>

  <ItemGroup>
    <!-- Entity Framework Core + seu provider para MySQL / MariaDB.
         O próprio Pomelo traz Microsoft.EntityFrameworkCore (e MySqlConnector,
         o driver ADO.NET) na versão compatível com ele. -->
    <PackageReference Include="Pomelo.EntityFrameworkCore.MySql" Version="9.0.0" />
    <!-- autenticação por token JWT (leitura e verificação do token) -->
    <PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="10.0.0" />
    <!-- hash de senhas (bcrypt), compatível com os
         hashes $2b$ do script SQL -->
    <PackageReference Include="BCrypt.Net-Next" Version="4.0.3" />
  </ItemGroup>

  <ItemGroup>
    <!-- os dicionários de tradução são lidos na inicialização. O SDK Web
         já coloca todos os arquivos .json entre os arquivos a publicar (Content):
         apenas especificamos que sempre sejam copiados (dotnet publish) -->
    <Content Update="i18n\*.json" CopyToPublishDirectory="PreserveNewest" />
    <!-- o script SQL não precisa ser publicado -->
    <Content Remove="database\**" />
    <None Include="database\**" />
  </ItemGroup>

</Project>

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).

// =========================================================================
// appsettings.json - a configuração da aplicação (o equivalente ao
// arquivo .env do projeto NestJS). O ASP.NET Core aceita comentários
// neste arquivo JSON.
//
// Os valores sensíveis (senha do MySQL, segredo JWT) podem ser
// substituídos sem tocar neste arquivo: variáveis de ambiente ou
// "user secrets" (veja README.md, seção Configuração).
// =========================================================================
{
  // porta de escuta. O servidor JSON já escuta na 8080: escolhemos outra
  // porta para poder executar os dois ao mesmo tempo.
  "Urls": "http://localhost:8081",

  // conexão com o banco de dados MySQL [dbrdvmedecins2] (script: database/dbrdvmedecins2.sql)
  "ConnectionStrings": {
    "RdvMedecins": "Server=localhost;Port=3306;Database=dbrdvmedecins2;User=root;Password=;"
  },
  "MySql": {
    // versão do servidor, para que o EF Core gere o dialeto SQL correto:
    // "8.0.0-mysql" para MySQL 8, "10.11.0-mariadb" para MariaDB 10.11...
    "ServerVersion": "8.0.0-mysql"
  },

  // autenticação (veja Auth/)
  "Auth": {
    // chave secreta dos tokens JWT: pelo menos 32 caracteres (HMAC-SHA256).
    // Deve ser absolutamente trocada em produção (string aleatória longa).
    "JwtSecret": "change-me-to-a-long-random-string",
    // duração de validade de um token, em segundos (7200 s = 2 h); o cookie
    // que carrega o token tem o mesmo tempo de vida
    "JwtExpiresInSeconds": 7200,
    // true em produção (site servido via HTTPS): o cookie de autenticação
    // nunca é enviado por uma conexão não criptografada
    "CookieSecure": false
  },

  // proteção contra robôs (veja Auth/AttemptLimiterService.cs)
  "Protection": {
    // login: falhas permitidas para o mesmo login a partir do mesmo endereço IP...
    "LoginMaxFailures": 5,
    // ... antes de um bloqueio dessa duração (o endereço IP inteiro também é
    // bloqueado se acumular 5 vezes mais falhas, todos os logins somados)
    "LoginBlockMinutes": 15,
    // criação de conta de cliente: no máximo este número de contas criadas por hora e por
    // endereço IP. Em uma sala de aula, todos os computadores costumam sair pelo
    // mesmo endereço: aumente se necessário.
    "RegistrationMaxPerHour": 10
  },

  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Microsoft.EntityFrameworkCore": "Warning"
    }
  },
  "AllowedHosts": "*"
}

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 [__]:

export ConnectionStrings__RdvMedecins="Server=localhost;Port=3306;Database=dbrdvmedecins2;User=root;Password=myPassword;"

O arquivo [README.md] da aplicação detalha essas opções.

11.6.3. appsettings.Development.json

// Sobrescrita de appsettings.json em desenvolvimento (ASPNETCORE_ENVIRONMENT=
// Development, veja Properties/launchSettings.json): exibimos no
// console as consultas SQL geradas pelo EF Core, como fazia a
// opção logging: true do TypeORM.
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Microsoft.EntityFrameworkCore.Database.Command": "Information"
    }
  }
}
  • 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

{
  "$schema": "https://json.schemastore.org/launchsettings.json",
  "profiles": {
    "http": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "http://localhost:8081",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

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

// =========================================================================
// Config/AuthOptions.cs
// -------------------------------------------------------------------------
// A seção "Auth" de appsettings.json, como uma classe tipada.
//
// É o "options pattern" do ASP.NET Core: em
// Program.cs, builder.Services.Configure<AuthOptions>(...) vincula a seção
// à classe; uma classe que precise dela recebe então IOptions<AuthOptions>
// por injeção de dependência. Evitamos assim ler strings
// por todo lado, como fazia process.env.JWT_SECRET.
// =========================================================================

namespace RdvMedecins.Config;

public class AuthOptions
{
    public const string Section = "Auth";

    // chave secreta usada para assinar / verificar os tokens JWT. O algoritmo
    // HMAC-SHA256 exige uma chave de pelo menos 256 bits, ou seja, 32 bytes.
    public string JwtSecret { get; set; } = "";

    // duração de validade de um token, em segundos; o cookie que o carrega
    // tem o mesmo tempo de vida
    public int JwtExpiresInSeconds { get; set; } = 7200;

    // true em produção (HTTPS): o cookie de autenticação nunca é
    // enviado por uma conexão não criptografada
    public bool CookieSecure { get; set; }
}

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

// =========================================================================
// Config/ProtectionOptions.cs
// -------------------------------------------------------------------------
// A seção "Protection" de appsettings.json: os limites da proteção
// contra robôs (veja Auth/AttemptLimiterService.cs).
// =========================================================================

namespace RdvMedecins.Config;

public class ProtectionOptions
{
    public const string Section = "Protection";

    // login: número de falhas (captcha ou senha errados) permitidas
    // para o mesmo login a partir do mesmo endereço IP, antes de esse par ser bloqueado...
    public int LoginMaxFailures { get; set; } = 5;

    // ... por esta duração (um endereço IP também é bloqueado se acumular
    // 5 vezes mais falhas, todos os logins somados)
    public int LoginBlockMinutes { get; set; } = 15;

    // criação de conta de cliente: número máximo de contas criadas por hora
    // a partir do mesmo endereço IP. Em uma sala de aula, todos os computadores costumam sair
    // pelo mesmo endereço: aumente se necessário.
    public int RegistrationMaxPerHour { get; set; } = 10;
}
  • 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

// =========================================================================
// Program.cs
// -------------------------------------------------------------------------
// O ponto de entrada da aplicação: o equivalente a main.ts
// (inicialização, middlewares) e app.module.ts (quem fornece o quê) juntos.
//
// Duas etapas, sempre nesta ordem:
//
//   1. builder.Services... : REGISTRAMOS os serviços no contêiner de injeção de
//      dependência (o equivalente aos "providers" dos
//      módulos do NestJS). Cada serviço tem um TEMPO DE VIDA:
//        - Singleton : uma única instância para toda a aplicação;
//        - Scoped    : uma instância por requisição HTTP (o DbContext e tudo
//                      que o usa);
//        - Transient : uma nova instância a cada vez que é solicitada.
//
//   2. app.Use... : construímos o PIPELINE de middlewares, pelo qual toda
//      requisição passa na ordem em que foram declarados.
// =========================================================================

using System.Globalization;
using System.Text.Encodings.Web;
using System.Text.Unicode;
using Microsoft.AspNetCore.Localization;
using Microsoft.EntityFrameworkCore;
using RdvMedecins.Auth;
using RdvMedecins.Config;
using RdvMedecins.Data;
using RdvMedecins.Business;
using RdvMedecins.Repositories;
using RdvMedecins.Web;

var builder = WebApplication.CreateBuilder(args);

// =========================================================================
// 1. os serviços
// =========================================================================

// - a configuração tipada (seções de appsettings.json, veja Config/)
builder.Services.Configure<AuthOptions>(builder.Configuration.GetSection(AuthOptions.Section));
builder.Services.Configure<ProtectionOptions>(builder.Configuration.GetSection(ProtectionOptions.Section));
var authOptions = builder.Configuration.GetSection(AuthOptions.Section).Get<AuthOptions>() ?? new AuthOptions();
  • 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

// - Entity Framework Core: o DbContext, um por requisição (Scoped).
// UseMySql: o provider Pomelo para MySQL / MariaDB. A versão do
// servidor indica a ele qual dialeto SQL gerar.
var connectionString = builder.Configuration.GetConnectionString("RdvMedecins")
    ?? throw new InvalidOperationException("ConnectionStrings:RdvMedecins missing from appsettings.json");
var serverVersion = ServerVersion.Parse(builder.Configuration["MySql:ServerVersion"] ?? "8.0.0-mysql");
builder.Services.AddDbContext<RdvMedecinsDbContext>(options => options.UseMySql(connectionString, serverVersion));

// - camada DAO e camada de negócio: Scoped, como o DbContext do qual
// dependem (um serviço nunca deve viver MAIS do que suas dependências)
builder.Services.AddScoped<DoctorRepository>();
builder.Services.AddScoped<ClientRepository>();
builder.Services.AddScoped<SlotRepository>();
builder.Services.AddScoped<AppointmentRepository>();
builder.Services.AddScoped<UserRepository>();
// "quando um IBusiness for solicitado, forneça um BusinessService" (NestJS:
// { provide: BUSINESS_TOKEN, useClass: BusinessService }). Em C#, a própria interface
// serve de token de injeção.
builder.Services.AddScoped<IBusiness, BusinessService>();

// - o cache (singleton) e sua fachada (scoped), veja Web/ApplicationModel.cs
builder.Services.AddSingleton<ListCache>();
builder.Services.AddScoped<ApplicationModel>();
  • 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

// - autenticação
builder.Services.AddScoped<AuthService>();
builder.Services.AddSingleton<CaptchaService>(); // captchas pendentes: em memória
builder.Services.AddSingleton<AttemptLimiterService>(); // contadores: em memória
builder.Services.AddSingleton<RegistrationPassService>(); // passes: em memória
builder.Services.AddJwtAuthentication(authOptions); // veja Auth/JwtAuthentication.cs
builder.Services.AddAuthorization();

// - tradução
builder.Services.AddSingleton<Translator>();

// - o codificador HTML do Razor. Por padrão, ele substitui todo caractere
// não ASCII por uma entidade ("é" -> "&#xE9;"): a página é exibida corretamente,
// mas seu código-fonte fica ilegível. Permitimos que ele escreva como estão
// os caracteres de todos os idiomas; < > & " ' são, por sua vez, sempre escapados.
builder.Services.AddSingleton(HtmlEncoder.Create(UnicodeRanges.All));
  • 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

// - MVC: controllers + views Razor
builder.Services.AddControllersWithViews(options =>
{
    // InvalidSessionException -> volta à página de login
    options.Filters.Add<HtmlExceptionFilter>();

    // com os tipos "nullable" habilitados, o MVC trata automaticamente uma propriedade
    // string (não anulável) como obrigatória. Preferimos dizê-lo nós mesmos,
    // explicitamente, com [Required] (veja Models/Forms.cs).
    options.SuppressImplicitRequiredAttributeForNonNullableReferenceTypes = true;

    // as mensagens dos erros de BINDING (um texto onde se espera um número:
    // version="abc"...) também são chaves de tradução
    var messages = options.ModelBindingMessageProvider;
    messages.SetValueMustNotBeNullAccessor(_ => "ERRORS.INVALID_FORM");
    messages.SetAttemptedValueIsInvalidAccessor((_, _) => "ERRORS.INVALID_FORM");
    messages.SetValueIsInvalidAccessor(_ => "ERRORS.INVALID_FORM");
    messages.SetValueMustBeANumberAccessor(_ => "ERRORS.INVALID_FORM");
    messages.SetUnknownValueIsInvalidAccessor(_ => "ERRORS.INVALID_FORM");
    messages.SetNonPropertyAttemptedValueIsInvalidAccessor(_ => "ERRORS.INVALID_FORM");
    messages.SetNonPropertyUnknownValueIsInvalidAccessor(() => "ERRORS.INVALID_FORM");
    messages.SetNonPropertyValueMustBeANumberAccessor(() => "ERRORS.INVALID_FORM");
    messages.SetMissingBindRequiredValueAccessor(_ => "ERRORS.INVALID_FORM");
    messages.SetMissingKeyOrValueAccessor(() => "ERRORS.INVALID_FORM");
    messages.SetMissingRequestBodyRequiredValueAccessor(() => "ERRORS.INVALID_FORM");
});
  • 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

var app = builder.Build();

// =========================================================================
// carga do cache (listas de médicos e de clientes). Os serviços scoped
// só existem dentro de um "escopo" (normalmente: uma requisição): criamos
// um, pelo tempo desta carga. Banco de dados inacessível -> a aplicação
// para aqui, com a exceção do EF Core no console.
// =========================================================================
using (var scope = app.Services.CreateScope())
{
    await scope.ServiceProvider.GetRequiredService<ApplicationModel>().LoadAsync();
}
  • 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

// =========================================================================
// 2. o pipeline de middlewares: a ORDEM importa
// =========================================================================

// - os erros viram páginas HTML (veja Web/HtmlExceptionFilter.cs):
// exceção não tratada -> página 500 (a exceção é gravada no log);
// resposta 400 / 403 / 404 sem conteúdo -> página de erro correspondente
app.UseExceptionHandler("/error/500");
app.UseStatusCodePagesWithReExecute("/error/{0}");

// - arquivos estáticos da pasta wwwroot/: /css/..., /js/..., /lib/bootstrap/...
app.UseStaticFiles();

// - o idioma de cada requisição: lido de um cookie (veja LanguageController),
// inglês por padrão. Ele define CultureInfo.CurrentCulture (formatos de data)
// e CultureInfo.CurrentUICulture (idioma dos textos, veja Web/Translator.cs).
var cultures = Translator.Languages.Select(l => new CultureInfo(l)).ToList();
var localization = new RequestLocalizationOptions
{
    DefaultRequestCulture = new RequestCulture(Translator.DefaultLanguage),
    SupportedCultures = cultures,
    SupportedUICultures = cultures,
};
// somente o cookie decide (nem o idioma do navegador, nem um parâmetro de URL)
localization.RequestCultureProviders = [new CookieRequestCultureProvider()];
app.UseRequestLocalization(localization);

// - roteamento, depois autenticação (quem é? -> HttpContext.User, a partir
// do token), depois autorização (é permitido? -> [Authorize])
app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();

// - os controllers, com suas rotas declaradas por atributos ([HttpGet("...")])
app.MapControllers();

app.Run();

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

// =========================================================================
// Entities/AbstractEntity.cs
// -------------------------------------------------------------------------
// Os dois campos comuns a todas as entidades: o identificador [id] e o
// número de versão [version] (bloqueio otimista).
//
// Como no TypeORM (e @MappedSuperclass no JPA), basta que uma classe
// ABSTRATA seja a mãe das classes de entidade: o EF Core não cria uma tabela
// para ela, mas adiciona suas propriedades às tabelas das classes filhas.
//
// Os atributos [Key], [Column]... vêm do namespace padrão
// System.ComponentModel.DataAnnotations: o EF Core os lê para construir
// seu "modelo" (qual classe vai em qual tabela, qual propriedade em
// qual coluna). Eles fazem o papel dos decoradores @PrimaryGeneratedColumn,
// @Column do TypeORM.
// =========================================================================

using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace RdvMedecins.Entities;

public abstract class AbstractEntity
{
    // [Key]: a chave primária. Uma chave inteira é, por convenção, gerada
    // pelo banco de dados (coluna AUTO_INCREMENT): o EF Core lê seu valor de volta após
    // cada INSERT.
    [Key]
    [Column("id")]
    public int Id { get; set; }

    // [ConcurrencyCheck]: o bloqueio otimista. Cada UPDATE gerado pelo EF
    // Core carrega a condição "WHERE id = ... AND version = <valor lido>".
    // Se alguém modificou a linha nesse meio-tempo, nenhuma linha é
    // atualizada e o EF Core lança uma DbUpdateConcurrencyException.
    //
    // Diferença com o @VersionColumn do TypeORM: o EF Core NÃO INCREMENTA
    // sozinho um número de versão inteiro. É o nosso DbContext que o faz,
    // logo antes de cada gravação (veja Data/RdvMedecinsDbContext.cs).
    [Column("version")]
    [ConcurrencyCheck]
    public int Version { get; set; }
}
  • 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

// =========================================================================
// Entities/Person.cs
// -------------------------------------------------------------------------
// Classe mãe (sem tabela) das entidades [Doctor] e [Client]: um título, um
// sobrenome, um nome - e a conta de usuário associada (coluna [user]).
//
// Um relacionamento declarado em uma classe abstrata é herdado pelas
// classes filhas exatamente como as colunas: o EF Core adiciona portanto o
// relacionamento [User] à tabela [doctors] E à tabela [clients].
// =========================================================================

using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace RdvMedecins.Entities;

public abstract class Person : AbstractEntity
{
    [Column("title")]
    [MaxLength(5)]
    public string Title { get; set; } = ""; // Melle, Mme, Mr

    [Column("last_name")]
    [MaxLength(20)]
    public string LastName { get; set; } = "";

    [Column("first_name")]
    [MaxLength(20)]
    public string FirstName { get; set; } = "";

    // -----------------------------------------------------------------------
    // O relacionamento com a conta de usuário, em DUAS propriedades: é a
    // forma usual de fazê-lo com o EF Core:
    //   - UserId : a própria chave estrangeira (coluna [user]). Pode ser
    //     lida sem carregar o User completo (TypeORM: @RelationId);
    //   - User   : a "propriedade de navegação", o próprio objeto User. Ela
    //     só é preenchida se for solicitada na consulta (.Include(...),
    //     veja Repositories/); caso contrário, é null.
    // [ForeignKey] liga as duas. A natureza "um para um" do relacionamento
    // (coluna [user] UNIQUE) é especificada em RdvMedecinsDbContext.
    // -----------------------------------------------------------------------
    [Column("user")]
    public int UserId { get; set; }

    // "= null!": prometemos ao compilador ler esta propriedade somente
    // quando ela tiver sido carregada (Include) ou atribuída
    [ForeignKey(nameof(UserId))]
    public User User { get; set; } = null!;
}
  • 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

// =========================================================================
// Entities/Doctor.cs
// -------------------------------------------------------------------------
// Um médico do consultório (tabela [doctors]).
//
// restrição de unicidade SQL: unq_doctors_first_name_last_name (dois médicos
// não podem ter o mesmo nome e sobrenome), criada pelo script SQL e
// reconhecida pelo nome na camada de negócio.
// =========================================================================

using System.ComponentModel.DataAnnotations.Schema;

namespace RdvMedecins.Entities;

[Table("doctors")]
public class Doctor : Person
{
    // relacionamento inverso (opcional): os horários deste médico.
    // Ele mostra o relacionamento "1 médico -> vários horários" nos dois
    // sentidos; como toda navegação, só é preenchido sob demanda.
    public List<Slot> Slots { get; set; } = [];
}
  • 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

// =========================================================================
// Entities/Client.cs
// -------------------------------------------------------------------------
// Atenção: [Client] aqui designa um PACIENTE do consultório médico, não um
// cliente HTTP! É o vocabulário do domínio de negócio original, mantido
// como está (tabela [clients]).
//
// restrição de unicidade SQL: unq_clients_first_name_last_name (veja Doctor.cs).
// =========================================================================

using System.ComponentModel.DataAnnotations.Schema;

namespace RdvMedecins.Entities;

[Table("clients")]
public class Client : Person
{
}

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

// =========================================================================
// Entities/Slot.cs
// -------------------------------------------------------------------------
// Um horário de um médico (tabela [slots]): 8:00 - 8:20, etc.
// =========================================================================

using System.ComponentModel.DataAnnotations.Schema;

namespace RdvMedecins.Entities;

[Table("slots")]
public class Slot : AbstractEntity
{
    [Column("start_hour")] public int StartHour { get; set; } // hora de início do horário
    [Column("start_minute")] public int StartMinute { get; set; } // minuto de início do horário
    [Column("end_hour")] public int EndHour { get; set; } // hora de término do horário
    [Column("end_minute")] public int EndMinute { get; set; } // minuto de término do horário

    // vários horários para o mesmo médico: chave estrangeira [doctor_id]
    // + navegação [Doctor] (mesma técnica de Person.UserId / User)
    [Column("doctor_id")]
    public int DoctorId { get; set; }

    [ForeignKey(nameof(DoctorId))]
    public Doctor Doctor { get; set; } = null!;
}
  • 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

// =========================================================================
// Entities/Appointment.cs
// -------------------------------------------------------------------------
// Uma consulta (tabela [appointments]): um cliente, em um horário, em um dia determinado.
//
// restrição de unicidade SQL: unq1_appointments (day, slot_id): um horário só é
// reservado uma vez por dia. Criada pelo script SQL e reconhecida pelo
// nome na camada de negócio.
// =========================================================================

using System.ComponentModel.DataAnnotations.Schema;

namespace RdvMedecins.Entities;

[Table("appointments")]
public class Appointment : AbstractEntity
{
    // DateOnly: uma data SEM hora, que corresponde exatamente ao tipo SQL
    // DATE da coluna [day]. (O projeto NestJS usava uma string
    // "yyyy-MM-dd": o JavaScript não tem um tipo "data sem hora".)
    // Dois valores DateOnly são comparados diretamente: day < today...
    [Column("day")]
    public DateOnly Day { get; set; }

    [Column("client_id")]
    public int ClientId { get; set; }

    [ForeignKey(nameof(ClientId))]
    public Client Client { get; set; } = null!;

    [Column("slot_id")]
    public int SlotId { get; set; }

    [ForeignKey(nameof(SlotId))]
    public Slot Slot { get; set; } = null!;
}
  • 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

// =========================================================================
// Entities/Role.cs
// -------------------------------------------------------------------------
// Os três papéis de um usuário (coluna users.role):
//   - ADMIN  : o administrador: consultas + gestão de médicos e clientes;
//   - DOCTOR : um médico: marca e cancela consultas;
//   - USER   : um cliente (paciente): marca para si mesmo, gerencia sua conta.
//
// Em C#, uma enumeração (enum) em vez de um tipo união de strings
// ('ADMIN' | 'DOCTOR' | 'USER'): o compilador recusa qualquer outro valor.
// O EF Core a armazena no banco de dados como TEXT ('ADMIN'...), como faz o
// script SQL (veja HasConversion<string>() em RdvMedecinsDbContext).
// =========================================================================

namespace RdvMedecins.Entities;

public enum Role
{
    ADMIN,
    DOCTOR,
    USER,
}
  • 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

// =========================================================================
// Entities/User.cs
// -------------------------------------------------------------------------
// Um usuário autorizado a fazer login na aplicação (tabela [users]).
// Cada médico e cada cliente tem SUA própria conta de usuário (coluna [user]
// das tabelas [doctors] e [clients], veja Person.cs).
//
// restrição de unicidade SQL: unq_users_login (um login pertence a uma única
// conta). É criada pelo script database/dbrdvmedecins2.sql;
// a camada de negócio a reconhece pelo NOME (veja Business/BusinessService.cs).
// =========================================================================

using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace RdvMedecins.Entities;

[Table("users")]
public class User : AbstractEntity
{
    [Column("login")]
    [MaxLength(30)]
    public string Login { get; set; } = "";

    // a senha com HASH (bcrypt), nunca em texto claro
    [Column("password")]
    [MaxLength(100)]
    public string Password { get; set; } = "";

    // o nome exibido após o login: para um médico ou um cliente,
    // "firstName LASTNAME" (p. ex. "Marie PELISSIER")
    [Column("name")]
    [MaxLength(40)]
    public string Name { get; set; } = "";

    // ADMIN, DOCTOR ou USER, armazenado no banco de dados como texto
    [Column("role")]
    public Role Role { get; set; }
}
  • 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

// =========================================================================
// Data/RdvMedecinsDbContext.cs
// -------------------------------------------------------------------------
// O DbContext é a peça central do Entity Framework Core. Ele faz ao mesmo
// tempo o papel:
//   - do DataSource do TypeORM: a conexão com o banco de dados;
//   - do Repository<T> do TypeORM: um DbSet<T> por tabela, que é
//     consultado em LINQ (db.Doctors.Where(...)...);
//   - de uma "unidade de trabalho": ele RASTREIA as entidades que
//     carregou (change tracking). Quando uma propriedade é modificada, nada
//     vai para o banco de dados; é SaveChangesAsync() que envia, de uma só vez, os
//     INSERT / UPDATE / DELETE necessários.
//
// Tempo de vida: um DbContext por requisição HTTP (registro "scoped",
// veja Program.cs). Todos os repositórios de uma mesma requisição compartilham portanto o
// MESMO DbContext e, consequentemente, a mesma conexão e a mesma
// transação quando a camada de negócio abre uma.
//
// O mapeamento classe <-> tabela é descrito principalmente pelos atributos
// das entidades ([Table], [Column], [ForeignKey]...); OnModelCreating completa
// o que os atributos não conseguem expressar.
// =========================================================================

using Microsoft.EntityFrameworkCore;
using RdvMedecins.Entities;

namespace RdvMedecins.Data;

public class RdvMedecinsDbContext(DbContextOptions<RdvMedecinsDbContext> options) : DbContext(options)
{
    // uma "tabela" por entidade. Set<T>() retorna o DbSet que o EF Core criou
    // para o tipo T.
    public DbSet<Doctor> Doctors => Set<Doctor>();
    public DbSet<Client> Clients => Set<Client>();
    public DbSet<Slot> Slots => Set<Slot>();
    public DbSet<Appointment> Appointments => Set<Appointment>();
    public DbSet<User> Users => Set<User>();

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        // um médico (um cliente) tem UMA conta, e uma conta pertence a no máximo
        // UMA pessoa (coluna [user] UNIQUE no script SQL): relacionamento "um para um",
        // cuja chave estrangeira é carregada por doctors.user
        // (clients.user). Sem esta precisão, o EF Core suporia "vários
        // médicos para a mesma conta", o que também funcionaria, mas
        // descreveria mal o modelo.
        modelBuilder.Entity<Doctor>().HasOne(d => d.User).WithOne().HasForeignKey<Doctor>(d => d.UserId);
        modelBuilder.Entity<Client>().HasOne(c => c.User).WithOne().HasForeignKey<Client>(c => c.UserId);

        // o papel é uma enumeração C#, armazenada no banco de dados como texto
        // ('ADMIN', 'DOCTOR', 'USER') e não como número (0, 1, 2)
        modelBuilder.Entity<User>().Property(u => u.Role).HasConversion<string>();
    }

    // -----------------------------------------------------------------------
    // O bloqueio otimista (veja AbstractEntity.Version): logo antes de cada
    // gravação, incrementamos a versão de toda entidade MODIFICADA.
    // O EF Core compara o valor ANTIGO (o lido do banco de dados) na
    // cláusula WHERE do UPDATE e grava o novo:
    //     UPDATE doctors SET last_name = ..., version = 4 WHERE id = 1 AND version = 3
    //
    // ChangeTracker: o "change tracking" do DbContext. Ele sabe, para
    // cada entidade carregada, se foi adicionada (Added), modificada
    // (Modified), excluída (Deleted) ou deixada como está (Unchanged).
    //
    // Todas as variantes de SaveChanges(Async) acabam neste método.
    // -----------------------------------------------------------------------
    public override Task<int> SaveChangesAsync(bool acceptAllChangesOnSuccess, CancellationToken cancellationToken = default)
    {
        foreach (var entry in ChangeTracker.Entries<AbstractEntity>())
        {
            if (entry.State == EntityState.Modified)
            {
                entry.Entity.Version++;
            }
        }
        return base.SaveChangesAsync(acceptAllChangesOnSuccess, cancellationToken);
    }
}

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

// =========================================================================
// Domain/DoctorDaySlot.cs
// -------------------------------------------------------------------------
// Um objeto "de negócio" (sem tabela) que associa um horário à
// consulta eventualmente marcada nesse horário, em um dia determinado.
//
// Um "record" C# é uma classe cujas propriedades são definidas uma vez
// por todas pelo construtor (objeto imutável): exatamente o que se precisa
// para um objeto calculado, que ninguém modifica depois.
// =========================================================================

using RdvMedecins.Entities;

namespace RdvMedecins.Domain;

// Appointment? : null se o horário estiver livre nesse dia
public record DoctorDaySlot(Slot Slot, Appointment? Appointment);
  • 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

// =========================================================================
// Domain/DoctorDaySchedule.cs
// -------------------------------------------------------------------------
// A agenda completa de um médico para um dia determinado: a lista de seus
// horários, cada um livre ou ocupado por uma consulta. Calculada por
// BusinessService.GetDoctorDayScheduleAsync, transformada em tabela HTML por
// ScheduleController.
// =========================================================================

using RdvMedecins.Entities;

namespace RdvMedecins.Domain;

public record DoctorDaySchedule(Doctor Doctor, DateOnly Day, List<DoctorDaySlot> DoctorDaySlots);

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.

// =========================================================================
// Repositories/PersonRepository.cs
// -------------------------------------------------------------------------
// A camada DAO comum aos médicos e aos clientes.
//
// Os dois DAOs do projeto NestJS (DoctorRepository, ClientRepository)
// eram idênticos, exceto por uma linha. Em C#, uma classe GENÉRICA os escreve
// uma só vez: PersonRepository<T>, em que T é Doctor ou Client.
// "where T : Person" garante que T tem LastName, FirstName, User...
//
// Transações: os métodos não precisam mais do parâmetro opcional EntityManager
// do TypeORM. Todos os repositórios de uma requisição compartilham o
// MESMO DbContext (veja Data/RdvMedecinsDbContext.cs): quando a camada de negócio
// abre uma transação neste DbContext, todas as suas consultas passam
// automaticamente a fazer parte dela.
// =========================================================================

using Microsoft.EntityFrameworkCore;
using RdvMedecins.Data;
using RdvMedecins.Entities;

namespace RdvMedecins.Repositories;

public abstract class PersonRepository<T>(RdvMedecinsDbContext db) where T : Person
{
    protected readonly RdvMedecinsDbContext db = db;

    // a "tabela" das pessoas do tipo T (db.Doctors ou db.Clients)
    protected DbSet<T> Table => db.Set<T>();

    // lista ordenada por sobrenome e depois por nome, conta de usuário incluída.
    // Include(p => p.User): traz TAMBÉM a conta, por meio de um join
    // (SELECT ... FROM doctors INNER JOIN users ...). Sem isso, p.User
    // seria null.
    // AsNoTracking(): estas listas são mantidas em memória pelo cache
    // (Web/ApplicationModel.cs), muito além da requisição HTTP: é inútil
    // (e custoso) para o DbContext rastreá-las.
    public Task<List<T>> FindAllAsync() =>
        Table.AsNoTracking().Include(p => p.User).OrderBy(p => p.LastName).ThenBy(p => p.FirstName).ToListAsync();

    public Task<T?> FindByIdAsync(int id) =>
        Table.Include(p => p.User).FirstOrDefaultAsync(p => p.Id == id);

    // a pessoa cuja conta de usuário é [userId], ou null
    public Task<T?> FindByUserIdAsync(int userId) =>
        Table.Include(p => p.User).FirstOrDefaultAsync(p => p.UserId == userId);

    // a pessoa que tem este nome e sobrenome, se houver. A comparação
    // é feita pelo MySQL, portanto com a collation do banco de dados
    // (utf8mb4_unicode_ci: sem distinção de maiúsculas e acentos):
    // exatamente a mesma regra da restrição de unicidade SQL.
    public Task<T?> FindByFirstNameLastNameAsync(string firstName, string lastName) =>
        Table.FirstOrDefaultAsync(p => p.FirstName == firstName && p.LastName == lastName);

    // criação (Id = 0: ainda não está no banco de dados) ou atualização (entidade já
    // rastreada pelo DbContext: SaveChanges detecta sozinho o que mudou)
    public async Task<T> SaveAsync(T person)
    {
        if (person.Id == 0)
        {
            Table.Add(person);
        }
        await db.SaveChangesAsync();
        return person;
    }

    // ExecuteDeleteAsync (EF Core 7+): um DELETE enviado diretamente ao banco de dados,
    // sem carregar as entidades antes:  DELETE FROM doctors WHERE id = ?
    public Task DeleteByIdAsync(int id) => Table.Where(p => p.Id == id).ExecuteDeleteAsync();
}

// os dois DAOs concretos: tudo é herdado
public class DoctorRepository(RdvMedecinsDbContext db) : PersonRepository<Doctor>(db);

public class ClientRepository(RdvMedecinsDbContext db) : PersonRepository<Client>(db)
{
    // -----------------------------------------------------------------------
    // lê um cliente colocando um BLOQUEIO em sua linha até o fim da
    // transação atual (SELECT ... FOR UPDATE). Uma segunda transação
    // que solicite o mesmo bloqueio ESPERA a primeira terminar.
    // Usado para marcar consultas (veja BusinessService.AddAppointmentAsync):
    // duas marcações simultâneas para o mesmo paciente são assim processadas
    // uma DEPOIS da outra, e a segunda enxerga a consulta criada pela primeira.
    //
    // o LINQ não consegue expressar "FOR UPDATE": escrevemos a consulta SQL
    // nós mesmos. FromSqlInterpolated transforma {id} em um PARÂMETRO SQL (sem
    // concatenação de strings, portanto sem possibilidade de injeção de SQL).
    // -----------------------------------------------------------------------
    public async Task<Client?> LockAsync(int id)
    {
        var clients = await Table.FromSqlInterpolated($"SELECT * FROM clients WHERE id = {id} FOR UPDATE").ToListAsync();
        return clients.FirstOrDefault();
    }
}

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

// =========================================================================
// Repositories/SlotRepository.cs
// -------------------------------------------------------------------------
// Camada DAO da entidade [Slot].
// =========================================================================

using Microsoft.EntityFrameworkCore;
using RdvMedecins.Data;
using RdvMedecins.Entities;

namespace RdvMedecins.Repositories;

public class SlotRepository(RdvMedecinsDbContext db)
{
    public Task<Slot?> FindByIdAsync(int id) =>
        db.Slots.Include(s => s.Doctor).FirstOrDefaultAsync(s => s.Id == id);

    // os horários de um médico, em ordem cronológica
    public Task<List<Slot>> GetAllSlotsAsync(int doctorId) =>
        db.Slots
            .Where(s => s.DoctorId == doctorId)
            .OrderBy(s => s.StartHour)
            .ThenBy(s => s.StartMinute)
            .ToListAsync();

    // exclui todos os horários de um médico (exclusão de um médico):
    //   DELETE FROM slots WHERE doctor_id = ?
    public Task DeleteByDoctorAsync(int doctorId) =>
        db.Slots.Where(s => s.DoctorId == doctorId).ExecuteDeleteAsync();
}
  • 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

// =========================================================================
// Repositories/AppointmentRepository.cs
// -------------------------------------------------------------------------
// Camada DAO da entidade [Appointment].
//
// As consultas são escritas em LINQ: o EF Core as traduz para SQL. Navegamos
// de uma entidade para outra pelas propriedades de navegação (a.Slot.DoctorId),
// e o EF Core escreve sozinho os joins necessários.
// =========================================================================

using Microsoft.EntityFrameworkCore;
using RdvMedecins.Data;
using RdvMedecins.Entities;

namespace RdvMedecins.Repositories;

public class AppointmentRepository(RdvMedecinsDbContext db)
{
    public Task<Appointment?> FindByIdAsync(int id) =>
        db.Appointments.Include(a => a.Client).Include(a => a.Slot).FirstOrDefaultAsync(a => a.Id == id);

    public async Task<Appointment> SaveAsync(Appointment appointment)
    {
        if (appointment.Id == 0)
        {
            db.Appointments.Add(appointment);
        }
        await db.SaveChangesAsync();
        return appointment;
    }

    public Task DeleteByIdAsync(int id) => db.Appointments.Where(a => a.Id == id).ExecuteDeleteAsync();

    // as consultas de um médico em um dia determinado, cliente e horário incluídos.
    // a.Slot.DoctorId: a tabela [appointments] não referencia o
    // médico diretamente; o EF Core passa pelo join com [slots].
    public Task<List<Appointment>> GetDoctorDayAppointmentsAsync(int doctorId, DateOnly day) =>
        db.Appointments
            .Include(a => a.Client)
            .Include(a => a.Slot)
            .Where(a => a.Slot.DoctorId == doctorId && a.Day == day)
            .ToListAsync();

    // as consultas de um cliente a partir do dia [fromDay] (incluído), em
    // ordem cronológica, com o horário E o médico desse horário
    // (Include e depois ThenInclude: consulta -> horário -> médico)
    public Task<List<Appointment>> FindUpcomingByClientAsync(int clientId, DateOnly fromDay) =>
        db.Appointments
            .Include(a => a.Slot).ThenInclude(s => s.Doctor)
            .Where(a => a.ClientId == clientId && a.Day >= fromDay)
            .OrderBy(a => a.Day)
            .ThenBy(a => a.Slot.StartHour)
            .ThenBy(a => a.Slot.StartMinute)
            .ToListAsync();

    // número de consultas de um cliente a partir do dia [fromDay] (incluído)
    public Task<int> CountUpcomingByClientAsync(int clientId, DateOnly fromDay) =>
        db.Appointments.CountAsync(a => a.ClientId == clientId && a.Day >= fromDay);

    // exclui TODAS as consultas (passadas e futuras) de um cliente:
    //   DELETE FROM appointments WHERE client_id = ?
    public Task DeleteByClientAsync(int clientId) =>
        db.Appointments.Where(a => a.ClientId == clientId).ExecuteDeleteAsync();

    // número de consultas (passadas ou futuras) de um médico:
    //   SELECT COUNT(*) FROM appointments INNER JOIN slots s ON ... WHERE s.doctor_id = ?
    public Task<int> CountByDoctorAsync(int doctorId) =>
        db.Appointments.CountAsync(a => a.Slot.DoctorId == doctorId);
}

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

// =========================================================================
// Repositories/UserRepository.cs
// -------------------------------------------------------------------------
// Camada DAO da entidade [User]. Criar (ou excluir) um médico ou um
// cliente também cria (ou exclui) sua conta: veja Business/BusinessService.cs.
// =========================================================================

using Microsoft.EntityFrameworkCore;
using RdvMedecins.Data;
using RdvMedecins.Entities;

namespace RdvMedecins.Repositories;

public class UserRepository(RdvMedecinsDbContext db)
{
    // null se nenhum usuário tiver este login
    public Task<User?> FindByLoginAsync(string login) => db.Users.FirstOrDefaultAsync(u => u.Login == login);

    public async Task<User> SaveAsync(User user)
    {
        if (user.Id == 0)
        {
            db.Users.Add(user);
        }
        await db.SaveChangesAsync();
        return user;
    }

    public Task DeleteByIdAsync(int id) => db.Users.Where(u => u.Id == id).ExecuteDeleteAsync();
}
  • 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

// =========================================================================
// Business/Dates.cs
// -------------------------------------------------------------------------
// A data de hoje. Ela é usada por REGRAS DE NEGÓCIO (nenhuma marcação
// no passado, uma única consulta FUTURA por paciente): portanto vive
// na camada de negócio. A camada web a reutiliza.
// =========================================================================

namespace RdvMedecins.Business;

public static class Dates
{
    // a data de hoje, no fuso horário do servidor
    public static DateOnly Today() => DateOnly.FromDateTime(DateTime.Now);
}
  • 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

// =========================================================================
// Business/BusinessException.cs
// -------------------------------------------------------------------------
// A exceção lançada pela camada de negócio quando uma REGRA DE NEGÓCIO é
// violada (login já utilizado, médico que ainda tem consultas, horário
// já reservado...). Ela não carrega um texto, mas uma CHAVE de
// tradução (p. ex. "ERRORS.LOGIN_TAKEN"): é a camada web que a
// traduzirá para francês ou inglês ao exibir a página
// (veja i18n/fr.json, i18n/en.json).
//
// Uma BusinessException não é uma anomalia: é uma resposta normal
// ("este login já está em uso"), exibida ao usuário. Qualquer outra
// exceção é uma anomalia real, que termina na página de erro 500.
// =========================================================================

namespace RdvMedecins.Business;

public class BusinessException(string key, IReadOnlyDictionary<string, string>? messageParams = null) : Exception(key)
{
    // chave de tradução da mensagem
    public string Key { get; } = key;

    // possíveis parâmetros da mensagem ({minutes}...)
    public IReadOnlyDictionary<string, string> Params { get; } = messageParams ?? new Dictionary<string, string>();
}
  • 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

// =========================================================================
// Business/IBusiness.cs
// -------------------------------------------------------------------------
// O contrato da camada de negócio: leituras, agenda, consultas, gestão
// dos médicos e dos clientes.
//
// Convenção do .NET: um método assíncrono retorna uma Task<T> (o equivalente
// de uma Promise<T>) e seu nome termina em "Async".
// =========================================================================

using RdvMedecins.Domain;
using RdvMedecins.Entities;

namespace RdvMedecins.Business;

// os dados digitados no formulário de "médico" ou "cliente"
public record PersonData
{
    public required string Title { get; init; } // Mr, Mme, Melle
    public required string LastName { get; init; }
    public required string FirstName { get; init; }

    // criação: opcional, por padrão o sobrenome em minúsculas
    // atualização: opcional, o login não muda se estiver ausente
    public string? Login { get; init; }

    // criação: opcional, por padrão o login
    // atualização: opcional, a senha não muda se estiver ausente
    public string? Password { get; init; }

    // atualização: a versão do registro no momento em que o formulário foi
    // exibido (bloqueio otimista, veja AbstractEntity.Version)
    public int? Version { get; init; }
}

public interface IBusiness
{
    // leituras
    Task<List<Client>> GetAllClientsAsync();
    Task<List<Doctor>> GetAllDoctorsAsync();
    Task<List<Slot>> GetAllSlotsAsync(int doctorId);
    Task<List<Appointment>> GetDoctorDayAppointmentsAsync(int doctorId, DateOnly day);
    Task<Client?> GetClientByIdAsync(int id);
    Task<Doctor?> GetDoctorByIdAsync(int id);
    Task<Appointment?> GetAppointmentByIdAsync(int id);
    Task<Slot?> GetSlotByIdAsync(int id);
    Task<DoctorDaySchedule?> GetDoctorDayScheduleAsync(int doctorId, DateOnly day);

    /// <summary>o cliente (paciente) cuja conta de usuário é [userId], ou null</summary>
    Task<Client?> GetClientByUserIdAsync(int userId);

    /// <summary>as consultas de um cliente, de hoje ou futuras, com horário e médico</summary>
    Task<List<Appointment>> GetClientUpcomingAppointmentsAsync(int clientId);

    // consultas (ADMIN, DOCTOR, USER)
    /// <summary>
    /// lança uma BusinessException se:
    ///  - o dia estiver no passado ("ERRORS.PAST_DATE");
    ///  - o paciente já tiver uma consulta futura ("ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT");
    ///  - o horário já estiver reservado nesse dia ("ERRORS.SLOT_ALREADY_BOOKED").
    /// </summary>
    Task<Appointment> AddAppointmentAsync(DateOnly day, Slot slot, Client client);

    Task DeleteAppointmentAsync(Appointment appointment);

    // médicos (ADMIN)
    /// <summary>cria o médico E sua conta de usuário (papel DOCTOR)</summary>
    Task<Doctor> AddDoctorAsync(PersonData data);

    /// <summary>atualiza o médico E sua conta de usuário</summary>
    Task<Doctor> EditDoctorAsync(int id, PersonData data);

    /// <summary>exclui o médico, seus horários E sua conta: recusado se ele tiver consultas</summary>
    Task DeleteDoctorAsync(int id);

    // clientes
    // (o ADMIN; AddClientAsync também é usado para o cadastro de um paciente,
    // EditClientAsync e DeleteClientAsync pelo paciente para a própria conta)
    /// <summary>cria o cliente E sua conta de usuário (papel USER)</summary>
    Task<Client> AddClientAsync(PersonData data);

    Task<Client> EditClientAsync(int id, PersonData data);

    /// <summary>
    /// exclui o cliente, sua conta E todas as suas consultas (passadas e futuras).
    /// Usado pelo ADMIN (página "Patients") e pelo próprio paciente ("Manage my account").
    /// </summary>
    Task DeleteClientAsync(int id);
}
  • 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

// =========================================================================
// Business/BusinessService.cs
// -------------------------------------------------------------------------
// Implementação da camada de negócio.
//
// A gestão dos médicos e dos clientes obedece a três regras de negócio:
//
//   1. uma pessoa (médico ou cliente) e sua conta de usuário andam
//      SEMPRE juntas: são criadas, atualizadas e excluídas juntas, na
//      mesma TRANSAÇÃO: ou tudo dá certo, ou nada é gravado;
//   2. o login é único em toda a aplicação, e dois médicos (ou
//      dois clientes) não podem ter o mesmo nome e sobrenome;
//   3. exclusão:
//      - um MÉDICO que tem consultas não pode ser excluído (seus
//        pacientes perderiam a consulta sem serem avisados): elas devem
//        antes ser canceladas. Seus horários desaparecem com ele;
//      - um CLIENTE, por outro lado, desaparece com TODAS as suas consultas (passadas e
//        futuras), quer a exclusão venha do ADMIN ou do próprio
//        paciente.
//
// E duas regras para marcar consultas, qualquer que seja o papel de
// quem marca (ADMIN, DOCTOR ou o próprio paciente):
//   4. nenhuma consulta no passado;
//   5. um paciente tem apenas UMA consulta futura por vez.
//
// Médicos e clientes seguem exatamente as mesmas regras: o código comum
// é escrito UMA vez (métodos privados genéricos XxxPersonAsync<T>) e
// parametrizado por um pequeno "descritor" que diz com que tipo de pessoa
// estamos lidando.
// =========================================================================

using System.Text.RegularExpressions;
using Microsoft.EntityFrameworkCore;
using MySqlConnector;
using RdvMedecins.Data;
using RdvMedecins.Domain;
using RdvMedecins.Entities;
using RdvMedecins.Repositories;

namespace RdvMedecins.Business;

public class BusinessService : IBusiness
{
    // número de rodadas de salting do bcrypt: o mesmo do script SQL ($2b$10$...)
    private const int BcryptRounds = 10;

    // tudo o que distingue um médico de um cliente para as regras de negócio.
    // "where T : Person, new()": T é uma Person, e podemos escrever new T().
    private record PersonDescriptor<T>(
        PersonRepository<T> Dao,
        Role Role, // DOCTOR ou USER
        string NotFoundKey, // mensagem se a pessoa não existir
        string AlreadyExistsKey, // mensagem se os mesmos nome e sobrenome já existirem
        // opcional: se presente, a exclusão é RECUSADA enquanto a
        // pessoa tiver consultas (CountAppointments > 0), com a mensagem HasAppointmentsKey
        Func<int, Task<int>>? CountAppointments = null,
        string? HasAppointmentsKey = null,
        // opcional: o que deve ser excluído ANTES da pessoa (as linhas que
        // a referenciam por uma chave estrangeira)
        Func<int, Task>? BeforeDelete = null) where T : Person, new();

    private readonly RdvMedecinsDbContext db;
    private readonly DoctorRepository doctorRepository;
    private readonly ClientRepository clientRepository;
    private readonly SlotRepository slotRepository;
    private readonly AppointmentRepository appointmentRepository;
    private readonly UserRepository userRepository;
    private readonly PersonDescriptor<Doctor> doctorDescriptor;
    private readonly PersonDescriptor<Client> clientDescriptor;

    // todas as dependências são fornecidas pela injeção de dependência
    // do ASP.NET Core (veja Program.cs). O DbContext é usado aqui SOMENTE para abrir
    // transações: as consultas em si permanecem na camada DAO.
    public BusinessService(
        RdvMedecinsDbContext db,
        DoctorRepository doctorRepository,
        ClientRepository clientRepository,
        SlotRepository slotRepository,
        AppointmentRepository appointmentRepository,
        UserRepository userRepository)
    {
        this.db = db;
        this.doctorRepository = doctorRepository;
        this.clientRepository = clientRepository;
        this.slotRepository = slotRepository;
        this.appointmentRepository = appointmentRepository;
        this.userRepository = userRepository;

        doctorDescriptor = new PersonDescriptor<Doctor>(
            doctorRepository,
            Role.DOCTOR,
            "ERRORS.DOCTOR_NOT_FOUND",
            "ERRORS.DOCTOR_ALREADY_EXISTS",
            CountAppointments: appointmentRepository.CountByDoctorAsync,
            HasAppointmentsKey: "ERRORS.DOCTOR_HAS_APPOINTMENTS",
            // um médico sem consultas ainda pode ter horários:
            // eles não fazem mais sentido sem ele, e os excluímos junto com o médico (caso contrário
            // a chave estrangeira slots.doctor_id proibiria a exclusão)
            BeforeDelete: slotRepository.DeleteByDoctorAsync);

        clientDescriptor = new PersonDescriptor<Client>(
            clientRepository,
            Role.USER,
            "ERRORS.PATIENT_NOT_FOUND",
            "ERRORS.PATIENT_ALREADY_EXISTS",
            // sem CountAppointments: a exclusão de um cliente nunca é recusada;
            // suas consultas (passadas e futuras) são excluídas junto com ele (caso contrário
            // a chave estrangeira appointments.client_id proibiria a exclusão)
            BeforeDelete: appointmentRepository.DeleteByClientAsync);
    }
  • 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

    // =======================================================================
    // leituras
    // =======================================================================

    public Task<List<Client>> GetAllClientsAsync() => clientRepository.FindAllAsync();

    public Task<List<Doctor>> GetAllDoctorsAsync() => doctorRepository.FindAllAsync();

    public Task<List<Slot>> GetAllSlotsAsync(int doctorId) => slotRepository.GetAllSlotsAsync(doctorId);

    public Task<List<Appointment>> GetDoctorDayAppointmentsAsync(int doctorId, DateOnly day) =>
        appointmentRepository.GetDoctorDayAppointmentsAsync(doctorId, day);

    public Task<Client?> GetClientByIdAsync(int id) => clientRepository.FindByIdAsync(id);

    public Task<Doctor?> GetDoctorByIdAsync(int id) => doctorRepository.FindByIdAsync(id);

    public Task<Appointment?> GetAppointmentByIdAsync(int id) => appointmentRepository.FindByIdAsync(id);

    public Task<Slot?> GetSlotByIdAsync(int id) => slotRepository.FindByIdAsync(id);

    public Task<Client?> GetClientByUserIdAsync(int userId) => clientRepository.FindByUserIdAsync(userId);

    public Task<List<Appointment>> GetClientUpcomingAppointmentsAsync(int clientId) =>
        appointmentRepository.FindUpcomingByClientAsync(clientId, Dates.Today());

    // mesmo algoritmo do servidor JSON (e do projeto Spring original)
    public async Task<DoctorDaySchedule?> GetDoctorDayScheduleAsync(int doctorId, DateOnly day)
    {
        var doctor = await GetDoctorByIdAsync(doctorId);
        if (doctor is null)
        {
            return null;
        }
        var timeSlots = await GetAllSlotsAsync(doctorId);
        var bookings = await GetDoctorDayAppointmentsAsync(doctorId, day);
        // nº do horário -> consulta marcada nesse horário
        var bookingsBySlot = bookings.ToDictionary(booking => booking.SlotId);
        var doctorDaySlots = timeSlots
            .Select(slot => new DoctorDaySlot(slot, bookingsBySlot.GetValueOrDefault(slot.Id)))
            .ToList();
        return new DoctorDaySchedule(doctor, day, doctorDaySlots);
    }
  • 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

    // =======================================================================
    // consultas
    // =======================================================================

    // -----------------------------------------------------------------------
    // marcação de uma consulta, em uma transação:
    //   1. nenhuma consulta no passado;
    //   2. BLOQUEAMOS a linha do paciente (SELECT ... FOR UPDATE): se o
    //      mesmo paciente marcar dois horários no mesmo instante (duas abas,
    //      clique duplo...), a segunda transação espera o fim da
    //      primeira e então enxerga a consulta que ela acabou de criar;
    //   3. uma única consulta futura por paciente;
    //   4. por fim, a inserção. Se o horário acabou de ser ocupado por OUTRO
    //      paciente, é a restrição SQL unq1_appointments (day, slot_id) que
    //      recusa a inserção, traduzida em BusinessException por TransactionAsync.
    // -----------------------------------------------------------------------
    public Task<Appointment> AddAppointmentAsync(DateOnly day, Slot slot, Client client) =>
        TransactionAsync(async () =>
        {
            var today = Dates.Today();
            if (day < today)
            {
                throw new BusinessException("ERRORS.PAST_DATE");
            }
            if (await clientRepository.LockAsync(client.Id) is null)
            {
                throw new BusinessException("ERRORS.PATIENT_NOT_FOUND");
            }
            if (await appointmentRepository.CountUpcomingByClientAsync(client.Id, today) > 0)
            {
                throw new BusinessException("ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT");
            }
            // preenchemos as chaves estrangeiras: não é preciso anexar os próprios
            // objetos Slot e Client para gravar a linha de [appointments]
            var appointment = new Appointment { Day = day, SlotId = slot.Id, ClientId = client.Id };
            return await appointmentRepository.SaveAsync(appointment);
        });

    public Task DeleteAppointmentAsync(Appointment appointment) => appointmentRepository.DeleteByIdAsync(appointment.Id);
  • 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

    // =======================================================================
    // médicos e clientes: os métodos públicos delegam aos métodos
    // privados comuns, com o descritor correto
    // =======================================================================

    public Task<Doctor> AddDoctorAsync(PersonData data) => AddPersonAsync(doctorDescriptor, data);

    public Task<Doctor> EditDoctorAsync(int id, PersonData data) =>
        EditPersonAsync(doctorDescriptor, id, data);

    public Task DeleteDoctorAsync(int id) => DeletePersonAsync(doctorDescriptor, id);

    public Task<Client> AddClientAsync(PersonData data) => AddPersonAsync(clientDescriptor, data);

    public Task<Client> EditClientAsync(int id, PersonData data) =>
        EditPersonAsync(clientDescriptor, id, data);

    // o cliente, sua conta E todas as suas consultas (ADMIN, ou o próprio paciente
    // a partir de "Manage my account": mesmo método, mesma regra)
    public Task DeleteClientAsync(int id) => DeletePersonAsync(clientDescriptor, id);

    // -----------------------------------------------------------------------
    // criação: primeiro a conta de usuário (a pessoa a referencia),
    // depois a pessoa, tudo em UMA transação.
    // -----------------------------------------------------------------------
    private Task<T> AddPersonAsync<T>(PersonDescriptor<T> d, PersonData data) where T : Person, new()
    {
        var lastName = data.LastName.Trim().ToUpperInvariant();
        var firstName = data.FirstName.Trim();
        // as regras do banco de dados dbrdvmedecins2: login = sobrenome em minúsculas,
        // senha = login, a menos que o ADMIN tenha digitado outros
        var login = (string.IsNullOrEmpty(data.Login) ? lastName : data.Login).ToLowerInvariant();
        var password = string.IsNullOrEmpty(data.Password) ? login : data.Password;

        return TransactionAsync(async () =>
        {
            await CheckPersonUniqueAsync(d, firstName, lastName, null);
            await CheckLoginFreeAsync(login);

            var user = new User
            {
                Login = login,
                Password = BCrypt.Net.BCrypt.HashPassword(password, BcryptRounds),
                Name = $"{firstName} {lastName}",
                Role = d.Role,
            };
            await userRepository.SaveAsync(user);

            var person = new T { Title = data.Title, LastName = lastName, FirstName = firstName, User = user };
            return await d.Dao.SaveAsync(person);
        });
    }

    // -----------------------------------------------------------------------
    // atualização: a pessoa E sua conta (o nome exibido "firstName LASTNAME"
    // deve acompanhar; o login e a senha só mudam se tiverem sido
    // digitados).
    // -----------------------------------------------------------------------
    private Task<T> EditPersonAsync<T>(PersonDescriptor<T> d, int id, PersonData data)
        where T : Person, new() =>
        TransactionAsync(async () =>
        {
            var person = await d.Dao.FindByIdAsync(id) ?? throw new BusinessException(d.NotFoundKey);

            // bloqueio otimista: se a versão no banco de dados não for mais a do
            // formulário, alguém modificou este registro nesse meio-tempo: recusamos
            // em vez de sobrescrever silenciosamente suas alterações.
            // (Se a atualização concorrente ocorrer DEPOIS desta leitura, é
            // a cláusula "WHERE version = ..." do UPDATE que a detecta.)
            if (data.Version is not null && data.Version != person.Version)
            {
                throw new BusinessException("ERRORS.CONCURRENT_UPDATE");
            }

            // apenas modificamos os objetos: o DbContext, que os rastreia,
            // enviará os UPDATEs necessários no próximo SaveChangesAsync
            person.Title = data.Title;
            person.LastName = data.LastName.Trim().ToUpperInvariant();
            person.FirstName = data.FirstName.Trim();
            await CheckPersonUniqueAsync(d, person.FirstName, person.LastName, id);

            var user = person.User;
            user.Name = $"{person.FirstName} {person.LastName}";
            if (!string.IsNullOrEmpty(data.Login) && data.Login.ToLowerInvariant() != user.Login)
            {
                var login = data.Login.ToLowerInvariant();
                await CheckLoginFreeAsync(login);
                user.Login = login;
            }
            if (!string.IsNullOrEmpty(data.Password))
            {
                user.Password = BCrypt.Net.BCrypt.HashPassword(data.Password, BcryptRounds);
            }
            await userRepository.SaveAsync(user);
            return await d.Dao.SaveAsync(person);
        });

    // -----------------------------------------------------------------------
    // exclusão, em UMA transação, na ordem imposta pelas chaves
    // estrangeiras:
    //   1. possível recusa se restarem consultas (médico);
    //   2. o que referencia a pessoa (horários de um médico, consultas
    //      de um cliente);
    //   3. a pessoa (ela referencia sua conta);
    //   4. sua conta.
    // -----------------------------------------------------------------------
    private Task DeletePersonAsync<T>(PersonDescriptor<T> d, int id) where T : Person, new() =>
        TransactionAsync(async () =>
        {
            var person = await d.Dao.FindByIdAsync(id) ?? throw new BusinessException(d.NotFoundKey);
            if (d.CountAppointments is not null && await d.CountAppointments(id) > 0)
            {
                throw new BusinessException(d.HasAppointmentsKey ?? "ERRORS.INVALID_FORM");
            }
            if (d.BeforeDelete is not null)
            {
                await d.BeforeDelete(id);
            }
            await d.Dao.DeleteByIdAsync(id);
            await userRepository.DeleteByIdAsync(person.UserId);
            return true; // TransactionAsync espera um resultado: aqui não precisamos de nenhum
        });

    // recusa nome e sobrenome já usados por OUTRA pessoa do mesmo tipo
    // (currentId: a pessoa sendo atualizada, que obviamente tem o
    // direito de manter o próprio nome e sobrenome; null para uma criação)
    private static async Task CheckPersonUniqueAsync<T>(PersonDescriptor<T> d, string firstName, string lastName, int? currentId)
        where T : Person, new()
    {
        var namesake = await d.Dao.FindByFirstNameLastNameAsync(firstName, lastName);
        if (namesake is not null && namesake.Id != currentId)
        {
            throw new BusinessException(d.AlreadyExistsKey);
        }
    }

    private async Task CheckLoginFreeAsync(string login)
    {
        if (await userRepository.FindByLoginAsync(login) is not null)
        {
            throw new BusinessException("ERRORS.LOGIN_TAKEN");
        }
    }
  • 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

    // -----------------------------------------------------------------------
    // executa [work] em uma transação:
    //   BeginTransactionAsync -> START TRANSACTION;
    //   CommitAsync            -> COMMIT, se tudo correu bem;
    //   se uma exceção for lançada (BusinessException incluída), não fazemos commit:
    //   "await using" fecha a transação ao sair do bloco, e uma
    //   transação fechada sem COMMIT é cancelada (ROLLBACK).
    //
    // As verificações "login livre" e "nome + sobrenome únicos" são feitas ANTES
    // da gravação, para dar uma mensagem clara. Mas dois ADMINs poderiam
    // gravar o mesmo login (ou o mesmo médico) no mesmo instante: neste
    // caso raro, é uma restrição de unicidade SQL que recusa a segunda
    // gravação, e então traduzimos este erro SQL na mesma BusinessException.
    // -----------------------------------------------------------------------
    private async Task<R> TransactionAsync<R>(Func<Task<R>> work)
    {
        await using var transaction = await db.Database.BeginTransactionAsync();
        try
        {
            var result = await work();
            await transaction.CommitAsync();
            return result;
        }
        catch (Exception e)
        {
            // em caso de falha, o DbContext "esquece" tudo o que rastreava: uma
            // entidade deixada no estado Added seria reenviada ao banco de dados no
            // próximo SaveChangesAsync da mesma requisição
            db.ChangeTracker.Clear();
            if (TranslateDatabaseError(e) is { } businessError)
            {
                throw businessError;
            }
            throw; // "throw;" relança a exceção original, com sua pilha de chamadas intacta
        }
    }

    // -----------------------------------------------------------------------
    // Erros do banco de dados -> BusinessException
    //
    // - DbUpdateConcurrencyException: o UPDATE "WHERE id = ... AND version = ..."
    //   não modificou nenhuma linha (bloqueio otimista, veja AbstractEntity);
    // - DbUpdateException cuja causa (InnerException) é o erro MySQL
    //   ER_DUP_ENTRY (nº 1062): uma restrição UNIQUE recusou a gravação. Sua
    //   mensagem cita o NOME da restrição:
    //     Duplicate entry 'marie-pelissier' for key 'doctors.unq_doctors_first_name_last_name'
    //   (o MySQL 8 prefixa o nome com o da tabela, o MariaDB não). É
    //   por isso que o script SQL DÁ NOME a todas as suas restrições.
    // Qualquer outro erro é uma anomalia real: retornamos null (não traduzido).
    // -----------------------------------------------------------------------
    private static readonly Dictionary<string, string> ConstraintMessages = new()
    {
        ["unq_users_login"] = "ERRORS.LOGIN_TAKEN",
        ["unq_doctors_first_name_last_name"] = "ERRORS.DOCTOR_ALREADY_EXISTS",
        ["unq_clients_first_name_last_name"] = "ERRORS.PATIENT_ALREADY_EXISTS",
        ["unq1_appointments"] = "ERRORS.SLOT_ALREADY_BOOKED",
    };

    private static BusinessException? TranslateDatabaseError(Exception e)
    {
        // atenção à ordem: DbUpdateConcurrencyException herda de DbUpdateException
        if (e is DbUpdateConcurrencyException)
        {
            return new BusinessException("ERRORS.CONCURRENT_UPDATE");
        }
        // "pattern matching": e é uma DbUpdateException
        // cuja InnerException é uma MySqlException com o código DuplicateKeyEntry?
        if (e is DbUpdateException { InnerException: MySqlException { ErrorCode: MySqlErrorCode.DuplicateKeyEntry } sqlError })
        {
            // "... for key 'doctors.unq_doctors_first_name_last_name'" -> "unq_doctors_first_name_last_name"
            var match = Regex.Match(sqlError.Message, @"for key '(?:[^'.]*\.)?([^']+)'");
            if (match.Success && ConstraintMessages.TryGetValue(match.Groups[1].Value, out var key))
            {
                return new BusinessException(key);
            }
        }
        return null;
    }
}
  • 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

// =========================================================================
// Auth/ConnectedUser.cs
// -------------------------------------------------------------------------
// O que o token JWT contém e como lê-lo de volta.
//
// No ASP.NET Core, o usuário da requisição é um ClaimsPrincipal
// (propriedade User de um controller, HttpContext.User nos demais lugares): uma lista de
// "claims", pares tipo / valor, exatamente os
// campos do token JWT depois de verificado. O middleware de autenticação o
// preenche a CADA requisição (veja Program.cs, UseAuthentication).
//
// As claims dos nossos tokens (veja AuthService.SetToken):
//   sub   : o id da conta de usuário (convenção JWT: "subject")
//   login : o login
//   name  : o nome exibido ("Marie PELISSIER"), para a barra de navegação
//   role  : ADMIN, DOCTOR ou USER
// =========================================================================

using System.Security.Claims;
using RdvMedecins.Entities;

namespace RdvMedecins.Auth;

public static class JwtClaims
{
    public const string Sub = "sub";
    public const string Login = "login";
    public const string Name = "name";
    public const string Role = "role";
}

// o usuário conectado, de forma tipada
public record ConnectedUser(int UserId, string Login, string Name, Role Role);

// -------------------------------------------------------------------------
// Um "método de extensão": é chamado como se fizesse parte de
// ClaimsPrincipal (User.CurrentUser()), embora seja definido aqui.
// -------------------------------------------------------------------------
public static class ClaimsPrincipalExtensions
{
    // o usuário conectado, ou null se a requisição não estiver autenticada
    public static ConnectedUser? CurrentUser(this ClaimsPrincipal principal)
    {
        if (principal.Identity?.IsAuthenticated != true
            || !int.TryParse(principal.FindFirstValue(JwtClaims.Sub), out var userId)
            || !Enum.TryParse<Role>(principal.FindFirstValue(JwtClaims.Role), out var role))
        {
            return null;
        }
        return new ConnectedUser(
            userId,
            principal.FindFirstValue(JwtClaims.Login) ?? "",
            principal.FindFirstValue(JwtClaims.Name) ?? "",
            role);
    }
}
  • 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

// =========================================================================
// Auth/AuthService.cs
// -------------------------------------------------------------------------
// A lógica de autenticação:
//   - ValidateUserAsync()      : verifica um par login / senha;
//   - SetToken()               : constrói o token JWT de um usuário validado
//                                e o armazena em um cookie;
//   - ClearToken()             : exclui esse cookie (logout).
//
// Por onde viaja o token JWT?
// Com o cliente Angular, era o código JavaScript do cliente que guardava o
// token e o adicionava por conta própria a cada requisição (cabeçalho
// "Authorization: Bearer ..."). Um navegador que exibe páginas HTML comuns não consegue
// fazer isso: para que ele apresente o token sozinho a cada requisição,
// ele precisa ser armazenado em um COOKIE. As opções deste cookie importam para
// a segurança:
//   - HttpOnly : o JavaScript da página não consegue ler o cookie (um
//     script injetado não poderia, portanto, roubar o token);
//   - SameSite=Lax : o navegador NÃO envia o cookie com um POST vindo
//     de outro site. Como todas as actions que modificam dados são
//     POSTs, uma página armadilhada em outro site não pode marcar nem
//     excluir nada se passando pelo usuário
//     (o chamado ataque CSRF);
//   - Secure : em produção (HTTPS), o cookie nunca viaja em texto claro;
//   - MaxAge : o cookie desaparece ao mesmo tempo em que o token expira.
// =========================================================================

using System.Text;
using Microsoft.Extensions.Options;
using Microsoft.IdentityModel.JsonWebTokens;
using Microsoft.IdentityModel.Tokens;
using RdvMedecins.Config;
using RdvMedecins.Entities;
using RdvMedecins.Repositories;

namespace RdvMedecins.Auth;

public class AuthService(UserRepository userRepository, IOptions<AuthOptions> options)
{
    // o nome do cookie que carrega o token
    public const string JwtCookie = "rdvmedecins_jwt";

    private readonly AuthOptions auth = options.Value;

    // a chave de assinatura dos tokens, construída a partir do segredo de
    // appsettings.json. Também usada para VERIFICAR os tokens (veja Program.cs).
    public static SymmetricSecurityKey SigningKey(AuthOptions auth)
    {
        var bytes = Encoding.UTF8.GetBytes(auth.JwtSecret);
        if (bytes.Length < 32)
        {
            // o HMAC-SHA256 exige uma chave de pelo menos 256 bits: dizemos isso
            // claramente na inicialização, em vez de no primeiro login
            throw new InvalidOperationException("Auth:JwtSecret must be at least 32 characters long (see appsettings.json).");
        }
        return new SymmetricSecurityKey(bytes);
    }

    // null se o login não existir ou se a senha estiver errada.
    // BCrypt.Verify faz o hash da senha digitada com o "salt" contido no
    // hash armazenado e depois compara os dois resultados.
    public async Task<User?> ValidateUserAsync(string login, string password)
    {
        var user = await userRepository.FindByLoginAsync(login);
        if (user is null)
        {
            return null;
        }
        return BCrypt.Net.BCrypt.Verify(password, user.Password) ? user : null;
    }

    // -----------------------------------------------------------------------
    // constrói o token JWT de [user] e o coloca em um cookie.
    // O token é ASSINADO (HMAC-SHA256) com a chave secreta: o navegador
    // pode lê-lo (ele não é criptografado), mas não modificá-lo, pois qualquer
    // modificação tornaria a assinatura inválida.
    // -----------------------------------------------------------------------
    public void SetToken(HttpResponse response, User user)
    {
        var descriptor = new SecurityTokenDescriptor
        {
            Claims = new Dictionary<string, object>
            {
                [JwtClaims.Sub] = user.Id,
                [JwtClaims.Login] = user.Login,
                [JwtClaims.Name] = user.Name,
                [JwtClaims.Role] = user.Role.ToString(),
            },
            Expires = DateTime.UtcNow.AddSeconds(auth.JwtExpiresInSeconds),
            SigningCredentials = new SigningCredentials(SigningKey(auth), SecurityAlgorithms.HmacSha256),
        };
        var token = new JsonWebTokenHandler().CreateToken(descriptor);

        response.Cookies.Append(JwtCookie, token, new CookieOptions
        {
            HttpOnly = true,
            SameSite = SameSiteMode.Lax,
            Secure = auth.CookieSecure,
            MaxAge = TimeSpan.FromSeconds(auth.JwtExpiresInSeconds),
            Path = "/",
        });
    }

    public static void ClearToken(HttpResponse response) =>
        response.Cookies.Delete(JwtCookie, new CookieOptions { Path = "/" });
}

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

// =========================================================================
// Auth/JwtAuthentication.cs
// -------------------------------------------------------------------------
// A configuração da autenticação por token JWT, chamada a partir de
// Program.cs (builder.Services.AddJwtAuthentication(...)).
//
// O "handler" JwtBearer do ASP.NET Core faz, a cada requisição, o que
// a estratégia 'jwt' do Passport e o JwtAuthGuard faziam no NestJS:
//   1. encontrar o token;
//   2. verificar sua assinatura e sua data de expiração;
//   3. derivar dele o usuário (HttpContext.User, veja ConnectedUser.cs).
//
// Três adaptações a uma aplicação HTML, graças aos "eventos" do
// handler (funções que ele chama em momentos precisos):
//   - OnMessageReceived : o token é lido de um COOKIE, e não do
//     cabeçalho "Authorization: Bearer ...";
//   - OnChallenge : quando uma página protegida é solicitada sem um token válido,
//     o JwtBearer responderia 401, o que serve para um cliente JavaScript. Um
//     navegador, porém, deve ser REDIRECIONADO para a página de login;
//   - (403: papel insuficiente) nada a fazer aqui: a resposta 403 vazia é
//     transformada em página de erro por UseStatusCodePagesWithReExecute
//     (veja Program.cs e Controllers/ErrorController.cs).
// =========================================================================

using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.IdentityModel.Tokens;
using RdvMedecins.Config;
using RdvMedecins.Web;

namespace RdvMedecins.Auth;

public static class JwtAuthentication
{
    public static IServiceCollection AddJwtAuthentication(this IServiceCollection services, AuthOptions auth)
    {
        services
            .AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
            .AddJwtBearer(options =>
            {
                // mantemos os nomes das claims do token como estão ("role", "sub"...)
                // em vez de traduzi-los para nomes longos no estilo Microsoft
                options.MapInboundClaims = false;

                options.TokenValidationParameters = new TokenValidationParameters
                {
                    ValidateIssuerSigningKey = true,
                    IssuerSigningKey = AuthService.SigningKey(auth),
                    ValidateLifetime = true,
                    // um token expirado é recusado imediatamente (por padrão, uma
                    // tolerância de 5 minutos é concedida para diferenças de relógio)
                    ClockSkew = TimeSpan.Zero,
                    // nossos tokens não têm nem emissor (iss) nem audiência (aud)
                    ValidateIssuer = false,
                    ValidateAudience = false,
                    // qual claim contém o nome e qual contém o papel:
                    // [Authorize(Roles = "ADMIN")] compara a claim "role"
                    NameClaimType = JwtClaims.Name,
                    RoleClaimType = JwtClaims.Role,
                };

                options.Events = new JwtBearerEvents
                {
                    // 1. o token está no cookie
                    OnMessageReceived = context =>
                    {
                        context.Token = context.Request.Cookies[AuthService.JwtCookie];
                        return Task.CompletedTask;
                    },

                    // 2. página protegida sem token válido -> página de login
                    OnChallenge = context =>
                    {
                        // HandleResponse(): "eu cuido da resposta", o JwtBearer
                        // portanto não escreverá seu 401
                        context.HandleResponse();
                        // um cookie estava presente, mas não é mais válido: a sessão expirou
                        if (context.Request.Cookies.ContainsKey(AuthService.JwtCookie))
                        {
                            AuthService.ClearToken(context.Response);
                            Flash.Put(context.HttpContext, FlashType.Danger, "ERRORS.SESSION_EXPIRED");
                        }
                        context.Response.Redirect("/login");
                        return Task.CompletedTask;
                    },
                };
            });

        return services;
    }
}

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

// =========================================================================
// Auth/InvalidSessionException.cs
// -------------------------------------------------------------------------
// O token é válido, mas a conta que ele designa não existe mais: foi
// excluída desde o login (pelo próprio paciente em outra
// aba, ou pelo ADMIN). Tratamos este caso como uma sessão expirada:
// HtmlExceptionFilter apaga o cookie e redireciona para a página de login
// (o equivalente à UnauthorizedException do NestJS).
// =========================================================================

namespace RdvMedecins.Auth;

public class InvalidSessionException() : Exception("the account of the connected user no longer exists");
  • 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

// =========================================================================
// Auth/CaptchaService.cs
// -------------------------------------------------------------------------
// Um CAPTCHA ("teste para distinguir um humano de um robô") feito pelo
// próprio servidor, sem nenhum serviço externo: alguns caracteres distorcidos,
// embaralhados por traços, em uma imagem SVG. Um humano os lê sem
// dificuldade; um robô que apenas envia formulários em loop
// não consegue.
//
// O projeto NestJS usava a biblioteca svg-captcha. Aqui, nenhuma
// biblioteca: a imagem é desenhada pela classe CaptchaDrawing (abaixo)
// a partir de uma pequena "fonte" vetorial escrita à mão. Um ponto
// importante: cada caractere é desenhado com TRAÇOS (<path>), nunca
// escrito como texto (<text>); caso contrário, um robô só teria de ler o código-fonte
// da imagem.
//
// Como funciona:
//   1. Generate() sorteia um texto aleatório, transforma-o em imagem e guarda a
//      resposta correta NA MEMÓRIA DO SERVIDOR, sob um identificador aleatório;
//   2. a página exibe a imagem e coloca o identificador em um campo oculto do
//      formulário (a resposta em si nunca sai do servidor);
//   3. Verify(id, input) compara a entrada com a resposta esperada e depois
//      ESQUECE este captcha: cada imagem é usada uma só vez, um robô não pode
//      reutilizar uma resposta já encontrada.
//
// Serviço SINGLETON (uma única instância para todo o servidor, veja
// Program.cs), usado por várias requisições EM PARALELO: daí o
// ConcurrentDictionary, um dicionário que várias threads podem ler
// e modificar ao mesmo tempo sem corrompê-lo.
//
// Limite aceito: a memória de um único processo. Com vários servidores
// atrás de um balanceador de carga, seria preciso um armazenamento compartilhado.
// =========================================================================

using System.Collections.Concurrent;
using System.Globalization;
using System.Security.Cryptography;
using System.Text;

namespace RdvMedecins.Auth;

// Id : a colocar no campo oculto "captchaId" do formulário
// Svg : a imagem, a inserir como está na página
public record Captcha(string Id, string Svg);

public class CaptchaService
{
    // duração de validade de uma imagem: você tem 10 minutos para preencher o formulário
    private static readonly TimeSpan Lifetime = TimeSpan.FromMinutes(10);

    // proteção da memória: acima disto, esquecemos os captchas mais antigos
    private const int MaxCaptchas = 10_000;

    // id -> (resposta esperada, data de expiração)
    private readonly ConcurrentDictionary<string, (string Text, DateTime Expires)> pending = new();

    public Captcha Generate()
    {
        Purge();
        var text = CaptchaDrawing.RandomText(5); // 5 caracteres
        var id = Guid.NewGuid().ToString();
        pending[id] = (text, DateTime.UtcNow + Lifetime);
        return new Captcha(id, CaptchaDrawing.Svg(text));
    }

    // true se [input] for a resposta correta do captcha [id] (sem distinção
    // de maiúsculas e minúsculas). O captcha é consumido em todos os casos.
    // TryRemove é ATÔMICO: se duas requisições apresentarem o mesmo captcha no
    // mesmo instante, só uma o remove e a outra falha.
    public bool Verify(string? id, string? input)
    {
        if (id is null || input is null || !pending.TryRemove(id, out var expected))
        {
            return false;
        }
        return expected.Expires > DateTime.UtcNow
            && string.Equals(expected.Text, input.Trim(), StringComparison.OrdinalIgnoreCase);
    }

    private void Purge()
    {
        var now = DateTime.UtcNow;
        foreach (var (id, captcha) in pending)
        {
            if (captcha.Expires <= now || pending.Count >= MaxCaptchas)
            {
                pending.TryRemove(id, out _);
            }
        }
    }
}

// -------------------------------------------------------------------------
// O desenho da imagem SVG (150 x 50 pixels).
// -------------------------------------------------------------------------
internal static class CaptchaDrawing
{
    private const int Width = 150;
    private const int Height = 50;

    // A "fonte": cada caractere é uma lista de traços, cada traço uma
    // série de pontos (x, y) em uma grade de 4 x 6 (y apontando para baixo).
    // Caracteres fáceis demais de confundir entre si: excluídos (0 O, 1 I L).
    private static readonly Dictionary<char, double[][]> Font = new()
    {
        ['A'] = [[0, 6, 2, 0, 4, 6], [0.8, 3.8, 3.2, 3.8]],
        ['B'] = [[0, 0, 0, 6, 3, 6, 4, 5, 4, 4, 3, 3, 0, 3], [0, 0, 3, 0, 4, 1, 4, 2, 3, 3]],
        ['C'] = [[4, 1, 3, 0, 1, 0, 0, 1, 0, 5, 1, 6, 3, 6, 4, 5]],
        ['D'] = [[0, 0, 0, 6, 2.5, 6, 4, 4.5, 4, 1.5, 2.5, 0, 0, 0]],
        ['E'] = [[4, 0, 0, 0, 0, 6, 4, 6], [0, 3, 3, 3]],
        ['F'] = [[4, 0, 0, 0, 0, 6], [0, 3, 3, 3]],
        ['G'] = [[4, 1, 3, 0, 1, 0, 0, 1, 0, 5, 1, 6, 3, 6, 4, 5, 4, 3.5, 2.5, 3.5]],
        ['H'] = [[0, 0, 0, 6], [4, 0, 4, 6], [0, 3, 4, 3]],
        ['J'] = [[4, 0, 4, 5, 3, 6, 1, 6, 0, 5]],
        ['K'] = [[0, 0, 0, 6], [4, 0, 0, 3.5], [1.3, 2.6, 4, 6]],
        ['M'] = [[0, 6, 0, 0, 2, 3.5, 4, 0, 4, 6]],
        ['N'] = [[0, 6, 0, 0, 4, 6, 4, 0]],
        ['P'] = [[0, 6, 0, 0, 3, 0, 4, 1, 4, 2, 3, 3, 0, 3]],
        ['Q'] = [[1, 0, 3, 0, 4, 1, 4, 5, 3, 6, 1, 6, 0, 5, 0, 1, 1, 0], [2.5, 4.5, 4, 6.3]],
        ['R'] = [[0, 6, 0, 0, 3, 0, 4, 1, 4, 2, 3, 3, 0, 3], [2, 3, 4, 6]],
        ['S'] = [[4, 1, 3, 0, 1, 0, 0, 1, 0, 2, 1, 3, 3, 3, 4, 4, 4, 5, 3, 6, 1, 6, 0, 5]],
        ['T'] = [[0, 0, 4, 0], [2, 0, 2, 6]],
        ['U'] = [[0, 0, 0, 5, 1, 6, 3, 6, 4, 5, 4, 0]],
        ['V'] = [[0, 0, 2, 6, 4, 0]],
        ['W'] = [[0, 0, 1, 6, 2, 2.5, 3, 6, 4, 0]],
        ['X'] = [[0, 0, 4, 6], [4, 0, 0, 6]],
        ['Y'] = [[0, 0, 2, 3, 4, 0], [2, 3, 2, 6]],
        ['Z'] = [[0, 0, 4, 0, 0, 6, 4, 6]],
        ['2'] = [[0, 1, 1, 0, 3, 0, 4, 1, 4, 2, 0, 6, 4, 6]],
        ['3'] = [[0, 1, 1, 0, 3, 0, 4, 1, 4, 2, 3, 3, 1.5, 3], [3, 3, 4, 4, 4, 5, 3, 6, 1, 6, 0, 5]],
        ['4'] = [[3, 6, 3, 0, 0, 4, 4, 4]],
        ['5'] = [[4, 0, 0, 0, 0, 3, 3, 3, 4, 4, 4, 5, 3, 6, 1, 6, 0, 5]],
        ['6'] = [[4, 1, 3, 0, 1, 0, 0, 1, 0, 5, 1, 6, 3, 6, 4, 5, 4, 4, 3, 3, 0, 3]],
        ['7'] = [[0, 0, 4, 0, 1.5, 6]],
        ['8'] = [[1, 3, 0, 2, 0, 1, 1, 0, 3, 0, 4, 1, 4, 2, 3, 3, 1, 3, 0, 4, 0, 5, 1, 6, 3, 6, 4, 5, 4, 4, 3, 3]],
        ['9'] = [[4, 3, 1, 3, 0, 2, 0, 1, 1, 0, 3, 0, 4, 1, 4, 5, 3, 6, 1, 6, 0, 5]],
    };

    private static readonly char[] Alphabet = [.. Font.Keys];

    // algumas cores escuras, fáceis de ler sobre o fundo claro
    private static readonly string[] Colors = ["#1f4e79", "#7b2d26", "#2e6b30", "#5b2c83", "#8a5a00", "#23395d", "#9c2a5b"];

    // RandomNumberGenerator: um gerador de números aleatórios "criptográfico",
    // imprevisível (ao contrário de Random, cuja sequência poderia ser adivinhada)
    public static string RandomText(int length) =>
        new(Enumerable.Range(0, length).Select(_ => Alphabet[RandomNumberGenerator.GetInt32(Alphabet.Length)]).ToArray());

    private static double RandomBetween(double min, double max) =>
        min + (max - min) * RandomNumberGenerator.GetInt32(1_000_001) / 1_000_000.0;

    public static string Svg(string text)
    {
        var svg = new StringBuilder();
        svg.Append($"<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"{Width}\" height=\"{Height}\" viewBox=\"0 0 {Width} {Height}\">");
        svg.Append($"<rect width=\"100%\" height=\"100%\" fill=\"#f5f7fa\"/>");

        // os caracteres: cada um ampliado, inclinado, deslocado, e cada ponto
        // levemente movido ao acaso
        var step = (Width - 20) / (double)text.Length;
        for (var i = 0; i < text.Length; i++)
        {
            var scale = RandomBetween(4.6, 5.6); // tamanho de uma unidade da grade, em pixels
            var angle = RandomBetween(-0.35, 0.35); // rotação, em radianos (cerca de ±20°)
            var cx = 10 + step * (i + 0.5) + RandomBetween(-3, 3); // centro do caractere
            var cy = Height / 2.0 + RandomBetween(-4, 4);
            var color = Colors[RandomNumberGenerator.GetInt32(Colors.Length)];
            var d = new StringBuilder();
            foreach (var stroke in Font[text[i]])
            {
                for (var k = 0; k < stroke.Length; k += 2)
                {
                    // ponto da grade, centrado em (2, 3), distorcido, girado, posicionado
                    var x = (stroke[k] - 2 + RandomBetween(-0.2, 0.2)) * scale;
                    var y = (stroke[k + 1] - 3 + RandomBetween(-0.2, 0.2)) * scale;
                    var px = cx + x * Math.Cos(angle) - y * Math.Sin(angle);
                    var py = cy + x * Math.Sin(angle) + y * Math.Cos(angle);
                    d.Append(k == 0 ? 'M' : 'L').Append(Number(px)).Append(' ').Append(Number(py)).Append(' ');
                }
            }
            svg.Append($"<path d=\"{d.ToString().TrimEnd()}\" fill=\"none\" stroke=\"{color}\" stroke-width=\"{Number(RandomBetween(2.2, 3))}\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/>");
        }

        // 3 traços de embaralhamento: curvas que cruzam a imagem
        for (var n = 0; n < 3; n++)
        {
            var color = Colors[RandomNumberGenerator.GetInt32(Colors.Length)];
            svg.Append($"<path d=\"M{Number(RandomBetween(0, 20))} {Number(RandomBetween(5, 45))} " +
                       $"C{Number(RandomBetween(30, 60))} {Number(RandomBetween(0, 50))} {Number(RandomBetween(90, 120))} {Number(RandomBetween(0, 50))} " +
                       $"{Number(RandomBetween(130, 150))} {Number(RandomBetween(5, 45))}\" fill=\"none\" stroke=\"{color}\" stroke-width=\"1.3\"/>");
        }

        svg.Append("</svg>");
        return svg.ToString();
    }

    // um número com ponto decimal, qualquer que seja o idioma do servidor
    // (em francês, ToString() escreveria "12,5", ilegível para o SVG)
    private static string Number(double value) => value.ToString("0.#", CultureInfo.InvariantCulture);
}

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

// =========================================================================
// Auth/AttemptLimiterService.cs
// -------------------------------------------------------------------------
// Segunda linha de defesa contra robôs (a primeira é o captcha): CONTAMOS as
// tentativas e, acima de um limite, BLOQUEAMOS por um tempo.
//
//   - login: após LoginMaxFailures falhas (captcha ou senha errados) para o mesmo login
//     a partir do mesmo endereço IP, este par é
//     bloqueado por LoginBlockMinutes minutos. O mesmo endereço IP também é
//     bloqueado se acumular 5 vezes mais falhas, todos os logins somados (um
//     robô que tenta milhares de logins diferentes);
//   - criação de conta: no máximo RegistrationMaxPerHour contas criadas por
//     hora a partir do mesmo endereço IP.
//
// Atenção em uma sala de aula: todos os computadores costumam sair para a Internet
// pelo MESMO endereço IP. É por isso que o bloqueio de login se aplica
// primeiro ao par (IP, login): um aluno que erra a
// senha não bloqueia seus colegas; e é por isso que os limites são ajustáveis
// em appsettings.json (seção "Protection").
//
// Serviço singleton, chamado por requisições paralelas: todas as
// operações sobre os contadores são feitas sob um lock, o que garante
// que apenas uma thread por vez leia E modifique um contador.
// =========================================================================

using Microsoft.Extensions.Options;
using RdvMedecins.Config;

namespace RdvMedecins.Auth;

public class AttemptLimiterService(IOptions<ProtectionOptions> options)
{
    private class Counter
    {
        public int Count; // tentativas contadas na janela atual
        public DateTime Start; // início da janela de contagem
        public DateTime BlockedUntil; // DateTime.MinValue se não estiver bloqueado
    }

    private static readonly TimeSpan OneHour = TimeSpan.FromHours(1);

    private readonly Dictionary<string, Counter> counters = [];
    private readonly Lock syncLock = new(); // o tipo Lock do .NET 9+, feito para o "lock"

    private readonly int maxLoginFailures = options.Value.LoginMaxFailures;
    private readonly TimeSpan loginBlockDuration = TimeSpan.FromMinutes(options.Value.LoginBlockMinutes);
    private readonly int maxRegistrations = options.Value.RegistrationMaxPerHour;

    // login

    // número de minutos de bloqueio restantes (0 = a tentativa é permitida)
    public int LoginBlockMinutes(string ip, string login)
    {
        lock (syncLock)
        {
            return Math.Max(RemainingMinutes(LoginKey(ip, login)), RemainingMinutes(IpKey(ip)));
        }
    }

    public void LoginFailure(string ip, string login)
    {
        lock (syncLock)
        {
            Count(LoginKey(ip, login), maxLoginFailures, loginBlockDuration, loginBlockDuration);
            Count(IpKey(ip), maxLoginFailures * 5, loginBlockDuration, loginBlockDuration);
        }
    }

    // um login bem-sucedido zera o contador DESTE login
    public void LoginSuccess(string ip, string login)
    {
        lock (syncLock)
        {
            counters.Remove(LoginKey(ip, login));
        }
    }

    // cadastro

    public int RegistrationBlockMinutes(string ip)
    {
        lock (syncLock)
        {
            return RemainingMinutes($"registration|{ip}");
        }
    }

    // janela de uma hora; atingida a cota, bloqueado até o fim da hora
    public void RegistrationSuccess(string ip)
    {
        lock (syncLock)
        {
            Count($"registration|{ip}", maxRegistrations, OneHour, OneHour);
        }
    }

    // mecânica compartilhada
    // (os métodos privados são sempre chamados sob o lock)

    private int RemainingMinutes(string key)
    {
        if (!counters.TryGetValue(key, out var c))
        {
            return 0;
        }
        var remaining = c.BlockedUntil - DateTime.UtcNow;
        return remaining > TimeSpan.Zero ? (int)Math.Ceiling(remaining.TotalMinutes) : 0;
    }

    // conta uma tentativa; se o limite for atingido dentro da janela, bloqueia
    private void Count(string key, int max, TimeSpan window, TimeSpan block)
    {
        var now = DateTime.UtcNow;
        Purge(now);
        if (!counters.TryGetValue(key, out var c) || now - c.Start > window)
        {
            c = new Counter { Count = 0, Start = now, BlockedUntil = DateTime.MinValue };
            counters[key] = c;
        }
        c.Count++;
        if (c.Count >= max)
        {
            c.BlockedUntil = now + block;
            c.Count = 0; // após o bloqueio, recomeçamos do zero
            c.Start = c.BlockedUntil;
        }
    }

    // esquecemos os contadores que não são mais úteis (nem bloqueados, nem recentes)
    private void Purge(DateTime now)
    {
        if (counters.Count < 1000)
        {
            return;
        }
        foreach (var (key, c) in counters.ToList())
        {
            if (c.BlockedUntil < now && now - c.Start > OneHour)
            {
                counters.Remove(key);
            }
        }
    }

    private static string LoginKey(string ip, string login) => $"login|{ip}|{login.Trim().ToLowerInvariant()}";

    private static string IpKey(string ip) => $"ip|{ip}";
}

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

// =========================================================================
// Auth/RegistrationPassService.cs
// -------------------------------------------------------------------------
// O "passe" de criação de conta.
//
// Para abrir a página "Create a patient account", é preciso antes ter
// copiado o captcha da página de autenticação (veja
// RegistrationController, POST /register/access). O servidor então emite
// um passe:
//   - um identificador aleatório, armazenado em um cookie HttpOnly;
//   - válido por 15 minutos (o tempo de preencher o formulário, mesmo que sejam
//     necessárias várias tentativas após erros de entrada);
//   - consumido assim que uma conta é criada: UM captcha resolvido = UMA conta no
//     máximo. Um robô não pode criar contas em série.
//
// Sem um passe válido, GET e POST /register redirecionam para a página de
// autenticação: digitar diretamente a URL /register não permite
// contornar o captcha.
//
// Como o captcha, os passes vivem na memória do processo.
// =========================================================================

using System.Collections.Concurrent;

namespace RdvMedecins.Auth;

public class RegistrationPassService
{
    public const string Cookie = "rdvmedecins_registration";

    private static readonly TimeSpan Lifetime = TimeSpan.FromMinutes(15);
    private const int MaxPasses = 10_000;

    // id -> data de expiração
    private readonly ConcurrentDictionary<string, DateTime> passes = new();

    // emite um novo passe; retorna seu identificador
    public string Issue()
    {
        Purge();
        var id = Guid.NewGuid().ToString();
        passes[id] = DateTime.UtcNow + Lifetime;
        return id;
    }

    // true se [id] for um passe existente e não expirado
    public bool IsValid(string? id) =>
        id is not null && passes.TryGetValue(id, out var expires) && expires > DateTime.UtcNow;

    // o passe foi usado: nós o esquecemos
    public void Consume(string? id)
    {
        if (id is not null)
        {
            passes.TryRemove(id, out _);
        }
    }

    // o cookie é enviado pelo navegador apenas para os endereços /register...
    public static CookieOptions GetCookieOptions() => new()
    {
        HttpOnly = true,
        SameSite = SameSiteMode.Lax,
        MaxAge = Lifetime,
        Path = "/register",
    };

    private void Purge()
    {
        var now = DateTime.UtcNow;
        foreach (var (id, expires) in passes)
        {
            if (expires <= now || passes.Count >= MaxPasses)
            {
                passes.TryRemove(id, out _);
            }
        }
    }
}

É 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

// =========================================================================
// Controllers/AuthController.cs
// -------------------------------------------------------------------------
// As rotas NÃO protegidas do login:
//   GET  /        redireciona para a página inicial do papel (ou para /login)
//   GET  /login   exibe o formulário de login (com seu captcha)
//   POST /login   verifica o limite de tentativas, o captcha, login / senha
//   POST /logout  apaga o cookie do token
//
// Um controller MVC herda de Controller e retorna um IActionResult:
// View(...) para exibir uma página, Redirect(...) para redirecionar...
// [HttpGet("login")] / [HttpPost("login")]: "attribute routing",
// o equivalente a @Get('login') / @Post('login').
//
// Proteção contra robôs, nesta ordem:
//   1. muitas falhas recentes para este login a partir deste endereço IP?
//      -> recusa imediata, sem sequer olhar a senha;
//   2. resposta errada ao captcha? -> recusa (contada como falha);
//   3. só então, verificação da senha.
// NUNCA verificamos a senha de uma tentativa recusada nas etapas
// 1 ou 2: um robô, portanto, nada pode aprender insistindo.
// =========================================================================

using Microsoft.AspNetCore.Mvc;
using RdvMedecins.Auth;
using RdvMedecins.Entities;
using RdvMedecins.Models;

namespace RdvMedecins.Controllers;

public class AuthController(
    AuthService authService,
    CaptchaService captchaService,
    AttemptLimiterService limiter) : Controller
{
    // a página inicial de cada papel, logo após o login
    public static string HomePage(Role role) => role == Role.USER ? "/my-area" : "/schedule";

    [HttpGet("/")]
    public IActionResult Home()
    {
        // User: o usuário da requisição, reconstruído a partir do token pelo
        // middleware de autenticação (veja Auth/ConnectedUser.cs)
        var user = User.CurrentUser();
        return Redirect(user is not null ? HomePage(user.Role) : "/login");
    }

    // GET /login[?login=xxx]: o parâmetro opcional preenche previamente o campo
    // de login (usado logo após a criação de uma conta, veja RegistrationController)
    [HttpGet("login")]
    public IActionResult ShowLogin(string? login)
    {
        // já conectado (token ainda válido): direto para a página inicial
        var user = User.CurrentUser();
        if (user is not null)
        {
            return Redirect(HomePage(user.Role));
        }
        return Form(login is null ? "" : login[..Math.Min(login.Length, 30)]);
    }

    // os parâmetros da action são preenchidos com os campos do formulário de
    // mesmo nome (model binding); [FromForm] especifica que eles são procurados no
    // corpo da requisição POST
    [HttpPost("login")]
    public async Task<IActionResult> LogIn(
        [FromForm] string? login,
        [FromForm] string? password,
        [FromForm] string? captchaId,
        [FromForm] string? captcha)
    {
        login = (login ?? "").Trim();
        password ??= "";
        var ip = IpAddress(HttpContext);

        // 1. muitas falhas recentes?
        var minutes = limiter.LoginBlockMinutes(ip, login);
        if (minutes > 0)
        {
            return Form(login, "ERRORS.TOO_MANY_ATTEMPTS", new Dictionary<string, string> { ["minutes"] = minutes.ToString() });
        }

        // 2. o captcha
        if (!captchaService.Verify(captchaId, captcha))
        {
            limiter.LoginFailure(ip, login);
            return Form(login, "ERRORS.WRONG_CAPTCHA");
        }

        // 3. a senha
        var user = login != "" && password != "" ? await authService.ValidateUserAsync(login, password) : null;
        if (user is null)
        {
            limiter.LoginFailure(ip, login);
            return Form(login, "LOGIN.ERROR");
        }

        limiter.LoginSuccess(ip, login);
        authService.SetToken(Response, user);
        return Redirect(HomePage(user.Role));
    }

    // logout com um POST (e não com um simples link GET): um site de terceiros não pode
    // desconectar o usuário sem que ele saiba (veja SameSite, AuthService)
    [HttpPost("logout")]
    public IActionResult LogOut()
    {
        AuthService.ClearToken(Response);
        return Redirect("/login");
    }

    // o endereço IP do visitante. Atrás de um proxy reverso (nginx...), o middleware
    // UseForwardedHeaders teria de ser habilitado para obter o do
    // visitante e não o do proxy.
    public static string IpAddress(HttpContext http) => http.Connection.RemoteIpAddress?.ToString() ?? "unknown";

    // o formulário, sempre com um NOVO captcha (cada imagem é usada uma só vez)
    private ViewResult Form(string login, string? error = null, IReadOnlyDictionary<string, string>? errorParams = null) =>
        View("Login", new LoginModel
        {
            PageTitle = "LOGIN.TITLE",
            Login = login, // reexibimos o login digitado, nunca a senha
            Captcha = captchaService.Generate(),
            Error = error,
            ErrorParams = errorParams,
        });
}

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

// =========================================================================
// Web/Translator.cs
// -------------------------------------------------------------------------
// Tradução francês / inglês da interface.
//
// Os dicionários são os MESMOS arquivos do projeto NestJS
// (i18n/fr.json, i18n/en.json), lidos uma só vez na inicialização. Uma view
// Razor traduz uma chave com @T("KEY") (veja Web/ViewPage.cs).
//
// O ASP.NET Core também oferece seu próprio sistema (IStringLocalizer e
// arquivos .resx); manter os arquivos JSON permite compartilhar os
// dicionários com as outras versões da aplicação.
//
// O IDIOMA ATUAL: é o middleware de localização do ASP.NET Core
// (UseRequestLocalization, veja Program.cs) que o determina a cada requisição,
// a partir de um cookie, e o armazena em CultureInfo.CurrentUICulture.
// =========================================================================

using System.Globalization;
using System.Text.Json;
using System.Text.RegularExpressions;

namespace RdvMedecins.Web;

public partial class Translator
{
    public static readonly string[] Languages = ["fr", "en"];
    public const string DefaultLanguage = "en";

    // idioma -> (chave completa "LOGIN.TITLE" -> texto)
    private readonly Dictionary<string, Dictionary<string, string>> dictionaries = [];

    public Translator(IWebHostEnvironment environment)
    {
        foreach (var language in Languages)
        {
            var path = Path.Combine(environment.ContentRootPath, "i18n", $"{language}.json");
            using var document = JsonDocument.Parse(File.ReadAllText(path));
            var dictionary = new Dictionary<string, string>();
            Flatten(document.RootElement, "", dictionary);
            dictionaries[language] = dictionary;
        }
    }

    // o idioma da requisição atual: "fr" ou "en"
    public static string CurrentLanguage()
    {
        var language = CultureInfo.CurrentUICulture.TwoLetterISOLanguageName;
        return Languages.Contains(language) ? language : DefaultLanguage;
    }

    // -----------------------------------------------------------------------
    // Translate("DOCTORS.ADDED", { ["name"] = "Marie PELISSIER" })
    //   -> procura "DOCTORS.ADDED" no dicionário do idioma atual
    //      e substitui {name} pelo seu valor. Uma chave ausente do idioma
    //      solicitado é procurada no idioma padrão; ausente em todos os lugares, a
    //      própria chave é exibida (uma omissão é assim percebida imediatamente).
    // -----------------------------------------------------------------------
    public string Translate(string? key, IReadOnlyDictionary<string, string>? messageParams = null)
    {
        if (string.IsNullOrEmpty(key))
        {
            return "";
        }
        var text = dictionaries[CurrentLanguage()].GetValueOrDefault(key)
                    ?? dictionaries[DefaultLanguage].GetValueOrDefault(key)
                    ?? key;
        if (messageParams is null || messageParams.Count == 0)
        {
            return text;
        }
        return Parameter().Replace(text, m => messageParams.TryGetValue(m.Groups[1].Value, out var value) ? value : m.Value);
    }

    // { "LOGIN": { "TITLE": "Login" } } -> { "LOGIN.TITLE": "Login" }
    private static void Flatten(JsonElement node, string prefix, Dictionary<string, string> result)
    {
        foreach (var property in node.EnumerateObject())
        {
            var key = prefix == "" ? property.Name : $"{prefix}.{property.Name}";
            if (property.Value.ValueKind == JsonValueKind.Object)
            {
                Flatten(property.Value, key, result);
            }
            else
            {
                result[key] = property.Value.GetString() ?? "";
            }
        }
    }

    // a expressão regular {name}, compilada de uma vez por todas pelo
    // compilador C# ([GeneratedRegex] "source generator")
    [GeneratedRegex(@"\{(\w+)\}")]
    private static partial Regex Parameter();
}

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

// =========================================================================
// Web/ViewPage.cs
// -------------------------------------------------------------------------
// A classe mãe de TODAS as views Razor da aplicação (veja
// Views/_ViewImports.cshtml: @inherits ViewPage<TModel>).
//
// Uma view .cshtml é compilada em uma classe C#, filha de RazorPage<TModel>.
// Ao inserir nossa própria classe, damos a todas as views o que
// precisam, qualquer que seja a página:
//   - @T("KEY")          : a tradução de uma chave (o equivalente ao
//                          helper Handlebars {{t 'KEY'}});
//   - Language           : "fr" ou "en";
//   - CurrentUser        : o usuário conectado, para a barra de navegação;
//   - FlashMessage       : a mensagem flash da requisição;
//   - CurrentPath        : a URL solicitada (menu ativo da barra de navegação).
// No NestJS, essas informações passavam por res.locals.
// =========================================================================

using Microsoft.AspNetCore.Mvc.Razor;
using Microsoft.AspNetCore.Mvc.Razor.Internal;
using RdvMedecins.Auth;

namespace RdvMedecins.Web;

public abstract class ViewPage<TModel> : RazorPage<TModel>
{
    // [RazorInject]: a propriedade é preenchida por injeção de dependência,
    // como a diretiva @inject faria em uma view
    [RazorInject]
    public Translator Translator { get; set; } = null!;

    // -----------------------------------------------------------------------
    // @T("BOOKING_DIALOG.SLOT", ("time", "8:00 - 8:20"))
    // Os parâmetros são "tuplas" (nome, valor): uma sintaxe compacta
    // para escrever pares de valores.
    // O texto retornado é então ESCAPADO pelo Razor (< vira &lt;): um nome
    // digitado por um usuário não pode, portanto, injetar HTML na página.
    // -----------------------------------------------------------------------
    public string T(string? key, params (string Name, object? Value)[] messageParams) =>
        Translator.Translate(key, messageParams.ToDictionary(p => p.Name, p => p.Value?.ToString() ?? ""));

    // o mesmo, com os parâmetros de uma mensagem flash ou de uma BusinessException
    public string T(string? key, IReadOnlyDictionary<string, string>? messageParams) => Translator.Translate(key, messageParams);

    public string Language => Translator.CurrentLanguage();

    public ViewUser? CurrentUser => ViewUser.Of(Context.User.CurrentUser());

    public FlashMessage? FlashMessage => Flash.Read(Context);

    public string CurrentPath => Context.Request.Path.Value ?? "/";

    // "active" se a página atual estiver sob este caminho (menu da barra de navegação)
    public string Active(string prefix) => CurrentPath.StartsWith(prefix, StringComparison.Ordinal) ? "active" : "";
}

// -------------------------------------------------------------------------
// o usuário conectado, como as views o enxergam
// -------------------------------------------------------------------------
public record ViewUser(string Login, string Name, string Role, bool IsAdmin, bool IsPatient)
{
    public static ViewUser? Of(ConnectedUser? u) =>
        u is null
            ? null
            : new ViewUser(
                u.Login,
                u.Name,
                u.Role.ToString(),
                IsAdmin: u.Role == Entities.Role.ADMIN, // ADMIN: menus Médicos / Pacientes
                IsPatient: u.Role == Entities.Role.USER); // USER: menu Minha área
}

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

// =========================================================================
// Web/Flash.cs
// -------------------------------------------------------------------------
// As mensagens "flash": uma mensagem a exibir UMA vez, na
// PRÓXIMA página. É o complemento natural do padrão "Post / Redirect / Get"
// usado por todos os formulários da aplicação: um POST bem-sucedido não
// constrói uma página, ele redireciona (302) para uma página GET: se
// o usuário recarregar essa página (F5), o navegador não envia
// o formulário uma segunda vez. A mensagem, porém, deve sobreviver ao
// redirecionamento.
//
// No NestJS, nós mesmos a programamos (um cookie de curta duração).
// O ASP.NET Core MVC a oferece de série: é o TempData. Um valor armazenado
// no TempData é mantido (por padrão em um cookie criptografado) até
// uma requisição seguinte LÊ-LO; ele é então apagado.
// =========================================================================

using System.Text.Json;
using Microsoft.AspNetCore.Mvc.ViewFeatures;

namespace RdvMedecins.Web;

public enum FlashType
{
    Success, // classe Bootstrap alert-success: no topo da página
    Danger, // um erro: no pé da página (veja Views/Shared/_Errors.cshtml)
}

// Key: chave de tradução; Params: seus parâmetros ({name}, {login}...)
public record FlashMessage(FlashType Type, string Key, Dictionary<string, string>? Params = null);

public static class Flash
{
    private const string Key = "flash";

    // -----------------------------------------------------------------------
    // coloca uma mensagem flash, que será exibida pela PRÓXIMA página.
    // Passamos por ITempDataDictionaryFactory (e não pela propriedade TempData
    // de um controller) para poder colocar uma mensagem de QUALQUER LUGAR:
    // um controller, mas também a autenticação JWT (sessão expirada, veja
    // Auth/JwtAuthentication.cs), que roda fora do MVC.
    // -----------------------------------------------------------------------
    public static void Put(HttpContext http, FlashType type, string key, Dictionary<string, string>? messageParams = null)
    {
        var tempData = TempDataOf(http);
        // o TempData só consegue manter valores simples: armazenamos a
        // mensagem como texto JSON
        tempData[Key] = JsonSerializer.Serialize(new FlashMessage(type, key, messageParams));
        // Save(): grava o cookie imediatamente (fora do MVC, ninguém
        // o faria por nós)
        tempData.Save();
    }

    // -----------------------------------------------------------------------
    // lê (e portanto apaga) a mensagem flash da requisição. A página pode
    // pedi-la várias vezes (a mensagem de sucesso é exibida no topo, a de erro
    // no pé): nós a mantemos em HttpContext.Items, um dicionário
    // que vive pelo tempo da requisição.
    // -----------------------------------------------------------------------
    public static FlashMessage? Read(HttpContext http)
    {
        if (http.Items.TryGetValue(Key, out var alreadyRead))
        {
            return alreadyRead as FlashMessage;
        }
        FlashMessage? message = null;
        if (TempDataOf(http)[Key] is string json)
        {
            try
            {
                message = JsonSerializer.Deserialize<FlashMessage>(json);
            }
            catch (JsonException)
            {
                // mensagem ilegível: nós a ignoramos
            }
        }
        http.Items[Key] = message;
        return message;
    }

    private static ITempDataDictionary TempDataOf(HttpContext http) =>
        http.RequestServices.GetRequiredService<ITempDataDictionaryFactory>().GetTempData(http);
}

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

// =========================================================================
// Web/HtmlExceptionFilter.cs
// -------------------------------------------------------------------------
// Como os erros viram páginas HTML. Três mecanismos
// do ASP.NET Core dividem o trabalho (veja Program.cs):
//
//   1. este filtro de exceção do MVC: uma InvalidSessionException (conta
//      excluída desde o login) -> volta à página de login;
//   2. UseStatusCodePagesWithReExecute("/error/{0}"): toda resposta 400,
//      403 ou 404 SEM conteúdo (return BadRequest(), papel insuficiente, página
//      desconhecida...) é substituída pela página de erro correspondente;
//   3. UseExceptionHandler("/error/500"): qualquer outra exceção (uma anomalia
//      real) é gravada no log do servidor, e o usuário
//      vê a página de erro 500, nunca a pilha de chamadas.
//
// No NestJS, um único filtro (HtmlExceptionFilter) fazia tudo isso.
// =========================================================================

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Filters;
using RdvMedecins.Auth;

namespace RdvMedecins.Web;

public class HtmlExceptionFilter : IExceptionFilter
{
    public void OnException(ExceptionContext context)
    {
        if (context.Exception is InvalidSessionException)
        {
            AuthService.ClearToken(context.HttpContext.Response);
            Flash.Put(context.HttpContext, FlashType.Danger, "ERRORS.SESSION_EXPIRED");
            context.Result = new RedirectResult("/login");
            context.ExceptionHandled = true;
        }
        // as outras exceções não são tratadas aqui: elas sobem
        // até UseExceptionHandler (página 500)
    }
}

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

// =========================================================================
// Web/ApplicationModel.cs
// -------------------------------------------------------------------------
// O cache / fachada já presente no servidor JSON (equivalente à classe
// [ApplicationModel] do projeto Spring): as listas de médicos e
// clientes são lidas uma vez na inicialização e depois servidas da memória.
//
// Essas listas podem MUDAR (o ADMIN adiciona, edita e exclui
// médicos e clientes): toda gravação passa portanto por esta fachada,
// que recarrega a lista em questão logo depois. Esse é todo o sentido de um
// ÚNICO ponto de entrada para a camada de negócio: a regra "gravação =>
// recarga do cache" é escrita somente aqui.
//
// Diferença importante com o NestJS: o TEMPO DE VIDA dos objetos.
//   - No NestJS, todos os serviços eram singletons.
//   - Aqui, o DbContext, e portanto os repositórios e a camada de negócio, vive
//     pelo tempo de UMA requisição HTTP (tempo de vida "scoped", veja Program.cs).
//   - Mas o cache deve sobreviver de uma requisição para a outra.
// Separamos, portanto, os dois papéis:
//   - ListCache (singleton): as duas listas, e nada mais;
//   - ApplicationModel (scoped): a fachada, que usa a camada de negócio da
//     requisição atual e atualiza o cache.
// =========================================================================

using RdvMedecins.Domain;
using RdvMedecins.Entities;
using RdvMedecins.Business;

namespace RdvMedecins.Web;

// -------------------------------------------------------------------------
// O cache em si, compartilhado por todas as requisições (singleton).
//
// O ASP.NET Core processa as requisições EM PARALELO, em várias threads (o Node,
// por sua vez, tem apenas uma). Por isso nunca modificamos uma lista no lugar: nós a
// SUBSTITUÍMOS inteiramente por uma nova. Trocar uma referência é atômico;
// "volatile" garante que todas as threads vejam imediatamente a nova lista.
// -------------------------------------------------------------------------
public class ListCache
{
    private volatile IReadOnlyList<Doctor> doctors = [];
    private volatile IReadOnlyList<Client> clients = [];

    public IReadOnlyList<Doctor> Doctors
    {
        get => doctors;
        set => doctors = value;
    }

    public IReadOnlyList<Client> Clients
    {
        get => clients;
        set => clients = value;
    }
}

// -------------------------------------------------------------------------
// A fachada (scoped): mesmo contrato da camada de negócio (IBusiness).
// -------------------------------------------------------------------------
public class ApplicationModel(IBusiness business, ListCache cache) : IBusiness
{
    // carga inicial das duas listas, chamada uma vez na inicialização
    // (veja Program.cs). Se o banco de dados estiver inacessível, a exceção interrompe o
    // servidor com uma mensagem explícita, o que é mais claro do que iniciar "vazio".
    public async Task LoadAsync()
    {
        await ReloadDoctorsAsync();
        await ReloadClientsAsync();
    }

    private async Task ReloadDoctorsAsync() => cache.Doctors = await business.GetAllDoctorsAsync();

    private async Task ReloadClientsAsync() => cache.Clients = await business.GetAllClientsAsync();

    // leituras a partir do cache

    public Task<List<Doctor>> GetAllDoctorsAsync() => Task.FromResult(cache.Doctors.ToList());

    public Task<List<Client>> GetAllClientsAsync() => Task.FromResult(cache.Clients.ToList());

    // o médico cuja conta de usuário é [userId], usado para pré-selecionar,
    // para um médico logado, sua própria agenda
    public Doctor? GetDoctorByUserId(int userId) => cache.Doctors.FirstOrDefault(d => d.UserId == userId);

    // delegações simples

    public Task<List<Slot>> GetAllSlotsAsync(int doctorId) => business.GetAllSlotsAsync(doctorId);

    public Task<List<Appointment>> GetDoctorDayAppointmentsAsync(int doctorId, DateOnly day) => business.GetDoctorDayAppointmentsAsync(doctorId, day);

    public Task<Client?> GetClientByIdAsync(int id) => business.GetClientByIdAsync(id);

    public Task<Doctor?> GetDoctorByIdAsync(int id) => business.GetDoctorByIdAsync(id);

    public Task<Appointment?> GetAppointmentByIdAsync(int id) => business.GetAppointmentByIdAsync(id);

    public Task<Slot?> GetSlotByIdAsync(int id) => business.GetSlotByIdAsync(id);

    public Task<DoctorDaySchedule?> GetDoctorDayScheduleAsync(int doctorId, DateOnly day) =>
        business.GetDoctorDayScheduleAsync(doctorId, day);

    // sem cache aqui: o que importa são os dados mais recentes (um paciente
    // que acabou de editar ou excluir sua conta)
    public Task<Client?> GetClientByUserIdAsync(int userId) => business.GetClientByUserIdAsync(userId);

    public Task<List<Appointment>> GetClientUpcomingAppointmentsAsync(int clientId) => business.GetClientUpcomingAppointmentsAsync(clientId);

    public Task<Appointment> AddAppointmentAsync(DateOnly day, Slot slot, Client client) => business.AddAppointmentAsync(day, slot, client);

    public Task DeleteAppointmentAsync(Appointment appointment) => business.DeleteAppointmentAsync(appointment);

    // gravações => recarga

    public async Task<Doctor> AddDoctorAsync(PersonData data)
    {
        var doctor = await business.AddDoctorAsync(data);
        await ReloadDoctorsAsync();
        return doctor;
    }

    public async Task<Doctor> EditDoctorAsync(int id, PersonData data)
    {
        var doctor = await business.EditDoctorAsync(id, data);
        await ReloadDoctorsAsync();
        return doctor;
    }

    public async Task DeleteDoctorAsync(int id)
    {
        await business.DeleteDoctorAsync(id);
        await ReloadDoctorsAsync();
    }

    public async Task<Client> AddClientAsync(PersonData data)
    {
        var client = await business.AddClientAsync(data);
        await ReloadClientsAsync();
        return client;
    }

    public async Task<Client> EditClientAsync(int id, PersonData data)
    {
        var client = await business.EditClientAsync(id, data);
        await ReloadClientsAsync();
        return client;
    }

    public async Task DeleteClientAsync(int id)
    {
        await business.DeleteClientAsync(id);
        await ReloadClientsAsync();
    }
}

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

// =========================================================================
// Web/Validation.cs
// -------------------------------------------------------------------------
// O que é necessário para REEXIBIR um formulário recusado: os erros de entrada
// campo a campo e os campos a destacar em vermelho.
// =========================================================================

using Microsoft.AspNetCore.Mvc.ModelBinding;
using RdvMedecins.Models;

namespace RdvMedecins.Web;

public static class Validation
{
    // -----------------------------------------------------------------------
    // ModelState (preenchido pelo MVC ao vincular o formulário) -> o
    // dicionário campo -> chave de mensagem, mantendo apenas a primeira
    // mensagem de cada campo: { "LastName": "ERRORS.LASTNAME_REQUIRED", ... }
    // -----------------------------------------------------------------------
    public static Dictionary<string, string> ErrorsOf(ModelStateDictionary modelState)
    {
        var errors = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
        foreach (var (field, entry) in modelState)
        {
            if (entry.Errors.Count > 0)
            {
                var message = entry.Errors[0].ErrorMessage;
                errors[field] = string.IsNullOrEmpty(message) ? "ERRORS.INVALID_FORM" : message;
            }
        }
        return errors;
    }

    // -----------------------------------------------------------------------
    // os campos do formulário envolvidos em cada erro de negócio de "entrada"
    // (uma duplicata): eles são destacados em vermelho, e a mensagem fica no pé da página
    // -----------------------------------------------------------------------
    public static readonly Dictionary<string, string[]> BusinessErrorFields = new()
    {
        ["ERRORS.LOGIN_TAKEN"] = ["login"],
        ["ERRORS.DOCTOR_ALREADY_EXISTS"] = ["firstName", "lastName"],
        ["ERRORS.PATIENT_ALREADY_EXISTS"] = ["firstName", "lastName"],
    };

    // -----------------------------------------------------------------------
    // prepara um modelo de formulário para sua (re)exibição:
    //   errors       : mensagem sob cada campo recusado pela validação
    //   error        : O mensagem de erro da página, exibida no pé da página;
    //                  por padrão "The form contains errors." se houver
    //                  erros de campo
    //   otherFields  : campos a destacar em vermelho SEM mensagem própria
    // -----------------------------------------------------------------------
    public static T Prepare<T>(
        T model,
        Dictionary<string, string>? errors = null,
        string? error = null,
        IEnumerable<string>? otherFields = null,
        IReadOnlyDictionary<string, string>? errorParams = null) where T : FormView
    {
        model.Errors = errors ?? new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
        model.InvalidFields = new HashSet<string>(model.Errors.Keys.Concat(otherFields ?? []), StringComparer.OrdinalIgnoreCase);
        model.Error = error ?? (model.Errors.Count > 0 ? "ERRORS.INVALID_FORM" : null);
        model.ErrorParams = errorParams;
        return model;
    }
}

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

// =========================================================================
// Web/Utils.cs
// -------------------------------------------------------------------------
// Pequenas funções utilitárias da camada web:
//   - Labels   : "Mme Alice DURAND";
//   - WebDates : datas "yyyy-MM-dd", horas "8:05", dias "Wednesday 23 September 2026";
//   - Input    : leitura de um inteiro positivo enviado pelo navegador;
//   - Patient  : o paciente (entidade Client) do usuário conectado.
//
// classes "static": elas só contêm funções, nunca criamos
// um objeto dessas classes.
// =========================================================================

using System.Globalization;
using System.Security.Claims;
using RdvMedecins.Auth;
using RdvMedecins.Entities;

namespace RdvMedecins.Web;

public static class Labels
{
    // "Mme Alice DURAND"
    public static string Label(Person p) => $"{p.Title} {p.FirstName} {p.LastName}";
}

public static class WebDates
{
    // o formato das datas nas URLs e no campo <input type="date">
    public const string IsoFormat = "yyyy-MM-dd";

    // true se [day] for uma data que existe no formato yyyy-MM-dd
    // ("2026-02-30" é recusada)
    public static bool IsValidDate(string? text, out DateOnly day) =>
        DateOnly.TryParseExact(text, IsoFormat, CultureInfo.InvariantCulture, DateTimeStyles.None, out day);

    public static string Iso(DateOnly day) => day.ToString(IsoFormat, CultureInfo.InvariantCulture);

    // "8:05" em vez de "8:5"
    public static string FormatTime(int h, int m) => $"{h}:{m:00}";

    public static string Time(Slot s) => $"{FormatTime(s.StartHour, s.StartMinute)} - {FormatTime(s.EndHour, s.EndMinute)}";

    // "mercredi 23 septembre 2026" / "Wednesday 23 September 2026", conforme o
    // idioma da requisição (CultureInfo.CurrentCulture, definido pelo
    // middleware de localização, veja Program.cs)
    public static string FormatDay(DateOnly day) =>
        day.ToString("dddd d MMMM yyyy", CultureInfo.CurrentCulture);
}

public static class Input
{
    // "3" -> 3 ; "", "abc", "-2", null -> null
    public static int? PositiveInteger(string? value) =>
        int.TryParse(value, NumberStyles.None, CultureInfo.InvariantCulture, out var n) && n > 0 ? n : null;
}

public static class Patient
{
    // -----------------------------------------------------------------------
    // O paciente (entidade Client) que corresponde ao usuário conectado.
    //
    // O token JWT contém apenas o id da CONTA (users.id). Para o
    // papel USER, encontramos o cliente correspondente graças à coluna clients.user.
    //
    // Se não houver nenhum, a conta foi excluída desde o
    // login enquanto seu token ainda é válido: tratamos isso como uma
    // sessão expirada (veja InvalidSessionException).
    // -----------------------------------------------------------------------
    public static async Task<Client> ConnectedPatientAsync(ApplicationModel application, ClaimsPrincipal user)
    {
        var currentUser = user.CurrentUser() ?? throw new InvalidSessionException();
        return await application.GetClientByUserIdAsync(currentUser.UserId) ?? throw new InvalidSessionException();
    }
}

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

// =========================================================================
// Models/Forms.cs
// -------------------------------------------------------------------------
// Os campos dos formulários de "pessoa" e suas restrições. Três
// formulários compartilham os mesmos campos de identidade (título, nome, sobrenome):
//
//   PersonFields                  título, nome, sobrenome
//    ├─ PersonForm                + login / senha OPCIONAIS, versão
//    │                              (o ADMIN adiciona ou edita um médico / cliente)
//    ├─ RegistrationForm          + login / senha / confirmação OBRIGATÓRIOS
//    │                              (um paciente cria sua conta)
//    └─ MyAccountForm             + login, nova senha opcional,
//                                   senha ATUAL OBRIGATÓRIA, versão
//                                   (um paciente edita sua conta)
//
// MODEL BINDING: quando uma action de controller recebe
// um parâmetro de uma destas classes, o ASP.NET Core MVC cria o objeto e
// preenche cada propriedade com o campo de formulário de mesmo nome (sem distinção
// de maiúsculas e minúsculas: o campo "lastName" preenche a propriedade LastName).
//
// VALIDAÇÃO: logo depois, o MVC verifica os atributos [Required],
// [MaxLength]... (namespace padrão System.ComponentModel.DataAnnotations,
// o equivalente ao class-validator) e armazena os erros em ModelState.
// O controller só precisa testar ModelState.IsValid.
//
// As mensagens de erro são CHAVES de tradução (veja i18n/*.json).
//
// LIMPEZA DA ENTRADA (o equivalente ao @Transform do class-transformer):
//   - o MVC já transforma um campo vazio em null;
//   - os setters abaixo removem os espaços supérfluos e colocam o
//     login em minúsculas. Uma senha, porém, não é "limpa" (os
//     espaços podem fazer parte dela).
// Todas as propriedades são "nullable" (string?): um campo sempre pode
// estar ausente do que o navegador envia; é o [Required] que o exige.
// =========================================================================

using System.ComponentModel.DataAnnotations;

namespace RdvMedecins.Models;

public static class InputRules
{
    public static readonly string[] Titles = ["Mr", "Mme", "Melle"];

    // login: letras minúsculas, dígitos, ponto, hífen, sublinhado, no máximo 30 caracteres
    public const string LoginFormat = "^[a-z0-9._-]{1,30}$";

    // tamanho mínimo de uma senha ESCOLHIDA por um paciente
    public const int PasswordMin = 6;

    // "  dupont " -> "dupont" ; "   " -> null
    public static string? Clean(string? value) => string.IsNullOrWhiteSpace(value) ? null : value.Trim();
}

// -------------------------------------------------------------------------
// Um atributo de validação "caseiro": o valor deve pertencer a uma lista.
// Basta herdar de ValidationAttribute e escrever IsValid.
// -------------------------------------------------------------------------
public class OneOfAttribute(params string[] values) : ValidationAttribute
{
    // null é aceito aqui: é papel do [Required] exigi-lo
    public override bool IsValid(object? value) => value is null || values.Contains(value as string);
}

// base comum
public class PersonFields
{
    [Required(ErrorMessage = "ERRORS.INVALID_TITLE")]
    [OneOf("Mr", "Mme", "Melle", ErrorMessage = "ERRORS.INVALID_TITLE")]
    public string? Title { get; set; }

    // tamanhos máximos = os das colunas SQL (VARCHAR(20))
    private string? firstName;

    [Required(ErrorMessage = "ERRORS.FIRSTNAME_REQUIRED")]
    [MaxLength(20, ErrorMessage = "ERRORS.FIRSTNAME_TOO_LONG")]
    public string? FirstName
    {
        get => firstName;
        set => firstName = InputRules.Clean(value);
    }

    private string? lastName;

    [Required(ErrorMessage = "ERRORS.LASTNAME_REQUIRED")]
    [MaxLength(20, ErrorMessage = "ERRORS.LASTNAME_TOO_LONG")]
    public string? LastName
    {
        get => lastName;
        set => lastName = InputRules.Clean(value);
    }
}

// ADMIN
public class PersonForm : PersonFields
{
    private string? login;

    // opcional (veja PersonData, Business/IBusiness.cs)
    [RegularExpression(InputRules.LoginFormat, ErrorMessage = "ERRORS.INVALID_LOGIN")]
    public string? Login
    {
        get => login;
        set => login = InputRules.Clean(value)?.ToLowerInvariant();
    }

    // opcional; no máximo 72 caracteres (acima disso, o bcrypt ignora o restante)
    [MaxLength(72, ErrorMessage = "ERRORS.PASSWORD_TOO_LONG")]
    public string? Password { get; set; }

    // campo oculto do formulário de edição (bloqueio otimista).
    // int?: um campo ausente ou vazio dá null; um texto que não é um
    // número dá um erro de binding (veja Program.cs, ModelBindingMessageProvider)
    public int? Version { get; set; }
}

// cadastro de um paciente
public class RegistrationForm : PersonFields
{
    private string? login;

    [Required(ErrorMessage = "ERRORS.LOGIN_REQUIRED")]
    [RegularExpression(InputRules.LoginFormat, ErrorMessage = "ERRORS.INVALID_LOGIN")]
    public string? Login
    {
        get => login;
        set => login = InputRules.Clean(value)?.ToLowerInvariant();
    }

    [Required(ErrorMessage = "ERRORS.PASSWORD_REQUIRED")]
    [MinLength(InputRules.PasswordMin, ErrorMessage = "ERRORS.PASSWORD_TOO_SHORT")]
    [MaxLength(72, ErrorMessage = "ERRORS.PASSWORD_TOO_LONG")]
    public string? Password { get; set; }

    [Required(ErrorMessage = "ERRORS.CONFIRMATION_REQUIRED")]
    public string? Confirmation { get; set; }
}

// "Manage my account"
public class MyAccountForm : PersonFields
{
    private string? login;

    [Required(ErrorMessage = "ERRORS.LOGIN_REQUIRED")]
    [RegularExpression(InputRules.LoginFormat, ErrorMessage = "ERRORS.INVALID_LOGIN")]
    public string? Login
    {
        get => login;
        set => login = InputRules.Clean(value)?.ToLowerInvariant();
    }

    // opcional: vazio = senha inalterada
    [MinLength(InputRules.PasswordMin, ErrorMessage = "ERRORS.PASSWORD_TOO_SHORT")]
    [MaxLength(72, ErrorMessage = "ERRORS.PASSWORD_TOO_LONG")]
    public string? Password { get; set; }

    public string? Confirmation { get; set; }

    // a senha ATUAL, exigida para qualquer modificação da conta
    [Required(ErrorMessage = "ERRORS.CURRENT_PASSWORD_REQUIRED")]
    public string? CurrentPassword { get; set; }

    public int? Version { get; set; }
}

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

// =========================================================================
// Models/ViewModels.cs
// -------------------------------------------------------------------------
// Os "view models": o que cada controller passa para
// sua view (return View("...", model)), em uma classe C# TIPADA. Em uma
// view Razor, @model ScheduleModel declara o tipo do modelo: o compilador
// verifica então cada @Model.Xxx da view: um erro de digitação é um erro de
// compilação, e não uma área vazia na página.
//
// Regra já seguida com o Handlebars: nenhuma lógica nas views. Os
// controllers preparam dados JÁ formatados ("Mme Marie
// PELISSIER", "8:00 - 8:20", Selected = true...) e já filtrados conforme
// o papel do usuário; as views apenas os colocam no HTML.
// =========================================================================

namespace RdvMedecins.Models;

// -------------------------------------------------------------------------
// o que TODAS as páginas têm em comum, lido pelo layout
// (Views/Shared/_Layout.cshtml)
// -------------------------------------------------------------------------
public abstract class ViewModel
{
    // chave de tradução do título da página (<title>)
    public string PageTitle { get; set; } = "APP.TITLE";

    // A mensagem de erro da página, exibida no pé da página
    // (veja Views/Shared/_Errors.cshtml); null = nenhum erro
    public string? Error { get; set; }

    public IReadOnlyDictionary<string, string>? ErrorParams { get; set; }
}

// uma opção de uma lista suspensa (médico, paciente)
public record OptionView(int Id, string Label, bool Selected);

// login
public class LoginModel : ViewModel
{
    public string Login { get; set; } = "";
    public required Auth.Captcha Captcha { get; set; }
}

// agenda
public class ScheduleRowView
{
    public int SlotId { get; init; }
    public string Time { get; init; } = ""; // "8:00 - 8:20"
    public bool Free { get; init; }
    public string? Patient { get; init; } // nome exibido para um horário reservado; null = "Booked"
    public bool Mine { get; init; } // a consulta do paciente conectado
    public bool Bookable { get; init; } // exibir o botão "Book"?
    public string BookUrl { get; init; } = "";
    public int? AppointmentId { get; init; } // preenchido somente se o botão "Cancel" for exibido
}

public record ScheduleView(string Doctor, string Day, List<ScheduleRowView> Rows);

public class BookingView
{
    public int SlotId { get; init; }
    public string Time { get; init; } = "";
    // ADMIN / DOCTOR: a lista de pacientes a escolher
    public List<OptionView> Clients { get; init; } = [];
    // USER: o paciente é o próprio usuário
    public string? Patient { get; init; }
}

public class ScheduleModel : ViewModel
{
    public List<OptionView> Doctors { get; set; } = [];
    public int? DoctorId { get; set; }
    public string Day { get; set; } = ""; // "yyyy-MM-dd"
    public ScheduleView? Schedule { get; set; }
    public BookingView? Booking { get; set; }
    public string BackUrl { get; set; } = "/schedule"; // a agenda exibida, sem diálogo de reserva
    // paciente que já tem uma consulta futura: a mensagem que explica
    // por que não há botão "Book"
    public string? Info { get; set; }
}

// formulários de "pessoa"

// os valores exibidos nos campos do formulário (nunca a senha)
public class PersonValues
{
    public string Title { get; set; } = "Mr";
    public string FirstName { get; set; } = "";
    public string LastName { get; set; } = "";
    public string Login { get; set; } = "";
    public int? Version { get; set; }
}

// o que o partial comum _PersonFields.cshtml usa (título, nome, sobrenome)
public abstract class FormView : ViewModel
{
    public PersonValues Values { get; set; } = new();

    // campo -> chave da mensagem exibida SOB este campo (erro de entrada)
    public Dictionary<string, string> Errors { get; set; } = new(StringComparer.OrdinalIgnoreCase);

    // campos a destacar em vermelho (classe Bootstrap is-invalid): os que têm
    // uma mensagem, mais eventualmente outros (nome + sobrenome duplicados, login em uso...)
    public HashSet<string> InvalidFields { get; set; } = new(StringComparer.OrdinalIgnoreCase);

    public string? ErrorOf(string field) => Errors.GetValueOrDefault(field);

    public string InvalidClass(string field) => InvalidFields.Contains(field) ? "is-invalid" : "";

    public IEnumerable<(string Value, bool Selected)> Titles =>
        InputRules.Titles.Select(t => (t, t == Values.Title));
}

public class PersonFormModel : FormView
{
    public bool Creating { get; set; } // true: adicionar; false: editar
    public string Action { get; set; } = ""; // URL do POST
    public string ListUrl { get; set; } = "";
}

public class RegistrationModel : FormView
{
    public int PasswordMin => InputRules.PasswordMin;
}

public class MyAccountModel : FormView
{
    public int PasswordMin => InputRules.PasswordMin;
}

// listas de médicos / clientes

// as chaves de tradução específicas de cada tipo de pessoa
public record PersonKeys(
    string Title, // "Doctors"
    string Add, // "Add a doctor"
    string Edit, // "Edit a doctor"
    string Empty, // "No doctors."
    string ConfirmDelete, // "Delete this doctor, their time slots and their user account?"
    string Added, // "Doctor {name} has been added (login: {login})."
    string Edited,
    string Deleted);

public record PersonView(string Title, string FirstName, string LastName, string Login, string EditUrl, string DeleteUrl);

public class PersonListModel : ViewModel
{
    public required PersonKeys Keys { get; set; }
    public string AddUrl { get; set; } = "";
    public List<PersonView> Persons { get; set; } = [];
}

// área do paciente
public record AppointmentView(int Id, string Day, string Time, string Doctor, string ScheduleUrl);

public class AreaModel : ViewModel
{
    public string Patient { get; set; } = "";
    public List<AppointmentView> Appointments { get; set; } = [];
}

// página de erro
public class ErrorModel : ViewModel
{
    public int Code { get; set; }
    public string Message { get; set; } = "ERRORS.SERVER_ERROR";
}

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

// =========================================================================
// Controllers/LanguageController.cs
// -------------------------------------------------------------------------
// GET /language/fr, GET /language/en: os dois botões FR / EN da barra de
// navegação. Rota não protegida: deve ser possível trocar de idioma antes de
// fazer login.
//
// A escolha é armazenada no cookie do middleware de localização
// do ASP.NET Core (CookieRequestCultureProvider, veja Program.cs): a cada
// requisição seguinte, esse middleware o lê de volta e define o idioma da requisição
// (CultureInfo.CurrentCulture / CurrentUICulture). Depois voltamos à
// página de onde viemos.
// =========================================================================

using Microsoft.AspNetCore.Localization;
using Microsoft.AspNetCore.Mvc;
using RdvMedecins.Web;

namespace RdvMedecins.Controllers;

public class LanguageController : Controller
{
    [HttpGet("language/{language}")]
    public IActionResult Change(string language)
    {
        if (!Translator.Languages.Contains(language))
        {
            return NotFound(); // -> página de erro 404 (veja Program.cs)
        }
        Response.Cookies.Append(
            CookieRequestCultureProvider.DefaultCookieName,
            // valor do cookie: "c=en|uic=en" (idioma dos formatos, idioma dos textos)
            CookieRequestCultureProvider.MakeCookieValue(new RequestCulture(language)),
            new CookieOptions { MaxAge = TimeSpan.FromDays(365), SameSite = SameSiteMode.Lax, HttpOnly = true, Path = "/" });
        return Redirect(OriginPage());
    }

    // a página anterior, segundo o cabeçalho HTTP "Referer" enviado pelo
    // navegador. Mantemos apenas seu caminho (/schedule?...): redirecionar para um
    // endereço completo fornecido pela requisição permitiria enviar
    // o usuário a outro site (a chamada falha de "open redirect").
    private string OriginPage()
    {
        var referer = Request.Headers.Referer.ToString();
        if (!Uri.TryCreate(referer, UriKind.Absolute, out var url))
        {
            return "/";
        }
        return url.AbsolutePath.StartsWith("/language/", StringComparison.Ordinal) ? "/" : url.PathAndQuery;
    }
}

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

// =========================================================================
// Controllers/ScheduleController.cs
// -------------------------------------------------------------------------
// A página da agenda: escolha de um médico e de um dia, agenda desse
// médico nesse dia, marcação e cancelamento de consultas.
//
//   GET  /schedule?doctorId=1&day=2026-09-23               a página
//   GET  /schedule?doctorId=1&day=2026-09-23&book=7        a mesma página, com
//                                                          o diálogo de marcação
//                                                          do horário 7 aberto
//   POST /schedule/book                                    cria uma consulta
//   POST /schedule/cancel                                  cancela uma consulta
//
// A página inteira é descrita por sua URL: ela pode ser recarregada,
// adicionada aos favoritos, e o botão "Voltar" do navegador pode ser usado, sem uma única linha
// de JavaScript.
//
// O que cada um vê e pode fazer:
//
//   | papel         | horário reservado exibido         | Reservar           | Cancelar |
//   |_______________|___________________________________|____________________|__________|
//   | ADMIN, DOCTOR | nome do paciente                  | para um paciente   | sim      |
//   |               |                                   | escolhido em uma   |          |
//   | USER (paciente)| "Booked", ou SEU nome se for     | para si mesmo, se  | não (*)  |
//   |               | sua própria consulta              | não tiver          |          |
//   |               |                                   | consulta futura    |          |
//
//   (*) o paciente cancela sua consulta na sua página "My area".
//
// CONFIDENCIALIDADE: para um paciente, o nome dos OUTROS pacientes não é
// simplesmente ocultado pela view: ele nunca é colocado no modelo
// passado à view. O HTML enviado ao navegador portanto não o contém,
// nem mesmo oculto (um simples "Exibir código-fonte da página" o revelaria de outra forma).
//
// Nenhuma marcação no passado: o botão "Book" só aparece
// para hoje e os dias seguintes (e a camada de negócio a recusaria
// de qualquer forma).
//
// [Authorize] na classe: todas as actions exigem um usuário
// logado (o equivalente a @UseGuards(JwtAuthGuard)). [Authorize(Roles =
// "...")] em uma action exige adicionalmente um dos papéis listados (RolesGuard +
// @Roles). Sem token válido: volta para /login; papel insuficiente: página 403.
// =========================================================================

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using RdvMedecins.Auth;
using RdvMedecins.Entities;
using RdvMedecins.Business;
using RdvMedecins.Models;
using RdvMedecins.Web;

namespace RdvMedecins.Controllers;

[Authorize]
[Route("schedule")]
public class ScheduleController(ApplicationModel application) : Controller
{
    // o que o controller sabe sobre o usuário, para decidir o que exibir
    private record Rights(
        bool Manager, // ADMIN ou DOCTOR
        Client? Patient, // o cliente conectado (papel USER), caso contrário null
        bool PatientCanBook); // USER sem consulta futura
  • 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

    // -----------------------------------------------------------------------
    // GET /schedule
    // Os parâmetros da URL são lidos brutos (Request.Query), para distinguir
    // um parâmetro AUSENTE de um VAZIO (?doctorId=).
    // -----------------------------------------------------------------------
    [HttpGet("")]
    public async Task<IActionResult> Show()
    {
        string? error = null;
        var user = User.CurrentUser()!;
        var rights = await RightsAsync(user);

        // o dia: o da URL se for válido, caso contrário hoje
        var day = Dates.Today();
        if (Request.Query.TryGetValue("day", out var rawDay))
        {
            if (WebDates.IsValidDate(rawDay, out var requestedDay))
            {
                day = requestedDay;
            }
            else
            {
                error = "ERRORS.INVALID_DATE";
            }
        }
        var dayBookable = day >= Dates.Today();

        // o médico: o da URL; na falta dele, para um médico logado, ele próprio
        var doctorId = Input.PositiveInteger(Request.Query["doctorId"]);
        if (!Request.Query.ContainsKey("doctorId") && user.Role == Role.DOCTOR)
        {
            doctorId = application.GetDoctorByUserId(user.UserId)?.Id;
        }

        var doctors = (await application.GetAllDoctorsAsync())
            .Select(d => Option(d, d.Id == doctorId))
            .ToList();

        // a agenda, se um médico estiver escolhido (e a data for válida)
        ScheduleView? schedule = null;
        if (doctorId is int id && error is null)
        {
            var doctorSchedule = await application.GetDoctorDayScheduleAsync(id, day);
            if (doctorSchedule is null)
            {
                error = "ERRORS.DOCTOR_NOT_FOUND";
            }
            else
            {
                var rows = doctorSchedule.DoctorDaySlots.Select(dds =>
                {
                    var (slot, appointment) = (dds.Slot, dds.Appointment);
                    var free = appointment is null;
                    // a consulta do paciente conectado?
                    var mine = appointment is not null && rights.Patient is not null && appointment.ClientId == rights.Patient.Id;
                    return new ScheduleRowView
                    {
                        SlotId = slot.Id,
                        Time = WebDates.Time(slot),
                        Free = free,
                        // O ponto de confidencialidade: um paciente só recebe o nome da
                        // SUA consulta; para as demais, null (a view exibe "Booked")
                        Patient = appointment is not null && (rights.Manager || mine) ? Labels.Label(appointment.Client) : null,
                        Mine = mine,
                        Bookable = free && dayBookable && (rights.Manager || rights.PatientCanBook),
                        BookUrl = ScheduleUrl(id, day, slot.Id),
                        AppointmentId = appointment is not null && rights.Manager ? appointment.Id : null,
                    };
                }).ToList();
                schedule = new ScheduleView(Labels.Label(doctorSchedule.Doctor), WebDates.Iso(day), rows);
            }
        }
  • 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

        // o diálogo de marcação: somente se o horário solicitado puder ser
        // reservado por este usuário
        BookingView? booking = null;
        var slotId = Input.PositiveInteger(Request.Query["book"]);
        var row = schedule?.Rows.FirstOrDefault(r => r.SlotId == slotId && r.Bookable);
        if (row is not null)
        {
            booking = new BookingView
            {
                SlotId = row.SlotId,
                Time = row.Time,
                Clients = rights.Manager
                    ? (await application.GetAllClientsAsync()).Select(c => Option(c, false)).ToList()
                    : [],
                Patient = rights.Patient is not null ? Labels.Label(rights.Patient) : null,
            };
        }

        return View("Schedule", new ScheduleModel
        {
            PageTitle = "SCHEDULE.PAGE_TITLE",
            Doctors = doctors,
            DoctorId = doctorId,
            Day = WebDates.Iso(day),
            Schedule = schedule,
            Booking = booking,
            BackUrl = doctorId is int dId ? ScheduleUrl(dId, day) : "/schedule",
            Info = rights.Patient is not null && !rights.PatientCanBook ? "SCHEDULE.ALREADY_BOOKED_INFO" : null,
            Error = error,
        });
    }
  • 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

    // -----------------------------------------------------------------------
    // POST /schedule/book   campos: doctorId, day, slotId, clientId
    //
    // Para um paciente (USER), o campo clientId é IGNORADO: ele sempre marca
    // para si mesmo. Confiar em um campo enviado pelo
    // navegador permitiria a um paciente esperto marcar em nome de outra pessoa.
    //
    // Padrão "Post / Redirect / Get": qualquer que seja o resultado, não
    // construímos uma página aqui: colocamos uma mensagem flash e redirecionamos
    // para a agenda (veja Web/Flash.cs).
    // -----------------------------------------------------------------------
    [HttpPost("book")]
    [Authorize(Roles = "ADMIN,DOCTOR,USER")]
    public async Task<IActionResult> Book(
        [FromForm] string? doctorId,
        [FromForm] string? day,
        [FromForm] string? slotId,
        [FromForm] string? clientId)
    {
        if (!ReadScheduleRequest(doctorId, day, out var docId, out var requestedDay)
            || Input.PositiveInteger(slotId) is not int sltId)
        {
            return BadRequest(); // -> página "invalid request" (veja Program.cs)
        }

        Client? client;
        if (User.IsInRole(nameof(Role.USER)))
        {
            client = await Patient.ConnectedPatientAsync(application, User);
        }
        else
        {
            if (Input.PositiveInteger(clientId) is not int cliId)
            {
                // nenhum paciente escolhido: reabrimos o diálogo de marcação
                Flash.Put(HttpContext, FlashType.Danger, "ERRORS.CHOOSE_PATIENT");
                return Redirect(ScheduleUrl(docId, requestedDay, sltId));
            }
            client = await application.GetClientByIdAsync(cliId);
        }

        var slot = await application.GetSlotByIdAsync(sltId);
        if (client is null)
        {
            Flash.Put(HttpContext, FlashType.Danger, "ERRORS.PATIENT_NOT_FOUND");
        }
        else if (slot is null || slot.DoctorId != docId)
        {
            Flash.Put(HttpContext, FlashType.Danger, "ERRORS.SLOT_NOT_FOUND");
        }
        else
        {
            try
            {
                // as regras (não no passado, uma única consulta futura por
                // paciente, horário livre) são verificadas pela camada de negócio
                await application.AddAppointmentAsync(requestedDay, slot, client);
                Flash.Put(HttpContext, FlashType.Success, "SCHEDULE.BOOKED");
            }
            // "when": um filtro de exceção. A mesma regra, mas com uma mensagem na 2ª
            // pessoa quando é o próprio paciente que marca ("You
            // already have..." em vez de "This patient...")
            catch (BusinessException e) when (e.Key == "ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT" && User.IsInRole(nameof(Role.USER)))
            {
                Flash.Put(HttpContext, FlashType.Danger, "SCHEDULE.ALREADY_BOOKED_INFO");
            }
            // qualquer outra BusinessException vira uma mensagem flash; as outras
            // exceções (anomalias reais) não são capturadas: página 500
            catch (BusinessException e)
            {
                Flash.Put(HttpContext, FlashType.Danger, e.Key, new Dictionary<string, string>(e.Params));
            }
        }
        return Redirect(ScheduleUrl(docId, requestedDay));
    }
  • 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

    // -----------------------------------------------------------------------
    // POST /schedule/cancel   campos: appointmentId, doctorId, day
    // (um paciente cancela SUA consulta em "My area", não daqui)
    // -----------------------------------------------------------------------
    [HttpPost("cancel")]
    [Authorize(Roles = "ADMIN,DOCTOR")]
    public async Task<IActionResult> Cancel([FromForm] string? appointmentId, [FromForm] string? doctorId, [FromForm] string? day)
    {
        if (!ReadScheduleRequest(doctorId, day, out var docId, out var requestedDay)
            || Input.PositiveInteger(appointmentId) is not int id)
        {
            return BadRequest();
        }
        var appointment = await application.GetAppointmentByIdAsync(id);
        if (appointment is null)
        {
            // já cancelada (por outra pessoa, ou clique duplo)
            Flash.Put(HttpContext, FlashType.Danger, "ERRORS.APPOINTMENT_NOT_FOUND");
        }
        else
        {
            await application.DeleteAppointmentAsync(appointment);
            Flash.Put(HttpContext, FlashType.Success, "SCHEDULE.CANCELLED");
        }
        return Redirect(ScheduleUrl(docId, requestedDay));
    }
  • 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

    // -----------------------------------------------------------------------
    // quem está logado e o que essa pessoa pode fazer nesta página?
    // -----------------------------------------------------------------------
    private async Task<Rights> RightsAsync(ConnectedUser user)
    {
        if (user.Role != Role.USER)
        {
            return new Rights(Manager: true, Patient: null, PatientCanBook: false);
        }
        var patient = await Patient.ConnectedPatientAsync(application, User);
        var upcoming = await application.GetClientUpcomingAppointmentsAsync(patient.Id);
        return new Rights(Manager: false, patient, PatientCanBook: upcoming.Count == 0);
    }

    // funções utilitárias

    // os campos ocultos doctorId / day, comuns aos dois formulários POST
    private static bool ReadScheduleRequest(string? rawDoctorId, string? rawDay, out int doctorId, out DateOnly day)
    {
        doctorId = Input.PositiveInteger(rawDoctorId) ?? 0;
        return WebDates.IsValidDate(rawDay, out day) && doctorId > 0;
    }

    private static string ScheduleUrl(int doctorId, DateOnly day, int? book = null)
    {
        var url = $"/schedule?doctorId={doctorId}&day={WebDates.Iso(day)}";
        return book is null ? url : $"{url}&book={book}";
    }

    private static OptionView Option(Person p, bool selected) => new(p.Id, Labels.Label(p), selected);
}
  • 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

// =========================================================================
// Controllers/PersonsControllerBase.cs
// -------------------------------------------------------------------------
// A gestão dos médicos e a dos clientes (reservadas ao ADMIN) são
// IDÊNTICAS: mesma lista, mesmo formulário, mesmas regras. Em vez de
// escrever as mesmas actions duas vezes, nós as escrevemos uma só vez nesta
// classe ABSTRATA e GENÉRICA, da qual DoctorsController
// ([Route("doctors")]) e ClientsController ([Route("clients")]) herdam. Cada
// subclasse só precisa fornecer sua "configuração": quais métodos
// chamar, quais rótulos exibir.
//
// As rotas colocadas AQUI ([HttpGet("add")]...) são herdadas e
// completam a rota da subclasse. Obtemos assim, para cada uma:
//
//   GET  /doctors                    lista
//   GET  /doctors/add                formulário vazio
//   POST /doctors/add                criação
//   GET  /doctors/{id}/edit          formulário preenchido
//   POST /doctors/{id}/edit          atualização
//   POST /doctors/{id}/delete        exclusão
//
// (e as mesmas URLs sob /clients). As views também são comuns:
// Views/Persons/List.cshtml e Views/Persons/Form.cshtml.
//
// Uma classe abstrata nunca é tomada por um controller pelo MVC: apenas
// suas subclasses concretas o são.
// =========================================================================

using Microsoft.AspNetCore.Mvc;
using RdvMedecins.Entities;
using RdvMedecins.Business;
using RdvMedecins.Models;
using RdvMedecins.Web;

namespace RdvMedecins.Controllers;

// o que cada subclasse deve fornecer
public record PersonsConfig<T>(
    string Url, // "/doctors" ou "/clients"
    PersonKeys Keys,
    Func<Task<List<T>>> List,
    Func<int, Task<T?>> Find,
    Func<PersonData, Task<T>> Add,
    Func<int, PersonData, Task<T>> Edit,
    Func<int, Task> Delete) where T : Person;

public abstract class PersonsControllerBase<T>(ApplicationModel application) : Controller where T : Person
{
    protected ApplicationModel Application { get; } = application;

    protected abstract PersonsConfig<T> Config { get; }

    // -----------------------------------------------------------------------
    // GET /doctors (ou /clients)
    // -----------------------------------------------------------------------
    [HttpGet("")]
    public async Task<IActionResult> List()
    {
        var persons = await Config.List();
        return View("~/Views/Persons/List.cshtml", new PersonListModel
        {
            PageTitle = Config.Keys.Title,
            Keys = Config.Keys,
            AddUrl = $"{Config.Url}/add",
            Persons = persons
                .Select(p => new PersonView(p.Title, p.FirstName, p.LastName, p.User?.Login ?? "",
                    $"{Config.Url}/{p.Id}/edit", $"{Config.Url}/{p.Id}/delete"))
                .ToList(),
        });
    }

    // -----------------------------------------------------------------------
    // GET /doctors/add
    // -----------------------------------------------------------------------
    [HttpGet("add")]
    public IActionResult AddForm() => ShowForm(null, new PersonValues());

    // -----------------------------------------------------------------------
    // POST /doctors/add
    // [form] foi preenchido E validado pelo MVC: ModelState diz se a
    // entrada está correta.
    // -----------------------------------------------------------------------
    [HttpPost("add")]
    public async Task<IActionResult> Add(PersonForm form)
    {
        if (!ModelState.IsValid)
        {
            return ShowForm(null, EnteredValues(form), Validation.ErrorsOf(ModelState));
        }
        try
        {
            var person = await Config.Add(Data(form));
            Flash.Put(HttpContext, FlashType.Success, Config.Keys.Added, MessageParams(person));
            return Redirect(Config.Url);
        }
        catch (BusinessException e)
        {
            return ShowBusinessError(null, EnteredValues(form), e);
        }
    }

    // -----------------------------------------------------------------------
    // GET /doctors/{id}/edit
    // {id:int}: uma "restrição de rota": /doctors/abc/edit não
    // corresponde a nenhuma rota (página 404)
    // -----------------------------------------------------------------------
    [HttpGet("{id:int}/edit")]
    public async Task<IActionResult> EditForm(int id)
    {
        var person = await Config.Find(id);
        if (person is null)
        {
            return NotFound();
        }
        return ShowForm(id, new PersonValues
        {
            Title = person.Title,
            FirstName = person.FirstName,
            LastName = person.LastName,
            Login = person.User?.Login ?? "",
            Version = person.Version,
        });
    }

    // -----------------------------------------------------------------------
    // POST /doctors/{id}/edit
    // -----------------------------------------------------------------------
    [HttpPost("{id:int}/edit")]
    public async Task<IActionResult> Edit(int id, PersonForm form)
    {
        if (!ModelState.IsValid)
        {
            return ShowForm(id, EnteredValues(form), Validation.ErrorsOf(ModelState));
        }
        try
        {
            var person = await Config.Edit(id, Data(form));
            Flash.Put(HttpContext, FlashType.Success, Config.Keys.Edited, MessageParams(person));
            return Redirect(Config.Url);
        }
        catch (BusinessException e)
        {
            return ShowBusinessError(id, EnteredValues(form), e);
        }
    }

    // -----------------------------------------------------------------------
    // POST /doctors/{id}/delete
    // (a confirmação "Are you sure?" é pedida pelo navegador antes de
    // enviar o formulário, veja wwwroot/js/app.js)
    // -----------------------------------------------------------------------
    [HttpPost("{id:int}/delete")]
    public async Task<IActionResult> Delete(int id)
    {
        var person = await Config.Find(id);
        try
        {
            await Config.Delete(id);
            Flash.Put(HttpContext, FlashType.Success, Config.Keys.Deleted, MessageParams(person));
        }
        catch (BusinessException e)
        {
            Flash.Put(HttpContext, FlashType.Danger, e.Key, new Dictionary<string, string>(e.Params));
        }
        return Redirect(Config.Url);
    }

    // métodos privados

    // id null: formulário de criação; caso contrário: formulário de edição
    private ViewResult ShowForm(
        int? id,
        PersonValues values,
        Dictionary<string, string>? errors = null,
        string? error = null,
        IEnumerable<string>? otherFields = null)
    {
        var creating = id is null;
        return View("~/Views/Persons/Form.cshtml", Validation.Prepare(
            new PersonFormModel
            {
                PageTitle = creating ? Config.Keys.Add : Config.Keys.Edit,
                Creating = creating,
                Action = creating ? $"{Config.Url}/add" : $"{Config.Url}/{id}/edit",
                ListUrl = Config.Url,
                Values = values,
            },
            errors, error, otherFields));
    }

    // uma regra de negócio recusou a gravação: reexibimos o formulário,
    // com a entrada do usuário e a mensagem da camada de negócio
    private IActionResult ShowBusinessError(int? id, PersonValues values, BusinessException e)
    {
        if (e.Key is "ERRORS.DOCTOR_NOT_FOUND" or "ERRORS.PATIENT_NOT_FOUND")
        {
            // excluído nesse meio-tempo por outro ADMIN: volta para a lista
            Flash.Put(HttpContext, FlashType.Danger, e.Key);
            return Redirect(Config.Url);
        }
        // a mensagem vai no pé da página; os campos envolvidos, se houver, são
        // destacados em vermelho para que o usuário veja imediatamente o que corrigir
        return ShowForm(id, values, null, e.Key, Validation.BusinessErrorFields.GetValueOrDefault(e.Key));
    }

    // o que o usuário digitou (senha excluída: nunca a enviamos de volta ao navegador)
    private static PersonValues EnteredValues(PersonForm f) => new()
    {
        Title = f.Title ?? "",
        FirstName = f.FirstName ?? "",
        LastName = f.LastName ?? "",
        Login = f.Login ?? "",
        Version = f.Version,
    };

    // o formulário validado -> os dados esperados pela camada de negócio
    private static PersonData Data(PersonForm f) => new()
    {
        Title = f.Title!,
        LastName = f.LastName!,
        FirstName = f.FirstName!,
        Login = f.Login,
        Password = f.Password,
        Version = f.Version,
    };

    // {name} e {login} das mensagens "added / updated / deleted"
    private static Dictionary<string, string> MessageParams(Person? person) => person is null
        ? new() { ["name"] = "", ["login"] = "" }
        : new() { ["name"] = $"{person.FirstName} {person.LastName}", ["login"] = person.User?.Login ?? "" };
}

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

// =========================================================================
// Controllers/DoctorsController.cs
// -------------------------------------------------------------------------
// Gestão dos médicos (somente papel ADMIN). Todas as actions são
// herdadas de PersonsControllerBase: resta aqui apenas dizer O QUE
// chamar e QUAIS rótulos exibir.
//
// [Authorize(Roles = "ADMIN")] colocado na CLASSE aplica-se a todas as suas
// actions, inclusive as herdadas.
// =========================================================================

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using RdvMedecins.Entities;
using RdvMedecins.Models;
using RdvMedecins.Web;

namespace RdvMedecins.Controllers;

[Authorize(Roles = "ADMIN")]
[Route("doctors")]
public class DoctorsController(ApplicationModel application) : PersonsControllerBase<Doctor>(application)
{
    protected override PersonsConfig<Doctor> Config => new(
        Url: "/doctors",
        Keys: new PersonKeys(
            Title: "DOCTORS.TITLE",
            Add: "DOCTORS.ADD",
            Edit: "DOCTORS.EDIT",
            Empty: "DOCTORS.EMPTY",
            ConfirmDelete: "DOCTORS.DELETE_CONFIRM",
            Added: "DOCTORS.ADDED",
            Edited: "DOCTORS.UPDATED",
            Deleted: "DOCTORS.DELETED"),
        List: Application.GetAllDoctorsAsync,
        Find: Application.GetDoctorByIdAsync,
        Add: Application.AddDoctorAsync,
        Edit: Application.EditDoctorAsync,
        Delete: Application.DeleteDoctorAsync);
}
  • 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

// =========================================================================
// Controllers/ClientsController.cs
// -------------------------------------------------------------------------
// Gestão dos clientes (os PACIENTES do consultório), somente papel ADMIN.
// Mesmo princípio de DoctorsController (veja seus comentários).
// =========================================================================

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using RdvMedecins.Entities;
using RdvMedecins.Models;
using RdvMedecins.Web;

namespace RdvMedecins.Controllers;

[Authorize(Roles = "ADMIN")]
[Route("clients")]
public class ClientsController(ApplicationModel application) : PersonsControllerBase<Client>(application)
{
    protected override PersonsConfig<Client> Config => new(
        Url: "/clients",
        Keys: new PersonKeys(
            Title: "CLIENTS.TITLE",
            Add: "CLIENTS.ADD",
            Edit: "CLIENTS.EDIT",
            Empty: "CLIENTS.EMPTY",
            ConfirmDelete: "CLIENTS.DELETE_CONFIRM",
            Added: "CLIENTS.ADDED",
            Edited: "CLIENTS.UPDATED",
            Deleted: "CLIENTS.DELETED"),
        List: Application.GetAllClientsAsync,
        Find: Application.GetClientByIdAsync,
        Add: Application.AddClientAsync,
        Edit: Application.EditClientAsync,
        Delete: Application.DeleteClientAsync);
}

O mesmo controller, para os clientes: rota diferente, chaves de tradução diferentes, métodos diferentes de [ApplicationModel].

11.16.6. Controllers/RegistrationController.cs

// =========================================================================
// Controllers/RegistrationController.cs
// -------------------------------------------------------------------------
// "Create a patient account": um paciente que ainda não tem conta
// a cria por conta própria. Rotas NÃO protegidas (ainda não temos conta, por
// definição):
//
//   POST /register/access     botão "Create a patient account" da
//                             página de autenticação: verifica o captcha
//                             DESTA página e depois abre o formulário
//   GET  /register            o formulário
//   POST /register            a criação e depois volta à página de login
//
// O fluxo é protegido contra robôs por UM captcha, o da
// página de autenticação:
//   1. o botão "Create a patient account" envia o formulário de login
//      para /register/access; se o captcha for copiado corretamente, o servidor
//      emite um passe (veja Auth/RegistrationPassService.cs);
//   2. sem um passe válido, /register redireciona para a
//      página de autenticação: digitar a URL diretamente é inútil;
//   3. o passe é consumido na criação: um captcha resolvido
//      permite criar UMA conta;
//   4. além disso, o número de contas criadas por hora e por endereço IP é
//      limitado (veja Auth/AttemptLimiterService.cs).
//
// A conta criada é exatamente a que o ADMIN criaria pela
// página "Patients" (mesmo método da camada de negócio: AddClientAsync), exceto
// que o paciente ESCOLHE seu login e sua senha (obrigatórios,
// com confirmação).
// =========================================================================

using Microsoft.AspNetCore.Mvc;
using RdvMedecins.Auth;
using RdvMedecins.Business;
using RdvMedecins.Models;
using RdvMedecins.Web;

namespace RdvMedecins.Controllers;

[Route("register")]
public class RegistrationController(
    ApplicationModel application,
    CaptchaService captchaService,
    AttemptLimiterService limiter,
    RegistrationPassService passes) : Controller
{
    // -----------------------------------------------------------------------
    // POST /register/access   campos: captchaId, captcha (os da
    // página de autenticação; login e senha, também enviados, são ignorados)
    // -----------------------------------------------------------------------
    [HttpPost("access")]
    public IActionResult Access([FromForm] string? captchaId, [FromForm] string? captcha)
    {
        var ip = AuthController.IpAddress(HttpContext);

        // muitas contas criadas recentemente a partir deste endereço: não é preciso ir adiante
        var minutes = limiter.RegistrationBlockMinutes(ip);
        if (minutes > 0)
        {
            Flash.Put(HttpContext, FlashType.Danger, "ERRORS.TOO_MANY_ACCOUNTS", new() { ["minutes"] = minutes.ToString() });
            return Redirect("/login");
        }

        // captcha ausente ou errado: volta para a página de autenticação, com
        // uma nova imagem (uma falha conta como falha de login)
        if (!captchaService.Verify(captchaId, captcha))
        {
            limiter.LoginFailure(ip, "");
            Flash.Put(HttpContext, FlashType.Danger, "ERRORS.CAPTCHA_BEFORE_ACCOUNT");
            return Redirect("/login");
        }

        // captcha correto: emitimos o passe e abrimos o formulário
        Response.Cookies.Append(RegistrationPassService.Cookie, passes.Issue(), RegistrationPassService.GetCookieOptions());
        return Redirect("/register");
    }

    // -----------------------------------------------------------------------
    // GET /register
    // -----------------------------------------------------------------------
    [HttpGet("")]
    public IActionResult Form()
    {
        if (!HasPass())
        {
            return BackToLogin();
        }
        return Show(new PersonValues());
    }

    // -----------------------------------------------------------------------
    // POST /register
    // O parâmetro [form] é preenchido e VALIDADO pelo MVC antes da chamada:
    // o resultado da validação está em ModelState.
    // -----------------------------------------------------------------------
    [HttpPost("")]
    public async Task<IActionResult> Create(RegistrationForm form)
    {
        if (!HasPass())
        {
            return BackToLogin();
        }
        var ip = AuthController.IpAddress(HttpContext);
        var values = new PersonValues
        {
            Title = form.Title ?? "Mr",
            FirstName = form.FirstName ?? "",
            LastName = form.LastName ?? "",
            Login = form.Login ?? "",
        };

        // 1. muitas contas criadas recentemente a partir deste endereço?
        var minutes = limiter.RegistrationBlockMinutes(ip);
        if (minutes > 0)
        {
            return Show(values, null, "ERRORS.TOO_MANY_ACCOUNTS", null, new Dictionary<string, string> { ["minutes"] = minutes.ToString() });
        }

        // 2. todos os erros de entrada de uma vez (campos + confirmação):
        //    o usuário os corrige todos de uma só vez
        var errors = Validation.ErrorsOf(ModelState);
        if (!errors.ContainsKey("password") && !errors.ContainsKey("confirmation") && form.Password != form.Confirmation)
        {
            errors["confirmation"] = "ERRORS.PASSWORDS_DIFFER";
        }
        if (errors.Count > 0)
        {
            return Show(values, errors);
        }

        // 3. a criação (cliente + conta USER, em uma transação)
        try
        {
            // "!": afirmamos ao compilador que esses valores não são nulos,
            // o que é verdade, já que a validação ([Required]) foi bem-sucedida
            await application.AddClientAsync(new PersonData
            {
                Title = form.Title!,
                LastName = form.LastName!,
                FirstName = form.FirstName!,
                Login = form.Login,
                Password = form.Password,
            });
        }
        catch (BusinessException e)
        {
            // login ou nome + sobrenome já em uso: o passe continua válido
            return Show(values, null, e.Key, Validation.BusinessErrorFields.GetValueOrDefault(e.Key));
        }

        // 4. o passe foi usado: ele não permitirá criar uma 2ª conta
        passes.Consume(Request.Cookies[RegistrationPassService.Cookie]);
        Response.Cookies.Delete(RegistrationPassService.Cookie, new CookieOptions { Path = "/register" });
        limiter.RegistrationSuccess(ip);

        // 5. volta para a página de login, com o login preenchido
        Flash.Put(HttpContext, FlashType.Success, "REGISTRATION.DONE", new() { ["login"] = form.Login! });
        return Redirect($"/login?login={Uri.EscapeDataString(form.Login!)}");
    }

    // métodos privados

    private bool HasPass() => passes.IsValid(Request.Cookies[RegistrationPassService.Cookie]);

    // nenhum passe válido: volta para a página de autenticação
    private RedirectResult BackToLogin()
    {
        Flash.Put(HttpContext, FlashType.Danger, "ERRORS.CAPTCHA_BEFORE_ACCOUNT");
        return Redirect("/login");
    }

    // o formulário; nunca enviamos nenhuma senha de volta ao navegador
    private ViewResult Show(
        PersonValues values,
        Dictionary<string, string>? errors = null,
        string? error = null,
        IEnumerable<string>? otherFields = null,
        IReadOnlyDictionary<string, string>? errorParams = null) =>
        View("Registration", Validation.Prepare(
            new RegistrationModel { PageTitle = "REGISTRATION.TITLE", Values = values },
            errors, error, otherFields, errorParams));
}

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

// =========================================================================
// Controllers/PatientAreaController.cs
// -------------------------------------------------------------------------
// As páginas PESSOAIS do paciente (papel USER), as que ele vê logo
// após o login:
//
//   GET  /my-area                  página inicial: [Manage my account],
//                                  [View a schedule], e sua consulta futura
//   POST /my-area/cancel           cancela SUA consulta
//   GET  /my-account               formulário para editar sua conta
//   POST /my-account               atualização
//   POST /my-account/delete        exclusão da conta (e de suas consultas)
//
// Regra de ouro deste controller: o paciente envolvido é SEMPRE o do
// token (Patient.ConnectedPatientAsync), nunca um identificador enviado pelo
// navegador. Um paciente não pode, portanto, ver, modificar nem cancelar o que
// pertence a outro paciente, mesmo forjando ele próprio suas requisições.
//
// Qualquer modificação ou exclusão da conta exige a senha
// ATUAL: alguém que encontrasse uma sessão deixada aberta não poderia
// nem trocar a senha, nem excluir a conta. Os erros de senha
// atual são contados como falhas de login (mesmo limite).
// =========================================================================

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using RdvMedecins.Auth;
using RdvMedecins.Entities;
using RdvMedecins.Business;
using RdvMedecins.Models;
using RdvMedecins.Web;

namespace RdvMedecins.Controllers;

[Authorize(Roles = "USER")]
public class PatientAreaController(
    ApplicationModel application,
    AuthService authService,
    AttemptLimiterService limiter) : Controller
{
    // -----------------------------------------------------------------------
    // GET /my-area
    // -----------------------------------------------------------------------
    [HttpGet("my-area")]
    public async Task<IActionResult> Area()
    {
        var patient = await Patient.ConnectedPatientAsync(application, User);
        var appointments = await application.GetClientUpcomingAppointmentsAsync(patient.Id);
        return View("Area", new AreaModel
        {
            PageTitle = "AREA.TITLE",
            Patient = Labels.Label(patient),
            Appointments = appointments.Select(a => new AppointmentView(
                a.Id,
                WebDates.FormatDay(a.Day),
                WebDates.Time(a.Slot),
                Labels.Label(a.Slot.Doctor),
                // link para a agenda do médico nesse dia: o paciente vê seu nome ali
                $"/schedule?doctorId={a.Slot.Doctor.Id}&day={WebDates.Iso(a.Day)}")).ToList(),
        });
    }

    // -----------------------------------------------------------------------
    // POST /my-area/cancel   campo: appointmentId
    // -----------------------------------------------------------------------
    [HttpPost("my-area/cancel")]
    public async Task<IActionResult> CancelAppointment([FromForm] string? appointmentId)
    {
        var patient = await Patient.ConnectedPatientAsync(application, User);
        var appointment = Input.PositiveInteger(appointmentId) is int id ? await application.GetAppointmentByIdAsync(id) : null;
        // uma consulta que não existe e a de OUTRO paciente recebem
        // a mesma resposta: não revelamos nada sobre as consultas dos outros
        if (appointment is null || appointment.ClientId != patient.Id)
        {
            Flash.Put(HttpContext, FlashType.Danger, "ERRORS.APPOINTMENT_NOT_FOUND");
        }
        else
        {
            await application.DeleteAppointmentAsync(appointment);
            Flash.Put(HttpContext, FlashType.Success, "SCHEDULE.CANCELLED");
        }
        return Redirect("/my-area");
    }

    // -----------------------------------------------------------------------
    // GET /my-account
    // -----------------------------------------------------------------------
    [HttpGet("my-account")]
    public async Task<IActionResult> AccountForm()
    {
        var patient = await Patient.ConnectedPatientAsync(application, User);
        return Show(new PersonValues
        {
            Title = patient.Title,
            FirstName = patient.FirstName,
            LastName = patient.LastName,
            Login = patient.User.Login,
            Version = patient.Version,
        });
    }

    // -----------------------------------------------------------------------
    // POST /my-account
    // -----------------------------------------------------------------------
    [HttpPost("my-account")]
    public async Task<IActionResult> EditAccount(MyAccountForm form)
    {
        var patient = await Patient.ConnectedPatientAsync(application, User);
        var values = new PersonValues
        {
            Title = form.Title ?? patient.Title,
            FirstName = form.FirstName ?? "",
            LastName = form.LastName ?? "",
            Login = form.Login ?? "",
            Version = form.Version,
        };

        var errors = Validation.ErrorsOf(ModelState);
        if (!errors.ContainsKey("password") && form.Password is not null && form.Password != form.Confirmation)
        {
            errors["confirmation"] = "ERRORS.PASSWORDS_DIFFER";
        }
        if (errors.Count > 0)
        {
            return Show(values, errors);
        }

        // a senha atual
        var passwordError = await CheckCurrentPasswordAsync(patient, form.CurrentPassword);
        if (passwordError is not null)
        {
            var (key, messageParams) = passwordError.Value;
            return Show(
                values,
                key == "ERRORS.WRONG_CURRENT_PASSWORD" ? new(StringComparer.OrdinalIgnoreCase) { ["currentPassword"] = key } : null,
                key,
                null,
                messageParams);
        }

        try
        {
            var client = await application.EditClientAsync(patient.Id, new PersonData
            {
                Title = form.Title!,
                LastName = form.LastName!,
                FirstName = form.FirstName!,
                Login = form.Login,
                Password = form.Password, // null = inalterada
                Version = form.Version,
            });
            // o login e o nome exibido ESTÃO no token: emitimos um
            // novo, caso contrário a barra de navegação manteria o nome antigo
            authService.SetToken(Response, client.User);
            Flash.Put(HttpContext, FlashType.Success, "MY_ACCOUNT.UPDATED");
            return Redirect("/my-area");
        }
        catch (BusinessException e)
        {
            return Show(values, null, e.Key, Validation.BusinessErrorFields.GetValueOrDefault(e.Key));
        }
    }

    // -----------------------------------------------------------------------
    // POST /my-account/delete   campo: deletePassword
    // A conta, o cliente e TODAS as suas consultas desaparecem juntos,
    // depois o paciente é desconectado.
    // -----------------------------------------------------------------------
    [HttpPost("my-account/delete")]
    public async Task<IActionResult> DeleteAccount([FromForm] string? deletePassword)
    {
        var patient = await Patient.ConnectedPatientAsync(application, User);
        var passwordError = await CheckCurrentPasswordAsync(patient, deletePassword);
        if (passwordError is not null)
        {
            var (key, messageParams) = passwordError.Value;
            Flash.Put(HttpContext, FlashType.Danger, key, messageParams);
            return Redirect("/my-account");
        }
        await application.DeleteClientAsync(patient.Id);
        AuthService.ClearToken(Response);
        Flash.Put(HttpContext, FlashType.Success, "MY_ACCOUNT.DELETED");
        return Redirect("/login");
    }

    // métodos privados

    // null se a senha atual estiver correta; caso contrário, a chave da mensagem
    // (e seus parâmetros). O tipo de retorno é uma "tupla" anulável.
    private async Task<(string Key, Dictionary<string, string>? Params)?> CheckCurrentPasswordAsync(
        Client patient, string? password)
    {
        var ip = AuthController.IpAddress(HttpContext);
        var login = patient.User.Login;
        var minutes = limiter.LoginBlockMinutes(ip, login);
        if (minutes > 0)
        {
            return ("ERRORS.TOO_MANY_ATTEMPTS", new Dictionary<string, string> { ["minutes"] = minutes.ToString() });
        }
        var ok = !string.IsNullOrEmpty(password) && await authService.ValidateUserAsync(login, password) is not null;
        if (!ok)
        {
            limiter.LoginFailure(ip, login);
            return ("ERRORS.WRONG_CURRENT_PASSWORD", null);
        }
        return null;
    }

    private ViewResult Show(
        PersonValues values,
        Dictionary<string, string>? errors = null,
        string? error = null,
        IEnumerable<string>? otherFields = null,
        IReadOnlyDictionary<string, string>? errorParams = null) =>
        View("Account", Validation.Prepare(
            new MyAccountModel { PageTitle = "MY_ACCOUNT.TITLE", Values = values },
            errors, error, otherFields, errorParams));
}

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

// =========================================================================
// Controllers/ErrorController.cs
// -------------------------------------------------------------------------
// A página de erro (400, 403, 404, 500).
//
// Ela nunca é alcançada por um link: são os middlewares
// UseStatusCodePagesWithReExecute("/error/{0}") e
// UseExceptionHandler("/error/500") (veja Program.cs) que REEXECUTAM a
// requisição que falhou com este endereço, para construir a página a devolver
// no lugar de uma resposta vazia ou de uma exceção.
//
// [Route] sem [HttpGet]: a action aceita todos os métodos HTTP: a
// requisição reexecutada mantém seu método original (um POST recusado continua sendo POST).
// =========================================================================

using Microsoft.AspNetCore.Mvc;
using RdvMedecins.Models;

namespace RdvMedecins.Controllers;

public class ErrorController : Controller
{
    private static readonly Dictionary<int, string> Messages = new()
    {
        [StatusCodes.Status400BadRequest] = "ERRORS.BAD_REQUEST",
        [StatusCodes.Status403Forbidden] = "ERRORS.FORBIDDEN",
        [StatusCodes.Status404NotFound] = "ERRORS.NOT_FOUND",
    };

    [Route("error/{code:int}")]
    public IActionResult Show(int code)
    {
        // a página mantém o código de erro original (404 continua 404...); um
        // código inesperado vira um erro 500
        if (code < 400 || code > 599)
        {
            code = StatusCodes.Status500InternalServerError;
        }
        Response.StatusCode = code;
        return View("Error", new ErrorModel
        {
            PageTitle = "ERROR_PAGE.TITLE",
            Code = code,
            Message = Messages.GetValueOrDefault(code, "ERRORS.SERVER_ERROR"),
        });
    }
}

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

@* =========================================================================
   Views/_ViewImports.cshtml
   -------------------------------------------------------------------------
   Lido antes de CADA view desta pasta e de suas subpastas: os "using"s
   comuns e a classe mãe de todas as views (Web/ViewPage.cs), que
   lhes traz @T("KEY"), CurrentUser, FlashMessage...
   TModel designa o tipo do modelo de cada view (@model ...).
   ========================================================================= *@
@using RdvMedecins
@using RdvMedecins.Models
@using RdvMedecins.Web
@inherits RdvMedecins.Web.ViewPage<TModel>
  • 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

@* =========================================================================
   Views/_ViewStart.cshtml
   -------------------------------------------------------------------------
   Executado antes de cada view: todas as páginas usam o layout comum
   Views/Shared/_Layout.cshtml (o hbs fazia isso automaticamente para
   views/layout.hbs; aqui, dizemos isso explicitamente).
   ========================================================================= *@
@{
    Layout = "_Layout";
}
  • 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

@* =========================================================================
   Views/Shared/_Layout.cshtml
   -------------------------------------------------------------------------
   O layout COMUM a todas as páginas. A página solicitada pelo controller
   (Schedule.cshtml, Login.cshtml...) é inserida no local de
   @RenderBody().

   O Razor ESCAPA tudo o que exibe com @ (os caracteres < > & " '
   viram &lt; &gt;...): proteção contra injeção de HTML por meio de um
   nome digitado, por exemplo. Para inserir HTML como está, é preciso pedi-lo
   explicitamente (@Html.Raw, veja _Captcha.cshtml).

   Mensagens: um sucesso é exibido no TOPO da página (_Flash), um erro na
   PARTE INFERIOR, sobre um fundo rosa claro (_Errors).

   O layout compartilha o modelo da página: se for um ViewModel (veja
   Models/ViewModels.cs), lemos dele o título e o erro da página.
   ========================================================================= *@
@{
    var page = ViewData.Model as ViewModel;
}
<!doctype html>
<html lang="@Language">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>@T(page?.PageTitle ?? "APP.TITLE") - @T("APP.TITLE")</title>
  <link rel="stylesheet" href="/lib/bootstrap/css/bootstrap.min.css">
  <link rel="stylesheet" href="/css/styles.css">
</head>
<body>
  <div class="container py-4">
    @await Html.PartialAsync("_Navbar")
    @await Html.PartialAsync("_Flash")
    @RenderBody()
    @await Html.PartialAsync("_Errors")
  </div>
  @* o diálogo "Are you sure?", oculto enquanto não for necessário *@
  @await Html.PartialAsync("_Confirmation")
  <script src="/js/app.js"></script>
</body>
</html>
  • 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

@* =========================================================================
   Views/Shared/_Navbar.cshtml - a barra de navegação.

   Título, FR/EN, papel, nome, logout - e um menu cujas entradas
   dependem do papel: "Doctors" e "Patients" aparecem somente para
   o ADMIN. É apenas uma conveniência de exibição: a proteção real é
   o [Authorize(Roles = ...)] dos controllers (um USER que digita /doctors
   manualmente recebe uma página 403). Um paciente (USER) também tem o
   menu "My area".
   ========================================================================= *@
@{
    var user = CurrentUser;
}
<nav class="navbar navbar-expand-sm navbar-dark bg-primary rounded mb-4 px-3">
  <span class="navbar-brand mb-0">@T("APP.TITLE")</span>

  @if (user is not null)
  {
    <ul class="navbar-nav me-auto">
      @if (user.IsPatient)
      {
        <li class="nav-item"><a class="nav-link @Active("/my-")" href="/my-area">@T("APP.MENU_MY_AREA")</a></li>
      }
      <li class="nav-item"><a class="nav-link @Active("/schedule")" href="/schedule">@T("APP.MENU_SCHEDULE")</a></li>
      @if (user.IsAdmin)
      {
        <li class="nav-item"><a class="nav-link @Active("/doctors")" href="/doctors">@T("APP.MENU_DOCTORS")</a></li>
        <li class="nav-item"><a class="nav-link @Active("/clients")" href="/clients">@T("APP.MENU_PATIENTS")</a></li>
      }
    </ul>
  }
  else
  {
    <div class="me-auto"></div>
  }

  <div class="d-flex align-items-center gap-2">
    @* FR / EN: links simples (GET /language/fr), com o idioma ativo destacado *@
    <div class="btn-group btn-group-sm" role="group" aria-label="FR / EN">
      <a class="btn @(Language == "fr" ? "btn-light" : "btn-outline-light")" href="/language/fr">FR</a>
      <a class="btn @(Language == "en" ? "btn-light" : "btn-outline-light")" href="/language/en">EN</a>
    </div>

    @if (user is not null)
    {
      <span class="badge text-bg-light text-primary">@user.Role</span>
      <span class="text-white">@user.Name</span>
      @* logout é um POST: um formulário reduzido ao seu botão *@
      <form method="post" action="/logout" class="m-0">
        <button type="submit" class="btn btn-sm btn-outline-light">@T("APP.LOGOUT")</button>
      </form>
    }
  </div>
</nav>
  • 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

@* =========================================================================
   Views/Shared/_Flash.cshtml - a mensagem de SUCESSO colocada pela ação
   anterior (consulta salva, médico adicionado...), exibida uma única
   vez, no topo da página (veja Web/Flash.cs).
   Uma mensagem flash de ERRO, por sua vez, é exibida na parte inferior da página, por
   _Errors.cshtml.
   ========================================================================= *@
@{
    var flash = FlashMessage;
}
@if (flash is { Type: FlashType.Success })
{
  <div class="alert alert-success" role="status">
    @T(flash.Key, flash.Params)
  </div>
}
  • 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

@* =========================================================================
   Views/Shared/_Errors.cshtml - a zona de erros, na PARTE INFERIOR de cada página,
   sobre um fundo rosa claro (classe .error-zone, veja wwwroot/css/styles.css).

   Reúne as duas fontes possíveis de erro:
     - Error: o erro da página exibida (formulário recusado, login ou
       nome + sobrenome já utilizados, data inválida, senha incorreta...);
     - uma mensagem flash de erro, colocada pela ação anterior antes de um
       redirecionamento (horário já reservado, exclusão recusada...).

   role="alert": um leitor de tela anuncia a mensagem assim que a
   página é exibida, mesmo que ela esteja na parte inferior.
   ========================================================================= *@
@{
    var page = ViewData.Model as ViewModel;
    var error = page?.Error;
    var flash = FlashMessage;
    var flashError = flash is { Type: FlashType.Danger } ? flash : null;
}
@if (error is not null || flashError is not null)
{
  <div class="error-zone" role="alert">
    @if (error is not null)
    {
      <div>@T(error, page!.ErrorParams)</div>
    }
    @if (flashError is not null)
    {
      <div>@T(flashError.Key, flashError.Params)</div>
    }
  </div>
}
  • 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

@* =========================================================================
   Views/Shared/_Confirmation.cshtml - o diálogo modal "Are you sure?".

   Ele substitui a caixa window.confirm() do navegador, que não pode ser
   estilizada nem traduzida (seus botões permanecem no idioma do
   navegador, não no da página).

   UM ÚNICO diálogo para toda a página, oculto (d-none) inicialmente. Seus
   rótulos são traduzidos aqui, pelo servidor, como o resto da página;
   o pequeno script wwwroot/js/app.js apenas o exibe, insere nele
   a mensagem específica do formulário (atributo data-confirmation) e envia
   o formulário se o usuário confirmar.

   As mesmas classes Bootstrap do diálogo de reserva (Schedule/_Booking.cshtml).
   ========================================================================= *@
<div id="confirmation-modal" class="d-none">
  <div class="modal-backdrop fade show"></div>
  <div class="modal fade show d-block" tabindex="-1" role="alertdialog" aria-modal="true"
       aria-labelledby="confirmation-modal-title" aria-describedby="confirmation-modal-message">
    <div class="modal-dialog modal-dialog-centered">
      <div class="modal-content">
        <div class="modal-header">
          <h5 class="modal-title" id="confirmation-modal-title">@T("CONFIRMATION.TITLE")</h5>
          <button type="button" class="btn-close" data-action="no" aria-label="@T("BOOKING_DIALOG.CLOSE_ARIA")"></button>
        </div>
        <div class="modal-body">
          <p class="mb-0" id="confirmation-modal-message"></p>
        </div>
        <div class="modal-footer">
          @* "No, go back" em vez de "Cancel": a pergunta às vezes é
             "Cancel this appointment?", e um botão "Cancel" seria ambíguo nesse caso *@
          <button type="button" class="btn btn-secondary" data-action="no">@T("CONFIRMATION.NO")</button>
          <button type="button" class="btn btn-danger" data-action="yes">@T("CONFIRMATION.YES")</button>
        </div>
      </div>
    </div>
  </div>
</div>

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

@* =========================================================================
   Views/Auth/_Captcha.cshtml - o captcha da página de autenticação
   (veja Auth/CaptchaService.cs). Ele protege tanto o login quanto
   o acesso à criação de conta (botão "Create a patient account").

   @Html.Raw(...): a imagem SVG é inserida COMO ESTÁ na página, sem
   escape. Isso é inofensivo aqui porque este SVG é construído pelo
   próprio servidor e não contém nada que venha do usuário - NUNCA
   faríamos isso com uma entrada do usuário.

   O campo oculto captchaId diz ao servidor QUAL captcha verificar; a resposta
   certa, por sua vez, nunca é enviada ao navegador.
   "Another image" simplesmente recarrega a página (path = a URL atual).
   ========================================================================= *@
@model RdvMedecins.Auth.Captcha
<div class="mb-3">
  <label class="form-label" for="captcha">@T("CAPTCHA.LABEL")</label>
  <div class="d-flex align-items-center gap-3 mb-2">
    <div class="captcha-image" role="img" aria-label="@T("CAPTCHA.IMAGE_ALT")">@Html.Raw(Model.Svg)</div>
    <a class="small" href="@CurrentPath">@T("CAPTCHA.NEW_IMAGE")</a>
  </div>
  <input type="hidden" name="captchaId" value="@Model.Id">
  <input id="captcha" name="captcha" type="text" maxlength="10" autocomplete="off" autocapitalize="off" spellcheck="false" required
         class="form-control">
  <div class="form-text">@T("CAPTCHA.HELP")</div>
</div>
  • 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

@* =========================================================================
   Views/Shared/_PersonFields.cshtml - os campos de identidade (título,
   nome, sobrenome), comuns a três formulários: o formulário de médico/cliente
   do ADMIN, "Create a patient account" e "Manage my account".
   O partial recebe o modelo da página que o insere (um FormView):
   valores, mensagem sob cada campo, campos contornados em vermelho.

   selected="@selected": um atributo booleano. O Razor escreve selected="selected"
   se o valor for true, e OMITE o atributo se for false.
   ========================================================================= *@
@model FormView
<div class="mb-3">
  <label class="form-label" for="title">@T("PERSONS.TITLE_LABEL")</label>
  <select id="title" name="title" class="form-select @Model.InvalidClass("title")">
    @foreach (var (value, selected) in Model.Titles)
    {
      <option value="@value" selected="@selected">@value</option>
    }
  </select>
  @if (Model.ErrorOf("title") is { } titleError)
  {
    <div class="invalid-feedback">@T(titleError)</div>
  }
</div>

<div class="row g-3 mb-3">
  <div class="col-sm-6">
    <label class="form-label" for="firstName">@T("PERSONS.FIRSTNAME_LABEL")</label>
    <input id="firstName" name="firstName" type="text" maxlength="20" required
           class="form-control @Model.InvalidClass("firstName")" value="@Model.Values.FirstName">
    @if (Model.ErrorOf("firstName") is { } firstNameError)
    {
      <div class="invalid-feedback">@T(firstNameError)</div>
    }
  </div>
  <div class="col-sm-6">
    <label class="form-label" for="lastName">@T("PERSONS.LASTNAME_LABEL")</label>
    <input id="lastName" name="lastName" type="text" maxlength="20" required
           class="form-control @Model.InvalidClass("lastName")" value="@Model.Values.LastName">
    @if (Model.ErrorOf("lastName") is { } lastNameError)
    {
      <div class="invalid-feedback">@T(lastNameError)</div>
    }
  </div>
</div>

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

@* =========================================================================
   Views/Schedule/_Booking.cshtml - o diálogo de reserva.

   Mesma técnica do cliente Angular (booking-dialog): as classes Bootstrap
   REAIS de um diálogo modal (.modal, .modal-backdrop...), tornadas
   visíveis "fixas no código" (show d-block) em vez de pelo JavaScript do
   Bootstrap. A diferença: é o SERVIDOR que decide exibi-lo
   (parâmetro &book=... da URL), e fechá-lo equivale a seguir um link
   para a mesma página sem esse parâmetro.
   ========================================================================= *@
@model ScheduleModel
@{
    var booking = Model.Booking!;
}
<div class="modal-backdrop fade show"></div>
<div class="modal fade show d-block" tabindex="-1" role="dialog" aria-modal="true" aria-labelledby="booking-title">
  <div class="modal-dialog modal-dialog-centered">
    <form method="post" action="/schedule/book" class="modal-content">
      <div class="modal-header">
        <h5 class="modal-title" id="booking-title">@T("BOOKING_DIALOG.TITLE")</h5>
        <a class="btn-close" href="@Model.BackUrl" aria-label="@T("BOOKING_DIALOG.CLOSE_ARIA")"></a>
      </div>

      <div class="modal-body">
        <p>@T("BOOKING_DIALOG.SLOT", ("time", booking.Time))</p>

        @* o que o servidor precisa saber além do paciente escolhido *@
        <input type="hidden" name="doctorId" value="@Model.DoctorId">
        <input type="hidden" name="day" value="@Model.Day">
        <input type="hidden" name="slotId" value="@booking.SlotId">

        @if (booking.Patient is not null)
        {
          @* um paciente reserva para si mesmo: sem lista para escolher
             (e o servidor ignora qualquer clientId de qualquer maneira) *@
          <p class="mb-0">@T("BOOKING_DIALOG.PATIENT_LABEL"): <strong>@booking.Patient</strong></p>
        }
        else
        {
          <label class="form-label" for="clientId">@T("BOOKING_DIALOG.PATIENT_LABEL")</label>
          <select id="clientId" name="clientId" class="form-select" required autofocus>
            <option value="">@T("BOOKING_DIALOG.CHOOSE_PATIENT")</option>
            @foreach (var client in booking.Clients)
            {
              <option value="@client.Id">@client.Label</option>
            }
          </select>
        }
      </div>

      <div class="modal-footer">
        <a class="btn btn-secondary" href="@Model.BackUrl">@T("BOOKING_DIALOG.CANCEL")</a>
        <button type="submit" class="btn btn-primary">@T("BOOKING_DIALOG.CONFIRM")</button>
      </div>
    </form>
  </div>
</div>
  • 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

@* =========================================================================
   Views/Auth/Login.cshtml - o formulário de login.
   Um <form> HTML comum: o próprio navegador envia login,
   senha e resposta do captcha com POST /login, sem JavaScript. Em
   caso de falha, o servidor devolve ESTA página, com o login já digitado, um
   NOVO captcha e o erro, exibido na parte inferior da página pelo layout.

   @model: o tipo do view model. O compilador verifica cada
   @Model.Xxx (um erro de digitação é um erro de compilação).
   ========================================================================= *@
@model LoginModel
@{
    var loginTyped = Model.Login != "";
}
<div class="row justify-content-center">
  <div class="col-sm-8 col-md-6 col-lg-5">
    <div class="card p-4">
      <h5 class="card-title mb-3">@T("LOGIN.TITLE")</h5>

      <form method="post" action="/login">
        <div class="mb-3">
          <label class="form-label" for="login">@T("LOGIN.LOGIN_LABEL")</label>
          <input id="login" name="login" type="text" class="form-control" autocomplete="username"
                 value="@Model.Login" required autofocus="@(!loginTyped)">
        </div>
        <div class="mb-3">
          <label class="form-label" for="password">@T("LOGIN.PASSWORD_LABEL")</label>
          <input id="password" name="password" type="password" class="form-control"
                 autocomplete="current-password" required autofocus="@loginTyped">
        </div>

        @await Html.PartialAsync("_Captcha", Model.Captcha)

        <button type="submit" class="btn btn-primary w-100">@T("LOGIN.SUBMIT")</button>

        @* ainda sem conta: um paciente pode criar uma sozinho.
           NÃO é um simples link: é um segundo botão submit
           DESTE formulário, que vai para outro endereço (formaction). O
           servidor verifica ali o captcha acima antes de abrir a página de
           criação de conta (veja RegistrationController).
           formnovalidate: o navegador não exige login e senha
           (inútil para criar uma conta); é o servidor que verifica
           o captcha. Enter em um campo sempre aciona o PRIMEIRO
           botão do formulário, "Log in". *@
        <button type="submit" class="btn btn-outline-primary w-100 mt-3"
                formaction="/register/access" formnovalidate>@T("LOGIN.CREATE_ACCOUNT")</button>
        <div class="form-text text-center">@T("LOGIN.CREATE_ACCOUNT_HELP")</div>
      </form>

      <div class="text-muted small mt-3">
        @T("LOGIN.DEMO_ACCOUNTS")
        <ul class="mb-0 mt-1">
          <li><code>admin</code> - @T("LOGIN.DEMO_ADMIN")</li>
          <li><code>pelissier</code>, <code>tatou</code>, <code>dupont</code> - @T("LOGIN.DEMO_DOCTOR")</li>
          <li><code>martin</code>, <code>durand</code>, <code>bistrou</code>, <code>german</code> - @T("LOGIN.DEMO_USER")</li>
        </ul>
      </div>
    </div>
  </div>
</div>
  • 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

@* =========================================================================
   Views/Schedule/Schedule.cshtml - a página principal (veja ScheduleController).
   Três blocos, como os três componentes do cliente Angular:
     1. a escolha do médico e do dia  (<app-doctor-day-picker>)
     2. a agenda                      (<app-agenda>)
     3. o diálogo de reserva          (<app-booking-dialog>)
   Um possível erro (data inválida, médico desconhecido) é exibido na
   parte inferior da página pelo layout (veja Views/Shared/_Errors.cshtml).
   ========================================================================= *@
@model ScheduleModel

@* 1. escolha do médico e do dia: um formulário GET, que simplesmente
   recarrega esta página com ?doctorId=...&day=... na URL *@
<form method="get" action="/schedule" class="card p-3 mb-3">
  <div class="row g-2 align-items-end">
    <div class="col-sm-5">
      <label class="form-label" for="doctorId">@T("DOCTOR_DAY_PICKER.DOCTOR_LABEL")</label>
      <select id="doctorId" name="doctorId" class="form-select" required>
        <option value="">@T("DOCTOR_DAY_PICKER.CHOOSE_DOCTOR")</option>
        @foreach (var doctor in Model.Doctors)
        {
          <option value="@doctor.Id" selected="@doctor.Selected">@doctor.Label</option>
        }
      </select>
    </div>
    <div class="col-sm-4">
      <label class="form-label" for="day">@T("DOCTOR_DAY_PICKER.DAY_LABEL")</label>
      <input id="day" name="day" type="date" class="form-control" value="@Model.Day" required>
    </div>
    <div class="col-sm-3">
      <button type="submit" class="btn btn-primary w-100">@T("DOCTOR_DAY_PICKER.VIEW_SCHEDULE")</button>
    </div>
  </div>
</form>

@* paciente que já tem uma consulta futura: por isso não há botão "Book" *@
@if (Model.Info is not null)
{
  <div class="alert alert-info">
    @T(Model.Info) <a href="/my-area" class="alert-link">@T("APP.MENU_MY_AREA")</a>
  </div>
}

@* 2. a agenda *@
@if (Model.Schedule is { } schedule)
{
  <div class="card p-3">
    <h5>@T("SCHEDULE.TITLE_PREFIX") @schedule.Day - @schedule.Doctor</h5>

    @if (schedule.Rows.Count > 0)
    {
      <table class="table table-hover align-middle">
        <thead>
          <tr>
            <th>@T("SCHEDULE.COLUMN_SLOT")</th>
            <th>@T("SCHEDULE.COLUMN_STATUS")</th>
            <th></th>
          </tr>
        </thead>
        <tbody>
          @foreach (var row in schedule.Rows)
          {
            <tr class="@(row.Bookable ? "free-slot" : null)">
              <td>@row.Time</td>
              <td>
                @* [Patient] só é preenchido se o usuário tiver permissão para
                   ver este nome (ADMIN, DOCTOR, ou o paciente para a SUA
                   consulta) - caso contrário, simplesmente "Booked" *@
                @if (row.Free)
                {
                  <span class="badge text-bg-success">@T("SCHEDULE.FREE")</span>
                }
                else if (row.Patient is not null)
                {
                  <span class="badge @(row.Mine ? "text-bg-primary" : "text-bg-secondary")">@row.Patient</span>
                }
                else
                {
                  <span class="badge text-bg-secondary">@T("SCHEDULE.BOOKED_BY_OTHER")</span>
                }
              </td>
              <td>
                @* os botões exibidos foram decididos pelo controller
                   (Bookable, AppointmentId) de acordo com o papel do usuário *@
                @if (row.Bookable)
                {
                  @* "Book" é um simples link: ele reabre esta página
                     com o diálogo de reserva deste horário *@
                  <a class="btn btn-sm btn-outline-success" href="@row.BookUrl">@T("SCHEDULE.BOOK")</a>
                }
                @if (row.AppointmentId is not null)
                {
                  @* "Cancel" MODIFICA dados: portanto é um POST *@
                  <form method="post" action="/schedule/cancel" class="m-0"
                        data-confirmation="@T("SCHEDULE.CANCEL_CONFIRM")">
                    <input type="hidden" name="appointmentId" value="@row.AppointmentId">
                    <input type="hidden" name="doctorId" value="@Model.DoctorId">
                    <input type="hidden" name="day" value="@Model.Day">
                    <button type="submit" class="btn btn-sm btn-outline-danger">@T("SCHEDULE.CANCEL_APPOINTMENT")</button>
                  </form>
                }
              </td>
            </tr>
          }
        </tbody>
      </table>
    }
    else
    {
      <p class="text-muted mb-0">@T("SCHEDULE.NO_SLOTS")</p>
    }
  </div>
}
else
{
  <p class="text-muted">@T("SCHEDULE.EMPTY_STATE")</p>
}

@* 3. o diálogo de reserva, somente se a URL contiver &book=... *@
@if (Model.Booking is not null)
{
  @await Html.PartialAsync("_Booking", Model)
}

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

@* =========================================================================
   Views/Persons/List.cshtml - a lista dos médicos OU dos clientes (ADMIN).
   Uma única view para ambos: os rótulos específicos de cada um chegam em
   Model.Keys (veja DoctorsController / ClientsController).
   ========================================================================= *@
@model PersonListModel
<div class="d-flex justify-content-between align-items-center mb-3">
  <h4 class="mb-0">@T(Model.Keys.Title)</h4>
  <a class="btn btn-primary" href="@Model.AddUrl">@T(Model.Keys.Add)</a>
</div>

<div class="card p-3">
  @if (Model.Persons.Count > 0)
  {
    <table class="table table-hover align-middle mb-0">
      <thead>
        <tr>
          <th>@T("PERSONS.COLUMN_TITLE")</th>
          <th>@T("PERSONS.COLUMN_FIRSTNAME")</th>
          <th>@T("PERSONS.COLUMN_LASTNAME")</th>
          <th>@T("PERSONS.COLUMN_LOGIN")</th>
          <th></th>
        </tr>
      </thead>
      <tbody>
        @foreach (var person in Model.Persons)
        {
          <tr>
            <td>@person.Title</td>
            <td>@person.FirstName</td>
            <td>@person.LastName</td>
            <td><code>@person.Login</code></td>
            <td class="text-end">
              <div class="d-inline-flex gap-2">
                <a class="btn btn-sm btn-outline-primary" href="@person.EditUrl">@T("PERSONS.EDIT")</a>
                @* data-confirmation: um diálogo de confirmação será aberto
                   antes do envio do formulário (veja wwwroot/js/app.js) *@
                <form method="post" action="@person.DeleteUrl" class="m-0"
                      data-confirmation="@T(Model.Keys.ConfirmDelete)">
                  <button type="submit" class="btn btn-sm btn-outline-danger">@T("PERSONS.DELETE")</button>
                </form>
              </div>
            </td>
          </tr>
        }
      </tbody>
    </table>
  }
  else
  {
    <p class="text-muted mb-0">@T(Model.Keys.Empty)</p>
  }
</div>

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

@* =========================================================================
   Views/Persons/Form.cshtml - criação OU atualização de um médico
   ou de um cliente (ADMIN). Model.Creating distingue os dois casos.

   Quando a entrada é recusada (campo vazio, login já utilizado...), o
   controller devolve ESTA view com:
     - os valores já digitados (Model.Values);
     - os campos com problema contornados em vermelho (classe Bootstrap "is-invalid");
     - sob um campo recusado pela validação, sua mensagem;
     - a mensagem de erro da página, exibida NA PARTE INFERIOR da página pelo
       layout (veja Views/Shared/_Errors.cshtml).
   ========================================================================= *@
@model PersonFormModel
<div class="row justify-content-center">
  <div class="col-md-8 col-lg-6">
    <div class="card p-4">
      <h5 class="card-title mb-3">@T(Model.PageTitle)</h5>

      @* novalidate: deixamos o SERVIDOR validar (é ele quem tem a autoridade);
         as verificações do navegador (required...) são apenas uma conveniência,
         que um usuário sempre pode contornar *@
      <form method="post" action="@Model.Action" novalidate>
        @if (!Model.Creating)
        {
          <input type="hidden" name="version" value="@Model.Values.Version">
        }

        @* título, nome, sobrenome: partial comum a três formulários *@
        @await Html.PartialAsync("_PersonFields", Model)

        <h6 class="mt-4 text-muted">@T("PERSONS.ACCOUNT_SECTION")</h6>

        <div class="mb-3">
          <label class="form-label" for="login">@T("PERSONS.LOGIN_LABEL")</label>
          <input id="login" name="login" type="text" maxlength="30" autocomplete="off"
                 class="form-control @Model.InvalidClass("login")" value="@Model.Values.Login">
          @if (Model.ErrorOf("login") is { } loginError)
          {
            <div class="invalid-feedback">@T(loginError)</div>
          }
          else
          {
            <div class="form-text">@T(Model.Creating ? "PERSONS.LOGIN_HELP_CREATE" : "PERSONS.LOGIN_HELP_EDIT")</div>
          }
        </div>

        <div class="mb-4">
          <label class="form-label" for="password">@T("PERSONS.PASSWORD_LABEL")</label>
          @* nunca preenchido previamente: a senha nunca volta para o navegador *@
          <input id="password" name="password" type="password" maxlength="72" autocomplete="new-password"
                 class="form-control @Model.InvalidClass("password")">
          @if (Model.ErrorOf("password") is { } passwordError)
          {
            <div class="invalid-feedback">@T(passwordError)</div>
          }
          else
          {
            <div class="form-text">@T(Model.Creating ? "PERSONS.PASSWORD_HELP_CREATE" : "PERSONS.PASSWORD_HELP_EDIT")</div>
          }
        </div>

        <div class="d-flex gap-2">
          <button type="submit" class="btn btn-primary">@T("PERSONS.SAVE")</button>
          <a class="btn btn-secondary" href="@Model.ListUrl">@T("PERSONS.BACK")</a>
        </div>
      </form>
    </div>
  </div>
</div>

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

@* =========================================================================
   Views/Registration/Registration.cshtml - "Create a patient account" (página
   pública, veja RegistrationController). Os mesmos campos de identidade que o
   formulário do ADMIN (partial _PersonFields), mas o login e a
   senha são obrigatórios, com confirmação.
   Sem captcha AQUI: esta página só é alcançada depois de copiar
   o da página de autenticação (botão "Create a patient account").
   ========================================================================= *@
@model RegistrationModel
<div class="row justify-content-center">
  <div class="col-md-8 col-lg-6">
    <div class="card p-4">
      <h5 class="card-title mb-1">@T("REGISTRATION.TITLE")</h5>
      <p class="text-muted small mb-3">@T("REGISTRATION.INTRO")</p>

      <form method="post" action="/register" novalidate>
        @await Html.PartialAsync("_PersonFields", Model)

        <h6 class="mt-4 text-muted">@T("PERSONS.ACCOUNT_SECTION")</h6>

        <div class="mb-3">
          <label class="form-label" for="login">@T("PERSONS.LOGIN_LABEL")</label>
          <input id="login" name="login" type="text" maxlength="30" autocomplete="username" required
                 class="form-control @Model.InvalidClass("login")" value="@Model.Values.Login">
          @if (Model.ErrorOf("login") is { } loginError)
          {
            <div class="invalid-feedback">@T(loginError)</div>
          }
          else
          {
            <div class="form-text">@T("REGISTRATION.LOGIN_HELP")</div>
          }
        </div>

        <div class="row g-3 mb-3">
          <div class="col-sm-6">
            <label class="form-label" for="password">@T("PERSONS.PASSWORD_LABEL")</label>
            <input id="password" name="password" type="password" maxlength="72" autocomplete="new-password" required
                   class="form-control @Model.InvalidClass("password")">
            @if (Model.ErrorOf("password") is { } passwordError)
            {
              <div class="invalid-feedback">@T(passwordError, ("min", Model.PasswordMin))</div>
            }
            else
            {
              <div class="form-text">@T("REGISTRATION.PASSWORD_HELP", ("min", Model.PasswordMin))</div>
            }
          </div>
          <div class="col-sm-6">
            <label class="form-label" for="confirmation">@T("ACCOUNT.CONFIRMATION_LABEL")</label>
            <input id="confirmation" name="confirmation" type="password" maxlength="72" autocomplete="new-password" required
                   class="form-control @Model.InvalidClass("confirmation")">
            @if (Model.ErrorOf("confirmation") is { } confirmationError)
            {
              <div class="invalid-feedback">@T(confirmationError)</div>
            }
          </div>
        </div>

        <div class="d-flex gap-2">
          <button type="submit" class="btn btn-primary">@T("REGISTRATION.SUBMIT")</button>
          <a class="btn btn-secondary" href="/login">@T("REGISTRATION.BACK_TO_LOGIN")</a>
        </div>
      </form>
    </div>
  </div>
</div>

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

@* =========================================================================
   Views/PatientArea/Area.cshtml - "My area": a página inicial do
   paciente (papel USER), exibida logo após o login.
     - duas opções: [Manage my account] e [View a schedule];
     - sua próxima consulta, se houver, com o meio de cancelá-la.
   ========================================================================= *@
@model AreaModel
<h4 class="mb-3">@T("AREA.HELLO", ("name", Model.Patient))</h4>

<div class="row g-3 mb-4">
  <div class="col-sm-6">
    <a class="card p-4 h-100 text-decoration-none option-card" href="/my-account">
      <h5 class="mb-1">@T("AREA.MANAGE_ACCOUNT")</h5>
      <span class="text-muted">@T("AREA.MANAGE_ACCOUNT_HELP")</span>
    </a>
  </div>
  <div class="col-sm-6">
    <a class="card p-4 h-100 text-decoration-none option-card" href="/schedule">
      <h5 class="mb-1">@T("AREA.VIEW_SCHEDULE")</h5>
      <span class="text-muted">@T("AREA.VIEW_SCHEDULE_HELP")</span>
    </a>
  </div>
</div>

<div class="card p-3">
  <h5>@T("AREA.MY_APPOINTMENT")</h5>
  @if (Model.Appointments.Count > 0)
  {
    @* normalmente apenas uma (regra "uma consulta futura por vez"),
       mas a página pode exibir várias *@
    for (var i = 0; i < Model.Appointments.Count; i++)
    {
      var appointment = Model.Appointments[i];
      var last = i == Model.Appointments.Count - 1;
      <div class="d-flex flex-wrap justify-content-between align-items-center gap-2 py-2 @(last ? "" : "border-bottom")">
        <div>
          <div class="fw-semibold">@appointment.Day, @appointment.Time</div>
          <div class="text-muted">@appointment.Doctor - <a href="@appointment.ScheduleUrl">@T("AREA.SEE_IN_SCHEDULE")</a></div>
        </div>
        <form method="post" action="/my-area/cancel" class="m-0"
              data-confirmation="@T("SCHEDULE.CANCEL_CONFIRM")">
          <input type="hidden" name="appointmentId" value="@appointment.Id">
          <button type="submit" class="btn btn-outline-danger">@T("AREA.CANCEL_APPOINTMENT")</button>
        </form>
      </div>
    }
  }
  else
  {
    <p class="text-muted mb-0">@T("AREA.NO_APPOINTMENT")</p>
  }
</div>
  • 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

@* =========================================================================
   Views/PatientArea/Account.cshtml - "Manage my account" (papel USER).
   Dois formulários independentes na mesma página:
     1. a atualização (identidade, login, nova senha opcional);
     2. a exclusão da conta - que também cancela suas consultas.
   Ambos exigem a senha ATUAL.
   ========================================================================= *@
@model MyAccountModel
<div class="row justify-content-center">
  <div class="col-md-8 col-lg-6">

    @* 1. atualização *@
    <div class="card p-4 mb-4">
      <h5 class="card-title mb-3">@T("MY_ACCOUNT.TITLE")</h5>

      <form method="post" action="/my-account" novalidate>
        <input type="hidden" name="version" value="@Model.Values.Version">

        @await Html.PartialAsync("_PersonFields", Model)

        <h6 class="mt-4 text-muted">@T("PERSONS.ACCOUNT_SECTION")</h6>

        <div class="mb-3">
          <label class="form-label" for="login">@T("PERSONS.LOGIN_LABEL")</label>
          <input id="login" name="login" type="text" maxlength="30" autocomplete="username" required
                 class="form-control @Model.InvalidClass("login")" value="@Model.Values.Login">
          @if (Model.ErrorOf("login") is { } loginError)
          {
            <div class="invalid-feedback">@T(loginError)</div>
          }
        </div>

        <div class="row g-3 mb-3">
          <div class="col-sm-6">
            <label class="form-label" for="password">@T("MY_ACCOUNT.NEW_PASSWORD_LABEL")</label>
            <input id="password" name="password" type="password" maxlength="72" autocomplete="new-password"
                   class="form-control @Model.InvalidClass("password")">
            @if (Model.ErrorOf("password") is { } passwordError)
            {
              <div class="invalid-feedback">@T(passwordError, ("min", Model.PasswordMin))</div>
            }
            else
            {
              <div class="form-text">@T("PERSONS.PASSWORD_HELP_EDIT")</div>
            }
          </div>
          <div class="col-sm-6">
            <label class="form-label" for="confirmation">@T("ACCOUNT.CONFIRMATION_LABEL")</label>
            <input id="confirmation" name="confirmation" type="password" maxlength="72" autocomplete="new-password"
                   class="form-control @Model.InvalidClass("confirmation")">
            @if (Model.ErrorOf("confirmation") is { } confirmationError)
            {
              <div class="invalid-feedback">@T(confirmationError)</div>
            }
          </div>
        </div>

        <div class="mb-4">
          <label class="form-label" for="currentPassword">@T("MY_ACCOUNT.CURRENT_PASSWORD_LABEL")</label>
          <input id="currentPassword" name="currentPassword" type="password" maxlength="72" autocomplete="current-password" required
                 class="form-control @Model.InvalidClass("currentPassword")">
          @if (Model.ErrorOf("currentPassword") is { } currentError)
          {
            <div class="invalid-feedback">@T(currentError)</div>
          }
          else
          {
            <div class="form-text">@T("MY_ACCOUNT.CURRENT_PASSWORD_HELP")</div>
          }
        </div>

        <div class="d-flex gap-2">
          <button type="submit" class="btn btn-primary">@T("PERSONS.SAVE")</button>
          <a class="btn btn-secondary" href="/my-area">@T("MY_ACCOUNT.BACK")</a>
        </div>
      </form>
    </div>

    @* 2. exclusão *@
    <div class="card p-4 border-danger">
      <h5 class="card-title text-danger mb-1">@T("MY_ACCOUNT.DELETE_TITLE")</h5>
      <p class="text-muted small">@T("MY_ACCOUNT.DELETE_HELP")</p>
      <form method="post" action="/my-account/delete" class="d-flex flex-wrap gap-2 align-items-end"
            data-confirmation="@T("MY_ACCOUNT.DELETE_CONFIRM")">
        <div class="flex-grow-1">
          <label class="form-label" for="deletePassword">@T("MY_ACCOUNT.CURRENT_PASSWORD_LABEL")</label>
          <input id="deletePassword" name="deletePassword" type="password" maxlength="72"
                 autocomplete="current-password" required class="form-control">
        </div>
        <button type="submit" class="btn btn-danger">@T("MY_ACCOUNT.DELETE_SUBMIT")</button>
      </form>
    </div>

  </div>
</div>
  • 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

@* =========================================================================
   Views/Shared/Error.cshtml - a página de erro (400, 403, 404, 500),
   construída por ErrorController.
   ========================================================================= *@
@model ErrorModel
<div class="row justify-content-center">
  <div class="col-md-8 col-lg-6">
    <div class="card p-4 text-center">
      <h1 class="display-4 text-danger">@Model.Code</h1>
      <p class="lead">@T(Model.Message)</p>
      <div><a class="btn btn-primary" href="/">@T("ERROR_PAGE.BACK")</a></div>
    </div>
  </div>
</div>
  • 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

{
  "APP": {
    "TITLE": "RdvMedecins",
    "LOGOUT": "Se déconnecter",
    "MENU_SCHEDULE": "Agenda",
    "MENU_DOCTORS": "Médecins",
    "MENU_PATIENTS": "Clients",
    "MENU_MY_AREA": "Mon espace"
  },
  "LOGIN": {
    "TITLE": "Connexion",
    "LOGIN_LABEL": "Login",
    "PASSWORD_LABEL": "Mot de passe",
    "SUBMIT": "Se connecter",
    "ERROR": "Login ou mot de passe incorrect.",
    "DEMO_ACCOUNTS": "Comptes de démonstration (mot de passe = login) :",
    "DEMO_ADMIN": "rôle ADMIN : rendez-vous + gestion des médecins et des clients",
    "DEMO_DOCTOR": "rôle DOCTOR : prise et annulation de rendez-vous",
    "DEMO_USER": "rôle USER (patients) : réservation pour eux-mêmes, gestion de leur compte",
    "CREATE_ACCOUNT": "Créer un compte client",
    "CREATE_ACCOUNT_HELP": "Pour créer un compte, recopiez d'abord les caractères de l'image."
  },
  "DOCTOR_DAY_PICKER": {
    "DOCTOR_LABEL": "Médecin",
    "CHOOSE_DOCTOR": "-- choisir un médecin --",
    "DAY_LABEL": "Jour",
    "VIEW_SCHEDULE": "Voir l'agenda"
  },
  "SCHEDULE": {
    "PAGE_TITLE": "Agenda",
    "TITLE_PREFIX": "Agenda du",
    "COLUMN_SLOT": "Créneau",
    "COLUMN_STATUS": "Statut",
    "FREE": "Libre",
    "BOOK": "Réserver",
    "CANCEL_APPOINTMENT": "Annuler",
    "CANCEL_CONFIRM": "Annuler ce rendez-vous ?",
    "EMPTY_STATE": "Choisissez un médecin et un jour, puis cliquez sur « Voir l'agenda ».",
    "NO_SLOTS": "Ce médecin n'a aucun créneau horaire.",
    "BOOKED": "Rendez-vous enregistré.",
    "CANCELLED": "Rendez-vous annulé.",
    "BOOKED_BY_OTHER": "Réservé",
    "ALREADY_BOOKED_INFO": "Vous avez déjà un rendez-vous à venir : annulez-le pour en prendre un autre."
  },
  "BOOKING_DIALOG": {
    "TITLE": "Réserver ce créneau",
    "CLOSE_ARIA": "Fermer",
    "SLOT": "Créneau de {time}",
    "PATIENT_LABEL": "Patient",
    "CHOOSE_PATIENT": "-- choisir un patient --",
    "CANCEL": "Annuler",
    "CONFIRM": "Confirmer"
  },
  "PERSONS": {
    "COLUMN_TITLE": "Titre",
    "COLUMN_FIRSTNAME": "Prénom",
    "COLUMN_LASTNAME": "Nom",
    "COLUMN_LOGIN": "Login",
    "EDIT": "Modifier",
    "DELETE": "Supprimer",
    "SAVE": "Enregistrer",
    "BACK": "Retour à la liste",
    "TITLE_LABEL": "Titre",
    "FIRSTNAME_LABEL": "Prénom",
    "LASTNAME_LABEL": "Nom",
    "LOGIN_LABEL": "Login",
    "PASSWORD_LABEL": "Mot de passe",
    "LOGIN_HELP_CREATE": "Facultatif : par défaut, le nom en minuscules.",
    "LOGIN_HELP_EDIT": "Laisser vide pour ne pas le changer.",
    "PASSWORD_HELP_CREATE": "Facultatif : par défaut, identique au login.",
    "PASSWORD_HELP_EDIT": "Laisser vide pour ne pas le changer.",
    "ACCOUNT_SECTION": "Compte utilisateur"
  },
  "DOCTORS": {
    "TITLE": "Médecins",
    "ADD": "Ajouter un médecin",
    "EDIT": "Modifier un médecin",
    "EMPTY": "Aucun médecin.",
    "DELETE_CONFIRM": "Supprimer ce médecin, ses créneaux horaires et son compte utilisateur ?",
    "ADDED": "Le médecin {name} a été ajouté (login : {login}).",
    "UPDATED": "Le médecin {name} a été modifié.",
    "DELETED": "Le médecin {name} a été supprimé."
  },
  "CLIENTS": {
    "TITLE": "Clients",
    "ADD": "Ajouter un client",
    "EDIT": "Modifier un client",
    "EMPTY": "Aucun client.",
    "DELETE_CONFIRM": "Supprimer ce client, son compte utilisateur et tous ses rendez-vous ?",
    "ADDED": "Le client {name} a été ajouté (login : {login}).",
    "UPDATED": "Le client {name} a été modifié.",
    "DELETED": "Le client {name} a été supprimé."
  },
  "ERROR_PAGE": {
    "TITLE": "Erreur",
    "BACK": "Retour à l'accueil"
  },
  "ERRORS": {
    "LOGIN_TAKEN": "Ce login est déjà utilisé par un autre compte.",
    "DOCTOR_ALREADY_EXISTS": "Un médecin portant ce prénom et ce nom existe déjà.",
    "PATIENT_ALREADY_EXISTS": "Un client portant ce prénom et ce nom existe déjà.",
    "DOCTOR_HAS_APPOINTMENTS": "Ce médecin a des rendez-vous : annulez-les avant de le supprimer.",
    "SLOT_ALREADY_BOOKED": "Ce créneau vient d'être réservé par quelqu'un d'autre.",
    "CONCURRENT_UPDATE": "Cette fiche a été modifiée entre-temps par un autre utilisateur. Revenez à la liste et rouvrez-la avant de recommencer.",
    "DOCTOR_NOT_FOUND": "Ce médecin n'existe pas (ou plus).",
    "PATIENT_NOT_FOUND": "Ce client n'existe pas (ou plus).",
    "SLOT_NOT_FOUND": "Ce créneau n'existe pas (ou plus).",
    "APPOINTMENT_NOT_FOUND": "Ce rendez-vous n'existe pas (ou plus).",
    "INVALID_DATE": "La date demandée n'est pas valide.",
    "CHOOSE_PATIENT": "Choisissez un patient.",
    "INVALID_FORM": "Le formulaire contient des erreurs.",
    "INVALID_TITLE": "Choisissez un titre dans la liste.",
    "FIRSTNAME_REQUIRED": "Le prénom est obligatoire.",
    "FIRSTNAME_TOO_LONG": "Le prénom ne doit pas dépasser 20 caractères.",
    "LASTNAME_REQUIRED": "Le nom est obligatoire.",
    "LASTNAME_TOO_LONG": "Le nom ne doit pas dépasser 20 caractères.",
    "INVALID_LOGIN": "30 caractères au plus : lettres minuscules non accentuées, chiffres, point, tiret, souligné.",
    "PASSWORD_TOO_LONG": "Le mot de passe ne doit pas dépasser 72 caractères.",
    "SESSION_EXPIRED": "Votre session a expiré : reconnectez-vous.",
    "BAD_REQUEST": "La requête est invalide.",
    "FORBIDDEN": "Votre rôle ne vous permet pas d'accéder à cette page.",
    "NOT_FOUND": "Cette page n'existe pas.",
    "SERVER_ERROR": "Une erreur inattendue s'est produite. Réessayez plus tard.",
    "TOO_MANY_ATTEMPTS": "Trop de tentatives infructueuses. Réessayez dans {minutes} minute(s).",
    "WRONG_CAPTCHA": "Les caractères recopiés ne correspondent pas à l'image. Une nouvelle image vous est proposée.",
    "TOO_MANY_ACCOUNTS": "Trop de comptes ont été créés depuis votre connexion. Réessayez dans {minutes} minute(s).",
    "LOGIN_REQUIRED": "Le login est obligatoire.",
    "PASSWORD_REQUIRED": "Le mot de passe est obligatoire.",
    "PASSWORD_TOO_SHORT": "Le mot de passe doit comporter au moins {min} caractères.",
    "CONFIRMATION_REQUIRED": "Confirmez le mot de passe.",
    "PASSWORDS_DIFFER": "La confirmation ne correspond pas au mot de passe.",
    "CURRENT_PASSWORD_REQUIRED": "Saisissez votre mot de passe actuel.",
    "WRONG_CURRENT_PASSWORD": "Mot de passe actuel incorrect.",
    "PAST_DATE": "On ne peut pas prendre de rendez-vous à une date passée.",
    "PATIENT_HAS_UPCOMING_APPOINTMENT": "Ce patient a déjà un rendez-vous à venir : il faut l'annuler avant d'en prendre un autre.",
    "CAPTCHA_BEFORE_ACCOUNT": "Pour créer un compte, recopiez d'abord correctement les caractères de l'image, puis cliquez sur « Créer un compte client »."
  },
  "CAPTCHA": {
    "LABEL": "Recopiez les caractères de l'image",
    "IMAGE_ALT": "Image de vérification anti-robots",
    "NEW_IMAGE": "Autre image",
    "HELP": "Majuscules ou minuscules, peu importe."
  },
  "REGISTRATION": {
    "TITLE": "Créer un compte client",
    "INTRO": "Ce compte vous permettra de prendre vous-même vos rendez-vous.",
    "LOGIN_HELP": "Lettres minuscules non accentuées, chiffres, point, tiret, souligné.",
    "PASSWORD_HELP": "Au moins {min} caractères.",
    "SUBMIT": "Créer mon compte",
    "BACK_TO_LOGIN": "Retour à la connexion",
    "DONE": "Votre compte a été créé. Vous pouvez vous connecter avec le login {login}."
  },
  "ACCOUNT": {
    "CONFIRMATION_LABEL": "Confirmation du mot de passe"
  },
  "AREA": {
    "TITLE": "Mon espace",
    "HELLO": "Bonjour {name}",
    "MANAGE_ACCOUNT": "Gérer mon compte",
    "MANAGE_ACCOUNT_HELP": "Modifier mes informations, mon mot de passe, ou supprimer mon compte.",
    "VIEW_SCHEDULE": "Voir un agenda",
    "VIEW_SCHEDULE_HELP": "Consulter l'agenda d'un médecin et réserver un créneau.",
    "MY_APPOINTMENT": "Mon rendez-vous",
    "SEE_IN_SCHEDULE": "voir dans l'agenda",
    "CANCEL_APPOINTMENT": "Annuler ce rendez-vous",
    "NO_APPOINTMENT": "Vous n'avez aucun rendez-vous à venir."
  },
  "MY_ACCOUNT": {
    "TITLE": "Gérer mon compte",
    "NEW_PASSWORD_LABEL": "Nouveau mot de passe",
    "CURRENT_PASSWORD_LABEL": "Mot de passe actuel",
    "CURRENT_PASSWORD_HELP": "Obligatoire pour enregistrer une modification.",
    "BACK": "Retour à mon espace",
    "DELETE_TITLE": "Supprimer mon compte",
    "DELETE_HELP": "Votre compte sera définitivement supprimé, ainsi que tous vos rendez-vous.",
    "DELETE_CONFIRM": "Supprimer définitivement votre compte ? Votre rendez-vous éventuel sera annulé.",
    "DELETE_SUBMIT": "Supprimer mon compte",
    "UPDATED": "Votre compte a été modifié.",
    "DELETED": "Votre compte a été supprimé."
  },
  "CONFIRMATION": {
    "TITLE": "Confirmation",
    "NO": "Non, revenir",
    "YES": "Oui, confirmer"
  }
}
  • 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

{
  "APP": {
    "TITLE": "RdvMedecins",
    "LOGOUT": "Log out",
    "MENU_SCHEDULE": "Schedule",
    "MENU_DOCTORS": "Doctors",
    "MENU_PATIENTS": "Patients",
    "MENU_MY_AREA": "My area"
  },
  "LOGIN": {
    "TITLE": "Login",
    "LOGIN_LABEL": "Login",
    "PASSWORD_LABEL": "Password",
    "SUBMIT": "Log in",
    "ERROR": "Incorrect login or password.",
    "DEMO_ACCOUNTS": "Demo accounts (password = login):",
    "DEMO_ADMIN": "ADMIN role: appointments + doctor and patient management",
    "DEMO_DOCTOR": "DOCTOR role: booking and cancelling appointments",
    "DEMO_USER": "USER role (patients): booking for themselves, managing their account",
    "CREATE_ACCOUNT": "Create a patient account",
    "CREATE_ACCOUNT_HELP": "To create an account, first type the characters shown in the image."
  },
  "DOCTOR_DAY_PICKER": {
    "DOCTOR_LABEL": "Doctor",
    "CHOOSE_DOCTOR": "-- choose a doctor --",
    "DAY_LABEL": "Day",
    "VIEW_SCHEDULE": "View schedule"
  },
  "SCHEDULE": {
    "PAGE_TITLE": "Schedule",
    "TITLE_PREFIX": "Schedule for",
    "COLUMN_SLOT": "Slot",
    "COLUMN_STATUS": "Status",
    "FREE": "Free",
    "BOOK": "Book",
    "CANCEL_APPOINTMENT": "Cancel",
    "CANCEL_CONFIRM": "Cancel this appointment?",
    "EMPTY_STATE": "Choose a doctor and a day, then click \"View schedule\".",
    "NO_SLOTS": "This doctor has no time slots.",
    "BOOKED": "Appointment booked.",
    "CANCELLED": "Appointment cancelled.",
    "BOOKED_BY_OTHER": "Booked",
    "ALREADY_BOOKED_INFO": "You already have an upcoming appointment: cancel it to book another one."
  },
  "BOOKING_DIALOG": {
    "TITLE": "Book this slot",
    "CLOSE_ARIA": "Close",
    "SLOT": "Slot {time}",
    "PATIENT_LABEL": "Patient",
    "CHOOSE_PATIENT": "-- choose a patient --",
    "CANCEL": "Cancel",
    "CONFIRM": "Confirm"
  },
  "PERSONS": {
    "COLUMN_TITLE": "Title",
    "COLUMN_FIRSTNAME": "First name",
    "COLUMN_LASTNAME": "Last name",
    "COLUMN_LOGIN": "Login",
    "EDIT": "Edit",
    "DELETE": "Delete",
    "SAVE": "Save",
    "BACK": "Back to the list",
    "TITLE_LABEL": "Title",
    "FIRSTNAME_LABEL": "First name",
    "LASTNAME_LABEL": "Last name",
    "LOGIN_LABEL": "Login",
    "PASSWORD_LABEL": "Password",
    "LOGIN_HELP_CREATE": "Optional: defaults to the last name in lower case.",
    "LOGIN_HELP_EDIT": "Leave empty to keep it unchanged.",
    "PASSWORD_HELP_CREATE": "Optional: defaults to the login.",
    "PASSWORD_HELP_EDIT": "Leave empty to keep it unchanged.",
    "ACCOUNT_SECTION": "User account"
  },
  "DOCTORS": {
    "TITLE": "Doctors",
    "ADD": "Add a doctor",
    "EDIT": "Edit a doctor",
    "EMPTY": "No doctors.",
    "DELETE_CONFIRM": "Delete this doctor, their time slots and their user account?",
    "ADDED": "Doctor {name} has been added (login: {login}).",
    "UPDATED": "Doctor {name} has been updated.",
    "DELETED": "Doctor {name} has been deleted."
  },
  "CLIENTS": {
    "TITLE": "Patients",
    "ADD": "Add a patient",
    "EDIT": "Edit a patient",
    "EMPTY": "No patients.",
    "DELETE_CONFIRM": "Delete this patient, their user account and all their appointments?",
    "ADDED": "Patient {name} has been added (login: {login}).",
    "UPDATED": "Patient {name} has been updated.",
    "DELETED": "Patient {name} has been deleted."
  },
  "ERROR_PAGE": {
    "TITLE": "Error",
    "BACK": "Back to the home page"
  },
  "ERRORS": {
    "LOGIN_TAKEN": "This login is already used by another account.",
    "DOCTOR_ALREADY_EXISTS": "A doctor with this first and last name already exists.",
    "PATIENT_ALREADY_EXISTS": "A patient with this first and last name already exists.",
    "DOCTOR_HAS_APPOINTMENTS": "This doctor has appointments: cancel them before deleting the doctor.",
    "SLOT_ALREADY_BOOKED": "This slot has just been booked by someone else.",
    "CONCURRENT_UPDATE": "This record was changed by another user in the meantime. Go back to the list and reopen it before trying again.",
    "DOCTOR_NOT_FOUND": "This doctor does not exist (any more).",
    "PATIENT_NOT_FOUND": "This patient does not exist (any more).",
    "SLOT_NOT_FOUND": "This slot does not exist (any more).",
    "APPOINTMENT_NOT_FOUND": "This appointment does not exist (any more).",
    "INVALID_DATE": "The requested date is not valid.",
    "CHOOSE_PATIENT": "Choose a patient.",
    "INVALID_FORM": "The form contains errors.",
    "INVALID_TITLE": "Choose a title from the list.",
    "FIRSTNAME_REQUIRED": "The first name is required.",
    "FIRSTNAME_TOO_LONG": "The first name must not exceed 20 characters.",
    "LASTNAME_REQUIRED": "The last name is required.",
    "LASTNAME_TOO_LONG": "The last name must not exceed 20 characters.",
    "INVALID_LOGIN": "At most 30 characters: unaccented lower-case letters, digits, dot, hyphen, underscore.",
    "PASSWORD_TOO_LONG": "The password must not exceed 72 characters.",
    "SESSION_EXPIRED": "Your session has expired: please log in again.",
    "BAD_REQUEST": "The request is invalid.",
    "FORBIDDEN": "Your role does not allow you to access this page.",
    "NOT_FOUND": "This page does not exist.",
    "SERVER_ERROR": "An unexpected error occurred. Please try again later.",
    "TOO_MANY_ATTEMPTS": "Too many failed attempts. Try again in {minutes} minute(s).",
    "WRONG_CAPTCHA": "The characters you typed do not match the image. A new image is shown.",
    "TOO_MANY_ACCOUNTS": "Too many accounts have been created from your connection. Try again in {minutes} minute(s).",
    "LOGIN_REQUIRED": "The login is required.",
    "PASSWORD_REQUIRED": "The password is required.",
    "PASSWORD_TOO_SHORT": "The password must be at least {min} characters long.",
    "CONFIRMATION_REQUIRED": "Please confirm the password.",
    "PASSWORDS_DIFFER": "The confirmation does not match the password.",
    "CURRENT_PASSWORD_REQUIRED": "Enter your current password.",
    "WRONG_CURRENT_PASSWORD": "Incorrect current password.",
    "PAST_DATE": "Appointments cannot be booked for a past date.",
    "PATIENT_HAS_UPCOMING_APPOINTMENT": "This patient already has an upcoming appointment: it must be cancelled before booking another one.",
    "CAPTCHA_BEFORE_ACCOUNT": "To create an account, first type the characters shown in the image correctly, then click \"Create a patient account\"."
  },
  "CAPTCHA": {
    "LABEL": "Type the characters shown in the image",
    "IMAGE_ALT": "Anti-robot verification image",
    "NEW_IMAGE": "Another image",
    "HELP": "Upper or lower case, it does not matter."
  },
  "REGISTRATION": {
    "TITLE": "Create a patient account",
    "INTRO": "With this account you can book your own appointments.",
    "LOGIN_HELP": "Unaccented lower-case letters, digits, dot, hyphen, underscore.",
    "PASSWORD_HELP": "At least {min} characters.",
    "SUBMIT": "Create my account",
    "BACK_TO_LOGIN": "Back to login",
    "DONE": "Your account has been created. You can now log in with the login {login}."
  },
  "ACCOUNT": {
    "CONFIRMATION_LABEL": "Confirm password"
  },
  "AREA": {
    "TITLE": "My area",
    "HELLO": "Hello {name}",
    "MANAGE_ACCOUNT": "Manage my account",
    "MANAGE_ACCOUNT_HELP": "Change my details or password, or delete my account.",
    "VIEW_SCHEDULE": "View a schedule",
    "VIEW_SCHEDULE_HELP": "See a doctor's schedule and book a slot.",
    "MY_APPOINTMENT": "My appointment",
    "SEE_IN_SCHEDULE": "see in the schedule",
    "CANCEL_APPOINTMENT": "Cancel this appointment",
    "NO_APPOINTMENT": "You have no upcoming appointment."
  },
  "MY_ACCOUNT": {
    "TITLE": "Manage my account",
    "NEW_PASSWORD_LABEL": "New password",
    "CURRENT_PASSWORD_LABEL": "Current password",
    "CURRENT_PASSWORD_HELP": "Required to save any change.",
    "BACK": "Back to my area",
    "DELETE_TITLE": "Delete my account",
    "DELETE_HELP": "Your account will be permanently deleted, together with all your appointments.",
    "DELETE_CONFIRM": "Permanently delete your account? Any appointment you have will be cancelled.",
    "DELETE_SUBMIT": "Delete my account",
    "UPDATED": "Your account has been updated.",
    "DELETED": "Your account has been deleted."
  },
  "CONFIRMATION": {
    "TITLE": "Confirmation",
    "NO": "No, go back",
    "YES": "Yes, confirm"
  }
}

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

/* =========================================================================
   wwwroot/css/styles.css - alguns ajustes sobre o Bootstrap
   (extraídos de src/styles.css do cliente Angular, via projeto NestJS).
   ========================================================================= */

body {
  background-color: #f5f7fa;
}

.free-slot:hover {
  background-color: #e9f7ef;
}

/* -------------------------------------------------------------------------
   .error-zone: as mensagens de erro, na parte inferior da página, sobre um fundo rosa claro
   (veja Views/Shared/_Errors.cshtml).
   position: sticky + bottom: se a página for mais alta que a janela (uma
   agenda de 12 horários, por exemplo), a zona fica colada na parte inferior da
   janela em vez de desaparecer abaixo da dobra - sem jamais
   cobrir o conteúdo quando a página for curta.
   z-index: acima do fundo cinza do diálogo de marcação (.modal-backdrop).
   ------------------------------------------------------------------------- */
.error-zone {
  position: sticky;
  bottom: 1rem;
  z-index: 1060;
  margin-top: 1.5rem;
  padding: 0.75rem 1rem;
  background-color: #fdecef; /* rosa claro */
  border: 1px solid #f5c2c7;
  border-radius: 0.375rem;
  color: #842029;
}

/* as duas grandes opções da página "My area" do paciente */
.option-card {
  transition: border-color 0.15s, box-shadow 0.15s;
}

.option-card:hover {
  border-color: #0d6efd;
  box-shadow: 0 0.25rem 0.75rem rgba(13, 110, 253, 0.15);
}

/* a imagem do captcha (SVG de 150 x 50 pixels) */
.captcha-image svg {
  display: block;
  border: 1px solid #dee2e6;
  border-radius: 0.375rem;
}
  • 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

// =========================================================================
// wwwroot/js/app.js - o ÚNICO JavaScript da aplicação.
// -------------------------------------------------------------------------
// A aplicação inteira funciona sem JavaScript. Este script adiciona uma
// comodidade: antes de enviar um formulário que carrega o atributo
// data-confirmation="...", uma janela modal pergunta "Are you sure?"
// (a janela em si está na página: Views/Shared/_Confirmation.cshtml).
// Se o JavaScript estiver desabilitado, o formulário é simplesmente enviado sem
// confirmação: nada quebra (princípio de "progressive enhancement").
//
// Por que não window.confirm()? Sua caixa não pode ser estilizada, e seus
// botões permanecem no idioma do navegador, não no da página.
// =========================================================================

(() => {
  const modal = document.getElementById('confirmation-modal');
  if (!modal) {
    return;
  }
  const message = document.getElementById('confirmation-modal-message');
  const noButton = modal.querySelector('.modal-footer [data-action="no"]');

  let pendingForm = null; // o formulário a enviar se o usuário confirmar
  let previousFocus = null; // o elemento a que devolver o foco ao fechar

  function open(form) {
    pendingForm = form;
    previousFocus = document.activeElement;
    // textContent (e não innerHTML): a mensagem é exibida como TEXTO,
    // nunca interpretada como HTML
    message.textContent = form.dataset.confirmation;
    modal.classList.remove('d-none');
    // o foco vai para "No": um Enter pressionado distraidamente não exclui nada
    noButton.focus();
  }

  function close() {
    modal.classList.add('d-none');
    pendingForm = null;
    if (previousFocus) {
      previousFocus.focus();
    }
  }

  // 1. interceptamos o envio dos formulários a confirmar
  document.querySelectorAll('form[data-confirmation]').forEach((form) => {
    form.addEventListener('submit', (event) => {
      event.preventDefault();
      open(form);
    });
  });

  // 2. os botões da janela (Yes / No / cruz de fechar)
  modal.addEventListener('click', (event) => {
    const action = event.target.closest('[data-action]')?.dataset.action;
    if (action === 'yes') {
      const form = pendingForm;
      close();
      // form.submit() envia o formulário SEM disparar novamente o
      // evento 'submit': nenhum novo pedido de confirmação
      form.submit();
    } else if (action === 'no') {
      close();
    } else if (event.target.classList.contains('modal')) {
      close(); // clique no fundo cinza, fora da janela
    }
  });

  // 3. teclado: Escape fecha a janela; Tab permanece DENTRO da janela
  //    (caso contrário o foco iria para a página acinzentada, atrás)
  modal.addEventListener('keydown', (event) => {
    if (event.key === 'Escape') {
      close();
    } else if (event.key === 'Tab') {
      const buttons = [...modal.querySelectorAll('button')];
      const first = buttons[0];
      const last = buttons[buttons.length - 1];
      if (event.shiftKey && document.activeElement === first) {
        event.preventDefault();
        last.focus();
      } else if (!event.shiftKey && document.activeElement === last) {
        event.preventDefault();
        first.focus();
      }
    }
  });
})();

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.