10. Estudo de caso: o cliente React da aplicação RdvMedecins
10.1. O problema
A aplicação [RdvMedecins] permite agendar consultas em um consultório médico. O curso de [NestJS] a escreveu como uma aplicação HTML, em que o servidor gerava as páginas. Aqui, escrevemos a aplicação cliente [React]: as MESMAS páginas, geradas no navegador a partir dos dados JSON do servidor descrito no capítulo “O servidor RdvMedecins, uma caixa-preta”.
O cliente deve oferecer tudo o que a aplicação HTML oferecia:
- uma página de login, protegida por um CAPTCHA, com a opção de criar uma conta de paciente;
- a agenda de um médico para um dia determinado, com reserva de consultas (janela de seleção de paciente) e cancelamento;
- para o administrador, o gerenciamento de médicos e clientes (listar, adicionar, editar, excluir);
- para o paciente, um painel pessoal (mostrando as consultas futuras, que ele pode cancelar) e o gerenciamento da conta;
- dois idiomas: francês e inglês;
- URLs únicas ([/schedule?doctorId=1&day=...]), que podem ser recarregadas, adicionadas aos favoritos e percorridas com os botões Voltar/Avançar do navegador.
10.2. Instalação e execução
O servidor JSON deve estar instalado e em execução (veja o capítulo “O servidor RdvMedecins, uma caixa-preta”). Para usar o cliente em um navegador, você não precisa do modo de teste do CAPTCHA: pode deixar o campo [CAPTCHA_TEST] em branco no arquivo [.env] do servidor.
Em uma janela de console aberta na pasta [rdvmedecins-react]:
depois abra http://localhost:5173 em um navegador. As contas de demonstração são listadas na página de login (senha = login).
Os exemplos também usam a porta 5173: primeiro, pare o exemplo em execução ([Ctrl-C]). Você também pode iniciar o cliente em outra porta: [npm start -- --port 5174].
10.3. Usando a aplicação
10.3.1. A página de login

Uma senha incorreta: a mensagem aparece na parte inferior da página, e uma nova imagem é exibida (cada imagem só pode ser usada uma vez):

10.3.2. A agenda, vista pelo administrador e pelos médicos
Autenticado como [admin], você é levado à agenda:

Selecione um médico e um dia e clique em “View schedule”. A URL passa a ser [/schedule?doctorId=1&day=2026-10-05]:

“Book” abre a janela de reserva. A URL passa a ser [/schedule?doctorId=1&day=2026-10-05&book=3]: recarregar a página (F5) reabre a mesma janela.

A consulta é salva:

“Cancel” pede confirmação:

Um médico é levado diretamente à SUA PRÓPRIA agenda do dia:

10.3.3. O portal do paciente
Um paciente ([martin]) acessa “My area”:

Em uma agenda, ele vê “Booked” junto aos horários de consulta de outros pacientes:

Ele marca uma consulta para si mesmo sem selecionar um paciente:

Sua consulta aparece sob o seu nome; o botão “Book” não está mais disponível (apenas uma consulta futura), e uma mensagem explica o motivo:

Seu painel mostra isto:

“Manage my account”: qualquer alteração exige a senha atual; os erros vêm do servidor:

Se ele digitar o endereço /doctors, que é reservado ao administrador:

10.3.4. Gerenciamento de médicos e clientes

Um formulário preenchido incorretamente:

Uma inclusão bem-sucedida:

Um homônimo:

O pedido de remoção de um médico que tem consultas é negado:

10.3.5. Criação de uma conta
Na página de login, digite o CAPTCHA e clique em “Create a patient account”. O formulário foi preenchido incorretamente e foi rejeitado pelo servidor:

Depois que a conta é criada, volte à página de login; os campos de login já vêm preenchidos:

10.3.6. Em francês
Os botões FR / EN traduzem a página na hora, sem fazer nenhuma requisição ao servidor; o título da aba do navegador também é traduzido:

10.3.7. Sessão expirada, endereço desconhecido
Se o token expira (ou se o cookie é apagado), a requisição seguinte recebe uma resposta 401; o cliente é redirecionado para a página de login:

Um endereço desconhecido:

10.4. Arquitetura do cliente
| rdvmedecins-react/
├── package.json, vite.config.ts, tsconfig.json
├── index.html THE page of the application
├── public/favicon.svg the tab icon
└── src/
├── main.tsx the startup
├── router.ts the router, the expired session, the flash messages
├── routes.tsx the pages and their access rights
├── guards.ts the router guards
├── styles.css
├── formatting.ts the formatting
├── api/ the API access layer
├── i18n/ the languages
├── stores/ session, messages, confirmation (Zustand)
├── hooks/ form submission, the captcha
├── components/ the layout and the reusable components
└── pages/ the pages
|

A tabela a seguir compara a aplicação HTML do curso [NestJS] com este cliente:
Aplicação HTML (NestJS) | Cliente React |
O servidor gera cada página ([res.render]) | O servidor retorna JSON; os componentes de [src/pages/] geram as páginas |
[views/layout.hbs] e suas views parciais | [Layout.tsx] e os componentes de [src/components/] |
as rotas do controller ([@Controller('schedule')]) | rotas do cliente ([routes.tsx]); o servidor tem apenas rotas /api/... |
[JwtAuthGuard] e [RolesGuard] redirecionam para /login ou para uma página 403 | guards do roteador; o servidor mantém seus próprios guards, que retornam 401 ou 403 |
mensagem flash em um cookie | mensagem flash em um store, [useMessages] |
dicionários lidos pelo servidor, helper [{{t}}] | dicionários no cliente, [i18next]; o servidor retorna apenas chaves |
idioma armazenado em um cookie | idioma armazenado no [localStorage] |
formulário rejeitado: o servidor recarrega a página | formulário rejeitado: resposta 400/409; o cliente exibe os erros abaixo dos campos |
Janela de confirmação: um pequeno script, [public/js/app.js] | um store e um componente, [ConfirmDialog] |
A aplicação funciona sem JavaScript | A aplicação É JavaScript |
Os clientes [Vue.js] e [Angular] das lições anteriores têm exatamente a mesma estrutura: os "stores" do [Pinia] e os serviços do [Angular] são aqui stores [Zustand]; os "composables" são os hooks, e as views são as páginas.
Todos os arquivos do cliente estão listados abaixo. Eles são amplamente comentados; seus comentários fazem parte do curso.
10.4.1. Configuração do projeto
10.4.1.1. package.json
| {
"name": "rdvmedecins-react",
"private": true,
"version": "1.0.0",
"description": "React client of the medical appointment booking application [RdvMedecins] - client of the JSON server [rdvmedecins-nestjs-json]",
"type": "module",
"scripts": {
"start": "vite",
"build": "tsc --noEmit && vite build",
"preview": "vite preview"
},
"dependencies": {
"@tanstack/react-query": "^5.104.0",
"bootstrap": "^5.3.8",
"i18next": "^26.4.2",
"react": "^19.3.0",
"react-dom": "^19.3.0",
"react-i18next": "^17.0.15",
"react-router": "^8.4.0",
"zustand": "^5.0.15"
},
"devDependencies": {
"@types/react": "^19.2.18",
"@types/react-dom": "^19.2.7",
"@vitejs/plugin-react": "^6.1.1",
"typescript": "~6.0.2",
"vite": "^8.3.0"
}
}
|
- Linhas 8–10: [npm start] inicia o servidor de desenvolvimento; [npm run build] verifica os tipos ([tsc --noEmit], veja abaixo) E ENTÃO gera a versão de produção; [npm run preview] serve a versão compilada para testes;
- Linhas 12–21: as bibliotecas usadas pela aplicação: [React], [React Router], [TanStack Query], [Zustand], [i18next], [Bootstrap];
- Linhas 22–28: ferramentas de desenvolvimento: [Vite] e sua extensão para [React], [TypeScript] e os tipos do [React].
Não há biblioteca de formulários ([React Hook Form], exemplo 08): como no exemplo 25, todas as regras de validação das entradas são verificadas pelo servidor, e o cliente se limita a exibir os resultados.
10.4.1.2. vite.config.ts
| // =========================================================================
// vite.config.ts - a ferramenta de build do cliente
// -------------------------------------------------------------------------
// - npm start : o servidor de desenvolvimento (http://localhost:5173),
// que encaminha /api/... ao servidor JSON (porta 8080);
// - npm run build : a aplicação compilada, em dist/;
// - npm run preview: serve dist/ (com o mesmo proxy), para experimentar.
// =========================================================================
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
// o proxy: páginas e API têm assim a MESMA origem (localhost:5173); o
// cookie httpOnly do token trafega sem nenhuma configuração, e sem CORS
const proxy = { '/api': 'http://localhost:8080' };
export default defineConfig({
plugins: [react()],
server: { port: 5173, proxy },
preview: { port: 4173, proxy },
// em produção: o código das bibliotecas (React, React Router,
// i18next...) em UM arquivo separado, "libraries-XXXX.js". Ele raramente
// muda: o navegador o mantém em cache de uma versão para a seguinte.
build: {
rolldownOptions: {
output: { codeSplitting: { groups: [{ name: 'libraries', test: /node_modules/ }] } },
},
},
});
|
- Linha 15: o proxy do Exemplo 22: as requisições /api/... são encaminhadas para o servidor JSON;
- linha 19: o servidor de desenvolvimento;
- linha 20: o servidor de [npm run preview], com o mesmo proxy;
- linhas 24–28: em produção, o código das bibliotecas é armazenado em um arquivo separado (veja o capítulo “Implantação”).
10.4.1.3. tsconfig.json
| {
"compilerOptions": {
"target": "ES2023",
"lib": ["ES2023", "DOM", "DOM.Iterable"],
"module": "ESNext",
"moduleResolution": "bundler",
"types": ["vite/client"],
"jsx": "react-jsx",
"strict": true,
"noUnusedLocals": true,
"noUnusedParameters": true,
"noFallthroughCasesInSwitch": true,
"noImplicitReturns": true,
"verbatimModuleSyntax": true,
"erasableSyntaxOnly": true,
"resolveJsonModule": true,
"skipLibCheck": true,
"noEmit": true
},
"include": ["src", "vite.config.ts"]
}
|
- linha 8: o JSX é compilado em chamadas a [jsx(...)], que são importadas automaticamente: não é necessário [import React] em cada arquivo;
- linha 9: o modo estrito do [TypeScript];
- linha 14: uma importação usada apenas para tipos é escrita como [import type]: ela desaparece durante a compilação;
- linha 15: só é permitida a sintaxe [TypeScript] que pode simplesmente ser APAGADA para obter [JavaScript] (sem [enum], sem parâmetros de propriedade): é isso que o [Vite] faz, e ele não verifica tipos;
- Linha 16: importação dos arquivos JSON (os dicionários);
- linha 18: [TypeScript] não gera nenhum arquivo: ele apenas VERIFICA ([tsc --noEmit]); [Vite] é quem compila.
10.4.2. Inicialização da aplicação
10.4.2.1. index.html
| <!doctype html>
<!--
index.html - A página da aplicação (Single Page Application).
O servidor nunca envia outra: todo o resto é construído no
navegador pelo React, em <div id="root">. lang e title são atualizados
pela aplicação conforme o idioma e a página exibida.
-->
<html lang="en">
<head>
<meta charset="utf-8">
<title>RdvMedecins</title>
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="icon" href="/favicon.svg" type="image/svg+xml">
</head>
<body>
<div id="root"></div>
<!-- sem JavaScript, uma aplicação React não consegue exibir nada: avisamos isso -->
<noscript>RdvMedecins requires JavaScript. / RdvMedecins a besoin de JavaScript.</noscript>
<script type="module" src="/src/main.tsx"></script>
</body>
</html>
|
- linha 16: o elemento no qual o [React] exibe a aplicação;
- linha 18: sem [JavaScript], uma aplicação [React] não consegue exibir nada: isso é informado;
- linha 19: o ponto de entrada da aplicação. Durante o desenvolvimento, o [Vite] compila [main.tsx] sob demanda; em produção, essa linha é substituída pelo arquivo compilado (veja o capítulo “Implantação”).
10.4.2.2. src/main.tsx
| // =========================================================================
// main.tsx - a inicialização da aplicação
// -------------------------------------------------------------------------
// - as folhas de estilo (Bootstrap, styles.css);
// - i18next (francês e inglês);
// - TanStack Query, que lê os dados do servidor: suas requisições que falham
// exibem sua mensagem no painel de erros, em UM só lugar
// (exceto as que declaram tratar o próprio erro:
// meta.errorHandled);
// - o roteador, que exibe a página do endereço atual.
// =========================================================================
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import { QueryCache, QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { RouterProvider } from 'react-router/dom';
import 'bootstrap/dist/css/bootstrap.min.css';
import './styles.css';
import './i18n/i18n';
import { useMessages } from './stores/messages';
import { router } from './router';
const queryClient = new QueryClient({
queryCache: new QueryCache({
onError: (error, query) => {
if (!query.meta?.errorHandled) {
useMessages.getState().showApiError(error);
}
},
}),
defaultOptions: {
queries: {
retry: false, // um erro é exibido imediatamente, sem nova tentativa
refetchOnWindowFocus: false, // nenhuma releitura ao voltar para a aba
},
},
});
createRoot(document.getElementById('root')!).render(
<StrictMode>
<QueryClientProvider client={queryClient}>
<RouterProvider router={router} />
</QueryClientProvider>
</StrictMode>,
);
|
- linhas 17–19: as folhas de estilo, seguidas da configuração do [i18next], que é executada uma única vez, quando o módulo é carregado;
- linhas 23–37: o cliente do [TanStack Query] (Exemplo 24), com dois ajustes:
- linhas 24–30: [onError] é chamado para CADA requisição que falha: sua mensagem de erro é exibida na área de erros, em um único local. Uma consulta que trata seu próprio erro o declara em seus metadados: [meta: { errorHandled: true }];
- linhas 33–34: por padrão, o [TanStack Query] repete três vezes uma requisição que falhou e recarrega os dados quando você volta à aba: aqui, um erro é exibido imediatamente, e os dados só mudam quando solicitados;
- linha 42: o roteador (construído em [router.ts]) exibe a página correspondente ao endereço atual.
10.4.2.3. src/router.ts
| // =========================================================================
// router.ts - o roteador da aplicação e o que depende dele
// -------------------------------------------------------------------------
// O roteador é criado aqui, fora de qualquer componente, para que dois
// mecanismos possam usá-lo:
// 1. a resposta 401 de uma requisição protegida (sessão expirada): o
// usuário é esquecido, a mensagem é preparada e vamos para a
// página de login (veja api/client.ts);
// 2. as mensagens "flash": ao final de CADA navegação, as mensagens
// da página anterior desaparecem, as deixadas para a próxima
// página aparecem (veja stores/messages.ts).
// =========================================================================
import { createBrowserRouter } from 'react-router';
import { routes } from './routes';
import { whenSessionExpired } from './api/client';
import { useSession } from './stores/session';
import { useMessages } from './stores/messages';
export const router = createBrowserRouter(routes);
// 1. a sessão expirada
whenSessionExpired(() => {
useSession.getState().forget();
useMessages.getState().flash('error', 'ERRORS.SESSION_EXPIRED');
router.navigate('/login');
});
// 2. subscribe: a função é chamada a cada mudança do estado do
// roteador. Uma navegação está CONCLUÍDA quando não está mais em andamento
// (idle) e o endereço mudou (cada endereço visitado tem uma chave única,
// location.key - inclusive quando só os parâmetros mudam: /schedule?...)
let locationKey = router.state.location.key;
router.subscribe((state) => {
if (state.navigation.state === 'idle' && state.location.key !== locationKey) {
locationKey = state.location.key;
useMessages.getState().newPage();
}
});
|
- linha 20: o roteador, no modo “data” (exemplo 17), é criado FORA de qualquer componente: um código que não é um componente pode, assim, usá-lo ([router.navigate]);
- linhas 23–27: o que fazer quando uma requisição protegida recebe uma resposta 401 (veja [api/client.ts]): esquecer o usuário, preparar a mensagem para a próxima página, ir para a página de login;
- linhas 33–39: [router.subscribe(function)]: a função é chamada sempre que o estado do roteador muda. Ao final de cada navegação, as mensagens da página anterior desaparecem e as mensagens “flash” aparecem (veja [stores/messages.ts]).
10.4.2.4. src/styles.css
| /* =========================================================================
styles.css - alguns ajustes sobre o Bootstrap
(extraídos de public/css/styles.css da aplicação HTML)
========================================================================= */
body {
background-color: #f5f7fa;
}
.free-slot:hover {
background-color: #e9f7ef;
}
/* -------------------------------------------------------------------------
.error-panel: as mensagens de erro, na parte inferior da página, sobre um fundo
rosa claro (veja components/ErrorPanel.tsx).
position: sticky + bottom: se a página for mais alta que a janela, o
painel permanece colado 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 dos diálogos modais.
pointer-events: none: o painel não contém nada clicável; se ele
se sobrepuser a um botão, o clique passa através dele.
------------------------------------------------------------------------- */
.error-panel {
position: sticky;
bottom: 1rem;
z-index: 1060;
pointer-events: none;
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 opções principais da página "Minha área" 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), inserida por dangerouslySetInnerHTML:
um estilo da folha global, como todos os outros */
.captcha-image svg {
display: block;
border: 1px solid #dee2e6;
border-radius: 0.375rem;
}
|
A folha de estilo da aplicação HTML, reproduzida quase literalmente. O único ponto a observar é a área de erros (linhas 24–35), posicionada na parte inferior da janela quando a página é alta.
10.4.3. A camada de acesso à API
10.4.3.1. src/api/types.ts
| // =========================================================================
// api/types.ts - os objetos JSON trocados com o servidor
// -------------------------------------------------------------------------
// A tradução, em interfaces TypeScript, da API descrita no capítulo
// "O servidor, uma caixa-preta". O compilador verifica assim que o cliente
// só usa campos que realmente existem.
// =========================================================================
export type Role = 'ADMIN' | 'DOCTOR' | 'USER';
// POST /api/auth/login, GET /api/auth/me, PUT /api/my-account
export interface User {
login: string;
name: string; // nome de exibição: "Marie PELISSIER"
role: Role;
}
// GET /api/captcha
export interface Captcha {
id: string;
svg: string;
}
// um título, um nome, um sobrenome
export interface Identity {
title: string;
firstName: string;
lastName: string;
}
// um médico ou um cliente: GET /api/doctors, GET /api/clients/:id...
export interface Person extends Identity {
id: number;
version: number; // bloqueio otimista: a ser reenviado com uma atualização
login?: string; // somente para o ADMIN
}
// o que é enviado para criar / atualizar uma pessoa (ADMIN)
export interface PersonData extends Identity {
login: string; // '' = valor padrão (criação) ou inalterado (atualização)
password: string; // idem
version?: number;
}
export interface Slot {
id: number;
startHour: number;
startMinute: number;
endHour: number;
endMinute: number;
}
// uma linha da agenda, com os DIREITOS do usuário logado
export interface ScheduleSlot extends Slot {
free: boolean;
patient: Identity | null; // null: livre, ou ocupado por outro paciente
mine: boolean; // a consulta do paciente logado
bookable: boolean;
appointmentId: number | null; // preenchido se o usuário puder cancelar
}
// GET /api/schedule?doctorId=...&day=...
export interface Schedule {
doctor: Person;
day: string; // "yyyy-MM-dd"
slots: ScheduleSlot[];
info: string | null; // chave de tradução (paciente que já tem uma consulta)
}
// GET /api/my-area
export interface MyArea {
patient: Identity;
appointments: { id: number; day: string; slot: Slot; doctor: Person }[];
}
// GET /api/my-account
export interface MyAccount extends Identity {
login: string;
version: number;
}
// PUT /api/my-account
export interface MyAccountUpdate extends Identity {
login: string;
password: string; // '' = inalterado
confirmation: string;
currentPassword: string;
version: number;
}
// POST /api/register
export interface Registration extends Identity {
login: string;
password: string;
confirmation: string;
}
|
Os objetos JSON da API, descritos no capítulo “O servidor RdvMedecins: uma caixa-preta”, traduzidos em interfaces [TypeScript]:
- linhas 25–29: um título, um nome, um sobrenome — o que médicos, clientes e pacientes têm em comum ao marcar consultas;
- linhas 32–36: um médico ou um cliente. [version]: o bloqueio otimista do servidor; uma modificação devolve a versão lida: se alguém modificou o registro nesse meio tempo, o servidor recusa ([ERRORS.CONCURRENT_UPDATE]);
- linhas 54–60: uma entrada da agenda. O servidor informa os DIREITOS do usuário logado: [bookable], [appointmentId] (preenchido se o usuário pode cancelar); o cliente não precisa recalculá-los;
- Linha 67: uma chave de tradução, para pacientes que já têm uma consulta.
10.4.3.2. src/api/api-error.ts
| // =========================================================================
// api/api-error.ts - UMA classe para todos os erros da API
// -------------------------------------------------------------------------
// Retirado de common/api-error.ts dos exemplos. Qualquer erro de uma requisição
// (resposta 4xx / 5xx do servidor, servidor inacessível, resposta de um proxy)
// vira um ApiError, que carrega a CHAVE de tradução da mensagem, seus
// parâmetros e o erro de cada campo de um formulário rejeitado.
// =========================================================================
export class ApiError extends Error {
readonly statusCode: number; // 0: o servidor não respondeu
readonly key: string; // chave de tradução: 'ERRORS.LOGIN_TAKEN'
readonly params: Record<string, string>;
readonly fields: Record<string, string>; // erro de cada campo
constructor(statusCode: number, key: string, params: Record<string, string> = {}, fields: Record<string, string> = {}) {
super(key);
this.name = 'ApiError';
this.statusCode = statusCode;
this.key = key;
this.params = params;
this.fields = fields;
}
}
// uma resposta de erro (4xx, 5xx) -> um ApiError
export async function fromResponse(response: Response): Promise<ApiError> {
let body: { key?: string; params?: Record<string, string>; fields?: Record<string, string> } = {};
try {
const json: unknown = await response.json();
if (typeof json === 'object' && json !== null) {
body = json;
}
} catch {
// não é JSON: não foi o nosso servidor que respondeu
}
return new ApiError(
response.status,
// sem chave: não foi o nosso servidor que respondeu, mas um proxy
// (Vite: 500 ou 502 sem corpo JSON; nginx: 502, 504...)
body.key ?? (response.status >= 500 ? 'ERRORS.SERVER_UNREACHABLE' : 'ERRORS.SERVER_ERROR'),
body.params,
body.fields,
);
}
|
A classe [ApiError] do Exemplo 24, sem alterações: QUALQUER erro de requisição se torna um [ApiError], que contém a chave de tradução da mensagem, seus parâmetros e o erro de cada campo em um formulário rejeitado.
10.4.3.3. src/api/client.ts
| // =========================================================================
// api/client.ts - TODAS as requisições à API passam por aqui
// -------------------------------------------------------------------------
// Retirado de common/api.ts dos exemplos, com uma novidade: o tratamento
// centralizado da resposta 401.
//
// Um 401 pode acontecer a qualquer momento: o token expirou (2 horas), a
// conta foi excluída, o servidor foi reiniciado com outra chave
// secreta... Em vez de tratar esse caso em cada componente, tratamos
// AQUI, uma única vez. Mas este arquivo não conhece nem o roteador nem as
// mensagens (não depende de nada): ele chama uma função que lhe foi dada
// na inicialização (whenSessionExpired, veja router.ts), que esquece
// o usuário e redireciona para a página de login.
//
// Algumas requisições tratam o próprio 401 (o login, GET
// /api/auth/me...): elas são "públicas" (veja rdvmedecins.api.ts).
// =========================================================================
import { fromResponse, ApiError } from './api-error';
// o que fazer quando o servidor responde 401 a uma requisição protegida
let sessionExpired: () => void = () => {};
export function whenSessionExpired(action: () => void): void {
sessionExpired = action;
}
export type Method = 'GET' | 'POST' | 'PUT' | 'DELETE';
// isPublic: true para as rotas que tratam o próprio 401
export async function request<T>(method: Method, url: string, body?: unknown, isPublic = false): Promise<T> {
let response: Response;
try {
response = await fetch(`/api${url}`, {
method,
headers: body === undefined ? {} : { 'Content-Type': 'application/json' },
body: body === undefined ? undefined : JSON.stringify(body),
});
} catch {
// sem resposta: rede fora do ar, servidor parado
throw new ApiError(0, 'ERRORS.SERVER_UNREACHABLE');
}
if (!response.ok) {
const error = await fromResponse(response);
if (error.statusCode === 401 && !isPublic) {
sessionExpired();
}
throw error;
}
return (await response.json()) as T;
}
|
A função [request] do Exemplo 24, com uma novidade: a resposta 401.
- Linhas 22–26: a função a ser chamada quando uma requisição protegida recebe uma resposta 401. Este arquivo não tem dependências (nem do roteador, nem das mensagens): [router.ts] atribui essa função a ele na inicialização. Isso evita uma dependência circular (o cliente importa o roteador, que importa as rotas, que importam as páginas, que importam o cliente...);
- linha 31: algumas requisições tratam seus próprios erros 401: o login (senha incorreta: 401), [GET /api/auth/me] (ninguém está logado: 401)...;
- Linhas 45–47: uma requisição protegida recebe um 401: a sessão expirou. Isso é sinalizado, ENTÃO a promise é rejeitada como em qualquer outro erro: o componente que aguarda a resposta não tem nenhuma ação específica a realizar.
10.4.3.4. src/api/rdvmedecins.api.ts
| // =========================================================================
// api/rdvmedecins.api.ts - uma função por rota da API
// -------------------------------------------------------------------------
// A "camada de acesso a dados" do cliente: os componentes chamam estas
// funções tipadas, sem saber nada sobre URLs, fetch ou JSON. Se
// a API mudar, só este arquivo muda.
// Cada função retorna uma PROMISE: os componentes encadeiam as
// requisições com async / await. Em caso de falha, a promise é rejeitada
// com um ApiError (veja client.ts).
// =========================================================================
import { request } from './client';
import type {
Schedule,
Captcha,
PersonData,
Registration,
MyAccountUpdate,
MyAccount,
MyArea,
Person,
User,
} from './types';
// /api/doctors ou /api/clients: ambos são gerenciados da mesma forma
export type PersonType = 'doctors' | 'clients';
type Empty = Record<string, never>;
export const api = {
// ──────────────────────────────────────────────── login (rotas públicas)
captcha: () => request<Captcha>('GET', '/captcha', undefined, true),
me: () => request<User>('GET', '/auth/me', undefined, true),
logIn: (login: string, password: string, captchaId: string, captcha: string) =>
request<User>('POST', '/auth/login', { login, password, captchaId, captcha }, true),
logOut: () => request<Empty>('POST', '/auth/logout', {}, true),
// ──────────────────────────────────────────────── criação de conta (público)
registrationAccess: (captchaId: string, captcha: string) =>
request<Empty>('POST', '/register/access', { captchaId, captcha }, true),
registrationAccessStatus: () => request<{ valid: boolean }>('GET', '/register/access', undefined, true),
register: (data: Registration) => request<{ login: string }>('POST', '/register', data, true),
// ──────────────────────────────────────────────── agenda e consultas
// doctorId null: para um médico logado, a agenda DELE
schedule(doctorId: number | null, day: string) {
const params = new URLSearchParams({ day });
if (doctorId !== null) {
params.set('doctorId', String(doctorId));
}
return request<Schedule>('GET', `/schedule?${params}`);
},
book: (day: string, slotId: number, clientId: number | null) =>
request<{ id: number }>('POST', '/appointments', { day, slotId, clientId: clientId ?? undefined }),
cancelAppointment: (appointmentId: number) => request<Empty>('DELETE', `/appointments/${appointmentId}`),
// ──────────────────────────────────────────────── médicos e clientes
list: (type: PersonType) => request<Person[]>('GET', `/${type}`),
read: (type: PersonType, id: number) => request<Person>('GET', `/${type}/${id}`),
add: (type: PersonType, data: PersonData) => request<Person>('POST', `/${type}`, data),
edit: (type: PersonType, id: number, data: PersonData) => request<Person>('PUT', `/${type}/${id}`, data),
remove: (type: PersonType, id: number) => request<Empty>('DELETE', `/${type}/${id}`),
// ──────────────────────────────────────────────── a área do paciente
myArea: () => request<MyArea>('GET', '/my-area'),
myAccount: () => request<MyAccount>('GET', '/my-account'),
editMyAccount: (data: MyAccountUpdate) => request<User>('PUT', '/my-account', data),
deleteMyAccount: (currentPassword: string) => request<Empty>('DELETE', '/my-account', { currentPassword }),
};
|
Uma função por rota da API, tipada: os componentes chamam [api.schedule(1, '2026-10-05')] sem saber nada sobre URL ou JSON. Se a API mudar, apenas este arquivo muda.
- linhas 32–36: as rotas de conexão, que são públicas (último parâmetro de [request]: [true]);
- linhas 39–42: a criação de conta, em duas etapas: resolver o CAPTCHA na página de login fornece um “passe” (um cookie), que a rota [POST /api/register] exige;
- linhas 46–52: [URLSearchParams] gera os parâmetros do endereço (e os codifica). Para um médico logado, não há [doctorId]: o servidor retorna a agenda DELE;
- linha 54: um paciente faz uma reserva para si mesmo: sem [clientId]. [JSON.stringify] omite as propriedades [undefined];
- linhas 58–62: médicos e clientes são tratados da mesma forma: o tipo é um parâmetro;
- linha 28: o tipo de um objeto vazio [{}], que algumas rotas retornam.
10.4.4. Idiomas
10.4.4.1. src/i18n/i18n.ts
| // =========================================================================
// i18n/i18n.ts - francês e inglês (i18next, veja o exemplo 21)
// -------------------------------------------------------------------------
// Os dicionários fr.json e en.json são os do curso NestJS
// (i18n/*.json), completados com algumas chaves específicas do cliente
// (ERRORS.SERVER_UNREACHABLE...). O servidor JSON só retorna CHAVES
// ('ERRORS.LOGIN_TAKEN'): elas são as mesmas dos dicionários.
//
// O idioma escolhido é armazenado no localStorage (uma preferência, não um
// dado sensível); na falta dele, usa-se o idioma do navegador.
// =========================================================================
import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import fr from './fr.json';
import en from './en.json';
export type Language = 'fr' | 'en';
export const LANGUAGES: Language[] = ['fr', 'en'];
const STORAGE_KEY = 'rdvmedecins.language';
function initialLanguage(): Language {
try {
const stored = localStorage.getItem(STORAGE_KEY);
if (stored === 'fr' || stored === 'en') {
return stored;
}
} catch {
// localStorage indisponível (navegação privada estrita...): tanto faz
}
return navigator.language.toLowerCase().startsWith('fr') ? 'fr' : 'en';
}
// a cada troca de idioma: armazená-lo e atualizar o
// atributo lang da página (leitores de tela, corretores ortográficos, hifenização)
i18n.on('languageChanged', (language) => {
document.documentElement.lang = language;
try {
localStorage.setItem(STORAGE_KEY, language);
} catch {
// sem importância
}
});
i18n.use(initReactI18next).init({
// os dicionários fazem parte do código da aplicação: nenhuma requisição
resources: { fr: { translation: fr }, en: { translation: en } },
lng: initialLanguage(),
fallbackLng: 'en',
interpolation: { escapeValue: false }, // o React já escapa tudo
});
export default i18n;
|
A configuração do Exemplo 21:
- linhas 22–32: o idioma armazenado ou, na falta dele, o idioma do navegador. O acesso ao [localStorage] pode falhar (navegação privada estrita): [try / catch];
- linhas 36–43: a cada mudança de idioma, ele é salvo e o atributo [lang] da página é atualizado;
- linha 47: os dicionários, importados como módulos, fazem parte do código compilado e não exigem requisições adicionais;
- linha 50: o [React] já escapa tudo o que exibe: não é preciso fazer isso duas vezes.
Não há equivalente à “estratégia de título” do [Angular]: cada página declara seu título com a tag [<title>], que o [React] 19 coloca no cabeçalho do documento (veja [components/PageTitle.tsx]).
10.4.4.2. Dicionários
Os dicionários [fr.json] e [en.json] são os da aplicação HTML do curso [NestJS], acrescidos de algumas chaves específicas do cliente ([ERRORS.SERVER_UNREACHABLE]...). A sintaxe de seus parâmetros, [{{min}}], é exatamente a mesma do [i18next]. O servidor JSON retorna as mesmas chaves.
| {
"APP": {
"TITLE": "RdvMedecins",
"LOGOUT": "Se déconnecter",
"MENU_SCHEDULE": "Agenda",
"MENU_DOCTORS": "Médecins",
"MENU_PATIENTS": "Clients",
"MENU_MY_AREA": "Mon espace",
"LOADING": "Chargement...",
"LANGUAGE": "Langue"
},
"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 ».",
"AUTH_REQUIRED": "Connectez-vous pour accéder à cette page.",
"JSON_REQUIRED": "Requête refusée : le serveur attend du JSON.",
"SERVER_UNREACHABLE": "Le serveur ne répond pas. Réessayez plus tard."
},
"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"
}
}
|
| {
"APP": {
"TITLE": "RdvMedecins",
"LOGOUT": "Log out",
"MENU_SCHEDULE": "Schedule",
"MENU_DOCTORS": "Doctors",
"MENU_PATIENTS": "Patients",
"MENU_MY_AREA": "My area",
"LOADING": "Loading...",
"LANGUAGE": "Language"
},
"LOGIN": {
"TITLE": "Login",
"LOGIN_LABEL": "Login",
"PASSWORD_LABEL": "Password",
"SUBMIT": "Log in",
"ERROR": "Incorrect login or password.",
"DEMO_ACCOUNTS": "Demo accounts (password = login):",
"DEMO_ADMIN": "ADMIN role: appointments + doctor and patient management",
"DEMO_DOCTOR": "DOCTOR role: booking and cancelling appointments",
"DEMO_USER": "USER role (patients): booking for themselves, managing their account",
"CREATE_ACCOUNT": "Create a patient account",
"CREATE_ACCOUNT_HELP": "To create an account, first type the characters shown in the image."
},
"DOCTOR_DAY_PICKER": {
"DOCTOR_LABEL": "Doctor",
"CHOOSE_DOCTOR": "-- choose a doctor --",
"DAY_LABEL": "Day",
"VIEW_SCHEDULE": "View schedule"
},
"SCHEDULE": {
"PAGE_TITLE": "Schedule",
"TITLE_PREFIX": "Schedule for",
"COLUMN_SLOT": "Slot",
"COLUMN_STATUS": "Status",
"FREE": "Free",
"BOOK": "Book",
"CANCEL_APPOINTMENT": "Cancel",
"CANCEL_CONFIRM": "Cancel this appointment?",
"EMPTY_STATE": "Choose a doctor and a day, then click \"View schedule\".",
"NO_SLOTS": "This doctor has no time slots.",
"BOOKED": "Appointment booked.",
"CANCELLED": "Appointment cancelled.",
"BOOKED_BY_OTHER": "Booked",
"ALREADY_BOOKED_INFO": "You already have an upcoming appointment: cancel it to book another one."
},
"BOOKING_DIALOG": {
"TITLE": "Book this slot",
"CLOSE_ARIA": "Close",
"SLOT": "Slot {{time}}",
"PATIENT_LABEL": "Patient",
"CHOOSE_PATIENT": "-- choose a patient --",
"CANCEL": "Cancel",
"CONFIRM": "Confirm"
},
"PERSONS": {
"COLUMN_TITLE": "Title",
"COLUMN_FIRSTNAME": "First name",
"COLUMN_LASTNAME": "Last name",
"COLUMN_LOGIN": "Login",
"EDIT": "Edit",
"DELETE": "Delete",
"SAVE": "Save",
"BACK": "Back to the list",
"TITLE_LABEL": "Title",
"FIRSTNAME_LABEL": "First name",
"LASTNAME_LABEL": "Last name",
"LOGIN_LABEL": "Login",
"PASSWORD_LABEL": "Password",
"LOGIN_HELP_CREATE": "Optional: defaults to the last name in lower case.",
"LOGIN_HELP_EDIT": "Leave empty to keep it unchanged.",
"PASSWORD_HELP_CREATE": "Optional: defaults to the login.",
"PASSWORD_HELP_EDIT": "Leave empty to keep it unchanged.",
"ACCOUNT_SECTION": "User account"
},
"DOCTORS": {
"TITLE": "Doctors",
"ADD": "Add a doctor",
"EDIT": "Edit a doctor",
"EMPTY": "No doctors.",
"DELETE_CONFIRM": "Delete this doctor, their time slots and their user account?",
"ADDED": "Doctor {{name}} has been added (login: {{login}}).",
"UPDATED": "Doctor {{name}} has been updated.",
"DELETED": "Doctor {{name}} has been deleted."
},
"CLIENTS": {
"TITLE": "Patients",
"ADD": "Add a patient",
"EDIT": "Edit a patient",
"EMPTY": "No patients.",
"DELETE_CONFIRM": "Delete this patient, their user account and all their appointments?",
"ADDED": "Patient {{name}} has been added (login: {{login}}).",
"UPDATED": "Patient {{name}} has been updated.",
"DELETED": "Patient {{name}} has been deleted."
},
"ERROR_PAGE": {
"TITLE": "Error",
"BACK": "Back to the home page"
},
"ERRORS": {
"LOGIN_TAKEN": "This login is already used by another account.",
"DOCTOR_ALREADY_EXISTS": "A doctor with this first and last name already exists.",
"PATIENT_ALREADY_EXISTS": "A patient with this first and last name already exists.",
"DOCTOR_HAS_APPOINTMENTS": "This doctor has appointments: cancel them before deleting the doctor.",
"SLOT_ALREADY_BOOKED": "This slot has just been booked by someone else.",
"CONCURRENT_UPDATE": "This record was changed by another user in the meantime. Go back to the list and reopen it before trying again.",
"DOCTOR_NOT_FOUND": "This doctor does not exist (any more).",
"PATIENT_NOT_FOUND": "This patient does not exist (any more).",
"SLOT_NOT_FOUND": "This slot does not exist (any more).",
"APPOINTMENT_NOT_FOUND": "This appointment does not exist (any more).",
"INVALID_DATE": "The requested date is not valid.",
"CHOOSE_PATIENT": "Choose a patient.",
"INVALID_FORM": "The form contains errors.",
"INVALID_TITLE": "Choose a title from the list.",
"FIRSTNAME_REQUIRED": "The first name is required.",
"FIRSTNAME_TOO_LONG": "The first name must not exceed 20 characters.",
"LASTNAME_REQUIRED": "The last name is required.",
"LASTNAME_TOO_LONG": "The last name must not exceed 20 characters.",
"INVALID_LOGIN": "At most 30 characters: unaccented lower-case letters, digits, dot, hyphen, underscore.",
"PASSWORD_TOO_LONG": "The password must not exceed 72 characters.",
"SESSION_EXPIRED": "Your session has expired: please log in again.",
"BAD_REQUEST": "The request is invalid.",
"FORBIDDEN": "Your role does not allow you to access this page.",
"NOT_FOUND": "This page does not exist.",
"SERVER_ERROR": "An unexpected error occurred. Please try again later.",
"TOO_MANY_ATTEMPTS": "Too many failed attempts. Try again in {{minutes}} minute(s).",
"WRONG_CAPTCHA": "The characters you typed do not match the image. A new image is shown.",
"TOO_MANY_ACCOUNTS": "Too many accounts have been created from your connection. Try again in {{minutes}} minute(s).",
"LOGIN_REQUIRED": "The login is required.",
"PASSWORD_REQUIRED": "The password is required.",
"PASSWORD_TOO_SHORT": "The password must be at least {{min}} characters long.",
"CONFIRMATION_REQUIRED": "Please confirm the password.",
"PASSWORDS_DIFFER": "The confirmation does not match the password.",
"CURRENT_PASSWORD_REQUIRED": "Enter your current password.",
"WRONG_CURRENT_PASSWORD": "Incorrect current password.",
"PAST_DATE": "Appointments cannot be booked for a past date.",
"PATIENT_HAS_UPCOMING_APPOINTMENT": "This patient already has an upcoming appointment: it must be cancelled before booking another one.",
"CAPTCHA_BEFORE_ACCOUNT": "To create an account, first type the characters shown in the image correctly, then click \"Create a patient account\".",
"AUTH_REQUIRED": "Please log in to access this page.",
"JSON_REQUIRED": "Request refused: the server expects JSON.",
"SERVER_UNREACHABLE": "The server does not respond. Please try again later."
},
"CAPTCHA": {
"LABEL": "Type the characters shown in the image",
"IMAGE_ALT": "Anti-robot verification image",
"NEW_IMAGE": "Another image",
"HELP": "Upper or lower case, it does not matter."
},
"REGISTRATION": {
"TITLE": "Create a patient account",
"INTRO": "With this account you can book your own appointments.",
"LOGIN_HELP": "Unaccented lower-case letters, digits, dot, hyphen, underscore.",
"PASSWORD_HELP": "At least {{min}} characters.",
"SUBMIT": "Create my account",
"BACK_TO_LOGIN": "Back to login",
"DONE": "Your account has been created. You can now log in with the login {{login}}."
},
"ACCOUNT": {
"CONFIRMATION_LABEL": "Confirm password"
},
"AREA": {
"TITLE": "My area",
"HELLO": "Hello {{name}}",
"MANAGE_ACCOUNT": "Manage my account",
"MANAGE_ACCOUNT_HELP": "Change my details or password, or delete my account.",
"VIEW_SCHEDULE": "View a schedule",
"VIEW_SCHEDULE_HELP": "See a doctor's schedule and book a slot.",
"MY_APPOINTMENT": "My appointment",
"SEE_IN_SCHEDULE": "see in the schedule",
"CANCEL_APPOINTMENT": "Cancel this appointment",
"NO_APPOINTMENT": "You have no upcoming appointment."
},
"MY_ACCOUNT": {
"TITLE": "Manage my account",
"NEW_PASSWORD_LABEL": "New password",
"CURRENT_PASSWORD_LABEL": "Current password",
"CURRENT_PASSWORD_HELP": "Required to save any change.",
"BACK": "Back to my area",
"DELETE_TITLE": "Delete my account",
"DELETE_HELP": "Your account will be permanently deleted, together with all your appointments.",
"DELETE_CONFIRM": "Permanently delete your account? Any appointment you have will be cancelled.",
"DELETE_SUBMIT": "Delete my account",
"UPDATED": "Your account has been updated.",
"DELETED": "Your account has been deleted."
},
"CONFIRMATION": {
"TITLE": "Confirmation",
"NO": "No, go back",
"YES": "Yes, confirm"
}
}
|
10.4.5. Os stores
10.4.5.1. src/stores/session.ts
| // =========================================================================
// stores/session.ts - QUEM está logado?
// -------------------------------------------------------------------------
// O usuário logado (ou null), em um store Zustand (veja o exemplo
// 20): legível pelos componentes (useSession) E pelo código que não é
// componente (os guards do roteador: useSession.getState()).
//
// O token JWT em si NÃO está aqui: ele está em um cookie httpOnly que
// só o navegador manipula. O store guarda apenas a DESCRIÇÃO do
// usuário, retornada pelo servidor ({ login, name, role }).
//
// Na inicialização (e após um F5), o store está vazio: check() pergunta
// ao servidor, uma única vez, quem está logado (GET /api/auth/me).
// =========================================================================
import { create } from 'zustand';
import { api } from '../api/rdvmedecins.api';
import type { Role, User } from '../api/types';
interface Session {
user: User | null;
check: () => Promise<void>;
logIn: (login: string, password: string, captchaId: string, captcha: string) => Promise<void>;
update: (u: User) => void;
logOut: () => Promise<void>;
forget: () => void;
}
// a pergunta "quem está logado?" já foi feita ao servidor?
// (uma variável do módulo: não precisa ser exibida)
let checking: Promise<void> | null = null;
export const useSession = create<Session>()((set, get) => ({
user: null,
// chamado pelo guard do roteador antes de CADA navegação; só pergunta
// ao servidor na primeira vez (a promise é guardada e reutilizada)
check() {
checking ??= api
.me()
.then((u) => set({ user: u }))
.catch(() => set({ user: null })); // 401: ninguém; ou servidor inacessível
return checking;
},
async logIn(login, password, captchaId, captcha) {
set({ user: await api.logIn(login, password, captchaId, captcha) });
},
// o usuário mudou de nome ou de login (PUT /api/my-account)
update: (u) => set({ user: u }),
async logOut() {
try {
await api.logOut();
} finally {
get().forget();
}
},
// sem perguntar nada ao servidor: sessão expirada, conta excluída
forget: () => set({ user: null }),
}));
// o que se deduz do usuário: funções comuns
export const role = (u: User | null): Role | null => u?.role ?? null;
export const isAdmin = (u: User | null) => role(u) === 'ADMIN';
export const isPatient = (u: User | null) => role(u) === 'USER';
// ADMIN e DOCTOR: reservam e cancelam as consultas de qualquer paciente
export const isManager = (u: User | null) => role(u) === 'ADMIN' || role(u) === 'DOCTOR';
// a página inicial de cada papel, logo após o login
export const homePage = (u: User | null) => (isPatient(u) ? '/my-area' : '/schedule');
|
O usuário logado, em um store [Zustand] (exemplo 20). Um store pode ser lido pelos componentes ([useSession((s) => s.user)]) E por meio de código que não é um componente: [useSession.getState()] (os guards do roteador).
- Linha 21: a DESCRIÇÃO do usuário ([{ login, name, role }]). O token JWT, por sua vez, fica no cookie httpOnly: o cliente nunca o vê;
- Linhas 31–44: [check()] pergunta ao servidor quem está logado UMA ÚNICA VEZ: a promise é guardada e reutilizada ([??=]: atribuição se a variável for [null]). Os guards a chamam antes de cada navegação: apenas o primeiro realmente espera;
- linhas 46–48: a conexão: o usuário retornado pelo servidor é armazenado no store;
- linhas 53–59: logout. [finally]: mesmo que o servidor não responda, o cliente esquece o usuário;
- linhas 66–72: o que se deduz sobre o usuário: funções comuns que recebem o usuário como parâmetro. Um componente escreve [isAdmin(user)] depois de ler [user] do store; ele é então reexibido quando o usuário muda.
10.4.5.2. src/stores/messages.ts
| // =========================================================================
// stores/messages.ts - as mensagens exibidas ao usuário
// -------------------------------------------------------------------------
// Mesma apresentação da aplicação HTML:
// - um SUCESSO é exibido no TOPO da página (faixa verde);
// - um ERRO no RODAPÉ, sobre um fundo rosa claro (painel "sticky").
// Uma mensagem é uma CHAVE de tradução (+ seus parâmetros): ela é, portanto,
// traduzida novamente por conta própria se o usuário trocar de idioma.
//
// As mensagens "flash": uma ação que termina com uma troca de
// página (reserva, inclusão de médico...) deixa sua mensagem com flash();
// ela será exibida na PRÓXIMA página e depois desaparece na navegação
// seguinte. É o roteador que chama newPage() ao fim de cada
// navegação (veja router.ts). Esse era, no lado do servidor, o papel do
// cookie de curta duração "rdvmedecins_flash".
// =========================================================================
import { create } from 'zustand';
import { ApiError } from '../api/api-error';
export interface Message {
key: string;
params?: Record<string, string>;
}
interface Messages {
success: Message | null;
error: Message | null;
// as mensagens a exibir na próxima página
pending: { success: Message | null; error: Message | null } | null;
showSuccess: (key: string, params?: Record<string, string>) => void;
showError: (key: string, params?: Record<string, string>) => void;
showApiError: (e: unknown) => void;
clear: () => void;
flash: (type: 'success' | 'error', key: string, params?: Record<string, string>) => void;
newPage: () => void;
}
export const useMessages = create<Messages>()((set) => ({
success: null,
error: null,
pending: null,
showSuccess: (key, params) => set({ success: { key, params }, error: null }),
showError: (key, params) => set({ error: { key, params }, success: null }),
// um ApiError -> a mensagem da página; qualquer outro erro é um
// bug do cliente, que é deixado passar (console do navegador)
showApiError(e) {
if (!(e instanceof ApiError)) {
throw e;
}
set({ error: { key: e.key, params: e.params }, success: null });
},
clear: () => set({ success: null, error: null }),
// para a PRÓXIMA página
flash: (type, key, params) =>
set((m) => ({ pending: { success: null, error: null, ...m.pending, [type]: { key, params } } })),
// uma nova página: as mensagens da anterior desaparecem, as mensagens
// flash aparecem
newPage: () =>
set((m) => ({ success: m.pending?.success ?? null, error: m.pending?.error ?? null, pending: null })),
}));
|
Mensagens exibidas ao usuário: uma mensagem de sucesso no topo da página, uma mensagem de erro na parte inferior.
- Linhas 21–24: uma mensagem é uma CHAVE de tradução e seus parâmetros, não um texto simples: ela se retraduz automaticamente se o usuário trocar de idioma;
- linhas 49–54: um [ApiError] se torna a mensagem de erro da página. Qualquer outro erro é um problema do lado do cliente (um erro de programação): ele é relançado para aparecer no console do navegador;
- linhas 59–60: [flash] define uma mensagem para a PRÓXIMA página. Uma ação que termina com uma mudança de página (adicionar um médico, seguida de um retorno à lista) usa isso: uma mensagem exibida imediatamente desapareceria durante a navegação do usuário;
- linhas 64–65: chamado pelo roteador ao final de cada navegação: as mensagens pendentes se tornam as mensagens da página.
10.4.5.3. src/stores/confirmation.ts
| // =========================================================================
// stores/confirmation.ts - "Tem certeza?"
// -------------------------------------------------------------------------
// Retirado do exemplo 16, na forma de um store: confirm(key) abre
// o diálogo de confirmação (components/ConfirmDialog.tsx, colocado uma vez
// no layout) e retorna uma promise resolvida com true (Sim) ou
// false (Não). A mensagem é uma CHAVE de tradução: o diálogo a traduz
// para o idioma atual.
//
// if (await confirm('SCHEDULE.CANCEL_CONFIRM')) { ... }
// =========================================================================
import { create } from 'zustand';
import { useMessages } from './messages';
interface Confirmation {
messageKey: string | null; // null: diálogo fechado
answer: (yes: boolean) => void;
}
// a função que resolverá a promise atual (nada a exibir: fora do estado)
let respond: ((yes: boolean) => void) | null = null;
export const useConfirmation = create<Confirmation>()((set) => ({
messageKey: null,
answer(yes) {
set({ messageKey: null });
const r = respond;
respond = null;
r?.(yes);
},
}));
// uma função comum, utilizável em qualquer lugar
export function confirm(key: string): Promise<boolean> {
respond?.(false); // uma pergunta ainda aberta? conta como "não"
// uma nova pergunta: as mensagens da ação anterior estão desatualizadas
useMessages.getState().clear();
useConfirmation.setState({ messageKey: key });
return new Promise<boolean>((resolve) => {
respond = resolve;
});
}
|
A janela de confirmação do Exemplo 16, implementada como um store e uma função comum:
- linha 17: a pergunta feita (uma chave de tradução) ou [null]: a janela ([components/ConfirmDialog.tsx]) está fechada;
- linha 22: a função que resolverá a promise da pergunta atual. Nada a exibir: isso não é um estado, mas uma variável de módulo;
- linhas 35–43: [confirm] abre a janela e retorna uma promise, resolvida com [true] (Sim) ou [false] (Não) por [answer]. Uma página simplesmente escreve [if (await confirm('SCHEDULE.CANCEL_CONFIRM')) { ... }]. Nenhum contexto é necessário, como no Exemplo 16: o store é acessível em qualquer lugar.
10.4.6. Os hooks
| // =========================================================================
// hooks/useFormSubmit.ts - envio de um formulário ao servidor
// -------------------------------------------------------------------------
// Todos os formulários da aplicação seguem o mesmo padrão do
// exemplo 25: nenhuma regra é verificada no navegador (elas
// vivem em UM só lugar, o servidor), e quando o formulário é rejeitado:
// - o erro de cada campo (ApiError.fields) é exibido sob o
// campo, contornado de vermelho;
// - a mensagem geral (ApiError.key) é exibida no rodapé da página.
// Este hook agrupa esses gestos. Uma página o chama uma vez por formulário:
//
// const submission = useFormSubmit();
// if (await submission.submit(() => api.register(form))) { ... }
// <InputField ... error={submission.errors.lastName} />
// =========================================================================
import { useCallback, useState } from 'react';
import { ApiError } from '../api/api-error';
import { useMessages } from '../stores/messages';
export function useFormSubmit() {
const showApiError = useMessages((m) => m.showApiError);
// o erro de cada campo: uma CHAVE de tradução
const [errors, setErrors] = useState<Record<string, string>>({});
// os parâmetros das mensagens de erro ({min}...), retornados pelo servidor
const [params, setParams] = useState<Record<string, string>>({});
const [submitting, setSubmitting] = useState(false);
// executa o envio; retorna true se teve sucesso. Em caso de ApiError, os
// erros são exibidos e retorna-se false.
const submit = useCallback(
async (action: () => Promise<unknown>): Promise<boolean> => {
setErrors({});
setParams({});
setSubmitting(true);
try {
await action();
return true;
} catch (e) {
showApiError(e); // (relança qualquer erro que não seja um ApiError)
const error = e as ApiError;
setErrors(error.fields);
setParams(error.params);
return false;
} finally {
setSubmitting(false);
}
},
[showApiError],
);
// o usuário modifica um campo: seu erro desaparece
const clearError = useCallback((field: string) => {
setErrors((e) => {
if (!(field in e)) return e; // nada a limpar: o MESMO objeto (nenhuma nova renderização)
const { [field]: _cleared, ...rest } = e;
return rest;
});
}, []);
return { errors, params, submitting, submit, clearError };
}
|
Todos os formulários da aplicação seguem o padrão mostrado no Exemplo 25: nenhuma regra de validação é verificada no navegador e, se o servidor rejeita o envio, o erro de cada campo é exibido abaixo do campo, com uma mensagem de erro geral na parte inferior da página. Este hook personalizado (Exemplo 15) cuida das seguintes ações:
- linhas 24–27: seu estado: o erro de cada campo (uma chave de tradução), seus parâmetros e “enviando” (para desabilitar o botão);
- linhas 31–50: [submit(action)] executa o envio e retorna [true] se ele tem sucesso. Se um [ApiError] é retornado, os erros são exibidos e a função retorna [false]. [useCallback]: a função permanece a MESMA de uma exibição para a seguinte;
- Linhas 53–59: o usuário modifica um campo: o erro desaparece. Se o campo não tinha erro, o MESMO objeto é retornado; o [React] não reexibe nada. [const { [field]: _cleared, ...rest } = e]: [rest] é uma cópia de [e], sem a propriedade [field].
10.4.6.2. src/hooks/useCaptcha.ts
| // =========================================================================
// hooks/useCaptcha.ts - uma imagem de CAPTCHA e o meio de trocá-la
// -------------------------------------------------------------------------
// Carrega um CAPTCHA (GET /api/captcha) quando o componente que o usa
// é exibido. reload() pede outro: ele é necessário após CADA
// tentativa, pois uma imagem só pode ser usada UMA vez (o servidor a esquece
// assim que a verifica). A página de login a usa com o componente
// CaptchaField, que exibe a imagem e o campo de entrada.
// =========================================================================
import { useCallback, useEffect, useState } from 'react';
import { api } from '../api/rdvmedecins.api';
import type { Captcha } from '../api/types';
export function useCaptcha() {
const [captcha, setCaptcha] = useState<Captcha | null>(null);
const reload = useCallback(async () => {
try {
setCaptcha(await api.captcha());
} catch {
setCaptcha(null); // servidor inacessível: o login falhará com uma mensagem clara
}
}, []);
useEffect(() => {
reload();
}, [reload]);
// captchaId: o identificador da imagem exibida, a enviar com a resposta
return { svg: captcha?.svg ?? '', captchaId: captcha?.id ?? '', reload };
}
|
Uma imagem de CAPTCHA, carregada quando o componente é exibido, e [reload()] para solicitar outra: isso é necessário após CADA tentativa, porque o servidor descarta uma imagem assim que a verifica.
| // =========================================================================
// formatting.ts - a exibição de pessoas, horários e dias
// -------------------------------------------------------------------------
// O servidor envia dados BRUTOS (startHour: 8, startMinute: 0; day:
// "2026-10-05"); a formatação, que depende do idioma, é assunto do
// cliente (veja o exemplo 09).
// =========================================================================
import type { Slot, Identity } from './api/types';
// "Mme Alice DURAND"
export function label(p: Identity): string {
return `${p.title} ${p.firstName} ${p.lastName}`;
}
// "8:05" em vez de "8:5"
export function time(h: number, m: number): string {
return `${h}:${String(m).padStart(2, '0')}`;
}
// "8:00 - 8:20"
export function timeRange(s: Slot): string {
return `${time(s.startHour, s.startMinute)} - ${time(s.endHour, s.endMinute)}`;
}
// a data de hoje, no formato "yyyy-MM-dd" (o de <input type="date"> e o da API)
export function today(): string {
const d = new Date();
return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
}
// true se [day] for uma data que existe, no formato yyyy-MM-dd
export function isValidDate(day: unknown): day is string {
if (typeof day !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(day)) {
return false;
}
const date = new Date(`${day}T00:00:00Z`);
return !isNaN(date.getTime()) && date.toISOString().slice(0, 10) === day;
}
// "lundi 5 octobre 2026" / "Monday 5 October 2026"
export function longDate(day: string, language: string): string {
return new Intl.DateTimeFormat(language === 'en' ? 'en-GB' : 'fr-FR', {
dateStyle: 'full',
timeZone: 'UTC', // "2026-10-05T00:00:00Z" deve continuar sendo dia 5, qualquer que seja o fuso horário
}).format(new Date(`${day}T00:00:00Z`));
}
|
O servidor envia dados brutos ([startHour: 8, startMinute: 0]; [day: "2026-10-05"]); a formatação é responsabilidade do cliente (exemplo 09). São funções comuns: o [React] não exige “pipes”, e uma expressão como o JSX pode chamar qualquer função ([{timeRange(c)}]).
- Linhas 33–39: [day is string]: um predicado de tipo: se a função retorna [true], o [TypeScript] passa a saber que [day] é uma string. Uma data “que existe”: [2026-02-30] tem o formato correto, mas [new Date] a converte em 2 de março; a data resultante é então comparada com a string original;
- linhas 42–47: o dia por extenso, no idioma do usuário, usando [Intl.DateTimeFormat]. [timeZone: 'UTC']: a data é construída à meia-noite (UTC); formatada no fuso horário da Martinica (UTC-4), ela ainda seria o dia anterior.
10.4.8. O roteador
10.4.8.1. src/routes.tsx
| // =========================================================================
// routes.tsx - as páginas da aplicação e seus direitos de acesso
// -------------------------------------------------------------------------
// Os MESMOS endereços da aplicação HTML (/login, /schedule, /doctors,
// /my-area...), mas agora são rotas do CLIENTE. O
// navegador só envia uma requisição ao servidor para a primeiríssima
// página; depois disso, o roteador muda o endereço e o componente exibido.
//
// O reverso da moeda: se o usuário recarregar /schedule (F5), o
// navegador pede mesmo /schedule ao servidor, que então deve
// devolver index.html (o Vite faz isso em desenvolvimento; em produção,
// veja web/client-spa.ts do servidor JSON).
//
// Todas as páginas são FILHAS da rota raiz, cujo componente,
// Layout, as exibe em seu <Outlet />. A função page() descreve uma
// página: seu endereço, seu componente (carregado sob demanda para as páginas
// que nem sempre são visitadas) e o guard que verifica seus direitos.
// =========================================================================
import type { ComponentType } from 'react';
import { redirect, type MiddlewareFunction, type RouteObject } from 'react-router';
import type { PersonType } from './api/rdvmedecins.api';
import { guard, registrationGuard, type Rights } from './guards';
import Layout from './components/Layout';
import Login from './pages/Login';
import Schedule from './pages/Schedule';
import ErrorPage from './pages/ErrorPage';
// uma página: componente carregado de uma vez (Component) ou sob demanda
// (load); otherGuards: guards específicos da página, após o guard comum
interface Page {
path: string;
rights: Rights;
Component?: ComponentType;
load?: () => Promise<ComponentType>;
otherGuards?: MiddlewareFunction[];
}
function page({ path, rights, Component, load, otherGuards = [] }: Page): RouteObject {
return {
path,
// os guards são executados ANTES de a página ser carregada
middleware: [guard(rights), ...otherGuards],
...(load ? { lazy: async () => ({ Component: await load() }) } : { Component }),
};
}
// as páginas de gerenciamento dos médicos E dos clientes (ADMIN), no mesmo
// modelo; o componente recebe o tipo como prop
function personPages(type: PersonType): RouteObject[] {
const rights: Rights = { roles: ['ADMIN'] };
const list = async () => {
const { default: Persons } = await import('./pages/Persons');
return () => <Persons type={type} />;
};
const form = async () => {
const { default: PersonForm } = await import('./pages/PersonForm');
return () => <PersonForm type={type} />;
};
return [
page({ path: type, rights, load: list }),
page({ path: `${type}/add`, rights, load: form }),
page({ path: `${type}/:id/edit`, rights, load: form }),
];
}
export const routes: RouteObject[] = [
{
path: '/',
Component: Layout,
// exibido durante a primeiríssima navegação (o tempo de perguntar ao
// servidor quem está logado)
HydrateFallback: () => null,
children: [
// "/": para /login, que por sua vez redireciona para a página inicial do papel se o usuário estiver logado
// (um componente que não exibe nada: o redirecionamento acontece antes)
{ index: true, loader: () => redirect('/login'), Component: () => null },
page({ path: 'login', rights: { public: true }, Component: Login }),
page({ path: 'schedule', rights: {}, Component: Schedule }),
...personPages('doctors'),
...personPages('clients'),
page({
path: 'register',
rights: { public: true },
load: async () => (await import('./pages/Register')).default,
otherGuards: [registrationGuard],
}),
page({ path: 'my-area', rights: { roles: ['USER'] }, load: async () => (await import('./pages/PatientArea')).default }),
page({ path: 'my-account', rights: { roles: ['USER'] }, load: async () => (await import('./pages/MyAccount')).default }),
page({ path: 'forbidden', rights: {}, Component: () => <ErrorPage code={403} /> }),
page({ path: '*', rights: { public: true }, Component: () => <ErrorPage code={404} /> }),
],
},
];
|
Os MESMOS endereços que a aplicação HTML usa, mas que agora são rotas do CLIENTE:
- linhas 31–37: a descrição de uma página: seu endereço, suas permissões de acesso e seu componente, fornecido imediatamente ([Component]) ou carregado sob demanda ([load]);
- linhas 39–46: [page()] gera a rota correspondente:
- linha 43: o guard comum, gerado com base nas permissões da página, seguido dos guards específicos da página. Eles são executados ANTES de a página ser carregada (Exemplo 18);
- linha 44: [lazy]: o código da página é carregado na primeira visita (Exemplo 17). A página de login e a agenda, que todos podem ver, são carregadas imediatamente; as páginas do ADMIN e do paciente são carregadas sob demanda;
- linhas 50–65: as três páginas de gerenciamento de médicos, seguidas das de clientes, usando o mesmo template. O componente é envolvido por um componente sem parâmetros, [() => <Persons type={type} />]: é assim que ele recebe o tipo como prop;
- linhas 69–70: a rota raiz. Seu componente, [Layout], exibe a página atual em seu [<Outlet />];
- linha 73: o que é exibido durante a primeira navegação, enquanto o guard pergunta ao servidor quem está conectado: nada;
- linha 77: o endereço [/] redireciona para [/login], cujo guard, por sua vez, redireciona para a página inicial do papel se o usuário estiver logado;
- linhas 78–79: [rights: { public: true }]: a página é acessível sem estar logado; [rights: {}]: é preciso estar logado, seja qual for o papel;
- linhas 83–87: a criação de uma conta pública tem um segundo guard, [registrationGuard];
- linhas 88–89: [roles: ['USER']]: as páginas do paciente;
- linha 90: a página 403;
- linha 91: a página 404: [*] refere-se a qualquer endereço que nenhuma outra rota reconheça.
Lembrete: se o usuário recarrega [/schedule] (F5), o navegador de fato solicita [/schedule] ao servidor, que deve então retornar [index.html]: é isso que o servidor de desenvolvimento do [Vite] faz e, em produção, o servidor JSON (veja o capítulo “Implantação”).
10.4.8.2. src/guards.ts
| // =========================================================================
// guards.ts - os guards do roteador (middlewares, veja o exemplo 18)
// -------------------------------------------------------------------------
// guard(rights) CRIA o guard de uma página, a partir de seus direitos de acesso:
// - public : acessível sem estar logado;
// - roles : os papéis permitidos (ausente = todos os papéis logados).
// Cada página declara os seus (veja routes.tsx). Antes de cada navegação
// para esta página, o guard:
// 1. na primeira vez (inicialização, F5), pergunta ao servidor quem está
// logado (useSession.getState().check());
// 2. verifica os direitos da página e redireciona se necessário.
//
// LEMBRETE: essas verificações são apenas uma CONVENIÊNCIA (não exibir uma
// página inútil). A proteção dos dados é garantida pelo servidor, que
// verifica o token e o papel novamente a CADA requisição.
// =========================================================================
import { redirect, type MiddlewareFunction } from 'react-router';
import type { Role } from './api/types';
import { api } from './api/rdvmedecins.api';
import { homePage, useSession } from './stores/session';
import { useMessages } from './stores/messages';
export interface Rights {
public?: boolean;
roles?: Role[];
}
export function guard(rights: Rights): MiddlewareFunction {
return async ({ request }) => {
await useSession.getState().check();
// getState(): o estado do store, lido FORA de um componente
const user = useSession.getState().user;
const url = new URL(request.url);
if (rights.public) {
// já logado: a página de login não faz mais sentido
if (url.pathname === '/login' && user !== null) {
throw redirect(homePage(user));
}
return;
}
if (user === null) {
// a página solicitada é memorizada, para voltar a ela após o login
throw redirect(`/login?redirect=${encodeURIComponent(url.pathname + url.search)}`);
}
if (rights.roles && !rights.roles.includes(user.role)) {
throw redirect('/forbidden');
}
};
}
// um guard ESPECÍFICO da rota /register: sem um passe (CAPTCHA
// resolvido na página de login), volta para a página de login
export const registrationGuard: MiddlewareFunction = async () => {
const { valid } = await api.registrationAccessStatus().catch(() => ({ valid: false }));
if (!valid) {
useMessages.getState().flash('error', 'ERRORS.CAPTCHA_BEFORE_ACCOUNT');
throw redirect('/login');
}
};
|
- linhas 24–27: os direitos de acesso de uma página;
- linhas 29–51: [guard(rights)] CRIA um guard, ou seja, um middleware do roteador (exemplo 18):
- linha 31: na primeira vez (inicialização, F5), pergunta-se ao servidor quem está logado; nas vezes seguintes, a resposta já está disponível;
- linhas 36–42: uma página pública. Um usuário logado não precisa mais fazer nada na página de login: ele é redirecionado para sua página inicial;
- linhas 43–46: ninguém está logado: redireciona para a página de login, guardando a página solicitada ([?redirect=...]), para voltar a ela após o login;
- linhas 47–49: o papel não está autorizado: a página 403;
- [throw redirect(...)]: um guard “dispara” um redirecionamento: a navegação atual é abandonada em favor do novo endereço;
- linhas 55–61: o guard específico da página [/register]: sem um passe (o CAPTCHA resolvido na página de login), volta-se à página de login com uma mensagem. De qualquer forma, o servidor se recusaria a criar a conta.
Essas verificações são apenas uma COMODIDADE: não exibir uma página inútil. A proteção dos dados é garantida pelo servidor, que reverifica o token e o papel a CADA requisição.
10.4.9. Os componentes
10.4.9.1. src/components/Layout.tsx
| // =========================================================================
// components/Layout.tsx - o LAYOUT comum a todas as páginas
// -------------------------------------------------------------------------
// O componente da rota raiz (veja routes.tsx), o equivalente de
// views/layout.hbs da aplicação HTML:
// - a barra de navegação;
// - uma mensagem de sucesso no TOPO;
// - a página atual (<Outlet />);
// - o painel de erros no RODAPÉ;
// - o diálogo de confirmação, uma vez para toda a aplicação.
// =========================================================================
import { Outlet } from 'react-router';
import NavBar from './NavBar';
import SuccessMessage from './SuccessMessage';
import ErrorPanel from './ErrorPanel';
import ConfirmDialog from './ConfirmDialog';
export default function Layout() {
return (
<>
<div className="container py-4">
<NavBar />
<SuccessMessage />
<Outlet />
<ErrorPanel />
</div>
<ConfirmDialog />
</>
);
}
|
O componente da rota raiz, equivalente a [views/layout.hbs] na aplicação HTML: a barra de navegação, a mensagem de sucesso no topo, a página atual ([<Outlet />]) e a área de erros na parte inferior. A janela de confirmação é colocada ali uma única vez para toda a aplicação.
10.4.9.2. src/components/PageTitle.tsx
| // =========================================================================
// components/PageTitle.tsx - o título da aba, traduzido
// -------------------------------------------------------------------------
// O React 19 coloca no <head> da página qualquer elemento <title> renderizado por
// um componente (veja o exemplo 17). Cada página exibe <PageTitle titleKey="..." />
// com a chave de seu título: a aba exibe "Schedule - RdvMedecins", e
// é traduzida novamente quando o idioma muda.
// =========================================================================
import { useTranslation } from 'react-i18next';
export default function PageTitle({ titleKey }: { titleKey: string }) {
const { t } = useTranslation();
return <title>{`${t(titleKey)} - ${t('APP.TITLE')}`}</title>;
}
|
O [React] 19 coloca no cabeçalho da página ([<head>]) qualquer elemento [<title>] renderizado por um componente (exemplo 17). Cada página exibe [<PageTitle titleKey="SCHEDULE.PAGE_TITLE" />]: a aba exibe “Schedule - RdvMedecins” e é retraduzida quando o idioma muda.
10.4.9.3. src/components/NavBar.tsx
| // =========================================================================
// components/NavBar.tsx - a barra de navegação
// -------------------------------------------------------------------------
// Mesmo conteúdo da aplicação HTML (views/partials/navbar.hbs):
// título, menus conforme o papel, FR / EN, papel, nome, logout.
// "Doctors" e "Patients" só aparecem para o ADMIN: uma simples
// conveniência de exibição, sendo a proteção real a do servidor.
// =========================================================================
import { NavLink, useNavigate } from 'react-router';
import { useTranslation } from 'react-i18next';
import { LANGUAGES } from '../i18n/i18n';
import { isAdmin, isPatient, useSession } from '../stores/session';
export default function NavBar() {
const { t, i18n } = useTranslation();
const user = useSession((s) => s.user);
const logOut = useSession((s) => s.logOut);
const navigate = useNavigate();
async function onLogOut() {
await logOut().catch(() => {}); // mesmo que o servidor não responda
navigate('/login');
}
return (
<nav className="navbar navbar-expand-sm navbar-dark bg-primary rounded mb-4 px-3">
<span className="navbar-brand mb-0">{t('APP.TITLE')}</span>
{user ? (
<ul className="navbar-nav me-auto">
{isPatient(user) && (
<li className="nav-item">
{/* NavLink define a classe "active" (Bootstrap) no menu da página exibida */}
<NavLink className="nav-link" to="/my-area">{t('APP.MENU_MY_AREA')}</NavLink>
</li>
)}
<li className="nav-item">
<NavLink className="nav-link" to="/schedule">{t('APP.MENU_SCHEDULE')}</NavLink>
</li>
{isAdmin(user) && (
<>
<li className="nav-item">
<NavLink className="nav-link" to="/doctors">{t('APP.MENU_DOCTORS')}</NavLink>
</li>
<li className="nav-item">
<NavLink className="nav-link" to="/clients">{t('APP.MENU_PATIENTS')}</NavLink>
</li>
</>
)}
</ul>
) : (
<div className="me-auto"></div>
)}
<div className="d-flex align-items-center gap-2">
{/* FR / EN: nenhuma requisição ao servidor, a página é traduzida novamente no lugar */}
<div className="btn-group btn-group-sm" role="group" aria-label={t('APP.LANGUAGE')}>
{LANGUAGES.map((l) => (
<button key={l} type="button" className={`btn ${i18n.language === l ? 'btn-light' : 'btn-outline-light'}`}
aria-pressed={i18n.language === l} onClick={() => i18n.changeLanguage(l)}>
{l.toUpperCase()}
</button>
))}
</div>
{user && (
<>
<span className="badge text-bg-light text-primary">{user.role}</span>
<span className="text-white">{user.name}</span>
<button type="button" className="btn btn-sm btn-outline-light" onClick={onLogOut}>{t('APP.LOGOUT')}</button>
</>
)}
</div>
</nav>
);
}
|
- linhas 17–18: o componente lê o usuário e a função de logout do store de sessão; ele é reexibido quando o usuário muda (login, logout, sessão expirada);
- linhas 21–24: logout e, em seguida, a página de login. Mesmo que o servidor não responda, o cliente esquece o usuário (veja [stores/session.ts]): o erro é ignorado ([catch(() => {})]);
- linhas 32–37: os menus dependem do papel;
- linha 35: [NavLink] (exemplo 17) define a classe [active] do [Bootstrap] no menu da página exibida;
- linhas 59–64: os botões FR / EN. [i18n.changeLanguage(l)]: nenhuma requisição é enviada ao servidor; a página inteira é renderizada novamente localmente. [aria-pressed]: um leitor de tela anuncia o botão do idioma atual como “pressionado”;
- linhas 67–73: o papel, o nome e o botão de logout.
10.4.9.4. src/components/SuccessMessage.tsx e ErrorPanel.tsx
| // =========================================================================
// components/SuccessMessage.tsx - a mensagem de SUCESSO, no topo da página
// (consulta salva, médico adicionado...) - veja stores/messages.ts.
// role="status": um leitor de tela a anuncia sem interromper o usuário.
// =========================================================================
import { useTranslation } from 'react-i18next';
import { useMessages } from '../stores/messages';
export default function SuccessMessage() {
const { t } = useTranslation();
const success = useMessages((m) => m.success);
return success && <div className="alert alert-success" role="status">{t(success.key, success.params)}</div>;
}
|
| // =========================================================================
// components/ErrorPanel.tsx - o painel de erros, no RODAPÉ de cada página, sobre
// um fundo rosa claro (classe .error-panel, veja styles.css) - como
// views/partials/errors.hbs da aplicação HTML.
// role="alert": um leitor de tela anuncia a mensagem assim que ela aparece.
// =========================================================================
import { useTranslation } from 'react-i18next';
import { useMessages } from '../stores/messages';
export default function ErrorPanel() {
const { t } = useTranslation();
const error = useMessages((m) => m.error);
return error && <div className="error-panel" role="alert">{t(error.key, error.params)}</div>;
}
|
Dois pequenos componentes que exibem as mensagens do store [useMessages], traduzidas para o idioma atual. [role="status"] e [role="alert"]: um leitor de tela anuncia a mensagem assim que ela aparece — discretamente para um sucesso, imediatamente para um erro. Um componente pode retornar [null] (ou [false]): nesse caso, ele não exibe nada.
10.4.9.5. src/components/ConfirmDialog.tsx
| // =========================================================================
// components/ConfirmDialog.tsx
// -------------------------------------------------------------------------
// O diálogo "Are you sure?" do exemplo 16, completado para o teclado
// como public/js/app.js da aplicação HTML:
// - ao abrir, o foco vai para "No, go back": um toque distraído em
// Enter não exclui nada;
// - Escape fecha o diálogo (= Não);
// - Tab e Shift+Tab permanecem DENTRO do diálogo (caso contrário o foco iria para
// a página acinzentada, ao fundo);
// - ao fechar, o foco volta para o elemento que o tinha (o
// botão "Delete" clicado, por exemplo).
// "No, go back" em vez de "Cancel": a pergunta às vezes é "Cancel this
// appointment?", e um botão "Cancel" seria ambíguo nesse caso.
// O componente é colocado uma vez no layout; ele não exibe nada enquanto
// o store de confirmação não tiver nenhuma pergunta (veja stores/confirmation.ts).
// =========================================================================
import { useEffect, useRef, type KeyboardEvent, type MouseEvent } from 'react';
import { createPortal } from 'react-dom';
import { useTranslation } from 'react-i18next';
import { useConfirmation } from '../stores/confirmation';
export default function ConfirmDialog() {
const { t } = useTranslation();
const key = useConfirmation((c) => c.messageKey);
const answer = useConfirmation((c) => c.answer);
const dialog = useRef<HTMLDivElement>(null);
const noButton = useRef<HTMLButtonElement>(null);
// o diálogo abre: memorizamos o elemento que tem o foco e o damos ao
// botão "No"; ele fecha (cleanup): devolvemos o foco
const open = key !== null;
useEffect(() => {
if (!open) return;
const previousFocus = document.activeElement as HTMLElement | null;
noButton.current?.focus();
return () => previousFocus?.focus();
}, [open]);
if (key === null) {
return null; // diálogo fechado: nada a exibir
}
function onKeydown(e: KeyboardEvent<HTMLDivElement>) {
if (e.key === 'Escape') {
answer(false);
} else if (e.key === 'Tab' && dialog.current) {
const buttons = [...dialog.current.querySelectorAll('button')];
const first = buttons[0];
const last = buttons[buttons.length - 1];
if (e.shiftKey && document.activeElement === first) {
e.preventDefault();
last?.focus();
} else if (!e.shiftKey && document.activeElement === last) {
e.preventDefault();
first?.focus();
}
}
}
// um clique no fundo acinzentado (e não no próprio diálogo) = Não
function onBackdropClick(e: MouseEvent<HTMLDivElement>) {
if (e.target === e.currentTarget) {
answer(false);
}
}
return createPortal(
<div onKeyDown={onKeydown}>
<div className="modal-backdrop fade show"></div>
<div ref={dialog} className="modal fade show d-block" tabIndex={-1} role="alertdialog" aria-modal="true"
aria-labelledby="confirmation-title" aria-describedby="confirmation-message" onClick={onBackdropClick}>
<div className="modal-dialog modal-dialog-centered">
<div className="modal-content">
<div className="modal-header">
<h5 id="confirmation-title" className="modal-title">{t('CONFIRMATION.TITLE')}</h5>
<button type="button" className="btn-close" aria-label={t('BOOKING_DIALOG.CLOSE_ARIA')} onClick={() => answer(false)}></button>
</div>
<div className="modal-body">
<p id="confirmation-message" className="mb-0">{t(key)}</p>
</div>
<div className="modal-footer">
<button ref={noButton} type="button" className="btn btn-secondary" onClick={() => answer(false)}>
{t('CONFIRMATION.NO')}
</button>
<button type="button" className="btn btn-danger" onClick={() => answer(true)}>{t('CONFIRMATION.YES')}</button>
</div>
</div>
</div>
</div>
</div>,
document.body,
);
}
|
A janela do Exemplo 16, ligada ao store de confirmação e completada para o teclado:
- linhas 26–27: a pergunta feita ([null]: janela fechada) e a função que a responde;
- linhas 33–39: um efeito que depende de [open]: ao abrir, guarda-se o elemento que tem o foco (o botão “Delete” que foi clicado) e o foco é dado ao botão “No, go back”: um toque acidental em Enter não apaga nada. A limpeza do efeito, executada ao fechar, devolve o foco ao elemento guardado;
- linhas 41–43: janela fechada: nada a exibir. Os hooks são chamados ANTES deste [return]: eles devem ser chamados cada vez que a janela é exibida, na mesma ordem;
- linhas 45–60: Esc significa “Não”. Tab e Shift+Tab mantêm o foco DENTRO da janela: Tab passa do último botão para o primeiro, e vice-versa; caso contrário, o foco iria para a página acinzentada por trás;
- linhas 63–67: um clique no fundo acinzentado é tratado como “Não”. [e.target] é o elemento clicado, e [e.currentTarget] é aquele que guarda o handler: eles são iguais se o clique ocorreu no próprio fundo, e não dentro da janela;
- Linhas 69–94: [createPortal] (Exemplo 16) exibe a janela no final do [<body>], fora da página: nenhum estilo da página pode deformá-la;
- linha 72: para um leitor de tela, uma janela que exige uma resposta urgente; [aria-labelledby] e [aria-describedby] referem-se ao seu título e à sua pergunta.
| // =========================================================================
// components/InputField.tsx - um campo de formulário completo
// -------------------------------------------------------------------------
// Label + campo + mensagem de ajuda OU mensagem de erro. Todos os
// formulários da aplicação o utilizam:
//
// <InputField fieldId="lastName" label="PERSONS.LASTNAME_LABEL" maxLength={20}
// value={form.lastName} onChange={(v) => edit('lastName', v)} error={submission.errors.lastName} />
//
// É um componente CONTROLADO (veja o exemplo 11): o valor pertence ao
// formulário pai. O erro é o retornado pelo SERVIDOR (veja
// hooks/useFormSubmit.ts). label, help e error são CHAVES de
// tradução; params, os parâmetros de suas mensagens ({min}...).
// =========================================================================
import { useTranslation } from 'react-i18next';
interface Props {
fieldId: string; // o id do <input>, vinculado ao <label>
label: string;
value: string;
onChange: (value: string) => void;
error?: string;
help?: string;
params?: Record<string, string>;
type?: 'text' | 'password';
maxLength?: number;
autoComplete?: string;
required?: boolean;
autoFocus?: boolean;
className?: string; // as classes do bloco (mb-3, col-sm-6...)
}
export default function InputField({
fieldId, label, value, onChange, error, help, params = {}, type = 'text', maxLength,
autoComplete = 'off', required = false, autoFocus = false, className = '',
}: Props) {
const { t } = useTranslation();
const messageId = `${fieldId}-message`;
return (
<div className={className}>
<label className="form-label" htmlFor={fieldId}>{t(label)}</label>
<input id={fieldId} type={type} className={`form-control ${error ? 'is-invalid' : ''}`} value={value}
onChange={(e) => onChange(e.target.value)} maxLength={maxLength} autoComplete={autoComplete}
required={required} autoFocus={autoFocus} aria-invalid={error ? true : undefined} aria-describedby={messageId} />
{error ? (
<div className="invalid-feedback" id={messageId}>{t(error, params)}</div>
) : (
help && <div className="form-text" id={messageId}>{t(help, params)}</div>
)}
</div>
);
}
|
Um campo de formulário completo: rótulo, campo, mensagem de ajuda OU mensagem de erro. Todos os formulários da aplicação o utilizam.
- linhas 18–32: suas props; [label], [help] e [error] são props de tradução (CHAVES);
- linhas 34–37: a desestruturação das props, com valores padrão ([type = 'text']);
- linha 39: o identificador da mensagem de ajuda ou de erro, que o [aria-describedby] liga ao campo; um leitor de tela o lê junto com o campo;
- linhas 44–46: um campo CONTROLADO (exemplo 05): seu valor pertence ao formulário pai, que o recebe por meio de [onChange]. [is-invalid]: a caixa vermelha do [Bootstrap];
- linhas 47–51: o erro retornado pelo servidor ou, na falta dele, o texto de ajuda.
10.4.9.7. src/components/PersonFields.tsx
| // =========================================================================
// components/PersonFields.tsx - título, nome, sobrenome
// -------------------------------------------------------------------------
// Os campos de identidade, comuns a três formulários: o formulário de médico / cliente
// do ADMIN, "Create a patient account" e "Manage my account" (o equivalente da
// partial views/partials/personFields.hbs). O pai lhe passa os
// valores, os erros e a função que modifica um campo:
// <PersonFields values={form} errors={submission.errors} onChange={edit} />
// =========================================================================
import { useTranslation } from 'react-i18next';
import type { Identity } from '../api/types';
import InputField from './InputField';
const TITLES = ['Mr', 'Mme', 'Melle'];
interface Props {
values: Identity;
errors: Record<string, string>;
onChange: (field: keyof Identity, value: string) => void;
}
export default function PersonFields({ values, errors, onChange }: Props) {
const { t } = useTranslation();
return (
<>
<div className="mb-3">
<label className="form-label" htmlFor="title">{t('PERSONS.TITLE_LABEL')}</label>
<select id="title" className={`form-select ${errors.title ? 'is-invalid' : ''}`} value={values.title}
onChange={(e) => onChange('title', e.target.value)}>
{TITLES.map((title) => <option key={title}>{title}</option>)}
</select>
{errors.title && <div className="invalid-feedback">{t(errors.title)}</div>}
</div>
<div className="row g-3 mb-3">
<InputField className="col-sm-6" fieldId="firstName" label="PERSONS.FIRSTNAME_LABEL" maxLength={20} required
value={values.firstName} onChange={(v) => onChange('firstName', v)} error={errors.firstName} />
<InputField className="col-sm-6" fieldId="lastName" label="PERSONS.LASTNAME_LABEL" maxLength={20} required
value={values.lastName} onChange={(v) => onChange('lastName', v)} error={errors.lastName} />
</div>
</>
);
}
|
Título, nome e sobrenome: campos comuns a três formulários (médico ou cliente do ADMIN, criação de conta, gerenciamento de conta). O equivalente da view parcial [views/partials/personFields.hbs] da aplicação HTML.
- Linha 20: [keyof Identity]: type ['title' | 'firstName' | 'lastName']; o compilador rejeita qualquer outro nome de campo;
- linha 31: um [<option>] sem [value] tem seu texto como valor.
10.4.9.8. src/components/CaptchaField.tsx
| // =========================================================================
// components/CaptchaField.tsx - a imagem do CAPTCHA e o campo de entrada
// -------------------------------------------------------------------------
// Um componente de exibição: a imagem (svg), o link "Another image"
// (onReload) e o campo, CONTROLADO pelo formulário pai (value,
// onChange). A imagem e seu identificador vêm do hook useCaptcha, que
// o pai chama (veja pages/Login.tsx): é o pai que precisa deles
// para enviar a resposta.
//
// dangerouslySetInnerHTML: a imagem SVG é inserida como está. Sem
// perigo AQUI porque ela é criada pelo nosso servidor (biblioteca
// svg-captcha) e não contém nada que venha de um usuário - veja o
// exemplo 22.
// =========================================================================
import { useTranslation } from 'react-i18next';
interface Props {
svg: string;
value: string;
onChange: (value: string) => void;
onReload: () => void;
error?: string;
}
export default function CaptchaField({ svg, value, onChange, onReload, error }: Props) {
const { t } = useTranslation();
return (
<div className="mb-3">
<label className="form-label" htmlFor="captcha">{t('CAPTCHA.LABEL')}</label>
<div className="d-flex align-items-center gap-3 mb-2">
<div className="captcha-image" role="img" aria-label={t('CAPTCHA.IMAGE_ALT')} dangerouslySetInnerHTML={{ __html: svg }} />
<button type="button" className="btn btn-link btn-sm p-0" onClick={onReload}>{t('CAPTCHA.NEW_IMAGE')}</button>
</div>
<input id="captcha" type="text" maxLength={10} autoComplete="off" autoCapitalize="off" spellCheck={false}
className={`form-control ${error ? 'is-invalid' : ''}`} value={value} onChange={(e) => onChange(e.target.value)} />
{error ? <div className="invalid-feedback">{t(error)}</div> : <div className="form-text">{t('CAPTCHA.HELP')}</div>}
</div>
);
}
|
Um componente de exibição: a imagem, o botão “Another image” e o campo, controlado pelo formulário pai. A imagem e seu identificador vêm do hook [useCaptcha], que a página chama: a página precisa dele para enviar a resposta.
- Linha 32: a imagem SVG é inserida tal como está (Exemplo 22). Seguro AQUI: ela é gerada pelo nosso servidor e não contém nada fornecido por um usuário. [role="img"] e [aria-label]: para um leitor de tela, isso é uma imagem com sua descrição;
- linha 35: [autoCapitalize="off"] e [spellCheck={false}]: sem capitalização automática (celulares) nem verificação ortográfica.
10.4.9.9. src/components/BookingDialog.tsx
| // =========================================================================
// components/BookingDialog.tsx - o diálogo de reserva de um horário
// -------------------------------------------------------------------------
// Mesmo diálogo de views/partials/booking.hbs da aplicação HTML:
// as classes Bootstrap de um diálogo modal, exibido "fixo no código" (show
// d-block).
//
// O componente não conversa com o servidor: ele chama
// - onConfirm, com o paciente escolhido (null para um paciente que reserva
// para si mesmo);
// - onClose.
// É a página da agenda que decide o que fazer com isso (pages/Schedule.tsx).
// =========================================================================
import { useEffect, useState, type FormEvent, type MouseEvent } from 'react';
import { createPortal } from 'react-dom';
import { useTranslation } from 'react-i18next';
import type { Person } from '../api/types';
import { label } from '../formatting';
interface Props {
time: string; // "8:00 - 8:20"
clients: readonly Person[]; // ADMIN / DOCTOR: os pacientes entre os quais escolher
patient: string | null; // USER: o paciente é o próprio usuário
submitting: boolean;
onConfirm: (clientId: number | null) => void;
onClose: () => void;
}
export default function BookingDialog({ time, clients, patient, submitting, onConfirm, onClose }: Props) {
const { t } = useTranslation();
const [clientId, setClientId] = useState<number | null>(null);
// Escape, em qualquer lugar da página: fechamos
useEffect(() => {
const onKeydown = (e: globalThis.KeyboardEvent) => {
if (e.key === 'Escape') onClose();
};
document.addEventListener('keydown', onKeydown);
return () => document.removeEventListener('keydown', onKeydown);
}, [onClose]);
function confirm(e: FormEvent<HTMLFormElement>) {
e.preventDefault();
onConfirm(clientId);
}
// um clique no fundo acinzentado (e não no próprio diálogo) fecha o diálogo
function onBackdropClick(e: MouseEvent<HTMLDivElement>) {
if (e.target === e.currentTarget) {
onClose();
}
}
return createPortal(
<>
<div className="modal-backdrop fade show"></div>
<div className="modal fade show d-block" tabIndex={-1} role="dialog" aria-modal="true" aria-labelledby="booking-title"
onClick={onBackdropClick}>
<div className="modal-dialog modal-dialog-centered">
<form className="modal-content" onSubmit={confirm}>
<div className="modal-header">
<h5 id="booking-title" className="modal-title">{t('BOOKING_DIALOG.TITLE')}</h5>
<button type="button" className="btn-close" aria-label={t('BOOKING_DIALOG.CLOSE_ARIA')} onClick={onClose}></button>
</div>
<div className="modal-body">
<p>{t('BOOKING_DIALOG.SLOT', { time })}</p>
{/* um paciente que reserva para si mesmo: sem lista (e o servidor
ignoraria de qualquer forma um eventual clientId) */}
{patient !== null ? (
<p className="mb-0">{t('BOOKING_DIALOG.PATIENT_LABEL')}: <strong>{patient}</strong></p>
) : (
<>
<label className="form-label" htmlFor="clientId">{t('BOOKING_DIALOG.PATIENT_LABEL')}</label>
{/* autoFocus: ao ser exibido, o foco fica na lista */}
<select id="clientId" className="form-select" autoFocus value={clientId ?? ''}
onChange={(e) => setClientId(e.target.value === '' ? null : Number(e.target.value))}>
<option value="">{t('BOOKING_DIALOG.CHOOSE_PATIENT')}</option>
{clients.map((c) => <option key={c.id} value={c.id}>{label(c)}</option>)}
</select>
</>
)}
</div>
<div className="modal-footer">
<button type="button" className="btn btn-secondary" onClick={onClose}>{t('BOOKING_DIALOG.CANCEL')}</button>
{/* sem lista, é o botão de confirmação que fica com o foco */}
<button type="submit" className="btn btn-primary" autoFocus={patient !== null} disabled={submitting}>
{t('BOOKING_DIALOG.CONFIRM')}
</button>
</div>
</form>
</div>
</div>
</>,
document.body,
);
}
|
A janela de reserva de consulta. Ela não se comunica com o servidor: chama [onConfirm] com o paciente selecionado ou [onClose]; a página da agenda decide o que fazer com isso.
- Linhas 21–28: [clients]: a lista de pacientes, para o ADMIN e os médicos; [patient]: o nome do paciente que marca a consulta para si mesmo ([null] para o ADMIN e os médicos);
- linha 32: o paciente selecionado na lista;
- linhas 35–41: Esc, em qualquer lugar da página, fecha a janela. O efeito se inscreve no evento [keydown] do documento, e sua limpeza cancela a inscrição ao fechar. [globalThis.KeyboardEvent]: o evento do navegador, não o do [React], que tem o mesmo nome;
- linhas 43–46: [preventDefault()] impede o navegador de enviar o formulário;
- linhas 71–83: um paciente faz uma reserva para si mesmo: sem lista. De qualquer forma, o servidor ignoraria qualquer [clientId];
- linha 78: o valor de um [<option>] é sempre uma string: ele é convertido em número;
- linha 89: sem lista, o botão de confirmação recebe o foco.
10.4.10. As páginas
10.4.10.1. src/pages/Login.tsx
| // =========================================================================
// pages/Login.tsx - a página de login (/login)
// -------------------------------------------------------------------------
// Mesma página de views/login.hbs da aplicação HTML: login, senha,
// CAPTCHA, e um segundo botão "Create a patient account" que verifica o
// MESMO CAPTCHA antes de abrir a criação de conta.
//
// /login?login=jbernard: o campo de login vem preenchido (logo após a
// criação de uma conta).
// /login?redirect=/doctors: após o login, esta página é aberta
// (deixada pelo guard do roteador) em vez da página inicial do papel.
// =========================================================================
import { useState, type FormEvent } from 'react';
import { useNavigate, useSearchParams } from 'react-router';
import { useTranslation } from 'react-i18next';
import { api } from '../api/rdvmedecins.api';
import { homePage, useSession } from '../stores/session';
import { useMessages } from '../stores/messages';
import { useFormSubmit } from '../hooks/useFormSubmit';
import { useCaptcha } from '../hooks/useCaptcha';
import CaptchaField from '../components/CaptchaField';
import PageTitle from '../components/PageTitle';
export default function Login() {
const { t } = useTranslation();
const [params] = useSearchParams();
const navigate = useNavigate();
const logIn = useSession((s) => s.logIn);
const clearMessages = useMessages((m) => m.clear);
const submission = useFormSubmit();
const captcha = useCaptcha();
// o login da URL, se houver: o valor INICIAL do campo
const urlLogin = (params.get('login') ?? '').slice(0, 30);
const [form, setForm] = useState({ login: urlLogin, password: '', captcha: '' });
function edit(field: keyof typeof form, value: string) {
setForm((f) => ({ ...f, [field]: value }));
submission.clearError(field);
}
// os dois botões compartilham esta sequência: envio e, em caso de falha,
// mensagem de erro e NOVA imagem (cada uma só pode ser usada uma vez)
async function attempt(action: () => Promise<unknown>): Promise<void> {
clearMessages();
const succeeded = await submission.submit(action);
if (!succeeded) {
setForm((f) => ({ ...f, captcha: '' }));
await captcha.reload();
}
}
async function onLogIn(e: FormEvent<HTMLFormElement>) {
e.preventDefault();
await attempt(async () => {
await logIn(form.login.trim(), form.password, captcha.captchaId, form.captcha);
const redirect = params.get('redirect');
// apenas um caminho INTERNO: nunca um redirecionamento para outro site
const internal = redirect !== null && redirect.startsWith('/') && !redirect.startsWith('//');
await navigate(internal ? redirect : homePage(useSession.getState().user));
});
}
async function createAccount() {
await attempt(async () => {
await api.registrationAccess(captcha.captchaId, form.captcha);
await navigate('/register');
});
}
return (
<div className="row justify-content-center">
<PageTitle titleKey="LOGIN.TITLE" />
<div className="col-sm-8 col-md-6 col-lg-5">
<div className="card p-4">
<h5 className="card-title mb-3">{t('LOGIN.TITLE')}</h5>
<form onSubmit={onLogIn}>
<div className="mb-3">
<label className="form-label" htmlFor="login">{t('LOGIN.LOGIN_LABEL')}</label>
{/* required: o navegador recusa enviar o formulário enquanto o campo estiver vazio.
autoFocus: o foco no login... ou na senha se o login já estiver preenchido */}
<input id="login" type="text" className="form-control" autoComplete="username" required
autoFocus={urlLogin === ''} value={form.login} onChange={(e) => edit('login', e.target.value)} />
</div>
<div className="mb-3">
<label className="form-label" htmlFor="password">{t('LOGIN.PASSWORD_LABEL')}</label>
<input id="password" type="password" className="form-control" autoComplete="current-password" required
autoFocus={urlLogin !== ''} value={form.password} onChange={(e) => edit('password', e.target.value)} />
</div>
<CaptchaField svg={captcha.svg} value={form.captcha} onChange={(v) => edit('captcha', v)}
onReload={captcha.reload} error={submission.errors.captcha} />
{/* type="submit": Enter em um campo aciona "Log in" */}
<button type="submit" className="btn btn-primary w-100" disabled={submission.submitting}>{t('LOGIN.SUBMIT')}</button>
{/* type="button": este botão não envia o formulário (e portanto
ignora os campos required, inútil aqui) */}
<button type="button" className="btn btn-outline-primary w-100 mt-3" disabled={submission.submitting} onClick={createAccount}>
{t('LOGIN.CREATE_ACCOUNT')}
</button>
<div className="form-text text-center">{t('LOGIN.CREATE_ACCOUNT_HELP')}</div>
</form>
<div className="text-muted small mt-3">
{t('LOGIN.DEMO_ACCOUNTS')}
<ul className="mb-0 mt-1">
<li><code>admin</code> - {t('LOGIN.DEMO_ADMIN')}</li>
<li><code>pelissier</code>, <code>tatou</code>, <code>dupont</code> - {t('LOGIN.DEMO_DOCTOR')}</li>
<li><code>martin</code>, <code>durand</code>, <code>bistrou</code>, <code>german</code> - {t('LOGIN.DEMO_USER')}</li>
</ul>
</div>
</div>
</div>
</div>
);
}
|
A página [views/login.hbs] da aplicação HTML: login, senha, CAPTCHA e um segundo botão "Create a patient account" que verifica o MESMO CAPTCHA antes de permitir o início do processo de criação da conta.
- Linhas 29–32: o que a página precisa: login (armazenamento da sessão), limpeza das mensagens, envio do formulário e o CAPTCHA (nossos dois hooks);
- Linhas 35–36: [/login?login=jbernard]: imediatamente após a criação de uma conta, o nome de usuário vem preenchido. [slice(0, 30)]: não recuperamos mais do que o comprimento máximo de um nome de usuário. A URL fornece apenas o valor INICIAL do campo;
- linhas 38–41: quando um campo é digitado, seu novo valor aparece e qualquer mensagem de erro desaparece. [[field]: value]: uma propriedade cujo nome é calculado;
- linhas 45–52: os dois botões seguem a mesma sequência: enviar e, se isso falhar, limpar o CAPTCHA e carregar uma NOVA imagem; cada uma é usada uma única vez;
- linhas 54–63: login e, em seguida, a próxima página:
- linha 58: a página solicitada antes do login, guardada pelo roteador ([/login?redirect=/doctors]);
- linha 60: SOMENTE um caminho interno: [/doctors], mas não [https://malicious-site.com] nem [//malicious-site.com] (um endereço “sem protocolo”, que aponta para outro site). Caso contrário, um link malicioso como [/login?redirect=https://...] enviaria o usuário — que acabou de fazer login — para outro site: essa é a chamada vulnerabilidade de “redirecionamento aberto”;
- linha 61: caso contrário, a página inicial do papel. [useSession.getState()]: o usuário ACABOU de ser armazenado no store; a variável de um componente, porém, só mudará no próximo carregamento da página;
- linhas 65–70: o segundo botão: o CAPTCHA é verificado pelo servidor, que retorna um token (um cookie) para a página [/register];
- linhas 84–85: [required]: o navegador se recusa a enviar o formulário enquanto o campo estiver vazio. Essa é a única validação feita no navegador — é apenas uma comodidade. [autoFocus]: o foco fica no campo de nome de usuário ou, se ele já estiver preenchido, no campo de senha (linha 90);
- linha 97: [type="submit"]: digitar em um campo aciona o botão “Log in”;
- linha 101: [type="button"]: este botão não envia o formulário e, portanto, ignora os campos [required], que aqui são desnecessários.
10.4.10.2. src/pages/Schedule.tsx
A página mais rica em funcionalidades da aplicação. Como na aplicação HTML, TODO o seu estado está na URL:
| /schedule?doctorId=1&day=2026-10-05 the schedule
/schedule?doctorId=1&day=2026-10-05&book=7 + the booking dialog
|
A página SEGUE a URL: ela lê seus parâmetros e os usa para determinar o que exibir; as ações do usuário, por sua vez, modificam a URL. Isso permite recarregar a página, adicioná-la aos favoritos e usar os botões Voltar e Avançar do navegador.
| // =========================================================================
// pages/Schedule.tsx - a página da agenda (/schedule)
// -------------------------------------------------------------------------
// Três blocos, como views/schedule.hbs da aplicação HTML:
// 1. a escolha do médico e do dia;
// 2. a agenda desse médico nesse dia;
// 3. o diálogo de reserva de um horário.
//
// Como na aplicação HTML, TODO o estado da página está em sua URL:
// /schedule?doctorId=1&day=2026-10-05 a agenda
// /schedule?doctorId=1&day=2026-10-05&book=7 + o diálogo de reserva
// A página pode, portanto, ser recarregada, favoritada, e os botões Voltar /
// Avançar do navegador funcionam. A página SEGUE sua URL: ela lê seus
// três parâmetros (useSearchParams) e deduz deles o que exibe;
// a agenda é uma query do TanStack Query cuja chave contém o médico
// e o dia (veja o exemplo 24); as ações do usuário, por sua vez,
// mudam a URL (navigate).
//
// O que cada usuário vê e pode fazer é decidido pelo SERVIDOR (campos
// patient, mine, bookable, appointmentId de cada horário): a página apenas
// o exibe. Um paciente nem sequer recebe os nomes dos outros pacientes.
// =========================================================================
import { useCallback, useEffect, useState, type FormEvent } from 'react';
import { Link, useNavigate, useSearchParams } from 'react-router';
import { useQuery, useQueryClient } from '@tanstack/react-query';
import { useTranslation } from 'react-i18next';
import { ApiError } from '../api/api-error';
import { api } from '../api/rdvmedecins.api';
import type { ScheduleSlot, Person } from '../api/types';
import { today, isValidDate, timeRange, longDate, label } from '../formatting';
import { isManager, isPatient, useSession } from '../stores/session';
import { useMessages } from '../stores/messages';
import { confirm } from '../stores/confirmation';
import BookingDialog from '../components/BookingDialog';
import PageTitle from '../components/PageTitle';
// "3" -> 3; "", "abc", "-2", ausente (null) -> null
function positiveInteger(value: string | null): number | null {
const n = Number(value);
return value !== null && value !== '' && Number.isInteger(n) && n > 0 ? n : null;
}
// o endereço da agenda (sem o diálogo de reserva, ou com ele)
function scheduleUrl(doctorId: number | null, day: string, book?: number): string {
const params = new URLSearchParams({ doctorId: String(doctorId ?? ''), day });
if (book !== undefined) {
params.set('book', String(book));
}
return `/schedule?${params}`;
}
// -------------------------------------------------------------------------
// 1. a escolha do médico e do dia: um pequeno formulário, cujo estado só
// é usado antes do envio. Ele COMEÇA com os valores da URL; a página lhe dá
// uma key que muda com eles: o React então o recria, e ele
// recomeça a partir dos novos valores (botão Voltar...).
// -------------------------------------------------------------------------
interface PickerProps {
doctors: Person[];
doctorId: number | null;
day: string;
onView: (doctorId: number | null, day: string) => void;
}
function DoctorDayPicker({ doctors, doctorId, day, onView }: PickerProps) {
const { t } = useTranslation();
const [chosenDoctor, setChosenDoctor] = useState(doctorId);
const [chosenDay, setChosenDay] = useState(day);
function view(e: FormEvent<HTMLFormElement>) {
e.preventDefault();
onView(chosenDoctor, chosenDay);
}
return (
<form className="card p-3 mb-3" onSubmit={view}>
<div className="row g-2 align-items-end">
<div className="col-sm-5">
<label className="form-label" htmlFor="doctorId">{t('DOCTOR_DAY_PICKER.DOCTOR_LABEL')}</label>
<select id="doctorId" className="form-select" required value={chosenDoctor ?? ''}
onChange={(e) => setChosenDoctor(positiveInteger(e.target.value))}>
<option value="">{t('DOCTOR_DAY_PICKER.CHOOSE_DOCTOR')}</option>
{doctors.map((d) => <option key={d.id} value={d.id}>{label(d)}</option>)}
</select>
</div>
<div className="col-sm-4">
<label className="form-label" htmlFor="day">{t('DOCTOR_DAY_PICKER.DAY_LABEL')}</label>
<input id="day" type="date" className="form-control" required value={chosenDay}
onChange={(e) => setChosenDay(e.target.value)} />
</div>
<div className="col-sm-3">
<button type="submit" className="btn btn-primary w-100">{t('DOCTOR_DAY_PICKER.VIEW_SCHEDULE')}</button>
</div>
</div>
</form>
);
}
// -------------------------------------------------------------------------
// a página
// -------------------------------------------------------------------------
export default function Schedule() {
const { t, i18n } = useTranslation();
const navigate = useNavigate();
const queryClient = useQueryClient();
const user = useSession((s) => s.user);
// as ações do store de mensagens: funções que nunca
// mudam; getState() as fornece sem inscrever a página nas mensagens
const { showSuccess, showError, showApiError, flash } = useMessages.getState();
const [submitting, setSubmitting] = useState(false);
// os parâmetros da URL
const [params] = useSearchParams();
const urlDoctorId = positiveInteger(params.get('doctorId'));
const urlDay = params.get('day');
const bookId = positiveInteger(params.get('book'));
// o dia: o da URL se for válido, caso contrário hoje
const invalidDay = urlDay !== null && !isValidDate(urlDay);
const day = urlDay !== null && !invalidDay ? urlDay : today();
// as listas: os médicos para todos; os pacientes só para quem
// pode lê-los (ADMIN, DOCTOR: diálogo de reserva)
const doctors = useQuery({ queryKey: ['doctors'], queryFn: () => api.list('doctors') });
const clients = useQuery({
queryKey: ['clients'],
queryFn: () => api.list('clients'),
enabled: isManager(user),
});
// a agenda: sem médico na URL, um DOCTOR vê a agenda DELE (o
// servidor a encontra a partir do token); os demais não veem nada
const withSchedule = !invalidDay && (urlDoctorId !== null || user?.role === 'DOCTOR');
const schedule = useQuery({
queryKey: ['schedule', urlDoctorId, day],
queryFn: () => api.schedule(urlDoctorId, day),
enabled: withSchedule,
});
const s = withSchedule ? schedule.data : undefined;
// o médico exibido: o da URL, ou o da agenda recebida (DOCTOR)
const doctorId = urlDoctorId ?? s?.doctor.id ?? null;
// uma data inválida na URL: uma mensagem (um EFEITO: ele age sobre o
// store de mensagens, não sobre a renderização deste componente)
useEffect(() => {
if (invalidDay) {
showError('ERRORS.INVALID_DATE');
}
}, [invalidDay, showError]);
// o horário cujo diálogo de reserva está aberto (?book=7),
// somente se puder ser reservado por este usuário
const slotToBook = s?.slots.find((c) => c.id === bookId && c.bookable) ?? null;
// o nome do paciente logado (USER), ou null para ADMIN e DOCTOR
const patient = isPatient(user) ? (user?.name ?? '') : null;
// -----------------------------------------------------------------------
// ações
// -----------------------------------------------------------------------
// "View schedule": mudamos a URL, a página a segue
function viewSchedule(chosenDoctorId: number | null, chosenDay: string) {
navigate(scheduleUrl(chosenDoctorId, chosenDay));
}
// useCallback: a MESMA função de uma renderização para a outra (o diálogo
// de reserva a usa nas dependências de um efeito)
const closeBooking = useCallback(() => navigate(scheduleUrl(doctorId, day)), [navigate, doctorId, day]);
// o servidor é a referência: após cada ação, a agenda é lida novamente
// (e a área do paciente, que mostra sua consulta)
const reload = () =>
Promise.all([queryClient.invalidateQueries({ queryKey: ['schedule'] }), queryClient.invalidateQueries({ queryKey: ['my-area'] })]);
async function confirmBooking(clientId: number | null) {
if (slotToBook === null) {
return;
}
setSubmitting(true);
try {
await api.book(day, slotToBook.id, isManager(user) ? clientId : null);
flash('success', 'SCHEDULE.BOOKED');
} catch (e) {
if (e instanceof ApiError && e.key === 'ERRORS.CHOOSE_PATIENT') {
// nenhum paciente escolhido: o diálogo permanece aberto
showError(e.key);
return; // (o finally é executado de qualquer jeito)
}
if (!(e instanceof ApiError)) {
throw e;
}
// horário ocupado nesse meio-tempo, paciente que já tem uma consulta...:
// a mensagem será exibida na agenda, com o diálogo fechado
flash('error', e.key, e.params);
} finally {
setSubmitting(false);
}
await closeBooking();
await reload();
}
async function cancel(c: ScheduleSlot) {
if (c.appointmentId === null || !(await confirm('SCHEDULE.CANCEL_CONFIRM'))) {
return;
}
try {
await api.cancelAppointment(c.appointmentId);
showSuccess('SCHEDULE.CANCELLED');
} catch (e) {
showApiError(e);
}
await reload();
}
// -----------------------------------------------------------------------
// renderização
// -----------------------------------------------------------------------
let content;
if (schedule.isLoading && !s) {
content = <p className="text-muted">{t('APP.LOADING')}</p>;
} else if (s) {
content = (
<div className="card p-3">
<h5>{t('SCHEDULE.TITLE_PREFIX')} {longDate(s.day, i18n.language)} - {label(s.doctor)}</h5>
{s.slots.length > 0 ? (
<table className="table table-hover align-middle">
<thead>
<tr>
<th>{t('SCHEDULE.COLUMN_SLOT')}</th>
<th>{t('SCHEDULE.COLUMN_STATUS')}</th>
<th></th>
</tr>
</thead>
<tbody>
{s.slots.map((c) => (
<tr key={c.id} className={c.bookable ? 'free-slot' : ''}>
<td>{timeRange(c)}</td>
<td>
{c.free ? (
<span className="badge text-bg-success">{t('SCHEDULE.FREE')}</span>
) : c.patient ? (
<span className={`badge ${c.mine ? 'text-bg-primary' : 'text-bg-secondary'}`}>{label(c.patient)}</span>
) : (
<span className="badge text-bg-secondary">{t('SCHEDULE.BOOKED_BY_OTHER')}</span>
)}
</td>
<td className="text-end">
{/* "Book" é um LINK: ele acrescenta &book=... à URL, o que
abre o diálogo de reserva */}
{c.bookable && (
<Link className="btn btn-sm btn-outline-success" to={scheduleUrl(doctorId, day, c.id)}>
{t('SCHEDULE.BOOK')}
</Link>
)}
{c.appointmentId !== null && (
<button type="button" className="btn btn-sm btn-outline-danger" onClick={() => cancel(c)}>
{t('SCHEDULE.CANCEL_APPOINTMENT')}
</button>
)}
</td>
</tr>
))}
</tbody>
</table>
) : (
<p className="text-muted mb-0">{t('SCHEDULE.NO_SLOTS')}</p>
)}
</div>
);
} else {
content = <p className="text-muted">{t('SCHEDULE.EMPTY_STATE')}</p>;
}
return (
<>
<PageTitle titleKey="SCHEDULE.PAGE_TITLE" />
<DoctorDayPicker key={`${doctorId}|${day}`} doctors={doctors.data ?? []} doctorId={doctorId} day={day}
onView={viewSchedule} />
{/* paciente que já tem uma consulta futura: por isso não há botão "Book" */}
{s?.info && (
<div className="alert alert-info">
{t(s.info)} <Link to="/my-area" className="alert-link">{t('APP.MENU_MY_AREA')}</Link>
</div>
)}
{content}
{/* 3. o diálogo de reserva, somente se a URL contiver &book=... */}
{slotToBook && (
<BookingDialog time={timeRange(slotToBook)} clients={clients.data ?? []} patient={patient}
submitting={submitting} onConfirm={confirmBooking} onClose={closeBooking} />
)}
</>
);
}
|
- linhas 39–42: um parâmetro da URL é uma string digitada por qualquer pessoa; apenas um inteiro positivo é aceito;
- linhas 45–51: a URL da agenda, com ou sem janela de reserva;
- linhas 66–98: o formulário de seleção de médico e data, um componente do mesmo arquivo. Seu estado só é usado antes do envio: ele é preenchido com os valores da URL (linhas 68–69). No entanto, [useState(value)] só usa seu valor durante a exibição: se a URL mudar (pelo botão “Voltar”), o formulário manteria a seleção anterior. Daí a key que a página lhe atribui, mais abaixo;
- linhas 114–120: os parâmetros da URL. O dia: o dia da URL, se for válido, ou o dia de hoje;
- linhas 124–129: as listas, com o [TanStack Query] (exemplo 24). A chave [['doctors']] refere-se aos dados no cache: outra página que solicite a mesma chave os recebe sem nova requisição. [enabled]: pacientes, apenas para quem está autorizado a vê-los (ADMIN e médicos, para a janela de consulta); para um paciente, a requisição não é enviada;
- linhas 133–138: a agenda. Sua chave contém o médico e o dia: quando a URL muda, a chave muda e o [TanStack Query] envia a nova requisição por conta própria. Se não há médico na URL, um médico logado vê a SUA PRÓPRIA agenda; os demais não veem nada;
- linha 141: o médico exibido: o da URL ou, na falta dele, o da agenda recebida;
- linhas 145–149: uma data inválida na URL: uma mensagem. Isso é um EFEITO: atuamos sobre o store de mensagens, não sobre a exibição deste componente. Nunca modificamos outro estado enquanto a exibição está ativa;
- linha 153: o horário cuja janela de reserva está aberta ([?book=7]), somente se puder ser reservado por este usuário: uma URL criada manualmente não abre nada;
- linhas 162–164: “View schedule” muda a URL; a página se atualiza de acordo;
- linha 168: fechar a janela leva de volta à URL da agenda. [useCallback]: a MESMA função de uma exibição para a seguinte, porque a janela de reserva a usa nas dependências de um efeito (veja [BookingDialog.tsx]): uma nova função a cada exibição acionaria o efeito todas as vezes;
- Linhas 172–173: os dados do servidor têm precedência: após cada ação, a agenda (e a área do paciente, que exibe sua consulta) é atualizada. [TanStack Query] relê imediatamente os dados exibidos; os dados que não estão exibidos serão relidos na próxima vez que forem usados;
- linhas 175–200: a reserva:
- linha 181: o ADMIN e os médicos enviam o paciente selecionado; um paciente faz a reserva para si mesmo;
- Linha 182: a mensagem aparecerá após a ação de navegação que fecha a janela;
- Linhas 184–188: nenhum paciente selecionado: a janela permanece aberta, exibindo a mensagem. [return] dentro de um [try]: o bloco [finally] é executado de qualquer maneira;
- linha 194: os demais erros (horário já ocupado, paciente que já tem uma consulta etc.) serão exibidos na agenda, com a janela fechada;
- linhas 202–213: o cancelamento, após confirmação: [await confirm(...)] espera a resposta do usuário (veja [stores/confirmation.ts]);
- linhas 218–272: o conteúdo principal, calculado antes do JSX: uma mensagem de espera, a agenda ou um convite para selecionar um médico. Um [if / else] comum costuma ser mais legível do que uma cascata de [? :] dentro do JSX;
- linhas 239–245: o status do horário: disponível, o nome do paciente (em azul se for o paciente logado) ou “Booked”: um paciente NÃO recebe os nomes dos outros pacientes; o servidor não os envia;
- linhas 250–254: “Book” é um LINK, [<Link>]: ele acrescenta [&book=...] à URL, o que abre a janela de reserva;
- linha 255: “Cancel”, se o servidor indicou que o usuário pode cancelar esta consulta;
- linha 277: a key do formulário contém o médico e o dia. Quando eles mudam, a key muda: o [React] destrói o formulário e cria um novo, que começa com os novos valores. É assim que o [React] “reinicia” um componente;
- Linhas 281–285: um paciente que já tem uma consulta futura: isso explica por que não há botão “Book”;
- linhas 290–293: a janela de reserva aparece apenas se a URL contiver [&book=...].
10.4.10.3. src/pages/persons.config.ts
| // =========================================================================
// pages/persons.config.ts - médicos ou clientes?
// -------------------------------------------------------------------------
// As páginas de gerenciamento dos médicos e dos clientes são IDÊNTICAS: mesma
// lista, mesmo formulário. Como na aplicação HTML (classe abstrata
// PersonsController), elas são escritas UMA vez (Persons.tsx,
// PersonForm.tsx); apenas o endereço da API e as
// chaves dos rótulos mudam, descritos aqui. O roteador passa o tipo a cada página
// (veja routes.tsx).
// =========================================================================
import type { PersonType } from '../api/rdvmedecins.api';
export interface PersonKeys {
title: string; // "Doctors"
add: string; // "Add a doctor"
edit: string; // "Edit a doctor"
empty: string; // "No doctor."
confirmDelete: string;
added: string; // "Doctor {name} has been added (login: {login})."
edited: string;
deleted: string;
}
export const PERSON_KEYS: Record<PersonType, PersonKeys> = {
doctors: {
title: 'DOCTORS.TITLE',
add: 'DOCTORS.ADD',
edit: 'DOCTORS.EDIT',
empty: 'DOCTORS.EMPTY',
confirmDelete: 'DOCTORS.DELETE_CONFIRM',
added: 'DOCTORS.ADDED',
edited: 'DOCTORS.UPDATED',
deleted: 'DOCTORS.DELETED',
},
clients: {
title: 'CLIENTS.TITLE',
add: 'CLIENTS.ADD',
edit: 'CLIENTS.EDIT',
empty: 'CLIENTS.EMPTY',
confirmDelete: 'CLIENTS.DELETE_CONFIRM',
added: 'CLIENTS.ADDED',
edited: 'CLIENTS.UPDATED',
deleted: 'CLIENTS.DELETED',
},
};
// {name} e {login} das mensagens "added / updated / deleted"
export function messageParams(p: { firstName: string; lastName: string; login?: string }): Record<string, string> {
return { name: `${p.firstName} ${p.lastName}`, login: p.login ?? '' };
}
|
As páginas de gerenciamento de médicos e de clientes são IDÊNTICAS: mesma lista, mesmo formulário. Como na aplicação HTML (classe abstrata [PersonsController]), elas são escritas UMA ÚNICA VEZ; as únicas coisas que mudam são o endereço da API (o tipo, ['doctors'] ou ['clients']) e as chaves dos rótulos, descritas aqui.
- linhas 14–23: as chaves de tradução específicas de cada tipo;
- linha 25: [Record<PersonType, PersonKeys>]: um objeto que tem exatamente uma propriedade por tipo; [doctors] e [clients]: o compilador acusa um elemento ausente;
- linhas 49–51: os parâmetros [{{name}}] e [{{login}}] das mensagens de “adicionado / modificado / excluído”.
10.4.10.4. src/pages/Persons.tsx
| // =========================================================================
// pages/Persons.tsx - a lista dos médicos OU dos clientes (ADMIN)
// -------------------------------------------------------------------------
// Uma única página para ambos: o tipo ('doctors' ou 'clients') chega
// como prop (veja routes.tsx); os rótulos específicos de cada um estão em
// persons.config.ts. Equivalente de views/persons/list.hbs da
// aplicação HTML.
// =========================================================================
import { Link } from 'react-router';
import { useQuery, useQueryClient } from '@tanstack/react-query';
import { useTranslation } from 'react-i18next';
import { api, type PersonType } from '../api/rdvmedecins.api';
import type { Person } from '../api/types';
import { useMessages } from '../stores/messages';
import { confirm } from '../stores/confirmation';
import PageTitle from '../components/PageTitle';
import { PERSON_KEYS, messageParams } from './persons.config';
export default function Persons({ type }: { type: PersonType }) {
const { t } = useTranslation();
const queryClient = useQueryClient();
const keys = PERSON_KEYS[type];
// a lista; a key contém o tipo: médicos e clientes têm cada um a sua
const persons = useQuery({ queryKey: [type], queryFn: () => api.list(type) });
async function remove(p: Person) {
if (!(await confirm(keys.confirmDelete))) {
return;
}
const messages = useMessages.getState();
try {
await api.remove(type, p.id);
messages.showSuccess(keys.deleted, messageParams(p));
} catch (e) {
// um médico que ainda tem consultas: 409 ERRORS.DOCTOR_HAS_APPOINTMENTS
messages.showApiError(e);
}
await queryClient.invalidateQueries({ queryKey: [type] });
}
const list = persons.data;
let content;
if (list === undefined) {
// ainda não carregado (ou o carregamento falhou: a mensagem está no rodapé da página)
content = <p className="text-muted mb-0">{t('APP.LOADING')}</p>;
} else if (list.length === 0) {
content = <p className="text-muted mb-0">{t(keys.empty)}</p>;
} else {
content = (
<table className="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>
{list.map((p) => (
<tr key={p.id}>
<td>{p.title}</td>
<td>{p.firstName}</td>
<td>{p.lastName}</td>
<td><code>{p.login}</code></td>
<td className="text-end">
<div className="d-inline-flex gap-2">
<Link className="btn btn-sm btn-outline-primary" to={`/${type}/${p.id}/edit`}>{t('PERSONS.EDIT')}</Link>
<button type="button" className="btn btn-sm btn-outline-danger" onClick={() => remove(p)}>
{t('PERSONS.DELETE')}
</button>
</div>
</td>
</tr>
))}
</tbody>
</table>
);
}
return (
<>
<PageTitle titleKey={keys.title} />
<div className="d-flex justify-content-between align-items-center mb-3">
<h4 className="mb-0">{t(keys.title)}</h4>
<Link className="btn btn-primary" to={`/${type}/add`}>{t(keys.add)}</Link>
</div>
<div className="card p-3">{content}</div>
</>
);
}
|
A lista de médicos ou de clientes. O tipo é passado como propriedade (veja [routes.tsx]).
- Linha 25: a lista. Sua chave é o tipo: médicos e clientes têm cada um a sua. A lista de médicos são os MESMOS dados, assim como a lista da agenda (chave [['doctors']]): ambas se beneficiam do cache;
- Linhas 27–40: exclusão, após confirmação, seguida do recarregamento da lista. Um médico que ainda tem consultas não pode ser excluído: o servidor retorna uma resposta 409 e uma mensagem é exibida na parte inferior da página;
- linha 31: [getState()] fornece os recursos do store sem inscrever a página nas mensagens: ela não precisa ser recarregada quando uma mensagem muda;
- linhas 44–81: o conteúdo: “Loading…”, “No doctors” ou a tabela;
- linha 70: “Edit” é um link para a página do formulário.
10.4.10.5. src/pages/PersonForm.tsx
| // =========================================================================
// pages/PersonForm.tsx - criação OU atualização de um médico ou
// de um cliente (ADMIN)
// -------------------------------------------------------------------------
// /doctors/add -> criação (sem parâmetro id)
// /doctors/3/edit -> atualização (parâmetro id = "3")
// (e os mesmos endereços sob /clients). Equivalente de
// views/persons/form.hbs da aplicação HTML.
//
// Dois componentes:
// - PersonForm lê o registro a atualizar (se houver);
// - Form só é exibido depois que o registro foi lido: ele COMEÇA com
// seus valores (estado inicial), sem precisar copiá-los depois.
// Nenhuma regra é verificada aqui: o servidor valida tudo, e seus erros
// são exibidos sob os campos (veja hooks/useFormSubmit.ts).
// A VERSÃO lida com o registro volta com a atualização: se outro
// ADMIN a modificou nesse meio-tempo, o servidor responde 409 CONCURRENT_UPDATE.
// =========================================================================
import { useEffect, useState, type FormEvent } from 'react';
import { Link, useNavigate, useParams } from 'react-router';
import { useQuery, useQueryClient } from '@tanstack/react-query';
import { useTranslation } from 'react-i18next';
import { ApiError } from '../api/api-error';
import { api, type PersonType } from '../api/rdvmedecins.api';
import type { PersonData } from '../api/types';
import { useMessages } from '../stores/messages';
import { useFormSubmit } from '../hooks/useFormSubmit';
import PersonFields from '../components/PersonFields';
import InputField from '../components/InputField';
import PageTitle from '../components/PageTitle';
import ErrorPage from './ErrorPage';
import { PERSON_KEYS, messageParams } from './persons.config';
const EMPTY: PersonData = { title: 'Mr', firstName: '', lastName: '', login: '', password: '' };
// -------------------------------------------------------------------------
// o formulário em si
// -------------------------------------------------------------------------
interface FormProps {
type: PersonType;
id: number | null; // null: criação
initial: PersonData;
}
function Form({ type, id, initial }: FormProps) {
const { t } = useTranslation();
const navigate = useNavigate();
const queryClient = useQueryClient();
const submission = useFormSubmit();
const [form, setForm] = useState(initial);
const keys = PERSON_KEYS[type];
const creating = id === null;
function edit(field: keyof PersonData, value: string) {
setForm((f) => ({ ...f, [field]: value }));
submission.clearError(field);
}
async function save(e: FormEvent<HTMLFormElement>) {
e.preventDefault();
const messages = useMessages.getState();
const succeeded = await submission.submit(async () => {
const p = id === null ? await api.add(type, form) : await api.edit(type, id, form);
messages.flash('success', creating ? keys.added : keys.edited, messageParams(p));
});
const key = useMessages.getState().error?.key;
if (succeeded) {
await queryClient.invalidateQueries({ queryKey: [type] }); // a lista mudou
navigate(`/${type}`);
} else if (key === 'ERRORS.DOCTOR_NOT_FOUND' || key === 'ERRORS.PATIENT_NOT_FOUND') {
// excluído nesse meio-tempo por outro ADMIN: volta para a lista
messages.flash('error', key);
navigate(`/${type}`);
}
}
return (
<div className="row justify-content-center">
<div className="col-md-8 col-lg-6">
<div className="card p-4">
<h5 className="card-title mb-3">{t(creating ? keys.add : keys.edit)}</h5>
{/* noValidate: é o SERVIDOR que valida (ele é a referência) */}
<form noValidate onSubmit={save}>
<PersonFields values={form} errors={submission.errors} onChange={edit} />
<h6 className="mt-4 text-muted">{t('PERSONS.ACCOUNT_SECTION')}</h6>
<InputField className="mb-3" fieldId="login" label="PERSONS.LOGIN_LABEL" maxLength={30}
value={form.login} onChange={(v) => edit('login', v)} error={submission.errors.login}
help={creating ? 'PERSONS.LOGIN_HELP_CREATE' : 'PERSONS.LOGIN_HELP_EDIT'} />
{/* nunca preenchida previamente: a senha nunca volta do servidor */}
<InputField className="mb-4" fieldId="password" type="password" label="PERSONS.PASSWORD_LABEL" maxLength={72}
autoComplete="new-password" value={form.password} onChange={(v) => edit('password', v)}
error={submission.errors.password} params={submission.params}
help={creating ? 'PERSONS.PASSWORD_HELP_CREATE' : 'PERSONS.PASSWORD_HELP_EDIT'} />
<div className="d-flex gap-2">
<button type="submit" className="btn btn-primary" disabled={submission.submitting}>{t('PERSONS.SAVE')}</button>
<Link className="btn btn-secondary" to={`/${type}`}>{t('PERSONS.BACK')}</Link>
</div>
</form>
</div>
</div>
</div>
);
}
// -------------------------------------------------------------------------
// a página: criação, ou leitura do registro a atualizar
// -------------------------------------------------------------------------
export default function PersonForm({ type }: { type: PersonType }) {
const { id: urlId } = useParams(); // undefined para uma criação
const navigate = useNavigate();
const keys = PERSON_KEYS[type];
const validId = urlId === undefined || /^\d+$/.test(urlId);
const id = urlId === undefined || !validId ? null : Number(urlId);
// atualização: o registro é lido (incluindo sua versão)
// - gcTime: 0: o registro não é mantido no cache após a visita; a
// próxima visita o lerá novamente, sempre atualizado (caso contrário o formulário
// começaria com uma versão desatualizada: 409 CONCURRENT_UPDATE);
// - meta.errorHandled: um erro de leitura é tratado AQUI, e não
// pelo tratador de erros comum (veja main.tsx)
const details = useQuery({
queryKey: [type, id],
queryFn: () => api.read(type, id!),
enabled: id !== null,
gcTime: 0,
meta: { errorHandled: true },
});
// registro que não existe (excluído nesse meio-tempo...): volta para a lista
useEffect(() => {
if (details.error instanceof ApiError) {
useMessages.getState().flash('error', details.error.key, details.error.params);
navigate(`/${type}`);
}
}, [details.error, navigate, type]);
// /doctors/abc/edit: este endereço não existe
if (!validId) {
return <ErrorPage code={404} />;
}
const p = details.data;
return (
<>
<PageTitle titleKey={id === null ? keys.add : keys.edit} />
{id === null ? (
<Form type={type} id={null} initial={EMPTY} />
) : (
p && (
<Form type={type} id={id}
initial={{ title: p.title, firstName: p.firstName, lastName: p.lastName, login: p.login ?? '', password: '', version: p.version }} />
)
)}
</>
);
}
|
Uma única página para criação ([/doctors/add]) e edição ([/doctors/3/edit]), composta por dois componentes:
- linhas 46–106: o formulário em si. Ele só é exibido depois que o registro foi lido e COMEÇA com seus valores ([useState(initial)]): não há necessidade de copiá-los depois, em um efeito, quando o registro chega:
- linhas 55–58: digitar em um campo faz seu erro desaparecer;
- linhas 60–76: a operação de salvar. Em uma atualização, [form] contém a VERSÃO lida junto com o registro: se outro ADMIN o modificou nesse meio tempo, o servidor responde com um 409 [ERRORS.CONCURRENT_UPDATE];
- linhas 68–70: em caso de sucesso, a lista mudou: ela é invalidada e, em seguida, o programa volta a ela com a mensagem;
- linhas 71–75: o registro foi excluído nesse meio tempo: volta-se à lista. Os demais erros permanecem exibidos no formulário;
- linha 84: [noValidate]: o navegador não valida os campos [required]; quem valida é o SERVIDOR, e é essa validação que conta;
- Linha 91: o campo de senha nunca vem preenchido: a senha nunca é retornada pelo servidor;
- Linhas 111–159: a página:
- linha 112: o parâmetro de rota [:id], que está ausente em uma nova criação;
- linhas 124–130: leitura do registro para uma edição. [gcTime: 0]: o registro não é mantido em cache após a visita; a próxima visita o relerá, mantendo-o atualizado (caso contrário, o formulário começaria com uma versão desatualizada). [meta: { errorHandled: true }]: um erro de leitura é tratado aqui, e não pelo handler comum (veja [main.tsx]);
- linhas 133–138: o registro não existe (excluído nesse meio tempo, endereço digitado manualmente...): volta-se à lista, com uma mensagem;
- linhas 141–143: [/doctors/abc/edit]: este endereço não existe;
- linhas 149–156: uma nova entrada: o formulário vazio; uma edição: o formulário, depois que o registro foi lido. [login: p.login ?? '']: o login de uma pessoa só é enviado ao ADMIN; ele é opcional no tipo [Person].
10.4.10.6. src/pages/Register.tsx
| // =========================================================================
// pages/Register.tsx - "Create a patient account" (/register)
// -------------------------------------------------------------------------
// Só se chega aqui depois de copiar o CAPTCHA da página de login
// (botão "Create a patient account"): o servidor então emitiu um
// passe, que o guard da rota verificou (veja guards.ts).
// Mesmos campos do formulário do ADMIN, mas o login e a
// senha são obrigatórios, com confirmação. Equivalente de
// views/account/registration.hbs da aplicação HTML.
// =========================================================================
import { useState, type FormEvent } from 'react';
import { Link, useNavigate } from 'react-router';
import { useTranslation } from 'react-i18next';
import { api } from '../api/rdvmedecins.api';
import type { Registration } from '../api/types';
import { useMessages } from '../stores/messages';
import { useFormSubmit } from '../hooks/useFormSubmit';
import PersonFields from '../components/PersonFields';
import InputField from '../components/InputField';
import PageTitle from '../components/PageTitle';
// tamanho mínimo de uma senha escolhida por um paciente: mesmo valor
// do servidor (que também retorna {min} com o erro PASSWORD_TOO_SHORT)
const PASSWORD_MIN = '6';
export default function Register() {
const { t } = useTranslation();
const navigate = useNavigate();
const submission = useFormSubmit();
const [form, setForm] = useState<Registration>({
title: 'Mr', firstName: '', lastName: '', login: '', password: '', confirmation: '',
});
// os parâmetros da mensagem de ajuda E dos erros de senha
const passwordParams = { min: PASSWORD_MIN, ...submission.params };
function edit(field: keyof Registration, value: string) {
setForm((f) => ({ ...f, [field]: value }));
submission.clearError(field);
}
async function create(e: FormEvent<HTMLFormElement>) {
e.preventDefault();
let login = '';
const succeeded = await submission.submit(async () => {
login = (await api.register(form)).login;
});
const messages = useMessages.getState();
if (succeeded) {
// volta para a página de login, com o login preenchido
messages.flash('success', 'REGISTRATION.DONE', { login });
navigate(`/login?login=${encodeURIComponent(login)}`);
} else if (messages.error?.key === 'ERRORS.CAPTCHA_BEFORE_ACCOUNT') {
// passe expirado (15 minutos): volta para o CAPTCHA
messages.flash('error', 'ERRORS.CAPTCHA_BEFORE_ACCOUNT');
navigate('/login');
}
}
return (
<div className="row justify-content-center">
<PageTitle titleKey="REGISTRATION.TITLE" />
<div className="col-md-8 col-lg-6">
<div className="card p-4">
<h5 className="card-title mb-1">{t('REGISTRATION.TITLE')}</h5>
<p className="text-muted small mb-3">{t('REGISTRATION.INTRO')}</p>
<form noValidate onSubmit={create}>
<PersonFields values={form} errors={submission.errors} onChange={edit} />
<h6 className="mt-4 text-muted">{t('PERSONS.ACCOUNT_SECTION')}</h6>
<InputField className="mb-3" fieldId="login" label="PERSONS.LOGIN_LABEL" maxLength={30} autoComplete="username"
required value={form.login} onChange={(v) => edit('login', v)} error={submission.errors.login}
help="REGISTRATION.LOGIN_HELP" />
<div className="row g-3 mb-3">
<InputField className="col-sm-6" fieldId="password" type="password" label="PERSONS.PASSWORD_LABEL" maxLength={72}
autoComplete="new-password" required value={form.password} onChange={(v) => edit('password', v)}
error={submission.errors.password} params={passwordParams} help="REGISTRATION.PASSWORD_HELP" />
<InputField className="col-sm-6" fieldId="confirmation" type="password" label="ACCOUNT.CONFIRMATION_LABEL"
maxLength={72} autoComplete="new-password" required value={form.confirmation}
onChange={(v) => edit('confirmation', v)} error={submission.errors.confirmation} />
</div>
<div className="d-flex gap-2">
<button type="submit" className="btn btn-primary" disabled={submission.submitting}>{t('REGISTRATION.SUBMIT')}</button>
<Link className="btn btn-secondary" to="/login">{t('REGISTRATION.BACK_TO_LOGIN')}</Link>
</div>
</form>
</div>
</div>
</div>
);
}
|
Criação de uma conta de paciente. Só é possível chegar aqui depois de digitar o CAPTCHA da página de login: o servidor emitiu um passe, que o guard verificou.
- linha 25: o comprimento mínimo da senha, para a mensagem de ajuda (“At least 6 characters.”). O servidor também o retorna com o erro [ERRORS.PASSWORD_TOO_SHORT];
- linha 35: os parâmetros da mensagem de ajuda E dos erros de senha: os parâmetros do servidor, se houver, têm precedência;
- linhas 42–58: criação da conta:
- linha 52: em caso de sucesso, volta-se à página de login com o nome de usuário preenchido;
- linhas 53–57: o token expirou (15 minutos): volta-se à página de login para um novo CAPTCHA.
10.4.10.7. src/pages/PatientArea.tsx
| // =========================================================================
// pages/PatientArea.tsx - "My area" (/my-area, papel USER)
// -------------------------------------------------------------------------
// A página inicial do paciente, 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.
// Equivalente de views/patient/area.hbs da aplicação HTML.
// =========================================================================
import { Link } from 'react-router';
import { useQuery, useQueryClient } from '@tanstack/react-query';
import { useTranslation } from 'react-i18next';
import { api } from '../api/rdvmedecins.api';
import { timeRange, longDate, label } from '../formatting';
import { useMessages } from '../stores/messages';
import { confirm } from '../stores/confirmation';
import PageTitle from '../components/PageTitle';
export default function PatientArea() {
const { t, i18n } = useTranslation();
const queryClient = useQueryClient();
const area = useQuery({ queryKey: ['my-area'], queryFn: api.myArea });
async function cancel(appointmentId: number) {
if (!(await confirm('SCHEDULE.CANCEL_CONFIRM'))) {
return;
}
const messages = useMessages.getState();
try {
await api.cancelAppointment(appointmentId);
messages.showSuccess('SCHEDULE.CANCELLED');
} catch (e) {
messages.showApiError(e);
}
// a área E as agendas mudaram
await queryClient.invalidateQueries({ queryKey: ['my-area'] });
await queryClient.invalidateQueries({ queryKey: ['schedule'] });
}
const a = area.data;
if (!a) {
return (
<>
<PageTitle titleKey="AREA.TITLE" />
<p className="text-muted">{t('APP.LOADING')}</p>
</>
);
}
return (
<>
<PageTitle titleKey="AREA.TITLE" />
<h4 className="mb-3">{t('AREA.HELLO', { name: label(a.patient) })}</h4>
<div className="row g-3 mb-4">
<div className="col-sm-6">
<Link className="card p-4 h-100 text-decoration-none option-card" to="/my-account">
<h5 className="mb-1">{t('AREA.MANAGE_ACCOUNT')}</h5>
<span className="text-muted">{t('AREA.MANAGE_ACCOUNT_HELP')}</span>
</Link>
</div>
<div className="col-sm-6">
<Link className="card p-4 h-100 text-decoration-none option-card" to="/schedule">
<h5 className="mb-1">{t('AREA.VIEW_SCHEDULE')}</h5>
<span className="text-muted">{t('AREA.VIEW_SCHEDULE_HELP')}</span>
</Link>
</div>
</div>
<div className="card p-3">
<h5>{t('AREA.MY_APPOINTMENT')}</h5>
{/* normalmente apenas uma (regra "uma consulta futura por vez"),
mas a página pode exibir várias */}
{a.appointments.map((appointment, i) => (
<div key={appointment.id} className={`d-flex flex-wrap justify-content-between align-items-center gap-2 py-2 ${i < a.appointments.length - 1 ? 'border-bottom' : ''}`}>
<div>
<div className="fw-semibold">{longDate(appointment.day, i18n.language)}, {timeRange(appointment.slot)}</div>
<div className="text-muted">
{label(appointment.doctor)} -{' '}
{/* a agenda do médico nesse dia: o paciente vê nela o seu nome */}
<Link to={`/schedule?${new URLSearchParams({ doctorId: String(appointment.doctor.id), day: appointment.day })}`}>
{t('AREA.SEE_IN_SCHEDULE')}
</Link>
</div>
</div>
<button type="button" className="btn btn-outline-danger" onClick={() => cancel(appointment.id)}>{t('AREA.CANCEL_APPOINTMENT')}</button>
</div>
))}
{a.appointments.length === 0 && <p className="text-muted mb-0">{t('AREA.NO_APPOINTMENT')}</p>}
</div>
</>
);
}
|
A página inicial do paciente: duas opções, “Manage my account” e “View a schedule”, e sua próxima consulta, que ele pode cancelar.
- linha 22: a área do paciente. [queryFn: api.myArea]: a própria função, sem envolvê-la em uma arrow function; ela não tem parâmetros;
- Linhas 24–38: cancelamento, após confirmação. A área E as agendas mudaram: ambas são invalidadas;
- linhas 41–48: enquanto a área não foi lida, “Loading…”;
- linhas 55–58: todo um card do [Bootstrap] é um link: [<Link>] aceita qualquer conteúdo;
- linhas 72–86: a próxima consulta. Normalmente apenas uma (a regra de “uma consulta futura por vez”), mas a página pode exibir várias;
- linha 79: um link para a agenda do médico naquele dia, em que o paciente vê seu nome.
10.4.10.8. src/pages/MyAccount.tsx
| // =========================================================================
// pages/MyAccount.tsx - "Manage my account" (/my-account, papel USER)
// -------------------------------------------------------------------------
// Dois formulários independentes, como views/patient/account.hbs:
// 1. a atualização (identidade, login, nova senha opcional);
// 2. a exclusão da conta - que também cancela suas consultas.
// Ambos exigem a senha ATUAL (verificada pelo servidor).
// Dois formulários, portanto dois estados e dois useFormSubmit (dois conjuntos
// de erros). Como no PersonForm, o formulário de atualização só é
// exibido depois que a conta foi lida, e começa com seus valores.
// =========================================================================
import { useState, type FormEvent } from 'react';
import { Link, useNavigate } from 'react-router';
import { useQuery, useQueryClient } from '@tanstack/react-query';
import { useTranslation } from 'react-i18next';
import { api } from '../api/rdvmedecins.api';
import type { MyAccountUpdate, MyAccount as Account } from '../api/types';
import { useSession } from '../stores/session';
import { useMessages } from '../stores/messages';
import { confirm } from '../stores/confirmation';
import { useFormSubmit } from '../hooks/useFormSubmit';
import PersonFields from '../components/PersonFields';
import InputField from '../components/InputField';
import PageTitle from '../components/PageTitle';
// -------------------------------------------------------------------------
// 1. a atualização
// -------------------------------------------------------------------------
function Update({ account }: { account: Account }) {
const { t } = useTranslation();
const navigate = useNavigate();
const queryClient = useQueryClient();
const submission = useFormSubmit();
const [form, setForm] = useState<MyAccountUpdate>({ ...account, password: '', confirmation: '', currentPassword: '' });
function edit(field: keyof MyAccountUpdate, value: string) {
setForm((f) => ({ ...f, [field]: value }));
submission.clearError(field);
}
async function save(e: FormEvent<HTMLFormElement>) {
e.preventDefault();
const succeeded = await submission.submit(async () => {
// o servidor emitiu um NOVO token (nome, login): a barra de
// navegação deve acompanhar
useSession.getState().update(await api.editMyAccount(form));
useMessages.getState().flash('success', 'MY_ACCOUNT.UPDATED');
});
if (succeeded) {
await queryClient.invalidateQueries({ queryKey: ['my-area'] });
navigate('/my-area');
} else {
// nunca uma senha deixada no campo após um envio rejeitado;
// o valor é alterado SEM passar por edit(), para não apagar
// o erro que o servidor acabou de associar a ele
setForm((f) => ({ ...f, currentPassword: '' }));
}
}
return (
<div className="card p-4 mb-4">
<h5 className="card-title mb-3">{t('MY_ACCOUNT.TITLE')}</h5>
<form noValidate onSubmit={save}>
<PersonFields values={form} errors={submission.errors} onChange={edit} />
<h6 className="mt-4 text-muted">{t('PERSONS.ACCOUNT_SECTION')}</h6>
<InputField className="mb-3" fieldId="login" label="PERSONS.LOGIN_LABEL" maxLength={30} autoComplete="username"
required value={form.login} onChange={(v) => edit('login', v)} error={submission.errors.login} />
<div className="row g-3 mb-3">
<InputField className="col-sm-6" fieldId="password" type="password" label="MY_ACCOUNT.NEW_PASSWORD_LABEL"
maxLength={72} autoComplete="new-password" value={form.password}
onChange={(v) => edit('password', v)} error={submission.errors.password} params={submission.params}
help="PERSONS.PASSWORD_HELP_EDIT" />
<InputField className="col-sm-6" fieldId="confirmation" type="password" label="ACCOUNT.CONFIRMATION_LABEL"
maxLength={72} autoComplete="new-password" value={form.confirmation}
onChange={(v) => edit('confirmation', v)} error={submission.errors.confirmation} />
</div>
<InputField className="mb-4" fieldId="currentPassword" type="password" label="MY_ACCOUNT.CURRENT_PASSWORD_LABEL"
maxLength={72} autoComplete="current-password" required value={form.currentPassword}
onChange={(v) => edit('currentPassword', v)} error={submission.errors.currentPassword}
help="MY_ACCOUNT.CURRENT_PASSWORD_HELP" />
<div className="d-flex gap-2">
<button type="submit" className="btn btn-primary" disabled={submission.submitting}>{t('PERSONS.SAVE')}</button>
<Link className="btn btn-secondary" to="/my-area">{t('MY_ACCOUNT.BACK')}</Link>
</div>
</form>
</div>
);
}
// -------------------------------------------------------------------------
// 2. a exclusão: um formulário com um único campo
// -------------------------------------------------------------------------
function Deletion() {
const { t } = useTranslation();
const navigate = useNavigate();
const submission = useFormSubmit();
const [currentPassword, setCurrentPassword] = useState('');
async function remove(e: FormEvent<HTMLFormElement>) {
e.preventDefault();
if (!(await confirm('MY_ACCOUNT.DELETE_CONFIRM'))) {
return;
}
const succeeded = await submission.submit(() => api.deleteMyAccount(currentPassword));
if (succeeded) {
useSession.getState().forget(); // o servidor apagou o cookie do token
useMessages.getState().flash('success', 'MY_ACCOUNT.DELETED');
navigate('/login');
}
}
return (
<div className="card p-4 border-danger">
<h5 className="card-title text-danger mb-1">{t('MY_ACCOUNT.DELETE_TITLE')}</h5>
<p className="text-muted small">{t('MY_ACCOUNT.DELETE_HELP')}</p>
<form className="d-flex flex-wrap gap-2 align-items-end" noValidate onSubmit={remove}>
<InputField className="flex-grow-1" fieldId="deletePassword" type="password" label="MY_ACCOUNT.CURRENT_PASSWORD_LABEL"
maxLength={72} autoComplete="current-password" required value={currentPassword}
onChange={(v) => {
setCurrentPassword(v);
submission.clearError('currentPassword');
}}
error={submission.errors.currentPassword} />
<button type="submit" className="btn btn-danger" disabled={submission.submitting}>{t('MY_ACCOUNT.DELETE_SUBMIT')}</button>
</form>
</div>
);
}
// -------------------------------------------------------------------------
// a página
// -------------------------------------------------------------------------
export default function MyAccount() {
const { t } = useTranslation();
// gcTime: 0: lida novamente a cada visita (sua versão deve estar atualizada)
const account = useQuery({ queryKey: ['my-account'], queryFn: api.myAccount, gcTime: 0 });
return (
<div className="row justify-content-center">
<PageTitle titleKey="MY_ACCOUNT.TITLE" />
<div className="col-md-8 col-lg-6">
{account.data ? <Update account={account.data} /> : <p className="text-muted">{t('APP.LOADING')}</p>}
<Deletion />
</div>
</div>
);
}
|
Dois formulários independentes e, portanto, dois componentes, cada um com seu próprio estado e seu próprio [useFormSubmit] (dois conjuntos de erros):
- linhas 30–90: modificação da identidade, do login e, opcionalmente, da senha:
- linha 35: o formulário começa com os valores da conta (incluindo sua versão), com os campos de senha vazios;
- linha 47: o servidor emitiu um NOVO token, com o novo nome e o novo login, e redireciona o usuário: ele é armazenado no store de sessão, e a barra de navegação é atualizada de acordo;
- linhas 53–58: um envio foi rejeitado: uma senha nunca deve ficar em um campo. Alteramos o valor SEM passar por [edit()], para não apagar o erro que o servidor acabou de associar ao campo;
- linhas 95–130: exclusão da conta, que também cancela suas consultas:
- linha 99: um formulário com um único campo: uma única string;
- linhas 107–111: a conta é excluída e o servidor apagou o cookie do token: o cliente esquece o usuário e, em seguida, vai para a página de login, junto com a mensagem;
- linhas 135–149: a página. [gcTime: 0]: a conta é relida a cada visita; sua versão deve estar atualizada. A exclusão é exibida imediatamente; a modificação, depois que a conta foi lida.
10.4.10.9. src/pages/ErrorPage.tsx
| // =========================================================================
// pages/ErrorPage.tsx - a página de erro: 404 (endereço desconhecido) ou 403
// (papel insuficiente, veja guards.ts). Equivalente de views/error.hbs.
// =========================================================================
import { Link } from 'react-router';
import { useTranslation } from 'react-i18next';
import PageTitle from '../components/PageTitle';
export default function ErrorPage({ code }: { code: 403 | 404 }) {
const { t } = useTranslation();
return (
<div className="card p-4">
<PageTitle titleKey="ERROR_PAGE.TITLE" />
<h4 className="text-danger">{t('ERROR_PAGE.TITLE')} {code}</h4>
<p>{t(code === 403 ? 'ERRORS.FORBIDDEN' : 'ERRORS.NOT_FOUND')}</p>
<Link to="/" className="btn btn-primary align-self-start">{t('ERROR_PAGE.BACK')}</Link>
</div>
);
}
|
Página de erro: 404 (endereço desconhecido) ou 403 (permissões insuficientes). [code: 403 | 404]: esta propriedade só pode assumir esses dois valores.