11. Estudo de caso: a aplicação RdvMedecins
11.1. O problema
A aplicação RdvMedecins gerencia as consultas de um consultório médico. Cada médico tem horários (das 8h às 12h em intervalos de 20 minutos, por exemplo); uma consulta é composta por um dia, um horário e um cliente (um paciente). Trata-se do porte exato, em [Flask], da aplicação [Spring MVC] da lição anterior (que por sua vez foi portada da versão [ASP.NET Core MVC]): mesmo banco de dados, mesmas regras de negócio, mesmas páginas, mesmas URLs, mesmos dicionários de tradução. As páginas HTML são geradas pelo servidor com views [Jinja2]; o acesso ao banco de dados é feito pelo [SQLAlchemy].
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, adicionar, editar, excluir) médicos e clientes |
DOCTOR | Médicos | ver as agendas, marcar consultas e cancelar consultas de qualquer paciente |
USER | clientes (pacientes) | ver as agendas sem ver os nomes dos outros pacientes; marcar uma consulta para si mesmo; cancelar sua consulta; gerenciar sua conta; criar uma conta |
Principais regras de gestão:
- nenhuma consulta no passado;
- um horário só pode ser reservado uma vez por dia;
- um paciente só pode ter uma consulta futura por vez;
- dois médicos (ou dois clientes) não podem ter o mesmo nome e sobrenome, e um login pertence a uma única conta;
- um médico com consultas não pode ser excluído; um cliente é excluído junto com suas consultas;
- a página de login é protegida contra bots (CAPTCHA, tentativas limitadas), e a criação de uma conta de cliente exige 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 e 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 no pé da página, sobre um fundo rosa claro:

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


Cada horário está disponível (botão Book) ou ocupado (nome do paciente, botão Cancel). Clicar em Book abre uma janela que pede as informações do paciente. Essa janela é gerada pelo servidor, assim como o restante da página: a URL passa a conter o parâmetro [book=4], que é o número do horário selecionado:

Após a reserva, uma mensagem confirma a consulta:

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

11.2.3. O portal do paciente
Um paciente (papel USER) chega a “My area”: sua consulta futura, que ele pode cancelar, e links para gerenciar sua conta e ver sua agenda. Aqui, ele ainda não tem consulta:

Na agenda, ele não vê os nomes dos outros pacientes; eles são substituídos por “Booked”: esse nome sequer aparece no código-fonte da página. Ele pode reservar um horário disponível:

A janela de reserva não pede que ele selecione um paciente: ele marca a consulta para si mesmo.


Seu painel agora mostra sua consulta futura, que ele pode cancelar:

Como ele tem uma consulta futura, não pode marcar outra: o botão “Book” não é exibido e, na agenda de outro dia ou de outro médico, uma mensagem explica o motivo:

Gerenciamento da conta: editar suas informações, alterar sua senha ou excluir sua conta (e as consultas). A senha atual é exigida para qualquer alteração:

Um paciente que tenta abrir uma página reservada ao administrador (aqui, [/doctors], digitada manualmente) recebe uma página de erro:

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


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

Um nome igual ao de um médico existente é rejeitado, mesmo escrito em minúsculas (o próprio banco de dados compara os nomes sem distinguir maiúsculas de minúsculas nem acentos; veja o exemplo 28):

A exclusão de um paciente 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:

Depois que a conta é criada, o usuário é redirecionado de volta à página de login, com seu nome de usuário já preenchido:

11.2.6. Fim da sessão
O token de login é válido por duas horas. Passado esse prazo (ou se o token tiver sido adulterado), a página solicitada redireciona para a página de login com a seguinte mensagem:

11.3. Instalação e execução
A aplicação fica na pasta [rdvmedecins2-flask], ao lado da pasta [examples]. É um projeto autônomo, com seus próprios arquivos [requirements.txt] e ambiente virtual. O arquivo [README.md] da pasta contém tudo o que segue. A introdução deste documento já descreveu a instalação; daremos aqui detalhes adicionais.
11.3.1. Software necessário
Dois softwares bastam:
- [Python] 3.12 ou posterior (a aplicação usa a sintaxe de classes genéricas introduzida na versão 3.12). Verifique a instalação em um terminal:
- um servidor [MySQL] 8 , por exemplo o do [Laragon] em execução no [Windows] (veja os apêndices). [MariaDB] também funciona: a aplicação foi testada com ele.
As bibliotecas são baixadas pelo [pip] a partir do repositório [PyPI] (*Python Package Index*): é preciso, portanto, estar conectado à Internet durante a instalação. O editor recomendado é o [Visual Studio Code], junto com a extensão [Python] da Microsoft (veja os apêndices); no entanto, tudo pode ser feito pela linha de comando.
11.3.2. Criar o banco de dados
O banco de dados [dbrdvmedecins2] é criado pelo script [database/dbrdvmedecins2.sql]. Com o [Laragon], abra a ferramenta [HeidiSQL] (botão Database) e execute o script pelo menu File / Run SQL. Pela linha de comando, na pasta da aplicação:
| mysql -u root -p < database/dbrdvmedecins2.sql
|
A opção [-p] solicita a senha do [root]; omita-a se a conta não tiver senha (como é o caso no [Laragon]). Este é o mesmo banco de dados usado pelas versões [ASP.NET Core] e [Spring MVC]: se ele já existir, esta etapa é opcional. O script pode ser executado a qualquer momento para voltar aos dados originais.
11.3.3. Configurar o acesso ao banco de dados
Todos os parâmetros de configuração ficam no arquivo [config.py] (comentado adiante). Por padrão, a aplicação se conecta ao [MySQL] em [localhost], porta 3306, com o usuário [root] sem senha: são os parâmetros padrão do [Laragon]. Se a sua conta [root] tiver senha, o mais simples é informá-la neste arquivo, na linha [DB_PASSWORD = ""]. Para evitar escrever uma senha em um arquivo do projeto, você também pode informá-la por meio de uma variável de ambiente, que tem precedência sobre o arquivo. Seu nome é o mesmo da variável do arquivo, precedido de [FLASK_] (exemplo 25):
| export FLASK_DB_PASSWORD=myPassword # Linux, macOS
set FLASK_DB_PASSWORD=myPassword # Windows (cmd)
$env:FLASK_DB_PASSWORD="myPassword" # Windows (PowerShell)
|
A variável vale apenas para o terminal em que foi definida; a aplicação é então iniciada a partir dele.
11.3.4. Iniciando a aplicação
Em uma janela de terminal aberta na pasta [rdvmedecins2-flask], com o ambiente virtual criado e ativado e as bibliotecas instaladas (veja a introdução):
A introdução mostrou a saída do console. Em seguida, abra a URL [http://localhost:8081] em um navegador e interrompa a aplicação com [Ctrl-C].
11.3.5. Contas de demonstração
A senha de cada conta é o seu nome de usuário; é preciso também digitar os caracteres da imagem, em maiúsculas ou minúsculas:
Logins | Papel |
[admin] | ADMIN (o administrador) |
[pelissier], [tatou], [dupont] | DOCTOR (médicos) |
[martin], [durand], [bistrou], [german] | USER (pacientes) |
Um roteiro para explorar a aplicação:
- [admin]: Schedule, Sra. Marie PELISSIER, hoje: um horário já está reservado pela Sra. Brigitte BISTROU. Reserve um horário para o Sr. Jean MARTIN e depois tente marcar uma segunda consulta para ele (recusada). Menus Doctors e Patients: adicionar, editar, excluir (a Dra. PELISSIER, que tem consultas, não pode ser excluída);
- [pelissier]: sua agenda do dia é exibida diretamente; o endereço [/doctors], digitado manualmente, retorna uma página de erro 403;
- [martin]: My area, sua consulta, a agenda em que os outros pacientes aparecem como “Booked”; Manage my account;
- página de login: Create a patient account e, em seguida, entre com a nova conta;
- Botões FR / EN: toda a interface muda de idioma, inclusive as datas.
11.3.6. Modo de desenvolvimento
O arquivo [app.py] inicia a aplicação com o perfil [dev] (o arquivo [config_dev.py], comentado adiante): o console passa então a exibir cada comando SQL enviado ao banco de dados pelo [SQLAlchemy]. O modo de depuração do servidor de desenvolvimento acrescenta dois recursos:
- recarregamento automático: a aplicação é reiniciada automaticamente assim que um arquivo [.py] é modificado. Uma view [templates/*.html] modificada é recarregada na próxima vez que a página for exibida;
- a página de depuração de exceções (exemplo 03), que aqui é desativada pelo parâmetro [PROPAGATE_EXCEPTIONS = False] (veja adiante): a aplicação exibe sua própria página de erro, mesmo durante o desenvolvimento, e a pilha de chamadas da exceção é escrita no console.
O [Visual Studio Code] depurador também permite executar a aplicação passo a passo: defina um ponto de interrupção clicando na margem de uma linha de código e, em seguida, inicie o arquivo [app.py] pelo menu Run / Start Debugging (tecla [F5]), selecionando “Python Debugger” e depois “Python File”. Convém evitar o recarregamento automático (ele inicia a aplicação em um processo separado, que o depurador não acompanha): desative-o iniciando a aplicação com o comando [flask --app rdvmedecins run --port 8081] (sem [--debug]).
11.3.7. Um servidor de produção
O servidor de desenvolvimento [Werkzeug] não se destina à produção: ele próprio avisa isso na inicialização. Em produção, a aplicação é implantada em um servidor WSGI (veja o capítulo sobre o ciclo de vida). A aplicação declara um em seu arquivo [requirements.txt]: [Waitress], um servidor escrito em [Python], que funciona tão bem no [Windows] quanto no [Linux]. Ele já está instalado no ambiente virtual:
| waitress-serve --port=8081 --call rdvmedecins:create_app
|
| INFO:waitress:Serving on http://0.0.0.0:8081
|
A opção [--call] especifica uma factory a chamar ([create_app], dentro do pacote [rdvmedecins]) para obter a aplicação. Iniciada dessa forma, a aplicação não tem o perfil [dev] (o console não exibe os comandos SQL) e tampouco está em modo de depuração. [Waitress] processa várias requisições em paralelo, em várias threads (quatro por padrão; opção [--threads]). No [Linux], o [Gunicorn] também é muito usado; no entanto, ele não funciona no [Windows]. Em ambos os casos, o servidor WSGI costuma ser colocado atrás de um servidor web ([nginx], [Apache]), que atende as requisições em modo HTTPS e as encaminha à aplicação.
Em produção, é preciso também alterar as chaves secretas e informar que o site é servido via HTTPS, por meio de variáveis de ambiente:
| export FLASK_SECRET_KEY="<a long random string>"
export FLASK_JWT_SECRET="<another long random string>"
export FLASK_COOKIE_SECURE=true
|
Uma cadeia aleatória adequada pode ser obtida com o próprio [Python] : [python -c "import secrets; print(secrets.token_urlsafe(48))"].
11.3.8. Problemas comuns
Ao iniciar, a aplicação lê as listas de médicos e clientes: se o banco de dados estiver inacessível, a aplicação para imediatamente, com um erro no console. Esse erro é precedido por uma longa pilha de chamadas; a mensagem relevante está no final, antes da linha [(Background on this error at: ...)]. Por exemplo, com um banco de dados inexistente:
| ...
sqlalchemy.exc.OperationalError: (pymysql.err.OperationalError) (1049, "Unknown database 'dbunknown'")
(Background on this error at: https://sqlalche.me/e/21/e3q8)
|
As mensagens mais comuns:
Mensagem | Causa |
[Can't connect to MySQL server on 'localhost' ([Errno 111] Connection refused)] ([[WinError 10061]] no [Windows]) | O [MySQL] não foi iniciado ou não está escutando em [localhost:3306] |
[Access denied for user 'root'@'localhost'] | A senha do [MySQL] precisa ser informada (veja “Configurar o acesso ao banco de dados”) |
[Unknown database 'dbrdvmedecins2'] | O script [database/dbrdvmedecins2.sql] não foi executado |
[JWT_SECRET must be at least 32 characters long (see config.py).] | A chave secreta do token é curta demais em [config.py] (ou na variável [FLASK_JWT_SECRET]) |
[ModuleNotFoundError: No module named 'flask'] | O ambiente virtual não está ativado, ou as bibliotecas não foram instaladas nele |
[Address already in use] ou [Port 8081 is in use by another program] | A porta 8081 já está em uso (a versão [Spring MVC] está em execução?): interrompa-a ou altere a porta em [app.py] |
['cryptography' package is required for sha256_password or caching_sha2_password auth methods] | A conta [MySQL] usa os parâmetros de autenticação do [MySQL] 8: falta a biblioteca [cryptography], instalada pelo [PyMySQL[rsa]] (veja [requirements.txt]) |
[SyntaxError] na inicialização, em uma linha [class ...[T: ...]] | a versão do [Python] é anterior à 3.12 |
11.4. A arquitetura da aplicação

- O navegador envia suas requisições ao servidor (o servidor de desenvolvimento [Werkzeug] ou o [Waitress]), que as encaminha à aplicação [Flask]. Cada requisição passa primeiro pelas funções [before_request] (veja o capítulo sobre o ciclo de vida): o idioma da requisição, depois o usuário, identificado a partir do token JWT em seu cookie, e a regra de acesso, que nega as páginas protegidas aos visitantes sem autorização para vê-las ([auth/security.py]);
- [controllers]: controllers da camada web, um blueprint para cada parte da aplicação. Todos passam por um único objeto, o [ApplicationModel] (pasta [web]), que armazena na memória as listas de médicos e clientes e repassa as demais requisições à camada de negócio;
- [auth]: autenticação, tokens JWT, CAPTCHA, limites de tentativas e criação de contas;
- [web]: elementos comuns da camada web: o cache e a fachada [ApplicationModel], tradução, mensagens flash, validação, variáveis comuns a todas as views e páginas de erro; [forms]: formulários [WTForms]; [models]: modelos das views;
- [business]: regras de negócio e transações;
- [repositories]: a camada DAO, uma classe por tabela;
- [entities]: as entidades que o [SQLAlchemy] lê e grava no banco de dados; [domain]: os objetos da agenda, calculados pela camada de negócio;
- [templates]: as views [Jinja2], que geram as páginas HTML; [i18n]: os dicionários, usados pelo tradutor; [static]: a folha de estilo, o script da página e o [Bootstrap];
- [rdvmedecins/__init__.py]: o construtor [create_app], que monta tudo; [config.py]: a configuração.
A pasta da aplicação:
| rdvmedecins2-flask/
├── app.py
├── config.py
├── config_dev.py
├── database/
│ ├── dbrdvmedecins2.sql
│ └── README.md
├── rdvmedecins/
│ ├── __init__.py
│ ├── auth/
│ │ ├── auth_service.py
│ │ ├── captcha.py
│ │ ├── captcha_drawing.py
│ │ ├── connected_user.py
│ │ ├── limiter.py
│ │ ├── passwords.py
│ │ ├── README.md
│ │ ├── registration_pass.py
│ │ └── security.py
│ ├── business/
│ │ ├── business.py
│ │ ├── dates.py
│ │ ├── exception.py
│ │ ├── person_data.py
│ │ ├── README.md
│ │ └── service.py
│ ├── controllers/
│ │ ├── area.py
│ │ ├── auth.py
│ │ ├── clients.py
│ │ ├── doctors.py
│ │ ├── language.py
│ │ ├── persons.py
│ │ ├── README.md
│ │ ├── registration.py
│ │ └── schedule.py
│ ├── domain/
│ │ ├── README.md
│ │ └── schedule.py
│ ├── entities/
│ │ ├── appointment.py
│ │ ├── base.py
│ │ ├── person.py
│ │ ├── README.md
│ │ ├── role.py
│ │ ├── slot.py
│ │ └── user.py
│ ├── forms/
│ │ ├── forms.py
│ │ ├── README.md
│ │ └── rules.py
│ ├── i18n/
│ │ ├── en.json
│ │ └── fr.json
│ ├── models/
│ │ ├── README.md
│ │ └── view_models.py
│ ├── repositories/
│ │ ├── appointment_repository.py
│ │ ├── client_repository.py
│ │ ├── doctor_repository.py
│ │ ├── person_repository.py
│ │ ├── README.md
│ │ ├── slot_repository.py
│ │ └── user_repository.py
│ ├── static/
│ │ ├── css/
│ │ │ └── styles.css
│ │ ├── js/
│ │ │ └── app.js
│ │ └── lib/
│ │ └── bootstrap/
│ ├── templates/
│ │ ├── account.html
│ │ ├── area.html
│ │ ├── error.html
│ │ ├── fragments/
│ │ │ ├── booking.html
│ │ │ ├── captcha.html
│ │ │ ├── confirmation.html
│ │ │ ├── errors.html
│ │ │ ├── flash.html
│ │ │ ├── navbar.html
│ │ │ └── person_fields.html
│ │ ├── layout.html
│ │ ├── login.html
│ │ ├── persons/
│ │ │ ├── form.html
│ │ │ └── list.html
│ │ ├── README.md
│ │ ├── registration.html
│ │ └── schedule.html
│ └── web/
│ ├── application_model.py
│ ├── common_model.py
│ ├── errors.py
│ ├── flash.py
│ ├── README.md
│ ├── services.py
│ ├── translator.py
│ ├── utils.py
│ └── validation.py
├── README.md
└── requirements.txt
|
Cada pasta de pacote contém também um arquivo chamado [__init__.py], em geral vazio, que transforma a pasta em um pacote [Python]: é isso que permite escrever [from rdvmedecins.entities import Doctor]. [Bootstrap] faz parte da aplicação (pasta [static/lib/bootstrap]) desta vez: o estudo de caso é autossuficiente.
Observe a escolha feita para o pacote [rdvmedecins]: a aplicação deixa de ser um simples módulo [app.py] e passa a ser um pacote, cujo arquivo [__init__.py] contém a factory [create_app]. Essa é a estrutura recomendada pela documentação do [Flask] para uma aplicação desse porte: o arquivo [app.py], na raiz, serve apenas para iniciar o servidor de desenvolvimento.
11.5. O banco de dados
O banco de dados [dbrdvmedecins2] tem cinco tabelas:
- [users]: usuários autorizados a entrar;
- [doctors] e [clients]: médicos e pacientes, cada um vinculado à sua respectiva conta de usuário;
- [slots]: os horários disponíveis de cada médico;
- [appointments]: as consultas, um cliente por horário em um determinado dia.
11.5.1. database/dbrdvmedecins2.sql
| -- =========================================================================
-- Banco de dados [dbrdvmedecins2] - MySQL 8
--
-- Evolução de [dbrdvmedecins]:
-- 1. as tabelas [doctors] e [clients] ganham uma coluna [user],
-- chave estrangeira para users(id): 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 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, consideradas idênticas.
--
-- A tabela [users] agora deve ser criada ANTES de [doctors] e [clients]
-- (elas a referenciam) e removida DEPOIS delas.
-- =========================================================================
-- o script é escrito em UTF-8
SET NAMES utf8mb4;
-- recomeçamos de um banco de dados vazio a cada execução do script (prático em desenvolvimento)
CREATE DATABASE IF NOT EXISTS dbrdvmedecins2 CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
USE dbrdvmedecins2;
-- ordem de remoção: das tabelas "filhas" para as tabelas "pais"
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 imediatamente um horário ocupado na agenda
INSERT INTO appointments (day, slot_id, client_id) VALUES
(CURDATE(), 2, 3);
|
- linha 33: o banco de dados é criado se não existir, com o conjunto de caracteres [utf8mb4] e a collation [utf8mb4_unicode_ci], que compara cadeias de caracteres sem considerar maiúsculas nem acentos (exemplo 28);
- linhas 37–41: as tabelas são removidas e depois recriadas; o script restaura o banco de dados ao seu estado inicial. A ordem importa: uma tabela não pode ser removida enquanto outra tabela a referenciar por uma chave estrangeira;
- linhas 46–54: users: um login, uma senha com hash gerado pelo [bcrypt] (exemplo 25), o nome de exibição após o login e o papel ([ADMIN], [DOCTOR], ou [USER]). A restrição [unq_users_login] garante que um nome de usuário pertença a uma única conta;
- linhas 60–71: cada tabela tem uma chave primária [id], gerada pelo banco de dados, e uma coluna [version], que é o bloqueio otimista (exemplo 28). A coluna [user] é uma chave estrangeira que referencia [users(id)]: o banco de dados rejeita qualquer valor que não seja o ID de um usuário existente. Como [user] é uma palavra reservada do SQL, ela é delimitada por acentos graves. Três restrições: [fk_doctors_user] (a chave estrangeira), [unq_doctors_user] (uma conta por médico e um médico por conta) e [unq_doctors_first_name_last_name] (sem homônimos). Todas as restrições são nomeadas: a aplicação reconhece uma restrição violada pelo seu nome;
- linhas 77–88: a tabela [clients] tem exatamente as mesmas colunas;
- linhas 94–102: um horário pertence a um médico; seus horários de início e de fim são armazenados em horas e minutos;
- linhas 108–117: uma consulta é composta por um dia (tipo [DATE], sem hora), um horário e um cliente. A restrição [unq1_appointments] impede que o mesmo horário seja reservado duas vezes no mesmo dia: o banco de dados impõe essa regra, mesmo que dois usuários o reservem ao mesmo tempo;
- linhas 130–140: usuários de demonstração, cuja senha é o próprio login. Os hashes começam com [$2b$10$]: o algoritmo ([bcrypt], variante [2b]) e o custo (10). Em seguida vêm o salt e o hash;
- linhas 144–147: a coluna [user] de cada médico é obtida por uma subconsulta com base no login, em vez de pressupor os valores das chaves primárias;
- linhas 170–171: uma consulta já marcada para hoje ([CURDATE()]) no segundo horário da Dra. PELISSIER para a Sra. BISTROU: a agenda mostra assim, de imediato, um horário reservado.
11.6. Configuração do projeto
11.6.1. requirements.txt
| # as bibliotecas da aplicação: pip install -r requirements.txt
Flask==3.1.3
Flask-WTF==1.3.0
SQLAlchemy==2.1.1
PyMySQL[rsa]==1.2.3
PyJWT==2.15.0
bcrypt==5.0.0
Babel==2.18.0
# um servidor WSGI para produção (veja README.md)
waitress==3.0.2
|
As bibliotecas da aplicação, com suas versões exatas ([==]). Especificar as versões garante que a aplicação funcione da mesma forma em todas as máquinas, mesmo daqui a um ano. [PyMySQL[rsa]] instala o driver [PyMySQL] junto com suas dependências opcionais [rsa], isto é, a biblioteca [cryptography], necessária para os métodos de autenticação do [MySQL] 8. [pip install -r requirements.txt] instala essas bibliotecas e aquelas de que elas dependem ([Werkzeug], [Jinja2], [WTForms]...). O comando [pip freeze] exibe a lista completa do que está instalado no ambiente virtual.
11.6.2. config.py
| # =========================================================================
# config.py - a configuração da aplicação.
#
# O Flask mantém apenas as variáveis em MAIÚSCULAS (veja rdvmedecins/__init__.py,
# app.config.from_pyfile). Cada valor pode ser substituído, sem modificar este
# arquivo, por uma variável de ambiente com o prefixo FLASK_:
# DB_PASSWORD é então escrito FLASK_DB_PASSWORD (app.config.from_prefixed_env).
# Os valores dessas variáveis são lidos como JSON quando possível:
# FLASK_LOGIN_MAX_FAILURES=3 resulta no número 3, FLASK_COOKIE_SECURE=true no booleano True.
# =========================================================================
# ———— o banco de dados MySQL [dbrdvmedecins2] (script: database/dbrdvmedecins2.sql):
# o servidor, sua porta, o usuário e sua senha (os do Laragon:
# root, sem senha), o banco de dados
DB_HOST = "localhost"
DB_PORT = 3306
DB_USER = "root"
DB_PASSWORD = ""
DB_NAME = "dbrdvmedecins2"
# True: as instruções SQL enviadas ao banco de dados são exibidas no console
SQL_ECHO = False
# ———— a chave secreta do Flask: ela ASSINA o cookie de sessão (mensagens
# flash, token anti-CSRF). Deve absolutamente ser alterada em produção.
SECRET_KEY = "change-me-too-to-a-long-random-string"
# ———— autenticação (veja rdvmedecins/auth/)
# chave secreta dos tokens JWT: pelo menos 32 caracteres (HMAC-SHA256).
# Deve absolutamente ser alterada em produção (string aleatória longa).
JWT_SECRET = "change-me-to-a-long-random-string"
# duração de validade de um token, em segundos (7200 s = 2 h); o cookie que
# carrega o token tem o mesmo tempo de vida
JWT_EXPIRES_IN_SECONDS = 7200
# True em produção (site servido em HTTPS): os cookies da aplicação
# nunca são então enviados por uma conexão não criptografada
COOKIE_SECURE = False
# ———— proteção contra robôs (veja rdvmedecins/auth/limiter.py)
# login: falhas permitidas para o mesmo login a partir do mesmo endereço IP...
LOGIN_MAX_FAILURES = 5
# ... antes de um bloqueio dessa duração (o endereço IP inteiro também é bloqueado
# se acumular 5 vezes mais falhas, todos os logins somados)
LOGIN_BLOCK_MINUTES = 15
# criação de conta de cliente: máximo de contas criadas por hora e por endereço
# IP. Em uma sala de aula, todos os computadores costumam sair pelo mesmo endereço:
# aumente se necessário.
REGISTRATION_MAX_PER_HOUR = 10
|
A configuração da aplicação, lida por [app.config.from_pyfile] (exemplo 25):
- linhas 15–19: acesso ao banco de dados: o servidor, sua porta, o nome de usuário e a senha, e o banco de dados. Esses valores são usados para construir a URL de conexão do [SQLAlchemy] (veja adiante);
- linha 22: exibição dos comandos SQL, desativada por padrão;
- linha 26: a chave secreta do [Flask], que assina o cookie de sessão (exemplo 20);
- linhas 31–34: a chave que assina os tokens JWT e sua duração de vida: duas horas;
- linha 37: em produção, os cookies da aplicação têm o atributo [Secure]; o navegador só os envia por uma conexão HTTPS;
- linhas 41–48: parâmetros de proteção contra bots: o número de tentativas de login fracassadas permitidas e a duração do bloqueio resultante; o número de contas de cliente que um mesmo endereço IP pode criar por hora.
Cada valor pode ser substituído por uma variável de ambiente com o prefixo [FLASK_]. As duas chaves secretas do arquivo são apenas valores de desenvolvimento: em produção, devem ser substituídas (veja “Um servidor de produção”).
11.6.3. config_dev.py
| # =========================================================================
# config_dev.py - complementa config.py em desenvolvimento (veja app.py, que inicia
# a aplicação com o perfil "dev"): as instruções SQL enviadas pelo
# SQLAlchemy são exibidas no console.
# =========================================================================
SQL_ECHO = True
|
O perfil de desenvolvimento: um segundo arquivo, lido depois do [config.py], cujos valores substituem os do primeiro. Há apenas um: a exibição dos comandos SQL. Também poderíamos escrever um [config_test.py] para testes, usando outro banco de dados.
11.7. Iniciando a aplicação
11.7.1. app.py
| # =========================================================================
# app.py - inicia a aplicação EM DESENVOLVIMENTO: python app.py
#
# O servidor de desenvolvimento do Flask (Werkzeug), na porta 8081, com:
# - o perfil "dev" (config_dev.py: as instruções SQL são exibidas);
# - debug=True: a aplicação reinicia sozinha assim que um arquivo .py
# é modificado, e uma view modificada é lida de novo quando a página é recarregada.
# Em produção, usa-se um servidor WSGI de verdade (veja README.md: waitress).
# =========================================================================
from rdvmedecins import create_app
if __name__ == "__main__":
create_app(profile="dev").run(port=8081, debug=True)
|
O arquivo que inicia a aplicação em desenvolvimento: a factory [create_app] é chamada com o perfil [dev] e, em seguida, a aplicação é entregue ao servidor de desenvolvimento na porta 8081, em modo de depuração. Em produção, esse arquivo não é usado: o servidor WSGI chama [create_app] (veja “Um servidor de produção”).
11.7.2. rdvmedecins/__init__.py
O construtor da aplicação. É o arquivo que reúne todo o resto: é a “planta” da aplicação.
| # =========================================================================
# rdvmedecins/__init__.py
# -------------------------------------------------------------------------
# A FACTORY da aplicação (veja o exemplo 02): create_app constrói e
# configura a aplicação Flask. É aqui que tudo é montado:
# 1. a configuração (config.py, config_dev.py, variáveis FLASK_...);
# 2. o acesso ao banco de dados: o engine e a factory de sessões do SQLAlchemy;
# 3. os objetos compartilhados: DAO -> camada de negócio -> cache (ApplicationModel),
# autenticação, captcha, limiter, passes de registro, tradutor -
# isso é injeção de dependência, escrita "à mão";
# 4. o que roda a cada requisição: idioma, autenticação;
# 5. os blueprints (os controllers), os tratadores de erro, a
# proteção anti-CSRF.
#
# Este arquivo faz de [rdvmedecins] um PACOTE Python: "from rdvmedecins
# import create_app" executa este arquivo.
# =========================================================================
from pathlib import Path
from flask import Flask, g, request
from flask_wtf.csrf import CSRFProtect
from sqlalchemy import URL, create_engine
from sqlalchemy.orm import sessionmaker
from rdvmedecins.auth import security
from rdvmedecins.auth.auth_service import AuthService
from rdvmedecins.auth.captcha import CaptchaService
from rdvmedecins.auth.limiter import AttemptLimiter
from rdvmedecins.auth.registration_pass import RegistrationPass
from rdvmedecins.controllers.schedule import schedule
from rdvmedecins.controllers.auth import auth
from rdvmedecins.controllers.clients import clients
from rdvmedecins.controllers.area import area
from rdvmedecins.controllers.registration import registration
from rdvmedecins.controllers.language import language
from rdvmedecins.controllers.doctors import doctors
from rdvmedecins.business.service import BusinessService
from rdvmedecins.repositories.client_repository import ClientRepository
from rdvmedecins.repositories.slot_repository import SlotRepository
from rdvmedecins.repositories.doctor_repository import DoctorRepository
from rdvmedecins.repositories.appointment_repository import AppointmentRepository
from rdvmedecins.repositories.user_repository import UserRepository
from rdvmedecins.web import errors, common_model, translator
from rdvmedecins.web.application_model import ApplicationModel
from rdvmedecins.web.translator import Translator
# a pasta do projeto (a que contém config.py), pai deste pacote
ROOT = Path(__file__).resolve().parent.parent
def create_app(profile: str | None = None) -> Flask:
app = Flask(__name__)
app.jinja_env.trim_blocks = True
app.jinja_env.lstrip_blocks = True
# ———— 1. a configuração: config.py, depois config_<profile>.py se houver
# um perfil, depois as variáveis de ambiente FLASK_...
app.config.from_pyfile(ROOT / "config.py")
if profile:
app.config.from_pyfile(ROOT / f"config_{profile}.py")
app.config.from_prefixed_env()
app.config.update(
# o cookie de sessão do Flask (mensagens flash, token anti-CSRF)
SESSION_COOKIE_NAME="rdvmedecins_session",
SESSION_COOKIE_SAMESITE="Lax",
SESSION_COOKIE_SECURE=app.config["COOKIE_SECURE"],
# o token anti-CSRF permanece válido enquanto durar a sessão do navegador
WTF_CSRF_TIME_LIMIT=None,
# uma exceção não tratada é entregue aos nossos tratadores de erro
# (página 500), mesmo no modo debug
PROPAGATE_EXCEPTIONS=False,
)
# ———— 2. acesso ao banco de dados. A URL de conexão do SQLAlchemy
# (mysql+pymysql://root:@localhost:3306/dbrdvmedecins2?charset=utf8mb4),
# construída por URL.create: uma senha que contenha caracteres
# especiais (@, :, /...) é corretamente codificada nela. str(...): uma variável
# FLASK_DB_PASSWORD=123456 seria lida como um NÚMERO (veja config.py)
url = URL.create("mysql+pymysql", username=str(app.config["DB_USER"]),
password=str(app.config["DB_PASSWORD"]), host=app.config["DB_HOST"],
port=int(app.config["DB_PORT"]), database=app.config["DB_NAME"],
query={"charset": "utf8mb4"})
# O engine gerencia um POOL de conexões; pool_pre_ping: uma conexão é
# testada antes de ser reutilizada; pool_recycle: ela é renovada após
# uma hora (o MySQL fecha sozinho as conexões que ficaram ociosas
# por tempo demais)
engine = create_engine(url, echo=app.config["SQL_ECHO"], pool_pre_ping=True,
pool_recycle=3600)
# expire_on_commit=False: os objetos lidos continuam utilizáveis após o fim
# da transação (pelas views, pelo cache)
sessions = sessionmaker(engine, expire_on_commit=False)
# ———— 3. os objetos compartilhados, criados uma vez por todas
business = BusinessService(sessions, DoctorRepository(), ClientRepository(),
SlotRepository(), AppointmentRepository(), UserRepository())
# o cache lê os médicos e os clientes: um banco de dados inacessível interrompe
# a aplicação AQUI, na inicialização
app.extensions["rdvmedecins.application"] = ApplicationModel(business)
auth_service = AuthService(sessions, UserRepository(), app.config["JWT_SECRET"],
app.config["JWT_EXPIRES_IN_SECONDS"], app.config["COOKIE_SECURE"])
app.extensions["rdvmedecins.auth"] = auth_service
app.extensions["rdvmedecins.captchas"] = CaptchaService()
app.extensions["rdvmedecins.limiter"] = AttemptLimiter(
app.config["LOGIN_MAX_FAILURES"], app.config["LOGIN_BLOCK_MINUTES"],
app.config["REGISTRATION_MAX_PER_HOUR"])
app.extensions["rdvmedecins.passes"] = RegistrationPass()
trans = Translator(Path(app.root_path) / "i18n")
# ———— 4. a cada requisição, na ordem de registro:
# o idioma (cookie rdvmedecins_language, inglês caso contrário)...
@app.before_request
def set_language():
g.language = translator.language(request.cookies.get(translator.LANGUAGE_COOKIE))
# ... depois o usuário, e a regra de acesso (veja auth/security.py)
security.register(app, auth_service)
# as variáveis comuns a todas as views
common_model.register(app, trans)
# ———— 5. os controllers, as páginas de erro, a proteção anti-CSRF
for blueprint in (auth, language, schedule, doctors, clients, registration, area):
app.register_blueprint(blueprint)
errors.register(app)
# toda requisição POST deve enviar de volta o token anti-CSRF da página
# (campo oculto csrf_token): caso contrário, resposta 400
CSRFProtect(app)
return app
|
- linha 48: a pasta do projeto, que contém o [config.py]: a pasta pai ([parent.parent]) da pasta deste arquivo;
- linhas 52–54: a aplicação; [__name__] equivale aqui a [rdvmedecins], o nome do pacote: o [Flask] procura, portanto, as pastas [templates] e [static] dentro da pasta do pacote;
- linhas 58–61: a configuração, em três etapas: o arquivo [config.py], o arquivo do perfil (se houver) e as variáveis de ambiente. Cada fonte substitui os valores das anteriores;
- linhas 62–71: alguns parâmetros do [Flask] e do [Flask-WTF], escritos aqui e não no [config.py] porque não se destinam a ser alterados. [SESSION_COOKIE_NAME] renomeia o cookie de sessão (padrão: [session]) para que não entre em conflito com o de outra aplicação servida por [localhost], como nos exemplos; [SESSION_COOKIE_SAMESITE] e [SESSION_COOKIE_SECURE] atribuem a ele os atributos [SameSite=Lax] e, em produção, [Secure] (exemplo 25). [WTF_CSRF_TIME_LIMIT=None]: por padrão, um token anti-CSRF é válido por apenas uma hora, e um formulário deixado aberto por mais tempo seria rejeitado; aqui, ele permanece válido durante toda a sessão do navegador. [PROPAGATE_EXCEPTIONS=False]: no modo de depuração, o [Flask] permite que certas exceções se propaguem até a página de depuração; este parâmetro garante que elas passem pelos nossos tratadores de erro;
- linhas 79–82: a URL de conexão do [SQLAlchemy] (exemplo 28), gerada por [URL.create] a partir de seus componentes. Quando escrita à mão, uma URL deve codificar os caracteres especiais de uma senha ([@], [:], [/]...), que têm significado dentro de uma URL; o [URL.create] faz isso por conta própria. [str(...)] e [int(...)] protegem contra as conversões das variáveis de ambiente: [FLASK_DB_PASSWORD=123456] seria interpretada como um número;
- linhas 87–88: o engine e seu pool de conexões. [pool_recycle=3600] renova uma conexão após uma hora; o [MySQL] fecha automaticamente as conexões inativas por muito tempo (oito horas por padrão);
- linha 91: a fábrica de sessões (exemplo 28);
- linhas 94–106: objetos compartilhados, criados uma única vez e armazenados em [app.extensions] (exemplo 06). Isto é injeção de dependência, feita à mão: cada objeto recebe em seu construtor os objetos de que precisa. A camada de negócio recebe a fábrica de sessões e as cinco classes da camada DAO; o cache [ApplicationModel] recebe a camada de negócio; o serviço de autenticação recebe a fábrica de sessões, a classe DAO de usuários e a configuração dos tokens. As chaves de [app.extensions] têm o prefixo [rdvmedecins.] para evitar conflito com as das extensões (o [Flask-WTF] também armazena seus objetos ali). O construtor do [ApplicationModel] lê a lista de médicos e clientes: se o banco de dados estiver inacessível, a aplicação para aqui, na inicialização, e não na primeira requisição;
- linha 107: o serviço de tradução (exemplo 22);
- linhas 111–113: a primeira função [before_request] obtém o idioma da requisição a partir do cookie [rdvmedecins_language];
- linha 116: a segunda variável: o usuário da requisição e a regra de acesso (veja [auth/security.py]). A ordem importa: a página de login para a qual um visitante não autorizado é redirecionado precisa conhecer o idioma;
- linha 118: as variáveis comuns a todas as views (o context processor do exemplo 15, veja [web/common_model.py]);
- linhas 121–122: os sete blueprints da aplicação;
- linha 123: os tratadores de erro (veja [web/errors.py]);
- linha 126: proteção CSRF para todas as requisições (POST, exemplo 21).
Este arquivo equivale à classe de inicialização e às classes de configuração de uma aplicação [Spring Boot], e ao arquivo [Program.cs] de uma aplicação [ASP.NET Core]. A principal diferença: o [Flask] não cria nem injeta nada por conta própria. Tudo o que existe na aplicação foi criado aqui explicitamente, e é possível rastrear cada objeto da criação ao uso.
11.8. Entidades
A pasta [entities] contém uma classe por tabela: as entidades que o [SQLAlchemy] lê e grava no banco de dados (exemplo 28). Seus atributos têm o nome das colunas, salvo indicação em contrário.
11.8.1. entities/base.py
| # =========================================================================
# entities/base.py
# -------------------------------------------------------------------------
# A classe pai de todas as entidades, e as duas colunas comuns a
# todas as tabelas: o identificador [id] e o número de versão [version].
#
# SQLAlchemy "declarativo": cada classe filha de Base descreve uma tabela
# (__tablename__), cada atributo Mapped[...] uma coluna. O SQLAlchemy lê
# essas declarações na inicialização para saber qual classe vai em qual
# tabela, qual atributo em qual coluna.
# =========================================================================
from sqlalchemy.orm import DeclarativeBase, Mapped, declared_attr, mapped_column
class Base(DeclarativeBase):
pass
# um MIXIN: uma classe sem tabela, cujas colunas são adicionadas às
# das classes que herdam dela (Doctor, Client, Slot, Appointment, User)
class WithIdAndVersion:
# a chave primária, gerada pelo banco de dados (coluna AUTO_INCREMENT):
# o SQLAlchemy lê seu valor de volta após cada INSERT. Uma entidade ainda não
# salva tem um id None.
id: Mapped[int] = mapped_column(primary_key=True)
# o bloqueio otimista. Cada UPDATE enviado pelo SQLAlchemy carrega a
# condição "WHERE id = ... AND version = <valor lido>" e escreve a
# versão incrementada em 1. Se alguém modificou a linha nesse meio-tempo,
# nenhuma linha é atualizada: o SQLAlchemy lança uma StaleDataError
# (veja business/service.py).
version: Mapped[int] = mapped_column()
# @declared_attr: um atributo calculado para CADA classe filha;
# version_id_col: a coluna usada como bloqueio otimista
@declared_attr.directive
def __mapper_args__(cls):
return {"version_id_col": cls.version}
|
- linhas 15–16: a classe pai de todas as entidades (exemplo 28);
- linhas 21–39: as duas colunas comuns a todas as tabelas, [id] e [version], definidas uma única vez. [WithIdAndVersion] é um mixin: uma classe que não tem tabela e nunca é criada isoladamente, mas da qual as classes filhas herdam colunas. Uma entidade herda, assim, de duas classes: [class User(WithIdAndVersion, Base)] (herança múltipla em [Python]);
- linhas 37–39: o bloqueio otimista (exemplo 28). [__mapper_args__] deve referir-se à coluna [version] de cada classe filha, e não à do mixin: o decorador [@declared_attr.directive] transforma este método em um atributo calculado para cada classe que herda do mixin. [SQLAlchemy] o chama ao analisar a classe filha, passando-a como parâmetro ([cls]).
11.8.2. entities/role.py
| # =========================================================================
# entities/role.py
# -------------------------------------------------------------------------
# Os três papéis de um usuário (coluna users.role):
# - ADMIN : o administrador - consultas + gestão de médicos e clientes;
# - DOCTOR : um médico - marca e cancela consultas;
# - USER : um cliente (paciente) - marca para si mesmo, gerencia sua conta.
#
# Uma enumeração (Enum): nenhum outro valor é possível. StrEnum: seus
# valores também são strings ("ADMIN"), guardados como estão no banco de dados,
# como faz o script SQL (veja user.py).
# =========================================================================
from enum import StrEnum
class Role(StrEnum):
ADMIN = "ADMIN"
DOCTOR = "DOCTOR"
USER = "USER"
|
Uma enumeração: um tipo cujos valores possíveis são fixados de uma vez por todas ([Role.ADMIN], [Role.DOCTOR], [Role.USER]). [StrEnum] (módulo padrão [enum], [Python] 3.11): cada valor é também uma cadeia de caracteres, igual a ["ADMIN"], etc. Ele pode, portanto, ser comparado a uma string, gravado em um token JWT ou incluído em uma página sem conversão.
11.8.3. entities/user.py
| # =========================================================================
# entities/user.py
# -------------------------------------------------------------------------
# Um usuário autorizado a fazer login na aplicação (tabela [users]).
# Cada médico e cada cliente tem SUA conta de usuário (coluna
# [user] das tabelas [doctors] e [clients], veja person.py).
#
# Restrição de unicidade SQL: unq_users_login (um login pertence a uma única
# conta). Ela é criada pelo script database/dbrdvmedecins2.sql;
# a camada de negócio a reconhece pelo seu NOME (veja business/service.py).
# =========================================================================
from sqlalchemy import Enum, String
from sqlalchemy.orm import Mapped, mapped_column
from rdvmedecins.entities.base import WithIdAndVersion, Base
from rdvmedecins.entities.role import Role
class User(WithIdAndVersion, Base):
__tablename__ = "users"
login: Mapped[str] = mapped_column(String(30))
# a senha com HASH (bcrypt) - nunca em texto claro
password: Mapped[str] = mapped_column(String(100))
# o nome exibido após o login - para um médico ou um cliente:
# "nome SOBRENOME" (ex.: "Marie PELISSIER")
name: Mapped[str] = mapped_column(String(40))
# ADMIN, DOCTOR ou USER, guardado no banco de dados como texto.
# native_enum=False: uma simples coluna VARCHAR (e não o tipo ENUM do MySQL)
role: Mapped[Role] = mapped_column(Enum(Role, native_enum=False, length=10))
|
- linha 19: a entidade herda o ID e a versão do mixin, e de [Base];
- linha 24: a senha com hash;
- linha 30: um atributo do tipo [Role]. O tipo [Enum] do [SQLAlchemy] converte a enumeração em texto na gravação (["ADMIN"]) e o texto em enumeração na leitura. [native_enum=False]: a coluna é um simples [VARCHAR], como no script SQL, e não o tipo [ENUM] específico do [MySQL].
11.8.4. entities/person.py
| # =========================================================================
# entities/person.py
# -------------------------------------------------------------------------
# Os médicos (tabela [doctors]) e os clientes (tabela [clients]): um
# título, um sobrenome, um nome - e a conta de usuário associada (coluna [user]).
#
# As duas tabelas têm exatamente as mesmas colunas: elas são descritas
# UMA ÚNICA VEZ, no mixin Person, do qual Doctor e Client herdam. Um
# relacionamento declarado em um mixin deve ser declarado por um método @declared_attr:
# o SQLAlchemy o chama para cada classe filha, que recebe assim SEU relacionamento.
#
# Atenção: [Client] aqui designa um PACIENTE do consultório médico, não um
# cliente HTTP! É o vocabulário do domínio de negócio original, mantido
# como está (tabela [clients]).
#
# Restrições de unicidade SQL: unq_doctors_first_name_last_name, unq_clients_first_name_last_name
# (dois médicos, ou dois clientes, não podem ter o mesmo nome e
# sobrenome) - criadas pelo script SQL, reconhecidas pelo nome na camada de negócio.
# =========================================================================
from sqlalchemy import ForeignKey, String
from sqlalchemy.orm import Mapped, declared_attr, mapped_column, relationship
from rdvmedecins.entities.base import WithIdAndVersion, Base
from rdvmedecins.entities.user import User
class Person(WithIdAndVersion):
title: Mapped[str] = mapped_column(String(5)) # Melle, Mme, Mr
last_name: Mapped[str] = mapped_column(String(20))
first_name: Mapped[str] = mapped_column(String(20))
# a chave estrangeira para users(id), lida como um simples número: assim sabemos
# o id da conta sem carregar o User. "user" é o nome da
# coluna (uma palavra-chave SQL, que o próprio SQLAlchemy envolve entre
# crases `user` se o SGBD exigir); user_id, o do atributo Python
@declared_attr
def user_id(cls) -> Mapped[int]:
return mapped_column("user", ForeignKey("users.id"))
# -----------------------------------------------------------------------
# O relacionamento com a conta de usuário: um médico (um cliente) tem UMA
# conta. relationship: o atributo [user] é um objeto User, e não um
# número. O SQLAlchemy só o lê do banco de dados se for solicitado: na
# consulta (opções joinedload, veja repositories/), ou no primeiro acesso ao
# atributo, enquanto a sessão estiver aberta.
# -----------------------------------------------------------------------
@declared_attr
def user(cls) -> Mapped[User]:
return relationship()
class Doctor(Person, Base):
__tablename__ = "doctors"
class Client(Person, Base):
__tablename__ = "clients"
|
- linha 27: como as tabelas [doctors] e [clients] têm exatamente as mesmas colunas, elas são descritas uma única vez no mixin [Person], que por sua vez herda do mixin [WithIdAndVersion];
- linhas 29–31: as colunas comuns, declaradas como no exemplo 28;
- linhas 9–39: a chave estrangeira para a conta de usuário. Em um mixin, uma coluna que serve de chave estrangeira deve ser declarada com o método [@declared_attr]: cada classe filha recebe assim sua própria coluna. [ForeignKey("users.id")] especifica a coluna referenciada; o primeiro parâmetro de [mapped_column] é o nome da coluna na tabela ([user]), que difere do do atributo [Python] ([user_id]);
- linhas 37–50: o relacionamento com a conta: o atributo [user] é um objeto [User], e não um número. [SQLAlchemy] deduz a junção pela chave estrangeira. Um relacionamento não é uma coluna: é um meio de obter o objeto vinculado. Por padrão, o [SQLAlchemy] só o lê do banco de dados no primeiro acesso ao atributo (carregamento tardio, ou lazy loading), o que pressupõe que a sessão ainda esteja aberta;
- linhas 53–58: duas entidades, que diferem apenas pela tabela.
Observe a terminologia: um [Client] aqui designa um paciente do consultório médico, e não um cliente HTTP. Essa é a terminologia da aplicação original, mantida como está.
11.8.5. entities/slot.py
| # =========================================================================
# entities/slot.py
# -------------------------------------------------------------------------
# Um horário de um médico (tabela [slots]): 8:00 - 8:20, etc.
# =========================================================================
from sqlalchemy import ForeignKey
from sqlalchemy.orm import Mapped, mapped_column, relationship
from rdvmedecins.entities.base import WithIdAndVersion, Base
from rdvmedecins.entities.person import Doctor
class Slot(WithIdAndVersion, Base):
__tablename__ = "slots"
start_hour: Mapped[int] # hora de início do horário
start_minute: Mapped[int] # minuto de início do horário
end_hour: Mapped[int] # hora de término do horário
end_minute: Mapped[int] # minuto de término do horário
# vários horários para o mesmo médico: a chave estrangeira [doctor_id]
# (um número), e o relacionamento [doctor] (o objeto Doctor)
doctor_id: Mapped[int] = mapped_column(ForeignKey("doctors.id"))
doctor: Mapped[Doctor] = relationship()
|
Um horário de consulta e seu médico: a chave estrangeira [doctor_id] (um número) e o relacionamento [doctor] (o objeto). Sem mixin, o relacionamento é declarado diretamente, como atributo.
11.8.6. entities/appointment.py
| # =========================================================================
# entities/appointment.py
# -------------------------------------------------------------------------
# Uma consulta (tabela [appointments]): um cliente, em um horário, em um dia determinado.
#
# Restrição de unicidade SQL: unq1_appointments (day, slot_id) - um horário é
# reservado uma única vez por dia. Criada pelo script SQL, reconhecida pelo seu
# nome na camada de negócio.
# =========================================================================
from datetime import date
from sqlalchemy import ForeignKey
from sqlalchemy.orm import Mapped, mapped_column, relationship
from rdvmedecins.entities.base import WithIdAndVersion, Base
from rdvmedecins.entities.slot import Slot
from rdvmedecins.entities.person import Client
class Appointment(WithIdAndVersion, Base):
__tablename__ = "appointments"
# date: uma data SEM hora, que corresponde exatamente ao tipo SQL DATE
# da coluna [day]
day: Mapped[date]
client_id: Mapped[int] = mapped_column(ForeignKey("clients.id"))
client: Mapped[Client] = relationship()
slot_id: Mapped[int] = mapped_column(ForeignKey("slots.id"))
slot: Mapped[Slot] = relationship()
|
- linha 25: o tipo [date] do [Python], uma data sem hora, corresponde exatamente ao tipo SQL [DATE];
- Linhas 27–31: as duas chaves estrangeiras e seus relacionamentos.
11.8.7. entities/__init__.py
| # =========================================================================
# entities/ - as ENTIDADES: uma classe por tabela do banco de dados dbrdvmedecins2.
# Este arquivo agrupa os imports: "from rdvmedecins.entities import
# Doctor" basta no resto da aplicação.
# =========================================================================
from rdvmedecins.entities.base import Base
from rdvmedecins.entities.slot import Slot
from rdvmedecins.entities.person import Client, Doctor, Person
from rdvmedecins.entities.role import Role
from rdvmedecins.entities.appointment import Appointment
from rdvmedecins.entities.user import User
__all__ = ["Base", "Client", "Slot", "Doctor", "Person", "Role", "Appointment", "User"]
|
O arquivo [__init__.py] de um pacote é executado quando o pacote é importado. Este arquivo importa as entidades de seus respectivos módulos; no restante do código, [from rdvmedecins.entities import Doctor] basta, sem a necessidade de saber em qual módulo a classe está definida. A lista [__all__] declara os nomes disponibilizados pelo pacote.
11.9. SQLAlchemy: sessões e carregamento de relacionamentos
O exemplo 28 abordou o básico do [SQLAlchemy]. O estudo de caso usa dois aspectos adicionais dele, interligados.
O tempo de vida dos objetos lidos. Cada método da camada de negócio abre uma sessão e uma transação e as fecha ao sair (exemplo 28). As entidades que ele retorna ficam então desanexadas: não estão mais associadas a nenhuma sessão. Graças ao parâmetro [expire_on_commit=False], seus atributos comuns continuam legíveis. No entanto, um relacionamento que não foi carregado não pode mais ser carregado: isso exigiria consultar o banco de dados, e não há mais sessão. Acessar o atributo lança então uma exceção [DetachedInstanceError]. Esse é o problema que o [Spring Boot] resolve, junto com o [Hibernate], por meio do parâmetro [open-in-view] (uma sessão aberta durante toda a requisição), que a versão [Spring MVC] do estudo de caso desativou pelo mesmo motivo que nós: uma view não deve disparar requisições SQL. A regra é, portanto: cada método da camada DAO carrega explicitamente os relacionamentos de que o chamador precisará.
Opções de carregamento. [SQLAlchemy] oferece várias maneiras de carregar um relacionamento junto com a entidade:
- [joinedload(Doctor.user)]: adiciona uma junção ([LEFT OUTER JOIN users ...]) à consulta, cujas colunas são usadas para construir os objetos [User]. Uma única consulta retorna os médicos e suas contas;
- [contains_eager(Appointment.slot)]: quando a consulta já contém uma junção ([select(Appointment).join(Appointment.slot)], escrita para filtrar por uma coluna da tabela unida), essa opção instrui o [SQLAlchemy] a usar as colunas dessa junção para preencher o relacionamento, em vez de adicionar uma segunda;
- As opções são encadeadas para carregar um relacionamento a partir de outro: [contains_eager(Appointment.slot).joinedload(Slot.doctor)] carrega o horário de cada consulta e, depois, o médico de cada horário.
Elas são os equivalentes de [JOIN FETCH] no [JPA] e de [Include] no [Entity Framework Core].
11.10. O domínio: a agenda
11.10.1. domain/schedule.py
| # =========================================================================
# domain/schedule.py
# -------------------------------------------------------------------------
# Objetos "de negócio" calculados, que não correspondem a nenhuma tabela:
# - DoctorDaySlot: um horário, e a consulta eventualmente
# marcada nesse horário em um dado dia (None se o horário estiver livre);
# - DoctorDaySchedule: a agenda completa de um médico em um dado dia,
# a lista de seus horários, cada um livre ou reservado. Calculada por
# BusinessService.get_doctor_day_schedule, transformada em uma tabela HTML por
# controllers/schedule.py.
#
# frozen=True: objetos imutáveis, cujos campos são definidos uma vez
# por todas pelo construtor - exatamente o que é preciso para um
# objeto calculado, que ninguém modifica depois.
# =========================================================================
from dataclasses import dataclass
from datetime import date
from rdvmedecins.entities import Slot, Doctor, Appointment
@dataclass(frozen=True)
class DoctorDaySlot:
slot: Slot
appointment: Appointment | None
@dataclass(frozen=True)
class DoctorDaySchedule:
doctor: Doctor
day: date
doctor_day_slots: list[DoctorDaySlot]
|
Duas classes que não correspondem a nenhuma tabela: a agenda de um médico para um único dia, calculada pela camada de negócio. [DoctorDaySlot] associa um horário à consulta marcada nesse horário nesse dia, ou a [None] se ele estiver disponível; [DoctorDaySchedule] combina o médico, o dia e a lista de horários do médico. São objetos [dataclass] imutáveis ([frozen=True]): um objeto calculado que ninguém modifica depois.
11.11. A camada DAO
A pasta [repositories] (o nome inglês usual para classes DAO, “repositories”) contém uma classe por entidade. Como no exemplo 28, cada método recebe a sessão aberta pela camada de negócio e não contém lógica de negócio.
11.11.1. repositories/person_repository.py
| # =========================================================================
# repositories/person_repository.py
# -------------------------------------------------------------------------
# A camada DAO comum aos médicos e aos clientes.
#
# Cada método recebe a SESSÃO do SQLAlchemy aberta pela camada
# de negócio (veja business/service.py): todas as consultas da mesma operação
# usam assim a mesma conexão e a mesma TRANSAÇÃO.
#
# As consultas são escritas com os objetos do SQLAlchemy (select, where,
# order_by...), que se aplicam às CLASSES e a seus atributos; o SQLAlchemy
# as traduz em SQL. Os valores (first_name, last_name...) se tornam PARÂMETROS
# da consulta: nenhuma concatenação de strings, logo nenhuma injeção de SQL.
#
# Os DAOs dos médicos e dos clientes seriam idênticos: esta classe
# GENÉRICA os escreve uma única vez. [T: Person]: um parâmetro de tipo,
# que é Doctor ou Client; self.entity é a classe correspondente.
# =========================================================================
from sqlalchemy import delete, select
from sqlalchemy.orm import Session, joinedload
from rdvmedecins.entities import Person
class PersonRepository[T: Person]:
def __init__(self, entity: type[T]):
self.entity = entity
# lista ordenada por sobrenome e depois por nome, conta de usuário incluída.
# joinedload(user): traz TAMBÉM a conta, por meio de um join
# (SELECT ... FROM doctors LEFT OUTER JOIN users ...). Sem ele, a
# conta só seria lida no primeiro acesso - impossível depois que a sessão
# é fechada: essas listas são mantidas em memória pelo cache
# (web/application_model.py), muito depois do fim da requisição.
def list(self, session: Session) -> list[T]:
e = self.entity
query = select(e).options(joinedload(e.user)).order_by(e.last_name, e.first_name)
return list(session.scalars(query))
# uma pessoa e sua conta; None se elas não existirem
def read(self, session: Session, id: int) -> T | None:
return session.get(self.entity, id, options=[joinedload(self.entity.user)])
# a pessoa cuja conta de usuário é [user_id]
def read_by_user(self, session: Session, user_id: int) -> T | None:
e = self.entity
query = select(e).options(joinedload(e.user)).where(e.user_id == user_id)
return session.scalars(query).first()
# a pessoa que tem esse nome e sobrenome, se houver. A comparação
# é feita pelo MySQL, portanto com o collation do banco de dados
# (utf8mb4_unicode_ci: sem distinguir maiúsculas e acentos) -
# exatamente a mesma regra da restrição de unicidade SQL.
def namesake(self, session: Session, first_name: str, last_name: str) -> T | None:
e = self.entity
return session.scalars(select(e).where(e.first_name == first_name, e.last_name == last_name).limit(1)).first()
def add(self, session: Session, person: T) -> T:
session.add(person)
return person
# um DELETE enviado diretamente ao banco de dados, sem ler a pessoa antes
def remove(self, session: Session, id: int):
session.execute(delete(self.entity).where(self.entity.id == id))
|
- linha 25: uma classe genérica, escrita com a sintaxe do [Python] 3.12 (PEP 695). [T] é um parâmetro de tipo: a classe será usada como [PersonRepository[Doctor]] ou [PersonRepository[Client]]. [T: Person] restringe [T] a classes que herdam de [Person]. Os tipos não são verificados pelo [Python] em tempo de execução (exemplo 06): eles documentam o código e permitem que o editor saiba que [list()] retorna uma lista de [Doctor] no DAO de médicos. Antes do [Python] 3.12, escrevia-se [T = TypeVar("T", bound=Person)] seguido de [class PersonRepository(Generic[T])];
- linhas 27–28: o parâmetro de tipo não existe em tempo de execução: a classe real ([Doctor] ou [Client]) é, portanto, passada ao construtor e armazenada em [self.entity]. [type[T]] é o tipo de uma classe (e não de um objeto);
- linhas 36–39: a lista ordenada, com a contagem de cada pessoa, carregada por meio de uma junção ([joinedload]). Isso é essencial aqui: essas listas são mantidas na memória pelo cache [ApplicationModel], bem depois do fim da sessão;
- linhas 42–43: a leitura pela chave primária também aceita opções de carregamento;
- linhas 46–49: a pessoa associada a uma conta: é assim que identificamos o cliente que entrou;
- linhas 55–57: busca de um homônimo. A comparação é feita pelo [MySQL], usando a collation do banco de dados: é exatamente a regra da restrição de unicidade;
- linhas 59–61: a adição, sem [flush]: a camada de negócio decide quando os comandos SQL são enviados;
- linhas 64–65: um [DELETE] enviado diretamente ao banco de dados.
11.11.2. repositories/doctor_repository.py
| # =========================================================================
# repositories/doctor_repository.py
# -------------------------------------------------------------------------
# O DAO dos médicos: tudo é herdado de PersonRepository.
# =========================================================================
from rdvmedecins.entities import Doctor
from rdvmedecins.repositories.person_repository import PersonRepository
class DoctorRepository(PersonRepository[Doctor]):
def __init__(self):
super().__init__(Doctor)
|
A classe DAO dos médicos herda de [PersonRepository[Doctor]] e passa a classe [Doctor] ao construtor de sua classe pai; todo o resto é herdado.
11.11.3. repositories/client_repository.py
| # =========================================================================
# repositories/client_repository.py
# -------------------------------------------------------------------------
# O DAO dos clientes: o das pessoas, mais um método de bloqueio.
# =========================================================================
from sqlalchemy import select
from sqlalchemy.orm import Session
from rdvmedecins.entities import Client
from rdvmedecins.repositories.person_repository import PersonRepository
class ClientRepository(PersonRepository[Client]):
def __init__(self):
super().__init__(Client)
# -----------------------------------------------------------------------
# coloca um LOCK na linha de um cliente até o fim da
# transação atual (SELECT ... FOR UPDATE), e retorna seu id (None
# se o cliente não existir). Uma segunda transação que peça o mesmo
# lock ESPERA até que a primeira termine.
# Usado para marcar uma consulta (veja BusinessService.add_appointment):
# duas marcações simultâneas para o mesmo paciente são assim tratadas
# uma DEPOIS da outra, e a segunda vê a consulta criada pela primeira.
# with_for_update: adiciona "FOR UPDATE" à consulta.
# -----------------------------------------------------------------------
def lock(self, session: Session, id: int) -> int | None:
return session.scalars(select(Client.id).where(Client.id == id).with_for_update()).first()
|
- Linhas 28–29: mais um método, que coloca um bloqueio no registro de um cliente: [with_for_update()] acrescenta [FOR UPDATE] à consulta ([SELECT clients.id FROM clients WHERE clients.id = ? FOR UPDATE]). Até o fim da transação, qualquer outra transação que peça o mesmo bloqueio espera. A camada de negócio usa isso para marcar consultas: duas consultas simultâneas para o mesmo paciente são assim processadas uma após a outra, e a segunda vê a consulta criada pela primeira (regra: apenas uma consulta futura por paciente). Esse bloqueio pessimista complementa o bloqueio otimista: o bloqueio otimista detecta uma modificação concorrente de uma linha, enquanto o bloqueio pessimista impede que duas transações tomem uma decisão com base nos mesmos dados ao mesmo tempo.
11.11.4. repositories/slot_repository.py
| # =========================================================================
# repositories/slot_repository.py
# -------------------------------------------------------------------------
# Camada DAO da entidade [Slot].
# =========================================================================
from sqlalchemy import delete, select
from sqlalchemy.orm import Session, joinedload
from rdvmedecins.entities import Slot
class SlotRepository:
# um horário e seu médico
def read(self, session: Session, id: int) -> Slot | None:
return session.get(Slot, id, options=[joinedload(Slot.doctor)])
# os horários de um médico, em ordem cronológica
def list_by_doctor(self, session: Session, doctor_id: int) -> list[Slot]:
query = (select(Slot).where(Slot.doctor_id == doctor_id)
.order_by(Slot.start_hour, Slot.start_minute))
return list(session.scalars(query))
# apaga todos os horários de um médico (exclusão de um médico):
# DELETE FROM slots WHERE doctor_id = ?
def delete_by_doctor(self, session: Session, doctor_id: int):
session.execute(delete(Slot).where(Slot.doctor_id == doctor_id))
|
Um horário de consulta (com um médico), os horários de consulta de um médico em ordem cronológica e a exclusão dos horários de consulta de um médico (quando o médico é removido).
11.11.5. repositories/appointment_repository.py
| # =========================================================================
# repositories/appointment_repository.py
# -------------------------------------------------------------------------
# Camada DAO da entidade [Appointment].
#
# join(Appointment.slot): um join SQL, escrito a partir do RELACIONAMENTO entre
# as duas classes (o SQLAlchemy conhece a chave estrangeira). contains_eager:
# as colunas da tabela unida servem TAMBÉM para preencher o relacionamento
# (appointment.slot), sem uma nova consulta.
# =========================================================================
from datetime import date
from sqlalchemy import delete, func, select
from sqlalchemy.orm import Session, contains_eager, joinedload
from rdvmedecins.entities import Slot, Appointment
class AppointmentRepository:
# uma consulta, seu cliente e seu horário
def read(self, session: Session, id: int) -> Appointment | None:
return session.get(Appointment, id, options=[joinedload(Appointment.client), joinedload(Appointment.slot)])
# as consultas de um médico em um dado dia, cliente e horário incluídos.
# A tabela [appointments] não referencia o médico diretamente: passamos pelo horário.
def doctor_day_appointments(self, session: Session, doctor_id: int, day: date) -> list[Appointment]:
query = (select(Appointment).join(Appointment.slot)
.options(contains_eager(Appointment.slot), joinedload(Appointment.client))
.where(Slot.doctor_id == doctor_id, Appointment.day == day))
return list(session.scalars(query))
# as consultas de um cliente a partir do dia [since] (incluído), em
# ordem cronológica, com o horário E o médico desse horário
def client_upcoming_appointments(self, session: Session, client_id: int, since: date) -> list[Appointment]:
query = (select(Appointment).join(Appointment.slot)
.options(contains_eager(Appointment.slot).joinedload(Slot.doctor))
.where(Appointment.client_id == client_id, Appointment.day >= since)
.order_by(Appointment.day, Slot.start_hour, Slot.start_minute))
return list(session.scalars(query))
# número de consultas de um cliente a partir do dia [since] (incluído)
def count_client_upcoming(self, session: Session, client_id: int, since: date) -> int:
query = select(func.count(Appointment.id)).where(Appointment.client_id == client_id, Appointment.day >= since)
return session.scalar(query)
# número de consultas (passadas ou futuras) de um médico
def count_by_doctor(self, session: Session, doctor_id: int) -> int:
query = select(func.count(Appointment.id)).join(Appointment.slot).where(Slot.doctor_id == doctor_id)
return session.scalar(query)
def add(self, session: Session, appointment: Appointment) -> Appointment:
session.add(appointment)
return appointment
# apaga uma consulta: DELETE FROM appointments WHERE id = ?
def remove(self, session: Session, id: int):
session.execute(delete(Appointment).where(Appointment.id == id))
# apaga TODAS as consultas (passadas e futuras) de um cliente
def delete_by_client(self, session: Session, client_id: int):
session.execute(delete(Appointment).where(Appointment.client_id == client_id))
|
- Linhas 27–31: as consultas de um médico em um determinado dia. A tabela [appointments] não referencia diretamente o médico: ela passa pelo horário de consulta. [join(Appointment.slot)] escreve a junção com base no relacionamento; o filtro se aplica a uma coluna da tabela unida ([Slot.doctor_id]). [contains_eager] reaproveita a junção para preencher [appointment.slot]; [joinedload] carrega o cliente: a agenda é construída em uma única consulta SQL;
- linhas 35–39: as consultas futuras de um cliente, com seus horários e o médico associado a cada horário;
- linhas 43–45: [func.count] gera a função SQL [COUNT], e [session.scalar] (no singular); [session.scalar] retorna a primeira coluna da primeira linha: a contagem;
- linhas 48–50: o número de consultas de um médico, para determinar se ele pode ser excluído;
- linhas 61–62: a exclusão das consultas de um cliente (quando o cliente é excluído).
11.11.6. repositories/user_repository.py
| # =========================================================================
# repositories/user_repository.py
# -------------------------------------------------------------------------
# Camada DAO da entidade [User]. Criar (ou apagar) um médico ou um
# cliente também cria (ou apaga) sua conta - veja business/service.py.
# =========================================================================
from sqlalchemy import delete, select
from sqlalchemy.orm import Session
from rdvmedecins.entities import User
class UserRepository:
# None se nenhum usuário tiver esse login
def read_by_login(self, session: Session, login: str) -> User | None:
return session.scalars(select(User).where(User.login == login)).first()
def add(self, session: Session, user: User) -> User:
session.add(user)
return user
def remove(self, session: Session, id: int):
session.execute(delete(User).where(User.id == id))
|
Leitura de um usuário pelo seu login (para entrar), adição e exclusão de uma conta.
11.12. A camada de negócio
A pasta [business] contém as regras de negócio, e somente elas. Ela não conhece [Flask], HTML nem a requisição HTTP: poderia ser usada como está em uma aplicação de linha de comando ou em uma API.
11.12.1. business/dates.py
| # =========================================================================
# business/dates.py
# -------------------------------------------------------------------------
# A data de hoje. Ela é usada por REGRAS DE NEGÓCIO (nenhuma marcação
# no passado, uma única consulta FUTURA por paciente): ela vive portanto
# na camada de negócio. A camada web a reutiliza.
# =========================================================================
from datetime import date
# a data de hoje, no fuso horário do servidor
def today() -> date:
return date.today()
|
A data atual é usada em duas regras de negócio (nenhuma consulta no passado, apenas uma consulta futura por paciente): ela pertence à camada de negócio. Isolá-la em uma função tem outra vantagem: um teste automatizado poderia substituí-la por uma data fixa.
11.12.2. business/exception.py
| # =========================================================================
# business/exception.py
# -------------------------------------------------------------------------
# A exceção lançada pela camada de negócio quando uma REGRA DE NEGÓCIO é
# violada (login já em uso, médico que ainda tem consultas, horário
# já reservado...). Ela não carrega um texto, mas uma CHAVE de
# tradução (ex.: "ERRORS.LOGIN_TAKEN"): é a camada web que a
# traduzirá para francês ou inglês ao exibir a página
# (veja i18n/fr.json, i18n/en.json).
#
# Uma BusinessException não é uma anomalia: é uma resposta normal
# ("este login já está em uso"), exibida ao usuário. Qualquer outra
# exceção é uma anomalia de verdade, que termina na página de erro 500.
# =========================================================================
class BusinessException(Exception):
def __init__(self, key: str, params: dict[str, str] | None = None):
super().__init__(key)
# chave de tradução da mensagem
self.key = key
# possíveis parâmetros da mensagem ({minutes}...)
self.params = params or {}
|
A exceção da camada de negócio não carrega texto, como no exemplo 28, mas sim uma chave de tradução ([ERRORS.LOGIN_TAKEN]) e eventuais parâmetros: a camada de negócio não sabe em que idioma o usuário está vendo a página. A camada web traduzirá a chave. [super().__init__(key)] passa a chave ao construtor da classe [Exception]: é o valor exibido se a exceção for registrada em log.
Uma [BusinessException] não é um erro: é uma resposta normal (“este nome de usuário já está em uso”), que é exibida ao usuário. Qualquer outra exceção é um erro verdadeiro, que resulta em uma página de erro 500.
11.12.3. business/person_data.py
| # =========================================================================
# business/person_data.py
# -------------------------------------------------------------------------
# Os dados digitados no formulário de "médico" ou de "cliente", como
# a camada web os repassa à camada de negócio.
# =========================================================================
from dataclasses import dataclass
@dataclass(frozen=True)
class PersonData:
title: str # Mr, Mme, Melle
last_name: str
first_name: str
# criação: opcional (None), por padrão o sobrenome em minúsculas
# edição: opcional, o login permanece inalterado se estiver ausente
login: str | None = None
# criação: opcional, por padrão o login
# edição: opcional, a senha permanece inalterada se estiver ausente
password: str | None = None
# edição: a versão do registro no momento em que o formulário foi
# exibido (bloqueio otimista, veja entities/base.py)
version: int | None = None
|
Dados de um formulário de “médico” ou “cliente”, transmitidos pela camada web (exemplo 28). O login, a senha e a versão são opcionais: os comentários explicam o que sua ausência significa na criação e na modificação.
11.12.4. business/business.py
| # =========================================================================
# business/business.py
# -------------------------------------------------------------------------
# O CONTRATO da camada de negócio: leituras, agenda, consultas, gestão
# dos médicos e dos clientes.
#
# Um Protocol descreve os métodos que um objeto deve ter, sem dizer como
# eles são escritos (o equivalente de uma interface). BusinessService (a
# camada de negócio) e ApplicationModel (o cache da camada web) ambos
# o respeitam. O Python não verifica nada em tempo de execução: são
# as ferramentas de análise (a do VS Code, por exemplo) que apontam uma incompatibilidade.
#
# T | None: um resultado que pode estar ausente (um médico que não existe...).
# =========================================================================
from datetime import date
from typing import Protocol
from rdvmedecins.domain.schedule import DoctorDaySchedule
from rdvmedecins.entities import Client, Slot, Doctor, Appointment
from rdvmedecins.business.person_data import PersonData
class Business(Protocol):
# ———————————————————————————————— leituras
def get_all_clients(self) -> list[Client]: ...
def get_all_doctors(self) -> list[Doctor]: ...
def get_all_slots(self, doctor_id: int) -> list[Slot]: ...
def get_doctor_day_appointments(self, doctor_id: int, day: date) -> list[Appointment]: ...
def get_client_by_id(self, id: int) -> Client | None: ...
def get_doctor_by_id(self, id: int) -> Doctor | None: ...
def get_appointment_by_id(self, id: int) -> Appointment | None: ...
def get_slot_by_id(self, id: int) -> Slot | None: ...
def get_doctor_day_schedule(self, doctor_id: int, day: date) -> DoctorDaySchedule | None: ...
# o cliente (paciente) cuja conta de usuário é [user_id]
def get_client_by_user_id(self, user_id: int) -> Client | None: ...
# as consultas de um cliente, de hoje ou futuras, com horário e médico
def get_client_upcoming_appointments(self, client_id: int) -> list[Appointment]: ...
# ———————————————————————————————— consultas (ADMIN, DOCTOR, USER)
# lança uma BusinessException se:
# - o dia for passado ("ERRORS.PAST_DATE");
# - o paciente já tiver uma consulta futura ("ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT");
# - o horário já estiver ocupado nesse dia ("ERRORS.SLOT_ALREADY_BOOKED").
def add_appointment(self, day: date, slot: Slot, client: Client) -> Appointment: ...
def delete_appointment(self, appointment: Appointment) -> None: ...
# ———————————————————————————————— médicos (ADMIN)
# cria o médico E sua conta de usuário (papel DOCTOR)
def add_doctor(self, data: PersonData) -> Doctor: ...
# edita o médico E sua conta de usuário
def edit_doctor(self, id: int, data: PersonData) -> Doctor: ...
# apaga o médico, seus horários E sua conta - recusado se ele tiver consultas
def delete_doctor(self, id: int) -> None: ...
# ———————————————————————————————— clientes
# (o ADMIN; add_client também é usado para o cadastro de um paciente,
# edit_client e delete_client pelo paciente para sua própria conta)
# cria o cliente E sua conta de usuário (papel USER)
def add_client(self, data: PersonData) -> Client: ...
def edit_client(self, id: int, data: PersonData) -> Client: ...
# apaga o cliente, sua conta E todas as suas consultas (passadas e futuras)
def delete_client(self, id: int) -> None: ...
|
- Linha 23: o contrato da camada de negócio: uma lista de seus métodos, com seus parâmetros e valores de retorno. Um [Protocol] (módulo padrão [typing]) é o equivalente, em [Python], de uma interface: descreve os métodos que um objeto deve ter, sem especificar como são implementados. Uma classe se conforma a ele desde que tenha esses métodos, sem precisar declará-lo (isso se chama tipagem estrutural, ou *duck typing*: “se anda como um pato…”). Duas classes se conformam a ele: [BusinessService], a camada de negócio, e [ApplicationModel], o cache da camada web (comentado adiante). O [Python] não verifica nada em tempo de execução: são as ferramentas de análise, como a do [Visual Studio Code], que apontam uma divergência;
- linha 26: o corpo de um método de protocolo se reduz a [...] (o objeto [Ellipsis] de [Python], que não faz nada);
- linhas 55–78: os comentários documentam a lógica de negócio e os códigos de erro de cada método.
11.12.5. business/service.py
A implementação da camada de negócio. É o arquivo mais importante da aplicação.
| # =========================================================================
# business/service.py
# -------------------------------------------------------------------------
# Implementação da camada de negócio.
#
# A gestão dos médicos e dos clientes segue 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, editadas e apagadas juntas, na
# mesma TRANSAÇÃO - ou tudo dá certo, ou nada é gravado;
# 2. o login é único em toda a aplicação, e dois médicos (ou
# dois clientes) não podem ter o mesmo nome e sobrenome;
# 3. exclusão:
# - um MÉDICO que tem consultas não pode ser apagado (seus
# pacientes perderiam a consulta sem serem avisados): elas devem
# ser canceladas antes. Seus horários desaparecem com ele;
# - um CLIENTE, por outro lado, desaparece com TODAS as suas consultas (passadas e
# futuras) - quer a exclusão venha do ADMIN ou do próprio
# paciente.
#
# E duas regras para 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 somente UMA consulta futura por vez.
#
# Médicos e clientes seguem exatamente as mesmas regras: o código comum
# é escrito UMA ÚNICA VEZ (métodos privados _xxx_person), e parametrizado por um
# pequeno "descritor" que diz com que tipo de pessoa estamos lidando.
#
# As TRANSAÇÕES são abertas pelo método _transaction (no final do
# arquivo), que também traduz em BusinessException os erros que o banco de dados
# informa quando as instruções SQL são enviadas a ele.
# =========================================================================
import re
from collections.abc import Callable
from dataclasses import dataclass
from datetime import date
from sqlalchemy.exc import IntegrityError
from sqlalchemy.orm import Session, sessionmaker
from sqlalchemy.orm.exc import StaleDataError
from rdvmedecins.auth.passwords import hash_password
from rdvmedecins.domain.schedule import DoctorDaySchedule, DoctorDaySlot
from rdvmedecins.entities import Client, Slot, Doctor, Person, Role, Appointment, User
from rdvmedecins.business import dates
from rdvmedecins.business.person_data import PersonData
from rdvmedecins.business.exception import BusinessException
from rdvmedecins.repositories.client_repository import ClientRepository
from rdvmedecins.repositories.slot_repository import SlotRepository
from rdvmedecins.repositories.doctor_repository import DoctorRepository
from rdvmedecins.repositories.person_repository import PersonRepository
from rdvmedecins.repositories.appointment_repository import AppointmentRepository
from rdvmedecins.repositories.user_repository import UserRepository
# tudo o que distingue um médico de um cliente para as regras de negócio
@dataclass(frozen=True)
class Descriptor:
dao: PersonRepository
factory: type[Person] # Doctor ou Client
role: Role # DOCTOR ou USER
not_found_key: str # mensagem se a pessoa não existe
already_exists_key: str # mensagem se já existem o mesmo nome e sobrenome
# opcional (None): se presente, a exclusão é RECUSADA enquanto a
# pessoa tiver consultas (count_appointments > 0), com a mensagem has_appointments_key
count_appointments: Callable[[Session, int], int] | None
has_appointments_key: str | None
# opcional: o que deve ser apagado ANTES da pessoa (as linhas que
# a referenciam por uma chave estrangeira)
before_delete: Callable[[Session, int], None] | None
# -----------------------------------------------------------------------
# Erros do banco de dados -> BusinessException
#
# Quando uma restrição UNIQUE recusa uma escrita, o SQLAlchemy lança uma
# IntegrityError, cujo atributo [orig] é o erro original, o do driver
# PyMySQL. Sua mensagem cita o NOME da restrição:
# Duplicate entry 'Marie-PELISSIER' for key 'doctors.unq_doctors_first_name_last_name'
# (o MySQL 8 prefixa o nome com o da tabela, o MariaDB não). É por
# isso que o script SQL NOMEIA todas as suas restrições.
# -----------------------------------------------------------------------
CONSTRAINT_MESSAGES = {
"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",
}
CONSTRAINT = re.compile(r"for key '(?:[^'.]*\.)?([^']+)'")
class BusinessService:
# todas as dependências são fornecidas pela factory da aplicação
# (veja rdvmedecins/__init__.py): é a injeção de dependência "à
# mão". sessions: a factory das sessões do SQLAlchemy.
def __init__(self, sessions: sessionmaker, doctors: DoctorRepository,
clients: ClientRepository, slots: SlotRepository, appointments: AppointmentRepository,
users: UserRepository):
self._sessions = sessions
self._doctors = doctors
self._clients = clients
self._slots = slots
self._appointments = appointments
self._users = users
self._doctor = Descriptor(
dao=doctors, factory=Doctor, role=Role.DOCTOR,
not_found_key="ERRORS.DOCTOR_NOT_FOUND",
already_exists_key="ERRORS.DOCTOR_ALREADY_EXISTS",
count_appointments=appointments.count_by_doctor,
has_appointments_key="ERRORS.DOCTOR_HAS_APPOINTMENTS",
# um médico sem consultas ainda pode ter horários:
# eles não fazem sentido sem ele, são apagados junto (caso contrário
# a chave estrangeira slots.doctor_id proibiria a exclusão)
before_delete=slots.delete_by_doctor)
self._client = Descriptor(
dao=clients, factory=Client, role=Role.USER,
not_found_key="ERRORS.PATIENT_NOT_FOUND",
already_exists_key="ERRORS.PATIENT_ALREADY_EXISTS",
# sem count_appointments: a exclusão de um cliente nunca é recusada;
# suas consultas (passadas e futuras) são apagadas junto (caso contrário
# a chave estrangeira appointments.client_id proibiria a exclusão)
count_appointments=None, has_appointments_key=None,
before_delete=appointments.delete_by_client)
# =======================================================================
# leituras: uma sessão, pelo tempo da leitura; os objetos lidos continuam
# utilizáveis depois (expire_on_commit=False, veja rdvmedecins/__init__.py)
# =======================================================================
def _read[R](self, work: Callable[[Session], R]) -> R:
with self._sessions() as session:
return work(session)
def get_all_clients(self) -> list[Client]:
return self._read(self._clients.list)
def get_all_doctors(self) -> list[Doctor]:
return self._read(self._doctors.list)
def get_all_slots(self, doctor_id: int) -> list[Slot]:
return self._read(lambda s: self._slots.list_by_doctor(s, doctor_id))
def get_doctor_day_appointments(self, doctor_id: int, day: date) -> list[Appointment]:
return self._read(lambda s: self._appointments.doctor_day_appointments(s, doctor_id, day))
def get_client_by_id(self, id: int) -> Client | None:
return self._read(lambda s: self._clients.read(s, id))
def get_doctor_by_id(self, id: int) -> Doctor | None:
return self._read(lambda s: self._doctors.read(s, id))
def get_appointment_by_id(self, id: int) -> Appointment | None:
return self._read(lambda s: self._appointments.read(s, id))
def get_slot_by_id(self, id: int) -> Slot | None:
return self._read(lambda s: self._slots.read(s, id))
def get_client_by_user_id(self, user_id: int) -> Client | None:
return self._read(lambda s: self._clients.read_by_user(s, user_id))
def get_client_upcoming_appointments(self, client_id: int) -> list[Appointment]:
return self._read(lambda s: self._appointments.client_upcoming_appointments(s, client_id, dates.today()))
# a agenda de um médico em um dado dia: seus horários, e para cada um a
# consulta marcada nesse dia (None se estiver livre)
def get_doctor_day_schedule(self, doctor_id: int, day: date) -> DoctorDaySchedule | None:
doctor = self.get_doctor_by_id(doctor_id)
if doctor is None:
return None
time_slots = self.get_all_slots(doctor_id)
# nº do horário -> consulta marcada nesse horário (uma "comprehension" de dicionário)
bookings = {a.slot_id: a for a in self.get_doctor_day_appointments(doctor_id, day)}
doctor_day_slots = [DoctorDaySlot(slot, bookings.get(slot.id))
for slot in time_slots]
return DoctorDaySchedule(doctor, day, doctor_day_slots)
# =======================================================================
# consultas
# =======================================================================
# -----------------------------------------------------------------------
# marcação de uma consulta, em uma transação:
# 1. nenhuma consulta no passado;
# 2. a linha do paciente é BLOQUEADA (SELECT ... FOR UPDATE): se o
# mesmo paciente marca dois horários ao mesmo tempo (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. uma única consulta futura por paciente;
# 4. por fim a inserção. Se o horário acabou de ser ocupado por OUTRO
# paciente, é a restrição SQL unq1_appointments (day, slot_id) que
# recusa a inserção - traduzida em BusinessException por _transaction.
# -----------------------------------------------------------------------
def add_appointment(self, day: date, slot: Slot, client: Client) -> Appointment:
def work(session: Session) -> Appointment:
today = dates.today()
if day < today:
raise BusinessException("ERRORS.PAST_DATE")
patient_id = self._clients.lock(session, client.id)
if patient_id is None:
raise BusinessException("ERRORS.PATIENT_NOT_FOUND")
if self._appointments.count_client_upcoming(session, patient_id, today) > 0:
raise BusinessException("ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT")
# conhecer os ids do horário e do paciente basta para escrever
# as chaves estrangeiras: não é preciso ler esses objetos de novo na sessão
return self._appointments.add(session, Appointment(day=day, slot_id=slot.id,
client_id=patient_id))
return self._transaction(work)
def delete_appointment(self, appointment: Appointment) -> None:
self._transaction(lambda session: self._appointments.remove(session, appointment.id))
# =======================================================================
# médicos e clientes - os métodos públicos delegam aos métodos
# privados comuns, com o descritor adequado
# =======================================================================
def add_doctor(self, data: PersonData) -> Doctor:
return self._add_person(self._doctor, data)
def edit_doctor(self, id: int, data: PersonData) -> Doctor:
return self._edit_person(self._doctor, id, data)
def delete_doctor(self, id: int) -> None:
self._delete_person(self._doctor, id)
def add_client(self, data: PersonData) -> Client:
return self._add_person(self._client, data)
def edit_client(self, id: int, data: PersonData) -> Client:
return self._edit_person(self._client, id, data)
# o cliente, sua conta E todas as suas consultas (ADMIN, ou o próprio paciente
# em "Gerenciar minha conta": mesmo método, mesma regra)
def delete_client(self, id: int) -> None:
self._delete_person(self._client, id)
# -----------------------------------------------------------------------
# criação: a conta de usuário E a pessoa, em UMA transação.
# -----------------------------------------------------------------------
def _add_person(self, d: Descriptor, data: PersonData):
last_name = data.last_name.strip().upper()
first_name = data.first_name.strip()
# as regras do banco de dados dbrdvmedecins2: login = sobrenome em minúsculas,
# senha = login - a menos que o ADMIN tenha digitado outros
login = (data.login or last_name).lower()
password = data.password or login
def work(session: Session):
self._check_person_unique(session, d, first_name, last_name, None)
self._check_login_free(session, login)
user = User(login=login, password=hash_password(password), name=f"{first_name} {last_name}", role=d.role)
person = d.factory(title=data.title, last_name=last_name, first_name=first_name, user=user)
# a pessoa referencia sua conta: o SQLAlchemy insere primeiro a
# conta (para conhecer seu id), depois a pessoa
d.dao.add(session, person)
# flush: os INSERTs saem imediatamente (e não no COMMIT); uma
# restrição violada lança portanto seu erro AQUI
session.flush()
return person
return self._transaction(work)
# -----------------------------------------------------------------------
# edição: a pessoa E sua conta (o nome exibido "nome SOBRENOME"
# deve acompanhar; o login e a senha só mudam se tiverem sido
# digitados).
# -----------------------------------------------------------------------
def _edit_person(self, d: Descriptor, id: int, data: PersonData):
def work(session: Session):
person = d.dao.read(session, id)
if person is None:
raise BusinessException(d.not_found_key)
# bloqueio otimista: se a versão no banco de dados não é mais a do
# formulário, alguém editou este registro nesse meio-tempo - recusamos
# em vez de sobrescrever silenciosamente suas alterações.
# (Se a edição concorrente ocorrer DEPOIS desta leitura, é
# a cláusula "WHERE version = ..." do UPDATE que a detecta.)
if data.version is not None and data.version != person.version:
raise BusinessException("ERRORS.CONCURRENT_UPDATE")
last_name = data.last_name.strip().upper()
first_name = data.first_name.strip()
self._check_person_unique(session, d, first_name, last_name, id)
# apenas modificamos os objetos: eles são "rastreados" pela
# sessão, que enviará ela mesma os UPDATEs necessários
person.title = data.title
person.last_name = last_name
person.first_name = first_name
user = person.user
user.name = f"{first_name} {last_name}"
if data.login and data.login.lower() != user.login:
login = data.login.lower()
self._check_login_free(session, login)
user.login = login
if data.password:
user.password = hash_password(data.password)
session.flush()
return person
return self._transaction(work)
# -----------------------------------------------------------------------
# exclusão, em UMA transação, na ordem imposta pelas chaves
# estrangeiras:
# 1. possível recusa se restarem consultas (médico);
# 2. o que referencia a pessoa (horários de um médico, consultas
# de um cliente);
# 3. a pessoa (ela referencia sua conta);
# 4. sua conta.
# -----------------------------------------------------------------------
def _delete_person(self, d: Descriptor, id: int) -> None:
def work(session: Session):
person = d.dao.read(session, id)
if person is None:
raise BusinessException(d.not_found_key)
if d.count_appointments is not None and d.count_appointments(session, id) > 0:
raise BusinessException(d.has_appointments_key)
if d.before_delete is not None:
d.before_delete(session, id)
d.dao.remove(session, id)
self._users.remove(session, person.user_id)
self._transaction(work)
# recusa nome e sobrenome já usados por OUTRA pessoa do mesmo tipo
# (current_id: a pessoa sendo editada, que obviamente tem o
# direito de manter seu próprio nome e sobrenome; None para uma criação)
@staticmethod
def _check_person_unique(session: Session, d: Descriptor, first_name: str, last_name: str,
current_id: int | None):
namesake = d.dao.namesake(session, first_name, last_name)
if namesake is not None and namesake.id != current_id:
raise BusinessException(d.already_exists_key)
def _check_login_free(self, session: Session, login: str):
if self._users.read_by_login(session, login) is not None:
raise BusinessException("ERRORS.LOGIN_TAKEN")
# -----------------------------------------------------------------------
# executa [work] em uma transação:
# sessions.begin() -> uma sessão e sua transação (START TRANSACTION);
# ao sair do bloco with: COMMIT se tudo correu bem; se uma
# exceção sair dele (BusinessException incluída), ROLLBACK: nada é gravado.
#
# As verificações de "login livre" e de "nome + sobrenome únicos" 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
# raro caso, é uma restrição de unicidade SQL que recusa a segunda
# escrita. Os erros do banco de dados são portanto interceptados EM VOLTA da
# transação, para traduzi-los na mesma BusinessException:
# - StaleDataError: o UPDATE "WHERE id = ... AND version = ..." não
# modificou nenhuma linha (bloqueio otimista);
# - IntegrityError: uma restrição do banco de dados recusou a escrita.
# Qualquer outro erro é uma anomalia de verdade: deixamos passar.
# -----------------------------------------------------------------------
def _transaction[R](self, work: Callable[[Session], R]) -> R:
try:
with self._sessions.begin() as session:
return work(session)
except StaleDataError:
raise BusinessException("ERRORS.CONCURRENT_UPDATE")
except IntegrityError as e:
match = CONSTRAINT.search(str(e.orig))
if match and match.group(1) in CONSTRAINT_MESSAGES:
raise BusinessException(CONSTRAINT_MESSAGES[match.group(1)])
raise
|
11.12.5.1. Os descritores
Médicos e clientes seguem exatamente as mesmas regras de negócio, com pequenas diferenças: um DAO diferente, um papel diferente para a conta, mensagens de erro diferentes e uma regra de exclusão diferente. Em vez de escrever cada método duas vezes, o código comum é escrito uma única vez (os métodos [_add_person], [_edit_person], [_delete_person]) e configurado por um descritor que especifica qual tipo de pessoa está sendo tratado:
- linhas 59–71: o descritor é um [dataclass] imutável. Três de seus campos são funções: [Callable[[Session, int], int]] é o tipo de uma função que recebe uma sessão e um inteiro e retorna um inteiro. [count_appointments] conta as consultas de uma pessoa (para impedir a exclusão de um médico que tenha alguma); [before_delete] exclui as referências à pessoa (os horários de um médico, as consultas de um cliente);
- linhas 109–118: o descritor dos médicos. [appointments.count_by_doctor] é um método associado ao objeto [appointments] (Exemplo 22): uma função que receberá a sessão e o ID;
- linhas 120–128: o dos clientes: sem recusa de exclusão ([count_appointments=None]), mas com a exclusão prévia de todas as suas consultas.
11.12.5.2. Operações de leitura e a agenda
- linhas 135–137: as leituras são tratadas por um pequeno método genérico: [R] é o tipo do resultado, o mesmo da função [work]. A sessão é aberta por [self._sessions()] (sem [begin]) enquanto a função é executada e depois fechada pelo bloco [with]. [SQLAlchemy] ainda inicia uma transação na primeira requisição ([BEGIN (implicit)] no console); como nada foi escrito, o fechamento da sessão a cancela ([ROLLBACK]): são as linhas que o console exibe quando a aplicação é iniciada;
- linhas 139–167: cada leitura instrui [_read] a chamar o método do DAO. Quando o método do DAO tem parâmetros além da sessão, uma função anônima ([lambda s: ...]) os fornece;
- Linhas 171–180: a agenda de um médico para um único dia. As consultas do dia são armazenadas em um dicionário ([{key: value for ...}]) que associa o número de cada horário à consulta correspondente; cada horário é então associado à sua consulta, ou a [None] ([bookings.get(slot.id)]). São três leituras, em três sessões: qualquer inconsistência entre elas (uma consulta marcada entre duas leituras) seria irrelevante, pois a agenda serve apenas para exibição.
11.12.5.3. Marcação de uma consulta
- Linhas 198–213: o método define uma função interna, [work], que contém as operações a executar na transação, e a passa ao método [_transaction] (veja adiante). As regras, em ordem: - nenhuma consulta no passado ([day < today]: as datas em [Python] são comparadas com os operadores usuais); - o registro do paciente é bloqueado ([lock], veja [ClientRepository]): se o mesmo paciente reservar dois horários ao mesmo tempo (duas abas, um clique duplo), a segunda transação espera a primeira terminar e então enxerga a consulta que ela criou; - apenas uma consulta futura por paciente; - por fim, a inserção. A consulta é criada a partir do ID do horário e do ID do paciente: basta conhecer os valores das chaves estrangeiras; não é preciso reler os objetos. Os parâmetros nomeados do construtor ([Appointment(day=..., slot_id=...)]) são fornecidos por [SQLAlchemy] a toda entidade que não tenha construtor próprio.
- Resta um cenário: o horário acabou de ser ocupado por outro paciente entre o momento em que a agenda é exibida e o momento da reserva. Nesse caso, a restrição do banco de dados [unq1_appointments] impede a inserção durante a operação [COMMIT]. O método [_transaction] traduz esse erro em [BusinessException];
- linhas 215–216: cancelamento de uma consulta. As verificações de permissão (um paciente só pode cancelar as próprias consultas) são feitas pela camada web, que conhece o usuário.
11.12.5.4. Gerenciamento de médicos e clientes
- linhas 223–241: os métodos públicos delegam aos métodos comuns, usando o descritor correto;
- linhas 246–267: criação. O sobrenome é colocado em maiúsculas e os espaços são removidos do nome; o nome de usuário padrão é o sobrenome em minúsculas, e a senha é o nome de usuário (a regra das contas de demonstração no script SQL). Na transação: validações (sem homônimos, login livre), seguidas da criação da conta e da pessoa. A pessoa recebe sua conta por meio de seu relacionamento ([user=user]): [SQLAlchemy] sabe que deve inserir primeiro a conta para obter seu ID e depois a pessoa. [session.flush()] envia [INSERT] imediatamente: uma restrição violada provoca um erro na transação, e a pessoa retornada já tem seu ID;
- linhas 274–309: a atualização. A versão do formulário é comparada à versão do banco de dados (bloqueio otimista, exemplo 28); depois, basta atualizar os objetos recuperados: eles são rastreados pela sessão, que enviará por conta própria os registros [UPDATE] necessários. O nome de conta exibido acompanha o nome e o sobrenome; o login e a senha só mudam se tiverem sido informados;
- linhas 320–332: exclusão, na ordem ditada pelas chaves estrangeiras: eventual recusa (um médico que tenha consultas), exclusão das referências à pessoa, da própria pessoa e, por fim, de sua conta. Na ordem inversa, o banco de dados rejeitaria cada [DELETE]. Tudo isso ocorre em uma única transação: se qualquer etapa falhar, nenhuma é executada;
- linhas 337–342: um homônimo é rejeitado, a menos que seja a própria pessoa que está sendo editada, que tem o direito de manter seu nome e sobrenome;
- linhas 344–346: um nome de usuário só pode pertencer a uma conta.
11.12.5.5. Transações e restrições de unicidade
- linhas 365–375: todas as atualizações passam por este método. [sessions.begin()] abre uma sessão e sua transação; ao sair do bloco [with], a transação é confirmada ([COMMIT]) se tudo correu bem, ou revertida ([ROLLBACK]) se ocorrer uma exceção, inclusive [BusinessException];
- linhas 369–370: o bloqueio otimista detectou uma modificação concorrente (exemplo 28);
- linhas 371–374: uma restrição do banco de dados rejeitou a escrita. As verificações feitas antes da escrita (nome de usuário único, sem homônimos) fornecem uma mensagem clara na grande maioria dos casos; porém, dois administradores podem cadastrar o mesmo nome de usuário ao mesmo tempo, ou dois pacientes podem reservar o mesmo horário. A restrição de unicidade rejeita então a segunda escrita, e [SQLAlchemy] lança uma [IntegrityError]. Sua mensagem original ([e.orig], o erro de [PyMySQL]) cita o nome da restrição (aqui com [MariaDB], para o segundo horário reservado duas vezes no mesmo dia):
| (1062, "Duplicate entry '2026-09-26-2' for key 'unq1_appointments'")
|
- A expressão regular [CONSTRAINT] (linha 91) extrai esse nome. [MySQL] 8 adiciona o prefixo com o nome da tabela (['appointments.unq1_appointments']), [MariaDB] não: a parte [(?:[^'.]*\.)?] aceita esse prefixo opcional ([(?:...)] é um grupo sem captura, [?] o torna opcional). O dicionário [CONSTRAINT_MESSAGES] (linhas 84–88) associa cada restrição conhecida à chave de sua mensagem. É por isso que o script SQL dá nome a todas as suas restrições;
- linha 375: qualquer outro erro é uma anomalia real: [raise], sem parâmetros, relança a exceção atual, o que resultará em uma página de erro 500.
Observe a estrutura de todos os métodos de escrita: uma função interna [work], que contém as operações, é passada a [_transaction], que a executa dentro de uma transação e traduz os erros. Isso equivale à anotação ***[@Transactional]*** do *[Spring]*, escrita em apenas algumas linhas: uma função é um objeto como qualquer outro, que pode ser passado como parâmetro.
11.13. Autenticação
A pasta [auth] incorpora os mecanismos dos Exemplos 25 a 27, com três diferenças: a regra de acesso é invertida (tudo é proibido, exceto o que for declarado público), os usuários são obtidos do banco de dados, e a criação de uma conta de cliente é protegida por um “passe”.
11.13.1. auth/passwords.py
| # =========================================================================
# auth/passwords.py
# -------------------------------------------------------------------------
# Hash de senhas: bcrypt, 10 rodadas, versão $2b$ - como os
# hashes do script SQL.
#
# o bcrypt só leva em conta os primeiros 72 BYTES de uma senha (um
# caractere acentuado ocupa dois deles, em UTF-8); a biblioteca bcrypt
# chega a recusar uma senha mais longa. Passamos a ele portanto apenas
# esses 72 bytes, na criação como na verificação.
# =========================================================================
import bcrypt
def _bytes(password: str) -> bytes:
return password.encode("utf-8")[:72]
# o hash a guardar no banco de dados: "$2b$10$" + o salt + o resultado
def hash_password(password: str) -> str:
return bcrypt.hashpw(_bytes(password), bcrypt.gensalt(rounds=10)).decode("ascii")
# checkpw calcula o hash da senha digitada com o "salt" contido no hash
# guardado, depois compara os dois resultados
def verify(password: str, hashed: str) -> bool:
return bcrypt.checkpw(_bytes(password), hashed.encode("ascii"))
|
- Linhas 15–16: [bcrypt] considera apenas os primeiros 72 bytes de uma senha, e a versão 5 da biblioteca rejeita senhas mais longas (Exemplo 25). Por isso, apenas esses 72 bytes são passados a ela, tanto na criação quanto na verificação: uma senha mais longa é aceita, mas os caracteres além do 72º byte são ignorados. Um caractere acentuado ocupa dois bytes em [UTF-8];
- linhas 20–21: o hash é armazenado em forma de texto: [decode("ascii")] converte em string os bytes retornados por [bcrypt] ;
- linhas 26–27: verificação (exemplo 25). Este módulo é usado pela autenticação e pela camada de negócio (criação de conta, alteração de senha).
11.13.2. auth/connected_user.py
| # =========================================================================
# auth/connected_user.py
# -------------------------------------------------------------------------
# O que o token JWT contém, e como lê-lo de volta.
#
# Os claims dos nossos tokens (veja AuthService.set_token):
# sub : o id da conta de usuário (convenção JWT: "subject"), como texto
# login : o login
# name : o nome exibido ("Marie PELISSIER"), para a barra de navegação
# role : ADMIN, DOCTOR ou USER
# iat, exp : datas de criação e de expiração do token
# =========================================================================
from dataclasses import dataclass
from rdvmedecins.entities import Role
# o usuário conectado, em forma tipada
@dataclass(frozen=True)
class ConnectedUser:
user_id: int
login: str
name: str
role: Role
# o usuário descrito pelas claims de um token já verificado; None se
# uma claim estiver ausente ou não tiver a forma esperada
@staticmethod
def of(claims: dict) -> "ConnectedUser | None":
try:
return ConnectedUser(int(claims["sub"]), claims["login"], claims["name"],
Role(claims["role"]))
except (KeyError, ValueError, TypeError):
return None
@property
def is_admin(self) -> bool:
return self.role == Role.ADMIN
@property
def is_patient(self) -> bool:
return self.role == Role.USER
|
- linhas 20–24: o usuário conectado, em forma tipada: o Exemplo 25 armazenava em [g.user] o dicionário de declarações do token; a aplicação armazena este objeto, cujos atributos são conhecidos pelo editor ([g.user.role]) e cujo papel é um valor da enumeração [Role];
- linhas 29–34: construção a partir das declarações de um token já verificado. O tipo do resultado é escrito entre aspas (["ConnectedUser | None"]): quando [Python] lê a definição do método, a classe [ConnectedUser] ainda não está totalmente definida, e seu nome não pode ser usado diretamente. Um token com uma declaração ausente ([KeyError]) ou com um valor inesperado ([ValueError]: um papel desconhecido, um [sub] que não é um número) resulta em [None]: o usuário não está autenticado;
- linhas 36–42: duas propriedades: o decorador [@property] transforma um método em uma propriedade calculada, usada sem parênteses: [g.user.is_admin].
O token contém o ID da conta ([sub], em forma de texto, como exige o padrão JWT), o login, o nome de exibição e o papel: tudo de que a barra de navegação e as regras de acesso precisam, sem consultar o banco de dados a cada requisição.
11.13.3. auth/auth_service.py
| # =========================================================================
# auth/auth_service.py
# -------------------------------------------------------------------------
# A lógica de autenticação:
# - validate_user() : verifica um par login / senha;
# - set_token() : constrói o token JWT de um usuário validado
# e o coloca em um cookie da resposta;
# - clear_token() : apaga esse cookie;
# - current_user() : o usuário descrito pelo cookie da requisição.
#
# Por onde viaja o token JWT?
# Com um cliente JavaScript, era o código do cliente que guardava o token
# 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 sozinho a cada requisição, o token
# deve ser armazenado em um COOKIE. As opções desse 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 em um POST vindo
# de outro site (primeira proteção contra o chamado ataque CSRF; a
# segunda é o token anti-CSRF dos formulários, veja rdvmedecins/__init__.py);
# - Secure: em produção (HTTPS), o cookie nunca trafega em claro;
# - Max-Age: o cookie desaparece ao mesmo tempo que o token expira.
# =========================================================================
from datetime import datetime, timedelta, timezone
import jwt
from flask import Request, Response
from rdvmedecins.auth.passwords import verify
from rdvmedecins.auth.connected_user import ConnectedUser
from rdvmedecins.entities import User
from rdvmedecins.repositories.user_repository import UserRepository
# o nome do cookie que carrega o token
JWT_COOKIE = "rdvmedecins_jwt"
class AuthService:
def __init__(self, sessions, users: UserRepository, secret: str, duration_seconds: int,
cookie_secure: bool):
# O HMAC-SHA256 exige uma chave de pelo menos 256 bits: dizemos isso
# claramente na inicialização, e não no primeiro login
if len(secret.encode("utf-8")) < 32:
raise RuntimeError("JWT_SECRET must be at least 32 characters long (see config.py).")
self._sessions = sessions
self._users = users
self._secret = secret
self._duration = timedelta(seconds=duration_seconds)
self._cookie_secure = cookie_secure
# None se o login não existir ou se a senha estiver errada
def validate_user(self, login: str, password: str) -> User | None:
with self._sessions() as session:
user = self._users.read_by_login(session, login)
if user is None or not verify(password, user.password):
return None
return user
# -----------------------------------------------------------------------
# constrói o token JWT de [user] e o coloca em um cookie.
# O token é ASSINADO (HMAC-SHA256) com a chave secreta: o navegador
# pode lê-lo (ele não é criptografado), mas não modificá-lo - qualquer
# modificação invalidaria a assinatura.
# -----------------------------------------------------------------------
def set_token(self, response: Response, user: User):
now = datetime.now(timezone.utc)
claims = {
"sub": str(user.id),
"login": user.login,
"name": user.name,
"role": user.role.value,
"iat": now,
"exp": now + self._duration,
}
token = jwt.encode(claims, self._secret, algorithm="HS256")
response.set_cookie(JWT_COOKIE, token, max_age=self._duration, path="/", httponly=True,
samesite="Lax", secure=self._cookie_secure)
# apaga o cookie: ele é definido novamente, vazio, com tempo de vida zero
@staticmethod
def clear_token(response: Response):
response.delete_cookie(JWT_COOKIE, path="/")
# o token presente na requisição, válido ou não
@staticmethod
def token_of(request: Request) -> str | None:
return request.cookies.get(JWT_COOKIE)
# -----------------------------------------------------------------------
# o usuário descrito pelo cookie da requisição; None se não houver
# token, ou se o token estiver expirado, forjado ou malformado.
# jwt.decode verifica a assinatura E a data de expiração (claim exp).
# -----------------------------------------------------------------------
def current_user(self, request: Request) -> ConnectedUser | None:
token = self.token_of(request)
if not token:
return None
try:
claims = jwt.decode(token, self._secret, algorithms=["HS256"])
except jwt.InvalidTokenError:
return None
return ConnectedUser.of(claims)
|
- linhas 46–47: uma chave de assinatura curta demais é sinalizada quando a aplicação inicia, e não no primeiro login: [create_app] cria o serviço, e a exceção encerra a aplicação com esta mensagem;
- Linhas 55–60: verificação de um nome de usuário e de uma senha. O serviço lê o usuário por meio do DAO, em uma sessão que permanece aberta apenas durante essa leitura; a verificação da senha ([bcrypt], que é lenta) ocorre depois que a sessão é fechada, para evitar manter uma conexão desnecessária com o banco de dados;
- Linhas 68–80: o token (exemplo 25) e seu cookie, [rdvmedecins_jwt]. [user.role.value]: o valor da enumeração, a string ["USER"]. O cookie recebe o atributo [Secure] em produção ([COOKIE_SECURE]);
- linhas 84–85: exclusão do cookie. Este é um método estático: não exige um objeto e é chamado na classe ([AuthService.clear_token(response)]);
- linhas 97–105: o usuário identificado pelo cookie da requisição, ou [None].
11.13.4. auth/security.py
O núcleo da segurança: a autenticação de cada requisição e a regra de acesso.
| # =========================================================================
# auth/security.py
# -------------------------------------------------------------------------
# Quem pode acessar o quê, e como o usuário é reconhecido em cada
# requisição (veja os exemplos 25 e 26).
#
# Para cada requisição, a função authenticate (um before_request da
# aplicação):
# 1. lê o token do cookie, verifica sua assinatura e sua data de expiração,
# e armazena o usuário em g.user (None se não houver);
# 2. aplica a regra de acesso: TODAS as ações exigem um usuário
# autenticado, exceto as marcadas com @public (login,
# criação de conta, escolha do idioma) e os arquivos estáticos.
# É a regra "tudo é proibido, exceto o que é permitido": uma ação
# adicionada depois, que alguém tenha esquecido de proteger, fica protegida por padrão.
# Só então o Flask chama a ação, cujo decorador
# @roles_required(...) verifica o papel.
#
# Dois casos de falha, duas respostas adequadas a uma aplicação HTML:
# - nenhum usuário autenticado (sem token, token expirado ou forjado)
# -> redirecionamento para a página de login;
# - papel insuficiente -> resposta 403, que web/errors.py transforma em uma página.
# =========================================================================
from functools import wraps
from flask import abort, current_app, g, redirect, request, url_for
from rdvmedecins.auth.auth_service import AuthService
from rdvmedecins.entities import Role
from rdvmedecins.web.flash import flash_error
# o token é válido, mas a conta que ele designa não existe mais: ela foi
# excluída desde o login (pelo próprio paciente em outra
# aba, ou pelo ADMIN). Esse caso é tratado como uma sessão expirada:
# web/errors.py apaga o cookie e redireciona para a página de login.
class InvalidSession(Exception):
pass
# um decorador que MARCA uma ação como pública (veja o exemplo 24)
def public(action):
action.public = True
return action
def register(app, auth_service: AuthService):
@app.before_request
def authenticate():
g.user = auth_service.current_user(request)
# nenhuma rota corresponde (a página 404 virá a seguir), ou um arquivo estático
if request.endpoint is None or request.endpoint == "static":
return None
action = current_app.view_functions[request.endpoint]
if getattr(action, "public", False) or g.user is not None:
return None
# uma resposta retornada por um before_request interrompe o processamento:
# a ação não é chamada
return to_login()
# -----------------------------------------------------------------------
# nenhum usuário autenticado -> página de login. Se havia um cookie
# presente, seu token não é mais válido: a sessão expirou.
# O cookie é então apagado, e o usuário é avisado por uma mensagem flash.
# -----------------------------------------------------------------------
def to_login():
response = redirect(url_for("auth.show_login"))
if AuthService.token_of(request):
AuthService.clear_token(response)
flash_error("ERRORS.SESSION_EXPIRED")
return response
# -----------------------------------------------------------------------
# o papel do usuário deve ser um dos [roles]; caso contrário, resposta 403.
# require_roles é chamado a partir de um before_request de blueprint (todas as
# ações do blueprint, veja controllers/persons.py); roles_required é
# o decorador de uma ação (veja o exemplo 26).
# -----------------------------------------------------------------------
def require_roles(*roles: Role):
if g.user is None:
raise InvalidSession()
if g.user.role not in roles:
abort(403)
def roles_required(*roles: Role):
def decorator(action):
@wraps(action)
def protected_action(*args, **kwargs):
require_roles(*roles)
return action(*args, **kwargs)
return protected_action
return decorator
|
- linhas 37–38: uma exceção para um caso especial: o token é válido, mas a conta a que se refere não existe mais (o paciente a excluiu em outra aba, ou o administrador a excluiu). As ações que exigem a conta lançam essa exceção; o tratador de erros a trata como uma sessão expirada (veja [web/errors.py]);
- linhas 42–44: o decorador que marca uma ação como pública (exemplo 24);
- linhas 50–60: a função [before_request] da aplicação. Primeiro, o usuário é autenticado em todas as requisições, inclusive as públicas: a página de login precisa saber se o usuário já está conectado. Em seguida, a regra de acesso: é permitida uma requisição que não corresponde a nenhuma rota ([request.endpoint is None]: a página 404 virá a seguir) ou que pede um arquivo estático; é permitida uma ação marcada como pública; é permitido um usuário autenticado. Caso contrário, a função retorna uma resposta (redirecionando para a página de login), o que interrompe o processamento: a ação não é chamada.
Esta é a regra “tudo é proibido, a menos que seja explicitamente permitido”: uma ação adicionada depois — mesmo que você se esqueça de protegê-la — fica automaticamente protegida. Esquecer de incluir [@public] em uma ação pública é imediatamente evidente (a página redireciona para o login); deixar de proteger uma ação privada não é evidente de imediato: a regra padrão deve ser a mais segura. Esta também é a regra da versão [Spring MVC] ([anyRequest().authenticated()]);
- linhas 68–73: o redirecionamento para a página de login. Se a requisição continha um cookie de token, significa que esse token não é mais válido (expirou ou foi adulterado): o cookie é excluído, e uma mensagem em um pop-up explica ao usuário que sua sessão expirou (a captura de tela da mensagem de fim de sessão, mostrada acima);
- linhas 82–86: autorização. O parâmetro [*roles] aceita qualquer número de papéis em uma tupla: [require_roles(Role.ADMIN, Role.DOCTOR)]. Um papel ausente da lista resulta em um erro 403. O teste [g.user is None] nunca deveria ser verdadeiro (a regra de acesso já filtrou os visitantes anônimos), a menos que [require_roles] fosse chamado a partir de uma ação pública: isso fornece uma camada adicional de segurança;
- linhas 89–98: o decorador com parâmetros do Exemplo 26, que chama [require_roles]. [require_roles] também pode ser usado isoladamente, no [before_request] de um blueprint, para proteger todas as suas ações de uma só vez (veja [controllers/persons.py]).
11.13.5. auth/captcha_drawing.py
A renderização da imagem é a mesma do Exemplo 27, reproduzida exatamente como está. Seu comentário de cabeçalho destaca um ponto importante: cada caractere é desenhado por meio de linhas (elementos [<path>]), e nunca escrito como texto (um elemento [<text>]); caso contrário, um robô só precisaria ler o código-fonte da imagem.
11.13.6. auth/captcha.py
| # =========================================================================
# auth/captcha.py
# -------------------------------------------------------------------------
# Um CAPTCHA ("teste para distinguir um humano de um robô") feito pelo
# próprio servidor, sem nenhum serviço externo: alguns caracteres distorcidos,
# embaralhados por linhas, em uma imagem SVG (veja captcha_drawing.py). 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, faz uma imagem dele e armazena a
# resposta correta NA MEMÓRIA DO SERVIDOR, sob um identificador aleatório;
# 2. a página exibe a imagem e coloca o identificador em um campo oculto do
# formulário (a resposta em si nunca sai do servidor);
# 3. verify(id, typed) compara a entrada com a resposta esperada e depois
# ESQUECE esse captcha: cada imagem é usada uma única vez, um robô não pode
# reutilizar uma resposta já encontrada.
#
# Um único objeto CaptchaService para todo o servidor, usado por várias
# requisições EM PARALELO (o servidor as processa em várias threads): um
# lock (Lock) garante que apenas uma thread por vez leia ou modifique o
# dicionário dos captchas pendentes.
#
# Limite aceito: a memória de um único processo. Com vários processos
# ou vários servidores, seria necessário um armazenamento compartilhado.
# =========================================================================
import secrets
from dataclasses import dataclass
from datetime import datetime, timedelta
from threading import Lock
from rdvmedecins.auth import captcha_drawing
# duração de validade de uma imagem: há 10 minutos para preencher o formulário
LIFETIME = timedelta(minutes=10)
# salvaguarda de memória: acima disso, todos os captchas pendentes são esquecidos
MAX_CAPTCHAS = 10_000
# um captcha: id, a colocar no campo oculto "captchaId" do formulário;
# svg, a imagem, a inserir como está na página
@dataclass(frozen=True)
class Captcha:
id: str
svg: str
class CaptchaService:
def __init__(self):
# id -> (resposta esperada, data de expiração)
self._pending: dict[str, tuple[str, datetime]] = {}
self._lock = Lock()
def generate(self) -> Captcha:
text = captcha_drawing.random_text(5) # 5 caracteres
id = secrets.token_urlsafe(16) # um identificador aleatório, impossível de adivinhar
with self._lock:
self._purge()
self._pending[id] = (text, datetime.now() + LIFETIME)
return Captcha(id, captcha_drawing.svg(text))
# true se [typed] for a resposta certa ao captcha [id] (sem distinção entre
# maiúsculas e minúsculas). O captcha é consumido em todos os casos: se duas
# requisições apresentarem o mesmo captcha no mesmo instante, apenas uma
# o remove (pop, sob o lock) - a outra falha.
def verify(self, id: str | None, typed: str | None) -> bool:
with self._lock:
expected = self._pending.pop(id, None) if id else None
if expected is None or typed is None:
return False
text, expires = expected
return expires > datetime.now() and text.lower() == typed.strip().lower()
# (chamado sob o lock)
def _purge(self):
now = datetime.now()
for id in [id for id, (_, expires) in self._pending.items() if expires <= now]:
del self._pending[id]
if len(self._pending) >= MAX_CAPTCHAS:
self._pending.clear()
|
O serviço do Exemplo 27, com um acréscimo: o método [_purge] (linhas 77–82), chamado a cada criação de um CAPTCHA, descarta os CAPTCHAs expirados. Sem ele, os CAPTCHAs exibidos mas nunca utilizados (como quando uma página de login é aberta e depois abandonada) se acumulariam na memória. [MAX_CAPTCHAS] funciona como salvaguarda: um robô que solicitasse milhões de páginas de login não conseguiria esgotar a memória do servidor. O número [10_000] é escrito com um sublinhado, que separa os milhares para facilitar a leitura ([Python] o ignora). A lista de identificadores a excluir é construída antes do laço de exclusão: não é possível excluir chaves de um dicionário enquanto ele é percorrido.
11.13.7. auth/limiter.py
| # =========================================================================
# auth/limiter.py
# -------------------------------------------------------------------------
# Segunda linha de defesa contra robôs (a primeira é o captcha): CONTAMOS
# as tentativas e, acima de um limite, BLOQUEAMOS por um tempo.
#
# - login: após LOGIN_MAX_FAILURES falhas (captcha errado ou senha
# errada) para o mesmo login a partir do mesmo endereço IP, esse par
# é bloqueado por LOGIN_BLOCK_MINUTES minutos. O mesmo endereço IP também é
# bloqueado se acumular 5 vezes mais falhas, todos os logins juntos (um
# robô 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.
#
# Cuidado em uma sala de aula: todos os computadores costumam sair para a Internet
# pelo MESMO endereço IP. É por isso que o bloqueio de login se aplica
# primeiro ao par (IP, login) - um aluno que erra a
# senha não bloqueia seus colegas - e por isso os limites podem ser definidos
# em config.py.
#
# Um único objeto para todo o servidor, chamado por requisições paralelas:
# todos os métodos públicos pegam o lock - apenas uma thread por
# vez lê E modifica os contadores.
# =========================================================================
import math
from datetime import datetime, timedelta
from threading import Lock
ONE_HOUR = timedelta(hours=1)
class Counter:
def __init__(self, start: datetime):
self.number = 0 # tentativas contadas na janela atual
self.start = start # início da janela de contagem
self.blocked_until = datetime.min # datetime.min se não estiver bloqueado
class AttemptLimiter:
def __init__(self, login_max_failures: int, login_block_minutes: int,
registration_max_per_hour: int):
self._counters: dict[str, Counter] = {}
self._lock = Lock()
self._max_login_failures = login_max_failures
self._login_block_duration = timedelta(minutes=login_block_minutes)
self._max_registrations = registration_max_per_hour
# ---------------------------------------------------------------- login
# número de minutos de bloqueio restantes (0 = a tentativa é permitida)
def login_block_minutes(self, ip: str, login: str) -> int:
with self._lock:
return max(self._remaining_minutes(self._login_key(ip, login)),
self._remaining_minutes(self._ip_key(ip)))
def login_failure(self, ip: str, login: str):
with self._lock:
self._count(self._login_key(ip, login), self._max_login_failures,
self._login_block_duration, self._login_block_duration)
self._count(self._ip_key(ip), self._max_login_failures * 5,
self._login_block_duration, self._login_block_duration)
# um login bem-sucedido zera o contador DESTE login
def login_success(self, ip: str, login: str):
with self._lock:
self._counters.pop(self._login_key(ip, login), None)
# ---------------------------------------------------------------- registration
def registration_block_minutes(self, ip: str) -> int:
with self._lock:
return self._remaining_minutes(f"registration|{ip}")
# janela de uma hora; atingida a cota, bloqueado até o fim da hora
def registration_success(self, ip: str):
with self._lock:
self._count(f"registration|{ip}", self._max_registrations, ONE_HOUR, ONE_HOUR)
# ---------------------------------------------------------------- common mechanics
# (os métodos privados são sempre chamados sob o lock)
def _remaining_minutes(self, key: str) -> int:
counter = self._counters.get(key)
if counter is None:
return 0
remaining = (counter.blocked_until - datetime.now()).total_seconds()
# arredondado PARA CIMA ao minuto: 30 s de bloqueio restante -> "1 minute"
return max(0, math.ceil(remaining / 60))
# conta uma tentativa; se o limite for atingido dentro da janela, bloqueia
def _count(self, key: str, maximum: int, window: timedelta, block: timedelta):
now = datetime.now()
self._purge(now)
counter = self._counters.get(key)
if counter is None or now - counter.start > window:
counter = Counter(now)
self._counters[key] = counter
counter.number += 1
if counter.number >= maximum:
counter.blocked_until = now + block
counter.number = 0 # após o bloqueio, recomeça-se do zero
counter.start = counter.blocked_until
# esquecemos os contadores que não são mais úteis (nem bloqueados, nem recentes)
def _purge(self, now: datetime):
if len(self._counters) < 1000:
return
for key in [key for key, c in self._counters.items()
if c.blocked_until < now and now - c.start > ONE_HOUR]:
del self._counters[key]
@staticmethod
def _login_key(ip: str, login: str) -> str:
return f"login|{ip}|{login.strip().lower()}"
@staticmethod
def _ip_key(ip: str) -> str:
return f"ip|{ip}"
|
Uma versão mais completa do limitador do Exemplo 27:
- O bloqueio de conexão visa primeiro o par (endereço IP, login): em uma sala de aula, todos os computadores costumam acessar a Internet pelo mesmo endereço IP, e um aluno que digita a senha errada não deve bloquear os colegas. No entanto, um endereço também é bloqueado se acumular cinco vezes mais tentativas malsucedidas, somando todos os logins: é o caso de um robô que tenta milhares de logins diferentes (linhas 57–61);
- a criação de contas é limitada a um certo número de contas por hora por endereço IP (linhas 71–78);
- Os contadores são armazenados em um único dicionário, com chaves prefixadas conforme o uso ([login|...], [ip|...], [registration|...]);
- linhas 92–103: um contador registra as tentativas dentro de uma janela de tempo; uma tentativa que ocorre depois do fim da janela inicia uma nova. Quando o limite é atingido, a chave é bloqueada e o contador volta a zero;
- linhas 106–111: quando o contador ultrapassa 1.000 entradas, as que não estão mais em uso (nem bloqueadas, nem recentes) são descartadas.
Assim como o CAPTCHA, o limitador armazena seus dados na memória do processo: isso é aceitável para uma aplicação servida por um único processo (o servidor de desenvolvimento, [Waitress]), mas não para vários processos ou vários servidores, que não compartilhariam seus contadores (seria então necessário um armazenamento compartilhado, como [Redis]).
11.13.8. auth/registration_pass.py
| # =========================================================================
# auth/registration_pass.py
# -------------------------------------------------------------------------
# O "pass" de criação de conta.
#
# Para abrir a página "Create a patient account", é preciso antes ter
# digitado o captcha da página de autenticação (veja
# controllers/registration.py, POST /register/access). O servidor então emite
# um pass:
# - um identificador aleatório, armazenado em um cookie HttpOnly;
# - válido por 15 minutos (o 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 robô não pode criar contas em série.
#
# Sem um pass válido, GET e POST /register redirecionam para a
# página de autenticação: digitar a URL /register diretamente não permite
# contornar o captcha.
#
# Como os captchas, os passes vivem na memória do processo.
# =========================================================================
import secrets
from datetime import datetime, timedelta
from threading import Lock
from flask import Response
COOKIE = "rdvmedecins_registration"
LIFETIME = timedelta(minutes=15)
MAX_PASSES = 10_000
class RegistrationPass:
def __init__(self):
# id -> data de expiração
self._passes: dict[str, datetime] = {}
self._lock = Lock()
# emite um novo pass; retorna seu identificador
def issue(self) -> str:
id = secrets.token_urlsafe(16)
with self._lock:
self._purge()
self._passes[id] = datetime.now() + LIFETIME
return id
# true se [id] for um pass existente e não expirado
def is_valid(self, id: str | None) -> bool:
with self._lock:
expires = self._passes.get(id) if id else None
return expires is not None and expires > datetime.now()
# o pass foi usado: ele é esquecido
def consume(self, id: str | None):
with self._lock:
self._passes.pop(id, None)
# (chamado sob o lock)
def _purge(self):
now = datetime.now()
for id in [id for id, expires in self._passes.items() if expires <= now]:
del self._passes[id]
if len(self._passes) >= MAX_PASSES:
self._passes.clear()
# o cookie é enviado pelo navegador somente para os endereços /register...
def set_cookie(response: Response, id: str, secure: bool):
response.set_cookie(COOKIE, id, max_age=LIFETIME, path="/register", httponly=True,
samesite="Lax", secure=secure)
# ... e é apagado definindo-o novamente vazio, com tempo de vida zero
def clear_cookie(response: Response):
response.delete_cookie(COOKIE, path="/register")
|
A criação de uma conta de paciente é uma página pública: um robô poderia criar contas em massa. Ela é, portanto, protegida pelo CAPTCHA da página de login: o botão “Criar uma conta de paciente” envia esse CAPTCHA ao servidor, que, se estiver correto, emite um token:
- linhas 42–47: um identificador aleatório, válido por 15 minutos, armazenado na memória como os CAPTCHAs;
- linhas 50–53: a página de cadastro verifica o passe a cada requisição — GET é tratado da mesma forma que POST;
- linhas 56–58: a criação de uma conta consome o passe: um CAPTCHA resolvido equivale, no máximo, a uma conta;
- linhas 70–72: o passe é armazenado em um cookie. Seu atributo [path="/register"], limita as requisições às quais o navegador o anexa: apenas endereços que começam por [/register];
- linhas 76–77: para excluir um cookie, é preciso especificar o mesmo caminho usado ao defini-lo.
11.13.9. controllers/auth.py
O controller de conexão, que usa todos esses serviços.
| # =========================================================================
# controllers/auth.py
# -------------------------------------------------------------------------
# As rotas PÚBLICAS do login:
# GET / redireciona para a página inicial do papel (ou para /login)
# GET /login exibe o formulário de login (com seu captcha)
# POST /login verifica limite de tentativas, captcha, login / senha
# POST /logout o logout
#
# Proteção contra robôs, nesta ordem:
# 1. falhas recentes demais para este login a partir deste endereço IP?
# -> recusa imediata, sem sequer olhar a senha;
# 2. resposta errada ao captcha? -> recusa (contada como uma falha);
# 3. só então, verificação da senha.
# A senha de uma tentativa recusada nas etapas 1 ou 2 NUNCA é
# verificada: um robô, portanto, não aprende nada insistindo.
# =========================================================================
from flask import Blueprint, g, redirect, render_template, request, url_for
from rdvmedecins.auth.auth_service import AuthService
from rdvmedecins.auth.security import public
from rdvmedecins.entities import Role
from rdvmedecins.models.view_models import LoginModel, Message
from rdvmedecins.web.services import auth_service, captchas, limiter
auth = Blueprint("auth", __name__)
# a página inicial de cada papel, logo após o login
def home_page(role: Role) -> str:
return url_for("area.patient_area") if role == Role.USER else url_for("schedule.show")
# o endereço IP do visitante. Atrás de um proxy reverso (nginx...), seria
# o do proxy: a aplicação teria então que ser envolvida no
# middleware ProxyFix do Werkzeug, que lê o cabeçalho X-Forwarded-For.
def ip_address() -> str:
return request.remote_addr or ""
# -----------------------------------------------------------------------
# GET /
# A rota é pública: o usuário foi estabelecido, se houver, por
# auth/security.py (g.user), mas nada é exigido.
# -----------------------------------------------------------------------
@auth.get("/")
@public
def home():
return redirect(home_page(g.user.role) if g.user else url_for("auth.show_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 controllers/registration.py)
# -----------------------------------------------------------------------
@auth.get("/login")
@public
def show_login():
# já conectado (token ainda válido): direto para a página inicial
if g.user:
return redirect(home_page(g.user.role))
return form(request.args.get("login", "")[:30], None)
# -----------------------------------------------------------------------
# POST /login
# request.form.get: um campo ausente resulta em None (e não em um erro 400) -
# é o código que decide o que fazer com isso.
# -----------------------------------------------------------------------
@auth.post("/login")
@public
def log_in():
login = (request.form.get("login") or "").strip()
password = request.form.get("password") or ""
ip = ip_address()
# 1. falhas recentes demais?
minutes = limiter().login_block_minutes(ip, login)
if minutes > 0:
return form(login, Message("ERRORS.TOO_MANY_ATTEMPTS", {"minutes": str(minutes)}))
# 2. o captcha
if not captchas().verify(request.form.get("captchaId"), request.form.get("captcha")):
limiter().login_failure(ip, login)
return form(login, Message("ERRORS.WRONG_CAPTCHA"))
# 3. a senha
user = auth_service().validate_user(login, password) if login and password else None
if user is None:
limiter().login_failure(ip, login)
return form(login, Message("LOGIN.ERROR"))
limiter().login_success(ip, login)
response = redirect(home_page(user.role))
auth_service().set_token(response, user)
return response
# -----------------------------------------------------------------------
# POST /logout: apaga o cookie do token e depois vai para a página
# de login. Somente POST: um simples link (GET), colocado em outro site,
# não pode desconectar o usuário sem que ele saiba.
# -----------------------------------------------------------------------
@auth.post("/logout")
@public
def log_out():
response = redirect(url_for("auth.show_login"))
AuthService.clear_token(response)
return response
# o formulário, sempre com um NOVO captcha (cada imagem é usada uma
# única vez); o login digitado é exibido novamente, nunca a senha
def form(login: str, error: Message | None):
model = LoginModel("LOGIN.TITLE", error, login, captchas().generate())
return render_template("login.html", model=model)
|
- linha 24: os serviços compartilhados são obtidos por meio de pequenas funções do módulo [web/services.py] (tratado adiante), que os recuperam de [app.extensions];
- linhas 30–31: cada papel tem sua própria página inicial: um portal do paciente para os pacientes e a agenda para os demais;
- linhas 37–38: o endereço IP do visitante. Atrás de um proxy reverso ([nginx], [Apache]), seria o endereço do proxy, o mesmo para todos os visitantes: a aplicação precisaria então ser envolvida pelo middleware [ProxyFix] do [Werkzeug] (veja o capítulo sobre o ciclo de vida), que lê o endereço original do cabeçalho [X-Forwarded-For] adicionado pelo proxy;
- linhas 46–49: a raiz pública do site: redireciona para a página inicial do usuário ou para a página de login;
- linhas 56–62: a página de login. Um usuário que já está conectado (cujo token ainda é válido) é enviado diretamente à sua página inicial. O parâmetro opcional [login] preenche previamente o campo (depois da criação de uma conta); [[:30]] limita seu tamanho ao de um nome de usuário;
- Linhas 70–96: o processo de login, em três etapas, nesta ordem: bloqueio eventual, o CAPTCHA e, só então, a senha. Uma tentativa rejeitada nas duas primeiras etapas nunca verifica a senha: um robô nada aprende ao insistir. [request.form.get(...) or ""]: um campo vazio retorna uma string vazia. A mensagem de erro é um objeto [Message]: uma chave de tradução e seus parâmetros (tratado adiante);
- linhas 104–109: logout, em POST (exemplo 25). Ele é público: um usuário cuja sessão expirou deve poder clicar em “Sair” sem ser antes redirecionado;
- linhas 114–116: a página de login, novamente com um novo CAPTCHA. Seu modelo é um objeto [LoginModel] (veja [models/view_models.py]).
Observe que o formulário de login não usa [WTForms]: seus três campos não têm regras de validação (um nome de usuário vazio resulta simplesmente em um login malsucedido), e o formulário é protegido contra ataques CSRF por [CSRFProtect], como todos os formulários da aplicação.
11.14. A camada web: serviços compartilhados
A pasta [web] contém o que os controllers têm em comum. Cada módulo dela responde a uma pergunta que todos os controllers se fazem: como obter um serviço, traduzir um texto, exibir uma mensagem após um redirecionamento, reexibir um formulário rejeitado ou converter um erro em uma página.
11.14.1. web/services.py
| # =========================================================================
# web/services.py
# -------------------------------------------------------------------------
# Os objetos compartilhados da aplicação (veja o exemplo 06): são criados UMA VEZ,
# pela application factory (rdvmedecins/__init__.py), e
# armazenados no dicionário app.extensions. Essas pequenas funções os encontram
# lá, para a aplicação que processa a requisição atual
# (current_app); elas também dão seu TIPO às ferramentas de análise.
# =========================================================================
from flask import current_app
from rdvmedecins.auth.auth_service import AuthService
from rdvmedecins.auth.captcha import CaptchaService
from rdvmedecins.auth.limiter import AttemptLimiter
from rdvmedecins.auth.registration_pass import RegistrationPass
from rdvmedecins.web.application_model import ApplicationModel
def application() -> ApplicationModel:
return current_app.extensions["rdvmedecins.application"]
def auth_service() -> AuthService:
return current_app.extensions["rdvmedecins.auth"]
def captchas() -> CaptchaService:
return current_app.extensions["rdvmedecins.captchas"]
def limiter() -> AttemptLimiter:
return current_app.extensions["rdvmedecins.limiter"]
def passes() -> RegistrationPass:
return current_app.extensions["rdvmedecins.passes"]
|
Os objetos compartilhados, criados pela fábrica e armazenados em [app.extensions], são recuperados por estas pequenas funções (exemplo 06). Elas dispensam repetir a chave do dicionário em cada controller e informam seu tipo às ferramentas de análise: em um controller, o editor sabe que [application()] é um [ApplicationModel] e oferece seus métodos.
11.14.2. web/translator.py
| # =========================================================================
# web/translator.py
# -------------------------------------------------------------------------
# Tradução francês / inglês da interface (veja o exemplo 22).
#
# Os dicionários são os MESMOS arquivos das versões NestJS,
# ASP.NET Core e Spring MVC da aplicação (i18n/fr.json, i18n/en.json),
# lidos uma única vez na inicialização.
#
# Nas views, a função t (veja web/common_model.py):
# {{ t("LOGIN.TITLE") }} sem parâmetro;
# {{ t("AREA.HELLO", name=model.patient) }} parâmetros nomeados;
# {{ t(message.key, message.params) }} um dicionário de parâmetros.
#
# O IDIOMA ATUAL: g.language, definido a cada requisição a partir de um cookie
# (veja rdvmedecins/__init__.py, função set_language).
# =========================================================================
import json
import re
from pathlib import Path
from flask import g
LANGUAGES = ("fr", "en")
DEFAULT_LANGUAGE = "en"
# o cookie que memoriza o idioma escolhido (veja controllers/language.py)
LANGUAGE_COOKIE = "rdvmedecins_language"
# {name}: um parâmetro em um texto
PARAMETER = re.compile(r"\{(\w+)\}")
# o idioma suportado que corresponde a [code]: "fr" -> "fr"; "de" ou None -> "en"
def language(code: str | None) -> str:
return code if code in LANGUAGES else DEFAULT_LANGUAGE
class Translator:
def __init__(self, folder: Path):
# idioma -> (chave completa "LOGIN.TITLE" -> texto)
self._dictionaries: dict[str, dict[str, str]] = {}
for code in LANGUAGES:
with open(folder / f"{code}.json", encoding="utf-8") as file:
self._dictionaries[code] = self._flatten(json.load(file))
# -----------------------------------------------------------------------
# translate("DOCTORS.ADDED", {"name": "Marie PELISSIER"})
# -> procura "DOCTORS.ADDED" no dicionário do idioma e
# substitui {name} pelo seu valor. Uma chave ausente do idioma solicitado
# é procurada em inglês; ausente em todos, a própria chave
# é exibida (uma omissão é assim percebida imediatamente).
# Os parâmetros: um dicionário e/ou parâmetros nomeados.
# -----------------------------------------------------------------------
def translate(self, key: str | None, params: dict | None = None, **others) -> str:
if not key:
return ""
text = self._dictionaries[language(g.get("language"))].get(key)
if text is None:
text = self._dictionaries[DEFAULT_LANGUAGE].get(key, key)
values = {**(params or {}), **others}
if not values:
return text
return PARAMETER.sub(lambda m: str(values.get(m.group(1), m.group(0))), text)
# { "LOGIN": { "TITLE": "Login" } } -> { "LOGIN.TITLE": "Login" }
@classmethod
def _flatten(cls, node: dict, prefix: str = "") -> dict[str, str]:
result = {}
for key, value in node.items():
full_key = f"{prefix}.{key}" if prefix else key
if isinstance(value, dict):
result.update(cls._flatten(value, full_key))
else:
result[full_key] = value
return result
|
O tradutor do Exemplo 22, com três acréscimos:
- Linhas 56–65: os parâmetros de um texto podem ser fornecidos por um dicionário (o segundo parâmetro, [params]), por parâmetros nomeados ([**others]), ou por ambos. As mensagens da aplicação (a classe [Message], tratada adiante) carregam seus parâmetros em um dicionário; as views, por sua vez, preferem parâmetros nomeados. [{**a, **b}] cria um dicionário que combina os de [a] e [b];
- linha 61: uma chave ausente no idioma solicitado é procurada em inglês antes de ser exibida como está;
- linha 59: [g.get("language")] retorna [None] se [g] não tiver o atributo [language], em vez de lançar uma exceção: o tradutor funciona mesmo que ocorra um erro antes da função [before_request] que define o idioma.
O nome do cookie de idioma é prefixado com o nome da aplicação ([rdvmedecins_language]), assim como o token e o passe: os cookies são associados a um nome de domínio ([localhost]), e não a uma porta. Os exemplos, que também são servidos por [localhost], poderiam, de outro modo, ler os cookies da aplicação.
11.14.3. web/common_model.py
| # =========================================================================
# web/common_model.py
# -------------------------------------------------------------------------
# O que TODAS as views precisam, seja qual for a página (veja o exemplo
# 15): um "context processor", executado antes de cada view ser
# construída, adiciona suas variáveis ao modelo de todas as views:
# - user : o usuário conectado (ou None), para a barra de navegação;
# - language : "fr" ou "en";
# - path : a URL solicitada (menu ativo da barra de navegação,
# link "Another image" do captcha);
# - t : a função de tradução (veja web/translator.py).
# As mensagens flash são lidas pelo layout (get_flashed_messages).
# =========================================================================
from flask import g, request
from rdvmedecins.web.translator import Translator
def register(app, translator: Translator):
@app.context_processor
def common_model():
return {
"user": g.get("user"),
"language": g.get("language", "en"),
"path": request.path,
"t": translator.translate,
}
|
O context processor do Exemplo 15: quatro variáveis disponíveis em todas as views, sem que as ações precisem fornecê-las: o usuário conectado (para a barra de navegação), o idioma (para o atributo [lang] da página e os botões FR / EN), o caminho da URL solicitada (para o menu ativo e o link “Outra imagem” do CAPTCHA) e a função de tradução [t]. [g.get("user")] retorna [None] se o atributo não existir (por exemplo, uma página de erro fabricada antes da autenticação).
11.14.4. web/flash.py
| # =========================================================================
# web/flash.py
# -------------------------------------------------------------------------
# As mensagens "flash": uma mensagem a exibir UMA ÚNICA VEZ, na PRÓXIMA
# página (veja o exemplo 20). É 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; a mensagem, porém, deve sobreviver ao redirecionamento.
#
# O Flask as armazena na SESSÃO, isto é, em um cookie ASSINADO pela
# chave secreta (SECRET_KEY): o servidor permanece SEM ESTADO, não guarda nada na
# memória entre duas requisições. O navegador pode ler esse cookie (ele não é
# criptografado), mas não modificá-lo sem que a assinatura o denuncie.
#
# Uma mensagem não contém um texto, mas uma CHAVE de tradução e seus
# parâmetros: ela é traduzida no momento da exibição, no idioma da
# página (veja templates/layout.html). Sua categoria: "success" (exibida no
# topo da página) ou "danger" (um erro, exibido na parte inferior).
# =========================================================================
from flask import flash
def flash_success(key: str, **params):
flash({"key": key, "params": params}, "success")
def flash_error(key: str, **params):
flash({"key": key, "params": params}, "danger")
|
As mensagens flash do Exemplo 20. Uma mensagem não é um texto, mas um dicionário: a chave de tradução e seus parâmetros. Ela será traduzida no momento da exibição, pelo template, para o idioma da página. [Flask] armazena as mensagens na sessão, que é um cookie: para isso, converte-as em JSON, que aceita um dicionário de strings. A categoria da mensagem ([success] ou [danger], os nomes de cores do [Bootstrap]) determina sua posição: no alto da página para um sucesso, na parte inferior para um erro.
11.14.5. web/errors.py
| # =========================================================================
# web/errors.py
# -------------------------------------------------------------------------
# Como os erros se tornam páginas HTML. Três handlers dividem
# o trabalho (veja o exemplo 24):
#
# 1. uma InvalidSession (conta excluída desde o login) -> volta para
# a página de login, como para uma sessão expirada;
# 2. um erro HTTP: abort(400), abort(403) (papel insuficiente), página
# desconhecida (404), método não suportado (405), token anti-CSRF
# ausente ou errado (400)... -> a página de erro, com o código original;
# 3. qualquer outra exceção (uma anomalia real) -> escrita no log
# do servidor, com seu stack trace; o usuário vê a
# página de erro 500 - nunca o stack trace.
# =========================================================================
from flask import current_app, redirect, render_template, url_for
from werkzeug.exceptions import HTTPException
from rdvmedecins.auth.auth_service import AuthService
from rdvmedecins.auth.security import InvalidSession
from rdvmedecins.models.view_models import ErrorModel
from rdvmedecins.web.flash import flash_error
MESSAGES = {
400: "ERRORS.BAD_REQUEST",
403: "ERRORS.FORBIDDEN",
404: "ERRORS.NOT_FOUND",
}
def error_page(code: int):
model = ErrorModel("ERROR_PAGE.TITLE", None, code, MESSAGES.get(code, "ERRORS.SERVER_ERROR"))
# a página mantém o código de erro (404 continua 404...)
return render_template("error.html", model=model), code
def register(app):
@app.errorhandler(InvalidSession)
def invalid_session(e):
response = redirect(url_for("auth.show_login"))
AuthService.clear_token(response)
flash_error("ERRORS.SESSION_EXPIRED")
return response
@app.errorhandler(HTTPException)
def http_error(e: HTTPException):
return error_page(e.code or 500)
# Exception: a classe pai de todas as exceções; este handler
# só recebe aquelas que nenhum handler mais específico tratou
@app.errorhandler(Exception)
def anomaly(e: Exception):
current_app.logger.exception("unexpected error")
return error_page(500)
|
Os tratadores de erros do Exemplo 24:
- linhas 31–34: a página de erro, com o código de erro original (uma página 404 continua sendo uma resposta 404) e uma mensagem traduzida escolhida conforme o código;
- linhas 39–44: uma conta excluída desde o login: redirecionamento para a página de login, como em uma sessão expirada;
- linhas 46–48: todos os erros HTTP: [abort(403)], uma página desconhecida (404), um método proibido (405), um token anti-CSRF ausente ou inválido (400, tratado por [CSRFProtect])...;
- linhas 52–55: qualquer outra exceção, isto é, uma anomalia real (um erro de programação, um banco de dados que se tornou inacessível). [current_app.logger] é o log da aplicação (um objeto do módulo padrão [logging]); seu método [exception] escreve nele a mensagem, seguida da pilha de chamadas da exceção atual. O usuário, porém, vê apenas a página de erro 500: nunca a pilha de chamadas, que revelaria detalhes internos da aplicação. [Flask] sempre seleciona o tratador mais específico: um erro HTTP é tratado pelo segundo tratador, e não por este.
11.14.6. web/application_model.py
| # =========================================================================
# web/application_model.py
# -------------------------------------------------------------------------
# O cache / fachada da camada de negócio (o equivalente da
# classe [ApplicationModel] das versões anteriores da aplicação): as
# listas de médicos e de clientes são lidas uma vez na inicialização e depois
# servidas da memória.
#
# Essas listas podem MUDAR (o ADMIN adiciona, edita, exclui
# médicos e clientes): cada escrita passa, portanto, por esta fachada,
# que recarrega a lista em questão logo depois. Este é todo o objetivo de um
# ÚNICO ponto de entrada para a camada de negócio: a regra "escrita =>
# recarga do cache" está escrita somente aqui.
#
# Um único objeto para toda a aplicação, usado por requisições
# processadas EM PARALELO, em várias threads. Uma lista nunca é, portanto, modificada
# no lugar: ela é SUBSTITUÍDA inteiramente por uma nova. Em Python,
# a atribuição de um atributo é atômica: uma thread que lê a lista vê
# a antiga ou a nova, nunca uma lista pela metade.
# =========================================================================
from datetime import date
from rdvmedecins.domain.schedule import DoctorDaySchedule
from rdvmedecins.entities import Client, Slot, Doctor, Appointment
from rdvmedecins.business.person_data import PersonData
from rdvmedecins.business.business import Business
# mesmo contrato da camada de negócio (Business)
class ApplicationModel:
def __init__(self, business: Business):
self._business = business
# carga inicial das duas listas, na inicialização da aplicação.
# Um erro de leitura (banco de dados inacessível...) não é capturado:
# ele interrompe o servidor, em vez de deixá-lo iniciar "vazio"
self._doctors: list[Doctor] = []
self._clients: list[Client] = []
self._reload_doctors()
self._reload_clients()
def _reload_doctors(self):
self._doctors = list(self._business.get_all_doctors())
def _reload_clients(self):
self._clients = list(self._business.get_all_clients())
# ------------------------------------------------ leituras do cache
def get_all_doctors(self) -> list[Doctor]:
return self._doctors
def get_all_clients(self) -> list[Client]:
return self._clients
# o médico cuja conta de usuário é [user_id] - usado para pré-selecionar,
# para um médico conectado, sua própria agenda
def get_doctor_by_user_id(self, user_id: int) -> Doctor | None:
return next((d for d in self._doctors if d.user_id == user_id), None)
# ------------------------------------------------ delegações simples
def get_all_slots(self, doctor_id: int) -> list[Slot]:
return self._business.get_all_slots(doctor_id)
def get_doctor_day_appointments(self, doctor_id: int, day: date) -> list[Appointment]:
return self._business.get_doctor_day_appointments(doctor_id, day)
def get_client_by_id(self, id: int) -> Client | None:
return self._business.get_client_by_id(id)
def get_doctor_by_id(self, id: int) -> Doctor | None:
return self._business.get_doctor_by_id(id)
def get_appointment_by_id(self, id: int) -> Appointment | None:
return self._business.get_appointment_by_id(id)
def get_slot_by_id(self, id: int) -> Slot | None:
return self._business.get_slot_by_id(id)
def get_doctor_day_schedule(self, doctor_id: int, day: date) -> DoctorDaySchedule | None:
return self._business.get_doctor_day_schedule(doctor_id, day)
# sem cache aqui: o que importa são os dados mais recentes (um paciente
# que acabou de editar ou excluir sua conta)
def get_client_by_user_id(self, user_id: int) -> Client | None:
return self._business.get_client_by_user_id(user_id)
def get_client_upcoming_appointments(self, client_id: int) -> list[Appointment]:
return self._business.get_client_upcoming_appointments(client_id)
def add_appointment(self, day: date, slot: Slot, client: Client) -> Appointment:
return self._business.add_appointment(day, slot, client)
def delete_appointment(self, appointment: Appointment) -> None:
self._business.delete_appointment(appointment)
# ------------------------------------------------ escritas => recarga
def add_doctor(self, data: PersonData) -> Doctor:
doctor = self._business.add_doctor(data)
self._reload_doctors()
return doctor
def edit_doctor(self, id: int, data: PersonData) -> Doctor:
doctor = self._business.edit_doctor(id, data)
self._reload_doctors()
return doctor
def delete_doctor(self, id: int) -> None:
self._business.delete_doctor(id)
self._reload_doctors()
def add_client(self, data: PersonData) -> Client:
client = self._business.add_client(data)
self._reload_clients()
return client
def edit_client(self, id: int, data: PersonData) -> Client:
client = self._business.edit_client(id, data)
self._reload_clients()
return client
def delete_client(self, id: int) -> None:
self._business.delete_client(id)
self._reload_clients()
|
O cache da camada web e sua interface com a camada de negócio:
- linhas 32–40: as listas de médicos e de pacientes são lidas uma única vez, na inicialização. Elas são usadas toda vez que a agenda é exibida (a lista suspensa de médicos, a lista de pacientes): mantê-las na memória evita duas requisições SQL por página. Um erro de leitura não é capturado: ele faz a aplicação falhar na inicialização (veja “Problemas comuns”);
- linhas 50–59: dados recuperados do cache. [get_doctor_by_user_id] identifica o médico conectado para pré-selecionar sua própria agenda;
- linhas 63–96: as demais operações de leitura, e as consultas, são simplesmente repassadas à camada de negócio. [get_client_by_user_id] não usa o cache: um paciente que acabou de modificar ou excluir sua conta deve ver os dados mais recentes;
- linhas 100–126: cada atualização de médicos ou de clientes renova a lista correspondente. Essa é a vantagem de um único ponto de entrada para a camada de negócio: a regra “atualizar e depois renovar o cache” é implementada somente aqui.
Este objeto único é usado por requisições tratadas em paralelo em várias threads: por isso, uma lista nunca é modificada no lugar (por [append] ou [remove]); em vez disso, ela é substituída por inteiro por uma nova. Em [Python], a atribuição de um atributo é atômica: uma thread que lê a lista enxerga a versão antiga ou a nova, nunca uma lista parcialmente construída. Portanto, nenhum bloqueio é necessário.
[ApplicationModel] respeita o contrato [Business] (tem os mesmos métodos que [BusinessService]): para os controllers, ele é a camada de negócio. Poderíamos remover o cache sem tocar nos controllers colocando diretamente [BusinessService] em [app.extensions].
11.14.7. web/validation.py
| # =========================================================================
# web/validation.py
# -------------------------------------------------------------------------
# O que é necessário para EXIBIR NOVAMENTE um formulário recusado: os erros de entrada
# campo a campo, e os campos a contornar em vermelho.
# =========================================================================
from flask_wtf import FlaskForm
from rdvmedecins.models.view_models import FormState, Message
# -----------------------------------------------------------------------
# o formulário validado (veja forms/forms.py) -> o dicionário
# campo -> chave da mensagem, mantendo apenas a primeira mensagem de cada
# campo: { "last_name": "ERRORS.LASTNAME_REQUIRED", ... }
#
# Nossas mensagens são chaves de tradução ("ERRORS...."). Uma mensagem que
# o WTForms tenha escrito ele mesmo (em inglês) é substituída pela chave
# ERRORS.INVALID_FORM.
# -----------------------------------------------------------------------
def errors_of(form: FlaskForm) -> dict[str, str]:
errors = {}
for field, messages in form.errors.items():
message = str(messages[0])
errors[field] = message if message.startswith("ERRORS.") else "ERRORS.INVALID_FORM"
return errors
# -----------------------------------------------------------------------
# os campos do formulário envolvidos em cada erro de negócio de "entrada"
# (uma duplicata): eles são contornados em vermelho, ficando a mensagem na parte inferior da página
# -----------------------------------------------------------------------
BUSINESS_ERROR_FIELDS = {
"ERRORS.LOGIN_TAKEN": ["login"],
"ERRORS.DOCTOR_ALREADY_EXISTS": ["first_name", "last_name"],
"ERRORS.PATIENT_ALREADY_EXISTS": ["first_name", "last_name"],
}
# o estado de um formulário a exibir (novamente): uma mensagem sob cada campo
# recusado pela validação (errors), e os campos a contornar em vermelho,
# esses mais eventuais outros (other_fields)
def state(errors: dict[str, str], other_fields: list[str] | None = None) -> FormState:
return FormState(dict(errors), set(errors) | set(other_fields or []))
# A mensagem de erro DA página, exibida na parte inferior da página: [error] se
# houver, caso contrário "The form contains errors." se houver
# erros de campo, caso contrário nada
def page_message(errors: dict[str, str], error: Message | None) -> Message | None:
if error is not None:
return error
return Message("ERRORS.INVALID_FORM") if errors else None
|
O que é necessário para reexibir um formulário rejeitado:
- linhas 21–26: os erros de um formulário [WTForms] (exemplo 19), na forma de um dicionário “campo → chave de mensagem”, mantendo apenas a primeira mensagem de cada campo. As mensagens de nossos validadores são chaves de tradução ([ERRORS.LASTNAME_REQUIRED], veja [forms/forms.py]); uma mensagem que [WTForms] tivesse gerado por conta própria, em inglês, é substituída por uma chave genérica;
- linhas 33–36: alguns erros de lógica de negócio dizem respeito a campos específicos — como um nome de usuário já utilizado ou um nome idêntico ao de outra pessoa. Suas mensagens de erro aparecem na parte inferior da página, mas os campos afetados são destacados em vermelho para que o usuário veja de imediato o que corrigir (veja a captura de tela do nome idêntico, acima);
- linhas 43–44: o estado de um formulário a ser reexibido: as mensagens abaixo dos campos e todos os campos a destacar em vermelho. [set(errors)] é o conjunto das chaves do dicionário; o operador [|] realiza a união de dois conjuntos;
- linhas 50–53: a mensagem geral do rodapé.
11.14.8. web/utils.py
| # =========================================================================
# web/utils.py
# -------------------------------------------------------------------------
# Pequenas funções utilitárias da camada web:
# - rótulos: "Mme Alice DURAND";
# - datas: "yyyy-mm-dd", horas "8:05", dias "Wednesday 23 September 2026";
# - entrada: leitura de um inteiro positivo enviado pelo navegador;
# - usuário: o usuário conectado e seu paciente (entidade Client).
# =========================================================================
import re
from datetime import date, datetime
from babel.dates import format_date
from flask import g
from rdvmedecins.auth.security import InvalidSession
from rdvmedecins.auth.connected_user import ConnectedUser
from rdvmedecins.entities import Client, Slot, Person
# ----------------------------------------------------------------- labels
# "Mme Alice DURAND"
def label(p: Person) -> str:
return f"{p.title} {p.first_name} {p.last_name}"
# ----------------------------------------------------------------- dates
# o formato das datas nas URLs e no campo <input type="date">
ISO_FORMAT = re.compile(r"\d{4}-\d{2}-\d{2}")
# a data, se [text] for uma data existente no formato yyyy-mm-dd; None caso contrário.
# strptime verifica que a data existe: "2026-02-30" é recusada
def valid_date(text: str | None) -> date | None:
if text is None or not ISO_FORMAT.fullmatch(text):
return None
try:
return datetime.strptime(text, "%Y-%m-%d").date()
except ValueError:
return None
def iso(day: date) -> str:
return day.isoformat()
# "8:05" em vez de "8:5"
def format_time(h: int, m: int) -> str:
return f"{h}:{m:02d}"
def time(s: Slot) -> str:
return f"{format_time(s.start_hour, s.start_minute)} - {format_time(s.end_hour, s.end_minute)}"
# "mercredi 23 septembre 2026" / "Wednesday 23 September 2026", conforme o
# idioma da requisição (g.language). O formato Babel: EEEE o dia da
# semana por extenso, d o dia, MMMM o mês por extenso, y o ano
def format_day(day: date) -> str:
return format_date(day, "EEEE d MMMM y", locale=g.language)
# ----------------------------------------------------------------- input
# "3" -> 3 ; "", "abc", "-2", "+2", None -> None
def positive_integer(value: str | None) -> int | None:
if value is None or not re.fullmatch(r"\d{1,9}", value):
return None
n = int(value)
return n if n > 0 else None
# ----------------------------------------------------------------- user
# o usuário conectado (veja auth/security.py). As ações protegidas só
# são chamadas se existirem; por precaução, sua ausência é tratada
# como uma sessão expirada.
def user() -> ConnectedUser:
if g.user is None:
raise InvalidSession()
return g.user
# -----------------------------------------------------------------------
# O paciente (entidade Client) que corresponde ao usuário conectado.
#
# O token JWT contém apenas o id da CONTA (users.id). Para o papel USER,
# o cliente correspondente é encontrado graças à coluna clients.user.
#
# Se não houver nenhum, a conta foi excluída desde o
# login enquanto seu token ainda é válido: isso é tratado como uma
# sessão expirada (veja InvalidSession).
# -----------------------------------------------------------------------
def connected_patient(application) -> Client:
patient = application.get_client_by_user_id(user().user_id)
if patient is None:
raise InvalidSession()
return patient
|
Funções utilitárias usadas por vários controllers:
- linha 24: o tratamento de uma pessoa, “Mme Alice DURAND”;
- linhas 31–42: análise de uma data no formato [yyyy-mm-dd], o mesmo usado nas entradas de URL da agenda ([day=2026-09-26]) e no campo [<input type="date">]. A expressão regular verifica o formato ([fullmatch]: a string inteira deve corresponder), enquanto [strptime] verifica a existência da data. Uma data inválida resulta em [None]: é a ação que decide o desfecho;
- linhas 50–51: o formato [02d] gera um inteiro de dois dígitos, preenchido com zeros: [8:05];
- linhas 61–62: uma data por extenso, no idioma da requisição, com [Babel] (exemplo 16). O formato é especificado explicitamente aqui: [EEEE], o dia da semana por extenso; [d], o dia; [MMMM], o mês por extenso; [y], o ano;
- linhas 69–73: leitura de um identificador enviado pelo navegador (um parâmetro de URL, um campo oculto). [\d{1,9}]: de um a nove dígitos, o que exclui letras, espaços e números grandes demais para uma coluna [INT]. Tudo o que vem do navegador pode ter sido modificado: deve ser verificado antes de ser usado;
- linhas 82–85: o usuário conectado; sua ausência (que não deveria ocorrer em uma ação protegida) é tratada como uma sessão expirada;
- linhas 98–102: o paciente (a entidade [Client]) correspondente ao usuário conectado. O token contém apenas o ID da conta: o paciente é identificado pela coluna [clients.user]. Se ele não existir, significa que a conta foi excluída desde o login do usuário.
| # =========================================================================
# forms/rules.py
# -------------------------------------------------------------------------
# As regras de entrada comuns aos formulários de "pessoa", e os FILTROS
# do WTForms (veja o exemplo 19): funções que transformam o valor
# recebido ANTES da validação.
# =========================================================================
TITLES = ("Mr", "Mme", "Melle")
# login: letras minúsculas, dígitos, ponto, hífen, sublinhado - no máximo 30 caracteres
LOGIN_FORMAT = r"^[a-z0-9._-]{1,30}$"
# comprimento mínimo de uma senha ESCOLHIDA por um paciente
PASSWORD_MIN = 6
# " dupont " -> "dupont" ; " " -> None
def clean(value):
if not isinstance(value, str):
return value
return value.strip() or None
# " Dupont " -> "dupont": um login é sempre em minúsculas
def login(value):
value = clean(value)
return value.lower() if isinstance(value, str) else value
# um campo vazio -> None; para uma senha, os espaços NÃO são removidos
# (eles podem fazer parte dela)
def empty_to_none(value):
return value if value else None
# o campo oculto [version]: um inteiro, ou None se estiver ausente ou vazio.
# Um texto que não é um número: um ValueError, que o WTForms transforma
# em um erro de campo, com esta mensagem (uma chave de tradução)
def version(value):
if value in (None, ""):
return None
try:
return int(value)
except (TypeError, ValueError):
raise ValueError("ERRORS.INVALID_FORM")
|
Regras de entrada comuns a todos os formulários, e os filtros do [WTForms] (exemplo 19):
- linhas 8–14: os tratamentos permitidos, o formato de um nome de usuário (letras minúsculas, números, ponto, hífen, sublinhado, até 30 caracteres) e o tamanho mínimo de uma senha escolhida por um paciente;
- Linhas 18–21: os espaços ao redor de uma entrada são removidos; uma entrada vazia se torna [None]. [a or b] equivale a [b] se [a] for “falso” (neste caso, uma string vazia);
- linhas 25–27: um nome de usuário está sempre em minúsculas;
- linhas 32–33: em uma senha, os espaços não são removidos, pois podem fazer parte dela;
- linhas 39–45: o campo oculto de versão (o bloqueio otimista): um inteiro, ou [None]. Um filtro que lança um [ValueError] provoca um erro de campo, com a mensagem de erro correspondente à da exceção: um navegador que envie qualquer coisa diferente de um número receberia o erro “formulário inválido”.
| # =========================================================================
# forms/forms.py
# -------------------------------------------------------------------------
# Os campos dos formulários de "pessoa" e suas restrições (veja os exemplos
# 19 e 28). Três formulários compartilham os mesmos campos de identidade
# (título, nome, sobrenome):
#
# PersonFields título, nome, sobrenome
# ├─ PersonForm + login / senha OPCIONAIS, version
# │ (o ADMIN adiciona ou edita um médico / cliente)
# ├─ RegistrationForm + login / senha / confirmação OBRIGATÓRIOS
# │ (um paciente cria sua conta)
# └─ MyAccountForm + login, nova senha opcional,
# senha ATUAL obrigatória, version
# (um paciente edita sua conta)
#
# Uma classe WTForms que herda de outra também herda seus campos.
#
# BINDING: o próprio PersonForm() lê os campos de mesmo nome da
# requisição POST atual (request.form) e aplica seus filtros a eles
# (espaços supérfluos removidos, login em minúsculas...).
# VALIDAÇÃO: form.validate() verifica então as restrições de cada
# campo, em ordem; a primeira que falha armazena sua mensagem em
# form.<field>.errors. Essas mensagens são CHAVES de tradução (veja i18n/*.json).
#
# Os formulários são usados aqui apenas para ler e validar a entrada: as views
# escrevem elas mesmas suas tags <input>, a partir dos modelos de view
# (veja models/view_models.py).
# =========================================================================
from flask_wtf import FlaskForm
from wtforms import PasswordField, StringField
from wtforms.validators import AnyOf, DataRequired, InputRequired, Length, Optional, Regexp
from rdvmedecins.forms import rules
# ------------------------------------------------------------------ common base
class PersonFields(FlaskForm):
title = StringField(validators=[AnyOf(rules.TITLES, message="ERRORS.INVALID_TITLE")])
# comprimentos máximos = os das colunas SQL (VARCHAR(20)).
# DataRequired interrompe a validação do campo se ele estiver vazio: a mensagem
# de Length, portanto, nunca é adicionada a esse
first_name = StringField(filters=[rules.clean], validators=[
DataRequired("ERRORS.FIRSTNAME_REQUIRED"),
Length(max=20, message="ERRORS.FIRSTNAME_TOO_LONG")])
last_name = StringField(filters=[rules.clean], validators=[
DataRequired("ERRORS.LASTNAME_REQUIRED"),
Length(max=20, message="ERRORS.LASTNAME_TOO_LONG")])
# ------------------------------------------------------------------ ADMIN
class PersonForm(PersonFields):
# opcional (veja business/person_data.py): Optional interrompe a validação de um
# campo vazio, sem erro
login = StringField(filters=[rules.login], validators=[
Optional(), Regexp(rules.LOGIN_FORMAT, message="ERRORS.INVALID_LOGIN")])
# opcional; no máximo 72 caracteres (acima disso, o bcrypt ignora o resto)
password = PasswordField(filters=[rules.empty_to_none], validators=[
Optional(strip_whitespace=False), Length(max=72, message="ERRORS.PASSWORD_TOO_LONG")])
# campo oculto do formulário de edição (bloqueio otimista)
version = StringField(filters=[rules.version])
# ------------------------------------------------------------------ registration of a patient
class RegistrationForm(PersonFields):
# InputRequired: a entrada não deve estar vazia
login = StringField(filters=[rules.login], validators=[
InputRequired("ERRORS.LOGIN_REQUIRED"),
Regexp(rules.LOGIN_FORMAT, message="ERRORS.INVALID_LOGIN")])
# duas restrições Length, cada uma com sua mensagem
password = PasswordField(filters=[rules.empty_to_none], validators=[
InputRequired("ERRORS.PASSWORD_REQUIRED"),
Length(min=rules.PASSWORD_MIN, message="ERRORS.PASSWORD_TOO_SHORT"),
Length(max=72, message="ERRORS.PASSWORD_TOO_LONG")])
confirmation = PasswordField(filters=[rules.empty_to_none], validators=[
InputRequired("ERRORS.CONFIRMATION_REQUIRED")])
# ------------------------------------------------------------------ "Manage my account"
class MyAccountForm(PersonFields):
login = StringField(filters=[rules.login], validators=[
InputRequired("ERRORS.LOGIN_REQUIRED"),
Regexp(rules.LOGIN_FORMAT, message="ERRORS.INVALID_LOGIN")])
# opcional: vazio = senha inalterada
password = PasswordField(filters=[rules.empty_to_none], validators=[
Optional(strip_whitespace=False),
Length(min=rules.PASSWORD_MIN, message="ERRORS.PASSWORD_TOO_SHORT"),
Length(max=72, message="ERRORS.PASSWORD_TOO_LONG")])
confirmation = PasswordField(filters=[rules.empty_to_none])
# a senha ATUAL, exigida para qualquer edição da conta
current_password = PasswordField(filters=[rules.empty_to_none], validators=[
InputRequired("ERRORS.CURRENT_PASSWORD_REQUIRED")])
version = StringField(filters=[rules.version])
|
- Linhas 38–51: os campos comuns aos três formulários: tratamento, nome e sobrenome. As mensagens dos validadores são chaves de tradução: a view as traduzirá para o idioma da página. O validador [AnyOf] aceita um valor de uma lista. Os tamanhos máximos são os das colunas SQL: uma entrada mais longa seria rejeitada pelo banco de dados;
- linhas 55–67: o formulário do administrador: um login e uma senha opcional (o validador [Optional] interrompe a validação de um campo vazio sem informar erro; [strip_whitespace=False]: uma senha formada por espaços não é considerada vazia) e a versão;
- linhas 71–85: o formulário de cadastro do paciente: nome de usuário, senha e confirmação são obrigatórios. Dois validadores, [Length], cada um com sua própria mensagem: curto demais, longo demais;
- linhas 89–107: “Gerenciar minha conta”: uma nova senha opcional e a senha atual, que é obrigatória para qualquer alteração.
Uma classe [WTForms] que herda de outra classe herda seus campos: os três formulários compartilham os campos de [PersonFields]. A comparação entre a senha e sua confirmação não é feita pelo validador [EqualTo] (Exemplo 19), mas pela ação, que assim escolhe a mensagem e o campo correspondentes.
Observe que esses formulários são usados apenas para ler e validar as entradas do usuário: as views não chamam os campos do [WTForms] para renderizá-los (Exemplo 18); em vez disso, escrevem suas próprias tags [<input>] com base nos templates das views. Essa abordagem mantém as views idênticas nos três formulários e dá à ação controle total sobre o que é exibido (nunca uma senha, por exemplo). É também a abordagem usada nas versões anteriores da aplicação.
11.15.3. models/view_models.py
| # =========================================================================
# models/view_models.py
# -------------------------------------------------------------------------
# Os "view models": o que cada ação passa para sua
# view, sob o nome [model]. São dataclasses: objetos construídos
# de uma só vez pela ação, que a view apenas lê
# ({{ model.schedule.rows }}...).
#
# Regra seguida por todas as páginas: nenhuma lógica nas views. As
# ações preparam dados JÁ formatados ("Mme Marie
# PELISSIER", "8:00 - 8:20", selected = True...) e já filtrados conforme
# o papel do usuário; as views apenas os colocam no HTML.
#
# Cada modelo de página tem dois campos, lidos pelo layout (templates/layout.html):
# page_title, a chave do título da página, e error, A mensagem de erro
# da página, exibida na parte inferior da página (None: sem erro).
# =========================================================================
from dataclasses import dataclass, field
from rdvmedecins.auth.captcha import Captcha
from rdvmedecins.forms import rules
# uma mensagem a traduzir: sua chave e seus parâmetros
@dataclass(frozen=True)
class Message:
key: str
params: dict[str, str] = field(default_factory=dict)
# uma opção de uma lista suspensa (médico, paciente)
@dataclass(frozen=True)
class OptionView:
id: int
label: str
selected: bool
# ------------------------------------------------------------------ login
@dataclass
class LoginModel:
page_title: str
error: Message | None
login: str
captcha: Captcha
# ------------------------------------------------------------------ schedule
@dataclass(frozen=True)
class ScheduleRowView:
slot_id: int
time: str # "8:00 - 8:20"
free: bool
patient: str | None # nome exibido para um horário reservado; None = "Booked"
mine: bool # a consulta do paciente conectado
bookable: bool # exibir o botão "Book"?
book_url: str
appointment_id: int | None # preenchido somente se o botão "Cancel" for exibido
@dataclass(frozen=True)
class ScheduleView:
doctor: str
day: str
rows: list[ScheduleRowView]
@dataclass(frozen=True)
class BookingView:
slot_id: int
time: str
clients: list[OptionView] # ADMIN / DOCTOR: os pacientes para escolher
patient: str | None # USER: o paciente é a própria pessoa
@dataclass
class ScheduleModel:
page_title: str
error: Message | None
doctors: list[OptionView]
doctor_id: int | None
day: str # "yyyy-mm-dd"
schedule: ScheduleView | None
booking: BookingView | None
back_url: str # a agenda exibida, sem diálogo de reserva
# paciente que já tem uma consulta futura: a mensagem que explica
# por que não há botão "Book"
info: str | None
# ------------------------------------------------------------------ "person" forms
# os valores exibidos nos campos do formulário (nunca a senha)
@dataclass(frozen=True)
class PersonValues:
title: str = "Mr"
first_name: str = ""
last_name: str = ""
login: str = ""
version: int | None = None
# o estado de um formulário recusado: a mensagem exibida SOB cada campo
# (campo -> chave da mensagem), e os campos a contornar em vermelho (classe
# is-invalid do Bootstrap): os que têm mensagem, mais eventuais outros
# (nome + sobrenome duplicados, login já usado...)
@dataclass(frozen=True)
class FormState:
errors: dict[str, str] = field(default_factory=dict)
invalid_fields: set[str] = field(default_factory=set)
def error_of(self, field: str) -> str | None:
return self.errors.get(field)
def invalid_class(self, field: str) -> str:
return "is-invalid" if field in self.invalid_fields else ""
# uma opção da lista de títulos
@dataclass(frozen=True)
class TitleOption:
value: str
selected: bool
# o que o fragmento comum person_fields.html usa (título, nome, sobrenome):
# uma classe base, da qual os três modelos de formulário herdam
@dataclass
class FormView:
page_title: str
error: Message | None
values: PersonValues
state: FormState
# uma property: é lida como um atributo (model.titles), mas é calculada
@property
def titles(self) -> list[TitleOption]:
return [TitleOption(t, t == self.values.title) for t in rules.TITLES]
@property
def password_min(self) -> int:
return rules.PASSWORD_MIN
@dataclass
class PersonFormModel(FormView):
creating: bool # True: adicionar; False: editar
action: str # URL do POST
list_url: str
@dataclass
class RegistrationModel(FormView):
pass
@dataclass
class MyAccountModel(FormView):
pass
# ------------------------------------------------------------------ doctor / client lists
# as chaves de tradução específicas de cada tipo de pessoa
@dataclass(frozen=True)
class PersonKeys:
title: str # "Doctors"
add: str # "Add a doctor"
edit: str # "Edit a doctor"
empty: str # "No doctors."
confirm_delete: str # "Delete this doctor and their account?"
added: str # "Doctor {name} has been added (login: {login})."
edited: str
deleted: str
@dataclass(frozen=True)
class PersonView:
title: str
first_name: str
last_name: str
login: str
edit_url: str
delete_url: str
@dataclass
class PersonListModel:
page_title: str
error: Message | None
keys: PersonKeys
add_url: str
persons: list[PersonView]
# ------------------------------------------------------------------ patient's area
@dataclass(frozen=True)
class AppointmentView:
id: int
day: str
time: str
doctor: str
schedule_url: str
@dataclass
class AreaModel:
page_title: str
error: Message | None
patient: str
appointments: list[AppointmentView]
# ------------------------------------------------------------------ error page
@dataclass
class ErrorModel:
page_title: str
error: Message | None
code: int
message: str
|
Modelos de view (*view models*): o que cada ação passa à sua view, sob o nome [model]. A regra seguida por todas as páginas: nenhuma lógica nas views. As ações preparam dados já formatados (“Mme Marie PELISSIER”, “8:00 – 8:20”) e já filtrados conforme o papel do usuário; as views apenas inserem esses dados no HTML.
- linhas 26–28: uma mensagem a traduzir: uma chave e seus parâmetros. [field(default_factory=dict)]: o valor padrão é um dicionário novo e vazio para cada objeto. Não se pode escrever [= {}]: esse dicionário seria criado uma única vez e compartilhado por todos os objetos;
- linhas 33–36: uma opção de uma lista suspensa;
- linhas 41–45: o modelo da página de login. Cada modelo de página tem dois campos lidos pelo template: [page_title], a chave do título da página, e [error], a mensagem de erro exibida na parte inferior da página;
- linhas 50–58: uma linha da agenda, já preenchida para o usuário conectado: [patient] equivale a [None] para um horário ocupado por outro paciente, quando o usuário é um paciente (a view exibirá “Reservado”); [bookable] indica se o botão “Reservar” deve ser exibido; [appointment_id] só é preenchido se o botão “Cancelar” deve ser exibido. Todas essas decisões são tomadas pela ação;
- linhas 69–73: a janela de reserva: a lista de pacientes para um administrador ou médico, o nome do paciente para um paciente;
- linhas 77–88: o modelo da página da agenda;
- linhas 108–116: o estado de um formulário rejeitado, com dois métodos chamados pelas views: a mensagem de um campo e a classe CSS que o destaca em vermelho;
- linhas 129–142: a classe base dos três modelos de formulário, usada pelo fragmento comum [person_fields.html]. Suas duas propriedades calculam a lista de tratamentos (incluindo o tratamento selecionado) e o tamanho mínimo de uma senha;
- Linhas 146–158: os três modelos de formulário herdam de [FormView]. Uma [dataclass] que herda de outra acrescenta seus campos aos de sua classe pai;
- linhas 166–174: chaves de tradução específicas de médicos ou de clientes: a mesma view exibe as duas listas;
- linhas 198–211: a área do paciente;
- linhas 216–220: a página de erro.
11.16. A camada web: controllers
A pasta [controllers] contém um blueprint para cada parte da aplicação (o controller de login, [controllers/auth.py], foi apresentado junto com a autenticação):
Blueprint | Endereços |
[language] | [GET /language/<code>] |
[schedule] | [GET /schedule], [POST /schedule/book], [POST /schedule/cancel] |
[doctors], [clients] | [/doctors/...], [/clients/...]: listar, adicionar, editar, excluir |
[registration] | [POST /register/access], [GET], and [POST /register] |
[area] | [/my-area], [/my-area/cancel], [/my-account], [/my-account/delete] |
Todas as ações seguem o mesmo padrão: ler e validar a requisição, chamar a camada de negócio (por meio de [ApplicationModel]) e construir o modelo da view; ou, para uma ação como POST, registrar uma mensagem flash e redirecionar (fluxo PRG, exemplo 20).
11.16.1. controllers/language.py
| # =========================================================================
# controllers/language.py
# -------------------------------------------------------------------------
# GET /language/fr, GET /language/en: os dois botões FR / EN da
# barra de navegação. Rota pública: é preciso poder mudar o idioma antes de
# fazer login.
#
# A escolha é memorizada em um cookie: a cada requisição seguinte, a
# função set_language (veja rdvmedecins/__init__.py) o lê novamente e define o
# idioma da requisição (g.language). Depois voltamos à página de onde viemos.
# =========================================================================
from datetime import timedelta
from urllib.parse import urlsplit
from flask import Blueprint, abort, current_app, redirect, request
from rdvmedecins.auth.security import public
from rdvmedecins.web.translator import LANGUAGE_COOKIE, LANGUAGES
language = Blueprint("language", __name__)
@language.get("/language/<code>")
@public
def change(code: str):
if code not in LANGUAGES:
abort(404) # -> página de erro 404 (veja web/errors.py)
response = redirect(origin_page())
response.set_cookie(LANGUAGE_COOKIE, code, max_age=timedelta(days=365), path="/",
httponly=True, samesite="Lax", secure=current_app.config["COOKIE_SECURE"])
return response
# -----------------------------------------------------------------------
# a página anterior, segundo o cabeçalho HTTP "Referer" enviado pelo
# navegador. Somente seu caminho (/schedule?...) é mantido: redirecionar para
# um endereço completo fornecido pela requisição permitiria enviar
# o usuário a outro site (a chamada falha de "open redirect").
# -----------------------------------------------------------------------
def origin_page() -> str:
referer = request.headers.get("Referer")
if not referer:
return "/"
url = urlsplit(referer)
path = url.path
# "//site.com/..." seria entendido pelo navegador como um endereço
# em OUTRO site: recusado também
if not url.scheme or not path.startswith("/") or path.startswith("//") \
or path.startswith("/language/"):
return "/"
return f"{path}?{url.query}" if url.query else path
|
A seleção de idioma do Exemplo 22, com duas precauções adicionais em [origin_page] (linhas 40–51): um [Referer] sem esquema ([http], [https]) não é um endereço completo, e um [Referer] que fosse ele próprio um endereço [/language/...] redirecionaria para esta ação, criando um laço. Nos dois casos, o usuário é redirecionado de volta à raiz do site. A duração do cookie é especificada por um [timedelta]: [set_cookie] aceita isso tão bem quanto um número de segundos.
A página principal da aplicação, para todos os papéis.
| # =========================================================================
# controllers/schedule.py
# -------------------------------------------------------------------------
# A página da agenda: escolha de um médico e de um dia, agenda desse
# médico nesse dia, agendamento e cancelamento de consultas.
#
# GET /schedule?doctorId=1&day=2026-09-23 a página
# GET /schedule?doctorId=1&day=2026-09-23&book=7 a mesma página, com
# o diálogo de agendamento
# do horário 7 aberto
# POST /schedule/book cria uma consulta
# POST /schedule/cancel cancela uma consulta
#
# A página inteira é descrita por sua URL: ela pode ser recarregada, salva nos favoritos,
# o botão "Back" do navegador pode ser usado - sem uma única linha
# de JavaScript.
#
# O que cada um vê e pode fazer:
#
# | papel | horário reservado exibido | Book | Cancel |
# |---------------|-----------------------------------|--------------------|---------|
# | ADMIN, DOCTOR | nome do paciente | para um paciente | sim |
# | | | escolhido em uma lista | |
# | USER (paciente)| "Booked", ou SEU nome se for | para si mesmo, se | não (*) |
# | | sua própria consulta | não tiver | |
# | | | consulta futura | |
#
# (*) o paciente cancela sua consulta na 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 de outra forma).
#
# Nenhum agendamento no passado: o botão "Book" só aparece
# para hoje e os dias seguintes (e a camada de negócio o recusaria
# de qualquer forma).
#
# Segurança: todas as URLs /schedule exigem um usuário autenticado
# (veja auth/security.py: tudo o que não é @public). @roles_required
# em uma ação exige adicionalmente um dos papéis listados. Sem token válido:
# volta para /login; papel insuficiente: página 403.
# =========================================================================
from dataclasses import dataclass
from datetime import date
from flask import Blueprint, abort, redirect, render_template, request, url_for
from rdvmedecins.auth.security import roles_required
from rdvmedecins.domain.schedule import DoctorDaySchedule
from rdvmedecins.entities import Client, Person, Role
from rdvmedecins.business import dates
from rdvmedecins.business.exception import BusinessException
from rdvmedecins.models.view_models import (ScheduleModel, ScheduleView, ScheduleRowView, Message,
OptionView, BookingView)
from rdvmedecins.web import utils
from rdvmedecins.web.flash import flash_error, flash_success
from rdvmedecins.web.services import application
schedule = Blueprint("schedule", __name__, url_prefix="/schedule")
# o que o controller sabe sobre o usuário, para decidir o que exibir
@dataclass(frozen=True)
class Rights:
manager: bool # ADMIN ou DOCTOR
patient: Client | None # o cliente conectado (papel USER), caso contrário None
patient_can_book: bool # USER sem consulta futura
# -----------------------------------------------------------------------
# GET /schedule
# Os parâmetros da URL são lidos brutos (request.args.get), para
# distinguir um parâmetro AUSENTE (None) de um parâmetro VAZIO (?doctorId=).
# -----------------------------------------------------------------------
@schedule.get("")
def show():
error = None
user = utils.user()
rights = compute_rights()
# o dia: o da URL se for válido, caso contrário hoje
day = dates.today()
raw_day = request.args.get("day")
if raw_day is not None:
requested_day = utils.valid_date(raw_day)
if requested_day is not None:
day = requested_day
else:
error = "ERRORS.INVALID_DATE"
day_bookable = day >= dates.today()
# o médico: o da URL; na falta dele, para um médico conectado, ele mesmo
raw_doctor_id = request.args.get("doctorId")
doctor_id = utils.positive_integer(raw_doctor_id)
if raw_doctor_id is None and user.role == Role.DOCTOR:
doctor = application().get_doctor_by_user_id(user.user_id)
doctor_id = doctor.id if doctor else None
# a lista suspensa dos médicos
doctors = [option(d, d.id == doctor_id) for d in application().get_all_doctors()]
# a agenda, se um médico estiver escolhido (e a data válida)
view = None
if doctor_id is not None and error is None:
doctor_schedule = application().get_doctor_day_schedule(doctor_id, day)
if doctor_schedule is None:
error = "ERRORS.DOCTOR_NOT_FOUND"
else:
view = schedule_view(doctor_schedule, rights, day_bookable)
# o diálogo de agendamento: somente se o horário solicitado
# puder ser agendado por este usuário
booking = None
slot_id = utils.positive_integer(request.args.get("book"))
if view is not None and slot_id is not None:
row = next((r for r in view.rows if r.slot_id == slot_id and r.bookable),
None)
if row is not None:
booking = BookingView(
row.slot_id,
row.time,
[option(c, False) for c in application().get_all_clients()]
if rights.manager else [],
utils.label(rights.patient) if rights.patient else None)
model = ScheduleModel(
page_title="SCHEDULE.PAGE_TITLE",
error=Message(error) if error else None,
doctors=doctors,
doctor_id=doctor_id,
day=utils.iso(day),
schedule=view,
booking=booking,
back_url=schedule_url(doctor_id, day) if doctor_id is not None else url_for("schedule.show"),
info=patient_info(rights, view))
return render_template("schedule.html", model=model)
# -----------------------------------------------------------------------
# POST /schedule/book campos: doctorId, day, slotId, clientId
#
# Para um paciente (USER), o campo clientId é IGNORADO: ele sempre agenda
# para si mesmo. Confiar em um campo enviado pelo
# navegador permitiria a um paciente esperto agendar em nome de outro.
#
# Padrão "Post / Redirect / Get": seja qual for o resultado, nenhuma página é
# construída aqui - uma mensagem flash é definida e redirecionamos
# para a agenda (veja o exemplo 20).
# -----------------------------------------------------------------------
@schedule.post("/book")
@roles_required(Role.ADMIN, Role.DOCTOR, Role.USER)
def book():
doctor_id, day = read_schedule_request()
slot_id = utils.positive_integer(request.form.get("slotId"))
if doctor_id is None or slot_id is None:
abort(400) # -> página "invalid request" (veja web/errors.py)
user = utils.user()
if user.is_patient:
client = utils.connected_patient(application())
else:
client_id = utils.positive_integer(request.form.get("clientId"))
if client_id is None:
# nenhum paciente escolhido: o diálogo de agendamento é aberto novamente
flash_error("ERRORS.CHOOSE_PATIENT")
return redirect(schedule_url(doctor_id, day, slot_id))
client = application().get_client_by_id(client_id)
slot = application().get_slot_by_id(slot_id)
if client is None:
flash_error("ERRORS.PATIENT_NOT_FOUND")
elif slot is None or slot.doctor_id != doctor_id:
flash_error("ERRORS.SLOT_NOT_FOUND")
else:
try:
# as regras (não no passado, uma única consulta futura por
# paciente, horário livre) são verificadas pela camada de negócio
application().add_appointment(day, slot, client)
flash_success("SCHEDULE.BOOKED")
except BusinessException as e:
# mesma regra, mas uma mensagem na 2ª pessoa quando é o
# próprio paciente que agenda ("You already have..." em vez
# de "This patient..."). As outras exceções (anomalias
# reais) não são capturadas: página 500.
if e.key == "ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT" and user.is_patient:
flash_error("SCHEDULE.ALREADY_BOOKED_INFO")
else:
flash_error(e.key, **e.params)
return redirect(schedule_url(doctor_id, day))
# -----------------------------------------------------------------------
# POST /schedule/cancel campos: appointmentId, doctorId, day
# (um paciente cancela SUA consulta em "My area", não daqui)
# -----------------------------------------------------------------------
@schedule.post("/cancel")
@roles_required(Role.ADMIN, Role.DOCTOR)
def cancel():
doctor_id, day = read_schedule_request()
appointment_id = utils.positive_integer(request.form.get("appointmentId"))
if doctor_id is None or appointment_id is None:
abort(400)
appointment = application().get_appointment_by_id(appointment_id)
if appointment is None:
# já cancelada (por outra pessoa, ou clique duplo)
flash_error("ERRORS.APPOINTMENT_NOT_FOUND")
else:
application().delete_appointment(appointment)
flash_success("SCHEDULE.CANCELLED")
return redirect(schedule_url(doctor_id, day))
# -----------------------------------------------------------------------
# quem está conectado e o que pode fazer nesta página?
# -----------------------------------------------------------------------
def compute_rights() -> Rights:
if not utils.user().is_patient:
return Rights(True, None, False)
patient = utils.connected_patient(application())
upcoming = application().get_client_upcoming_appointments(patient.id)
return Rights(False, patient, not upcoming)
# -----------------------------------------------------------------------
# a agenda do médico, formatada para a view - e filtrada conforme os direitos
# -----------------------------------------------------------------------
def schedule_view(doctor_schedule: DoctorDaySchedule, rights: Rights, day_bookable: bool) -> ScheduleView:
doctor_id = doctor_schedule.doctor.id
day = doctor_schedule.day
rows = []
for dds in doctor_schedule.doctor_day_slots:
slot, appointment = dds.slot, dds.appointment
free = appointment is None
# a consulta do paciente conectado?
mine = appointment is not None and rights.patient is not None and appointment.client_id == rights.patient.id
rows.append(ScheduleRowView(
slot_id=slot.id,
time=utils.time(slot),
free=free,
# O ponto de CONFIDENCIALIDADE: um paciente só recebe o nome
# de SUA consulta; para as outras, None (a view exibe "Booked")
patient=utils.label(appointment.client) if appointment is not None and (rights.manager or mine) else None,
mine=mine,
bookable=free and day_bookable and (rights.manager or rights.patient_can_book),
book_url=schedule_url(doctor_id, day, slot.id),
appointment_id=appointment.id if appointment is not None and rights.manager else None))
return ScheduleView(utils.label(doctor_schedule.doctor), utils.format_day(day), rows)
# ----------------------------------------------------------------- utility functions
# os campos ocultos doctorId / day dos formulários POST; (None, None) se forem inválidos
def read_schedule_request() -> tuple[int | None, date | None]:
doctor_id = utils.positive_integer(request.form.get("doctorId"))
day = utils.valid_date(request.form.get("day"))
return (None, None) if doctor_id is None or day is None else (doctor_id, day)
# /schedule?doctorId=1&day=2026-09-23[&book=7]: url_for adiciona no final da
# URL os parâmetros que não são variáveis do caminho
def schedule_url(doctor_id: int, day: date, book: int | None = None) -> str:
if book is None:
return url_for("schedule.show", doctorId=doctor_id, day=utils.iso(day))
return url_for("schedule.show", doctorId=doctor_id, day=utils.iso(day), book=book)
def option(p: Person, selected: bool) -> OptionView:
return OptionView(p.id, utils.label(p), selected)
# -----------------------------------------------------------------------
# a mensagem informativa de um paciente que já tem uma consulta futura
# (por que não há botão "Book"), ou None. Inútil se SUA
# consulta aparecer na agenda exibida (em azul): é o caso logo
# depois de a terem acabado de agendar, quando a mensagem estaria fora de lugar.
# -----------------------------------------------------------------------
def patient_info(rights: Rights, view: ScheduleView | None) -> str | None:
if rights.patient is None or rights.patient_can_book:
return None
appointment_shown = view is not None and any(row.mine for row in view.rows)
return None if appointment_shown else "SCHEDULE.ALREADY_BOOKED_INFO"
|
11.16.2.1. A URL da página
A página inteira é descrita por sua URL: [/schedule?doctorId=1&day=2026-09-26] exibe a agenda do médico nº 1 naquele dia; [&book=4] abre também a janela de reserva do horário nº 4. A janela de reserva de consulta não é, portanto, aberta por [JavaScript]: o servidor gera uma página que já contém a janela. Isso significa que é possível recarregar a página, adicioná-la aos favoritos, usar o botão “Voltar” do navegador, e a aplicação funciona sem [JavaScript] (o único script da aplicação serve para as janelas de confirmação, e também funciona sem ele; veja o exemplo 21).
11.16.2.2. GET /schedule
- linhas 65–68: o que a ação sabe sobre o usuário para determinar a exibição: um “gerente” (ADMIN ou DOCTOR) ou um paciente, que pode ou não fazer uma reserva;
- linhas 83–91: o dia: o dia especificado na URL, se for válido; caso contrário, hoje. Os parâmetros são lidos em formato bruto ([request.args.get]) para distinguir um parâmetro ausente ([None]: usa-se o valor padrão, sem erro) de um parâmetro inválido (um erro é informado). Apenas hoje e os dias seguintes podem receber reservas;
- linhas 94–98: o médico: o da URL; caso contrário, para um médico conectado, o próprio médico: um médico pode ver sua agenda do dia diretamente ao fazer login;
- linha 101: a lista suspensa de médicos, lida do cache, com o médico selecionado em destaque;
- linhas 104–110: a agenda, se um médico estiver selecionado e a data for válida. Um médico inexistente (um ID modificado manualmente na URL) provoca uma mensagem de erro, não uma página de erro;
- linhas 114–125: a janela de reserva, somente se o horário solicitado existir e puder ser reservado por este usuário: um paciente que acrescente [&book=2] à URL de um horário já reservado não verá nada. [next(...)] procura a entrada correspondente da agenda (exemplo 21). A janela exibe uma lista de pacientes para um administrador; para um paciente, exibe o próprio nome;
- Linhas 127–137: o modelo da página. [back_url] é a URL da agenda sem a janela de reserva; o botão “Cancelar” da janela leva até ela.
11.16.2.3. POST /schedule/book
- linha 152: todos os papéis podem fazer reservas. O decorador documenta a regra e a protege caso um quarto papel venha a surgir no futuro;
- linhas 154–157: os campos ocultos do formulário. Campos inválidos só podem resultar de uma requisição fabricada manualmente: erro 400;
- linhas 160–168: o paciente da consulta. Para um paciente, é sempre ele próprio: o campo [clientId] é ignorado. Confiar em um campo enviado pelo navegador permitiria que um paciente reservasse em nome de outro. Para um administrador que não selecionou um paciente, a janela de reserva é reaberta com uma mensagem;
- linhas 170–189: validações (o paciente existe, o horário existe e pertence ao médico da agenda), seguidas da reserva. As regras de negócio são verificadas pela camada de lógica de negócio; uma [BusinessException] se torna uma mensagem flash de erro. A mensagem “apenas uma consulta futura” é adaptada quando o próprio paciente faz a reserva (“Você já tem...” em vez de “Este paciente já tem...”);
- linha 190: em todos os casos, retorno à agenda (esquema PRG).
11.16.2.4. POST /schedule/cancel
- Linhas 197–211: cancelamento de uma consulta, reservado aos administradores (um paciente cancela sua consulta a partir de sua conta). Uma consulta já cancelada (por outra pessoa ou por um clique duplo) exibe uma mensagem, não um erro.
- linhas 217–222: as permissões do usuário. Para um paciente, é necessário ver suas consultas futuras: uma lista vazia é “incorreta”, daí [not upcoming];
- linhas 228–248: a agenda do dia, formatada para exibição e filtrada conforme as permissões. É aqui que entra a confidencialidade do paciente (linha 243): para um paciente, os nomes dos outros pacientes não são apenas ocultados da vista; eles nunca são incluídos no template. O HTML enviado ao navegador, portanto, não os contém, mesmo ocultos (caso contrário, um simples “Exibir código-fonte” os revelaria). O botão “Reservar” aparece somente quando há um horário disponível, um dia reservável e um usuário com direito de fazer reserva; o botão “Cancelar” aparece somente para um administrador;
- linhas 254–257: os campos ocultos [doctorId] and [day] nos formulários POST, validados;
- linhas 262–265: a URL da agenda. [url_for] adiciona à URL, como parâmetros, os parâmetros nomeados que não são variáveis de caminho (exemplo 16);
- linhas 278–282: a mensagem informativa para um paciente que já tem uma consulta futura: ela explica por que os botões “Reservar” estão ausentes. Não é exibida se a própria consulta do paciente aparece na agenda (em azul), o que ocorre logo após a reserva. [any(...)] retorna [True] se uma das duas condições for verdadeira.
11.16.3. controllers/persons.py
O gerenciamento de médicos e de clientes, reservado ao administrador, é idêntico: mesma lista, mesmo formulário, mesmas regras. Em vez de escrever as mesmas ações duas vezes, escrevemos uma única vez, em uma fábrica de blueprints.
| # =========================================================================
# controllers/persons.py
# -------------------------------------------------------------------------
# O gerenciamento dos médicos e o dos clientes (reservado ao ADMIN) são
# IDÊNTICOS: mesma lista, mesmo formulário, mesmas regras. Em vez de
# escrever as mesmas ações duas vezes, elas são escritas uma vez em uma
# FÁBRICA DE BLUEPRINTS: a função create_blueprint constrói um
# blueprint completo, a partir de uma "configuração" que diz O QUE chamar e
# QUAIS rótulos exibir. controllers/doctors.py e controllers/clients.py
# a chamam cada um com a sua. Obtemos assim, para cada um deles:
#
# 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 edição
# POST /doctors/<id>/delete exclusão
#
# (e as mesmas URLs sob /clients). As views também são comuns:
# templates/persons/list.html e templates/persons/form.html.
#
# SEGURANÇA: um before_request DO BLUEPRINT exige o papel ADMIN. Ele
# é executado antes de CADA ação do blueprint - inclusive as que seriam
# adicionadas a ele depois: a regra é escrita uma vez por todas.
# =========================================================================
from collections.abc import Callable
from dataclasses import dataclass
from flask import Blueprint, abort, redirect, render_template, url_for
from rdvmedecins.auth.security import require_roles
from rdvmedecins.entities import Person, Role
from rdvmedecins.forms.forms import PersonForm
from rdvmedecins.business.person_data import PersonData
from rdvmedecins.business.exception import BusinessException
from rdvmedecins.models.view_models import (PersonKeys, FormState, PersonFormModel,
PersonListModel, Message, PersonView,
PersonValues)
from rdvmedecins.web import validation
from rdvmedecins.web.flash import flash_error, flash_success
# -----------------------------------------------------------------------
# o que cada tipo de pessoa deve fornecer. Os últimos cinco campos
# são FUNÇÕES: doctors.py e clients.py colocam neles lambdas que
# chamam os métodos do ApplicationModel (get_all_doctors...).
# -----------------------------------------------------------------------
@dataclass(frozen=True)
class PersonsConfig:
name: str # "doctors" ou "clients": o nome do blueprint e o início das URLs
keys: PersonKeys
list: Callable[[], list[Person]] # () -> lista
find: Callable[[int], Person | None] # id -> pessoa
add: Callable[[PersonData], Person] # data -> pessoa criada
edit: Callable[[int, PersonData], Person] # (id, data) -> pessoa editada
delete: Callable[[int], None] # id -> nada
def create_blueprint(config: PersonsConfig) -> Blueprint:
bp = Blueprint(config.name, __name__, url_prefix=f"/{config.name}")
# a URL de uma ação DESTE blueprint: url("list_persons") -> "/doctors"
def url(action: str, **params) -> str:
return url_for(f"{config.name}.{action}", **params)
# todas as ações do blueprint são reservadas ao ADMIN
@bp.before_request
def admin_only():
require_roles(Role.ADMIN)
# -------------------------------------------------------------------
# GET /doctors (ou /clients)
# -------------------------------------------------------------------
@bp.get("")
def list_persons():
persons = [PersonView(p.title, p.first_name, p.last_name, login(p),
url("edit_form", id=p.id),
url("delete", id=p.id))
for p in config.list()]
model = PersonListModel(config.keys.title, None, config.keys, url("add_form"),
persons)
return render_template("persons/list.html", model=model)
# -------------------------------------------------------------------
# GET /doctors/add
# -------------------------------------------------------------------
@bp.get("/add")
def add_form():
return show_form(None, PersonValues(), {}, None, None)
# -------------------------------------------------------------------
# POST /doctors/add
# PersonForm() lê a entrada; validate() a verifica.
# -------------------------------------------------------------------
@bp.post("/add")
def add():
form = PersonForm()
if not form.validate():
return show_form(None, entered_values(form), validation.errors_of(form),
None, None)
try:
person = config.add(data(form))
except BusinessException as e:
return show_business_error(None, entered_values(form), e)
flash_success(config.keys.added, **params(person))
return redirect(url("list_persons"))
# -------------------------------------------------------------------
# GET /doctors/<id>/edit
# <int:id>: o id deve ser composto de dígitos - /doctors/abc/edit não
# corresponde a nenhuma rota (página 404)
# -------------------------------------------------------------------
@bp.get("/<int:id>/edit")
def edit_form(id: int):
person = config.find(id)
if person is None:
abort(404)
values = PersonValues(person.title, person.first_name, person.last_name, login(person),
person.version)
return show_form(id, values, {}, None, None)
# -------------------------------------------------------------------
# POST /doctors/<id>/edit
# -------------------------------------------------------------------
@bp.post("/<int:id>/edit")
def edit(id: int):
form = PersonForm()
if not form.validate():
return show_form(id, entered_values(form), validation.errors_of(form),
None, None)
try:
person = config.edit(id, data(form))
except BusinessException as e:
return show_business_error(id, entered_values(form), e)
flash_success(config.keys.edited, **params(person))
return redirect(url("list_persons"))
# -------------------------------------------------------------------
# POST /doctors/<id>/delete
# (a confirmação "Are you sure?" é solicitada antes de o formulário
# ser enviado, veja static/js/app.js)
# -------------------------------------------------------------------
@bp.post("/<int:id>/delete")
def delete(id: int):
person = config.find(id)
try:
config.delete(id)
flash_success(config.keys.deleted, **params(person))
except BusinessException as e:
flash_error(e.key, **e.params)
return redirect(url("list_persons"))
# ----------------------------------------------------------------- internal functions
# id None: formulário de criação; caso contrário: formulário de edição.
# errors: campo -> chave da mensagem; error: a chave da mensagem na parte inferior
# da página; other_fields: campos adicionais a contornar em vermelho
def show_form(id: int | None, values: PersonValues, errors: dict[str, str],
error: str | None, other_fields: list[str] | None):
creating = id is None
state: FormState = validation.state(errors, other_fields)
model = PersonFormModel(
page_title=config.keys.add if creating else config.keys.edit,
error=validation.page_message(errors, Message(error) if error else None),
values=values,
state=state,
creating=creating,
action=url("add") if creating else url("edit", id=id),
list_url=url("list_persons"))
return render_template("persons/form.html", model=model)
# 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
def show_business_error(id: int | None, values: PersonValues, e: BusinessException):
if e.key in ("ERRORS.DOCTOR_NOT_FOUND", "ERRORS.PATIENT_NOT_FOUND"):
# excluído nesse meio tempo por outro ADMIN: volta para a lista
flash_error(e.key)
return redirect(url("list_persons"))
# a mensagem vai na parte inferior da página; os campos envolvidos, se houver, são
# contornados em vermelho para que o usuário veja imediatamente o que corrigir
return show_form(id, values, {}, e.key, validation.BUSINESS_ERROR_FIELDS.get(e.key))
return bp
# o que o usuário digitou (senha excluída: ela nunca é enviada de volta
# ao navegador). form.<field>.data: o valor, após os filtros
def entered_values(form: PersonForm) -> PersonValues:
return PersonValues(form.title.data or "", form.first_name.data or "", form.last_name.data or "",
form.login.data or "", form.version.data)
# o formulário validado -> os dados esperados pela camada de negócio
def data(form: PersonForm) -> PersonData:
return PersonData(form.title.data, form.last_name.data, form.first_name.data, form.login.data,
form.password.data, form.version.data)
# {name} e {login} das mensagens "added / edited / deleted"
def params(person: Person | None) -> dict[str, str]:
if person is None:
return {"name": "", "login": ""}
return {"name": f"{person.first_name} {person.last_name}", "login": login(person)}
def login(person: Person) -> str:
return person.user.login if person.user else ""
|
- linhas 49–56: o que cada tipo de entidade deve fornecer: o nome do blueprint (que também é o início da URL), as chaves de tradução e cinco funções: listar, localizar, adicionar, editar e excluir. É o mesmo procedimento dos descritores da camada de negócio;
- Linhas 59–60: a fábrica cria um blueprint, cujo nome e prefixo de URL vêm da configuração. As ações são funções internas de [create_blueprint]: elas têm acesso à variável [config] da fábrica. Cada chamada a [create_blueprint] cria um novo blueprint, com suas próprias ações;
- linhas 63–64: a URL de uma ação deste blueprint: [url("list_persons")] returns [/doctors] para o blueprint dos médicos e [/clients] para o blueprint dos clientes;
- linhas 67–69: um blueprint [before_request]: ele é executado antes de cada ação do blueprint (e somente deste), depois das da aplicação. Todas as ações ficam assim reservadas ao administrador, inclusive as que forem acrescentadas depois: a regra é escrita uma só vez e vale para todas;
- linhas 74–82: a listagem. [@bp.get("")]: a rota é o próprio prefixo do blueprint ([/doctors]);
- linhas 95–106: a operação de adição: validação do formulário (erros de entrada, exibidos abaixo dos campos), chamada à camada de negócio (erros de negócio, exibidos na parte inferior da página), seguida de uma mensagem flash e do redirecionamento para a lista. As mensagens flash recebem parâmetros: o nome e o login da pessoa;
- linhas 113–120: o formulário de edição, preenchido previamente com a versão do registro (bloqueio otimista). Uma pessoa inexistente resulta em uma página 404;
- linhas 125–136: a atualização, nos moldes da adição;
- linhas 143–151: a operação de exclusão, previamente confirmada pela janela de confirmação (exemplo 21). Uma recusa da camada de negócio (um médico que tem consultas) resulta em uma mensagem flash de erro;
- linhas 158–170: o formulário de adição ([id] igual a [None]) ou de edição, junto com seu estado (valores, erros, campos destacados em vermelho);
- linhas 174–181: um erro de negócio: uma pessoa que foi excluída por outro administrador nesse meio-tempo é devolvida à lista; as demais reexibem o formulário, com os campos pertinentes destacados em vermelho;
- linhas 188–190: os valores a reexibir: o que o usuário digitou, nunca a senha;
- linhas 194–196: o formulário validado, convertido em dados para a camada de negócio;
- linhas 200–203: os parâmetros das mensagens “adicionado/modificado/excluído”.
11.16.4. controllers/doctors.py e controllers/clients.py
| # =========================================================================
# controllers/doctors.py
# -------------------------------------------------------------------------
# Gerenciamento dos médicos (somente papel ADMIN). Todas as ações são
# construídas por controllers/persons.py: resta aqui apenas dizer O QUE
# chamar e QUAIS rótulos exibir.
#
# As funções da configuração são LAMBDAS (funções sem
# nome, escritas na hora): application() só é chamada quando
# a ação é executada, durante uma requisição - o ApplicationModel ainda não existe
# quando este módulo é importado.
# =========================================================================
from rdvmedecins.controllers.persons import PersonsConfig, create_blueprint
from rdvmedecins.models.view_models import PersonKeys
from rdvmedecins.web.services import application
doctors = create_blueprint(PersonsConfig(
name="doctors",
keys=PersonKeys(
title="DOCTORS.TITLE",
add="DOCTORS.ADD",
edit="DOCTORS.EDIT",
empty="DOCTORS.EMPTY",
confirm_delete="DOCTORS.DELETE_CONFIRM",
added="DOCTORS.ADDED",
edited="DOCTORS.UPDATED",
deleted="DOCTORS.DELETED"),
list=lambda: application().get_all_doctors(),
find=lambda id: application().get_doctor_by_id(id),
add=lambda data: application().add_doctor(data),
edit=lambda id, data: application().edit_doctor(id, data),
delete=lambda id: application().delete_doctor(id)))
|
O blueprint dos médicos, gerado por [create_blueprint] com sua configuração. As funções de configuração são funções anônimas ([lambda]), que chamam [ApplicationModel]. Por que não escrever [list=application().get_all_doctors] diretamente? Porque este módulo é executado quando é importado, na inicialização, antes de a aplicação ser criada: [application()], que exige [current_app], falharia. A função anônima adia a chamada até que a ação seja executada, durante uma requisição.
| # =========================================================================
# controllers/clients.py
# -------------------------------------------------------------------------
# Gerenciamento dos clientes (os PACIENTES do consultório), somente papel ADMIN.
# Mesmo princípio de controllers/doctors.py (veja seus comentários).
# =========================================================================
from rdvmedecins.controllers.persons import PersonsConfig, create_blueprint
from rdvmedecins.models.view_models import PersonKeys
from rdvmedecins.web.services import application
clients = create_blueprint(PersonsConfig(
name="clients",
keys=PersonKeys(
title="CLIENTS.TITLE",
add="CLIENTS.ADD",
edit="CLIENTS.EDIT",
empty="CLIENTS.EMPTY",
confirm_delete="CLIENTS.DELETE_CONFIRM",
added="CLIENTS.ADDED",
edited="CLIENTS.UPDATED",
deleted="CLIENTS.DELETED"),
list=lambda: application().get_all_clients(),
find=lambda id: application().get_client_by_id(id),
add=lambda data: application().add_client(data),
edit=lambda id, data: application().edit_client(id, data),
delete=lambda id: application().delete_client(id)))
|
O blueprint dos clientes, seguindo o mesmo padrão.
11.16.5. controllers/registration.py
| # =========================================================================
# controllers/registration.py
# -------------------------------------------------------------------------
# "Create a patient account": um paciente que ainda não tem conta
# a cria ele mesmo. Rotas PÚBLICAS (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 e 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 robôs por UM captcha, o da página de
# autenticação:
# 1. o botão "Create a patient account" envia o formulário de login
# para /register/access; se o captcha for digitado corretamente, o servidor
# emite um pass (veja auth/registration_pass.py);
# 2. sem um pass válido, /register redireciona para a
# página de autenticação - digitar a URL diretamente é inútil;
# 3. o pass é 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/limiter.py).
#
# A conta criada é exatamente a que o ADMIN criaria a partir da
# página "Patients" (mesmo método da camada de negócio: add_client), exceto
# que o paciente ESCOLHE seu login e sua senha (obrigatórios,
# com confirmação).
# =========================================================================
from flask import Blueprint, current_app, redirect, render_template, request, url_for
from rdvmedecins.auth import registration_pass
from rdvmedecins.auth.security import public
from rdvmedecins.controllers.auth import ip_address
from rdvmedecins.forms.forms import RegistrationForm
from rdvmedecins.business.person_data import PersonData
from rdvmedecins.business.exception import BusinessException
from rdvmedecins.models.view_models import RegistrationModel, Message, PersonValues
from rdvmedecins.web import validation
from rdvmedecins.web.flash import flash_error, flash_success
from rdvmedecins.web.services import application, captchas, limiter, passes
registration = Blueprint("registration", __name__, url_prefix="/register")
# -----------------------------------------------------------------------
# POST /register/access campos: captchaId, captcha (os da
# página de autenticação; login e senha, também enviados, são ignorados)
# -----------------------------------------------------------------------
@registration.post("/access")
@public
def access():
ip = ip_address()
# contas demais criadas recentemente a partir deste endereço: não precisa ir além
minutes = limiter().registration_block_minutes(ip)
if minutes > 0:
flash_error("ERRORS.TOO_MANY_ACCOUNTS", minutes=str(minutes))
return redirect(url_for("auth.show_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 not captchas().verify(request.form.get("captchaId"), request.form.get("captcha")):
limiter().login_failure(ip, "")
flash_error("ERRORS.CAPTCHA_BEFORE_ACCOUNT")
return redirect(url_for("auth.show_login"))
# captcha correto: o pass é emitido e o formulário é aberto
response = redirect(url_for("registration.form"))
registration_pass.set_cookie(response, passes().issue(), current_app.config["COOKIE_SECURE"])
return response
# -----------------------------------------------------------------------
# GET /register
# -----------------------------------------------------------------------
@registration.get("")
@public
def form():
if not passes().is_valid(request.cookies.get(registration_pass.COOKIE)):
return back_to_login()
return show(PersonValues(), {}, None, None)
# -----------------------------------------------------------------------
# POST /register
# -----------------------------------------------------------------------
@registration.post("")
@public
def create():
pass_id = request.cookies.get(registration_pass.COOKIE)
if not passes().is_valid(pass_id):
return back_to_login()
ip = ip_address()
form = RegistrationForm()
form.validate()
values = PersonValues(form.title.data or "Mr", form.first_name.data or "",
form.last_name.data or "", form.login.data or "", None)
# 1. contas demais criadas recentemente a partir deste endereço?
minutes = limiter().registration_block_minutes(ip)
if minutes > 0:
return show(values, {}, Message("ERRORS.TOO_MANY_ACCOUNTS", {"minutes": str(minutes)}),
None)
# 2. todos os erros de entrada de uma vez (campos + confirmação):
# o usuário os corrige todos de uma só vez
errors = validation.errors_of(form)
if "password" not in errors and "confirmation" not in errors \
and form.password.data != form.confirmation.data:
errors["confirmation"] = "ERRORS.PASSWORDS_DIFFER"
if errors:
return show(values, errors, None, None)
# 3. a criação (cliente + conta USER, em uma transação)
try:
application().add_client(PersonData(form.title.data, form.last_name.data,
form.first_name.data, form.login.data,
form.password.data))
except BusinessException as e:
# login ou nome + sobrenome já usados: o pass continua válido
return show(values, {}, Message(e.key), validation.BUSINESS_ERROR_FIELDS.get(e.key))
# 4. o pass foi usado: ele não permitirá criar uma 2ª conta
passes().consume(pass_id)
limiter().registration_success(ip)
# 5. volta para a página de login, login preenchido
flash_success("REGISTRATION.DONE", login=form.login.data)
response = redirect(url_for("auth.show_login", login=form.login.data))
registration_pass.clear_cookie(response)
return response
# ----------------------------------------------------------------- internal functions
# sem pass válido: volta para a página de autenticação
def back_to_login():
flash_error("ERRORS.CAPTCHA_BEFORE_ACCOUNT")
return redirect(url_for("auth.show_login"))
# o formulário; nunca uma senha enviada de volta ao navegador
def show(values: PersonValues, errors: dict[str, str], error: Message | None,
other_fields: list[str] | None):
model = RegistrationModel("REGISTRATION.TITLE", validation.page_message(errors, error),
values, validation.state(errors, other_fields))
return render_template("registration.html", model=model)
|
- Linhas 51–72: o botão “Criar uma conta de paciente” da página de login envia o formulário de login a esta ação (por meio do atributo [formaction], Exemplo 20). Ela verifica o limite de criações de conta e depois o CAPTCHA da página de login; se estiver correto, emite um token ([auth/registration_pass.py]) e redireciona para o formulário de cadastro. Uma falha é contada como uma tentativa de login malsucedida (com um nome de usuário vazio);
- linhas 78–83: o formulário, somente com um passe válido: digitar diretamente o endereço [/register] redireciona para a página de login;
- linhas 89–133: criação da conta: - o passe, novamente; - [form.validate()] é chamado, mas seu resultado é ignorado: queremos todos os erros de entrada de uma só vez, inclusive uma eventual divergência entre a senha e sua confirmação, que é então verificada pela ação (desde que os dois campos sejam válidos nos demais aspectos). O usuário corrige todos de uma vez; - o cliente e sua conta são criados com o mesmo método da lógica de negócio usado para o administrador; - o passe é consumido, e a criação é contada pelo limitador; - retorno à página de login, com uma mensagem e o login preenchido previamente (parâmetro [login] da URL). O cookie do passe é apagado.
11.16.6. controllers/area.py
As páginas pessoais do paciente.
| # =========================================================================
# controllers/area.py
# -------------------------------------------------------------------------
# As páginas PESSOAIS do paciente (papel USER), aquelas que ele vê logo
# após fazer login:
#
# GET /my-area página inicial: [Manage my account],
# [View a schedule], e sua consulta futura
# POST /my-area/cancel cancela SUA consulta
# GET /my-account formulário para editar sua conta
# POST /my-account edição
# POST /my-account/delete exclusão da conta (e de suas consultas)
#
# Regra de ouro deste controller: o paciente em questão é SEMPRE o do
# token (utils.connected_patient), nunca um identificador enviado pelo
# navegador. Um paciente não pode, portanto, nem ver, nem editar, nem cancelar o que
# pertence a outro paciente, mesmo forjando ele mesmo suas requisições.
#
# Qualquer ediçã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. Erros de senha atual
# errada são contados como falhas de login (mesmo limite).
# =========================================================================
from flask import Blueprint, redirect, render_template, request, url_for
from rdvmedecins.auth.auth_service import AuthService
from rdvmedecins.auth.security import require_roles
from rdvmedecins.controllers.auth import ip_address
from rdvmedecins.entities import Client, Role
from rdvmedecins.forms.forms import MyAccountForm
from rdvmedecins.business.person_data import PersonData
from rdvmedecins.business.exception import BusinessException
from rdvmedecins.models.view_models import (AreaModel, Message, MyAccountModel, AppointmentView,
PersonValues)
from rdvmedecins.web import utils, validation
from rdvmedecins.web.flash import flash_error, flash_success
from rdvmedecins.web.services import application, auth_service, limiter
area = Blueprint("area", __name__)
# todas as ações deste blueprint são reservadas ao papel USER
@area.before_request
def patient_only():
require_roles(Role.USER)
# -----------------------------------------------------------------------
# GET /my-area
# -----------------------------------------------------------------------
@area.get("/my-area")
def patient_area():
patient = utils.connected_patient(application())
appointments = [AppointmentView(
a.id,
utils.format_day(a.day),
utils.time(a.slot),
utils.label(a.slot.doctor),
# link para a agenda do médico nesse dia: o paciente vê seu nome lá
url_for("schedule.show", doctorId=a.slot.doctor_id, day=utils.iso(a.day)))
for a in application().get_client_upcoming_appointments(patient.id)]
model = AreaModel("AREA.TITLE", None, utils.label(patient), appointments)
return render_template("area.html", model=model)
# -----------------------------------------------------------------------
# POST /my-area/cancel campo: appointmentId
# -----------------------------------------------------------------------
@area.post("/my-area/cancel")
def cancel_appointment():
patient = utils.connected_patient(application())
appointment_id = utils.positive_integer(request.form.get("appointmentId"))
appointment = application().get_appointment_by_id(appointment_id) if appointment_id is not None else None
# uma consulta que não existe e a de OUTRO paciente recebem
# a mesma resposta: nada é revelado sobre as consultas dos outros
if appointment is None or appointment.client_id != patient.id:
flash_error("ERRORS.APPOINTMENT_NOT_FOUND")
else:
application().delete_appointment(appointment)
flash_success("SCHEDULE.CANCELLED")
return redirect(url_for("area.patient_area"))
# -----------------------------------------------------------------------
# GET /my-account
# -----------------------------------------------------------------------
@area.get("/my-account")
def account_form():
patient = utils.connected_patient(application())
values = PersonValues(patient.title, patient.first_name, patient.last_name, patient.user.login,
patient.version)
return show(values, {}, None, None)
# -----------------------------------------------------------------------
# POST /my-account
# -----------------------------------------------------------------------
@area.post("/my-account")
def edit_account():
patient = utils.connected_patient(application())
form = MyAccountForm()
form.validate()
values = PersonValues(form.title.data or patient.title, form.first_name.data or "",
form.last_name.data or "", form.login.data or "", form.version.data)
errors = validation.errors_of(form)
if "password" not in errors and form.password.data is not None \
and form.password.data != form.confirmation.data:
errors["confirmation"] = "ERRORS.PASSWORDS_DIFFER"
if errors:
return show(values, errors, None, None)
# a senha atual
password_error = check_current_password(patient, form.current_password.data)
if password_error is not None:
# senha errada: a mensagem também vai SOB o campo
field_errors = ({"current_password": password_error.key}
if password_error.key == "ERRORS.WRONG_CURRENT_PASSWORD" else {})
return show(values, field_errors, password_error, None)
try:
client = application().edit_client(patient.id, PersonData(
form.title.data, form.last_name.data, form.first_name.data, form.login.data,
form.password.data, # None = inalterado
form.version.data))
except BusinessException as e:
return show(values, {}, Message(e.key), validation.BUSINESS_ERROR_FIELDS.get(e.key))
# o login e o nome exibido estão NO token: um novo é
# emitido, caso contrário a barra de navegação manteria o nome antigo
flash_success("MY_ACCOUNT.UPDATED")
response = redirect(url_for("area.patient_area"))
auth_service().set_token(response, client.user)
return response
# -----------------------------------------------------------------------
# POST /my-account/delete campo: delete_password
# A conta, o cliente e TODAS as suas consultas desaparecem juntos,
# depois o paciente é desconectado.
# -----------------------------------------------------------------------
@area.post("/my-account/delete")
def delete_account():
patient = utils.connected_patient(application())
password_error = check_current_password(
patient, request.form.get("delete_password"))
if password_error is not None:
flash_error(password_error.key, **password_error.params)
return redirect(url_for("area.account_form"))
application().delete_client(patient.id)
flash_success("MY_ACCOUNT.DELETED")
response = redirect(url_for("auth.show_login"))
AuthService.clear_token(response)
return response
# ----------------------------------------------------------------- internal functions
# None se a senha atual estiver correta; caso contrário, a mensagem de erro
def check_current_password(patient: Client, password: str | None) -> Message | None:
ip = ip_address()
login = patient.user.login
minutes = limiter().login_block_minutes(ip, login)
if minutes > 0:
return Message("ERRORS.TOO_MANY_ATTEMPTS", {"minutes": str(minutes)})
ok = bool(password) and auth_service().validate_user(login, password) is not None
if not ok:
limiter().login_failure(ip, login)
return Message("ERRORS.WRONG_CURRENT_PASSWORD")
return None
def show(values: PersonValues, errors: dict[str, str], error: Message | None,
other_fields: list[str] | None):
model = MyAccountModel("MY_ACCOUNT.TITLE", validation.page_message(errors, error), values,
validation.state(errors, other_fields))
return render_template("account.html", model=model)
|
- linhas 43–45: todas as ações do blueprint são reservadas ao papel USER;
- linhas 51–63: o painel do paciente: suas consultas futuras, formatadas, cada uma com um link para a agenda do médico naquele dia. O paciente é sempre aquele associado ao token ([utils.connected_patient]), nunca um identificador enviado pelo navegador: um paciente não pode ver, modificar nem cancelar as informações de outro paciente;
- linhas 69–81: cancelamento da consulta do paciente. Uma consulta inexistente e a consulta de outro paciente recebem a mesma resposta: nenhuma informação sobre as consultas de outros pacientes é divulgada (caso contrário, um paciente poderia descobrir quais números de consulta existem);
- linhas 87–92: o formulário da conta do usuário, preenchido previamente;
- linhas 98–133: a edição: validação dos campos e da confirmação, verificação da senha atual e, em seguida, chamada à camada de negócio. O login e o nome exibido estão no token: a ação emite um novo; caso contrário, a barra de navegação manteria o nome antigo até o próximo login;
- linhas 141–153: exclusão da conta, também protegida pela senha atual. A conta, o cliente e todas as suas consultas são excluídos em conjunto; o paciente é desconectado;
- linhas 159–169: a senha atual protege a conta de qualquer pessoa que encontre uma sessão deixada aberta. Os erros são contados como falhas de login, com o mesmo limite: não podem ser usados para descobrir a senha.
11.17. As views
A pasta [templates] contém as views [Jinja2] da aplicação: um template, sete fragmentos e oito páginas. Todas seguem a mesma regra: nenhuma lógica nas views. As ações lhes passam modelos pré-preparados ([models/view_models.py]); as views apenas inserem os dados no HTML e traduzem os textos por meio da função [t]. Elas não contêm nenhum texto fixo no código: tudo passa pelos dicionários.
11.17.1. O template e os fragmentos
11.17.1.1. templates/layout.html
| <!doctype html>
{# =========================================================================
templates/layout.html
=========================================================================
O layout COMUM a todas as páginas (veja o exemplo 15): cada página
(schedule.html, login.html...) o ESTENDE ({% extends %}) e preenche seu bloco
[content].
O Jinja2 ESCAPA tudo o que exibe com {{ ... }} (os caracteres
< > & " ' viram < >...): proteção contra injeção de HTML
por meio de um nome digitado, por exemplo. Para inserir HTML como está, é preciso
pedir explicitamente (filtro safe, veja fragments/captcha.html).
Mensagens: um sucesso é exibido no TOPO da página, um erro no PÉ, sobre
um fundo rosa claro (fragmento errors.html).
O layout compartilha as variáveis da página: [model] (o modelo de view
passado pela action, veja models/view_models.py), de onde lê a chave do
título da página; [language], [user], [path], [t], adicionadas a
todas as views por web/common_model.py.
========================================================================= #}
<html lang="{{ language }}">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
{# t(key): a tradução de uma chave; aqui, a chave é uma VARIÁVEL (model.page_title) #}
<title>{{ t(model.page_title) }} - {{ t("APP.TITLE") }}</title>
<link rel="stylesheet" href="{{ url_for('static', filename='lib/bootstrap/css/bootstrap.min.css') }}">
<link rel="stylesheet" href="{{ url_for('static', filename='css/styles.css') }}">
</head>
<body>
{# as mensagens flash definidas pela requisição anterior: lidas UMA VEZ
(get_flashed_messages as esquece imediatamente), depois separadas: os sucessos
no topo, os erros no pé #}
{% set flashes = get_flashed_messages(with_categories=true) %}
<div class="container py-4">
{% include "fragments/navbar.html" %}
{% include "fragments/flash.html" %}
<main>
{% block content %}{% endblock %}
</main>
{% include "fragments/errors.html" %}
</div>
{# o diálogo "Are you sure?", oculto até ser necessário #}
{% include "fragments/confirmation.html" %}
<script src="{{ url_for('static', filename='js/app.js') }}"></script>
</body>
</html>
|
- linha 22: o idioma da página, fornecido pelo context processor;
- linha 27: o título da página. A chave do título é uma variável ([model.page_title]): cada modelo de página fornece uma (o procedimento do Exemplo 22, usando o modelo da view em vez de uma variável [{% set %}]);
- linha 28: [Bootstrap] faz parte da aplicação, localizado em sua pasta [static];
- Linha 35: as mensagens flash são lidas uma única vez pelo template; [get_flashed_messages] as esquece imediatamente, e uma segunda chamada retornaria uma lista vazia. Com [with_categories=true], a função retorna tuplas (categoria, mensagem). A variável [flashes] é então lida pelos dois fragmentos que as exibem: mensagens de sucesso no alto, mensagens de erro na parte inferior. Uma variável definida por [{% set %}] é visível para os fragmentos incluídos por [{% include %}];
- linhas 37–42: a barra de navegação, as mensagens de sucesso, o conteúdo da página e a área de erros;
- linhas 45–46: a janela de confirmação e o script que a gerencia (Exemplo 21).
11.17.1.2. templates/fragments/navbar.html
| {# =========================================================================
templates/fragments/navbar.html - a barra de navegação.
Título, FR/EN, papel, nome, logout - e um menu cujas entradas
dependem do papel: "Doctors" e "Patients" só aparecem para
o ADMIN. É apenas uma conveniência de exibição: a proteção real são
as verificações de papel das actions (um USER que digita /doctors à mão
recebe uma página 403). Um paciente (USER) tem ainda o seu menu "My area".
O menu da página atual fica destacado (classe "active"):
[path] é a URL solicitada (veja web/common_model.py). Uma macro escreve
uma só vez o HTML de uma entrada de menu; seu parâmetro opcional [prefix]
(href por padrão) é o início dos caminhos para os quais a entrada fica ativa.
========================================================================= #}
{% macro entry(href, key, prefix=none) %}
<li class="nav-item">
<a class="nav-link{{ ' active' if path.startswith(prefix or href) }}" href="{{ href }}">{{ t(key) }}</a>
</li>
{% endmacro %}
<nav class="navbar navbar-expand-sm navbar-dark bg-primary rounded mb-4 px-3">
<span class="navbar-brand mb-0">{{ t("APP.TITLE") }}</span>
{% if user %}
<ul class="navbar-nav me-auto">
{% if user.is_patient %}
{# ativa para /my-area E /my-account #}
{{ entry("/my-area", "APP.MENU_MY_AREA", "/my-") }}
{% endif %}
{{ entry("/schedule", "APP.MENU_SCHEDULE") }}
{% if user.is_admin %}
{{ entry("/doctors", "APP.MENU_DOCTORS") }}
{{ entry("/clients", "APP.MENU_PATIENTS") }}
{% endif %}
</ul>
{% else %}
<div class="me-auto"></div>
{% endif %}
<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">
{% for code in ["fr", "en"] %}
<a class="btn {{ 'btn-light' if language == code else 'btn-outline-light' }}" href="/language/{{ code }}">{{ code | upper }}</a>
{% endfor %}
</div>
{% if user %}
<span class="badge text-bg-light text-primary">{{ user.role }}</span>
<span class="text-white">{{ user.name }}</span>
{# o logout é um POST: um formulário reduzido ao seu botão (e ao token anti-CSRF) #}
<form method="post" action="/logout" class="m-0">
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
<button type="submit" class="btn btn-sm btn-outline-light">{{ t("APP.LOGOUT") }}</button>
</form>
{% endif %}
</div>
</nav>
|
- linhas 15–19: um item de menu, destacado (classe [active]) se o caminho da página atual começar pelo seu prefixo. O parâmetro [prefix] é opcional ([none] para o [Jinja2], assim como [None] para o [Python]); caso contrário, é o endereço da entrada ([prefix or href]). A entrada “Minha área” tem o prefixo [/my-]: ela fica ativa tanto para [/my-area] quanto para [/my-account];
- linhas 23–37: o menu depende do papel: “Minha área” para um paciente, “Médicos” e “Pacientes” para o administrador. Isso é apenas uma conveniência de exibição; a segurança real vem dos controles por papel nas ações. Um paciente que digite manualmente [/doctors] receberá uma página de erro 403;
- linhas 42–44: os botões FR e EN são simples links para [/language/fr] and [/language/en];
- linhas 48–54: papel, nome de usuário e logout: um formulário POST reduzido ao seu botão, com o token anti-CSRF.
11.17.1.3. templates/fragments/flash.html
| {# =========================================================================
templates/fragments/flash.html - as mensagens de SUCESSO definidas pela
action anterior (consulta salva, médico adicionado...),
exibidas uma única vez, no topo da página (veja web/flash.py).
Uma mensagem flash de ERRO é exibida no pé da página, por
fragments/errors.html.
[flashes]: a lista dos pares (categoria, mensagem), lida pelo layout.
t(message.key, message.params): a mensagem cuja chave é
message.key, com como parâmetro o dicionário dos valores de {name},
{login}... (veja web/translator.py).
========================================================================= #}
{% for category, message in flashes if category == "success" %}
<div class="alert alert-success" role="status">{{ t(message.key, message.params) }}</div>
{% endfor %}
|
- linha 13: um laço [for] do [Jinja2] pode filtrar seus elementos: [for ... in ... if condition] itera apenas sobre os elementos que satisfazem a condição. Cada elemento é um par, com as duas partes armazenadas em duas variáveis;
- linha 14: a mensagem é um dicionário (veja [web/flash.py]): sua chave e seus parâmetros. A notação de ponto no [Jinja2] também lê as chaves de um dicionário (exemplo 13).
11.17.1.4. templates/fragments/errors.html
| {# =========================================================================
templates/fragments/errors.html - a zona de erro, no PÉ de cada
página, sobre um fundo rosa claro (classe .error-zone, veja static/css/styles.css).
Ela reúne as duas fontes possíveis de erro:
- model.error: o erro da página exibida (formulário recusado, login
ou nome + sobrenome já usados, data inválida, senha incorreta...);
- as mensagens flash de erro, definidas pela action anterior antes de um
redirecionamento (horário já reservado, exclusão recusada...).
Um laço for pode filtrar seus elementos: "for ... in ... if condition".
role="alert": um leitor de tela anuncia a mensagem assim que a página é
exibida, mesmo que ela esteja no pé.
========================================================================= #}
{% set flash_errors = flashes | selectattr(0, "equalto", "danger") | list %}
{% if model.error or flash_errors %}
<div class="error-zone" role="alert">
{% if model.error %}
<div>{{ t(model.error.key, model.error.params) }}</div>
{% endif %}
{% for category, message in flash_errors %}
<div>{{ t(message.key, message.params) }}</div>
{% endfor %}
</div>
{% endif %}
|
- linha 15: mensagens flash de erro, extraídas por dois filtros: [selectattr(0, "equalto", "danger")] mantém apenas os elementos cujo atributo [0] (o primeiro elemento do par, a categoria) é igual a ["danger"]; [list] converte o resultado em uma lista (filtros desse tipo retornam um iterador que só pode ser percorrido uma vez e cuja vacuidade não pode ser verificada);
- Linhas 16–25: a área de erros combina as duas fontes de erros: os erros da página exibida (um formulário rejeitado, uma data inválida) e os erros gerados pela ação anterior antes de um redirecionamento (um horário já ocupado, uma exclusão recusada). A área só existe se houver pelo menos um erro.
11.17.1.5. templates/fragments/confirmation.html
| {# =========================================================================
templates/fragments/confirmation.html - 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 ficam no idioma do
navegador, não no da página).
UM ÚNICO 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 static/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.
Mesmas classes Bootstrap do diálogo de reserva (fragments/booking.html).
========================================================================= #}
<div id="confirmation-modal" class="d-none">
<div class="modal-backdrop fade show"></div>
<div class="modal fade show d-block" tabindex="-1" role="alertdialog" aria-modal="true"
aria-labelledby="confirmation-modal-title" aria-describedby="confirmation-modal-message">
<div class="modal-dialog modal-dialog-centered">
<div class="modal-content">
<div class="modal-header">
<h5 class="modal-title" id="confirmation-modal-title">{{ t("CONFIRMATION.TITLE") }}</h5>
<button type="button" class="btn-close" data-action="no" aria-label="{{ t('BOOKING_DIALOG.CLOSE_ARIA') }}"></button>
</div>
<div class="modal-body">
<p class="mb-0" id="confirmation-modal-message"></p>
</div>
<div class="modal-footer">
{# "No, go back" em vez de "Cancel": a pergunta às vezes é
"Cancel this appointment?", e um botão "Cancel" seria ambíguo nesse caso #}
<button type="button" class="btn btn-secondary" data-action="no">{{ t("CONFIRMATION.NO") }}</button>
<button type="button" class="btn btn-danger" data-action="yes">{{ t("CONFIRMATION.YES") }}</button>
</div>
</div>
</div>
</div>
</div>
|
A janela de confirmação do Exemplo 21, com rótulos traduzidos pelo servidor (a caixa [window.confirm()] do navegador exibe seus botões no idioma do navegador, e não no da página), um botão de fechar e atributos de acessibilidade: [aria-labelledby] e [aria-describedby] se referem ao título e à mensagem da janela, que os leitores de tela anunciam quando a janela é aberta. O botão “Não, voltar” é preferível a “Cancelar”: a pergunta às vezes é “Cancelar esta consulta?”, e um botão “Cancelar” seria ambíguo nesse contexto.
11.17.1.6. templates/fragments/captcha.html
| {# =========================================================================
templates/fragments/captcha.html - o captcha da página de autenticação
(veja auth/captcha.py). Ele protege tanto o login quanto o acesso à
criação de conta ("Create a patient account" botão).
Uma macro, cujo parâmetro é um objeto Captcha (id, svg).
O filtro safe: a imagem SVG é inserida TAL COMO ESTÁ na página, sem
escape. Isso é inofensivo aqui porque esse SVG é construído pelo
próprio servidor e não contém nada vindo do usuário - jamais se faria
isso com uma entrada.
O campo oculto captchaId diz ao servidor QUAL captcha verificar; a própria
resposta certa nunca é enviada ao navegador.
"Another image" simplesmente recarrega a página ([path] = a URL atual).
Uma macro não enxerga as variáveis da página que a chama ("with
context": ela enxerga, na importação, login.html): aqui, t e path.
========================================================================= #}
{% macro captcha(captcha) %}
<div class="mb-3">
<label class="form-label" for="captcha">{{ t("CAPTCHA.LABEL") }}</label>
<div class="d-flex align-items-center gap-3 mb-2">
<div class="captcha-image" role="img" aria-label="{{ t('CAPTCHA.IMAGE_ALT') }}">{{ captcha.svg | safe }}</div>
<a class="small" href="{{ path }}">{{ 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">
<div class="form-text">{{ t("CAPTCHA.HELP") }}</div>
</div>
{% endmacro %}
|
- linha 18: uma macro que recebe um objeto [Captcha];
- linha 22: a imagem SVG, inserida como está (exemplo 27). O atributo [role="img"] e seu [aria-label] descrevem a imagem para os leitores de tela;
- linha 23: o link “Outra imagem” simplesmente recarrega a página: cada exibição gera um novo CAPTCHA;
- Linhas 25–27: o ID do CAPTCHA e o campo de entrada. [autocapitalize="off"] e [spellcheck="false"] impedem que os celulares modifiquem a entrada (letra inicial maiúscula, verificação ortográfica).
Por padrão, uma macro importada não tem acesso às variáveis da página que a importa: a função [t] e a variável [path], fornecidas pelo context processor, seriam desconhecidas para ela. É por isso que [login.html] a importa com a referência [with context].
11.17.1.7. templates/fragments/person_fields.html
| {# =========================================================================
templates/fragments/person_fields.html - os campos de identidade (título,
nome, sobrenome), comuns a três formulários: médico/cliente do ADMIN,
"Create a patient account" e "Manage my account".
O fragmento, inserido por {% include %}, lê a variável [model] da
página que o insere (um FormView, veja models/view_models.py):
valores, mensagem sob cada campo, campos contornados em vermelho.
selected: um atributo booleano, escrito se a opção estiver escolhida, omitido caso contrário.
state.invalid_class(field): "is-invalid" (contorno vermelho do Bootstrap)
para um campo recusado, "" caso contrário.
========================================================================= #}
{% set state = model.state %}
<div class="mb-3">
<label class="form-label" for="title">{{ t("PERSONS.TITLE_LABEL") }}</label>
<select id="title" name="title" class="form-select {{ state.invalid_class('title') }}">
{% for title in model.titles %}
<option value="{{ title.value }}"{{ " selected" if title.selected }}>{{ title.value }}</option>
{% endfor %}
</select>
{% if state.error_of("title") %}
<div class="invalid-feedback">{{ t(state.error_of("title")) }}</div>
{% endif %}
</div>
<div class="row g-3 mb-3">
<div class="col-sm-6">
<label class="form-label" for="first_name">{{ t("PERSONS.FIRSTNAME_LABEL") }}</label>
<input id="first_name" name="first_name" type="text" maxlength="20" required
class="form-control {{ state.invalid_class('first_name') }}" value="{{ model.values.first_name }}">
{% if state.error_of("first_name") %}
<div class="invalid-feedback">{{ t(state.error_of("first_name")) }}</div>
{% endif %}
</div>
<div class="col-sm-6">
<label class="form-label" for="last_name">{{ t("PERSONS.LASTNAME_LABEL") }}</label>
<input id="last_name" name="last_name" type="text" maxlength="20" required
class="form-control {{ state.invalid_class('last_name') }}" value="{{ model.values.last_name }}">
{% if state.error_of("last_name") %}
<div class="invalid-feedback">{{ t(state.error_of("last_name")) }}</div>
{% endif %}
</div>
</div>
|
Os campos de identidade (tratamento, nome, sobrenome), comuns aos três formulários da aplicação. O fragmento, inserido por [{% include %}], lê a variável [model] da página que o insere: um modelo que herda de [FormView].
- Linhas 16–20: a lista de tratamentos, calculada pela propriedade [titles] do modelo, com o tratamento selecionado em destaque;
- linhas 29–30: o campo de entrada do nome, com o valor a reexibir, e a classe [is-invalid] se o campo for rejeitado ([state.invalid_class('first_name')]);
- linhas 31–33: a mensagem abaixo do campo, traduzida.
Os atributos [maxlength] e [required] são controles do navegador. Os formulários da aplicação incluem o atributo [novalidate] (Exemplo 19): essas verificações não são realizadas antes do envio; a validação fica a cargo do servidor. [maxlength], por outro lado, sempre impede que os usuários digitem mais caracteres do que uma coluna comporta.
11.17.1.8. templates/fragments/booking.html
| {# =========================================================================
templates/fragments/booking.html - o diálogo de reserva da
agenda.
As classes Bootstrap REAIS de um diálogo modal (.modal,
.modal-backdrop...), tornado visível "fixo no código" (show d-block) em vez
de pelo JavaScript do Bootstrap. É 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.
O fragmento lê diretamente a variável [model] da página que o insere
(um ScheduleModel).
========================================================================= #}
{% set booking = model.booking %}
<div class="modal-backdrop fade show"></div>
<div class="modal fade show d-block" tabindex="-1" role="dialog" aria-modal="true" aria-labelledby="booking-title">
<div class="modal-dialog modal-dialog-centered">
<form method="post" action="/schedule/book" class="modal-content">
<div class="modal-header">
<h5 class="modal-title" id="booking-title">{{ t("BOOKING_DIALOG.TITLE") }}</h5>
<a class="btn-close" href="{{ model.back_url }}" 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="csrf_token" value="{{ csrf_token() }}">
<input type="hidden" name="doctorId" value="{{ model.doctor_id }}">
<input type="hidden" name="day" value="{{ model.day }}">
<input type="hidden" name="slotId" value="{{ booking.slot_id }}">
{# um paciente reserva para si mesmo: sem lista para escolher
(e o servidor ignora de qualquer forma um eventual clientId) #}
{% if booking.patient %}
<p class="mb-0">
<span>{{ t("BOOKING_DIALOG.PATIENT_LABEL") }}</span>:
<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>
{% for client in booking.clients %}
<option value="{{ client.id }}">{{ client.label }}</option>
{% endfor %}
</select>
{% endif %}
</div>
<div class="modal-footer">
<a class="btn btn-secondary" href="{{ model.back_url }}">{{ t("BOOKING_DIALOG.CANCEL") }}</a>
<button type="submit" class="btn btn-primary">{{ t("BOOKING_DIALOG.CONFIRM") }}</button>
</div>
</form>
</div>
</div>
|
A janela de reserva. Ela usa as classes reais de uma janela modal do [Bootstrap] ([modal], [modal-backdrop]...), tornadas visíveis “diretamente no código” ([show d-block]) em vez de pelo [JavaScript] do [Bootstrap]: o servidor decide se ela deve ser exibida (o parâmetro [book] da URL), e fechá-la equivale a seguir um link para a mesma página sem esse parâmetro ([model.back_url]).
- Linhas 29–31: campos ocultos: informações que o servidor precisa conhecer, além do paciente selecionado;
- linhas 35–48: um paciente faz uma reserva para si mesmo: seu nome é exibido, sem lista de opções (e o servidor ignoraria de qualquer modo um campo [clientId]). Para um administrador, é exibida a lista de pacientes, cuja primeira opção, com valor vazio, convida a fazer uma seleção.
11.17.2. As páginas
11.17.2.1. templates/login.html
| {# =========================================================================
templates/login.html - o formulário de login (veja controllers/auth.py).
Um <form> HTML comum: o próprio navegador envia login,
senha e resposta do captcha em POST /login, sem JavaScript. Em
caso de falha, o servidor devolve ESTA página, com o login já digitado, um
NOVO captcha e o erro, exibido no pé da página pelo layout.
========================================================================= #}
{% extends "layout.html" %}
{# with context: a macro enxerga as variáveis desta página (t, path) #}
{% from "fragments/captcha.html" import captcha with context %}
{% block content %}
{% set login_typed = model.login != "" %}
<div class="row justify-content-center">
<div class="col-sm-8 col-md-6 col-lg-5">
<div class="card p-4">
<h5 class="card-title mb-3">{{ t("LOGIN.TITLE") }}</h5>
<form method="post" action="/login">
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
<div class="mb-3">
<label class="form-label" for="login">{{ t("LOGIN.LOGIN_LABEL") }}</label>
{# autofocus: um atributo booleano, escrito se a condição for verdadeira, omitido caso contrário #}
<input id="login" name="login" type="text" class="form-control" autocomplete="username"
value="{{ model.login }}" required{{ " autofocus" if not login_typed }}>
</div>
<div class="mb-3">
<label class="form-label" for="password">{{ t("LOGIN.PASSWORD_LABEL") }}</label>
<input id="password" name="password" type="password" class="form-control"
autocomplete="current-password" required{{ " autofocus" if login_typed }}>
</div>
{{ captcha(model.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 link simples: é um segundo botão de envio deste
MESMO 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 controllers/registration.py).
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">
<span>{{ t("LOGIN.DEMO_ACCOUNTS") }}</span>
<ul class="mb-0 mt-1">
<li><code>admin</code> - <span>{{ t("LOGIN.DEMO_ADMIN") }}</span></li>
<li><code>pelissier</code>, <code>tatou</code>, <code>dupont</code> - <span>{{ t("LOGIN.DEMO_DOCTOR") }}</span></li>
<li><code>martin</code>, <code>durand</code>, <code>bistrou</code>, <code>german</code> - <span>{{ t("LOGIN.DEMO_USER") }}</span></li>
</ul>
</div>
</div>
</div>
</div>
{% endblock %}
|
- linha 10: a macro é importada, junto com o contexto da página;
- linha 13: o cursor é colocado no campo de login se ele estiver vazio, ou no campo de senha em caso contrário (após uma tentativa de login malsucedida ou após a criação de uma conta): o atributo booleano [autofocus] é definido em um ou no outro;
- linhas 24–30: os valores do atributo [autocomplete] ajudam os gerenciadores de senhas dos navegadores a preencher o formulário;
- linhas 46–47: o botão “Criar uma conta de paciente” não é um link, mas um segundo botão para enviar este formulário, que o envia a um endereço diferente ([formaction], exemplo 20). O servidor verifica ali o CAPTCHA antes de abrir a página de criação de conta. [formnovalidate]: o navegador não exige o nome de usuário e a senha, marcados como [required], que são desnecessários para criar uma conta. Pressionar a tecla Enter em um campo sempre aciona o primeiro botão do formulário, “Entrar”.
11.17.2.2. templates/schedule.html
| {# =========================================================================
templates/schedule.html - a página principal (veja controllers/schedule.py).
Três blocos:
1. a escolha do médico e do dia;
2. a agenda;
3. o diálogo de reserva (fragments/booking.html).
Um possível erro (data inválida, médico desconhecido) é exibido no
pé da página pelo layout (veja fragments/errors.html).
========================================================================= #}
{% extends "layout.html" %}
{% block content %}
{# 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>
{% for doctor in model.doctors %}
<option value="{{ doctor.id }}"{{ " selected" if doctor.selected }}>{{ doctor.label }}</option>
{% endfor %}
</select>
</div>
<div class="col-sm-4">
<label class="form-label" for="day">{{ t("DOCTOR_DAY_PICKER.DAY_LABEL") }}</label>
<input id="day" name="day" type="date" class="form-control" value="{{ model.day }}" required>
</div>
<div class="col-sm-3">
<button type="submit" class="btn btn-primary w-100">{{ t("DOCTOR_DAY_PICKER.VIEW_SCHEDULE") }}</button>
</div>
</div>
</form>
{# paciente que já tem uma consulta futura: por isso não há botão "Book" #}
{% if model.info %}
<div class="alert alert-info">
<span>{{ t(model.info) }}</span>
<a href="/my-area" class="alert-link">{{ t("APP.MENU_MY_AREA") }}</a>
</div>
{% endif %}
{# 2. a agenda #}
{% set schedule = model.schedule %}
{% if schedule %}
<div class="card p-3">
<h5>{{ t("SCHEDULE.TITLE_PREFIX") }} {{ schedule.day }} - {{ schedule.doctor }}</h5>
{% if schedule.rows %}
<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>
{% for row in schedule.rows %}
<tr class="{{ 'free-slot' if row.bookable }}">
<td>{{ row.time }}</td>
<td>
{# [patient] é preenchido somente 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 row.free %}
<span class="badge text-bg-success">{{ t("SCHEDULE.FREE") }}</span>
{% elif row.patient %}
<span class="badge {{ 'text-bg-primary' if row.mine else 'text-bg-secondary' }}">{{ row.patient }}</span>
{% else %}
<span class="badge text-bg-secondary">{{ t("SCHEDULE.BOOKED_BY_OTHER") }}</span>
{% endif %}
</td>
<td>
{# os botões exibidos foram decididos pelo controller
(bookable, appointment_id) de acordo com o papel do usuário.
"Book" é um link simples: ele reabre esta página
com o diálogo de reserva deste horário #}
{% if row.bookable %}
<a class="btn btn-sm btn-outline-success" href="{{ row.book_url }}">{{ t("SCHEDULE.BOOK") }}</a>
{% endif %}
{# "Cancel" MODIFICA dados: portanto é um POST #}
{% if row.appointment_id %}
<form method="post" action="/schedule/cancel" class="m-0"
data-confirmation="{{ t('SCHEDULE.CANCEL_CONFIRM') }}">
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
<input type="hidden" name="appointmentId" value="{{ row.appointment_id }}">
<input type="hidden" name="doctorId" value="{{ model.doctor_id }}">
<input type="hidden" name="day" value="{{ model.day }}">
<button type="submit" class="btn btn-sm btn-outline-danger">{{ t("SCHEDULE.CANCEL_APPOINTMENT") }}</button>
</form>
{% endif %}
</td>
</tr>
{% endfor %}
</tbody>
</table>
{% else %}
<p class="text-muted mb-0">{{ t("SCHEDULE.NO_SLOTS") }}</p>
{% endif %}
</div>
{% else %}
<p class="text-muted">{{ t("SCHEDULE.EMPTY_STATE") }}</p>
{% endif %}
{# 3. o diálogo de reserva, somente se a URL contiver &book=... #}
{% if model.booking %}
{% include "fragments/booking.html" %}
{% endif %}
{% endblock %}
|
- Linhas 15–34: seleção de um médico e de um dia: um formulário GET (Exemplo 17), que simplesmente recarrega a página com os parâmetros [doctorId] and [day] na URL. O campo [<input type="date">] exibe seus valores no formato [yyyy-mm-dd], qualquer que seja o idioma em que o navegador o apresente;
- linhas 37–42: a mensagem informativa para um paciente que já tem uma consulta futura;
- Linhas 61–95: uma entrada da agenda. Há três estados possíveis: disponível, reservado com o nome do paciente (em azul se for a consulta do paciente conectado) ou reservado sem o nome (“Reservado”). Os botões exibidos são determinados pela ação. “Reservar” é um simples link: ele reabre esta página com a janela de reserva daquele horário. “Cancelar” modifica dados: é um formulário POST, com seu pedido de confirmação (exemplo 21);
- linhas 108–110: a janela de reserva, somente se a ação a tiver preparado.
11.17.2.3. templates/persons/list.html
| {# =========================================================================
templates/persons/list.html - a lista dos médicos OU dos clientes (ADMIN).
Uma única view para ambos: os rótulos específicos de cada um chegam em
model.keys (veja controllers/doctors.py / controllers/clients.py).
========================================================================= #}
{% extends "layout.html" %}
{% block content %}
<div class="d-flex justify-content-between align-items-center mb-3">
<h4 class="mb-0">{{ t(model.keys.title) }}</h4>
<a class="btn btn-primary" href="{{ model.add_url }}">{{ t(model.keys.add) }}</a>
</div>
<div class="card p-3">
{% if model.persons %}
<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>
{% for person in model.persons %}
<tr>
<td>{{ person.title }}</td>
<td>{{ person.first_name }}</td>
<td>{{ person.last_name }}</td>
<td><code>{{ person.login }}</code></td>
<td class="text-end">
<div class="d-inline-flex gap-2">
<a class="btn btn-sm btn-outline-primary" href="{{ person.edit_url }}">{{ t("PERSONS.EDIT") }}</a>
{# data-confirmation: um diálogo de confirmação será aberto
antes do envio do formulário (veja static/js/app.js) #}
<form method="post" action="{{ person.delete_url }}" class="m-0"
data-confirmation="{{ t(model.keys.confirm_delete) }}">
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
<button type="submit" class="btn btn-sm btn-outline-danger">{{ t("PERSONS.DELETE") }}</button>
</form>
</div>
</td>
</tr>
{% endfor %}
</tbody>
</table>
{% else %}
<p class="text-muted mb-0">{{ t(model.keys.empty) }}</p>
{% endif %}
</div>
{% endblock %}
|
Uma única view para as duas listas, de médicos e de clientes: os rótulos específicos de cada uma aparecem em [model.keys]; [t(model.keys.title)] renderiza uma chave que é ela própria uma variável. Cada linha tem um link “Editar” e um formulário “Excluir”, que exige confirmação.
| {# =========================================================================
templates/persons/form.html - criação OU edição de um
médico ou de um cliente (ADMIN). model.creating distingue os dois casos.
Quando a entrada é recusada (campo vazio, login já em uso...), a action
devolve ESTA view com:
- os valores já digitados (model.values);
- os campos com problema contornados em vermelho (classe Bootstrap "is-invalid");
- sob um campo recusado pela validação, sua mensagem;
- a mensagem de erro da página, exibida NO PÉ da página pelo
layout (veja fragments/errors.html).
========================================================================= #}
{% extends "layout.html" %}
{% block content %}
{% set state = model.state %}
<div class="row justify-content-center">
<div class="col-md-8 col-lg-6">
<div class="card p-4">
<h5 class="card-title mb-3">{{ t(model.page_title) }}</h5>
{# novalidate: deixamos o SERVIDOR validar (ele é a autoridade);
as verificações do navegador (required...) são apenas uma conveniência,
que um usuário sempre pode contornar #}
<form method="post" action="{{ model.action }}" novalidate>
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
{% if not model.creating %}
<input type="hidden" name="version" value="{{ model.values.version }}">
{% endif %}
{# título, nome, sobrenome: fragmento comum a três formulários #}
{% include "fragments/person_fields.html" %}
<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 {{ state.invalid_class('login') }}" value="{{ model.values.login }}">
{% if state.error_of("login") %}
<div class="invalid-feedback">{{ t(state.error_of("login")) }}</div>
{% else %}
<div class="form-text">{{ t("PERSONS.LOGIN_HELP_CREATE" if model.creating else "PERSONS.LOGIN_HELP_EDIT") }}</div>
{% endif %}
</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 {{ state.invalid_class('password') }}">
{% if state.error_of("password") %}
<div class="invalid-feedback">{{ t(state.error_of("password")) }}</div>
{% else %}
<div class="form-text">{{ t("PERSONS.PASSWORD_HELP_CREATE" if model.creating else "PERSONS.PASSWORD_HELP_EDIT") }}</div>
{% endif %}
</div>
<div class="d-flex gap-2">
<button type="submit" class="btn btn-primary">{{ t("PERSONS.SAVE") }}</button>
<a class="btn btn-secondary" href="{{ model.list_url }}">{{ t("PERSONS.BACK") }}</a>
</div>
</form>
</div>
</div>
</div>
{% endblock %}
|
- linha 25: o endereço de envio é fornecido pela ação: [/doctors/add], [/clients/3/edit]...;
- linhas 27–29: na atualização, a versão do registro é armazenada em um campo oculto (bloqueio otimista);
- linha 32: os campos de identidade;
- linhas 38–44: o login, opcional, com uma dica que depende de o registro estar sendo criado ou editado ([t("..." if model.creating else "...")]);
- linhas 50-50: a senha nunca é preenchida previamente; nunca é reenviada ao navegador. [autocomplete="new-password"] impede que o navegador sugira aqui a senha do administrador.
11.17.2.5. templates/registration.html
| {# =========================================================================
templates/registration.html - "Create a patient account" (página pública,
veja controllers/registration.py). Mesmos campos de identidade do formulário
do ADMIN (fragmento person_fields.html), mas o login e a
senha são obrigatórios, com confirmação.
Sem captcha AQUI: só se chega a esta página depois de digitar
o da página de autenticação (botão "Create a patient account").
t(key, min=...): a mensagem cuja chave é o valor de [key], com o
parâmetro {min} (veja web/translator.py).
========================================================================= #}
{% extends "layout.html" %}
{% block content %}
{% set state = model.state %}
<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>
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
{% include "fragments/person_fields.html" %}
<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 {{ state.invalid_class('login') }}" value="{{ model.values.login }}">
{% if state.error_of("login") %}
<div class="invalid-feedback">{{ t(state.error_of("login")) }}</div>
{% else %}
<div class="form-text">{{ t("REGISTRATION.LOGIN_HELP") }}</div>
{% endif %}
</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 {{ state.invalid_class('password') }}">
{% if state.error_of("password") %}
<div class="invalid-feedback">{{ t(state.error_of("password"), min=model.password_min) }}</div>
{% else %}
<div class="form-text">{{ t("REGISTRATION.PASSWORD_HELP", min=model.password_min) }}</div>
{% endif %}
</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 {{ state.invalid_class('confirmation') }}">
{% if state.error_of("confirmation") %}
<div class="invalid-feedback">{{ t(state.error_of("confirmation")) }}</div>
{% endif %}
</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>
{% endblock %}
|
O formulário de criação de conta de paciente: os campos de dados pessoais, seguidos do nome de usuário, da senha e da confirmação da senha, são obrigatórios. A mensagem que indica que uma senha é curta demais tem um parâmetro com o tamanho mínimo: [t(state.error_of("password"), min=model.password_min)]. Não há CAPTCHA aqui: só é possível acessar esta página depois de informar o CAPTCHA da página de login.
11.17.2.6. templates/area.html
| {# =========================================================================
templates/area.html - "My area": a página inicial do paciente
(papel USER), exibida logo após o login.
- duas opções: [Manage my account] e [View a schedule];
- sua consulta futura, se tiver uma, com o meio de cancelá-la.
========================================================================= #}
{% extends "layout.html" %}
{% block content %}
<h4 class="mb-3">{{ t("AREA.HELLO", name=model.patient) }}</h4>
<div class="row g-3 mb-4">
<div class="col-sm-6">
<a class="card p-4 h-100 text-decoration-none option-card" href="/my-account">
<h5 class="mb-1">{{ t("AREA.MANAGE_ACCOUNT") }}</h5>
<span class="text-muted">{{ t("AREA.MANAGE_ACCOUNT_HELP") }}</span>
</a>
</div>
<div class="col-sm-6">
<a class="card p-4 h-100 text-decoration-none option-card" href="/schedule">
<h5 class="mb-1">{{ t("AREA.VIEW_SCHEDULE") }}</h5>
<span class="text-muted">{{ t("AREA.VIEW_SCHEDULE_HELP") }}</span>
</a>
</div>
</div>
<div class="card p-3">
<h5>{{ t("AREA.MY_APPOINTMENT") }}</h5>
{# normalmente só uma (regra "uma consulta futura por vez"),
mas a página pode exibir várias. loop.last: último elemento?
O bloco else de um laço for: a lista está vazia #}
{% for appointment in model.appointments %}
<div class="d-flex flex-wrap justify-content-between align-items-center gap-2 py-2{{ '' if loop.last else ' border-bottom' }}">
<div>
<div class="fw-semibold">{{ appointment.day }}, {{ appointment.time }}</div>
<div class="text-muted">
<span>{{ appointment.doctor }}</span> -
<a href="{{ appointment.schedule_url }}">{{ 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="csrf_token" value="{{ csrf_token() }}">
<input type="hidden" name="appointmentId" value="{{ appointment.id }}">
<button type="submit" class="btn btn-outline-danger">{{ t("AREA.CANCEL_APPOINTMENT") }}</button>
</form>
</div>
{% else %}
<p class="text-muted mb-0">{{ t("AREA.NO_APPOINTMENT") }}</p>
{% endfor %}
</div>
{% endblock %}
|
O painel do paciente: duas grandes abas (“Gerenciar minha conta”, “Ver uma agenda”) e suas consultas futuras. O laço [for ... else] (exemplo 14) exibe uma mensagem se a lista estiver vazia; [loop.last] remove a borda abaixo da última consulta. A página pode exibir várias consultas, mesmo que a regra de gerenciamento permita apenas uma.
11.17.2.7. templates/account.html
| {# =========================================================================
templates/account.html - "Manage my account" (papel USER).
Dois formulários independentes na mesma página:
1. a edição (identidade, login, nova senha opcional);
2. a exclusão da conta - que também cancela suas consultas.
Ambos exigem a senha ATUAL.
========================================================================= #}
{% extends "layout.html" %}
{% block content %}
{% set state = model.state %}
<div class="row justify-content-center">
<div class="col-md-8 col-lg-6">
{# 1. ediçã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="csrf_token" value="{{ csrf_token() }}">
<input type="hidden" name="version" value="{{ model.values.version }}">
{% include "fragments/person_fields.html" %}
<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 {{ state.invalid_class('login') }}" value="{{ model.values.login }}">
{% if state.error_of("login") %}
<div class="invalid-feedback">{{ t(state.error_of("login")) }}</div>
{% endif %}
</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 {{ state.invalid_class('password') }}">
{% if state.error_of("password") %}
<div class="invalid-feedback">{{ t(state.error_of("password"), min=model.password_min) }}</div>
{% else %}
<div class="form-text">{{ t("PERSONS.PASSWORD_HELP_EDIT") }}</div>
{% endif %}
</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 {{ state.invalid_class('confirmation') }}">
{% if state.error_of("confirmation") %}
<div class="invalid-feedback">{{ t(state.error_of("confirmation")) }}</div>
{% endif %}
</div>
</div>
<div class="mb-4">
<label class="form-label" for="current_password">{{ t("MY_ACCOUNT.CURRENT_PASSWORD_LABEL") }}</label>
<input id="current_password" name="current_password" type="password" maxlength="72"
autocomplete="current-password" required
class="form-control {{ state.invalid_class('current_password') }}">
{% if state.error_of("current_password") %}
<div class="invalid-feedback">{{ t(state.error_of("current_password")) }}</div>
{% else %}
<div class="form-text">{{ t("MY_ACCOUNT.CURRENT_PASSWORD_HELP") }}</div>
{% endif %}
</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') }}">
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
<div class="flex-grow-1">
<label class="form-label" for="delete_password">{{ t("MY_ACCOUNT.CURRENT_PASSWORD_LABEL") }}</label>
<input id="delete_password" name="delete_password" 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>
{% endblock %}
|
Dois formulários independentes na mesma página: modificação da conta (linhas 19–73) e exclusão da conta (linhas 80–89), confirmada pela janela de confirmação. Ambos exigem a senha atual, digitada em dois campos separados (um formulário envia apenas os seus próprios campos).
11.17.2.8. templates/error.html
| {# =========================================================================
templates/error.html - a página de erro (400, 403, 404, 500...),
construída por web/errors.py.
========================================================================= #}
{% extends "layout.html" %}
{% block content %}
<div class="row justify-content-center">
<div class="col-md-8 col-lg-6">
<div class="card p-4 text-center">
<h1 class="display-4 text-danger">{{ model.code }}</h1>
<p class="lead">{{ t(model.message) }}</p>
<div><a class="btn btn-primary" href="/">{{ t("ERROR_PAGE.BACK") }}</a></div>
</div>
</div>
</div>
{% endblock %}
|
A página de erro: o código, exibido com destaque, e a mensagem traduzida. Ela estende o template: mesmo em caso de erro, o usuário mantém sua barra de navegação e pode trocar de idioma.
11.18. Os dicionários
Os textos da interface estão em dois dicionários JSON, [i18n/fr.json] e [i18n/en.json], que o tradutor lê na inicialização. São os mesmos arquivos das versões [NestJS], [ASP.NET Core MVC] e [Spring MVC] da aplicação.
11.18.1. i18n/fr.json
| {
"APP": {
"TITLE": "RdvMedecins",
"LOGOUT": "Se déconnecter",
"MENU_SCHEDULE": "Agenda",
"MENU_DOCTORS": "Médecins",
"MENU_PATIENTS": "Clients",
"MENU_MY_AREA": "Mon espace"
},
"LOGIN": {
"TITLE": "Connexion",
"LOGIN_LABEL": "Login",
"PASSWORD_LABEL": "Mot de passe",
"SUBMIT": "Se connecter",
"ERROR": "Login ou mot de passe incorrect.",
"DEMO_ACCOUNTS": "Comptes de démonstration (mot de passe = login) :",
"DEMO_ADMIN": "rôle ADMIN : rendez-vous + gestion des médecins et des clients",
"DEMO_DOCTOR": "rôle DOCTOR : prise et annulation de rendez-vous",
"DEMO_USER": "rôle USER (patients) : réservation pour eux-mêmes, gestion de leur compte",
"CREATE_ACCOUNT": "Créer un compte client",
"CREATE_ACCOUNT_HELP": "Pour créer un compte, recopiez d'abord les caractères de l'image."
},
"DOCTOR_DAY_PICKER": {
"DOCTOR_LABEL": "Médecin",
"CHOOSE_DOCTOR": "-- choisir un médecin --",
"DAY_LABEL": "Jour",
"VIEW_SCHEDULE": "Voir l'agenda"
},
"SCHEDULE": {
"PAGE_TITLE": "Agenda",
"TITLE_PREFIX": "Agenda du",
"COLUMN_SLOT": "Créneau",
"COLUMN_STATUS": "Statut",
"FREE": "Libre",
"BOOK": "Réserver",
"CANCEL_APPOINTMENT": "Annuler",
"CANCEL_CONFIRM": "Annuler ce rendez-vous ?",
"EMPTY_STATE": "Choisissez un médecin et un jour, puis cliquez sur « Voir l'agenda ».",
"NO_SLOTS": "Ce médecin n'a aucun créneau horaire.",
"BOOKED": "Rendez-vous enregistré.",
"CANCELLED": "Rendez-vous annulé.",
"BOOKED_BY_OTHER": "Réservé",
"ALREADY_BOOKED_INFO": "Vous avez déjà un rendez-vous à venir : annulez-le pour en prendre un autre."
},
"BOOKING_DIALOG": {
"TITLE": "Réserver ce créneau",
"CLOSE_ARIA": "Fermer",
"SLOT": "Créneau de {time}",
"PATIENT_LABEL": "Patient",
"CHOOSE_PATIENT": "-- choisir un patient --",
"CANCEL": "Annuler",
"CONFIRM": "Confirmer"
},
"PERSONS": {
"COLUMN_TITLE": "Titre",
"COLUMN_FIRSTNAME": "Prénom",
"COLUMN_LASTNAME": "Nom",
"COLUMN_LOGIN": "Login",
"EDIT": "Modifier",
"DELETE": "Supprimer",
"SAVE": "Enregistrer",
"BACK": "Retour à la liste",
"TITLE_LABEL": "Titre",
"FIRSTNAME_LABEL": "Prénom",
"LASTNAME_LABEL": "Nom",
"LOGIN_LABEL": "Login",
"PASSWORD_LABEL": "Mot de passe",
"LOGIN_HELP_CREATE": "Facultatif : par défaut, le nom en minuscules.",
"LOGIN_HELP_EDIT": "Laisser vide pour ne pas le changer.",
"PASSWORD_HELP_CREATE": "Facultatif : par défaut, identique au login.",
"PASSWORD_HELP_EDIT": "Laisser vide pour ne pas le changer.",
"ACCOUNT_SECTION": "Compte utilisateur"
},
"DOCTORS": {
"TITLE": "Médecins",
"ADD": "Ajouter un médecin",
"EDIT": "Modifier un médecin",
"EMPTY": "Aucun médecin.",
"DELETE_CONFIRM": "Supprimer ce médecin, ses créneaux horaires et son compte utilisateur ?",
"ADDED": "Le médecin {name} a été ajouté (login : {login}).",
"UPDATED": "Le médecin {name} a été modifié.",
"DELETED": "Le médecin {name} a été supprimé."
},
"CLIENTS": {
"TITLE": "Clients",
"ADD": "Ajouter un client",
"EDIT": "Modifier un client",
"EMPTY": "Aucun client.",
"DELETE_CONFIRM": "Supprimer ce client, son compte utilisateur et tous ses rendez-vous ?",
"ADDED": "Le client {name} a été ajouté (login : {login}).",
"UPDATED": "Le client {name} a été modifié.",
"DELETED": "Le client {name} a été supprimé."
},
"ERROR_PAGE": {
"TITLE": "Erreur",
"BACK": "Retour à l'accueil"
},
"ERRORS": {
"LOGIN_TAKEN": "Ce login est déjà utilisé par un autre compte.",
"DOCTOR_ALREADY_EXISTS": "Un médecin portant ce prénom et ce nom existe déjà.",
"PATIENT_ALREADY_EXISTS": "Un client portant ce prénom et ce nom existe déjà.",
"DOCTOR_HAS_APPOINTMENTS": "Ce médecin a des rendez-vous : annulez-les avant de le supprimer.",
"SLOT_ALREADY_BOOKED": "Ce créneau vient d'être réservé par quelqu'un d'autre.",
"CONCURRENT_UPDATE": "Cette fiche a été modifiée entre-temps par un autre utilisateur. Revenez à la liste et rouvrez-la avant de recommencer.",
"DOCTOR_NOT_FOUND": "Ce médecin n'existe pas (ou plus).",
"PATIENT_NOT_FOUND": "Ce client n'existe pas (ou plus).",
"SLOT_NOT_FOUND": "Ce créneau n'existe pas (ou plus).",
"APPOINTMENT_NOT_FOUND": "Ce rendez-vous n'existe pas (ou plus).",
"INVALID_DATE": "La date demandée n'est pas valide.",
"CHOOSE_PATIENT": "Choisissez un patient.",
"INVALID_FORM": "Le formulaire contient des erreurs.",
"INVALID_TITLE": "Choisissez un titre dans la liste.",
"FIRSTNAME_REQUIRED": "Le prénom est obligatoire.",
"FIRSTNAME_TOO_LONG": "Le prénom ne doit pas dépasser 20 caractères.",
"LASTNAME_REQUIRED": "Le nom est obligatoire.",
"LASTNAME_TOO_LONG": "Le nom ne doit pas dépasser 20 caractères.",
"INVALID_LOGIN": "30 caractères au plus : lettres minuscules non accentuées, chiffres, point, tiret, souligné.",
"PASSWORD_TOO_LONG": "Le mot de passe ne doit pas dépasser 72 caractères.",
"SESSION_EXPIRED": "Votre session a expiré : reconnectez-vous.",
"BAD_REQUEST": "La requête est invalide.",
"FORBIDDEN": "Votre rôle ne vous permet pas d'accéder à cette page.",
"NOT_FOUND": "Cette page n'existe pas.",
"SERVER_ERROR": "Une erreur inattendue s'est produite. Réessayez plus tard.",
"TOO_MANY_ATTEMPTS": "Trop de tentatives infructueuses. Réessayez dans {minutes} minute(s).",
"WRONG_CAPTCHA": "Les caractères recopiés ne correspondent pas à l'image. Une nouvelle image vous est proposée.",
"TOO_MANY_ACCOUNTS": "Trop de comptes ont été créés depuis votre connexion. Réessayez dans {minutes} minute(s).",
"LOGIN_REQUIRED": "Le login est obligatoire.",
"PASSWORD_REQUIRED": "Le mot de passe est obligatoire.",
"PASSWORD_TOO_SHORT": "Le mot de passe doit comporter au moins {min} caractères.",
"CONFIRMATION_REQUIRED": "Confirmez le mot de passe.",
"PASSWORDS_DIFFER": "La confirmation ne correspond pas au mot de passe.",
"CURRENT_PASSWORD_REQUIRED": "Saisissez votre mot de passe actuel.",
"WRONG_CURRENT_PASSWORD": "Mot de passe actuel incorrect.",
"PAST_DATE": "On ne peut pas prendre de rendez-vous à une date passée.",
"PATIENT_HAS_UPCOMING_APPOINTMENT": "Ce patient a déjà un rendez-vous à venir : il faut l'annuler avant d'en prendre un autre.",
"CAPTCHA_BEFORE_ACCOUNT": "Pour créer un compte, recopiez d'abord correctement les caractères de l'image, puis cliquez sur « Créer un compte client »."
},
"CAPTCHA": {
"LABEL": "Recopiez les caractères de l'image",
"IMAGE_ALT": "Image de vérification anti-robots",
"NEW_IMAGE": "Autre image",
"HELP": "Majuscules ou minuscules, peu importe."
},
"REGISTRATION": {
"TITLE": "Créer un compte client",
"INTRO": "Ce compte vous permettra de prendre vous-même vos rendez-vous.",
"LOGIN_HELP": "Lettres minuscules non accentuées, chiffres, point, tiret, souligné.",
"PASSWORD_HELP": "Au moins {min} caractères.",
"SUBMIT": "Créer mon compte",
"BACK_TO_LOGIN": "Retour à la connexion",
"DONE": "Votre compte a été créé. Vous pouvez vous connecter avec le login {login}."
},
"ACCOUNT": {
"CONFIRMATION_LABEL": "Confirmation du mot de passe"
},
"AREA": {
"TITLE": "Mon espace",
"HELLO": "Bonjour {name}",
"MANAGE_ACCOUNT": "Gérer mon compte",
"MANAGE_ACCOUNT_HELP": "Modifier mes informations, mon mot de passe, ou supprimer mon compte.",
"VIEW_SCHEDULE": "Voir un agenda",
"VIEW_SCHEDULE_HELP": "Consulter l'agenda d'un médecin et réserver un créneau.",
"MY_APPOINTMENT": "Mon rendez-vous",
"SEE_IN_SCHEDULE": "voir dans l'agenda",
"CANCEL_APPOINTMENT": "Annuler ce rendez-vous",
"NO_APPOINTMENT": "Vous n'avez aucun rendez-vous à venir."
},
"MY_ACCOUNT": {
"TITLE": "Gérer mon compte",
"NEW_PASSWORD_LABEL": "Nouveau mot de passe",
"CURRENT_PASSWORD_LABEL": "Mot de passe actuel",
"CURRENT_PASSWORD_HELP": "Obligatoire pour enregistrer une modification.",
"BACK": "Retour à mon espace",
"DELETE_TITLE": "Supprimer mon compte",
"DELETE_HELP": "Votre compte sera définitivement supprimé, ainsi que tous vos rendez-vous.",
"DELETE_CONFIRM": "Supprimer définitivement votre compte ? Votre rendez-vous éventuel sera annulé.",
"DELETE_SUBMIT": "Supprimer mon compte",
"UPDATED": "Votre compte a été modifié.",
"DELETED": "Votre compte a été supprimé."
},
"CONFIRMATION": {
"TITLE": "Confirmation",
"NO": "Non, revenir",
"YES": "Oui, confirmer"
}
}
|
As chaves são agrupadas por página ou por tema: [APP] (a barra de navegação), [LOGIN], [SCHEDULE], [BOOKING_DIALOG] (a janela de reserva), [PERSONS], [DOCTORS], [CLIENTS], [ERRORS] (todas as mensagens de erro, inclusive as dos validadores de formulário e as da camada de negócio)... Os parâmetros das mensagens são escritos como [{name}], [{login}], [{minutes}], [{min}], [{time}].
11.18.2. i18n/en.json
O dicionário em inglês tem exatamente as mesmas chaves. Eis algumas linhas para comparação:
| {
"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."
|
Mais um dicionário bastaria para um terceiro idioma: seria preciso acrescentá-lo à lista do tradutor ([LANGUAGES]) e adicionar um botão à barra de navegação.
11.19. Arquivos estáticos
A pasta [static] contém a folha de estilos da aplicação, seu script e o [Bootstrap] (pasta [lib/bootstrap]: a folha de estilos [bootstrap.min.css] da distribuição oficial e sua licença; a aplicação não usa o [JavaScript] do [Bootstrap]).
11.19.1. static/css/styles.css
| /* =========================================================================
static/css/styles.css - alguns ajustes sobre o Bootstrap
(os mesmos das versões ASP.NET Core MVC e Spring MVC desta aplicação).
========================================================================= */
body {
background-color: #f5f7fa;
}
.free-slot:hover {
background-color: #e9f7ef;
}
/* -------------------------------------------------------------------------
.error-zone: as mensagens de erro, na parte inferior da página, sobre um fundo rosa claro
(veja templates/fragments/errors.html).
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;
}
|
Algumas regras adicionais para o [Bootstrap], as mesmas das versões anteriores da aplicação. A área de erros (linhas 23–32) é fixa ([position: sticky], [bottom: 1rem]): se a página for mais alta que a janela (uma agenda com doze horários), ela permanece visível na parte inferior da janela em vez de desaparecer abaixo da dobra. [z-index: 1060] a coloca acima do fundo cinza das janelas modais.
11.19.2. static/js/app.js
| // =========================================================================
// static/js/app.js - o ÚNICO JavaScript da aplicação.
// -------------------------------------------------------------------------
// A aplicação inteira funciona sem JavaScript. Este script adiciona uma
// comodidade: antes de enviar um formulário que carrega o atributo
// data-confirmation="...", um diálogo modal pergunta "Are you sure?"
// (o próprio diálogo está na página: templates/fragments/confirmation.html).
// 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 (Sim / Não / X 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
// (caso contrário o foco iria para a página acinzentada, atrás)
modal.addEventListener('keydown', (event) => {
if (event.key === 'Escape') {
close();
} else if (event.key === 'Tab') {
const buttons = [...modal.querySelectorAll('button')];
const first = buttons[0];
const last = buttons[buttons.length - 1];
if (event.shiftKey && document.activeElement === first) {
event.preventDefault();
last.focus();
} else if (!event.shiftKey && document.activeElement === last) {
event.preventDefault();
first.focus();
}
}
});
})();
|
O script do Exemplo 21, completo:
- linhas 16–18: o script não faz nada se a página não tiver uma janela de confirmação;
- linhas 26–34: ao abrir, a mensagem é colocada por meio de [textContent], e não de [innerHTML]: ela é exibida como texto e nunca é interpretada como HTML. O foco passa para o botão “Não”: pressionar Enter acidentalmente não exclui nada;
- linhas 37–41: ao fechar, o foco volta ao elemento que o tinha anteriormente (o botão “Excluir”), o que é importante para a navegação pelo teclado;
- linhas 54–65: cliques dentro da janela. [closest('[data-action]')] procura o elemento com o atributo [data-action], a partir do elemento clicado e subindo pelos seus elementos pais: um clique em um ícone dentro de um botão é assim atribuído ao botão. O operador [?.] retorna [undefined] em vez de gerar um erro se nenhum elemento for encontrado. Um clique no fundo acinzentado fecha a janela;
- linhas 71–83: comportamento do teclado: Esc fecha a janela; Tab e Shift-Tab alternam o foco entre os botões da janela, sem passar para a página acinzentada ao fundo.