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). Ela usa as camadas de banco de dados e de negócio do servidor [NestJS] dos cursos “Uma aplicação cliente/servidor [Flutter] / [NestJS]” e “Um exemplo cliente/servidor com Angular/NestJS”, e exibe as mesmas páginas do cliente [Angular]; mas, em vez de servir JSON a um cliente [JavaScript] ou [Flutter], ela gera suas próprias páginas HTML.
Três papéis de usuário compartilham a aplicação:
Papel | Quem | O que pode fazer |
ADMIN | O administrador ([admin]) | ver as agendas, marcar e cancelar consultas de qualquer paciente; gerenciar (listar, incluir, alterar, excluir) médicos e clientes |
DOCTOR | Os médicos | Ver as agendas, marcar e cancelar consultas de qualquer paciente |
USER | os clientes (pacientes) | ver as agendas sem ver os nomes dos outros pacientes; marcar uma consulta para si; cancelar a própria consulta; gerenciar a própria 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 pode ter apenas 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 primeiro resolver o CAPTCHA dessa página.
11.2. Usando a aplicação
11.2.1. A página de login

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

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

11.2.2. O calendário, visto pelo administrador e pelos médicos
Depois de logado, o administrador é levado à página do calendário. Ele seleciona um médico e um dia:


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

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

11.2.3. O painel do paciente
Um paciente (papel USER) chega a My area: sua próxima consulta, que ele pode cancelar, e links para o gerenciamento de sua conta e para o calendário:

No calendário, ele vê a própria consulta, mas não os nomes dos outros pacientes (Booked). Como já tem uma consulta futura, não pode marcar outra:

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

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

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

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


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

Um nome igual ao de um médico existente é rejeitado:

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

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


11.3. Instalação e execução
A pasta da aplicação:
| rdvmedecins-nestjs-html/
├── database/
│ ├── README.md
│ └── dbrdvmedecins2.sql
├── i18n/
│ ├── en.json
│ └── fr.json
├── public/
│ ├── css/
│ │ └── styles.css
│ └── js/
│ └── app.js
├── src/
│ ├── auth/
│ │ ├── README.md
│ │ ├── attempt-limiter.service.ts
│ │ ├── auth.constants.ts
│ │ ├── auth.controller.ts
│ │ ├── auth.module.ts
│ │ ├── auth.service.ts
│ │ ├── captcha.service.ts
│ │ ├── jwt-auth.guard.ts
│ │ ├── jwt.strategy.ts
│ │ ├── registration-pass.service.ts
│ │ ├── roles.decorator.ts
│ │ └── roles.guard.ts
│ ├── business/
│ │ ├── README.md
│ │ ├── business.exception.ts
│ │ ├── business.interface.ts
│ │ ├── business.service.ts
│ │ └── dates.ts
│ ├── config/
│ │ ├── README.md
│ │ ├── database.config.ts
│ │ └── paths.ts
│ ├── domain/
│ │ ├── README.md
│ │ ├── doctor-day-schedule.ts
│ │ └── doctor-day-slot.ts
│ ├── entities/
│ │ ├── README.md
│ │ ├── abstract.entity.ts
│ │ ├── appointment.entity.ts
│ │ ├── client.entity.ts
│ │ ├── doctor.entity.ts
│ │ ├── person.entity.ts
│ │ ├── slot.entity.ts
│ │ └── user.entity.ts
│ ├── repositories/
│ │ ├── README.md
│ │ ├── appointment.repository.ts
│ │ ├── client.repository.ts
│ │ ├── doctor.repository.ts
│ │ ├── slot.repository.ts
│ │ └── user.repository.ts
│ ├── web/
│ │ ├── controllers/
│ │ │ ├── clients.controller.ts
│ │ │ ├── doctors.controller.ts
│ │ │ ├── language.controller.ts
│ │ │ ├── patient-area.controller.ts
│ │ │ ├── persons.controller.ts
│ │ │ ├── registration.controller.ts
│ │ │ └── schedule.controller.ts
│ │ ├── helpers/
│ │ │ ├── dates.helper.ts
│ │ │ ├── form.helper.ts
│ │ │ └── patient.helper.ts
│ │ ├── models/
│ │ │ └── person-form.dto.ts
│ │ ├── views/
│ │ │ └── handlebars-helpers.ts
│ │ ├── README.md
│ │ ├── application-model.service.ts
│ │ ├── html-exception.filter.ts
│ │ ├── i18n.ts
│ │ ├── view-context.ts
│ │ └── view-user.interceptor.ts
│ ├── README.md
│ ├── app.module.ts
│ └── main.ts
├── views/
│ ├── account/
│ │ └── registration.hbs
│ ├── partials/
│ │ ├── booking.hbs
│ │ ├── captcha.hbs
│ │ ├── confirmation.hbs
│ │ ├── errors.hbs
│ │ ├── flash.hbs
│ │ ├── navbar.hbs
│ │ └── personFields.hbs
│ ├── patient/
│ │ ├── account.hbs
│ │ └── area.hbs
│ ├── persons/
│ │ ├── form.hbs
│ │ └── list.hbs
│ ├── README.md
│ ├── error.hbs
│ ├── layout.hbs
│ ├── login.hbs
│ └── schedule.hbs
├── .env.example
├── README.md
├── nest-cli.json
├── package-lock.json
├── package.json
└── tsconfig.json
|
Os arquivos [README.md] descrevem a finalidade de cada pasta; eles não são reproduzidos aqui. Para instalar e executar a aplicação:
- crie o banco de dados [dbrdvmedecins2] executando o script [database/dbrdvmedecins2.sql] (veja os apêndices);
- em uma janela de console aberta na pasta da aplicação, instale as dependências: [npm install];
- renomeie o arquivo [.env.example] para [.env] e atualize nele as configurações de conexão de acordo com as do [MySQL];
- execute a aplicação: [npm run start:dev], depois abra [http://localhost:8081].
As senhas das contas de demonstração são os próprios logins: [admin] (ADMIN), [pelissier], [tatou], [dupont] (DOCTOR), [martin], [durand], [bistrou], [german] (USER). Na inicialização:
| [Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [NestFactory] Starting Nest application...
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [InstanceLoader] TypeOrmModule dependencies initialized +84ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [InstanceLoader] PassportModule dependencies initialized +0ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [InstanceLoader] JwtModule dependencies initialized +1ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [InstanceLoader] TypeOrmCoreModule dependencies initialized +58ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [InstanceLoader] TypeOrmModule dependencies initialized +1ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [InstanceLoader] TypeOrmModule dependencies initialized +0ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [InstanceLoader] AuthModule dependencies initialized +1ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [InstanceLoader] AppModule dependencies initialized +3ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [RoutesResolver] ScheduleController {/schedule}: +15ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [RouterExplorer] Mapped {/schedule, GET} route +3ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [RouterExplorer] Mapped {/schedule/book, POST} route +0ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [RouterExplorer] Mapped {/schedule/cancel, POST} route +0ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [RoutesResolver] DoctorsController {/doctors}: +1ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [RouterExplorer] Mapped {/doctors, GET} route +0ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [RouterExplorer] Mapped {/doctors/add, GET} route +0ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [RouterExplorer] Mapped {/doctors/add, POST} route +0ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [RouterExplorer] Mapped {/doctors/:id/edit, GET} route +1ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [RouterExplorer] Mapped {/doctors/:id/edit, POST} route +0ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [RouterExplorer] Mapped {/doctors/:id/delete, POST} route +0ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [RoutesResolver] ClientsController {/clients}: +0ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [RouterExplorer] Mapped {/clients, GET} route +1ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [RouterExplorer] Mapped {/clients/add, GET} route +0ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [RouterExplorer] Mapped {/clients/add, POST} route +0ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [RouterExplorer] Mapped {/clients/:id/edit, GET} route +0ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [RouterExplorer] Mapped {/clients/:id/edit, POST} route +0ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [RouterExplorer] Mapped {/clients/:id/delete, POST} route +0ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LOG [RoutesResolver] LanguageController {/language}: +0ms
[Nest] 14248 - 09/23/2026, 4:23:55 PM LO
|
(os comandos SQL exibidos pelo [TypeORM] foram removidos)
11.4. Arquitetura da aplicação

- [src/main.ts] configura a aplicação: view engine, arquivos estáticos, cookies, filtro de exceção;
- [src/auth]: autenticação, tokens (JWT), papéis, CAPTCHA e limite de tentativas;
- [src/web]: a camada web. Seus controllers ([src/web/controllers]) passam todos por um único serviço, [ApplicationModelService], que guarda em memória as listas de médicos e clientes e encaminha as demais requisições à camada de negócio;
- [src/business]: as regras de negócio;
- [src/repositories]: a camada DAO, uma classe por tabela;
- [src/entities]: as entidades [TypeORM]; [src/domain]: os objetos do calendário, calculados pela camada de negócio;
- [views]: as views [Handlebars]; [i18n]: os dicionários; [public]: a folha de estilos e o script das páginas.
A sequência comenta todos os arquivos, das camadas inferiores (banco de dados) às camadas superiores (views).
11.5. O banco de dados
O arquivo [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): cada médico e cada 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 rounds)
-- - nome exibido = nome + sobrenome
--
-- 4. restrições de unicidade, todas NOMEADAS (a aplicação NestJS 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 vale para os clientes.
-- Atenção: a collation utf8mb4_unicode_ci compara sem diferenciar
-- maiúsculas de minúsculas nem acentos - "Hélène DUPONT" e "helene dupont"
-- são portanto considerados idênticos.
--
-- A tabela [users] agora deve ser criada ANTES de [doctors] e [clients]
-- (elas a referenciam), e removida DEPOIS delas.
-- =========================================================================
-- recomeçamos de um banco 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 "pai"
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 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 salt rounds)
-- 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 reservar 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] é buscada 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 8h às 12h, 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 14h às 18h, 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 comentar este script:
- linha 30: como no Exemplo 28, a collation [utf8mb4_unicode_ci] ignora maiúsculas e acentos nas comparações;
- linhas 34–38: as tabelas são excluídas das tabelas “filhas” para as tabelas “pais”: uma tabela referenciada por uma chave estrangeira não pode ser excluída antes das tabelas que a referenciam;
- linhas 43–52: contas de usuário. [password] contém o hash bcrypt da senha (veja o Exemplo 25). Linha 51: um login é único;
- Linhas 57–69: médicos. Cada um tem uma conta (coluna [user], chave estrangeira para [users], linha 64). O nome [user] é uma palavra reservada do [MySQL]: por isso ele é delimitado por crases. Linha 66: uma conta pertence a um único médico; linha 68: não pode haver dois médicos com o mesmo nome e sobrenome;
- linhas 74–86: clientes, seguindo o mesmo formato;
- linhas 91–100: os horários de cada médico (hora de início e de término em horas e minutos);
- linhas 105–115: consultas: um dia, um horário, um cliente. Linha 114: um horário é reservado apenas uma vez por dia;
- linhas 127–137: contas de demonstração; a senha de cada conta é o seu login;
- linhas 141–144: a coluna [user] de cada médico é obtida por uma subconsulta sobre o login, em vez de supor as credenciais geradas;
- linhas 167–168: uma consulta no mesmo dia ([CURDATE()]), para mostrar imediatamente um horário reservado.
11.6. Configuração do projeto
O arquivo [package.json]:
| {
"name": "rdvmedecins-nestjs-html",
"version": "1.0.0",
"description": "NestJS web application (HTML pages generated server-side) for booking medical appointments [RdvMedecins] - database [dbrdvmedecins2], roles ADMIN / DOCTOR / USER",
"private": true,
"license": "UNLICENSED",
"scripts": {
"build": "nest build",
"start": "nest start",
"start:dev": "nest start --watch --watchAssets",
"start:debug": "nest start --debug --watch --watchAssets",
"start:prod": "node dist/main"
},
"dependencies": {
"@nestjs/common": "^10.4.0",
"@nestjs/core": "^10.4.0",
"@nestjs/jwt": "^10.2.0",
"@nestjs/passport": "^10.0.3",
"@nestjs/platform-express": "^10.4.0",
"@nestjs/typeorm": "^10.0.2",
"bcryptjs": "^3.0.3",
"bootstrap": "^5.3.3",
"class-transformer": "^0.5.1",
"class-validator": "^0.14.1",
"cookie-parser": "^1.4.7",
"dotenv": "^17.4.2",
"hbs": "^4.2.0",
"mysql2": "^3.11.0",
"passport-jwt": "^4.0.1",
"reflect-metadata": "^0.2.2",
"rxjs": "^7.8.1",
"svg-captcha": "^1.4.0",
"typeorm": "^0.3.20"
},
"devDependencies": {
"@nestjs/cli": "^10.4.5",
"@types/bcryptjs": "^2.4.6",
"@types/cookie-parser": "^1.4.7",
"@types/express": "^4.17.21",
"@types/node": "^20.14.0",
"@types/passport-jwt": "^4.0.1",
"typescript": "^5.5.0"
}
}
|
- linhas 7–13: os comandos [npm run ...]. [start:dev] inicia a aplicação no modo “watch”: o código é recompilado e o servidor reiniciado a cada alteração; a opção [--watchAssets] também monitora os arquivos que não são código;
- Linhas 14–34: as bibliotecas da aplicação, todas abordadas nos exemplos. [dotenv] lê o arquivo [.env]; [mysql2] é o driver [MySQL] usado pelo [TypeORM]; [reflect-metadata] e [rxjs] são exigidos pelo [NestJS];
- Linhas 35–43: ferramentas de desenvolvimento: a ferramenta [nest], o compilador [TypeScript] e as declarações de tipos ([@types/...]) das bibliotecas escritas em [JavaScript].
O arquivo [tsconfig.json]:
| {
"compilerOptions": {
"module": "commonjs",
"declaration": false,
"removeComments": true,
"emitDecoratorMetadata": true,
"experimentalDecorators": true,
"allowSyntheticDefaultImports": true,
"target": "ES2022",
"lib": ["ES2022"],
"sourceMap": true,
"outDir": "./dist",
"baseUrl": "./",
"incremental": true,
"skipLibCheck": true,
"strictNullChecks": true,
"noImplicitAny": false,
"strictBindCallApply": false,
"forceConsistentCasingInFileNames": true,
"noFallthroughCasesInSwitch": false
}
}
|
Este arquivo é gerado pela ferramenta [nest] para um novo projeto. Em comparação com os exemplos: linha 5, os comentários não são copiados para o código compilado; linha 14, apenas os arquivos modificados são recompilados; linha 17: uma variável sem tipo explícito ou inferível é aceita (ela é então do tipo [any]). É isso que permite importar o pacote [hbs], que não tem declarações de tipos.
O arquivo [nest-cli.json]:
| {
"$schema": "https://json.schemastore.org/nest-cli",
"collection": "@nestjs/schematics",
"sourceRoot": "src",
"compilerOptions": {
"deleteOutDir": true
}
}
|
Idêntico ao dos exemplos.
O arquivo [.env.example]:
| # -----------------------------------------------------------------------
# Arquivo de configuração de exemplo.
# Copie este arquivo para [.env] e depois adapte os valores à sua máquina.
# O arquivo [.env] nunca deve ser compartilhado nem commitado (senhas).
# -----------------------------------------------------------------------
# porta de escuta do servidor NestJS. O servidor JSON já escuta na 8080:
# escolhemos outra porta para que os dois possam executar ao mesmo tempo.
PORT=8081
# parâmetros de conexão com o banco de dados MySQL [dbrdvmedecins2]
# (script: database/dbrdvmedecins2.sql)
DB_HOST=localhost
DB_PORT=3306
DB_USERNAME=root
DB_PASSWORD=
DB_DATABASE=dbrdvmedecins2
# -----------------------------------------------------------------------
# autenticação (veja src/auth/)
# -----------------------------------------------------------------------
# chave secreta usada para assinar/verificar os tokens JWT - DEVE ser alterada
# em produção (uma string aleatória longa, nunca commitada).
JWT_SECRET=change-me-to-a-long-random-string
# validade de um token JWT, em segundos (7200 s = 2 h). O cookie
# que carrega o token tem o mesmo tempo de vida.
JWT_EXPIRES_IN_SECONDS=7200
# defina como true em produção (site servido por HTTPS): o cookie de
# autenticação então nunca será enviado por uma conexão não criptografada.
COOKIE_SECURE=false
# -----------------------------------------------------------------------
# proteção contra bots (veja src/auth/attempt-limiter.service.ts)
# -----------------------------------------------------------------------
# login: número de falhas (captcha ou senha errados) permitidas para
# o mesmo login a partir do mesmo endereço IP, antes de este par ser bloqueado...
LOGIN_MAX_FAILURES=5
# ... por esta duração (um endereço IP também é bloqueado se acumular
# 5 vezes mais falhas, todos os logins somados)
LOGIN_BLOCK_MINUTES=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.
REGISTRATION_MAX_PER_HOUR=10
|
- Um arquivo chamado [.env] contém as configurações específicas da máquina: ele nunca é compartilhado (contém senhas). O arquivo [.env.example] serve de modelo a ser copiado;
- linha 9: a porta da aplicação;
- linhas 13–17: a conexão com o banco de dados;
- linhas 24–30: a chave do token, sua duração (duas horas) e a opção de cookie [secure] (em produção, o site é servido por HTTPS, e o cookie nunca deve ser transmitido por uma conexão não criptografada);
- linhas 37–44: os limites da proteção contra bots.
O arquivo [src/config/database.config.ts]:
| // =========================================================================
// config/database.config.ts
// -------------------------------------------------------------------------
// Configuração da conexão com o banco de dados MySQL, usada pelo
// TypeORM. É o equivalente da classe [DomainAndPersitenceConfig] do
// projeto Spring original, que definia um [DataSource] (bloco @Bean).
//
// Aqui, sem classe: o NestJS/TypeORM prefere uma simples função que
// retorna um objeto de configuração, lido das variáveis de ambiente
// (arquivo .env na raiz do projeto, carregado automaticamente pelo NestJS
// por meio do módulo @nestjs/config se instalado - aqui lemos
// process.env diretamente para manter tudo simples e didático).
// =========================================================================
import { TypeOrmModuleOptions } from '@nestjs/typeorm';
import { Doctor } from '../entities/doctor.entity';
import { Client } from '../entities/client.entity';
import { Slot } from '../entities/slot.entity';
import { Appointment } from '../entities/appointment.entity';
import { User } from '../entities/user.entity';
export function getDatabaseConfig(): TypeOrmModuleOptions {
return {
// 'mysql': usamos o driver MySQL, como no projeto original (MySQL5 -> MySQL8 aqui).
type: 'mysql',
host: process.env.DB_HOST ?? 'localhost',
port: process.env.DB_PORT ? parseInt(process.env.DB_PORT, 10) : 3306,
username: process.env.DB_USERNAME ?? 'root',
password: process.env.DB_PASSWORD ?? '',
database: process.env.DB_DATABASE ?? 'dbrdvmedecins2',
// a lista de entidades (classes @Entity) que o TypeORM deve gerenciar.
// É o equivalente do "scan" automático das classes @Entity feito pelo Spring Boot.
entities: [Doctor, Client, Slot, Appointment, User],
// IMPORTANTE: synchronize=false o tempo todo neste curso.
// Se synchronize fosse true, o TypeORM modificaria por conta própria o schema do banco
// a partir das entidades: prático para um protótipo descartável, perigoso assim que há
// dados reais (risco de perda de dados). Como faria uma equipe de verdade, preferimos
// manter o controle do schema por meio do script database/dbrdvmedecins2.sql.
synchronize: false,
// exibe no console as consultas SQL geradas pelo TypeORM: muito útil para
// entender o que o ORM faz por você, exatamente como os logs do Hibernate
// do projeto Spring original.
logging: process.env.NODE_ENV !== 'production',
};
}
|
A conexão com o banco de dados (veja o Exemplo 28). Linha 46: os comandos SQL são exibidos, exceto em produção.
O arquivo [src/config/paths.ts]:
| // =========================================================================
// config/paths.ts
// -------------------------------------------------------------------------
// As pastas NÃO compiladas do projeto (views Handlebars, arquivos estáticos,
// dicionários de tradução) ficam na raiz do projeto, ao lado de
// src/ e dist/. Depois de compilado, este mesmo arquivo fica em
// dist/config/: a raiz do projeto está portanto dois níveis acima.
// =========================================================================
import { join, resolve } from 'path';
export const PROJECT_ROOT = resolve(__dirname, '..', '..');
export const VIEWS_DIR = join(PROJECT_ROOT, 'views'); // templates de página (.hbs)
export const PARTIALS_DIR = join(VIEWS_DIR, 'partials'); // partes reutilizáveis de páginas
export const PUBLIC_DIR = join(PROJECT_ROOT, 'public'); // CSS, JS, imagens
export const I18N_DIR = join(PROJECT_ROOT, 'i18n'); // fr.json, en.json
export const BOOTSTRAP_DIR = join(PROJECT_ROOT, 'node_modules', 'bootstrap', 'dist');
|
- Linha 12: depois de compilado, este arquivo fica em [dist/config]: a raiz do projeto está dois níveis acima;
- linhas 14–18: as pastas não compiladas (views, arquivos estáticos, dicionários) e a do [Bootstrap].
11.7. Inicialização da aplicação
O arquivo [src/main.ts]:
| // =========================================================================
// main.ts
// -------------------------------------------------------------------------
// Ponto de entrada da aplicação. Em comparação com o servidor JSON, a
// inicialização também configura tudo o que é necessário para CONSTRUIR PÁGINAS HTML
// no lado do servidor:
// - uma engine de views (Handlebars, arquivos views/*.hbs);
// - os arquivos estáticos (Bootstrap, CSS, um pouco de JavaScript);
// - a análise de cookies (token JWT, idioma, mensagens flash);
// - um filtro que transforma erros em páginas HTML.
// Não há mais CORS a permitir: páginas e dados agora vêm do
// MESMO servidor.
// =========================================================================
import 'dotenv/config'; // DEVE continuar sendo o primeiríssimo import (veja o servidor JSON)
import 'reflect-metadata';
import { NestFactory } from '@nestjs/core';
import { NestExpressApplication } from '@nestjs/platform-express';
import * as cookieParser from 'cookie-parser';
import * as hbs from 'hbs';
import { AppModule } from './app.module';
import { BOOTSTRAP_DIR, PARTIALS_DIR, PUBLIC_DIR, VIEWS_DIR } from './config/paths';
import { registerHelpers } from './web/views/handlebars-helpers';
import { viewContextMiddleware } from './web/view-context';
import { HtmlExceptionFilter } from './web/html-exception.filter';
import { ViewUserInterceptor } from './web/view-user.interceptor';
async function bootstrap() {
// NestExpressApplication: declaramos que a plataforma subjacente é o
// Express, para ter acesso aos seus métodos próprios (setViewEngine,
// useStaticAssets...) - eles não existem na plataforma Fastify.
const app = await NestFactory.create<NestExpressApplication>(AppModule);
// 1. arquivos estáticos: /css/..., /js/... (pasta public/) e
// /bootstrap/css/bootstrap.min.css (diretamente de node_modules:
// sem necessidade de copiar o Bootstrap para o projeto)
app.useStaticAssets(PUBLIC_DIR);
app.useStaticAssets(BOOTSTRAP_DIR, { prefix: '/bootstrap/' });
// 2. a engine de views. O arquivo views/layout.hbs é usado
// AUTOMATICAMENTE pelo hbs como template comum de todas as páginas:
// cada view é inserida no local de {{{body}}} deste template.
app.setBaseViewsDir(VIEWS_DIR);
app.setViewEngine('hbs');
registerHelpers(hbs);
// os "partials" (views/partials/*.hbs): partes reutilizáveis de página,
// inseridos com {{> name}}. registerPartials lê a pasta
// de forma assíncrona: esperamos que termine antes de aceitar requisições.
await new Promise<void>((done) => hbs.registerPartials(PARTIALS_DIR, () => done()));
// 3. cookie-parser preenche req.cookies; depois nosso middleware prepara o
// idioma e a mensagem flash de cada página (veja web/view-context.ts)
app.use(cookieParser());
app.use(viewContextMiddleware);
// 4. o usuário logado, visível para todas as views; e os erros
// transformados em páginas HTML (ou em um redirecionamento para /login)
app.useGlobalInterceptors(new ViewUserInterceptor());
app.useGlobalFilters(new HtmlExceptionFilter());
const port = process.env.PORT ? parseInt(process.env.PORT, 10) : 8081;
await app.listen(port);
// eslint-disable-next-line no-console
console.log(`[RdvMedecins] web application started on http://localhost:${port}`);
}
bootstrap();
|
Vamos analisar este código:
- Linha 15: [dotenv/config] lê o arquivo [.env] e coloca seus valores em [process.env]. Essa importação deve ser a primeira: os outros módulos leem [process.env] assim que são carregados ([JWT_SECRET], por exemplo);
- linhas 37–38: arquivos estáticos (veja o Exemplo 15);
- linhas 43–49: a view engine, os helpers e as views parciais (veja os Exemplos 15 e 16);
- linhas 53–54: leitura dos cookies, seguida do middleware que prepara o idioma e a mensagem flash de cada página (veja [web/view-context.ts]);
- linhas 58–59: um interceptor global expõe o usuário logado às views, e um filtro global converte as exceções em páginas HTML (veja o Capítulo 7);
- linha 61: a porta, lida de [.env] (8081 por padrão).
O arquivo [src/app.module.ts]:
| // =========================================================================
// app.module.ts
// -------------------------------------------------------------------------
// O módulo raiz. As mesmas camadas do servidor JSON (DAO, negócio,
// cache/fachada); só os controllers mudam: eles agora constroem
// páginas HTML em vez de respostas JSON.
// =========================================================================
import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { getDatabaseConfig } from './config/database.config';
import { Doctor } from './entities/doctor.entity';
import { Client } from './entities/client.entity';
import { Slot } from './entities/slot.entity';
import { Appointment } from './entities/appointment.entity';
import { DoctorRepository } from './repositories/doctor.repository';
import { ClientRepository } from './repositories/client.repository';
import { SlotRepository } from './repositories/slot.repository';
import { AppointmentRepository } from './repositories/appointment.repository';
import { BUSINESS_TOKEN } from './business/business.interface';
import { BusinessService } from './business/business.service';
import { ApplicationModelService } from './web/application-model.service';
import { ScheduleController } from './web/controllers/schedule.controller';
import { DoctorsController } from './web/controllers/doctors.controller';
import { ClientsController } from './web/controllers/clients.controller';
import { LanguageController } from './web/controllers/language.controller';
import { RegistrationController } from './web/controllers/registration.controller';
import { PatientAreaController } from './web/controllers/patient-area.controller';
import { AuthModule } from './auth/auth.module';
@Module({
imports: [
TypeOrmModule.forRoot(getDatabaseConfig()),
TypeOrmModule.forFeature([Doctor, Client, Slot, Appointment]),
// AuthModule fornece /login e /logout; ele exporta UserRepository
// (injetado em BusinessService), AuthService, CaptchaService e
// AttemptLimiterService (injetados nos controllers de src/web/)
AuthModule,
],
controllers: [
ScheduleController,
DoctorsController,
ClientsController,
LanguageController,
RegistrationController, // "Criar uma conta de paciente" (pública)
PatientAreaController, // "Minha área", "Gerenciar minha conta" (USER)
],
providers: [
DoctorRepository,
ClientRepository,
SlotRepository,
AppointmentRepository,
{ provide: BUSINESS_TOKEN, useClass: BusinessService },
ApplicationModelService,
],
})
export class AppModule {}
|
- linha 38: a conexão com o banco de dados;
- linha 39: os repositórios das quatro entidades gerenciadas por este módulo (o de [User] é declarado pelo [AuthModule]);
- linha 43: o módulo de autenticação, com seu próprio controller e seus serviços;
- linhas 45–52: os controllers da camada web;
- Linhas 53–60: os serviços: a camada DAO (os quatro repositórios), a camada de negócio e o cache da camada web. Linha 58: a camada de negócio é registrada sob um token ([BUSINESS_TOKEN]) em vez de sob o nome de sua classe: quem a utiliza depende da interface [IBusiness], e não da classe [BusinessService]. A implementação poderia ser substituída (por uma versão de teste, por exemplo) modificando apenas esta linha.
11.8. As entidades
As entidades do [TypeORM] mapeiam as tabelas do banco de dados para classes em [TypeScript] (veja o Exemplo 28). Seus comentários frequentemente remetem ao projeto [Java] / [Spring] , do qual a aplicação é uma descendente distante, e ao “servidor JSON”: o servidor [NestJS] dos cursos cliente/servidor, cujo estudo de caso incorpora as camadas DAO e de negócio.
11.8.1. src/entities/abstract.entity.ts
| // =========================================================================
// entities/abstract.entity.ts
// -------------------------------------------------------------------------
// Equivalente da classe [AbstractEntity] do projeto Spring original,
// que era anotada com @MappedSuperclass. Ela agrupa os dois campos
// comuns a todas as nossas entidades persistentes: o identificador [id] e o
// número de versão [version] usado para gerenciar o acesso concorrente.
//
// No JPA, @MappedSuperclass significa "esta classe não é uma tabela,
// mas seus campos devem ser adicionados às tabelas das classes filhas".
// O TypeORM oferece exatamente o mesmo mecanismo: basta que uma classe
// abstrata (não decorada com @Entity) seja herdada por uma classe que,
// ela sim, tenha a anotação @Entity. O TypeORM então adiciona automaticamente
// as colunas herdadas à tabela da classe filha.
// =========================================================================
import { PrimaryGeneratedColumn, VersionColumn } from 'typeorm';
export abstract class AbstractEntity {
// equivalente a:
// @Id
// @GeneratedValue(strategy = GenerationType.AUTO)
// protected Long id;
//
// @PrimaryGeneratedColumn() declara uma chave primária autoincrementada pelo SGBD,
// exatamente como GenerationType.AUTO a delegava ao SGBD.
@PrimaryGeneratedColumn()
id: number;
// equivalente a:
// @Version
// protected Long version;
//
// @VersionColumn() é O mecanismo nativo do TypeORM para o bloqueio otimista:
// o TypeORM incrementa automaticamente esta coluna a cada UPDATE e lança um erro
// ao tentar salvar uma entidade cuja versão não corresponde mais à do
// banco de dados (outra pessoa a alterou nesse meio tempo). Ela corresponde diretamente ao
// papel de @Version no JPA/Hibernate.
@VersionColumn()
version: number;
}
|
- linha 19: uma classe abstrata sem o decorador [@Entity]: ela não corresponde a nenhuma tabela, mas suas colunas são acrescentadas às das classes filhas;
- linhas 27–28: a chave primária, gerada pelo banco de dados;
- linhas 39–40: a versão da linha, incrementada pelo [TypeORM] a cada modificação (bloqueio otimista; veja o Exemplo 28).
11.8.2. src/entities/person.entity.ts
| // =========================================================================
// entities/person.entity.ts
// -------------------------------------------------------------------------
// Classe pai (ela mesma não persistida) das entidades [Doctor] e
// [Client]: um título, um sobrenome, um nome - e, novidade no banco de dados
// [dbrdvmedecins2], a conta de usuário associada (coluna [user]).
//
// Uma relação declarada em uma classe abstrata é herdada pelas
// classes filhas exatamente como as colunas: o TypeORM portanto adiciona a
// relação [user] à tabela [doctors] E à tabela [clients].
// =========================================================================
import { Column, JoinColumn, OneToOne, RelationId } from 'typeorm';
import { AbstractEntity } from './abstract.entity';
import { User } from './user.entity';
export abstract class Person extends AbstractEntity {
@Column({ length: 5 })
title: string; // Melle, Mme, Mr
@Column({ name: 'last_name', length: 20 })
lastName: string;
@Column({ name: 'first_name', length: 20 })
firstName: string;
// @OneToOne: um médico (ou um cliente) tem UMA conta de usuário, e uma
// conta de usuário pertence a no máximo UMA pessoa (a coluna [user]
// é declarada UNIQUE no script SQL).
// @JoinColumn({ name: 'user' }): é ESTA tabela (doctors / clients)
// que carrega a chave estrangeira, na coluna chamada [user].
// Como nas outras relações, [user] só é carregado sob demanda
// (opção `relations`) - veja doctor.repository.ts.
@OneToOne(() => User)
@JoinColumn({ name: 'user' })
user: User;
// o valor bruto da chave estrangeira, sem carregar o User completo
// (mesma técnica de Slot.doctorId, veja slot.entity.ts)
@RelationId((person: Person) => person.user)
userId: number;
}
|
- linha 17: a classe pai de [Doctor] e [Client], ela mesma filha de [AbstractEntity];
- Linhas 18–25: título, sobrenome, nome;
- linhas 34–36: um relacionamento um-para-um com a conta de usuário. [@JoinColumn] indica que esta tabela contém a chave estrangeira, na coluna [user]. O relacionamento só é carregado se for solicitado (opção [relations] nas consultas);
- Linhas 40–41: [@RelationId] expõe o valor da chave estrangeira (o identificador da conta) sem carregar a própria conta.
11.8.3. src/entities/doctor.entity.ts
| // =========================================================================
// entities/doctor.entity.ts
// -------------------------------------------------------------------------
// Equivalente da entidade JPA [Medecin] (um médico):
//
// @Entity
// @Table(name = "medecins")
// public class Medecin extends Personne { ... }
// =========================================================================
import { Entity, OneToMany, Unique } from 'typeorm';
import { Person } from './person.entity';
import { Slot } from './slot.entity';
// @Entity({ name: 'doctors' }): declara a classe como uma entidade TypeORM,
// persistida na tabela [doctors]. É o equivalente exato de
// @Entity + @Table(name = "doctors") no JPA.
@Entity({ name: 'doctors' })
// lembrete da restrição SQL do script database/dbrdvmedecins2.sql: dois
// médicos não podem ter o mesmo nome e sobrenome. Como para unq1_appointments
// (veja appointment.entity.ts), é documentação: com synchronize=false, é o
// script SQL que realmente cria a restrição - com ESTE nome, que a
// camada de negócio reconhece nas mensagens de erro do MySQL (veja business.service.ts).
@Unique('unq_doctors_first_name_last_name', ['firstName', 'lastName'])
export class Doctor extends Person {
// relação inversa (opcional, útil para navegar de um médico para os slots dele).
// O projeto original não a definia do lado de [Medecin] (apenas do lado de [Creneau]),
// mas o TypeORM torna sua adição quase gratuita e ela é útil didaticamente:
// mostra a relação "1 médico -> vários slots" nos dois sentidos.
@OneToMany(() => Slot, (slot) => slot.doctor)
slots: Slot[];
}
|
- linha 18: a classe corresponde à tabela [doctors];
- linha 24: a restrição de unicidade, incluída aqui para fins de documentação; ela é de fato criada pelo script SQL ([synchronize: false]);
- Linhas 30–31: o relacionamento um-para-muitos com os horários do médico, o inverso do relacionamento [@ManyToOne] de [Slot].
11.8.4. src/entities/client.entity.ts
| // =========================================================================
// entities/client.entity.ts
// -------------------------------------------------------------------------
// Equivalente da entidade JPA [Client]:
//
// @Entity
// @Table(name = "clients")
// public class Client extends Personne { ... }
//
// Atenção: [Client] aqui significa 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á para permanecer fiel ao documento de origem.
// =========================================================================
import { Entity, Unique } from 'typeorm';
import { Person } from './person.entity';
@Entity({ name: 'clients' })
// dois clientes não podem ter o mesmo nome e sobrenome
// (veja a mesma restrição em Doctor, doctor.entity.ts)
@Unique('unq_clients_first_name_last_name', ['firstName', 'lastName'])
export class Client extends Person {}
|
Um cliente (um paciente): um [Person] da tabela [clients], sem campos adicionais.
11.8.5. src/entities/slot.entity.ts
| // =========================================================================
// entities/slot.entity.ts
// -------------------------------------------------------------------------
// Equivalente da entidade JPA [Creneau] (um slot de horário):
//
// @Entity
// @Table(name = "creneaux")
// public class Creneau extends AbstractEntity {
// private int hdebut, mdebut, hfin, mfin;
// @ManyToOne(fetch = FetchType.LAZY)
// @JoinColumn(name = "id_medecin")
// private Medecin medecin;
// @Column(name = "id_medecin", insertable = false, updatable = false)
// private long idMedecin;
// }
// =========================================================================
import { Column, Entity, JoinColumn, ManyToOne, RelationId } from 'typeorm';
import { AbstractEntity } from './abstract.entity';
import { Doctor } from './doctor.entity';
@Entity({ name: 'slots' })
export class Slot extends AbstractEntity {
@Column({ name: 'start_hour' }) startHour: number; // hora de início do slot
@Column({ name: 'start_minute' }) startMinute: number; // minuto de início do slot
@Column({ name: 'end_hour' }) endHour: number; // hora de término do slot
@Column({ name: 'end_minute' }) endMinute: number; // minuto de término do slot
// equivalente a:
// @ManyToOne(fetch = FetchType.LAZY)
// @JoinColumn(name = "id_medecin")
// private Medecin medecin;
//
// @ManyToOne: vários slots para o mesmo médico.
// Por padrão, o TypeORM NÃO carrega a relação [doctor] ao ler um slot
// (comportamento "lazy" por padrão): ela deve ser pedida explicitamente, pela opção
// `relations: ['doctor']` de uma consulta - exatamente como FetchType.LAZY exigia
// no JPA um `left join fetch` explícito na consulta JPQL para trazer o médico de volta.
@ManyToOne(() => Doctor, (doctor) => doctor.slots)
@JoinColumn({ name: 'doctor_id' })
doctor: Doctor;
// equivalente a:
// @Column(name = "id_medecin", insertable = false, updatable = false)
// private long idMedecin;
//
// @RelationId: é o equivalente EXATO e idiomático no TypeORM do campo somente leitura
// "idMedecin" do projeto original. Ele expõe diretamente o valor
// da chave estrangeira, SEM precisar carregar a entidade [Doctor] completa.
// Muito útil para comparar identificadores sem carregar as entidades relacionadas.
@RelationId((slot: Slot) => slot.doctor)
doctorId: number;
}
|
- linhas 24–27: as horas e os minutos de início e de término;
- linhas 39–41: o relacionamento muitos-para-um com o médico: vários horários para um médico. A chave estrangeira é a coluna [doctor_id];
- linhas 51–52: o identificador do médico, sem carregar o médico.
11.8.6. src/entities/appointment.entity.ts
| // =========================================================================
// entities/appointment.entity.ts
// -------------------------------------------------------------------------
// Equivalente da entidade JPA [Rv] (uma consulta):
//
// @Entity
// @Table(name = "rv")
// public class Rv extends AbstractEntity {
// @Temporal(TemporalType.DATE) private Date jour;
// @ManyToOne(fetch = FetchType.LAZY) @JoinColumn(name = "id_client") private Client client;
// @ManyToOne(fetch = FetchType.LAZY) @JoinColumn(name = "id_creneau") private Creneau creneau;
// @Column(name = "id_client", insertable = false, updatable = false) private long idClient;
// @Column(name = "id_creneau", insertable = false, updatable = false) private long idCreneau;
// }
//
// A restrição SQL de unicidade em (day, slot_id) - que impede duas
// consultas no mesmo slot no mesmo dia - é definida diretamente
// no script database/dbrdvmedecins2.sql (CONSTRAINT unq1_appointments UNIQUE).
// =========================================================================
import { Column, Entity, JoinColumn, ManyToOne, RelationId, Unique } from 'typeorm';
import { AbstractEntity } from './abstract.entity';
import { Client } from './client.entity';
import { Slot } from './slot.entity';
@Entity({ name: 'appointments' })
// lembra, do lado do TypeORM, a restrição SQL do script do banco. Atenção: referenciamos aqui
// o nome da RELAÇÃO ('slot'), não o campo @RelationId ('slotId') - este último é
// uma coluna "virtual" (calculada), que o TypeORM não aceita em uma restrição @Unique.
// O próprio TypeORM traduz 'slot' para a sua coluna de chave estrangeira real (slot_id).
@Unique('unq1_appointments', ['day', 'slot'])
export class Appointment extends AbstractEntity {
// equivalente a: @Temporal(TemporalType.DATE) private Date jour;
// tipo 'date' (e não 'datetime'): só o dia é mantido, não a hora,
// exatamente como TemporalType.DATE especificava no lado JPA.
@Column({ type: 'date' })
day: string; // formato "yyyy-MM-dd", por exemplo "2026-09-13"
@ManyToOne(() => Client)
@JoinColumn({ name: 'client_id' })
client: Client;
@ManyToOne(() => Slot)
@JoinColumn({ name: 'slot_id' })
slot: Slot;
// equivalentes dos campos somente leitura idClient / idCreneau do projeto original
// (veja a explicação detalhada em slot.entity.ts sobre @RelationId)
@RelationId((appointment: Appointment) => appointment.client)
clientId: number;
@RelationId((appointment: Appointment) => appointment.slot)
slotId: number;
}
|
- linha 31: um horário de consulta é reservado apenas uma vez por dia;
- linhas 36–37: uma coluna do tipo [DATE], tratada como uma string [yyyy-mm-dd]: sem problemas de fuso horário, e duas datas são comparadas como strings;
- linhas 39–45: o cliente e o horário da consulta;
- linhas 49–53: seus identificadores.
11.8.7. src/entities/user.entity.ts
| // =========================================================================
// entities/user.entity.ts
// -------------------------------------------------------------------------
// Um usuário autorizado a fazer login na aplicação (tabela [users]).
//
// Novidade no banco de dados [dbrdvmedecins2]: cada médico e cada cliente
// agora tem a SUA PRÓPRIA conta de usuário (coluna [user] das
// tabelas [doctors] e [clients], veja person.entity.ts). Daí um terceiro papel:
// - ADMIN : o administrador - consultas + gerenciamento de médicos e clientes;
// - DOCTOR : um médico - marca e cancela consultas;
// - USER : um cliente (paciente) - marca para si mesmo, gerencia sua conta.
//
// Os papéis continuam mutuamente exclusivos: uma simples coluna [role]
// ainda basta (sem tabela [roles] / [users_roles] como no
// projeto Spring original).
// =========================================================================
import { Column, Entity, Unique } from 'typeorm';
import { AbstractEntity } from './abstract.entity';
export type Role = 'ADMIN' | 'DOCTOR' | 'USER';
@Entity({ name: 'users' })
// um login pertence a uma única conta (restrição SQL unq_users_login)
@Unique('unq_users_login', ['login'])
export class User extends AbstractEntity {
@Column({ length: 30 })
login: string;
// a senha com HASH (bcrypt) - nunca em texto claro
@Column({ length: 100 })
password: string;
// o nome exibido após o login - para um médico ou um cliente:
// "firstName LASTNAME" (por exemplo "Marie PELISSIER")
@Column({ length: 40 })
name: string;
@Column({ type: 'varchar', length: 10 })
role: Role;
}
|
- linha 21: um tipo união de strings: uma variável do tipo [Role] só pode ser uma destas três strings;
- linhas 31–32: o hash da senha;
- linhas 36–37: o nome exibido na barra de navegação (“Marie PELISSIER”);
- linhas 39–40: o papel. O tipo da coluna é especificado: o [TypeORM] não consegue inferir um tipo SQL a partir de um tipo união.
11.9. O domínio: o calendário
A pasta [domain] contém duas classes que não correspondem a nenhuma tabela: elas descrevem a agenda do médico em um único dia, tal como calculada pela camada de negócio.
11.9.1. src/domain/doctor-day-slot.ts
| // =========================================================================
// domain/doctor-day-slot.ts
// -------------------------------------------------------------------------
// Equivalente da classe [CreneauMedecinJour] do projeto Spring original:
// uma entidade "de negócio" (não persistida no banco de dados) que liga um slot
// de horário à consulta eventualmente marcada nesse slot.
//
// public class CreneauMedecinJour implements Serializable {
// private Creneau creneau;
// private Rv rv; // null se o slot estiver livre
// }
//
// Esse tipo de classe não tem tabela no banco de dados: ela só existe durante
// o cálculo da agenda de um médico, que a camada web então transforma
// em linhas da tabela HTML da agenda (veja schedule.controller.ts).
// =========================================================================
import { Slot } from '../entities/slot.entity';
import { Appointment } from '../entities/appointment.entity';
export class DoctorDaySlot {
constructor(
public slot: Slot,
public appointment: Appointment | null, // null se o slot estiver livre nesse dia
) {}
}
|
linhas 22–25: um horário e a consulta marcada para esse horário nesse dia ([null] se o horário estiver disponível). A sintaxe [public slot: Slot] nos parâmetros de um construtor declara e inicializa o campo em um único passo.
11.9.2. src/domain/doctor-day-schedule.ts
| // =========================================================================
// domain/doctor-day-schedule.ts
// -------------------------------------------------------------------------
// Equivalente da classe [AgendaMedecinJour] do projeto Spring original:
// a agenda completa de um médico em um determinado dia, isto é, a lista dos
// slots de horário do médico, cada um livre ou ocupado por uma consulta.
//
// public class AgendaMedecinJour implements Serializable {
// private Medecin medecin;
// private Date jour;
// private CreneauMedecinJour[] creneauxMedecinJour;
// }
// =========================================================================
import { Doctor } from '../entities/doctor.entity';
import { DoctorDaySlot } from './doctor-day-slot';
export class DoctorDaySchedule {
constructor(
public doctor: Doctor,
public day: string, // formato "yyyy-MM-dd"
public doctorDaySlots: DoctorDaySlot[],
) {}
}
|
A agenda: um médico, um dia e a lista de seus horários, disponíveis ou reservados.
11.10. A camada DAO
Uma classe por tabela. Todas seguem o modelo do Exemplo 28: um [Repository] [TypeORM] injetado, um método [repo(manager)] que seleciona o repositório da transação corrente e métodos curtos, sem lógica de negócio.
11.10.1. src/repositories/doctor.repository.ts
| // =========================================================================
// repositories/doctor.repository.ts
// -------------------------------------------------------------------------
// Camada DAO da entidade [Doctor]. Em comparação com o servidor JSON, três
// novidades, todas relacionadas ao gerenciamento de médicos pelo ADMIN:
// - as leituras também trazem a conta de usuário associada (relação
// [user]), para exibir o login na lista de médicos;
// - save() / deleteById(): criação, atualização, exclusão;
// - cada método de escrita aceita um EntityManager OPCIONAL: quando
// a camada de negócio o fornece, a operação executa DENTRO da transação
// dessa camada (veja business.service.ts, dataSource.transaction(...)).
// =========================================================================
import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { EntityManager, Repository } from 'typeorm';
import { Doctor } from '../entities/doctor.entity';
@Injectable()
export class DoctorRepository {
constructor(
@InjectRepository(Doctor)
private readonly repository: Repository<Doctor>,
) {}
// o Repository a usar: o da transação atual se houver
// uma, o Repository "comum" caso contrário.
private repo(manager?: EntityManager): Repository<Doctor> {
return manager ? manager.getRepository(Doctor) : this.repository;
}
// lista ordenada por sobrenome e depois por nome, conta de usuário incluída
findAll(): Promise<Doctor[]> {
return this.repository.find({ relations: { user: true }, order: { lastName: 'ASC', firstName: 'ASC' } });
}
findById(id: number, manager?: EntityManager): Promise<Doctor | null> {
return this.repo(manager).findOne({ where: { id }, relations: { user: true } });
}
// a pessoa com 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 SQL de unicidade.
findByFirstNameLastName(firstName: string, lastName: string, manager?: EntityManager): Promise<Doctor | null> {
return this.repo(manager).findOneBy({ firstName, lastName });
}
save(doctor: Doctor, manager?: EntityManager): Promise<Doctor> {
return this.repo(manager).save(doctor);
}
async deleteById(id: number, manager?: EntityManager): Promise<void> {
await this.repo(manager).delete(id);
}
}
|
- linhas 28–30: dentro de uma transação, o repositório da transação corrente ([manager]);
- linhas 33–35: todos os médicos, junto com sua conta ([relations: { user: true }]), ordenados por sobrenome e depois por nome. A conta é usada para exibir o login na lista de médicos;
- linhas 45–47: eventuais homônimos. A comparação é feita pelo [MySQL], de acordo com a collation do banco de dados;
- linhas 49–51 e 53–55: operações de gravação e exclusão.
11.10.2. src/repositories/client.repository.ts
| // =========================================================================
// repositories/client.repository.ts
// -------------------------------------------------------------------------
// Camada DAO da entidade [Client] (um PACIENTE do consultório). Estritamente
// o mesmo princípio de doctor.repository.ts (veja seus comentários).
// =========================================================================
import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { EntityManager, Repository } from 'typeorm';
import { Client } from '../entities/client.entity';
@Injectable()
export class ClientRepository {
constructor(
@InjectRepository(Client)
private readonly repository: Repository<Client>,
) {}
private repo(manager?: EntityManager): Repository<Client> {
return manager ? manager.getRepository(Client) : this.repository;
}
findAll(): Promise<Client[]> {
return this.repository.find({ relations: { user: true }, order: { lastName: 'ASC', firstName: 'ASC' } });
}
findById(id: number, manager?: EntityManager): Promise<Client | null> {
return this.repo(manager).findOne({ where: { id }, relations: { user: true } });
}
// o cliente (paciente) cuja conta de usuário é [userId], ou null.
// where: { user: { id } }: o TypeORM traduz este filtro sobre a relação em
// um simples "WHERE clients.user = ?" (sem necessidade de join)
findByUserId(userId: number): Promise<Client | null> {
return this.repository.findOne({ where: { user: { id: userId } }, relations: { user: true } });
}
// lê um cliente aplicando um BLOQUEIO na sua linha até o fim da
// transação atual (SELECT ... FOR UPDATE). Uma segunda transação que
// peça o mesmo bloqueio ESPERA até que a primeira termine.
// Usado ao marcar uma consulta (veja BusinessService.addAppointment): duas
// marcações simultâneas para o mesmo paciente são assim processadas uma
// DEPOIS da outra, e a segunda vê a consulta criada pela primeira.
lock(id: number, manager: EntityManager): Promise<Client | null> {
return manager.getRepository(Client).findOne({ where: { id }, lock: { mode: 'pessimistic_write' } });
}
// a pessoa com 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 SQL de unicidade.
findByFirstNameLastName(firstName: string, lastName: string, manager?: EntityManager): Promise<Client | null> {
return this.repo(manager).findOneBy({ firstName, lastName });
}
save(client: Client, manager?: EntityManager): Promise<Client> {
return this.repo(manager).save(client);
}
async deleteById(id: number, manager?: EntityManager): Promise<void> {
await this.repo(manager).delete(id);
}
}
|
Os mesmos métodos que para os médicos, mais dois:
- linhas 35–37: o cliente cuja conta é a indicada: é assim que um paciente logado (cujo token contém o identificador de sua conta) obtém seu registro de cliente. O [TypeORM] traduz o filtro [where: { user: { id: userId } }] em [WHERE clients.user = ?];
- linhas 45–47: uma leitura com um bloqueio ([lock: { mode: 'pessimistic_write' }], ou seja, [SELECT ... FOR UPDATE] em SQL). Até o fim da transação, qualquer outra transação que solicite o mesmo bloqueio espera. O módulo de agendamento de consultas usa isso para processar, uma após a outra, duas reservas simultâneas para o mesmo paciente.
11.10.3. src/repositories/slot.repository.ts
| // =========================================================================
// repositories/slot.repository.ts
// -------------------------------------------------------------------------
// Camada DAO da entidade [Slot]. Novo: deleteByDoctor(), usado
// quando um médico é excluído (os slots de horário do médico desaparecem
// junto com o médico - veja BusinessService.deleteDoctor).
// =========================================================================
import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { EntityManager, Repository } from 'typeorm';
import { Slot } from '../entities/slot.entity';
@Injectable()
export class SlotRepository {
constructor(
@InjectRepository(Slot)
private readonly repository: Repository<Slot>,
) {}
findById(id: number): Promise<Slot | null> {
return this.repository.findOne({ where: { id }, relations: { doctor: true } });
}
// os slots de um médico, em ordem cronológica
// (mesma consulta do servidor JSON - veja seus comentários)
getAllSlots(doctorId: number): Promise<Slot[]> {
return this.repository
.createQueryBuilder('s')
.where('s.doctor = :doctorId', { doctorId })
.orderBy('s.startHour', 'ASC')
.addOrderBy('s.startMinute', 'ASC')
.getMany();
}
// exclui todos os slots de um médico. delete({ doctor: { id } })
// gera: DELETE FROM slots WHERE doctor_id = ?
async deleteByDoctor(doctorId: number, manager?: EntityManager): Promise<void> {
const repo = manager ? manager.getRepository(Slot) : this.repository;
await repo.delete({ doctor: { id: doctorId } });
}
}
|
- Linhas 27–34: os horários de um médico, em ordem cronológica. A consulta é escrita com o QueryBuilder do [TypeORM], que constrói uma consulta SQL método a método: [createQueryBuilder('s')] (a tabela, com o alias [s]), [where] (com um parâmetro chamado [:doctorId], nunca uma concatenação de strings, que abriria a porta para injeções de SQL), [orderBy], depois [getMany], que executa a consulta;
- linhas 38–41: exclusão dos horários de um médico, usada quando esse médico é removido.
11.10.4. src/repositories/appointment.repository.ts
| // =========================================================================
// repositories/appointment.repository.ts
// -------------------------------------------------------------------------
// Camada DAO da entidade [Appointment]. Novidades:
// - o número de consultas de um médico, para RECUSAR a exclusão
// de um médico que ainda tem consultas (veja BusinessService);
// - as PRÓXIMAS consultas de um cliente (página "Minha área" do paciente, e
// regra "apenas uma próxima consulta por paciente");
// - a exclusão de todas as consultas de um cliente (um cliente é
// excluído junto com suas consultas, pelo ADMIN ou por ele mesmo).
// =========================================================================
import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { EntityManager, Repository } from 'typeorm';
import { Appointment } from '../entities/appointment.entity';
@Injectable()
export class AppointmentRepository {
constructor(
@InjectRepository(Appointment)
private readonly repository: Repository<Appointment>,
) {}
private repo(manager?: EntityManager): Repository<Appointment> {
return manager ? manager.getRepository(Appointment) : this.repository;
}
findById(id: number): Promise<Appointment | null> {
return this.repository.findOne({ where: { id }, relations: { client: true, slot: true } });
}
save(appointment: Appointment, manager?: EntityManager): Promise<Appointment> {
return this.repo(manager).save(appointment);
}
async deleteById(id: number): Promise<void> {
await this.repository.delete(id);
}
// as consultas de um médico em um determinado dia, cliente e slot incluídos
// (mesma consulta do servidor JSON - veja seus comentários)
getDoctorDayAppointments(doctorId: number, day: string): Promise<Appointment[]> {
return this.repository
.createQueryBuilder('appointment')
.leftJoinAndSelect('appointment.client', 'client')
.leftJoinAndSelect('appointment.slot', 'slot')
.where('slot.doctor = :doctorId', { doctorId })
.andWhere('appointment.day = :day', { day })
.getMany();
}
// as consultas de um cliente a partir do dia [from] (inclusive), em
// ordem cronológica, com o slot E o médico desse slot
// (innerJoinAndSelect em cascata: consulta -> slot -> médico)
findUpcomingByClient(clientId: number, from: string): Promise<Appointment[]> {
return this.repository
.createQueryBuilder('appointment')
.innerJoinAndSelect('appointment.slot', 'slot')
.innerJoinAndSelect('slot.doctor', 'doctor')
.where('appointment.client = :clientId', { clientId })
.andWhere('appointment.day >= :from', { from })
.orderBy('appointment.day', 'ASC')
.addOrderBy('slot.startHour', 'ASC')
.addOrderBy('slot.startMinute', 'ASC')
.getMany();
}
// número de consultas de um cliente a partir do dia [from] (inclusive)
countUpcomingByClient(clientId: number, from: string, manager?: EntityManager): Promise<number> {
return this.repo(manager)
.createQueryBuilder('appointment')
.where('appointment.client = :clientId', { clientId })
.andWhere('appointment.day >= :from', { from })
.getCount();
}
// exclui TODAS as consultas (passadas e futuras) de um cliente:
// DELETE FROM appointments WHERE client_id = ?
async deleteByClient(clientId: number, manager?: EntityManager): Promise<void> {
await this.repo(manager).delete({ client: { id: clientId } });
}
// número de consultas (passadas ou futuras) de um médico - é preciso passar
// pelos slots do médico, pois [appointments] não referencia [doctors] diretamente:
// SELECT COUNT(*) FROM appointments INNER JOIN slots s ON ... WHERE s.doctor_id = ?
countByDoctor(doctorId: number, manager?: EntityManager): Promise<number> {
return this.repo(manager)
.createQueryBuilder('appointment')
.innerJoin('appointment.slot', 'slot')
.where('slot.doctor = :doctorId', { doctorId })
.getCount();
}
}
|
- linhas 43–51: as consultas de um médico em um determinado dia. [leftJoinAndSelect] faz uma junção e carrega a entidade associada: cada consulta é obtida junto com seu paciente e seu horário;
- linhas 56–67: as consultas de um cliente a partir de um determinado dia, com seu horário e o médico responsável por esse horário (duas junções em cascata): é isso que é exibido em “My area”;
- linhas 70–76: sua contagem, para a regra de “apenas uma consulta futura”;
- linhas 80–82: a exclusão de todas as consultas de um cliente;
- linhas 87–93: o número de consultas de um médico. A tabela [appointments] não referencia diretamente os médicos: é preciso passar pelos horários ([innerJoin], uma junção sem carregamento).
11.10.5. src/repositories/user.repository.ts
| // =========================================================================
// repositories/user.repository.ts
// -------------------------------------------------------------------------
// Camada DAO da entidade [User]. Novo: save() / deleteById(), porque
// criar (ou excluir) um médico ou um cliente também cria (ou exclui) a
// conta de usuário - veja BusinessService.
// =========================================================================
import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { EntityManager, Repository } from 'typeorm';
import { User } from '../entities/user.entity';
@Injectable()
export class UserRepository {
constructor(
@InjectRepository(User)
private readonly repository: Repository<User>,
) {}
private repo(manager?: EntityManager): Repository<User> {
return manager ? manager.getRepository(User) : this.repository;
}
// retorna null se nenhum usuário tiver este login
findByLogin(login: string, manager?: EntityManager): Promise<User | null> {
return this.repo(manager).findOneBy({ login });
}
save(user: User, manager?: EntityManager): Promise<User> {
return this.repo(manager).save(user);
}
async deleteById(id: number, manager?: EntityManager): Promise<void> {
await this.repo(manager).delete(id);
}
}
|
Linhas 26–28: a conta de um login, usada para fazer login e para verificar se um login está disponível.
11.11. A camada de negócio
11.11.1. src/business/dates.ts
| // =========================================================================
// business/dates.ts
// -------------------------------------------------------------------------
// A data de hoje no formato "yyyy-MM-dd" (o da coluna appointments.day).
// É usada por REGRAS DE NEGÓCIO (sem marcação no passado, apenas uma
// PRÓXIMA consulta por paciente): ela portanto fica na camada de
// negócio. A camada web a reutiliza (veja web/helpers/dates.helper.ts).
//
// Duas datas "yyyy-MM-dd" podem ser comparadas diretamente como strings:
// "2026-09-23" < "2026-10-01" - a ordem alfabética é a ordem cronológica.
// =========================================================================
// a data de hoje, no fuso horário do servidor
export function today(): string {
const d = new Date();
const twoDigits = (n: number) => n.toString().padStart(2, '0');
return `${d.getFullYear()}-${twoDigits(d.getMonth() + 1)}-${twoDigits(d.getDate())}`;
}
|
Linhas 14–18: a data de hoje no formato [yyyy-mm-dd]; a data na coluna [appointments.day]. [padStart(2, '0')] serve para completar um número de um dígito com zero à esquerda (9 vira [09]). Nesse formato, a ordem alfabética é a ordem cronológica: duas datas são comparadas com [<].
11.11.2. src/business/business.exception.ts
| // =========================================================================
// business/business.exception.ts
// -------------------------------------------------------------------------
// A exceção lançada pela camada de negócio quando uma REGRA DE NEGÓCIO é
// violada (login já usado, médico que ainda tem consultas, slot
// já ocupado...). Ela não carrega um texto, mas uma CHAVE de tradução
// (por exemplo '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).
//
// A camada de negócio assim permanece independente do idioma da interface -
// como já era independente do formato de saída (JSON ou HTML).
// =========================================================================
export class BusinessException extends Error {
constructor(
public readonly key: string, // chave de tradução da mensagem
public readonly params: Record<string, string> = {}, // parâmetros opcionais da mensagem
) {
super(key);
this.name = 'BusinessException';
}
}
|
- linha 17: uma [BusinessException] não carrega uma mensagem, mas uma chave de tradução ([ERRORS.LOGIN_TAKEN]). A camada de negócio ignora, assim, o idioma da interface: a view traduzirá a chave (veja o Capítulo 5);
- linha 18: os eventuais parâmetros da mensagem;
- linha 21: o nome da exceção, exibido nos logs de erro.
11.11.3. src/business/business.interface.ts
| // =========================================================================
// business/business.interface.ts
// -------------------------------------------------------------------------
// O contrato da camada de negócio. Aos 11 métodos do servidor JSON (leitura de
// listas, agenda, inclusão/exclusão de consulta) somam-se 2
// métodos para a área do paciente e 6 métodos para gerenciar médicos
// e clientes.
// =========================================================================
import { Client } from '../entities/client.entity';
import { Slot } from '../entities/slot.entity';
import { Doctor } from '../entities/doctor.entity';
import { Appointment } from '../entities/appointment.entity';
import { DoctorDaySchedule } from '../domain/doctor-day-schedule';
// os dados informados no formulário de "médico" ou de "cliente"
export interface PersonData {
title: string; // Mr, Mme, Melle
lastName: string;
firstName: string;
// criação: opcional, padrão é o sobrenome em minúsculas
// atualização: opcional, o login permanece inalterado se ausente
login?: string;
// criação: opcional, padrão é o login
// atualização: opcional, a senha permanece inalterada se ausente
password?: string;
// atualização: a versão do registro quando o formulário foi
// exibido (bloqueio otimista, veja AbstractEntity.version)
version?: number;
}
export interface IBusiness {
// ────────────────────────────────────────── leituras (inalteradas)
getAllClients(): Promise<Client[]>;
getAllDoctors(): Promise<Doctor[]>;
getAllSlots(doctorId: number): Promise<Slot[]>;
getDoctorDayAppointments(doctorId: number, day: string): Promise<Appointment[]>;
getClientById(id: number): Promise<Client | null>;
getDoctorById(id: number): Promise<Doctor | null>;
getAppointmentById(id: number): Promise<Appointment | null>;
getSlotById(id: number): Promise<Slot | null>;
getDoctorDaySchedule(doctorId: number, day: string): Promise<DoctorDaySchedule | null>;
/** o cliente (paciente) cuja conta de usuário é [userId], ou null */
getClientByUserId(userId: number): Promise<Client | null>;
/** as consultas de um cliente, hoje ou no futuro, com slot e médico */
getClientUpcomingAppointments(clientId: number): Promise<Appointment[]>;
// ────────────────────────────────────────── consultas (ADMIN, DOCTOR, USER)
/**
* lança uma BusinessException se:
* - o dia está no passado ('ERRORS.PAST_DATE');
* - o paciente já tem uma consulta futura ('ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT');
* - o horário já está ocupado naquele dia ('ERRORS.SLOT_ALREADY_BOOKED').
*/
addAppointment(day: string, slot: Slot, client: Client): Promise<Appointment>;
deleteAppointment(appointment: Appointment): Promise<void>;
// ────────────────────────────────────────── médicos (ADMIN)
/** cria o médico E a conta de usuário dele (papel DOCTOR) */
addDoctor(data: PersonData): Promise<Doctor>;
/** atualiza o médico E a conta de usuário dele */
editDoctor(id: number, data: PersonData): Promise<Doctor>;
/** exclui o médico, os slots E a conta - recusado se houver consultas */
deleteDoctor(id: number): Promise<void>;
// ────────────────────────────────────────── clientes
// (o ADMIN; addClient também é usado para o cadastro de um paciente,
// editClient e deleteClient pelo paciente para a própria conta)
/** cria o cliente E a conta de usuário dele (papel USER) */
addClient(data: PersonData): Promise<Client>;
editClient(id: number, data: PersonData): Promise<Client>;
/**
* exclui o cliente, a conta E todas as consultas (passadas e futuras).
* Usado pelo ADMIN (página "Clients") e pelo próprio paciente
* ("Manage my account").
*/
deleteClient(id: number): Promise<void>;
}
export const BUSINESS_TOKEN = 'IBusiness';
|
- linhas 17–30: os dados de um médico ou cliente a ser criado ou modificado. Nome de usuário e senha são opcionais: na criação, o padrão é o nome em minúsculas; na modificação, só mudam se tiverem sido informados;
- linhas 32–78: o contrato da camada de negócio, ou seja, o que as outras camadas podem solicitar a ela. Os comentários [/** ... */] são comentários de documentação, exibidos pelo [VS Code] quando você passa o mouse sobre o método;
- linha 80: o token sob o qual a implementação é registrada em [app.module.ts]. Uma interface [TypeScript] desaparece na compilação: ela não pode ser usada para injeção de dependência. Por isso, a injeção é feita com esse token: [@Inject(BUSINESS_TOKEN)].
11.11.4. src/business/business.service.ts
| // =========================================================================
// business/business.service.ts
// -------------------------------------------------------------------------
// Implementação da camada de negócio.
//
// As leituras e a agenda são tiradas tal como estão do servidor JSON. A
// novidade é o gerenciamento de médicos e clientes, que obedece a três
// regras de negócio:
//
// 1. uma pessoa (médico ou cliente) e sua conta de usuário vão SEMPRE
// juntas: são criadas, atualizadas e excluídas juntas, em
// uma única 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 (os pacientes
// do médico perderiam a consulta sem serem avisados): elas
// devem ser canceladas antes. Os slots de horário do médico também desaparecem;
// - 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 a marcação de 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 próxima consulta por vez.
//
// Médicos e clientes seguem exatamente as mesmas regras: o código comum
// é escrito UMA vez (métodos privados xxxPerson), e parametrizado por um
// pequeno "descritor" que diz com que tipo de pessoa estamos lidando.
// =========================================================================
import { Injectable } from '@nestjs/common';
import { DataSource, EntityManager, QueryFailedError } from 'typeorm';
import * as bcrypt from 'bcryptjs';
import { PersonData, IBusiness } from './business.interface';
import { BusinessException } from './business.exception';
import { DoctorRepository } from '../repositories/doctor.repository';
import { ClientRepository } from '../repositories/client.repository';
import { SlotRepository } from '../repositories/slot.repository';
import { AppointmentRepository } from '../repositories/appointment.repository';
import { UserRepository } from '../repositories/user.repository';
import { Client } from '../entities/client.entity';
import { Slot } from '../entities/slot.entity';
import { Doctor } from '../entities/doctor.entity';
import { Person } from '../entities/person.entity';
import { Appointment } from '../entities/appointment.entity';
import { Role, User } from '../entities/user.entity';
import { DoctorDaySchedule } from '../domain/doctor-day-schedule';
import { DoctorDaySlot } from '../domain/doctor-day-slot';
import { today } from './dates';
// número de salt rounds do bcrypt - o mesmo do script SQL ($2b$10$...)
const BCRYPT_ROUNDS = 10;
// o que os dois DAOs DoctorRepository e ClientRepository têm em comum
// (o TypeScript verifica a compatibilidade pela FORMA dos objetos: as duas
// classes satisfazem esta interface sem precisar declará-la)
interface PersonDao<T extends Person> {
findById(id: number, manager?: EntityManager): Promise<T | null>;
findByFirstNameLastName(firstName: string, lastName: string, manager?: EntityManager): Promise<T | null>;
save(person: T, manager?: EntityManager): Promise<T>;
deleteById(id: number, manager?: EntityManager): Promise<void>;
}
// tudo o que distingue um médico de um cliente para as regras de negócio
interface PersonDescriptor<T extends Person> {
dao: PersonDao<T>;
create: () => T; // new Doctor() ou new Client()
role: Role; // DOCTOR ou USER
notFoundKey: string; // mensagem se a pessoa não existir
alreadyExistsKey: string; // mensagem se já existir o mesmo nome e sobrenome
// opcional: se presente, a exclusão é RECUSADA enquanto a pessoa
// tiver consultas (countAppointments > 0), com a mensagem hasAppointmentsKey
countAppointments?: (id: number, manager: EntityManager) => Promise<number>;
hasAppointmentsKey?: string;
// opcional: o que deve ser excluído ANTES da pessoa (as linhas que
// referenciam a pessoa por uma chave estrangeira)
beforeDelete?: (id: number, manager: EntityManager) => Promise<void>;
}
@Injectable()
export class BusinessService implements IBusiness {
private readonly doctorDescriptor: PersonDescriptor<Doctor>;
private readonly clientDescriptor: PersonDescriptor<Client>;
constructor(
// DataSource: a própria conexão TypeORM, fornecida por
// TypeOrmModule.forRoot(...). Nós a usamos APENAS para abrir
// transações (dataSource.transaction(...)) - as consultas, por outro lado,
// permanecem na camada DAO.
private readonly dataSource: DataSource,
private readonly doctorRepository: DoctorRepository,
private readonly clientRepository: ClientRepository,
private readonly slotRepository: SlotRepository,
private readonly appointmentRepository: AppointmentRepository,
private readonly userRepository: UserRepository,
) {
this.doctorDescriptor = {
dao: doctorRepository,
create: () => new Doctor(),
role: 'DOCTOR',
notFoundKey: 'ERRORS.DOCTOR_NOT_FOUND',
alreadyExistsKey: 'ERRORS.DOCTOR_ALREADY_EXISTS',
countAppointments: (id, manager) => appointmentRepository.countByDoctor(id, manager),
hasAppointmentsKey: 'ERRORS.DOCTOR_HAS_APPOINTMENTS',
// um médico sem consultas ainda pode ter slots de horário:
// eles não fazem sentido sem o médico, e também são excluídos (caso contrário
// a chave estrangeira slots.doctor_id proibiria a exclusão).
beforeDelete: (id, manager) => slotRepository.deleteByDoctor(id, manager),
};
this.clientDescriptor = {
dao: clientRepository,
create: () => new Client(),
role: 'USER',
notFoundKey: 'ERRORS.PATIENT_NOT_FOUND',
alreadyExistsKey: 'ERRORS.PATIENT_ALREADY_EXISTS',
// sem countAppointments: a exclusão de um cliente nunca é recusada;
// suas consultas (passadas e futuras) são excluídas com ele (caso contrário
// a chave estrangeira appointments.client_id proibiria a exclusão)
beforeDelete: (id, manager) => appointmentRepository.deleteByClient(id, manager),
};
}
// =======================================================================
// leituras - inalteradas em relação ao servidor JSON
// =======================================================================
getAllClients(): Promise<Client[]> {
return this.clientRepository.findAll();
}
getAllDoctors(): Promise<Doctor[]> {
return this.doctorRepository.findAll();
}
getAllSlots(doctorId: number): Promise<Slot[]> {
return this.slotRepository.getAllSlots(doctorId);
}
getDoctorDayAppointments(doctorId: number, day: string): Promise<Appointment[]> {
return this.appointmentRepository.getDoctorDayAppointments(doctorId, day);
}
getClientById(id: number): Promise<Client | null> {
return this.clientRepository.findById(id);
}
getDoctorById(id: number): Promise<Doctor | null> {
return this.doctorRepository.findById(id);
}
getAppointmentById(id: number): Promise<Appointment | null> {
return this.appointmentRepository.findById(id);
}
getSlotById(id: number): Promise<Slot | null> {
return this.slotRepository.findById(id);
}
getClientByUserId(userId: number): Promise<Client | null> {
return this.clientRepository.findByUserId(userId);
}
getClientUpcomingAppointments(clientId: number): Promise<Appointment[]> {
return this.appointmentRepository.findUpcomingByClient(clientId, today());
}
// mesmo algoritmo do servidor JSON (e do projeto Spring original)
async getDoctorDaySchedule(doctorId: number, day: string): Promise<DoctorDaySchedule | null> {
const doctor = await this.getDoctorById(doctorId);
if (doctor === null) {
return null;
}
const timeSlots = await this.getAllSlots(doctorId);
const bookings = await this.getDoctorDayAppointments(doctorId, day);
const bookingsBySlot = new Map<number, Appointment>();
for (const booking of bookings) {
bookingsBySlot.set(booking.slotId, booking);
}
const doctorDaySlots = timeSlots.map(
(slot) => new DoctorDaySlot(slot, bookingsBySlot.get(slot.id) ?? null),
);
return new DoctorDaySchedule(doctor, day, doctorDaySlots);
}
// =======================================================================
// 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 slots no mesmo instante (duas abas,
// clique duplo...), a segunda transação espera o fim da
// primeira - e então vê a consulta que ela acabou de criar;
// 3. apenas uma próxima consulta por paciente;
// 4. por fim, a inserção. Se o slot acabou de ser ocupado por OUTRO
// paciente, é a restrição SQL unq1_appointments (day, slot_id) que
// recusa a inserção - traduzida em uma BusinessException por transaction().
// -----------------------------------------------------------------------
addAppointment(day: string, slot: Slot, client: Client): Promise<Appointment> {
return this.transaction(async (manager) => {
const todayDate = today();
if (day < todayDate) {
throw new BusinessException('ERRORS.PAST_DATE');
}
if ((await this.clientRepository.lock(client.id, manager)) === null) {
throw new BusinessException('ERRORS.PATIENT_NOT_FOUND');
}
if ((await this.appointmentRepository.countUpcomingByClient(client.id, todayDate, manager)) > 0) {
throw new BusinessException('ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT');
}
const appointment = new Appointment();
appointment.day = day;
appointment.slot = slot;
appointment.client = client;
return this.appointmentRepository.save(appointment, manager);
});
}
async deleteAppointment(appointment: Appointment): Promise<void> {
await this.appointmentRepository.deleteById(appointment.id);
}
// =======================================================================
// médicos e clientes - os métodos públicos delegam aos métodos
// privados comuns, com o descritor adequado
// =======================================================================
addDoctor(data: PersonData): Promise<Doctor> {
return this.addPerson(this.doctorDescriptor, data);
}
editDoctor(id: number, data: PersonData): Promise<Doctor> {
return this.editPerson(this.doctorDescriptor, id, data);
}
deleteDoctor(id: number): Promise<void> {
return this.deletePerson(this.doctorDescriptor, id);
}
addClient(data: PersonData): Promise<Client> {
return this.addPerson(this.clientDescriptor, data);
}
editClient(id: number, data: PersonData): Promise<Client> {
return this.editPerson(this.clientDescriptor, id, data);
}
// o cliente, a conta E todas as consultas (ADMIN, ou o próprio paciente
// em "Gerenciar minha conta": mesmo método, mesma regra)
deleteClient(id: number): Promise<void> {
return this.deletePerson(this.clientDescriptor, id);
}
// -----------------------------------------------------------------------
// criação: primeiro a conta de usuário (a pessoa a referencia),
// depois a pessoa - tudo em UMA transação.
// -----------------------------------------------------------------------
private addPerson<T extends Person>(d: PersonDescriptor<T>, data: PersonData): Promise<T> {
const lastName = data.lastName.trim().toUpperCase();
const firstName = data.firstName.trim();
// as regras do banco de dados dbrdvmedecins2: login = sobrenome em minúsculas,
// senha = login - a menos que o ADMIN informe outros valores
const login = (data.login || lastName).toLowerCase();
const password = data.password || login;
return this.transaction(async (manager) => {
await this.checkPersonUnique(d, firstName, lastName, null, manager);
await this.checkLoginFree(login, manager);
const user = new User();
user.login = login;
user.password = await bcrypt.hash(password, BCRYPT_ROUNDS);
user.name = `${firstName} ${lastName}`;
user.role = d.role;
await this.userRepository.save(user, manager);
const person = d.create();
person.title = data.title;
person.lastName = lastName;
person.firstName = firstName;
person.user = user;
return d.dao.save(person, manager);
});
}
// -----------------------------------------------------------------------
// atualização: a pessoa E a conta (o nome exibido "firstName LASTNAME"
// deve acompanhar; o login e a senha só mudam se tiverem sido
// informados).
// -----------------------------------------------------------------------
private editPerson<T extends Person>(
d: PersonDescriptor<T>,
id: number,
data: PersonData,
): Promise<T> {
return this.transaction(async (manager) => {
const person = await d.dao.findById(id, manager);
if (person === null) {
throw new BusinessException(d.notFoundKey);
}
// bloqueio otimista: se a versão no banco de dados não é mais a do
// formulário, alguém alterou este registro nesse meio tempo - recusamos
// em vez de sobrescrever silenciosamente as alterações dessa pessoa.
if (data.version !== undefined && data.version !== person.version) {
throw new BusinessException('ERRORS.CONCURRENT_UPDATE');
}
person.title = data.title;
person.lastName = data.lastName.trim().toUpperCase();
person.firstName = data.firstName.trim();
await this.checkPersonUnique(d, person.firstName, person.lastName, id, manager);
const user = person.user;
user.name = `${person.firstName} ${person.lastName}`;
if (data.login && data.login.toLowerCase() !== user.login) {
const login = data.login.toLowerCase();
await this.checkLoginFree(login, manager);
user.login = login;
}
if (data.password) {
user.password = await bcrypt.hash(data.password, BCRYPT_ROUNDS);
}
await this.userRepository.save(user, manager);
return d.dao.save(person, manager);
});
}
// -----------------------------------------------------------------------
// exclusão, em UMA transação, na ordem imposta pelas chaves
// estrangeiras:
// 1. eventual recusa se ainda houver consultas (médico);
// 2. o que referencia a pessoa (slots de um médico, consultas
// de um cliente);
// 3. a pessoa (ela referencia a conta);
// 4. a conta.
// -----------------------------------------------------------------------
private deletePerson<T extends Person>(d: PersonDescriptor<T>, id: number): Promise<void> {
return this.transaction(async (manager) => {
const person = await d.dao.findById(id, manager);
if (person === null) {
throw new BusinessException(d.notFoundKey);
}
if (d.countAppointments && (await d.countAppointments(id, manager)) > 0) {
throw new BusinessException(d.hasAppointmentsKey ?? 'ERRORS.INVALID_FORM');
}
if (d.beforeDelete) {
await d.beforeDelete(id, manager);
}
await d.dao.deleteById(id, manager);
await this.userRepository.deleteById(person.userId, manager);
});
}
// recusa um 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 async checkPersonUnique<T extends Person>(
d: PersonDescriptor<T>,
firstName: string,
lastName: string,
currentId: number | null,
manager: EntityManager,
): Promise<void> {
const namesake = await d.dao.findByFirstNameLastName(firstName, lastName, manager);
if (namesake !== null && namesake.id !== currentId) {
throw new BusinessException(d.alreadyExistsKey);
}
}
private async checkLoginFree(login: string, manager: EntityManager): Promise<void> {
if ((await this.userRepository.findByLogin(login, manager)) !== null) {
throw new BusinessException('ERRORS.LOGIN_TAKEN');
}
}
// -----------------------------------------------------------------------
// executa [work] em uma transação: dataSource.transaction() faz
// START TRANSACTION, chama [work] com um EntityManager vinculado a esta
// transação, depois COMMIT se tudo correu bem - ou ROLLBACK se uma
// exceção foi lançada (BusinessException incluída).
//
// As verificações de "login livre" e de "nome + sobrenome único" são feitas ANTES
// da escrita, para dar uma mensagem clara. Mas dois ADMINs poderiam
// salvar o mesmo login (ou o mesmo médico) no mesmo instante: nesse
// caso raro, é uma restrição SQL de unicidade que recusa a segunda
// escrita - então traduzimos esse erro SQL na mesma BusinessException.
// -----------------------------------------------------------------------
private async transaction<R>(work: (manager: EntityManager) => Promise<R>): Promise<R> {
try {
return await this.dataSource.transaction(work);
} catch (e) {
throw translateDuplicate(e);
}
}
}
// -------------------------------------------------------------------------
// Violações de restrição de unicidade -> BusinessException
//
// Quando uma restrição UNIQUE recusa uma escrita, o MySQL retorna o erro
// ER_DUP_ENTRY (nº 1062), cuja 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: cada uma pode então
// ser traduzida em sua própria mensagem.
// -------------------------------------------------------------------------
const CONSTRAINT_MESSAGES: Record<string, string> = {
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',
};
// retorna a BusinessException correspondente à restrição violada, ou
// o erro original, inalterado, se não for uma violação conhecida
function translateDuplicate(e: unknown): unknown {
if (!(e instanceof QueryFailedError)) {
return e;
}
const sqlError = e.driverError as { code?: string; sqlMessage?: string };
if (sqlError?.code !== 'ER_DUP_ENTRY') {
return e;
}
// "... for key 'doctors.unq_doctors_first_name_last_name'" -> "unq_doctors_first_name_last_name"
const constraint = /for key '(?:[^'.]*\.)?([^']+)'/.exec(sqlError.sqlMessage ?? e.message)?.[1];
const key = constraint ? CONSTRAINT_MESSAGES[constraint] : undefined;
return key ? new BusinessException(key) : e;
}
|
Este é o arquivo mais completo da aplicação. Vamos analisá-lo seção por seção.
11.11.4.1. Os descritores
- linha 54: o custo do bcrypt, o mesmo do script SQL;
- linhas 59–64: o que os DAO de médicos e de clientes têm em comum. [TypeScript] compara os tipos pela sua forma: [DoctorRepository] e [ClientRepository] satisfazem essa interface sem declará-la ([implements]);
- Linhas 67–80: tudo o que distingue um médico de um cliente do ponto de vista da lógica de negócio: seu DAO, a forma de criar uma instância, o papel de sua conta, suas mensagens de erro e o que acontece quando ele é excluído. Como médicos e clientes seguem as mesmas regras, o código dessas regras é escrito uma só vez, em métodos genéricos parametrizados por um descritor;
- linhas 87–98: o construtor recebe o [DataSource] (para abrir transações) e os cinco DAO. Ele constrói os dois descritores. O dos médicos (linhas 99–111) impede a exclusão de um médico que tenha consultas ([countAppointments]) e exclui seus horários antes de o médico ser excluído ([beforeDelete]). O dos clientes (linhas 112–122) não tem [countAppointments]: um cliente é excluído junto com suas consultas.
11.11.4.2. Operações de leitura e o calendário
- linhas 129–167: as consultas delegam à camada DAO;
- linhas 170–185: cálculo do calendário. Os horários do médico e as consultas do dia são lidos; as consultas são guardadas em um [Map] indexado pelo identificador do horário; em seguida, cada horário é associado à sua consulta ou a [null]. O [Map] evita ter de percorrer a lista de consultas para cada horário.
11.11.4.3. Marcação de uma consulta
- linhas 203–221: tudo ocorre dentro de uma única transação;
- linhas 206–208: nenhuma consulta no passado;
- linhas 209–211: o registro do paciente é bloqueado. Sem esse bloqueio, duas consultas para o mesmo paciente enviadas ao mesmo tempo (duas abas, um clique duplo) poderiam ambas passar no teste seguinte antes que qualquer uma delas gravasse sua consulta no banco de dados. Com o bloqueio, a segunda transação espera a primeira terminar e então vê a consulta que ela criou;
- linhas 212–214: apenas uma consulta futura por paciente;
- linhas 215–219: a inserção. Se outro paciente acabou de reservar o mesmo horário, a restrição [unq1_appointments] rejeita a inserção, e o método [transaction] trata o erro (veja adiante);
- linhas 223–225: exclusão de uma consulta.
11.11.4.4. Gerenciamento de médicos e clientes
- linhas 232–256: os seis métodos públicos delegam aos três métodos genéricos, usando o descritor correto;
- Linhas 262–288: criação. O nome é capitalizado; por padrão, o nome de usuário é o nome em minúsculas, e a senha é o nome de usuário (linhas 267–268). Dentro da transação: as regras de unicidade são verificadas, a conta é criada (a senha é transformada em hash), depois a pessoa, que é associada à conta. Se a segunda operação de gravação falhar, a primeira é desfeita: uma conta nunca é criada sem uma pessoa;
- linhas 295–299: a alteração. O bloqueio otimista (linhas 308–310) rejeita um registro que tenha sido modificado nesse meio-tempo. O nome exibido da conta acompanha o nome e o sobrenome; o nome de usuário e a senha só mudam se tiverem sido informados;
- linhas 341–356: a exclusão, na ordem ditada pelas chaves estrangeiras: possível rejeição (um médico que tem consultas), exclusão das referências à pessoa (os horários de um médico, as consultas de um cliente), exclusão da pessoa e, por fim, exclusão de sua conta;
- linhas 361–367: uma pessoa com o mesmo nome é rejeitada, a menos que seja a própria pessoa (modificação);
- linhas 374–378: um nome de usuário já em uso é rejeitado.
11.11.4.5. Transações e restrições de unicidade
- linhas 392–398: todas as gravações passam por este método: [dataSource.transaction] confirma ou desfaz a transação (veja o Exemplo 28), e um erro é traduzido por [translateDuplicate];
- linhas 411–416: cada restrição de unicidade nomeada do script SQL tem sua própria mensagem de erro;
- linhas 420–432: um erro SQL ([QueryFailedError]) com o código [ER_DUP_ENTRY] é uma violação de restrição de unicidade. Sua mensagem inclui o nome da restrição (precedido do nome da tabela no [MySQL] 8, sem prefixo no [MariaDB]): a expressão regular da linha 429 o extrai. Uma restrição conhecida se torna uma [BusinessException]; qualquer outro erro é repassado como está: trata-se de uma anomalia genuína.
11.12. Autenticação
A pasta [auth] reúne, de forma mais completa, os exemplos 25 a 27: o token JWT em um cookie, papéis, CAPTCHA e limite de tentativas. Ela inclui também um “passe” para a criação de contas.
11.12.1. src/auth/auth.constants.ts
| // =========================================================================
// auth/auth.constants.ts
// -------------------------------------------------------------------------
// Por onde viaja o token JWT?
//
// Com o cliente Angular, era o código JavaScript do cliente que guardava
// o token (localStorage) e o adicionava ele mesmo a cada requisição (cabeçalho
// "Authorization: Bearer ..."). Um navegador que exibe páginas HTML
// comuns não pode fazer isso: para que ele apresente o token por conta
// própria a cada requisição, o token deve ser armazenado em um COOKIE.
//
// As opções deste cookie importam para a segurança:
// - httpOnly: o JavaScript da página não pode 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 alteram
// 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 trafega em texto claro;
// - maxAge: o cookie desaparece ao mesmo tempo em que o token expira.
// =========================================================================
import { CookieOptions } from 'express';
export const COOKIE_JWT = 'rdvmedecins_jwt';
export const JWT_SECRET = process.env.JWT_SECRET ?? 'dev-secret-change-in-production';
export const JWT_EXPIRES_IN_SECONDS = process.env.JWT_EXPIRES_IN_SECONDS
? parseInt(process.env.JWT_EXPIRES_IN_SECONDS, 10)
: 7200;
export function jwtCookieOptions(): CookieOptions {
return {
httpOnly: true,
sameSite: 'lax',
secure: process.env.COOKIE_SECURE === 'true',
maxAge: JWT_EXPIRES_IN_SECONDS * 1000, // em milissegundos para o Express
path: '/',
};
}
|
- linhas 4–21: o comentário explica por que o token é guardado em um cookie e a finalidade de cada uma de suas opções (veja o exemplo 25);
- linha 28: a chave, lida de [.env]. O valor padrão deve ser usado apenas durante o desenvolvimento;
- linhas 30–32: a duração do token: duas horas por padrão;
- linhas 34–42: as opções do cookie, reunidas em um só lugar (são usadas no login e na modificação da conta de um paciente). [secure] é ativada apenas em produção, onde o site é servido por HTTPS; [maxAge] é dado em milissegundos.
11.12.2. src/auth/auth.service.ts
| // =========================================================================
// auth/auth.service.ts
// -------------------------------------------------------------------------
// A lógica de autenticação:
// - validateUser() : verifica um par login / senha;
// - createToken() : constrói o token JWT de um usuário validado;
// - readToken() : verifica um token (página de login: se o
// usuário já está logado, não é preciso pedir
// a senha novamente).
// =========================================================================
import { Injectable } from '@nestjs/common';
import { JwtService } from '@nestjs/jwt';
import * as bcrypt from 'bcryptjs';
import { UserRepository } from '../repositories/user.repository';
import { User } from '../entities/user.entity';
import { JwtPayload } from './jwt.strategy';
@Injectable()
export class AuthService {
constructor(
private readonly userRepository: UserRepository,
private readonly jwtService: JwtService,
) {}
async validateUser(login: string, password: string): Promise<User | null> {
const user = await this.userRepository.findByLogin(login);
if (user === null) {
return null;
}
return (await bcrypt.compare(password, user.password)) ? user : null;
}
createToken(user: User): string {
const payload: JwtPayload = { sub: user.id, login: user.login, name: user.name, role: user.role };
return this.jwtService.sign(payload);
}
// retorna o conteúdo do token se ele for válido (assinatura correta, não
// expirado), null caso contrário
readToken(token: string | undefined): JwtPayload | null {
if (!token) {
return null;
}
try {
return this.jwtService.verify<JwtPayload>(token);
} catch {
return null;
}
}
}
|
- linhas 26–32: a conta, se o nome de usuário e a senha estiverem corretos ([bcrypt.compare]), [null] caso contrário;
- linhas 34–37: o token, que contém o identificador, o nome de usuário, o nome de exibição e o papel;
- linhas 41–50: [jwtService.verify] verifica a assinatura e a data de expiração de um token e lança uma exceção se ele for inválido. Esse método é usado pelas páginas não protegidas (a página de login) que querem determinar se o usuário já está logado.
11.12.3. src/auth/jwt.strategy.ts
| // =========================================================================
// auth/jwt.strategy.ts
// -------------------------------------------------------------------------
// A estratégia Passport que autentica CADA requisição protegida a partir do
// token JWT. Única diferença em relação ao servidor JSON: o token é lido do
// cookie [rdvmedecins_jwt] (veja auth.constants.ts) em vez do
// cabeçalho "Authorization: Bearer ...".
// =========================================================================
import { Injectable } from '@nestjs/common';
import { PassportStrategy } from '@nestjs/passport';
import { Request } from 'express';
import { ExtractJwt, Strategy } from 'passport-jwt';
import { Role } from '../entities/user.entity';
import { COOKIE_JWT, JWT_SECRET } from './auth.constants';
// o que é armazenado NO token quando ele é construído (veja AuthService).
// O nome exibido também está lá, para que a barra de navegação possa
// exibi-lo sem consultar o banco de dados a cada página.
export interface JwtPayload {
sub: number; // o id do usuário (convenção JWT)
login: string;
name: string;
role: Role;
}
// o que request.user conterá depois que o token for verificado
export interface ConnectedUser {
userId: number;
login: string;
name: string;
role: Role;
}
@Injectable()
export class JwtStrategy extends PassportStrategy(Strategy, 'jwt') {
constructor() {
super({
// fromExtractors([...]): fornecemos NOSSA própria função de extração
// do token - aqui, a leitura de um cookie (req.cookies é preenchido pelo
// middleware cookie-parser, veja main.ts).
jwtFromRequest: ExtractJwt.fromExtractors([(req: Request) => req?.cookies?.[COOKIE_JWT] ?? null]),
ignoreExpiration: false,
secretOrKey: JWT_SECRET,
});
}
validate(payload: JwtPayload): ConnectedUser {
return { userId: payload.sub, login: payload.login, name: payload.name, role: payload.role };
}
}
|
- linhas 20–25: o conteúdo do token;
- linhas 28–33: o que [req.user] conterá;
- linhas 38–45: o token é lido do cookie; se tiver expirado ou estiver com a assinatura incorreta, é rejeitado;
- linhas 48–50: o conteúdo do token passa a ser [req.user].
11.12.4. src/auth/jwt-auth.guard.ts
| // =========================================================================
// auth/jwt-auth.guard.ts
// -------------------------------------------------------------------------
// O guard que protege todas as páginas da aplicação (exceto /login): ele
// exige um token JWT válido (veja jwt.strategy.ts, registrada sob o nome
// 'jwt'). Sem token, ou com um token inválido/expirado, ele lança uma
// UnauthorizedException - que HtmlExceptionFilter transforma em um redirecionamento
// para a página de login (veja web/html-exception.filter.ts).
// =========================================================================
import { Injectable } from '@nestjs/common';
import { AuthGuard } from '@nestjs/passport';
@Injectable()
export class JwtAuthGuard extends AuthGuard('jwt') {}
|
O guard que exige um token válido (veja o Exemplo 25). Sem token, ele lança uma [UnauthorizedException], que o filtro de exceção converte em um redirecionamento para [/login].
11.12.5. src/auth/roles.decorator.ts
| // =========================================================================
// auth/roles.decorator.ts
// -------------------------------------------------------------------------
// @Roles('ADMIN') é um decorador CASEIRO (nós mesmos o escrevemos,
// ao contrário de @Get/@Post/@Injectable fornecidos pelo NestJS): ele apenas
// anexa um metadado ("este método exige tal papel") ao
// método que decora, sem verificar nada por si só - é o RolesGuard
// (veja roles.guard.ts) que lerá este metadado e fará a verificação.
//
// SetMetadata(key, value) é a função de baixo nível do NestJS que permite
// escrever este tipo de decorador "personalizado": nós a usamos aqui para não
// ter de repetir a string 'roles' por todo o código.
// =========================================================================
import { SetMetadata } from '@nestjs/common';
import { Role } from '../entities/user.entity';
export const ROLES_KEY = 'roles';
export const Roles = (...roles: Role[]) => SetMetadata(ROLES_KEY, roles);
|
Linha 19: o decorador [@Roles(...)] (veja o Exemplo 26). Seus parâmetros são do tipo [Role]: [@Roles('ADMIM')] (erro de digitação) é rejeitado pelo compilador.
11.12.6. src/auth/roles.guard.ts
| // =========================================================================
// auth/roles.guard.ts
// -------------------------------------------------------------------------
// Segundo nível de controle, DEPOIS de JwtAuthGuard: este apenas verifica
// que estamos de fato autenticados (um token JWT válido); RolesGuard
// verifica além disso que o papel do usuário logado (request.user.role,
// definido por JwtStrategy) está entre os exigidos por @Roles(...)
// no método visado.
//
// Inalterado em relação ao servidor JSON, exceto o destino do erro:
// a ForbiddenException lançada aqui é transformada em uma PÁGINA "403 - acesso
// proibido" por HtmlExceptionFilter (veja web/html-exception.filter.ts).
//
// É o equivalente, em espírito, da regra do Spring Security:
// http.authorizeRequests().antMatchers(...).hasRole("ADMIN")
// mas aplicada aqui método por método em vez de URL por URL, graças ao
// par decorador (@Roles) + Reflector (que sabe reler os metadados
// definidos por um decorador).
// =========================================================================
import { CanActivate, ExecutionContext, ForbiddenException, Injectable } from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { ROLES_KEY } from './roles.decorator';
import { Role } from '../entities/user.entity';
import { ConnectedUser } from './jwt.strategy';
@Injectable()
export class RolesGuard implements CanActivate {
constructor(private readonly reflector: Reflector) {}
canActivate(context: ExecutionContext): boolean {
// relemos os metadados definidos por @Roles(...) no método visado -
// getAllAndOverride procura primeiro no método, depois na classe.
const requiredRoles = this.reflector.getAllAndOverride<Role[]>(ROLES_KEY, [context.getHandler(), context.getClass()]);
// sem metadado @Roles(...) neste método: nenhuma restrição adicional de papel
// (JwtAuthGuard já terá exigido uma autenticação
// válida, qualquer que seja o papel).
if (!requiredRoles || requiredRoles.length === 0) {
return true;
}
// request.user foi definido por JwtStrategy.validate() (veja jwt.strategy.ts) -
// RolesGuard portanto SEMPRE executa depois de JwtAuthGuard (veja a ordem
// deles em @UseGuards(JwtAuthGuard, RolesGuard), veja src/web/controllers/).
const request = context.switchToHttp().getRequest<{ user: ConnectedUser }>();
const user = request.user;
if (!requiredRoles.includes(user.role)) {
throw new ForbiddenException(
`role [${user.role}] does not allow this action (required role: ${requiredRoles.join(', ')})`,
);
}
return true;
}
}
|
O mapeamento de papéis é idêntico ao do Exemplo 26.
11.12.7. src/auth/captcha.service.ts
| // =========================================================================
// auth/captcha.service.ts
// -------------------------------------------------------------------------
// Um CAPTCHA ("teste para distinguir um humano de um robô") construído pelo
// próprio servidor, sem nenhum serviço externo: a biblioteca svg-captcha
// desenha alguns caracteres distorcidos, borrados por linhas, em uma
// imagem SVG. Um humano os lê facilmente; um robô que apenas
// envia formulários em loop não consegue.
//
// Como funciona:
// 1. generate() sorteia um texto aleatório, o transforma em imagem e armazena a
// resposta certa 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 única vez, um robô não pode
// reutilizar uma resposta já encontrada.
//
// Limite aceito: a memória de um único processo Node. Com vários
// servidores atrás de um balanceador de carga, seria necessário um armazenamento
// compartilhado (Redis, banco de dados...).
// =========================================================================
import { Injectable } from '@nestjs/common';
import { randomUUID } from 'crypto';
import * as svgCaptcha from 'svg-captcha';
// validade de uma imagem: você tem 10 minutos para preencher o formulário
const LIFETIME_MS = 10 * 60 * 1000;
// proteção de memória: além disso, os captchas mais antigos são esquecidos
const MAX_CAPTCHAS = 10_000;
export interface Captcha {
id: string; // para colocar no campo oculto "captchaId" do formulário
svg: string; // a imagem, a inserir como está na página
}
@Injectable()
export class CaptchaService {
// id -> { resposta esperada, data de expiração }. Um Map mantém a ordem
// de inserção: suas primeiras entradas são as mais antigas.
private readonly pending = new Map<string, { text: string; expires: number }>();
generate(): Captcha {
this.purge();
const { text, data } = svgCaptcha.create({
size: 5, // 5 caracteres
noise: 3, // 3 linhas de borrão
color: true,
background: '#f5f7fa',
// caracteres fáceis demais de confundir entre si: excluídos
ignoreChars: '0oO1iIlL',
});
const id = randomUUID();
this.pending.set(id, { text: text.toLowerCase(), expires: Date.now() + LIFETIME_MS });
return { id, svg: data };
}
// true se [input] é a resposta certa ao captcha [id] (sem distinção
// de maiúsculas e minúsculas). O captcha é consumido em todos os casos.
verify(id: unknown, input: unknown): boolean {
if (typeof id !== 'string' || typeof input !== 'string') {
return false;
}
const expected = this.pending.get(id);
this.pending.delete(id);
return expected !== undefined && expected.expires > Date.now() && expected.text === input.trim().toLowerCase();
}
private purge(): void {
const now = Date.now();
for (const [id, { expires }] of this.pending) {
if (expires <= now || this.pending.size >= MAX_CAPTCHAS) {
this.pending.delete(id);
}
}
}
}
|
- Linhas 29–31: em comparação com o Exemplo 27, um CAPTCHA tem tempo de vida (dez minutos) e o número de CAPTCHAs em memória é limitado: um bot que solicitasse a página de login milhões de vezes não conseguiria esgotar a memória do servidor;
- linha 42: um [Map] preserva a ordem de inserção: suas entradas mais antigas são as primeiras;
- linhas 44–57: a imagem, a resposta esperada (em minúsculas) e a data de expiração;
- linhas 61–68: a resposta é comparada sem distinção entre maiúsculas e minúsculas; o CAPTCHA é consumido em todos os casos;
- linhas 70–77: os CAPTCHAs expirados são descartados, assim como os mais antigos quando o limite é atingido.
11.12.8. src/auth/attempt-limiter.service.ts
| // =========================================================================
// auth/attempt-limiter.service.ts
// -------------------------------------------------------------------------
// Segunda linha de defesa contra bots (a primeira é o captcha): CONTAMOS
// as tentativas e, acima de um limite, BLOQUEAMOS por um tempo.
//
// - login: após LOGIN_MAX_FAILURES falhas (captcha errado ou senha
// errada) para o mesmo login a partir do mesmo endereço IP, este par é
// bloqueado por LOGIN_BLOCK_MINUTES minutos. O mesmo endereço IP também é
// bloqueado se acumular 5 vezes mais falhas, todos os logins somados (um
// bot que tenta milhares de logins diferentes);
// - criação de conta: no máximo REGISTRATION_MAX_PER_HOUR 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 vizinhos - e por que os limites podem ser definidos
// no arquivo .env.
//
// Como o captcha, os contadores vivem na memória do processo.
// =========================================================================
import { Injectable } from '@nestjs/common';
interface Counter {
count: number; // tentativas contadas na janela atual
start: number; // início da janela de contagem (ms)
blockedUntil: number; // 0 se não estiver bloqueado
}
const MINUTE = 60 * 1000;
function envInteger(name: string, fallback: number): number {
const value = parseInt(process.env[name] ?? '', 10);
return Number.isInteger(value) && value > 0 ? value : fallback;
}
@Injectable()
export class AttemptLimiterService {
private readonly counters = new Map<string, Counter>();
private readonly maxLoginFailures = envInteger('LOGIN_MAX_FAILURES', 5);
private readonly loginBlockDuration = envInteger('LOGIN_BLOCK_MINUTES', 15) * MINUTE;
private readonly maxRegistrations = envInteger('REGISTRATION_MAX_PER_HOUR', 10);
// ────────────────────────────────────────── login
// número de minutos restantes de bloqueio (0 = a tentativa é permitida)
loginBlockMinutes(ip: string, login: string): number {
return Math.max(this.remainingMinutes(loginKey(ip, login)), this.remainingMinutes(ipKey(ip)));
}
loginFailure(ip: string, login: string): void {
this.count(loginKey(ip, login), this.maxLoginFailures, this.loginBlockDuration, this.loginBlockDuration);
this.count(ipKey(ip), this.maxLoginFailures * 5, this.loginBlockDuration, this.loginBlockDuration);
}
// um login bem-sucedido zera o contador DESTE login
loginSuccess(ip: string, login: string): void {
this.counters.delete(loginKey(ip, login));
}
// ────────────────────────────────────────── cadastro
registrationBlockMinutes(ip: string): number {
return this.remainingMinutes(`registration|${ip}`);
}
registrationSuccess(ip: string): void {
// janela de uma hora; atingida a cota, bloqueado até o fim da hora
this.count(`registration|${ip}`, this.maxRegistrations, 60 * MINUTE, 60 * MINUTE);
}
// ────────────────────────────────────────── mecânica comum
private remainingMinutes(key: string): number {
const c = this.counters.get(key);
const remaining = c ? c.blockedUntil - Date.now() : 0;
return remaining > 0 ? Math.ceil(remaining / MINUTE) : 0;
}
// conta uma tentativa; se o limite for atingido dentro da janela, bloqueia
private count(key: string, max: number, window: number, block: number): void {
const now = Date.now();
this.purge(now);
let c = this.counters.get(key);
if (!c || now - c.start > window) {
c = { count: 0, start: now, blockedUntil: 0 };
this.counters.set(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 purge(now: number): void {
if (this.counters.size < 1000) {
return;
}
for (const [key, c] of this.counters) {
if (c.blockedUntil < now && now - c.start > 60 * MINUTE) {
this.counters.delete(key);
}
}
}
}
function loginKey(ip: string, login: string): string {
return `login|${ip}|${login.trim().toLowerCase()}`;
}
function ipKey(ip: string): string {
return `ip|${ip}`;
}
|
- linhas 26–30: um contador de tentativas, com o início de sua janela de contagem e a data de fim do bloqueio;
- linhas 34–37: um limite lido de [.env], com um valor padrão;
- linhas 50–52: o bloqueio se aplica ao par (endereço IP, login) e apenas ao endereço IP quando este acumula um grande número de tentativas fracassadas, em todos os logins. Em uma sala de aula, todas as estações costumam se conectar pelo mesmo endereço IP: um aluno que digita a senha errada não deve bloquear os colegas;
- linhas 54–57: uma tentativa fracassada conta para as duas chaves;
- linhas 66–68 e 70–73: o número de contas criadas por hora a partir do mesmo endereço IP é limitado;
- linhas 84–98: a contagem. Uma janela expirada volta a zero; quando o limite é atingido, a chave é bloqueada;
- linhas 101–110: limpeza dos contadores antigos para evitar que as chaves se acumulem indefinidamente na memória;
- linhas 113–118: geração das chaves para o [Map].
11.12.9. src/auth/registration-pass.service.ts
| // =========================================================================
// auth/registration-pass.service.ts
// -------------------------------------------------------------------------
// O "passe" para a criação de conta.
//
// Para abrir a página "Criar uma conta de paciente", é preciso antes ter
// digitado 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 (tempo de preencher o formulário, mesmo
// tentando várias vezes após erros de entrada);
// - consumido assim que uma conta é criada: UM captcha resolvido = UMA conta no
// máximo. Um bot não consegue criar contas em massa.
//
// Sem um passe válido, GET e POST /register enviam de volta à página de
// autenticação: digitar diretamente a URL /register não
// contorna o captcha.
//
// Como o captcha, os passes vivem na memória do processo.
// =========================================================================
import { Injectable } from '@nestjs/common';
import { randomUUID } from 'crypto';
import { CookieOptions } from 'express';
export const COOKIE_REGISTRATION_PASS = 'rdvmedecins_registration';
const LIFETIME_MS = 15 * 60 * 1000;
const MAX_PASSES = 10_000;
@Injectable()
export class RegistrationPassService {
// id -> data de expiração
private readonly passes = new Map<string, number>();
// emite um novo passe; retorna seu identificador
issue(): string {
this.purge();
const id = randomUUID();
this.passes.set(id, Date.now() + LIFETIME_MS);
return id;
}
// true se [id] é um passe existente e não expirado
isValid(id: unknown): boolean {
if (typeof id !== 'string') {
return false;
}
const expires = this.passes.get(id);
return expires !== undefined && expires > Date.now();
}
// o passe foi usado: nós o esquecemos
consume(id: unknown): void {
if (typeof id === 'string') {
this.passes.delete(id);
}
}
cookieOptions(): CookieOptions {
return { httpOnly: true, sameSite: 'lax', maxAge: LIFETIME_MS, path: '/register' };
}
private purge(): void {
const now = Date.now();
for (const [id, expires] of this.passes) {
if (expires <= now || this.passes.size >= MAX_PASSES) {
this.passes.delete(id);
}
}
}
}
|
A criação de uma conta de paciente está disponível a partir da página de login, desde que o CAPTCHA tenha sido resolvido. Portanto, uma requisição (o formulário de cadastro) precisa saber que a requisição anterior resolveu o CAPTCHA. Este é o papel do passe:
- linhas 38–43: um identificador aleatório, válido por 15 minutos, armazenado em memória; ele será gravado em um cookie;
- linhas 46–52: o formulário de cadastro só é exibido e aceito com um passe válido;
- linhas 55–59: a criação de uma conta consome o passe: um CAPTCHA resolvido dá direito a uma conta, e não mais que isso;
- linhas 61–63: a opção [path: '/register'] restringe o envio do cookie às URLs que começam com [/register].
11.12.10. src/auth/auth.controller.ts
| // =========================================================================
// auth/auth.controller.ts
// -------------------------------------------------------------------------
// As rotas de login NÃO protegidas:
// 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 limite de tentativas, captcha, login / senha
// POST /logout apaga o cookie do token
//
// O servidor JSON usava um guard Passport "local" para POST /login:
// em caso de falha, ele respondia 401 diretamente, o que serve a um
// cliente JavaScript. Uma página HTML, porém, deve EXIBIR o formulário NOVAMENTE
// com uma mensagem de erro: por isso chamamos nós mesmos o AuthService.
//
// Proteção contra bots, nesta ordem (veja captcha.service.ts e
// attempt-limiter.service.ts):
// 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 a senha é verificada.
// A senha de uma tentativa recusada nas etapas 1 ou 2 NUNCA é verificada:
// um bot portanto não consegue aprender nada insistindo.
// =========================================================================
import { Body, Controller, Get, HttpCode, Post, Query, Req, Res } from '@nestjs/common';
import { Request, Response } from 'express';
import { AuthService } from './auth.service';
import { CaptchaService } from './captcha.service';
import { AttemptLimiterService } from './attempt-limiter.service';
import { COOKIE_JWT, jwtCookieOptions } from './auth.constants';
import { Role } from '../entities/user.entity';
// a página inicial de cada papel, logo após o login
export function homePage(role: Role): string {
return role === 'USER' ? '/my-area' : '/schedule';
}
@Controller()
export class AuthController {
constructor(
private readonly authService: AuthService,
private readonly captchaService: CaptchaService,
private readonly limiter: AttemptLimiterService,
) {}
@Get()
home(@Req() req: Request, @Res() res: Response): void {
const token = this.authService.readToken(req.cookies?.[COOKIE_JWT]);
res.redirect(token ? homePage(token.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)
@Get('login')
showLogin(@Req() req: Request, @Res() res: Response, @Query('login') login?: string): void {
// já logado (token ainda válido): direto para a página inicial
const token = this.authService.readToken(req.cookies?.[COOKIE_JWT]);
if (token !== null) {
return res.redirect(homePage(token.role));
}
this.showForm(res, typeof login === 'string' ? login.slice(0, 30) : '');
}
// @HttpCode(200): por padrão, o NestJS responde 201 (Created) a um POST - o que
// não faz sentido quando o formulário é EXIBIDO NOVAMENTE (um redirecionamento, por sua vez,
// impõe de qualquer modo o seu próprio código, 302).
@Post('login')
@HttpCode(200)
async logIn(
@Body() body: { login?: string; password?: string; captchaId?: string; captcha?: string },
@Req() req: Request,
@Res() res: Response,
): Promise<void> {
const login = (body.login ?? '').trim();
const password = body.password ?? '';
const ip = req.ip ?? 'unknown';
// 1. muitas falhas recentes?
const minutes = this.limiter.loginBlockMinutes(ip, login);
if (minutes > 0) {
return this.showForm(res, login, 'ERRORS.TOO_MANY_ATTEMPTS', { minutes: String(minutes) });
}
// 2. o captcha
if (!this.captchaService.verify(body.captchaId, body.captcha)) {
this.limiter.loginFailure(ip, login);
return this.showForm(res, login, 'ERRORS.WRONG_CAPTCHA');
}
// 3. a senha
const user = login && password ? await this.authService.validateUser(login, password) : null;
if (user === null) {
this.limiter.loginFailure(ip, login);
return this.showForm(res, login, 'LOGIN.ERROR');
}
this.limiter.loginSuccess(ip, login);
res.cookie(COOKIE_JWT, this.authService.createToken(user), jwtCookieOptions());
res.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 o conhecimento dele (veja sameSite, auth.constants.ts)
@Post('logout')
logOut(@Res() res: Response): void {
res.clearCookie(COOKIE_JWT, { path: '/' });
res.redirect('/login');
}
// o formulário, sempre com um captcha NOVO (cada imagem é usada uma única vez)
private showForm(
res: Response,
login: string,
error?: string,
errorParams?: Record<string, string>,
): void {
res.render('login', {
pageTitle: 'LOGIN.TITLE',
login, // o login digitado é exibido novamente, nunca a senha
captcha: this.captchaService.generate(),
error,
errorParams,
});
}
}
|
Vamos comentar este código:
- linhas 34–36: a página inicial depende do papel do usuário: “Minha área” para os pacientes, a agenda para todos os demais;
- linhas 46–50: a raiz do site redireciona conforme o usuário esteja logado ou não. Como a rota não é protegida pelo guard, o token é verificado por [readToken];
- linhas 54–62: um usuário que já está logado é enviado para sua página inicial. O parâmetro [login] preenche o campo previamente (depois que uma conta é criada). [slice(0, 30)] limita seu tamanho: dados da requisição nunca são usados sem precauções;
- linhas 69–73: o processo de login, em ordem: eventual bloqueio, CAPTCHA e, por fim, senha (veja o Exemplo 27). [req.ip] é o endereço IP do cliente. Em caso de sucesso: contador zerado, cookie definido, redirecionamento para a página inicial do papel;
- linhas 104–108: logout;
- linhas 111–116: a página de login, sempre com um novo CAPTCHA. O erro é uma chave de tradução, junto com seus parâmetros (o número de minutos de bloqueio).
11.12.11. src/auth/auth.module.ts
| // =========================================================================
// auth/auth.module.ts
// -------------------------------------------------------------------------
// O módulo de autenticação. Ele EXPORTA:
// - UserRepository, de que a camada de negócio precisa (criar, atualizar,
// excluir a conta de um médico ou de um cliente - veja business.service.ts);
// - AuthService, CaptchaService, AttemptLimiterService e
// RegistrationPassService, também usados pelas páginas "Criar uma conta"
// e "Gerenciar minha conta" (src/web/).
// =========================================================================
import { Module } from '@nestjs/common';
import { JwtModule } from '@nestjs/jwt';
import { PassportModule } from '@nestjs/passport';
import { TypeOrmModule } from '@nestjs/typeorm';
import { User } from '../entities/user.entity';
import { UserRepository } from '../repositories/user.repository';
import { AuthService } from './auth.service';
import { AuthController } from './auth.controller';
import { JwtStrategy } from './jwt.strategy';
import { CaptchaService } from './captcha.service';
import { AttemptLimiterService } from './attempt-limiter.service';
import { RegistrationPassService } from './registration-pass.service';
import { JWT_EXPIRES_IN_SECONDS, JWT_SECRET } from './auth.constants';
@Module({
imports: [
TypeOrmModule.forFeature([User]),
PassportModule,
JwtModule.register({
secret: JWT_SECRET,
signOptions: { expiresIn: JWT_EXPIRES_IN_SECONDS },
}),
],
controllers: [AuthController],
providers: [
AuthService,
UserRepository,
JwtStrategy,
CaptchaService,
AttemptLimiterService,
RegistrationPassService,
],
exports: [UserRepository, AuthService, CaptchaService, AttemptLimiterService, RegistrationPassService],
})
export class AuthModule {}
|
- linha 28: o repositório da entidade [User];
- linhas 30–33: a configuração do [JwtService];
- linha 44: os serviços exportados para o módulo raiz (veja o Exemplo 06): [UserRepository] para a camada de negócio (criar a conta de um médico ou de um cliente), os demais para os controllers da camada web (criação de conta, gerenciamento da conta pelo paciente).
11.13. A camada web: serviços comuns
Antes de ver os controllers, eis o que eles têm em comum: a tradução, o contexto de cada página, o interceptor, o filtro de exceção, o cache das listas e os helpers.
11.13.1. src/web/i18n.ts
| // =========================================================================
// web/i18n.ts
// -------------------------------------------------------------------------
// Tradução francês / inglês da interface.
//
// O cliente Angular carregava seus dicionários (public/i18n/fr.json e
// en.json) no NAVEGADOR com @ngx-translate. Aqui, as páginas são
// construídas no SERVIDOR: são portanto os mesmos dicionários (mesmas
// chaves, complementadas), mas lidos uma única vez pelo servidor na inicialização.
// Uma view Handlebars traduz uma chave com o helper {{t 'KEY'}}
// (veja views/handlebars-helpers.ts), o equivalente do pipe `| translate`.
// =========================================================================
import { readFileSync } from 'fs';
import { join } from 'path';
import { I18N_DIR } from '../config/paths';
export type Language = 'fr' | 'en';
export const LANGUAGES: Language[] = ['fr', 'en'];
export const DEFAULT_LANGUAGE: Language = 'en';
// um dicionário é um objeto JSON aninhado: { "LOGIN": { "TITLE": "Login" } }
type Dictionary = { [key: string]: string | Dictionary };
const dictionaries: Record<Language, Dictionary> = {
fr: JSON.parse(readFileSync(join(I18N_DIR, 'fr.json'), 'utf-8')),
en: JSON.parse(readFileSync(join(I18N_DIR, 'en.json'), 'utf-8')),
};
export function isLanguage(value: unknown): value is Language {
return typeof value === 'string' && (LANGUAGES as string[]).includes(value);
}
// -------------------------------------------------------------------------
// translate('en', 'DOCTORS.ADDED', { name: 'Marie PELISSIER' })
// -> procura DOCTORS e depois ADDED no dicionário inglês, e substitui
// {name} pelo seu valor. Uma chave ausente no idioma solicitado é
// procurada no idioma padrão; ausente em todos, a própria chave é exibida
// (uma omissão nos dicionários é assim percebida imediatamente).
// -------------------------------------------------------------------------
export function translate(language: Language, key: string, params: Record<string, unknown> = {}): string {
const text = lookup(dictionaries[language], key) ?? lookup(dictionaries[DEFAULT_LANGUAGE], key) ?? key;
return text.replace(/\{(\w+)\}/g, (whole, name: string) => (name in params ? String(params[name]) : whole));
}
function lookup(dictionary: Dictionary, key: string): string | null {
let node: string | Dictionary | undefined = dictionary;
for (const part of key.split('.')) {
if (typeof node !== 'object' || node === null) {
return null;
}
node = node[part];
}
return typeof node === 'string' ? node : null;
}
|
O módulo de tradução do Exemplo 22, com um esclarecimento (linha 42): se uma chave estiver ausente do dicionário em francês, ela é procurada no dicionário em inglês (o idioma padrão); se estiver ausente de ambos, a própria chave é exibida.
11.13.2. src/web/view-context.ts
| // =========================================================================
// web/view-context.ts
// -------------------------------------------------------------------------
// O que TODAS as páginas precisam saber, qualquer que seja a rota
// que as exibe: o idioma da interface, a eventual mensagem "flash" a
// exibir e o usuário logado (para a barra de navegação).
//
// O Express oferece [res.locals] para isso: um objeto anexado à resposta, cujo
// conteúdo é mesclado AUTOMATICAMENTE ao modelo de cada view no
// momento de res.render(...). Os controllers portanto não precisam repetir esta
// informação em cada um de seus modelos.
//
// Lembrete: o cliente Angular mantinha essas informações no navegador
// (signals + localStorage). Um servidor HTML, porém, deve encontrá-las de novo a
// CADA requisição - aqui em cookies.
// =========================================================================
import { NextFunction, Request, Response } from 'express';
import { Language, DEFAULT_LANGUAGE, isLanguage } from './i18n';
import { ConnectedUser } from '../auth/jwt.strategy';
export const COOKIE_LANGUAGE = 'rdvmedecins_language';
export const COOKIE_FLASH = 'rdvmedecins_flash';
// uma mensagem a exibir UMA vez, na próxima página
export interface FlashMessage {
type: 'success' | 'danger'; // classes do Bootstrap alert-success / alert-danger
key: string; // chave de tradução
params?: Record<string, string>;
}
// o usuário logado, como as views o veem
export interface ViewUser {
login: string;
name: string;
role: string;
isAdmin: boolean; // ADMIN: menus Médicos / Clientes
isPatient: boolean; // USER: menu Minha área
}
// -------------------------------------------------------------------------
// Middleware Express, executado ANTES de qualquer rota (veja main.ts):
// - res.locals.lang : idioma escolhido (cookie), inglês por padrão;
// - res.locals.flash : a eventual mensagem flash, que é apagada
// imediatamente (ela deve ser exibida uma só vez);
// - res.locals.currentPath: a URL requisitada (menu ativo da barra de navegação).
// -------------------------------------------------------------------------
export function viewContextMiddleware(req: Request, res: Response, next: NextFunction): void {
res.locals.lang = languageOf(req);
res.locals.currentPath = req.path;
res.locals.flash = null;
res.locals.currentUser = null;
const raw = req.cookies?.[COOKIE_FLASH];
if (raw) {
try {
res.locals.flash = JSON.parse(raw) as FlashMessage;
} catch {
// cookie ilegível: ignorado
}
res.clearCookie(COOKIE_FLASH);
}
next();
}
export function languageOf(req: Request): Language {
const value = req.cookies?.[COOKIE_LANGUAGE];
return isLanguage(value) ? value : DEFAULT_LANGUAGE;
}
// -------------------------------------------------------------------------
// define uma mensagem flash, que será exibida pela 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 então recarrega essa
// página (F5), o navegador não envia o formulário uma segunda vez.
// A mensagem, porém, deve sobreviver ao redirecionamento: um cookie de
// vida curta resolve.
// -------------------------------------------------------------------------
export function flash(res: Response, message: FlashMessage): void {
res.cookie(COOKIE_FLASH, JSON.stringify(message), { httpOnly: true, sameSite: 'lax', maxAge: 60_000 });
}
// -------------------------------------------------------------------------
// expõe o usuário logado (request.user, definido por JwtStrategy) às
// views. Chamado por ViewUserInterceptor (rotas normais) e por
// HtmlExceptionFilter (páginas de erro).
// -------------------------------------------------------------------------
export function exposeUser(req: Request, res: Response): void {
const user = (req as Request & { user?: ConnectedUser }).user;
if (!user) {
return;
}
const currentUser: ViewUser = {
login: user.login,
name: user.name,
role: user.role,
isAdmin: user.role === 'ADMIN',
isPatient: user.role === 'USER',
};
res.locals.currentUser = currentUser;
}
|
Vamos comentar este código:
- linhas 22–23: os nomes dos cookies do idioma e da mensagem flash;
- linhas 26–30: uma mensagem flash: um tipo (sucesso ou erro), uma chave de tradução e seus parâmetros. Ela é armazenada no cookie como JSON;
- linhas 33–39: o usuário logado, como visto pelas views. Os booleanos [isAdmin] e [isPatient] evitam que as views comparem strings;
- linhas 48–64: o middleware executado antes de qualquer rota (veja os exemplos 20 e 22): o idioma, o caminho (para o menu ativo) e a mensagem flash, que é lida e depois apagada. [JSON.parse] é protegido por um [try]: um cookie modificado manualmente não deve fazer a página falhar;
- linhas 66–69: o idioma, com base em seu cookie;
- linhas 80–82: exibe uma mensagem flash (veja o exemplo 20);
- linhas 89–102: copia o usuário logado ([req.user]) para [res.locals] para a barra de navegação. Esta função não é chamada pelo middleware: o middleware é executado antes dos guards e, portanto, antes de [req.user] existir (veja o Capítulo 7). Ela é chamada pelo interceptor seguinte e pelo filtro de exceção.
11.13.3. src/web/view-user.interceptor.ts
| // =========================================================================
// web/view-user.interceptor.ts
// -------------------------------------------------------------------------
// Por que um interceptor e não simplesmente o middleware de
// view-context.ts? Porque a ORDEM de execução importa:
//
// middlewares -> guards (JwtAuthGuard...) -> interceptors -> controller
//
// É o guard JwtAuthGuard que define request.user: um middleware executa
// cedo demais para vê-lo. Um interceptor, porém, executa DEPOIS dos guards e
// ANTES do controller - o momento certo para copiar o usuário logado
// para res.locals, onde todas as views o encontrarão.
// =========================================================================
import { CallHandler, ExecutionContext, Injectable, NestInterceptor } from '@nestjs/common';
import { Request, Response } from 'express';
import { Observable } from 'rxjs';
import { exposeUser } from './view-context';
@Injectable()
export class ViewUserInterceptor implements NestInterceptor {
intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {
const http = context.switchToHttp();
exposeUser(http.getRequest<Request>(), http.getResponse<Response>());
return next.handle();
}
}
|
Linhas 22–26: um interceptor é executado depois dos guards e antes da ação: é o momento certo para expor o usuário repassado pelo [JwtAuthGuard]. Ele não tem nada a fazer depois da ação: retorna [next.handle()] diretamente.
11.13.4. src/web/html-exception.filter.ts
| // =========================================================================
// web/html-exception.filter.ts
// -------------------------------------------------------------------------
// Um "filtro de exceção" do NestJS recebe toda exceção que não foi
// tratada pelo código dos controllers. Por padrão, o NestJS responde em JSON
// ({"statusCode":403,"message":...}) - perfeito para o servidor JSON, mas
// ilegível em um navegador. Em vez disso, este filtro constrói uma resposta
// adequada a uma aplicação HTML:
//
// 401 (não logado, ou token expirado) -> redirecionamento para /login
// 403 (papel insuficiente) -> página de erro "acesso proibido"
// 404 (página desconhecida) -> página de erro "página não encontrada"
// 400 (parâmetro inválido) -> página de erro "requisição inválida"
// todo o resto -> página de erro 500
//
// @Catch() sem argumento: o filtro captura TODAS as exceções. Ele é
// registrado uma única vez para toda a aplicação em main.ts.
// =========================================================================
import { ArgumentsHost, Catch, ExceptionFilter, HttpException, HttpStatus, Logger } from '@nestjs/common';
import { Request, Response } from 'express';
import { COOKIE_JWT } from '../auth/auth.constants';
import { exposeUser, flash } from './view-context';
const MESSAGES: Record<number, string> = {
[HttpStatus.BAD_REQUEST]: 'ERRORS.BAD_REQUEST',
[HttpStatus.FORBIDDEN]: 'ERRORS.FORBIDDEN',
[HttpStatus.NOT_FOUND]: 'ERRORS.NOT_FOUND',
};
@Catch()
export class HtmlExceptionFilter implements ExceptionFilter {
private readonly logger = new Logger(HtmlExceptionFilter.name);
catch(exception: unknown, host: ArgumentsHost): void {
const http = host.switchToHttp();
const req = http.getRequest<Request>();
const res = http.getResponse<Response>();
const status = exception instanceof HttpException ? exception.getStatus() : HttpStatus.INTERNAL_SERVER_ERROR;
if (status === HttpStatus.UNAUTHORIZED) {
// um cookie estava presente mas não é mais válido: a sessão expirou
if (req.cookies?.[COOKIE_JWT]) {
res.clearCookie(COOKIE_JWT, { path: '/' });
flash(res, { type: 'danger', key: 'ERRORS.SESSION_EXPIRED' });
}
res.redirect('/login');
return;
}
if (status >= 500) {
// uma anomalia real: mantemos o rastro completo no console do
// servidor, sem nunca exibi-lo ao usuário
this.logger.error(exception instanceof Error ? exception.stack : String(exception));
}
// a página de erro mantém a barra de navegação do usuário logado
// (se houver - um 403 ocorre DEPOIS da autenticação)
exposeUser(req, res);
res.status(status).render('error', {
pageTitle: 'ERROR_PAGE.TITLE',
code: status,
message: MESSAGES[status] ?? 'ERRORS.SERVER_ERROR',
});
}
}
|
- linhas 25–29: a chave de mensagem para cada código de erro;
- linhas 42–50: um 401 redireciona para a página de login. Se havia um cookie de token, ele expirou (ou a conta foi excluída): o cookie é apagado e o usuário é avisado por uma mensagem pop-up;
- linhas 52–56: um erro genuíno é registrado no console do servidor, junto com sua pilha de chamadas, mas nunca é revelado ao usuário: esses detalhes ajudariam um atacante;
- linhas 60–65: a página de erro, com a barra de navegação do usuário logado.
11.13.5. src/web/application-model.service.ts
| // =========================================================================
// web/application-model.service.ts
// -------------------------------------------------------------------------
// O cache / fachada já presente no servidor JSON (equivalente da classe
// [ApplicationModel] do projeto Spring): as listas de médicos e
// de clientes são lidas uma vez na inicialização e depois servidas da memória.
//
// Novidade: essas listas agora podem MUDAR (o ADMIN adiciona,
// edita, exclui médicos e clientes). Um cache que nunca
// fosse atualizado exibiria dados obsoletos: cada escrita
// portanto passa por este serviço, que recarrega a lista afetada logo depois.
// Esse é todo o sentido de ter UMA ÚNICA porta de entrada para a camada
// de negócio: a regra "escrita => recarga do cache" é escrita apenas aqui.
// =========================================================================
import { Inject, Injectable, OnModuleInit } from '@nestjs/common';
import { PersonData, IBusiness, BUSINESS_TOKEN } from '../business/business.interface';
import { Client } from '../entities/client.entity';
import { Doctor } from '../entities/doctor.entity';
import { Slot } from '../entities/slot.entity';
import { Appointment } from '../entities/appointment.entity';
import { DoctorDaySchedule } from '../domain/doctor-day-schedule';
@Injectable()
export class ApplicationModelService implements IBusiness, OnModuleInit {
private doctors: Doctor[] = [];
private clients: Client[] = [];
constructor(@Inject(BUSINESS_TOKEN) private readonly business: IBusiness) {}
// se o banco de dados estiver inacessível na inicialização, a exceção interrompe o servidor
// com uma mensagem explícita - mais claro, para uma aplicação HTML, do que
// iniciar "empty" e exibir listas vazias.
async onModuleInit(): Promise<void> {
await this.reloadDoctors();
await this.reloadClients();
}
private async reloadDoctors(): Promise<void> {
this.doctors = await this.business.getAllDoctors();
}
private async reloadClients(): Promise<void> {
this.clients = await this.business.getAllClients();
}
// ------------------------------------------------ leituras a partir do cache
async getAllDoctors(): Promise<Doctor[]> {
return this.doctors;
}
async getAllClients(): Promise<Client[]> {
return this.clients;
}
// o médico cuja conta de usuário é [userId] - usado para pré-selecionar,
// para um médico logado, a agenda do próprio médico
getDoctorByUserId(userId: number): Doctor | null {
return this.doctors.find((d) => d.userId === userId) ?? null;
}
// ------------------------------------------------ delegações simples
getAllSlots(doctorId: number): Promise<Slot[]> {
return this.business.getAllSlots(doctorId);
}
getDoctorDayAppointments(doctorId: number, day: string): Promise<Appointment[]> {
return this.business.getDoctorDayAppointments(doctorId, day);
}
getClientById(id: number): Promise<Client | null> {
return this.business.getClientById(id);
}
getDoctorById(id: number): Promise<Doctor | null> {
return this.business.getDoctorById(id);
}
getAppointmentById(id: number): Promise<Appointment | null> {
return this.business.getAppointmentById(id);
}
getSlotById(id: number): Promise<Slot | null> {
return this.business.getSlotById(id);
}
getDoctorDaySchedule(doctorId: number, day: string): Promise<DoctorDaySchedule | null> {
return this.business.getDoctorDaySchedule(doctorId, day);
}
// sem cache aqui: o que importa são os dados mais recentes (um paciente
// que acabou de atualizar ou excluir sua conta)
getClientByUserId(userId: number): Promise<Client | null> {
return this.business.getClientByUserId(userId);
}
getClientUpcomingAppointments(clientId: number): Promise<Appointment[]> {
return this.business.getClientUpcomingAppointments(clientId);
}
addAppointment(day: string, slot: Slot, client: Client): Promise<Appointment> {
return this.business.addAppointment(day, slot, client);
}
deleteAppointment(appointment: Appointment): Promise<void> {
return this.business.deleteAppointment(appointment);
}
// ------------------------------------------------ escritas => recarregar
async addDoctor(data: PersonData): Promise<Doctor> {
const doctor = await this.business.addDoctor(data);
await this.reloadDoctors();
return doctor;
}
async editDoctor(id: number, data: PersonData): Promise<Doctor> {
const doctor = await this.business.editDoctor(id, data);
await this.reloadDoctors();
return doctor;
}
async deleteDoctor(id: number): Promise<void> {
await this.business.deleteDoctor(id);
await this.reloadDoctors();
}
async addClient(data: PersonData): Promise<Client> {
const client = await this.business.addClient(data);
await this.reloadClients();
return client;
}
async editClient(id: number, data: PersonData): Promise<Client> {
const client = await this.business.editClient(id, data);
await this.reloadClients();
return client;
}
async deleteClient(id: number): Promise<void> {
await this.business.deleteClient(id);
await this.reloadClients();
}
}
|
Vamos comentar este código:
- linha 25: o serviço tem a mesma interface que a camada de negócio: para os controllers, ele é a camada de negócio. Ele fica entre as duas para armazenar em memória (escopo de aplicação, veja o Capítulo 6) as listas de médicos e de clientes, que são exibidas em quase todas as páginas;
- linha 29: a camada de negócio é injetada por meio de seu token;
- linhas 34–37: [onModuleInit] é chamado pelo [NestJS] quando o módulo está construído, antes de o servidor iniciar: as listas são lidas na inicialização. Se o banco de dados estiver inacessível, a aplicação termina com uma mensagem clara;
- linhas 49–55: as listas são servidas a partir da memória;
- linhas 59–61: a conta de um médico: um médico logado vê imediatamente a sua própria agenda;
- linhas 65–109: as demais chamadas são repassadas sem alteração;
- linhas 113–145: qualquer operação de escrita envolvendo médicos ou clientes atualiza a lista correspondente. Como este serviço é o único ponto de entrada para a camada de negócio, a regra “escrita = atualização do cache” é implementada apenas aqui, e o cache não pode ficar desatualizado.
11.13.6. src/web/views/handlebars-helpers.ts
| // =========================================================================
// web/views/handlebars-helpers.ts
// -------------------------------------------------------------------------
// Handlebars é deliberadamente uma linguagem de template SEM LÓGICA: nenhuma
// expressão JavaScript nas views, apenas {{variables}},
// blocos {{#if}} / {{#each}}... Quando uma view precisa de um pouco mais, nós
// damos a ela um "helper": uma função TypeScript, chamável a partir da view.
//
// A aplicação precisa de apenas quatro helpers:
// {{t 'KEY'}} tradução (equivalente ao pipe `| translate`)
// {{t 'KEY' name=person.lastName}} tradução com parâmetro(s)
// {{#if (eq a b)}} comparação de igualdade
// {{#if (or a b)}} verdadeiro se pelo menos um dos argumentos for verdadeiro
// {{active currentPath '/doctors'}} "active" se a página atual estiver sob este caminho
// =========================================================================
import { HelperOptions } from 'handlebars';
import { Language, DEFAULT_LANGUAGE, isLanguage, translate } from '../i18n';
// o módulo 'hbs' não tem declarações de tipos: descrevemos aqui o pouco
// que usamos dele
interface Hbs {
registerHelper(name: string, fn: (...args: any[]) => unknown): void;
}
export function registerHelpers(hbs: Hbs): void {
// O último argumento recebido por um helper é sempre o objeto [options]
// do Handlebars: options.hash contém os parâmetros nomeados (name=...) e
// options.data.root o modelo COMPLETO da página - portanto também res.locals.lang,
// o idioma escolhido (veja view-context.ts), mesmo dentro de um {{#each}}.
hbs.registerHelper('t', (key: unknown, options: HelperOptions) => {
const lang = options.data?.root?.lang;
const language: Language = isLanguage(lang) ? lang : DEFAULT_LANGUAGE;
// o texto retornado é então escapado pelo Handlebars ({{ }} e não {{{ }}}):
// um nome digitado pelo usuário, portanto, não pode injetar HTML
return typeof key === 'string' ? translate(language, key, options.hash) : '';
});
hbs.registerHelper('eq', (a: unknown, b: unknown) => a === b);
// ...args: todos os argumentos; o último é o objeto [options]
// do Handlebars (veja acima), que separamos antes de testar os outros
hbs.registerHelper('or', (...args: unknown[]) => args.slice(0, -1).some(Boolean));
hbs.registerHelper('active', (path: unknown, prefix: unknown) =>
typeof path === 'string' && typeof prefix === 'string' && path.startsWith(prefix) ? 'active' : '',
);
}
|
- linhas 31–37: o helper de tradução (veja o Exemplo 22);
- linha 39: a verificação de igualdade (veja o Exemplo 16);
- linha 43: verdadeiro se qualquer um dos argumentos for verdadeiro. [...args] recebe todos os argumentos; o último é o objeto [options] do [Handlebars], que é descartado;
- linhas 45–47: a classe [active] do menu atual (veja o Exemplo 16).
| // =========================================================================
// web/models/person-form.dto.ts
// -------------------------------------------------------------------------
// Os campos dos formulários de "person" e suas restrições. Três
// formulários compartilham os mesmos campos de identidade (título, nome, sobrenome):
//
// PersonFieldsDto title, firstName, lastName
// ├─ PersonFormDto + login / password OPCIONAIS, version
// │ (o ADMIN adiciona ou edita um médico / cliente)
// ├─ RegistrationFormDto + login / password / confirmação OBRIGATÓRIOS
// │ (um paciente cria sua conta)
// └─ MyAccountFormDto + login, nova senha opcional,
// senha ATUAL obrigatória, version
// (um paciente edita sua conta)
//
// A herança de classes também vale para os decoradores do class-validator:
// uma classe filha herda as restrições dos campos de sua classe pai.
//
// As mensagens de erro são CHAVES de tradução (veja i18n/*.json).
// @Transform(...) (class-transformer) limpa a entrada ANTES da
// validação: espaços extras removidos, campos opcionais deixados vazios
// convertidos em `undefined`, login convertido para minúsculas, version convertida em
// número (tudo o que vem de um formulário HTML é uma string).
//
// A verificação "password = confirmation" envolve DOIS campos:
// ela é feita pelo controller, após a validação de cada campo.
// =========================================================================
import { Transform } from 'class-transformer';
import { IsIn, IsInt, IsNotEmpty, IsOptional, Matches, MaxLength, MinLength } from 'class-validator';
export const TITLES = ['Mr', 'Mme', 'Melle'];
const clean = ({ value }: { value: unknown }) => (typeof value === 'string' ? value.trim() : value);
const emptyToUndefined = ({ value }: { value: unknown }) =>
typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
const cleanLogin = ({ value }: { value: unknown }) => emptyToUndefined({ value })?.toLowerCase();
// uma senha não é "cleaned" (espaços podem fazer parte dela)
const passwordOrUndefined = ({ value }: { value: unknown }) =>
typeof value === 'string' && value !== '' ? value : undefined;
const numberOrUndefined = ({ value }: { value: unknown }) =>
value === undefined || value === '' ? undefined : Number(value);
// login: letras minúsculas, dígitos, ponto, hífen, sublinhado - no máximo 30 caracteres
const LOGIN_FORMAT = /^[a-z0-9._-]{1,30}$/;
// tamanho mínimo de uma senha ESCOLHIDA por um paciente
export const PASSWORD_MIN = 6;
// ------------------------------------------------------------------ base comum
export class PersonFieldsDto {
@IsIn(TITLES, { message: 'ERRORS.INVALID_TITLE' })
title: string;
// tamanhos máximos = os das colunas SQL (VARCHAR(20))
@Transform(clean)
@IsNotEmpty({ message: 'ERRORS.FIRSTNAME_REQUIRED' })
@MaxLength(20, { message: 'ERRORS.FIRSTNAME_TOO_LONG' })
firstName: string;
@Transform(clean)
@IsNotEmpty({ message: 'ERRORS.LASTNAME_REQUIRED' })
@MaxLength(20, { message: 'ERRORS.LASTNAME_TOO_LONG' })
lastName: string;
}
// ------------------------------------------------------------------ ADMIN
export class PersonFormDto extends PersonFieldsDto {
// opcional (veja PersonData, business.interface.ts)
@Transform(cleanLogin)
@IsOptional()
@Matches(LOGIN_FORMAT, { message: 'ERRORS.INVALID_LOGIN' })
login?: string;
// opcional; no máximo 72 caracteres (além disso, o bcrypt ignora o restante)
@Transform(passwordOrUndefined)
@IsOptional()
@MaxLength(72, { message: 'ERRORS.PASSWORD_TOO_LONG' })
password?: string;
// campo oculto do formulário de edição (bloqueio otimista)
@Transform(numberOrUndefined)
@IsOptional()
@IsInt({ message: 'ERRORS.INVALID_FORM' })
version?: number;
}
// ------------------------------------------------------------------ cadastro de um paciente
export class RegistrationFormDto extends PersonFieldsDto {
@Transform(cleanLogin)
@IsNotEmpty({ message: 'ERRORS.LOGIN_REQUIRED' })
@Matches(LOGIN_FORMAT, { message: 'ERRORS.INVALID_LOGIN' })
login: string;
@Transform(passwordOrUndefined)
@IsNotEmpty({ message: 'ERRORS.PASSWORD_REQUIRED' })
@MinLength(PASSWORD_MIN, { message: 'ERRORS.PASSWORD_TOO_SHORT' })
@MaxLength(72, { message: 'ERRORS.PASSWORD_TOO_LONG' })
password: string;
@Transform(passwordOrUndefined)
@IsNotEmpty({ message: 'ERRORS.CONFIRMATION_REQUIRED' })
confirmation: string;
}
// ------------------------------------------------------------------ "Manage my account"
export class MyAccountFormDto extends PersonFieldsDto {
@Transform(cleanLogin)
@IsNotEmpty({ message: 'ERRORS.LOGIN_REQUIRED' })
@Matches(LOGIN_FORMAT, { message: 'ERRORS.INVALID_LOGIN' })
login: string;
// opcional: vazio = senha inalterada
@Transform(passwordOrUndefined)
@IsOptional()
@MinLength(PASSWORD_MIN, { message: 'ERRORS.PASSWORD_TOO_SHORT' })
@MaxLength(72, { message: 'ERRORS.PASSWORD_TOO_LONG' })
password?: string;
@Transform(passwordOrUndefined)
@IsOptional()
confirmation?: string;
// a senha ATUAL, exigida para qualquer alteração na conta
@Transform(passwordOrUndefined)
@IsNotEmpty({ message: 'ERRORS.CURRENT_PASSWORD_REQUIRED' })
currentPassword: string;
@Transform(numberOrUndefined)
@IsOptional()
@IsInt({ message: 'ERRORS.INVALID_FORM' })
version?: number;
}
|
Vamos comentar este código:
- linha 32: os tratamentos possíveis;
- linhas 34–42: as funções de limpeza aplicadas por [@Transform] antes da validação: remoção de espaços, campos vazios reduzidos a [undefined] (para que [@IsOptional] os aceite), login em minúsculas, versão convertida em número. A senha não é saneada: seus espaços fazem parte dela;
- linha 45: o formato de um nome de usuário, descrito por uma expressão regular;
- linhas 50–64: os campos de identidade, comuns a três formulários. Os comprimentos máximos são os das colunas SQL. As mensagens são chaves de tradução;
- linhas 67–85: o formulário do ADMIN (médico ou cliente): nome de usuário e senha opcionais, e a versão para o bloqueio otimista. [extends]: a classe herda os campos e decoradores de sua classe pai. A senha deve ter 72 caracteres ou menos; o bcrypt ignora os caracteres além desse limite;
- linhas 88–103: um paciente cria uma conta: nome de usuário e senha obrigatórios, com no mínimo seis caracteres, e confirmação;
- linhas 106–132: um paciente modificando sua conta: nova senha opcional, senha atual obrigatória.
| // =========================================================================
// web/helpers/form.helper.ts
// -------------------------------------------------------------------------
// Validação de um formulário HTML com class-validator.
//
// O servidor JSON deixava a validação para o ValidationPipe global: em
// caso de erro, ele respondia 400 Bad Request por conta própria - o que convém a um
// cliente JavaScript, que então exibe o erro à sua maneira. Para uma página
// HTML, ao contrário, queremos EXIBIR o formulário NOVAMENTE, com os valores
// já digitados e uma mensagem sob cada campo inválido. Por isso chamamos
// o class-validator nós mesmos, para manter o controle sobre o que acontece depois.
// =========================================================================
import { ClassConstructor, plainToInstance } from 'class-transformer';
import { validate } from 'class-validator';
import { TITLES } from '../models/person-form.dto';
// erros por campo: { lastName: 'ERRORS.LASTNAME_REQUIRED', ... } - cada
// mensagem é uma CHAVE de tradução (veja os decoradores dos DTOs)
export type FormErrors = Record<string, string>;
export interface ValidationResult<T> {
dto: T; // os dados, convertidos e limpos (veja os @Transform dos DTOs)
errors: FormErrors | null; // null = formulário válido
}
export async function validateForm<T extends object>(
cls: ClassConstructor<T>,
body: Record<string, unknown>,
): Promise<ValidationResult<T>> {
// plainToInstance: transforma o objeto simples recebido ({ lastName: ' dupont ' })
// em uma instância da classe DTO, aplicando seus @Transform(...)
const dto = plainToInstance(cls, body);
// validate: verifica todas as restrições (@IsNotEmpty, @MaxLength...);
// forbidUnknownValues:false porque validamos um objeto que nós mesmos construímos
const violations = await validate(dto, { forbidUnknownValues: false });
if (violations.length === 0) {
return { dto, errors: null };
}
const errors: FormErrors = {};
for (const violation of violations) {
// mantemos apenas a primeira mensagem de cada campo
errors[violation.property] = Object.values(violation.constraints ?? {})[0] ?? 'ERRORS.INVALID_FORM';
}
return { dto, errors };
}
// -------------------------------------------------------------------------
// os campos do formulário envolvidos em cada erro de negócio de "input"
// (uma duplicidade): são destacados em vermelho, com a mensagem no rodapé da página
// -------------------------------------------------------------------------
export const BUSINESS_ERROR_FIELDS: Record<string, string[]> = {
'ERRORS.LOGIN_TAKEN': ['login'],
'ERRORS.DOCTOR_ALREADY_EXISTS': ['firstName', 'lastName'],
'ERRORS.PATIENT_ALREADY_EXISTS': ['firstName', 'lastName'],
};
// { firstName: true, lastName: true }: os campos a destacar em vermelho (is-invalid) -
// os que têm uma mensagem de validação, mais eventuais outros
export function invalidFields(errors: FormErrors, others: string[] = []): Record<string, boolean> {
const fields: Record<string, boolean> = {};
for (const field of [...Object.keys(errors), ...others]) {
fields[field] = true;
}
return fields;
}
// as opções da lista suspensa "Title", com a de [value] selecionada
export function titleOptions(value: string): { value: string; selected: boolean }[] {
return TITLES.map((t) => ({ value: t, selected: t === value }));
}
|
- linhas 27–30: validação do formulário, como no Exemplo 19. A opção [forbidUnknownValues: false] é necessária porque estamos validando um objeto gerado por [plainToInstance], e não um recebido do [ValidationPipe];
- linhas 52–56: certos erros de negócio se referem a campos específicos (por exemplo, um nome de usuário já em uso): esses campos serão destacados em vermelho, com a mensagem aparecendo na parte inferior da página;
- linhas 60–66: os campos a serem destacados em vermelho;
- linhas 69–71: as opções da lista de tratamentos, com a selecionada em destaque (veja o exemplo 18).
11.13.9. src/web/helpers/dates.helper.ts
| // =========================================================================
// web/helpers/dates.helper.ts
// -------------------------------------------------------------------------
// Pequenas funções sobre datas no formato "yyyy-MM-dd" (o da
// coluna appointments.day e do campo <input type="date"> dos formulários).
// =========================================================================
// data de hoje: definida na camada de negócio, que precisa dela para
// suas regras de negócio - nós apenas a reexportamos aqui
export { today } from '../../business/dates';
// true se [day] for uma data que existe, no formato yyyy-MM-dd
// (mesma verificação do servidor JSON: "2026-02-30" é recusada)
export function isValidDate(day: unknown): day is string {
if (typeof day !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(day)) {
return false;
}
const date = new Date(`${day}T00:00:00Z`);
return !isNaN(date.getTime()) && date.toISOString().slice(0, 10) === day;
}
// "8:05" em vez de "8:5"
export function formatTime(h: number, m: number): string {
return `${h}:${twoDigits(m)}`;
}
// "mercredi 23 septembre 2026" / "Wednesday 23 September 2026", conforme o idioma
// (Intl.DateTimeFormat: a API de formatação de datas embutida no JavaScript)
export function formatDay(day: string, language: string): string {
return new Intl.DateTimeFormat(language === 'en' ? 'en-GB' : 'fr-FR', {
dateStyle: 'full',
timeZone: 'UTC', // "2026-09-23T00:00:00Z" deve continuar sendo dia 23, qualquer que seja o fuso horário do servidor
}).format(new Date(`${day}T00:00:00Z`));
}
function twoDigits(n: number): string {
return n.toString().padStart(2, '0');
}
|
- Linha 10: a data atual é definida na camada de negócio; este módulo a reexporta: os controllers importam todas as funções de data de um único local;
- linhas 14–20: uma data [yyyy-mm-dd] que existe (veja o Exemplo 12);
- linhas 29–34: uma data por extenso, conforme o idioma. A opção [timeZone: 'UTC'] evita um deslocamento de um dia quando o servidor não está configurado para o horário de Greenwich.
11.13.10. src/web/helpers/patient.helper.ts
| // =========================================================================
// web/helpers/patient.helper.ts
// -------------------------------------------------------------------------
// O paciente (entidade Client) correspondente ao usuário logado.
//
// O token JWT contém apenas o id da CONTA (users.id). Para um papel USER,
// o cliente correspondente é encontrado pela coluna clients.user.
//
// Se não houver nenhum, a conta foi excluída desde o login
// (pelo próprio paciente em outra aba, ou pelo ADMIN) enquanto
// o token ainda é válido: tratamos como uma sessão expirada
// (UnauthorizedException -> volta para a página de login, veja
// HtmlExceptionFilter).
// =========================================================================
import { UnauthorizedException } from '@nestjs/common';
import { ApplicationModelService } from '../application-model.service';
import { ConnectedUser } from '../../auth/jwt.strategy';
import { Client } from '../../entities/client.entity';
import { Person } from '../../entities/person.entity';
// "Mme Alice DURAND"
export function label(p: Person): string {
return `${p.title} ${p.firstName} ${p.lastName}`;
}
export async function connectedPatient(
application: ApplicationModelService,
user: ConnectedUser,
): Promise<Client> {
const client = await application.getClientByUserId(user.userId);
if (client === null) {
throw new UnauthorizedException();
}
return client;
}
|
- linhas 23–25: “Mme Alice DURAND”;
- linhas 27–30: o cadastro do paciente logado, recuperado a partir de sua conta. Se ele não existir mais (conta excluída em outra aba, ou pelo ADMIN, embora o token ainda seja válido), um erro 401 é retornado: redirecionamento para a página de login.
11.14. A camada web: os controllers
11.14.1. src/web/controllers/language.controller.ts
| // =========================================================================
// web/controllers/language.controller.ts
// -------------------------------------------------------------------------
// GET /language/fr, GET /language/en: os dois botões FR / EN da
// barra de navegação. A escolha é armazenada em um cookie (o cliente Angular
// a mantinha no localStorage), depois voltamos para a página de onde viemos.
// Rota sem proteção: o idioma deve poder ser alterado antes do login.
// =========================================================================
import { Controller, Get, NotFoundException, Param, Req, Res } from '@nestjs/common';
import { Request, Response } from 'express';
import { isLanguage } from '../i18n';
import { COOKIE_LANGUAGE } from '../view-context';
const ONE_YEAR = 365 * 24 * 3600 * 1000;
@Controller('language')
export class LanguageController {
@Get(':language')
change(@Param('language') language: string, @Req() req: Request, @Res() res: Response): void {
if (!isLanguage(language)) {
throw new NotFoundException();
}
res.cookie(COOKIE_LANGUAGE, language, { maxAge: ONE_YEAR, sameSite: 'lax', httpOnly: true });
res.redirect(originPage(req));
}
}
// a página anterior, segundo o cabeçalho HTTP "Referer" enviado pelo
// navegador. Apenas seu caminho é mantido (/schedule?...): redirecionar para
// um endereço completo fornecido pela requisição permitiria enviar
// o usuário para outro site (a chamada vulnerabilidade de "open redirect").
function originPage(req: Request): string {
const referer = req.get('referer');
if (!referer) {
return '/';
}
try {
const url = new URL(referer);
return url.pathname.startsWith('/language/') ? '/' : url.pathname + url.search;
} catch {
return '/';
}
}
|
O controller do Exemplo 22. Observe: se a página de origem for ela própria uma página [/language/...] (linha 40), a requisição é redirecionada para a raiz do site para evitar um loop infinito.
| // =========================================================================
// web/controllers/schedule.controller.ts
// -------------------------------------------------------------------------
// 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.
// É o equivalente, no lado do servidor, dos componentes Angular
// <app-doctor-day-picker>, <app-agenda> e <app-booking-dialog>.
//
// 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: é possível recarregá-la, salvá-la nos favoritos,
// usar o botão "Back" do navegador - sem uma única linha
// de JavaScript.
//
// O que cada usuário vê e pode fazer:
//
// | papel | horário ocupado exibido | Book | Cancel |
// |---------------|-----------------------------------|--------------------|---------|
// | ADMIN, DOCTOR | nome do paciente | para um paciente | sim |
// | | | escolhido em uma | |
// | USER (patient)| "Booked", ou SEU nome se for | para si mesmo, se | não (*) |
// | | sua própria consulta | não tiver nenhuma | |
// | | | futura | |
//
// (*) o paciente cancela sua consulta na 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 "View page source" o revelaria, caso contrário).
//
// 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).
// =========================================================================
import { BadRequestException, Body, Controller, Get, Post, Query, Render, Req, Res, UseGuards } from '@nestjs/common';
import { Request, Response } from 'express';
import { ApplicationModelService } from '../application-model.service';
import { JwtAuthGuard } from '../../auth/jwt-auth.guard';
import { RolesGuard } from '../../auth/roles.guard';
import { Roles } from '../../auth/roles.decorator';
import { ConnectedUser } from '../../auth/jwt.strategy';
import { BusinessException } from '../../business/business.exception';
import { flash } from '../view-context';
import { today, isValidDate, formatTime } from '../helpers/dates.helper';
import { label, connectedPatient } from '../helpers/patient.helper';
import { Client } from '../../entities/client.entity';
import { Person } from '../../entities/person.entity';
type AuthenticatedRequest = Request & { user: ConnectedUser };
// ----------------------------------------------------------------- modelo da view
// (o que views/schedule.hbs exibe - apenas dados já formatados
// E já filtrados conforme o papel: a view não decide nada)
interface OptionView {
id: number;
label: string; // "Mme Marie PELISSIER"
selected: boolean;
}
interface ScheduleRowView {
slotId: number;
time: string; // "8:00 - 8:20"
free: boolean;
patient: string | null; // nome exibido para um horário ocupado; null = "Booked"
mine: boolean; // a consulta do paciente logado
bookable: boolean; // exibir o botão "Book"?
bookUrl: string;
appointmentId: number | null; // definido apenas se o botão "Cancel" for exibido
}
interface ScheduleView {
doctor: string;
day: string;
rows: ScheduleRowView[];
}
interface BookingView {
slotId: number;
time: string;
// ADMIN / DOCTOR: a lista de pacientes para escolher
clients: OptionView[];
// USER: o paciente é o próprio usuário
patient: string | null;
}
export interface ScheduleModel {
pageTitle: string;
doctors: OptionView[];
doctorId: number | null;
day: string;
schedule: ScheduleView | null;
booking: BookingView | null;
backUrl: string; // a agenda exibida, sem o diálogo de marcação
// paciente que já tem uma consulta futura: a mensagem que explica
// por que não há botão "Book"
info: string | null;
error: string | null;
}
// o que o controller sabe sobre o usuário, para decidir o que exibir
interface Rights {
manager: boolean; // ADMIN ou DOCTOR
patient: Client | null; // o cliente logado (papel USER), null caso contrário
patientCanBook: boolean; // USER sem consulta futura
}
@UseGuards(JwtAuthGuard, RolesGuard)
@Controller('schedule')
export class ScheduleController {
constructor(private readonly application: ApplicationModelService) {}
// -----------------------------------------------------------------------
// GET /schedule
// @Render('schedule'): o objeto retornado pelo método se torna o modelo da
// view views/schedule.hbs (+ o conteúdo de res.locals, veja view-context.ts).
// -----------------------------------------------------------------------
@Get()
@Render('schedule')
async show(
@Req() req: AuthenticatedRequest,
@Query('doctorId') rawDoctorId?: string,
@Query('day') rawDay?: string,
@Query('book') rawBook?: string,
): Promise<ScheduleModel> {
let error: string | null = null;
const rights = await this.rights(req.user);
// o dia: o da URL se for válido, hoje caso contrário
let day = today();
if (rawDay !== undefined) {
if (isValidDate(rawDay)) {
day = rawDay;
} else {
error = 'ERRORS.INVALID_DATE';
}
}
const dayBookable = day >= today();
// o médico: o da URL; na falta dele, para um médico logado, o próprio médico
let doctorId = positiveInteger(rawDoctorId);
if (rawDoctorId === undefined && req.user.role === 'DOCTOR') {
doctorId = this.application.getDoctorByUserId(req.user.userId)?.id ?? null;
}
const doctors = (await this.application.getAllDoctors()).map((d) => option(d, d.id === doctorId));
// a agenda, se um médico for escolhido (e a data for válida)
let schedule: ScheduleView | null = null;
if (doctorId !== null && error === null) {
const doctorSchedule = await this.application.getDoctorDaySchedule(doctorId, day);
if (doctorSchedule === null) {
error = 'ERRORS.DOCTOR_NOT_FOUND';
} else {
schedule = {
doctor: label(doctorSchedule.doctor),
day,
rows: doctorSchedule.doctorDaySlots.map(({ slot, appointment }) => {
const free = appointment === null;
// a consulta do paciente logado?
const mine = !free && rights.patient !== null && appointment.clientId === rights.patient.id;
return {
slotId: slot.id,
time: `${formatTime(slot.startHour, slot.startMinute)} - ${formatTime(slot.endHour, slot.endMinute)}`,
free,
// O ponto de confidencialidade: um paciente recebe o nome apenas
// de SUA consulta; para as outras, null (a view exibe "Booked")
patient: free ? null : rights.manager || mine ? label(appointment.client) : null,
mine,
bookable: free && dayBookable && (rights.manager || rights.patientCanBook),
bookUrl: scheduleUrl(doctorId as number, day, slot.id),
appointmentId: !free && rights.manager ? appointment.id : null,
};
}),
};
}
}
// o diálogo de marcação: somente se o horário solicitado puder ser
// marcado por este usuário
let booking: BookingView | null = null;
const slotId = positiveInteger(rawBook);
const row = schedule?.rows.find((r) => r.slotId === slotId && r.bookable);
if (row) {
booking = {
slotId: row.slotId,
time: row.time,
clients: rights.manager ? (await this.application.getAllClients()).map((c) => option(c, false)) : [],
patient: rights.patient ? label(rights.patient) : null,
};
}
return {
pageTitle: 'SCHEDULE.PAGE_TITLE',
doctors,
doctorId,
day,
schedule,
booking,
backUrl: doctorId !== null ? scheduleUrl(doctorId, day) : '/schedule',
info: rights.patient !== null && !rights.patientCanBook ? 'SCHEDULE.ALREADY_BOOKED_INFO' : null,
error,
};
}
// -----------------------------------------------------------------------
// 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 que um paciente esperto marcasse em nome de outra pessoa.
//
// Padrão "Post / Redirect / Get": qualquer que seja o resultado, não
// construímos uma página aqui - definimos uma mensagem flash e redirecionamos
// para a agenda (veja flash(), view-context.ts).
// -----------------------------------------------------------------------
@Post('book')
@Roles('ADMIN', 'DOCTOR', 'USER')
async book(
@Body() body: Record<string, string>,
@Req() req: AuthenticatedRequest,
@Res() res: Response,
): Promise<void> {
const { doctorId, day } = readScheduleRequest(body);
const slotId = positiveInteger(body.slotId);
if (slotId === null) {
throw new BadRequestException();
}
let client: Client | null;
if (req.user.role === 'USER') {
client = await connectedPatient(this.application, req.user);
} else {
const clientId = positiveInteger(body.clientId);
if (clientId === null) {
// nenhum paciente escolhido: o diálogo de marcação é aberto novamente
flash(res, { type: 'danger', key: 'ERRORS.CHOOSE_PATIENT' });
return res.redirect(scheduleUrl(doctorId, day, slotId));
}
client = await this.application.getClientById(clientId);
}
const slot = await this.application.getSlotById(slotId);
if (client === null) {
flash(res, { type: 'danger', key: 'ERRORS.PATIENT_NOT_FOUND' });
} else if (slot === null || slot.doctorId !== doctorId) {
flash(res, { type: 'danger', key: 'ERRORS.SLOT_NOT_FOUND' });
} else {
try {
// as regras (não no passado, apenas uma consulta futura por
// paciente, horário livre) são verificadas pela camada de negócio
await this.application.addAppointment(day, slot, client);
flash(res, { type: 'success', key: 'SCHEDULE.BOOKED' });
} catch (e) {
// mesma regra, mas uma mensagem na 2ª pessoa quando é o próprio paciente
// quem marca ("You already have..." em vez de "This patient...")
if (
req.user.role === 'USER' &&
e instanceof BusinessException &&
e.key === 'ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT'
) {
flash(res, { type: 'danger', key: 'SCHEDULE.ALREADY_BOOKED_INFO' });
} else {
flashBusinessError(res, e);
}
}
}
res.redirect(scheduleUrl(doctorId, day));
}
// -----------------------------------------------------------------------
// POST /schedule/cancel campos: appointmentId, doctorId, day
// (um paciente cancela SUA consulta em "My area", não daqui)
// -----------------------------------------------------------------------
@Post('cancel')
@Roles('ADMIN', 'DOCTOR')
async cancel(@Body() body: Record<string, string>, @Res() res: Response): Promise<void> {
const { doctorId, day } = readScheduleRequest(body);
const appointmentId = positiveInteger(body.appointmentId);
if (appointmentId === null) {
throw new BadRequestException();
}
const appointment = await this.application.getAppointmentById(appointmentId);
if (appointment === null) {
// já cancelada (por outra pessoa, ou clique duplo)
flash(res, { type: 'danger', key: 'ERRORS.APPOINTMENT_NOT_FOUND' });
} else {
await this.application.deleteAppointment(appointment);
flash(res, { type: 'success', key: 'SCHEDULE.CANCELLED' });
}
res.redirect(scheduleUrl(doctorId, day));
}
// -----------------------------------------------------------------------
// quem está logado, e o que essa pessoa pode fazer nesta página?
// -----------------------------------------------------------------------
private async rights(user: ConnectedUser): Promise<Rights> {
if (user.role !== 'USER') {
return { manager: true, patient: null, patientCanBook: false };
}
const patient = await connectedPatient(this.application, user);
const upcoming = await this.application.getClientUpcomingAppointments(patient.id);
return { manager: false, patient, patientCanBook: upcoming.length === 0 };
}
}
// ----------------------------------------------------------------- funções utilitárias
// "3" -> 3 ; "", "abc", "-2", undefined -> null
function positiveInteger(value: unknown): number | null {
const n = Number(value);
return typeof value === 'string' && value !== '' && Number.isInteger(n) && n > 0 ? n : null;
}
// os campos ocultos doctorId / day, comuns aos dois formulários POST
function readScheduleRequest(body: Record<string, string>): { doctorId: number; day: string } {
const doctorId = positiveInteger(body.doctorId);
if (doctorId === null || !isValidDate(body.day)) {
throw new BadRequestException(); // -> página "invalid request" (veja HtmlExceptionFilter)
}
return { doctorId, day: body.day };
}
function scheduleUrl(doctorId: number, day: string, book?: number): string {
const params = new URLSearchParams({ doctorId: String(doctorId), day });
if (book !== undefined) {
params.set('book', String(book));
}
return `/schedule?${params.toString()}`;
}
function option(p: Person, selected: boolean): OptionView {
return { id: p.id, label: label(p), selected };
}
// uma BusinessException vira uma mensagem flash; qualquer outro erro é uma
// anomalia real, que deixamos subir até o HtmlExceptionFilter
function flashBusinessError(res: Response, e: unknown): void {
if (e instanceof BusinessException) {
flash(res, { type: 'danger', key: e.key, params: e.params });
return;
}
throw e;
}
|
A página principal da aplicação. Vamos percorrer este código seção por seção.
11.14.2.1. A seção de URL da página
Os comentários das linhas 9–14 descrevem as rotas. Observe que a janela de reserva não é aberta pelo [JavaScript]: é um parâmetro da URL ([book=7]) que instrui o servidor a exibir a página com a janela aberta. O botão “Book” é, portanto, simplesmente um link. A página inteira é descrita por sua URL: você pode recarregá-la, adicioná-la aos favoritos ou usar o botão “Voltar” do navegador.
11.14.2.2. O template da view
- linha 56: o tipo da requisição de uma rota protegida: uma requisição do [Express] cujo campo [user] foi definido pelo [JwtAuthGuard];
- linhas 62–106: o template da view é tipado. A view recebe apenas dados já formatados ([time: "8:00 - 8:20"]) e filtrados de acordo com o papel do usuário; ela não toma nenhuma decisão. Em [ScheduleRowView] (linhas 68–77), [patient] é igual a [null] quando o usuário não tem permissão para ver o nome do paciente; [bookable] e [appointmentId] determinam se os botões “Book” e “Cancel” devem ser exibidos;
- linhas 109–113: o que o controller sabe sobre o usuário logado.
11.14.2.3. GET /schedule
- linhas 115–116: todas as rotas exigem um usuário logado. Sem [@Roles] na classe, todos os papéis têm acesso à página;
- linhas 127–132: os três parâmetros da URL, todos opcionais, recebidos como strings e convertidos mais adiante;
- linhas 137–145: a data solicitada, se válida; caso contrário, hoje. Só é possível agendar consultas a partir de hoje;
- linhas 148–151: o médico solicitado; caso contrário, um médico logado vê a sua própria agenda;
- linha 153: a lista suspensa de médicos, recuperada do cache;
- linhas 157–184: a agenda, calculada pela camada de negócio, é convertida em linhas de tabela. A linha 175 é o ponto de controle de privacidade da aplicação: um paciente recebe apenas o nome de sua própria consulta. Para os demais, o modelo contém [null], e a view exibe “Booked”. O nome não é simplesmente ocultado pela view: ele nunca é enviado ao navegador;
- linhas 188–198: a janela de reserva só é aberta se o horário solicitado puder ser reservado por esse usuário. Um administrador seleciona o paciente em uma lista; um paciente reserva para si mesmo;
- linhas 200–210: o template [info] explica a um paciente que já tem uma consulta por que ele não vê um botão “Book”.
11.14.2.4. POST /schedule/book
- linha 225: os três papéis podem fazer uma reserva;
- linha 231: os campos [doctorId] e [day] — que ficam ocultos no formulário — permitem que o usuário volte à agenda exibida;
- linhas 238–239: para um paciente, o campo [clientId] é ignorado: o paciente sempre reserva para si mesmo. Confiar nesse campo, enviado pelo navegador, permitiria que um paciente malicioso fizesse uma reserva em nome de outra pessoa;
- Linhas 242–246: um administrador que não selecionou um paciente volta para a janela de reserva, acompanhado de uma mensagem;
- linhas 251–254: o horário deve existir e pertencer ao médico da agenda;
- linhas 256–261: as regras de negócio são verificadas pela camada de negócio. Para um paciente, a mensagem “This patient already has an upcoming appointment” é substituída por uma mensagem dirigida diretamente ao paciente;
- Linha 275: padrão PRG: seja qual for o resultado, exibe-se uma mensagem pop-up e redireciona-se para a agenda.
11.14.2.5. POST /schedule/cancel
Linhas 282–299: reservado aos administradores; um paciente cancela sua consulta a partir de “Minha área”. Uma consulta que já foi cancelada (por duplo clique ou por outro administrador) resulta em uma mensagem de erro, e não em uma página de erro.
11.14.2.6. Permissões e funções utilitárias
- Linhas 304–311: um administrador tem todas as permissões; um paciente pode fazer uma reserva se não tiver nenhuma consulta futura;
- linhas 317–320: conversão segura de um parâmetro em identificador;
- linhas 323–329: campos ocultos inválidos só podem vir de uma requisição forjada manualmente: erro 400;
- linhas 331–337: [URLSearchParams] constrói uma query string corretamente codificada;
- linhas 345–351: uma [BusinessException] se transforma em uma mensagem flash; qualquer outra exceção é propagada até o filtro de exceção.
11.14.3. src/web/controllers/persons.controller.ts
| // =========================================================================
// web/controllers/persons.controller.ts
// -------------------------------------------------------------------------
// O gerenciamento de médicos e o de clientes (reservado ao ADMIN) são
// IDÊNTICOS: mesma lista, mesmo formulário, mesmas regras. Em vez de
// escrever as mesmas rotas duas vezes, nós as escrevemos uma só vez nesta
// classe ABSTRATA, herdada por DoctorsController (@Controller('doctors'))
// e ClientsController (@Controller('clients')). Cada subclasse só
// precisa fornecer sua "configuração": quais métodos chamar, quais
// rótulos exibir.
//
// Os decoradores de rota (@Get, @Post...) definidos AQUI são herdados: o NestJS
// percorre toda a cadeia de protótipos da classe do controller. Obtemos
// portanto, para cada uma das duas subclasses:
//
// 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 em /clients). As views também são compartilhadas:
// views/persons/list.hbs e views/persons/form.hbs.
// =========================================================================
import { Body, Get, HttpCode, NotFoundException, Param, ParseIntPipe, Post, Render, Res } from '@nestjs/common';
import { Response } from 'express';
import { ApplicationModelService } from '../application-model.service';
import { PersonData } from '../../business/business.interface';
import { BusinessException } from '../../business/business.exception';
import { Person } from '../../entities/person.entity';
import { flash } from '../view-context';
import {
BUSINESS_ERROR_FIELDS,
FormErrors,
invalidFields,
titleOptions,
validateForm,
} from '../helpers/form.helper';
import { PersonFormDto } from '../models/person-form.dto';
// as chaves de tradução específicas de cada tipo de pessoa
export interface PersonKeys {
title: string; // "Doctors"
add: string; // "Add a doctor"
edit: string; // "Edit a doctor"
empty: string; // "No doctors."
confirmDelete: string; // "Delete this doctor and their account?"
added: string; // "Doctor {name} has been added (login: {login})."
edited: string;
deleted: string;
}
export interface PersonsConfig<T extends Person> {
url: string; // '/doctors' ou '/clients'
keys: PersonKeys;
list(): Promise<T[]>;
find(id: number): Promise<T | null>;
add(data: PersonData): Promise<T>;
edit(id: number, data: PersonData): Promise<T>;
delete(id: number): Promise<void>;
}
// os valores exibidos nos campos do formulário
interface FormValues {
title: string;
firstName: string;
lastName: string;
login: string;
version: number | null;
}
export abstract class PersonsController<T extends Person> {
protected abstract readonly config: PersonsConfig<T>;
constructor(protected readonly application: ApplicationModelService) {}
// -----------------------------------------------------------------------
// GET /doctors (ou /clients)
// -----------------------------------------------------------------------
@Get()
@Render('persons/list')
async list() {
const persons = await this.config.list();
return {
pageTitle: this.config.keys.title,
keys: this.config.keys,
addUrl: `${this.config.url}/add`,
persons: persons.map((p) => ({
title: p.title,
firstName: p.firstName,
lastName: p.lastName,
login: p.user?.login ?? '',
editUrl: `${this.config.url}/${p.id}/edit`,
deleteUrl: `${this.config.url}/${p.id}/delete`,
})),
};
}
// -----------------------------------------------------------------------
// GET /doctors/add
// -----------------------------------------------------------------------
@Get('add')
addForm(@Res() res: Response): void {
this.showForm(res, null, { title: 'Mr', firstName: '', lastName: '', login: '', version: null });
}
// -----------------------------------------------------------------------
// POST /doctors/add
// -----------------------------------------------------------------------
@Post('add')
@HttpCode(200) // se o formulário for exibido novamente (veja auth.controller.ts)
async add(@Body() body: Record<string, unknown>, @Res() res: Response): Promise<void> {
const { dto, errors } = await validateForm(PersonFormDto, body);
if (errors !== null) {
return this.showForm(res, null, enteredValues(dto), errors);
}
try {
const person = await this.config.add(dto);
flash(res, { type: 'success', key: this.config.keys.added, params: messageParams(person) });
res.redirect(this.config.url);
} catch (e) {
this.showBusinessError(res, null, enteredValues(dto), e);
}
}
// -----------------------------------------------------------------------
// GET /doctors/:id/edit
// ParseIntPipe: se :id não for um inteiro, o NestJS lança uma
// BadRequestException (página "invalid request", veja HtmlExceptionFilter)
// -----------------------------------------------------------------------
@Get(':id/edit')
async editForm(@Param('id', ParseIntPipe) id: number, @Res() res: Response): Promise<void> {
const person = await this.config.find(id);
if (person === null) {
throw new NotFoundException();
}
this.showForm(res, id, {
title: person.title,
firstName: person.firstName,
lastName: person.lastName,
login: person.user?.login ?? '',
version: person.version,
});
}
// -----------------------------------------------------------------------
// POST /doctors/:id/edit
// -----------------------------------------------------------------------
@Post(':id/edit')
@HttpCode(200)
async edit(
@Param('id', ParseIntPipe) id: number,
@Body() body: Record<string, unknown>,
@Res() res: Response,
): Promise<void> {
const { dto, errors } = await validateForm(PersonFormDto, body);
if (errors !== null) {
return this.showForm(res, id, enteredValues(dto), errors);
}
try {
const person = await this.config.edit(id, dto);
flash(res, { type: 'success', key: this.config.keys.edited, params: messageParams(person) });
res.redirect(this.config.url);
} catch (e) {
this.showBusinessError(res, id, enteredValues(dto), e);
}
}
// -----------------------------------------------------------------------
// POST /doctors/:id/delete
// (a confirmação "Are you sure?" é solicitada pelo navegador antes
// de o formulário ser enviado, veja public/js/app.js)
// -----------------------------------------------------------------------
@Post(':id/delete')
async delete(@Param('id', ParseIntPipe) id: number, @Res() res: Response): Promise<void> {
const person = await this.config.find(id);
try {
await this.config.delete(id);
flash(res, { type: 'success', key: this.config.keys.deleted, params: messageParams(person) });
} catch (e) {
if (!(e instanceof BusinessException)) {
throw e;
}
flash(res, { type: 'danger', key: e.key, params: e.params });
}
res.redirect(this.config.url);
}
// ----------------------------------------------------------------- métodos privados
// id === null: formulário de criação; caso contrário: formulário de edição
// errors : mensagem sob cada campo recusado pela validação
// error : A mensagem de erro da página, exibida no rodapé da página
// (veja views/partials/errors.hbs)
// otherFields : campos a destacar em vermelho SEM mensagem própria (ex.:
// nome + sobrenome de um homônimo - a mensagem fica no rodapé)
private showForm(
res: Response,
id: number | null,
values: FormValues,
errors: FormErrors = {},
error: string | null = null,
otherFields: string[] = [],
): void {
const creating = id === null;
res.render('persons/form', {
pageTitle: creating ? this.config.keys.add : this.config.keys.edit,
creating,
action: creating ? `${this.config.url}/add` : `${this.config.url}/${id}/edit`,
listUrl: this.config.url,
values,
titles: titleOptions(values.title),
errors,
invalidFields: invalidFields(errors, otherFields),
error: error ?? (Object.keys(errors).length > 0 ? 'ERRORS.INVALID_FORM' : null),
});
}
// uma regra de negócio recusou a escrita: o formulário é exibido novamente,
// com a entrada do usuário e a mensagem da camada de negócio
private showBusinessError(res: Response, id: number | null, values: FormValues, e: unknown): void {
if (!(e instanceof BusinessException)) {
throw e; // anomalia real -> HtmlExceptionFilter (página 500)
}
if (e.key === 'ERRORS.DOCTOR_NOT_FOUND' || e.key === 'ERRORS.PATIENT_NOT_FOUND') {
// excluído nesse meio tempo por outro ADMIN: volta para a lista
flash(res, { type: 'danger', key: e.key });
return res.redirect(this.config.url);
}
// a mensagem fica no rodapé da página; os campos envolvidos, se houver, são
// destacados em vermelho para que o usuário veja imediatamente o que corrigir
this.showForm(res, id, values, {}, e.key, BUSINESS_ERROR_FIELDS[e.key] ?? []);
}
}
// o que o usuário digitou (senha excluída: ela nunca é devolvida ao navegador)
function enteredValues(dto: PersonFormDto): FormValues {
return {
title: dto.title ?? '',
firstName: typeof dto.firstName === 'string' ? dto.firstName : '',
lastName: typeof dto.lastName === 'string' ? dto.lastName : '',
login: dto.login ?? '',
version: dto.version ?? null,
};
}
// {name} e {login} das mensagens "added / updated / deleted"
function messageParams(person: Person | null): Record<string, string> {
if (person === null) {
return { name: '', login: '' };
}
return { name: `${person.firstName} ${person.lastName}`, login: person.user?.login ?? '' };
}
|
O tratamento de médicos e clientes é idêntico. Em vez de escrever dois controllers semelhantes, criamos uma classe abstrata da qual os dois controllers herdam.
- linhas 44–53: os textos específicos de cada tipo de pessoa (chaves de tradução);
- linhas 55–63: a configuração fornecida por cada subclasse: a URL base, os textos e as funções a chamar para listar, pesquisar, adicionar, modificar e excluir;
- linha 75: um campo abstrato: cada subclasse deve defini-lo;
- linhas 82–99: a lista. Os decoradores de rota aplicados a uma classe pai são herdados: o [NestJS] os encontra percorrendo a cadeia de protótipos. O modelo contém, para cada pessoa, a URL de seus botões;
- linhas 104–107 e 112–126: a adição, em três etapas, como no Exemplo 28: validação, camada de negócio, PRG;
- linhas 133–146 e 151–157: modificação. [ParseIntPipe] rejeita um identificador não numérico (erro 400);
- linhas 176–189: exclusão. A pessoa é recuperada antes para exibir seu nome na mensagem de confirmação;
- linhas 199–206: o formulário, tanto para a criação ([id === null]) quanto para a modificação;
- linhas 223–235: uma pessoa que foi excluída nesse meio-tempo é devolvida à lista; os demais erros de negócio reexibem o formulário, com os campos relevantes destacados em vermelho;
- linhas 239–247: os valores a reexibir (nunca a senha).
11.14.4. src/web/controllers/doctors.controller.ts
| // =========================================================================
// web/controllers/doctors.controller.ts
// -------------------------------------------------------------------------
// Gerenciamento dos médicos (somente papel ADMIN). Todas as rotas são
// herdadas de PersonsController (veja persons.controller.ts): resta
// aqui apenas dizer O QUE chamar e QUAIS rótulos exibir.
//
// @Roles('ADMIN') definido na CLASSE vale para todas as suas rotas,
// inclusive as herdadas (o RolesGuard procura os metadados no método,
// depois na classe - veja auth/roles.guard.ts).
// =========================================================================
import { Controller, UseGuards } from '@nestjs/common';
import { JwtAuthGuard } from '../../auth/jwt-auth.guard';
import { RolesGuard } from '../../auth/roles.guard';
import { Roles } from '../../auth/roles.decorator';
import { ApplicationModelService } from '../application-model.service';
import { Doctor } from '../../entities/doctor.entity';
import { PersonsConfig, PersonsController } from './persons.controller';
@UseGuards(JwtAuthGuard, RolesGuard)
@Roles('ADMIN')
@Controller('doctors')
export class DoctorsController extends PersonsController<Doctor> {
protected readonly config: PersonsConfig<Doctor> = {
url: '/doctors',
keys: {
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: () => this.application.getAllDoctors(),
find: (id) => this.application.getDoctorById(id),
add: (data) => this.application.addDoctor(data),
edit: (id, data) => this.application.editDoctor(id, data),
delete: (id) => this.application.deleteDoctor(id),
};
// um construtor explícito, para que o TypeScript emita NESTA classe os
// metadados de tipo dos parâmetros, de que o NestJS precisa para
// saber o que injetar (a classe pai, abstrata e sem decorador,
// não tem nenhum)
constructor(application: ApplicationModelService) {
super(application);
}
}
|
- linhas 21–22: reservado ao ADMIN. [@Roles] aplicado à classe vale para todas as suas rotas, inclusive as herdadas;
- linhas 25–42: a configuração: as chaves de tradução para médicos e os métodos do cache a chamar;
- linhas 48–50: um construtor explícito, embora ele apenas chame o construtor da classe pai; é isso que permite ao compilador gerar, para esta classe, os metadados de tipo de que o [NestJS] precisa para saber o que injetar.
11.14.5. src/web/controllers/clients.controller.ts
| // =========================================================================
// web/controllers/clients.controller.ts
// -------------------------------------------------------------------------
// Gerenciamento dos clientes (os PACIENTES do consultório), somente papel ADMIN.
// Mesmo princípio do DoctorsController (veja seus comentários).
// =========================================================================
import { Controller, UseGuards } from '@nestjs/common';
import { JwtAuthGuard } from '../../auth/jwt-auth.guard';
import { RolesGuard } from '../../auth/roles.guard';
import { Roles } from '../../auth/roles.decorator';
import { ApplicationModelService } from '../application-model.service';
import { Client } from '../../entities/client.entity';
import { PersonsConfig, PersonsController } from './persons.controller';
@UseGuards(JwtAuthGuard, RolesGuard)
@Roles('ADMIN')
@Controller('clients')
export class ClientsController extends PersonsController<Client> {
protected readonly config: PersonsConfig<Client> = {
url: '/clients',
keys: {
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: () => this.application.getAllClients(),
find: (id) => this.application.getClientById(id),
add: (data) => this.application.addClient(data),
edit: (id, data) => this.application.editClient(id, data),
delete: (id) => this.application.deleteClient(id),
};
constructor(application: ApplicationModelService) {
super(application);
}
}
|
O mesmo controller, para os clientes.
11.14.6. src/web/controllers/registration.controller.ts
| // =========================================================================
// web/controllers/registration.controller.ts
// -------------------------------------------------------------------------
// "Create a patient account": um paciente que ainda não tem conta
// a cria por conta própria. Rotas SEM proteção (ainda não se tem conta,
// por definição):
//
// POST /register/access botão "Create a patient account" da página de
// autenticação: verifica o captcha DESSA página, depois abre o
// formulário
// GET /register o formulário
// POST /register a criação, depois volta para a página de login
//
// O fluxo é protegido contra bots 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 digitado corretamente, o servidor
// emite um passe (veja auth/registration-pass.service.ts);
// 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/attempt-limiter.service.ts).
//
// A conta criada é exatamente a que o ADMIN criaria na página
// "Clients" (mesmo método da camada de negócio: addClient), exceto
// que o paciente ESCOLHE seu login e sua senha (obrigatórios, com
// confirmação).
// =========================================================================
import { Body, Controller, Get, HttpCode, Post, Req, Res } from '@nestjs/common';
import { Request, Response } from 'express';
import { ApplicationModelService } from '../application-model.service';
import { CaptchaService } from '../../auth/captcha.service';
import { AttemptLimiterService } from '../../auth/attempt-limiter.service';
import { COOKIE_REGISTRATION_PASS, RegistrationPassService } from '../../auth/registration-pass.service';
import { BusinessException } from '../../business/business.exception';
import { flash } from '../view-context';
import {
BUSINESS_ERROR_FIELDS,
FormErrors,
invalidFields,
titleOptions,
validateForm,
} from '../helpers/form.helper';
import { RegistrationFormDto, PASSWORD_MIN } from '../models/person-form.dto';
interface RegistrationValues {
title: string;
firstName: string;
lastName: string;
login: string;
}
@Controller('register')
export class RegistrationController {
constructor(
private readonly application: ApplicationModelService,
private readonly captchaService: CaptchaService,
private readonly limiter: AttemptLimiterService,
private readonly passes: RegistrationPassService,
) {}
// -----------------------------------------------------------------------
// POST /register/access campos: captchaId, captcha (os da página de
// autenticação; login e password, também enviados, são ignorados)
// -----------------------------------------------------------------------
@Post('access')
access(@Body() body: Record<string, unknown>, @Req() req: Request, @Res() res: Response): void {
const ip = req.ip ?? 'unknown';
// contas demais criadas recentemente a partir deste endereço: não adianta ir além
const minutes = this.limiter.registrationBlockMinutes(ip);
if (minutes > 0) {
flash(res, { type: 'danger', key: 'ERRORS.TOO_MANY_ACCOUNTS', params: { minutes: String(minutes) } });
return res.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 (!this.captchaService.verify(body.captchaId, body.captcha)) {
this.limiter.loginFailure(ip, '');
flash(res, { type: 'danger', key: 'ERRORS.CAPTCHA_BEFORE_ACCOUNT' });
return res.redirect('/login');
}
// captcha correto: emitimos o passe e abrimos o formulário
res.cookie(COOKIE_REGISTRATION_PASS, this.passes.issue(), this.passes.cookieOptions());
res.redirect('/register');
}
// -----------------------------------------------------------------------
// GET /register
// -----------------------------------------------------------------------
@Get()
form(@Req() req: Request, @Res() res: Response): void {
if (!this.hasPass(req, res)) {
return;
}
this.show(res, { title: 'Mr', firstName: '', lastName: '', login: '' });
}
// -----------------------------------------------------------------------
// POST /register
// -----------------------------------------------------------------------
@Post()
@HttpCode(200) // se o formulário for exibido novamente (veja auth.controller.ts)
async create(@Body() body: Record<string, unknown>, @Req() req: Request, @Res() res: Response): Promise<void> {
if (!this.hasPass(req, res)) {
return;
}
const ip = req.ip ?? 'unknown';
const { dto, errors } = await validateForm(RegistrationFormDto, body);
const values: RegistrationValues = {
title: dto.title ?? 'Mr',
firstName: typeof dto.firstName === 'string' ? dto.firstName : '',
lastName: typeof dto.lastName === 'string' ? dto.lastName : '',
login: dto.login ?? '',
};
// 1. contas demais criadas recentemente a partir deste endereço?
const minutes = this.limiter.registrationBlockMinutes(ip);
if (minutes > 0) {
return this.show(res, values, {}, 'ERRORS.TOO_MANY_ACCOUNTS', [], { minutes: String(minutes) });
}
// 2. todos os erros de entrada de uma vez (campos + confirmação):
// o usuário os corrige todos de uma só vez
const allErrors: FormErrors = { ...(errors ?? {}) };
if (!allErrors.password && !allErrors.confirmation && dto.password !== dto.confirmation) {
allErrors.confirmation = 'ERRORS.PASSWORDS_DIFFER';
}
if (Object.keys(allErrors).length > 0) {
return this.show(res, values, allErrors);
}
// 3. a criação (cliente + conta USER, em uma transação)
try {
await this.application.addClient({
title: dto.title,
lastName: dto.lastName,
firstName: dto.firstName,
login: dto.login,
password: dto.password,
});
} catch (e) {
if (!(e instanceof BusinessException)) {
throw e;
}
// login ou nome + sobrenome já em uso: o passe continua válido
return this.show(res, values, {}, e.key, BUSINESS_ERROR_FIELDS[e.key] ?? []);
}
// 4. o passe foi usado: ele não permitirá criar uma 2ª conta
this.passes.consume(req.cookies?.[COOKIE_REGISTRATION_PASS]);
res.clearCookie(COOKIE_REGISTRATION_PASS, { path: '/register' });
this.limiter.registrationSuccess(ip);
// 5. volta para a página de login, com o login preenchido
flash(res, { type: 'success', key: 'REGISTRATION.DONE', params: { login: dto.login } });
res.redirect(`/login?${new URLSearchParams({ login: dto.login }).toString()}`);
}
// ----------------------------------------------------------------- métodos privados
// sem passe válido: volta para a página de autenticação
private hasPass(req: Request, res: Response): boolean {
if (this.passes.isValid(req.cookies?.[COOKIE_REGISTRATION_PASS])) {
return true;
}
flash(res, { type: 'danger', key: 'ERRORS.CAPTCHA_BEFORE_ACCOUNT' });
res.redirect('/login');
return false;
}
// o formulário; nenhuma senha é devolvida ao navegador
private show(
res: Response,
values: RegistrationValues,
errors: FormErrors = {},
error: string | null = null,
otherFields: string[] = [],
errorParams?: Record<string, string>,
): void {
res.render('account/registration', {
pageTitle: 'REGISTRATION.TITLE',
values,
titles: titleOptions(values.title),
errors,
invalidFields: invalidFields(errors, otherFields),
error: error ?? (Object.keys(errors).length > 0 ? 'ERRORS.INVALID_FORM' : null),
errorParams,
passwordMin: PASSWORD_MIN,
});
}
}
|
Vamos comentar este código:
- linhas 69–91: o botão “Create a patient account” da página de login envia o formulário de login para este endereço (atributo [formaction]; veja o Exemplo 20). O CAPTCHA da página é verificado; se estiver correto, um passe é armazenado em um cookie e o navegador é redirecionado para o formulário;
- linhas 96–102: o formulário, mas somente com um passe válido;
- linhas 109–163: criação da conta: passe, limite de tempo, validação (incluindo a verificação de que a senha coincide com sua confirmação), criação pela camada de negócio. Em seguida o passe é consumido, e o paciente é redirecionado para a página de login com seu nome de usuário já preenchido;
- linhas 168–175: sem um passe, volta-se à página de login com uma mensagem;
- linhas 178–185: o formulário. [passwordMin] é usado para o texto de ajuda (“At least 6 characters”).
11.14.7. src/web/controllers/patient-area.controller.ts
| // =========================================================================
// web/controllers/patient-area.controller.ts
// -------------------------------------------------------------------------
// 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 a 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 (connectedPatient), nunca um identificador enviado pelo navegador.
// Um paciente, portanto, não pode ver, nem editar, nem cancelar o que pertence
// a outro paciente, mesmo forjando suas próprias requisições.
//
// Qualquer atualização ou exclusão da conta exige a senha ATUAL:
// alguém que encontrasse uma sessão deixada aberta
// não poderia nem alterar a senha nem excluir a conta. Os erros de senha
// atual são contados como falhas de login (mesmo limite).
// =========================================================================
import { Body, Controller, Get, HttpCode, Post, Render, Req, Res, UseGuards } from '@nestjs/common';
import { Request, Response } from 'express';
import { ApplicationModelService } from '../application-model.service';
import { AuthService } from '../../auth/auth.service';
import { AttemptLimiterService } from '../../auth/attempt-limiter.service';
import { JwtAuthGuard } from '../../auth/jwt-auth.guard';
import { RolesGuard } from '../../auth/roles.guard';
import { Roles } from '../../auth/roles.decorator';
import { ConnectedUser } from '../../auth/jwt.strategy';
import { COOKIE_JWT, jwtCookieOptions } from '../../auth/auth.constants';
import { BusinessException } from '../../business/business.exception';
import { Client } from '../../entities/client.entity';
import { flash } from '../view-context';
import { formatTime, formatDay } from '../helpers/dates.helper';
import { label, connectedPatient } from '../helpers/patient.helper';
import {
BUSINESS_ERROR_FIELDS,
FormErrors,
invalidFields,
titleOptions,
validateForm,
} from '../helpers/form.helper';
import { MyAccountFormDto, PASSWORD_MIN } from '../models/person-form.dto';
type AuthenticatedRequest = Request & { user: ConnectedUser };
interface MyAccountValues {
title: string;
firstName: string;
lastName: string;
login: string;
version: number | null;
}
@UseGuards(JwtAuthGuard, RolesGuard)
@Roles('USER')
@Controller()
export class PatientAreaController {
constructor(
private readonly application: ApplicationModelService,
private readonly authService: AuthService,
private readonly limiter: AttemptLimiterService,
) {}
// -----------------------------------------------------------------------
// GET /my-area
// @Res({ passthrough: true }): acessamos a resposta (para ler o idioma em
// res.locals) SEM abrir mão do funcionamento normal do @Render.
// -----------------------------------------------------------------------
@Get('my-area')
@Render('patient/area')
async area(@Req() req: AuthenticatedRequest, @Res({ passthrough: true }) res: Response) {
const patient = await connectedPatient(this.application, req.user);
const appointments = await this.application.getClientUpcomingAppointments(patient.id);
return {
pageTitle: 'AREA.TITLE',
patient: label(patient),
appointments: appointments.map((appointment) => ({
id: appointment.id,
day: formatDay(appointment.day, res.locals.lang),
time: `${formatTime(appointment.slot.startHour, appointment.slot.startMinute)} - ${formatTime(appointment.slot.endHour, appointment.slot.endMinute)}`,
doctor: label(appointment.slot.doctor),
// link para a agenda do médico nesse dia: o paciente vê seu nome ali
scheduleUrl: `/schedule?${new URLSearchParams({ doctorId: String(appointment.slot.doctor.id), day: appointment.day })}`,
})),
};
}
// -----------------------------------------------------------------------
// POST /my-area/cancel campo: appointmentId
// -----------------------------------------------------------------------
@Post('my-area/cancel')
async cancelAppointment(
@Body() body: Record<string, string>,
@Req() req: AuthenticatedRequest,
@Res() res: Response,
): Promise<void> {
const patient = await connectedPatient(this.application, req.user);
const appointment = await this.application.getAppointmentById(Number(body.appointmentId) || 0);
// uma consulta que não existe e uma de OUTRO paciente recebem
// a mesma resposta: nada é revelado sobre as consultas de outras pessoas
if (appointment === null || appointment.clientId !== patient.id) {
flash(res, { type: 'danger', key: 'ERRORS.APPOINTMENT_NOT_FOUND' });
} else {
await this.application.deleteAppointment(appointment);
flash(res, { type: 'success', key: 'SCHEDULE.CANCELLED' });
}
res.redirect('/my-area');
}
// -----------------------------------------------------------------------
// GET /my-account
// -----------------------------------------------------------------------
@Get('my-account')
async accountForm(@Req() req: AuthenticatedRequest, @Res() res: Response): Promise<void> {
const patient = await connectedPatient(this.application, req.user);
this.show(res, {
title: patient.title,
firstName: patient.firstName,
lastName: patient.lastName,
login: patient.user.login,
version: patient.version,
});
}
// -----------------------------------------------------------------------
// POST /my-account
// -----------------------------------------------------------------------
@Post('my-account')
@HttpCode(200) // se o formulário for exibido novamente (veja auth.controller.ts)
async editAccount(
@Body() body: Record<string, unknown>,
@Req() req: AuthenticatedRequest,
@Res() res: Response,
): Promise<void> {
const patient = await connectedPatient(this.application, req.user);
const { dto, errors } = await validateForm(MyAccountFormDto, body);
const values: MyAccountValues = {
title: dto.title ?? patient.title,
firstName: typeof dto.firstName === 'string' ? dto.firstName : '',
lastName: typeof dto.lastName === 'string' ? dto.lastName : '',
login: dto.login ?? '',
version: dto.version ?? null,
};
const allErrors: FormErrors = { ...(errors ?? {}) };
if (!allErrors.password && dto.password !== undefined && dto.password !== dto.confirmation) {
allErrors.confirmation = 'ERRORS.PASSWORDS_DIFFER';
}
if (Object.keys(allErrors).length > 0) {
return this.show(res, values, allErrors);
}
// a senha atual
const passwordError = await this.checkCurrentPassword(req, patient, dto.currentPassword);
if (passwordError !== null) {
return this.show(
res,
values,
passwordError.key === 'ERRORS.WRONG_CURRENT_PASSWORD' ? { currentPassword: passwordError.key } : {},
passwordError.key,
[],
passwordError.params,
);
}
try {
const client = await this.application.editClient(patient.id, {
title: dto.title,
lastName: dto.lastName,
firstName: dto.firstName,
login: dto.login,
password: dto.password, // undefined = inalterada
version: dto.version,
});
// o login e o nome exibido estão NO token: emitimos
// um novo, senão a barra de navegação manteria o nome antigo
res.cookie(COOKIE_JWT, this.authService.createToken(client.user), jwtCookieOptions());
flash(res, { type: 'success', key: 'MY_ACCOUNT.UPDATED' });
res.redirect('/my-area');
} catch (e) {
if (!(e instanceof BusinessException)) {
throw e;
}
this.show(res, values, {}, e.key, BUSINESS_ERROR_FIELDS[e.key] ?? []);
}
}
// -----------------------------------------------------------------------
// POST /my-account/delete campo: deletePassword
// A conta, o cliente e TODAS as suas consultas desaparecem juntos,
// depois o paciente é desconectado.
// -----------------------------------------------------------------------
@Post('my-account/delete')
async deleteAccount(
@Body() body: Record<string, string>,
@Req() req: AuthenticatedRequest,
@Res() res: Response,
): Promise<void> {
const patient = await connectedPatient(this.application, req.user);
const passwordError = await this.checkCurrentPassword(req, patient, body.deletePassword);
if (passwordError !== null) {
flash(res, { type: 'danger', key: passwordError.key, params: passwordError.params });
return res.redirect('/my-account');
}
await this.application.deleteClient(patient.id);
res.clearCookie(COOKIE_JWT, { path: '/' });
flash(res, { type: 'success', key: 'MY_ACCOUNT.DELETED' });
res.redirect('/login');
}
// ----------------------------------------------------------------- métodos privados
// null se a senha atual estiver correta; caso contrário, a chave da mensagem
private async checkCurrentPassword(
req: Request,
patient: Client,
password: unknown,
): Promise<{ key: string; params?: Record<string, string> } | null> {
const ip = req.ip ?? 'unknown';
const login = patient.user.login;
const minutes = this.limiter.loginBlockMinutes(ip, login);
if (minutes > 0) {
return { key: 'ERRORS.TOO_MANY_ATTEMPTS', params: { minutes: String(minutes) } };
}
const ok =
typeof password === 'string' &&
password !== '' &&
(await this.authService.validateUser(login, password)) !== null;
if (!ok) {
this.limiter.loginFailure(ip, login);
return { key: 'ERRORS.WRONG_CURRENT_PASSWORD' };
}
return null;
}
private show(
res: Response,
values: MyAccountValues,
errors: FormErrors = {},
error: string | null = null,
otherFields: string[] = [],
errorParams?: Record<string, string>,
): void {
res.render('patient/account', {
pageTitle: 'MY_ACCOUNT.TITLE',
values,
titles: titleOptions(values.title),
errors,
invalidFields: invalidFields(errors, otherFields),
error: error ?? (Object.keys(errors).length > 0 ? 'ERRORS.INVALID_FORM' : null),
errorParams,
passwordMin: PASSWORD_MIN,
});
}
}
|
Vamos comentar este código:
- linhas 59–60: reservado aos pacientes;
- linhas 14–17: a regra de ouro deste controller: o paciente em questão é sempre aquele associado ao token, nunca um identificador enviado pelo navegador;
- linhas 74–91: a página “My area”. [@Res({ passthrough: true })] dá acesso à resposta (para ler o idioma em [res.locals] e formatar a data) sem abrir mão do [@Render] (veja o Exemplo 05);
- linhas 96–101: cancelamento de uma consulta. Uma consulta inexistente e a consulta de outro paciente recebem a mesma resposta: nenhuma informação sobre as consultas de outros pacientes é revelada;
- linhas 118–128: o formulário da conta, já preenchido;
- linhas 133–139: a atualização: validação, verificação da senha atual e, em seguida, a camada de negócio. O token contém o login e o nome de exibição: após uma atualização, um novo token é emitido (linha 182); caso contrário, a barra de navegação manteria o nome antigo;
- Linhas 198–203: exclusão da conta, do cadastro e de todas as consultas (usando o mesmo método da camada de negócio que o ADMIN), seguida de logout;
- linhas 219–223: a senha atual é exigida para qualquer alteração: quem encontrasse uma sessão deixada aberta não conseguiria alterar a senha nem excluir a conta. Os erros contam como falhas de login;
- linhas 241–248: o formulário.
11.15. As views
As views quase não têm decisões a tomar: seu template foi preparado pelos controllers. Cada view começa com um comentário [Handlebars] [{{!-- ... --}}] que descreve seu papel; esses comentários não aparecem nas páginas enviadas ao navegador.
11.15.1. Os arquivos de template e de partials
11.15.1.1. views/layout.hbs
| {{!--
==========================================================================
views/layout.hbs
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
O template COMUM a todas as páginas. O hbs o usa automaticamente
(arquivo chamado "layout.hbs" na raiz da pasta views): a página
solicitada pelo controller (schedule.hbs, login.hbs...) é inserida no
local de {{{body}}}.
Chaves triplas {{{ }}}: o conteúdo é inserido COMO ESTÁ, sem
escape - essencial aqui, pois [body] já é HTML pronto.
Em todos os outros lugares usamos {{ }}, que escapa os caracteres < > & " '
(proteção contra injeção de HTML por meio de um nome digitado, por exemplo).
Mensagens: um sucesso é exibido no TOPO da página ({{> flash}}), um
erro no PÉ, sobre um fundo rosa claro ({{> errors}}).
Equivalente a src/index.html + app.html do cliente Angular.
==========================================================================
--}}
<!doctype html>
<html lang="{{lang}}">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>{{t pageTitle}} - {{t 'APP.TITLE'}}</title>
<link rel="stylesheet" href="/bootstrap/css/bootstrap.min.css">
<link rel="stylesheet" href="/css/styles.css">
</head>
<body>
<div class="container py-4">
{{> navbar}}
{{> flash}}
{{{body}}}
{{> errors}}
</div>
{{!-- o diálogo "Are you sure?", oculto enquanto não é necessário --}}
{{> confirmation}}
<script src="/js/app.js"></script>
</body>
</html>
|
- linha 22: o idioma da página (veja o Exemplo 22);
- linha 26: o título, traduzido: a chave [pageTitle] é fornecida por cada ação;
- linhas 32–35: a barra de navegação, a mensagem de sucesso, a página e a área de erro;
- linhas 38–39: a janela de confirmação e seu script (veja o Exemplo 21).
11.15.1.2. views/partials/navbar.hbs
| {{!--
views/partials/navbar.hbs - a barra de navegação (inserida por {{> navbar}}).
Mesmo conteúdo que o do cliente Angular (título, FR/EN, papel, nome,
logout), mais um menu cujas entradas dependem do papel:
"Doctors" e "Clients" aparecem apenas para o ADMIN. É apenas uma
conveniência de exibição: a proteção real são os guards dos
controllers (um USER que digita /doctors manualmente recebe uma página 403).
Um paciente (USER) tem também o seu menu "My area".
--}}
<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 currentUser}}
<ul class="navbar-nav me-auto">
{{#if currentUser.isPatient}}
<li class="nav-item"><a class="nav-link {{active currentPath '/my-'}}" href="/my-area">{{t 'APP.MENU_MY_AREA'}}</a></li>
{{/if}}
<li class="nav-item"><a class="nav-link {{active currentPath '/schedule'}}" href="/schedule">{{t 'APP.MENU_SCHEDULE'}}</a></li>
{{#if currentUser.isAdmin}}
<li class="nav-item"><a class="nav-link {{active currentPath '/doctors'}}" href="/doctors">{{t 'APP.MENU_DOCTORS'}}</a></li>
<li class="nav-item"><a class="nav-link {{active currentPath '/clients'}}" href="/clients">{{t 'APP.MENU_PATIENTS'}}</a></li>
{{/if}}
</ul>
{{else}}
<div class="me-auto"></div>
{{/if}}
<div class="d-flex align-items-center gap-2">
{{!-- FR / EN: links simples (GET /language/fr), o idioma ativo destacado --}}
<div class="btn-group btn-group-sm" role="group" aria-label="FR / EN">
<a class="btn {{#if (eq lang 'fr')}}btn-light{{else}}btn-outline-light{{/if}}" href="/language/fr">FR</a>
<a class="btn {{#if (eq lang 'en')}}btn-light{{else}}btn-outline-light{{/if}}" href="/language/en">EN</a>
</div>
{{#if currentUser}}
<span class="badge text-bg-light text-primary">{{currentUser.role}}</span>
<span class="text-white">{{currentUser.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>
{{/if}}
</div>
</nav>
|
- linhas 14–25: os menus dependem do papel: “My area” para um paciente, “Doctors” e “Patients” para o ADMIN. Isso é apenas por conveniência; a segurança é garantida pelos guards dos controllers;
- linhas 31–34: os links FR / EN;
- linhas 36–43: o papel, o nome e o botão de logout em um formulário POST.
11.15.1.3. views/partials/flash.hbs
| {{!--
views/partials/flash.hbs - a mensagem de SUCESSO definida pela action
anterior (consulta agendada, médico adicionado...), exibida uma única
vez, no topo da página (veja src/web/view-context.ts).
Uma mensagem flash de ERRO, por sua vez, é exibida no pé da página, por
views/partials/errors.hbs.
--}}
{{#if (eq flash.type 'success')}}
<div class="alert alert-success" role="status">
{{t flash.key name=flash.params.name login=flash.params.login minutes=flash.params.minutes}}
</div>
{{/if}}
|
linha 10: a mensagem é uma chave; seus eventuais parâmetros ([name], [login], [minutes]) são passados ao helper [t].
11.15.1.4. views/partials/errors.hbs
| {{!--
==========================================================================
views/partials/errors.hbs - a zona de erros, no PÉ de cada página, sobre
um fundo rosa claro (classe .error-zone, veja public/css/styles.css).
Ela agrupa as duas fontes possíveis de erro:
- [error]: o erro da página exibida (formulário recusado, login ou
nome + sobrenome já usado, data inválida, senha incorreta...);
- uma mensagem flash de erro, definida pela action 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 no pé.
==========================================================================
--}}
{{#if (or error (eq flash.type 'danger'))}}
<div class="error-zone" role="alert">
{{#if error}}
<div>{{t error minutes=errorParams.minutes}}</div>
{{/if}}
{{#if (eq flash.type 'danger')}}
<div>{{t flash.key name=flash.params.name login=flash.params.login minutes=flash.params.minutes}}</div>
{{/if}}
</div>
{{/if}}
|
Linha 16: a área é exibida se houver um erro de página ou uma mensagem de erro flash: o helper [or] combina as duas condições, com [eq] usado como subexpressão.
11.15.1.5. views/partials/confirmation.hbs
| {{!--
==========================================================================
views/partials/confirmation.hbs - 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 diálogo para a página inteira, oculto (d-none) no início. Seus
rótulos são traduzidos aqui, pelo servidor, como o resto da página;
o pequeno script public/js/app.js apenas o exibe, coloca 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 agendamento (partials/booking.hbs).
==========================================================================
--}}
<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 --}}
<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 e atributos de acessibilidade: [role="alertdialog"] e [aria-labelledby] / [aria-describedby], que especificam o título e a mensagem lidos por um leitor de tela.
11.15.1.6. views/partials/captcha.hbs
| {{!--
==========================================================================
views/partials/captcha.hbs - o captcha da página de autenticação
(veja src/auth/captcha.service.ts). Ele protege tanto o login quanto
o acesso à criação de conta (botão "Create a patient account").
{{{captcha.svg}}}: chaves triplas, a imagem SVG é inserida COMO ESTÁ
na página. É seguro aqui porque esse SVG é construído pelo
próprio servidor (biblioteca svg-captcha) 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 informa ao servidor QUAL captcha verificar; a resposta
correta, por sua vez, nunca é enviada ao navegador.
"Another image" simplesmente recarrega a página (path = a URL atual).
==========================================================================
--}}
<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'}}">{{{captcha.svg}}}</div>
<a class="small" href="{{currentPath}}">{{t 'CAPTCHA.NEW_IMAGE'}}</a>
</div>
<input type="hidden" name="captchaId" value="{{captcha.id}}">
<input id="captcha" name="captcha" type="text" maxlength="10" autocomplete="off" autocapitalize="off" spellcheck="false" required
class="form-control {{#if invalidFields.captcha}}is-invalid{{/if}}">
{{#if errors.captcha}}
<div class="invalid-feedback">{{t errors.captcha}}</div>
{{else}}
<div class="form-text">{{t 'CAPTCHA.HELP'}}</div>
{{/if}}
</div>
|
- linha 20: a imagem SVG, inserida como está (chaves triplas): ela é gerada pelo servidor, sem nenhuma entrada do usuário;
- linha 21: “Another image” simplesmente recarrega a página;
- linha 23: o identificador do CAPTCHA, em um campo oculto.
11.15.1.7. views/partials/personFields.hbs
| {{!--
views/partials/personFields.hbs - 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 usa o modelo da página que o insere: values, titles,
errors (mensagem sob o campo) e invalidFields (moldura vermelha).
--}}
<div class="mb-3">
<label class="form-label" for="title">{{t 'PERSONS.TITLE_LABEL'}}</label>
<select id="title" name="title" class="form-select {{#if invalidFields.title}}is-invalid{{/if}}">
{{#each titles}}
<option value="{{value}}" {{#if selected}}selected{{/if}}>{{value}}</option>
{{/each}}
</select>
{{#if errors.title}}<div class="invalid-feedback">{{t errors.title}}</div>{{/if}}
</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 {{#if invalidFields.firstName}}is-invalid{{/if}}" value="{{values.firstName}}">
{{#if errors.firstName}}<div class="invalid-feedback">{{t errors.firstName}}</div>{{/if}}
</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 {{#if invalidFields.lastName}}is-invalid{{/if}}" value="{{values.lastName}}">
{{#if errors.lastName}}<div class="invalid-feedback">{{t errors.lastName}}</div>{{/if}}
</div>
</div>
|
Os campos de identidade, comuns a três formulários (veja o Exemplo 19). Um partial inserido sem parâmetros usa o template da página que o insere: [values], [titles], [errors], [invalidFields].
11.15.1.8. views/partials/booking.hbs
| {{!--
==========================================================================
views/partials/booking.hbs - o diálogo de agendamento.
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.
==========================================================================
--}}
<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="{{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="{{doctorId}}">
<input type="hidden" name="day" value="{{day}}">
<input type="hidden" name="slotId" value="{{booking.slotId}}">
{{#if booking.patient}}
{{!-- um paciente agenda para si mesmo: nenhuma 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>
{{#each booking.clients}}
<option value="{{id}}">{{label}}</option>
{{/each}}
</select>
{{/if}}
</div>
<div class="modal-footer">
<a class="btn btn-secondary" href="{{backUrl}}">{{t 'BOOKING_DIALOG.CANCEL'}}</a>
<button type="submit" class="btn btn-primary">{{t 'BOOKING_DIALOG.CONFIRM'}}</button>
</div>
</form>
</div>
</div>
|
- linhas 13–14: as classes do [Bootstrap] de uma janela modal, tornada visível “de forma fixa no código”: é o servidor que decide exibi-la;
- linha 19: fechar a janela significa seguir um link para a mesma página, sem o parâmetro [book];
- linhas 26–28: os campos ocultos do formulário;
- linhas 30–34: um paciente vê seu nome; um administrador seleciona o paciente em uma lista.
11.15.2. As páginas
11.15.2.1. views/login.hbs
| {{!--
==========================================================================
views/login.hbs - o formulário de login.
Equivalente a features/login/ do cliente Angular. 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 [error], exibido
no pé da página pelo layout.
==========================================================================
--}}
<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="{{login}}" required {{#unless login}}autofocus{{/unless}}>
</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 {{#if login}}autofocus{{/if}}>
</div>
{{> captcha}}
<button type="submit" class="btn btn-primary w-100">{{t 'LOGIN.SUBMIT'}}</button>
{{!-- ainda sem conta: um paciente pode criar uma por conta própria.
NÃO é um simples link: é um segundo botão de envio
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 20: o cursor é colocado no campo de login, ou no campo de senha se o login já for conhecido;
- linha 28: o CAPTCHA;
- linhas 41–42: o segundo botão envia o mesmo formulário para [/register/access] ([formaction]). [formnovalidate]: o navegador não exige nome de usuário e senha, pois eles não são necessários para criar uma conta.
11.15.2.2. views/schedule.hbs
| {{!--
==========================================================================
views/schedule.hbs - 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 agendamento (<app-booking-dialog>)
==========================================================================
--}}
{{!-- um possível erro (data inválida, médico desconhecido) é exibido
no pé da página pelo layout (veja views/partials/errors.hbs) --}}
{{!-- 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>
{{#each doctors}}
<option value="{{id}}" {{#if selected}}selected{{/if}}>{{label}}</option>
{{/each}}
</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="{{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 info}}
<div class="alert alert-info">
{{t info}} <a href="/my-area" class="alert-link">{{t 'APP.MENU_MY_AREA'}}</a>
</div>
{{/if}}
{{!-- 2. a agenda --}}
{{#if schedule}}
<div class="card p-3">
<h5>{{t 'SCHEDULE.TITLE_PREFIX'}} {{schedule.day}} - {{schedule.doctor}}</h5>
{{#if schedule.rows.length}}
<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>
{{#each schedule.rows}}
<tr {{#if bookable}}class="free-slot"{{/if}}>
<td>{{time}}</td>
<td>
{{!-- [patient] só é definido se o usuário tem permissão
para ver este nome (ADMIN, DOCTOR, ou o paciente para a SUA
consulta) - caso contrário, simplesmente "Booked" --}}
{{#if free}}
<span class="badge text-bg-success">{{t 'SCHEDULE.FREE'}}</span>
{{else if patient}}
<span class="badge {{#if mine}}text-bg-primary{{else}}text-bg-secondary{{/if}}">{{patient}}</span>
{{else}}
<span class="badge text-bg-secondary">{{t 'SCHEDULE.BOOKED_BY_OTHER'}}</span>
{{/if}}
</td>
<td>
{{!-- os botões exibidos foram decididos pelo controller
(bookable, appointmentId) de acordo com o papel do usuário --}}
{{#if bookable}}
{{!-- "Book" é um simples link: ele reabre esta página
com o diálogo de agendamento deste horário --}}
<a class="btn btn-sm btn-outline-success" href="{{bookUrl}}">{{t 'SCHEDULE.BOOK'}}</a>
{{/if}}
{{#if appointmentId}}
{{!-- "Cancel" ALTERA dados: portanto é um POST.
@root: o modelo da PÁGINA (dentro de um {{#each}},
nomes simples se referem aos campos da linha atual) --}}
<form method="post" action="/schedule/cancel" class="m-0"
data-confirmation="{{t 'SCHEDULE.CANCEL_CONFIRM'}}">
<input type="hidden" name="appointmentId" value="{{appointmentId}}">
<input type="hidden" name="doctorId" value="{{@root.doctorId}}">
<input type="hidden" name="day" value="{{@root.day}}">
<button type="submit" class="btn btn-sm btn-outline-danger">{{t 'SCHEDULE.CANCEL_APPOINTMENT'}}</button>
</form>
{{/if}}
</td>
</tr>
{{/each}}
</tbody>
</table>
{{else}}
<p class="text-muted mb-0">{{t 'SCHEDULE.NO_SLOTS'}}</p>
{{/if}}
</div>
{{else}}
<p class="text-muted">{{t 'SCHEDULE.EMPTY_STATE'}}</p>
{{/if}}
{{!-- 3. o diálogo de agendamento, somente se a URL contém &book=... --}}
{{#if booking}}
{{> booking}}
{{/if}}
|
- Linhas 16–35: seleção de um médico e de uma data: um formulário GET (veja o Exemplo 17). Um campo [type="date"] envia a data no formato [yyyy-mm-dd];
- Linhas 38–42: uma mensagem para um paciente que já tem uma consulta;
- linhas 59–96: uma linha por horário. [{{else if patient}}] lista os estados em sequência: disponível, reservado com nome visível, reservado sem nome (“Booked”);
- linha 80: “Book” é um link;
- linhas 86–92: “Cancel” é um formulário POST com confirmação. No loop, [@root.doctorId] refere-se ao campo do template da página, não ao da linha;
- linhas 108–110: a janela de reserva, se o controller a tiver preparado.
11.15.2.3. views/persons/list.hbs
| {{!--
==========================================================================
views/persons/list.hbs - a lista de médicos OU de clientes (ADMIN).
Uma única view para ambos: os rótulos específicos de cada um chegam em
[keys] (veja DoctorsController / ClientsController).
==========================================================================
--}}
<div class="d-flex justify-content-between align-items-center mb-3">
<h4 class="mb-0">{{t keys.title}}</h4>
<a class="btn btn-primary" href="{{addUrl}}">{{t keys.add}}</a>
</div>
<div class="card p-3">
{{#if persons.length}}
<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>
{{#each persons}}
<tr>
<td>{{title}}</td>
<td>{{firstName}}</td>
<td>{{lastName}}</td>
<td><code>{{login}}</code></td>
<td class="text-end">
<div class="d-inline-flex gap-2">
<a class="btn btn-sm btn-outline-primary" href="{{editUrl}}">{{t 'PERSONS.EDIT'}}</a>
{{!-- data-confirmation: um diálogo de confirmação será aberto
antes do envio do formulário (veja public/js/app.js) --}}
<form method="post" action="{{deleteUrl}}" class="m-0"
data-confirmation="{{t @root.keys.confirmDelete}}">
<button type="submit" class="btn btn-sm btn-outline-danger">{{t 'PERSONS.DELETE'}}</button>
</form>
</div>
</td>
</tr>
{{/each}}
</tbody>
</table>
{{else}}
<p class="text-muted mb-0">{{t keys.empty}}</p>
{{/if}}
</div>
|
Uma única view para médicos e clientes: os textos são fornecidos como chaves ([keys.title], [keys.add]...). Linha 38: [@root.keys] é necessário no loop.
| {{!--
==========================================================================
views/persons/form.hbs - criação OU atualização de um médico
ou de um cliente (ADMIN). [creating] distingue os dois casos.
Quando a entrada é recusada (campo vazio, login já em uso...), o
controller devolve ESTA view com:
- os valores já digitados (values.xxx);
- os campos com problema emoldurados em vermelho (invalidFields.xxx, classe
Bootstrap "is-invalid");
- sob um campo recusado pela validação, sua mensagem (errors.xxx);
- a mensagem de erro da página (error), exibida NO PÉ da página
pelo layout (veja views/partials/errors.hbs).
==========================================================================
--}}
<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 pageTitle}}</h5>
{{!-- novalidate: deixamos o SERVIDOR validar (é ele quem
dá a palavra final); as verificações do navegador (required...) são apenas uma
conveniência, que um usuário sempre pode contornar --}}
<form method="post" action="{{action}}" novalidate>
{{#unless creating}}
<input type="hidden" name="version" value="{{values.version}}">
{{/unless}}
{{!-- título, nome, sobrenome: partial comum a três formulários --}}
{{> personFields}}
<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 {{#if invalidFields.login}}is-invalid{{/if}}" value="{{values.login}}">
{{#if errors.login}}
<div class="invalid-feedback">{{t errors.login}}</div>
{{else}}
<div class="form-text">{{#if creating}}{{t 'PERSONS.LOGIN_HELP_CREATE'}}{{else}}{{t 'PERSONS.LOGIN_HELP_EDIT'}}{{/if}}</div>
{{/if}}
</div>
<div class="mb-4">
<label class="form-label" for="password">{{t 'PERSONS.PASSWORD_LABEL'}}</label>
{{!-- nunca preenchido previamente: a senha nunca volta ao navegador --}}
<input id="password" name="password" type="password" maxlength="72" autocomplete="new-password"
class="form-control {{#if invalidFields.password}}is-invalid{{/if}}">
{{#if errors.password}}
<div class="invalid-feedback">{{t errors.password}}</div>
{{else}}
<div class="form-text">{{#if creating}}{{t 'PERSONS.PASSWORD_HELP_CREATE'}}{{else}}{{t 'PERSONS.PASSWORD_HELP_EDIT'}}{{/if}}</div>
{{/if}}
</div>
<div class="d-flex gap-2">
<button type="submit" class="btn btn-primary">{{t 'PERSONS.SAVE'}}</button>
<a class="btn btn-secondary" href="{{listUrl}}">{{t 'PERSONS.BACK'}}</a>
</div>
</form>
</div>
</div>
</div>
|
- Linha 24: o endereço de envio ([action]) é fornecido pelo controller. [novalidate]: o servidor faz essa validação;
- Linhas 25–27: o número da versão, para uma modificação;
- linha 30: os campos de identidade;
- linhas 35–42: o login, com um texto de ajuda ou uma mensagem de erro;
- linhas 46–54: a senha, que nunca é preenchida previamente.
11.15.2.5. views/account/registration.hbs
| {{!--
==========================================================================
views/account/registration.hbs - "Create a patient account" (página pública,
veja RegistrationController). Mesmos campos de identidade do 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ó pode ser acessada depois de digitar
o da página de autenticação (botão "Create a patient account").
"Back to login" leva de volta à página de autenticação.
==========================================================================
--}}
<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>
{{> personFields}}
<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 {{#if invalidFields.login}}is-invalid{{/if}}" value="{{values.login}}">
{{#if errors.login}}
<div class="invalid-feedback">{{t errors.login}}</div>
{{else}}
<div class="form-text">{{t 'REGISTRATION.LOGIN_HELP'}}</div>
{{/if}}
</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 {{#if invalidFields.password}}is-invalid{{/if}}">
{{#if errors.password}}
<div class="invalid-feedback">{{t errors.password min=passwordMin}}</div>
{{else}}
<div class="form-text">{{t 'REGISTRATION.PASSWORD_HELP' min=passwordMin}}</div>
{{/if}}
</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 {{#if invalidFields.confirmation}}is-invalid{{/if}}">
{{#if errors.confirmation}}<div class="invalid-feedback">{{t errors.confirmation}}</div>{{/if}}
</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. Linha 42: o texto de ajuda tem um parâmetro — o comprimento mínimo da senha — fornecido pelo controller.
11.15.2.6. views/patient/area.hbs
| {{!--
==========================================================================
views/patient/area.hbs - "My area": a página inicial do paciente
(papel USER), exibida logo após o login (veja PatientAreaController).
- duas opções: [Manage my account] e [View a schedule];
- sua consulta futura, se tiver uma, com o meio de cancelá-la.
==========================================================================
--}}
<h4 class="mb-3">{{t 'AREA.HELLO' name=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 appointments.length}}
{{!-- normalmente apenas uma (regra "uma consulta futura por vez"),
mas a página pode exibir várias --}}
{{#each appointments}}
<div class="d-flex flex-wrap justify-content-between align-items-center gap-2 py-2 {{#unless @last}}border-bottom{{/unless}}">
<div>
<div class="fw-semibold">{{day}}, {{time}}</div>
<div class="text-muted">{{doctor}} - <a href="{{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="{{id}}">
<button type="submit" class="btn btn-outline-danger">{{t 'AREA.CANCEL_APPOINTMENT'}}</button>
</form>
</div>
{{/each}}
{{else}}
<p class="text-muted mb-0">{{t 'AREA.NO_APPOINTMENT'}}</p>
{{/if}}
</div>
|
- Linha 9: “Hello Mr Jean MARTIN”;
- Linhas 13–19: as duas opções, links;
- linhas 31–43: a próxima consulta. [{{#unless @last}}]: uma borda separa as consultas, exceto depois da última.
11.15.2.7. views/patient/account.hbs
| {{!--
==========================================================================
views/patient/account.hbs - "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.
==========================================================================
--}}
<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="{{values.version}}">
{{> personFields}}
<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 {{#if invalidFields.login}}is-invalid{{/if}}" value="{{values.login}}">
{{#if errors.login}}<div class="invalid-feedback">{{t errors.login}}</div>{{/if}}
</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 {{#if invalidFields.password}}is-invalid{{/if}}">
{{#if errors.password}}
<div class="invalid-feedback">{{t errors.password min=passwordMin}}</div>
{{else}}
<div class="form-text">{{t 'PERSONS.PASSWORD_HELP_EDIT'}}</div>
{{/if}}
</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 {{#if invalidFields.confirmation}}is-invalid{{/if}}">
{{#if errors.confirmation}}<div class="invalid-feedback">{{t errors.confirmation}}</div>{{/if}}
</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 {{#if invalidFields.currentPassword}}is-invalid{{/if}}">
{{#if errors.currentPassword}}
<div class="invalid-feedback">{{t errors.currentPassword}}</div>
{{else}}
<div class="form-text">{{t 'MY_ACCOUNT.CURRENT_PASSWORD_HELP'}}</div>
{{/if}}
</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 17–65: modificação da conta;
- linhas 72–80: exclusão, com confirmação. Dois formulários independentes na mesma página: cada um envia apenas os seus próprios campos.
11.15.2.8. views/error.hbs
| {{!--
views/error.hbs - a página de erro (403, 404, 400, 500), construída por
HtmlExceptionFilter (src/web/html-exception.filter.ts).
--}}
<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">{{code}}</h1>
<p class="lead">{{t message}}</p>
<div><a class="btn btn-primary" href="/">{{t 'ERROR_PAGE.BACK'}}</a></div>
</div>
</div>
</div>
|
A página de erro do filtro de exceção: o código HTTP e a mensagem traduzida.
11.16. Os dicionários
11.16.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]);
- linha 80: um texto com dois parâmetros, [{name}] e [{login}];
- linhas 98–137: mensagens de erro. São as chaves usadas pela [BusinessException] na camada de negócio, pelos decoradores de validação de formulários e pelo filtro de exceção.
11.16.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.17. Arquivos estáticos
11.17.1. public/css/styles.css
| /* =========================================================================
public/css/styles.css - alguns ajustes sobre o Bootstrap
(extraídos de src/styles.css do cliente Angular).
========================================================================= */
body {
background-color: #f5f7fa;
}
.free-slot:hover {
background-color: #e9f7ef;
}
/* -
.error-zone: as mensagens de erro, no fim da página, sobre um fundo rosa claro
(veja views/partials/errors.hbs).
position: sticky + bottom: se a página for mais alta que a janela (uma
agenda de 12 horários, por exemplo), a zona permanece colada na parte inferior
da janela em vez de desaparecer abaixo da dobra - sem nunca
cobrir o conteúdo quando a página é curta.
z-index: acima do fundo cinza do diálogo de reserva (.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 horário que pode ser reservado 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 das janelas modais;
- linhas 36–43: as duas opções de “My area” respondem à passagem do mouse;
- linhas 46–50: a moldura da imagem do CAPTCHA.
11.17.2. public/js/app.js
| // =========================================================================
// public/js/app.js - o ÚNICO JavaScript da aplicação.
// -------------------------------------------------------------------------
// A aplicação inteira funciona sem JavaScript. Este script acrescenta uma
// comodidade: antes de enviar um formulário que traz o atributo
// data-confirmation="...", um diálogo modal pergunta "Are you sure?"
// (o próprio diálogo está na página: views/partials/confirmation.hbs).
// Se o JavaScript estiver desativado, 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 ficam 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 ao qual 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 por distração 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 do diálogo (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 do diálogo
}
});
// 3. teclado: Escape fecha o diálogo; Tab permanece DENTRO do diálogo
// (senão 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 completo da janela de confirmação do Exemplo 21:
- linhas 17–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 antes de a janela abrir, para o qual o foco retorna quando a janela é fechada;
- linhas 26–35: o foco é colocado em “No, go back”; um toque acidental na tecla Enter não exclui nada;
- linhas 37–43: a janela é ocultada e o foco é restaurado;
- 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 você tenha clicado em um elemento dentro dele;
- linhas 71–86: a tecla Esc fecha a janela; a tecla Tab faz o foco circular dentro da janela, em vez de deixá-lo passar para a página escurecida ao fundo.