Skip to content

10. Estudo de caso: o cliente Vue.js 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, na qual o servidor gerava as páginas. Aqui escrevemos o cliente [Vue.js]: as MESMAS páginas, geradas no navegador a partir dos dados JSON do servidor descritos 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 determinado dia, com reserva de consultas (janela de seleção de paciente) e cancelamento;
  • para o administrador, o gerenciamento de médicos e clientes (listar, incluir, editar, excluir);
  • para o paciente, um painel pessoal (com 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 navegadas 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 anterior). Para usar o cliente em um navegador, você não precisa do modo de teste do CAPTCHA: NÃO é necessário ativá-lo no arquivo [.env] do servidor.

Em uma janela de console aberta na pasta [rdvmedecins-vuejs]:

npm install
npm run dev

Em seguida, abra http://localhost:5173 em um navegador. As contas de demonstração estão listadas na página de login (senha = login).

O servidor [Vite] dos exemplos também usa a porta 5173. Se essa porta já estiver em uso, o [Vite] usará outra (5174...) e a exibirá no console: você deverá então abrir esse endereço.

10.3. Usando a aplicação

10.3.1. A página de login

Image

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

Image

10.3.2. O calendário, visto pelo administrador e pelos médicos

Ao fazer login como [admin], você é levado ao calendário:

Image

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

Image

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

Image

A consulta é salva:

Image

"Cancel" pede confirmação:

Image

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

Image

10.3.3. O portal do paciente

Um paciente ([martin]) acessa “My area”:

Image

No calendário, ele vê “Booked” ao lado dos horários de outros pacientes:

Image

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

Image

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

Image

Seu painel mostra isto:

Image

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

Image

Se ele digitar o endereço [/doctors], reservado ao administrador:

Image

10.3.4. Gerenciamento de médicos e clientes

Image

Um cadastro preenchido incorretamente:

Image

Uma inclusão bem-sucedida:

Image

Um homônimo:

Image

O pedido de remoção de um médico com consultas agendadas é negado:

Image

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, preenchido incorretamente, é então rejeitado pelo servidor:

Image

Depois que a conta é criada, volte à página de login; os campos de login estão pré-preenchidos:

Image

10.3.6. Em francês

Os botões FR / EN traduzem a página na hora, sem fazer nenhuma requisição ao servidor:

Image

10.3.7. Sessão expirada, endereço desconhecido

Se o token expirar (ou se o cookie for apagado), a próxima requisição recebe uma resposta 401; o cliente é redirecionado para a página de login:

Image

Um endereço desconhecido:

Image

10.4. Arquitetura do cliente

Image

rdvmedecins-vuejs/
├── index.html             THE page of the application
├── public/favicon.svg     the tab icon
├── package.json, vite.config.ts, tsconfig.json, env.d.ts
└── src/
    ├── main.ts            the startup
    ├── App.vue            the layout shared by all the pages
    ├── styles.css
    ├── router.ts          the pages and their access rights
    ├── i18n.ts            the languages
    ├── locales/           fr.json, en.json
    ├── api/               the API access layer
    ├── stores/            session.ts, messages.ts
    ├── composables/       useConfirmation, useFormatting, useForm
    ├── components/        the reusable components
    └── views/             the pages

A tabela a seguir compara a aplicação HTML do curso de [NestJS] com este cliente:

Aplicação HTML (NestJS)
Cliente Vue.js
O servidor gera cada página ([res.render])
O servidor devolve JSON; os componentes de [src/views/] geram as páginas
[views/layout.hbs] e suas views parciais
[App.vue] e os componentes de [src/components/]
as rotas do controller ([@Controller('schedule')])
rotas do cliente ([router.ts]); o servidor só tem rotas [/api/...]
[JwtAuthGuard] e [RolesGuard] redirecionam para [/login] ou para uma página 403
o guard do roteador; o servidor mantém seus próprios guards, que respondem com 401 / 403
mensagem flash em um cookie
mensagem flash em um store Pinia
Dicionários lidos pelo servidor, helper [{{t}}]
dicionários no cliente, [vue-i18n]; o servidor devolve apenas chaves
idioma armazenado em um cookie
idioma armazenado em [localStorage]
formulário rejeitado: o servidor recarrega a página
formulário rejeitado: resposta 400/409; o cliente exibe os erros
janela de confirmação: um pequeno script, [public/js/app.js]
um componente, [ConfirmDialog.vue]
A aplicação funciona sem JavaScript
A aplicação É JavaScript

10.5. Configuração do projeto

10.5.1. package.json

{
  "name": "rdvmedecins-vuejs",
  "version": "1.0.0",
  "description": "Vue.js client of the medical appointment booking application [RdvMedecins] - client of the JSON server [rdvmedecins-nestjs-json]",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vue-tsc --noEmit && vite build",
    "preview": "vite preview",
    "check": "vue-tsc --noEmit"
  },
  "dependencies": {
    "bootstrap": "^5.3.8",
    "pinia": "^3.0.4",
    "vue": "^3.5.22",
    "vue-i18n": "~11.3.2",
    "vue-router": "^4.6.3"
  },
  "devDependencies": {
    "@types/node": "^22.10.0",
    "@vitejs/plugin-vue": "^6.0.1",
    "@vue/tsconfig": "^0.8.1",
    "typescript": "~5.9.3",
    "vite": "^7.1.12",
    "vue-tsc": "^3.1.3"
  }
}

As mesmas bibliotecas dos exemplos. Um comando adicional:

  • linha 10: [npm run preview] serve a versão compilada da aplicação (pasta [dist/], gerada por [npm run build]), para verificá-la antes de implantá-la.

10.5.2. vite.config.ts

// =========================================================================
// vite.config.ts
// -------------------------------------------------------------------------
//   - npm run dev   : servidor de desenvolvimento em http://localhost:5173;
//                     as requisições /api/... são encaminhadas ao servidor JSON
//                     (porta 8080) pelo proxy: página e API têm a mesma
//                     origem, o cookie do token trafega normalmente;
//   - npm run build : a aplicação compilada, em dist/. Para colocá-la em
//                     produção, copie o CONTEÚDO de dist/ para a pasta
//                     client/ do servidor JSON, que então a serve ele mesmo
//                     (veja o capítulo "Implantação").
// =========================================================================

import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';

export default defineConfig({
  plugins: [vue()],
  server: {
    port: 5173,
    proxy: {
      '/api': 'http://localhost:8080',
    },
  },
  // npm run preview: serve dist/ (depois de npm run build), com o mesmo proxy
  preview: {
    port: 4173,
    proxy: {
      '/api': 'http://localhost:8080',
    },
  },
});
  • linhas 21–23: o proxy das requisições de [/api] para o servidor JSON;
  • linhas 26–31: o mesmo proxy para o [npm run preview].

Um detalhe importante: a aplicação usa endereços “limpos” ([/schedule], [/my-area]). Se você recarregar a página [/schedule], o navegador solicita [/schedule] ao servidor [Vite]. Como o servidor não encontra um arquivo com esse nome, ele devolve o [index.html] (esse é seu comportamento padrão para uma aplicação de página única); a aplicação é iniciada e seu roteador exibe a página do calendário.

10.5.3. tsconfig.json e env.d.ts

Idênticos aos dos exemplos, exceto pela lista de arquivos:

1
2
3
4
5
6
7
8
9
{
  "extends": "@vue/tsconfig/tsconfig.dom.json",
  "compilerOptions": {
    "types": ["vite/client"],
    "noUnusedLocals": true,
    "noUnusedParameters": true
  },
  "include": ["src/**/*.ts", "src/**/*.vue", "env.d.ts"]
}

10.6. Inicialização da aplicação

10.6.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 Vue.js, em <div id="app">. 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">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link rel="icon" href="/favicon.svg" type="image/svg+xml">
  <title>RdvMedecins</title>
</head>
<body>
  <div id="app"></div>
  <!-- sem JavaScript, uma aplicação Vue.js não consegue exibir nada: avisamos isso -->
  <noscript>RdvMedecins requires JavaScript. / RdvMedecins a besoin de JavaScript.</noscript>
  <script type="module" src="/src/main.ts"></script>
</body>
</html>
  • linha 12: o ícone da aba. Os arquivos da pasta [public/] são servidos como estão, na raiz do site;
  • linha 18: sem [JavaScript], uma aplicação [Vue.js] não consegue exibir nada. A aplicação HTML do curso de [NestJS], por outro lado, funcionava sem [JavaScript]: essa é a contrapartida de uma aplicação de página única;
  • linha 19: o programa.

10.6.2. src/main.ts

// =========================================================================
// main.ts - a inicialização da aplicação
// -------------------------------------------------------------------------
//   1. Bootstrap (CSS) e nossos poucos estilos;
//   2. Pinia (stores), vue-i18n (idiomas), o roteador;
//   3. a reação a uma resposta 401 vinda de qualquer requisição:
//      a sessão expirou - esquecemos o usuário e voltamos à página de
//      login, com uma mensagem;
//   4. a exibição em <div id="app">.
// =========================================================================

import { createApp } from 'vue';
import { createPinia } from 'pinia';
import 'bootstrap/dist/css/bootstrap.min.css';
import './styles.css';
import App from './App.vue';
import { i18n } from './i18n';
import { router } from './router';
import { whenUnauthenticated } from './api/http-client';
import { useSessionStore } from './stores/session';
import { useMessagesStore } from './stores/messages';

const app = createApp(App);
app.use(createPinia());
app.use(i18n);
app.use(router);

whenUnauthenticated(() => {
  useSessionStore().forget();
  useMessagesStore().flash('error', 'ERRORS.SESSION_EXPIRED');
  router.push({ name: 'login' });
});

app.mount('#app');
  • linhas 24–26: as três extensões: stores, idiomas e o roteador. O [Pinia] deve ser instalado ANTES do roteador: o guard do roteador usa um store;
  • linhas 28–32: o que fazer quando qualquer requisição recebe uma resposta 401 (sessão expirada, conta excluída etc.): esquecer o usuário, preparar a mensagem “Sua sessão expirou” para a próxima página e redirecionar para a página de login. Essa resposta é declarada UMA única vez aqui; a função [whenUnauthenticated] é descrita junto com o [http-client.ts].

10.6.3. src/App.vue

<!--
  =========================================================================
  App.vue - the root component: the TEMPLATE common to all the pages
  -------------------------------------------------------------------------
  The equivalent of views/layout.hbs of the HTML application:
    - the navigation bar;
    - a success message at the TOP;
    - the current page (<RouterView>);
    - the error panel at the BOTTOM;
    - the confirmation dialog, once for the whole application.

  :key="String(route.name)" on <RouterView>: when going from one route to
  ANOTHER (from /doctors to /clients, for example), the page component
  is recreated; when only the query changes (/schedule?day=...), it is
  kept, and it is the component that follows the URL.
  =========================================================================
-->
<script setup lang="ts">
import { RouterView, useRoute } from 'vue-router';
import NavBar from './components/NavBar.vue';
import SuccessMessage from './components/SuccessMessage.vue';
import ErrorPanel from './components/ErrorPanel.vue';
import ConfirmDialog from './components/ConfirmDialog.vue';

const route = useRoute();
</script>

<template>
  <div class="container py-4">
    <NavBar />
    <SuccessMessage />
    <RouterView :key="String(route.name)" />
    <ErrorPanel />
  </div>
  <ConfirmDialog />
</template>

O template comum a todas as páginas, equivalente ao [views/layout.hbs]:

  • linha 30: a barra de navegação;
  • linha 31: uma mensagem de sucesso no topo;
  • linha 32: a página atual. O atributo [:key]: quando a chave de um componente muda, o [Vue.js] o destrói e cria um novo. Com o NOME da rota como chave, passar de [/doctors] para [/clients] (duas rotas diferentes, exibidas pelo mesmo componente) recria a página, que recarrega seus dados. Quando muda apenas a [query] (para [/schedule?day=...]), a página é mantida, e é ela que acompanha sua URL;
  • linha 33: a área de erros, na parte inferior;
  • linha 35: a janela de confirmação, exibida uma única vez para toda a aplicação.

10.6.4. src/styles.css

/* =========================================================================
   styles.css - alguns ajustes sobre o Bootstrap
   (extraído 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.vue).
   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
   sobrepuser um botão, o clique passa através.
   ------------------------------------------------------------------------- */
.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 principais opções 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) */
.captcha-image svg {
  display: block;
  border: 1px solid #dee2e6;
  border-radius: 0.375rem;
}

Os estilos da aplicação HTML, com um acréscimo:

  • linha 28: a área de erros, que “gruda” na parte inferior da janela, pode se sobrepor a um botão (uma janela de confirmação no centro de uma página curta, por exemplo); ela não contém nada clicável, e um clique a atravessa.

10.7. A camada de acesso à API

10.7.1. src/api/types.ts

Os objetos JSON da API, descritos no capítulo sobre a caixa-preta, traduzidos em interfaces [TypeScript]:

// =========================================================================
// 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
// usa apenas 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 paciente: GET /api/doctors, GET /api/clients/:id...
export interface Person extends Identity {
  id: number;
  version: number; // bloqueio otimista: a reenviar 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;
}
  • linha 32: uma interface pode estender outra: uma [Person] é uma [Identity] que tem, além disso, um ID, uma versão e, para o ADMIN, um login;
  • linha 54: uma entrada do calendário: um horário, mais as permissões do usuário logado;
  • linhas 39 e seguintes: o que o cliente ENVIA ao servidor.

10.7.2. src/api/http-client.ts

A função [request] do Exemplo 19 ([common/api.ts]), com tratamento centralizado da resposta 401:

// =========================================================================
// api/http-client.ts - a função que envia TODAS as requisições à API
// -------------------------------------------------------------------------
// Extraída de common/api.ts dos exemplos, com uma novidade: o tratamento
// centralizado da resposta 401.
//
// Um 401 pode ocorrer a qualquer momento: o token expirou (2 horas), a
// conta foi excluída, o servidor reiniciou com outra chave
// secreta... Em vez de tratar esse caso em cada componente,
// notificamos UMA função, registrada na inicialização (veja main.ts), que esquece
// o usuário e redireciona para a página de login.
// =========================================================================

export class ApiError extends Error {
  constructor(
    public readonly statusCode: number, // 0: o servidor não respondeu
    public readonly key: string, // chave de tradução: 'ERRORS.LOGIN_TAKEN'
    public readonly params: Record<string, string> = {},
    public readonly fields: Record<string, string> = {}, // erro de cada campo
  ) {
    super(key);
    this.name = 'ApiError';
  }
}

// a função chamada a cada resposta 401 (veja main.ts)
let onUnauthenticated: (error: ApiError) => void = () => {};

export function whenUnauthenticated(callback: (error: ApiError) => void): void {
  onUnauthenticated = callback;
}

type Method = 'GET' | 'POST' | 'PUT' | 'DELETE';

export interface RequestOptions {
  // as rotas públicas (login, captcha...) e GET /api/auth/me
  // tratam o 401 por conta própria: sem redirecionamento automático
  ignore401?: boolean;
}

export async function request<T>(method: Method, url: string, body?: unknown, options: RequestOptions = {}): Promise<T> {
  let response: Response;
  try {
    response = await fetch(`/api${url}`, {
      method,
      headers: body !== undefined ? { 'Content-Type': 'application/json', Accept: 'application/json' } : { Accept: 'application/json' },
      body: body !== undefined ? JSON.stringify(body) : undefined,
    });
  } catch {
    throw new ApiError(0, 'ERRORS.SERVER_UNREACHABLE');
  }

  // lido como texto e depois convertido: uma resposta vazia, ou uma que não seja
  // JSON (servidor parado: é o proxy do Vite que responde), não
  // derruba a aplicação
  const text = await response.text();
  let data: unknown = null;
  try {
    data = text ? JSON.parse(text) : null;
  } catch {
    data = null;
  }

  if (response.ok) {
    return data as T;
  }

  const e = (data ?? {}) as { key?: string; params?: Record<string, string>; fields?: Record<string, string> };
  const error = new ApiError(
    response.status,
    // sem chave: não foi o nosso servidor que respondeu, e sim um proxy
    // (Vite: 500 sem corpo; nginx: 502, 504...)
    e.key ?? (response.status >= 500 ? 'ERRORS.SERVER_UNREACHABLE' : 'ERRORS.SERVER_ERROR'),
    e.params,
    e.fields,
  );
  if (response.status === 401 && !options.ignore401) {
    onUnauthenticated(error);
  }
  throw error;
}
  • linhas 14–23: um erro de requisição: código HTTP, chave da mensagem, parâmetros, erro de cada campo;
  • linha 27: a função a ser chamada a cada resposta 401. Inicialmente ela não faz nada; o [main.ts] fornece uma, por meio de [whenUnauthenticated]. Por que não chamar o roteador diretamente aqui? Porque a camada de acesso à API não deve saber nada sobre as páginas: ela sinaliza o erro, e a aplicação decide;
  • linhas 35–39: algumas requisições esperam um 401 e o tratam por conta própria: uma senha incorreta ([POST /api/auth/login] responde com um 401) ou a pergunta “quem está logado?” ([GET /api/auth/me], 401 se ninguém estiver logado). Para essas, não há redirecionamento automático;
  • linha 46: o cabeçalho [Accept] informa ao servidor o formato de resposta desejado;
  • linha 50: nenhuma resposta;
  • linha 73: uma resposta sem chave não vem do nosso servidor: quando o servidor JSON está fora do ar, quem responde é o proxy (o do [Vite] devolve um erro 500 sem corpo; um proxy de produção como o [nginx] devolve um 502 ou 504);
  • linhas 77–79: um 401 inesperado: notificamos a aplicação e depois rejeitamos a promise, como faríamos com qualquer erro.

10.7.3. src/api/rdvmedecins.api.ts

Uma função por rota da API:

// =========================================================================
// 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, apenas este arquivo muda.
// =========================================================================

import { request } from './http-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 rdvApi = {
  // ------------------------------------------------ login (rotas públicas)
  captcha: () => request<Captcha>('GET', '/captcha', undefined, { ignore401: true }),
  me: () => request<User>('GET', '/auth/me', undefined, { ignore401: true }),
  logIn: (login: string, password: string, captchaId: string, captcha: string) =>
    request<User>('POST', '/auth/login', { login, password, captchaId, captcha }, { ignore401: true }),
  logOut: () => request<Empty>('POST', '/auth/logout', {}, { ignore401: true }),

  // ------------------------------------------------ criação de conta (pública)
  registrationAccess: (captchaId: string, captcha: string) =>
    request<Empty>('POST', '/register/access', { captchaId, captcha }, { ignore401: true }),
  registrationAccessStatus: () => request<{ valid: boolean }>('GET', '/register/access', undefined, { ignore401: true }),
  register: (data: Registration) => request<{ login: string }>('POST', '/register', data, { ignore401: true }),

  // ------------------------------------------------ agenda e consultas
  // doctorId null: para um médico logado, a SUA agenda
  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 pacientes
  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 }),
};
  • linha 23: médicos e clientes são tratados da mesma forma; só o endereço muda: [/api/doctors] ou [/api/clients];
  • linha 25: o tipo de um objeto vazio, [{}];
  • linhas 29–33: as rotas de conexão, que tratam seu próprio 401 ([ignore401]);
  • linhas 43–49: se nenhum médico for informado, o parâmetro [doctorId] é omitido; se um médico estiver logado, o servidor devolve a SUA agenda;
  • linhas 50–51: [clientId ?? undefined]: [null] vira [undefined], e o [JSON.stringify] omite as propriedades [undefined]: um paciente não envia [clientId];
  • linhas 55–60: as cinco operações sobre pessoas, definidas pelo seu tipo;
  • linha 66: uma requisição DELETE também pode ter um corpo.

10.8. Idiomas

10.8.1. src/i18n.ts

// =========================================================================
// i18n.ts - francês e inglês
// -------------------------------------------------------------------------
// Os dicionários locales/fr.json e locales/en.json são os do
// curso de NestJS (i18n/*.json), completados com algumas chaves específicas do cliente
// (ERRORS.SERVER_UNREACHABLE...). O servidor JSON retorna apenas CHAVES
// ('ERRORS.LOGIN_TAKEN'): 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 { createI18n } from 'vue-i18n';
import fr from './locales/fr.json';
import en from './locales/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...): sem problema
  }
  return navigator.language.toLowerCase().startsWith('fr') ? 'fr' : 'en';
}

export const i18n = createI18n({
  legacy: false,
  locale: initialLanguage(),
  fallbackLocale: 'en',
  messages: { fr, en },
  // sem aviso no console para uma chave traduzida por fallback
  fallbackWarn: false,
  missingWarn: false,
});

// mudar o idioma: a aplicação inteira é traduzida novamente de uma só vez
export function changeLanguage(language: Language): void {
  i18n.global.locale.value = language;
  document.documentElement.lang = language;
  try {
    localStorage.setItem(STORAGE_KEY, language);
  } catch {
    // sem importância
  }
}

document.documentElement.lang = i18n.global.locale.value;
  • linhas 21–31: o idioma armazenado ou, na falta dele, o idioma do navegador. O acesso ao [localStorage] é protegido por [try / catch]: alguns navegadores, no modo anônimo, o bloqueiam;
  • linhas 39–40: nenhum aviso no console quando uma chave está ausente ou vem do dicionário de reserva;
  • linhas 44–52: troca de idioma: [i18n.global.locale] é o idioma de toda a aplicação; o atributo [lang] da página também é atualizado, e a seleção é salva.

10.8.2. Os dicionários

Estas são as chaves do curso de [NestJS], complementadas por algumas chaves específicas do cliente ([APP.LOADING], [ERRORS.AUTH_REQUIRED], [ERRORS.JSON_REQUIRED], [ERRORS.SERVER_UNREACHABLE]). Os códigos de erro são os devolvidos pelo servidor.

10.8.2.1. src/locales/fr.json

{
  "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"
  }
}

10.8.2.2. src/locales/en.json

{
  "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.9. Os stores

10.9.1. src/stores/session.ts

// =========================================================================
// stores/session.ts - QUEM está logado?
// -------------------------------------------------------------------------
// O store Pinia da sessão: o usuário logado (ou null) e o que
// se deduz dele (o usuário é um ADMIN? um paciente?).
//
// O token JWT em si NÃO está aqui: ele está em um cookie httpOnly que
// apenas o navegador manipula. O store guarda somente 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 { computed, ref } from 'vue';
import { defineStore } from 'pinia';
import { rdvApi } from '../api/rdvmedecins.api';
import type { Role, User } from '../api/types';

export const useSessionStore = defineStore('session', () => {
  const user = ref<User | null>(null);
  // a pergunta "quem está logado?" já foi feita ao servidor?
  let checking: Promise<void> | null = null;

  const loggedIn = computed(() => user.value !== null);
  const role = computed<Role | null>(() => user.value?.role ?? null);
  const isAdmin = computed(() => role.value === 'ADMIN');
  const isPatient = computed(() => role.value === 'USER');
  // ADMIN e DOCTOR: marcam e cancelam as consultas de qualquer paciente
  const isManager = computed(() => role.value === 'ADMIN' || role.value === 'DOCTOR');

  // a página inicial de cada papel, logo após o login
  const homePage = computed(() => (isPatient.value ? '/my-area' : '/schedule'));

  // chamado pelo guard do roteador antes de CADA navegação; só consulta
  // o servidor na primeira vez (a promise é guardada e reutilizada)
  function check(): Promise<void> {
    checking ??= rdvApi
      .me()
      .then((u) => {
        user.value = u;
      })
      .catch(() => {
        user.value = null; // 401: ninguém; ou servidor inacessível
      });
    return checking;
  }

  async function logIn(login: string, password: string, captchaId: string, captcha: string): Promise<void> {
    user.value = await rdvApi.logIn(login, password, captchaId, captcha);
  }

  // o usuário mudou de nome ou de login (PUT /api/my-account)
  function update(u: User): void {
    user.value = u;
  }

  async function logOut(): Promise<void> {
    try {
      await rdvApi.logOut();
    } finally {
      forget();
    }
  }

  // sem perguntar nada ao servidor: sessão expirada, conta excluída
  function forget(): void {
    user.value = null;
  }

  return {
    user,
    loggedIn,
    role,
    isAdmin,
    isPatient,
    isManager,
    homePage,
    check,
    logIn,
    update,
    logOut,
    forget,
  };
});
  • linha 21: o usuário logado, conforme descrito pelo servidor. O token em si não está aqui — ele está em um cookie que somente o navegador manipula;
  • linhas 25–30: o que se deduz disso, usado pelas páginas e pela barra de navegação;
  • linha 33: a página inicial de cada papel: “My area” para um paciente, o calendário para os demais;
  • linhas 37–47: a pergunta “quem está logado?”, feita ao servidor somente na PRIMEIRA vez. A promise é mantida em [checking]: as chamadas seguintes a reutilizam (o operador [??=] só atribui um valor se a variável for [null] ou [undefined]). Ela não pode falhar: um erro (401, servidor inacessível) significa “ninguém”;
  • linhas 49–51: o login. Se falhar, o [rdvApi.logIn] rejeita sua promise com um [ApiError], que atravessa esta função até a página de login;
  • linha 54: depois de alterar a conta, o paciente pode ter mudado de nome;
  • linhas 58–64: [finally]: o usuário é esquecido, mesmo que o servidor não tenha respondido;
  • linha 67: sem fazer nenhuma requisição ao servidor (sessão expirada, conta excluída).

10.9.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 na PARTE INFERIOR, 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 mudar de idioma.
//
// As mensagens "flash": uma ação que termina com uma mudança de
// página (marcação, adição de médico...) deixa sua mensagem com flash();
// ela será exibida na PRÓXIMA página e depois desaparecerá na navegação
// seguinte (veja router.afterEach em router.ts). No lado do servidor, esse era o
// papel do cookie de curta duração "rdvmedecins_flash".
// =========================================================================

import { ref } from 'vue';
import { defineStore } from 'pinia';
import { ApiError } from '../api/http-client';

export interface Message {
  key: string;
  params?: Record<string, string>;
}

export const useMessagesStore = defineStore('messages', () => {
  const success = ref<Message | null>(null);
  const error = ref<Message | null>(null);
  // as mensagens a exibir na próxima página
  let pending: { success: Message | null; error: Message | null } | null = null;

  function showSuccess(key: string, params?: Record<string, string>): void {
    success.value = { key, params };
    error.value = null;
  }

  function showError(key: string, params?: Record<string, string>): void {
    error.value = { key, params };
    success.value = null;
  }

  // um ApiError -> a mensagem da página; qualquer outro erro é uma
  // anomalia do cliente, que é deixada passar (console do navegador)
  function showApiError(e: unknown): void {
    if (!(e instanceof ApiError)) {
      throw e;
    }
    showError(e.key, e.params);
  }

  function clear(): void {
    success.value = null;
    error.value = null;
  }

  // para a PRÓXIMA página
  function flash(type: 'success' | 'error', key: string, params?: Record<string, string>): void {
    pending ??= { success: null, error: null };
    pending[type] = { key, params };
  }

  // chamado após cada navegação (router.afterEach)
  function newPage(): void {
    success.value = pending?.success ?? null;
    error.value = pending?.error ?? null;
    pending = null;
  }

  return { success, error, showSuccess, showError, showApiError, clear, flash, newPage };
});
  • linhas 21–24: uma mensagem é composta por uma CHAVE de tradução e seus parâmetros. Assim, ela se traduz automaticamente se o usuário trocar de idioma;
  • linhas 27–28: a mensagem de sucesso (exibida no topo) e a mensagem de erro (na parte inferior) da página atual;
  • linhas 44–49: um [ApiError] torna-se a mensagem da página. Qualquer outro erro é uma anomalia do CLIENTE (um erro de programação): ele pode ser registrado em log e será exibido no console do navegador;
  • linhas 57–60: uma mensagem para a PRÓXIMA página. Uma ação que resulta em uma mudança de página (reservar, incluir um médico, fazer login após criar uma conta) exibe essa mensagem antes de navegar para a página seguinte;
  • linhas 63–67: chamada após cada navegação entre páginas (veja [router.ts]): as mensagens da página anterior desaparecem, e as mensagens pendentes aparecem. Na aplicação HTML, esse era o papel do cookie de curta duração [rdvmedecins_flash].

10.10. Os composables

10.10.1. src/composables/useConfirmation.ts

O composable do Exemplo 12, com três diferenças:

// =========================================================================
// composables/useConfirmation.ts - "Tem certeza?"
// -------------------------------------------------------------------------
// Extraído do exemplo 12: confirm(key) abre o diálogo de confirmação
// (components/ConfirmDialog.vue, colocado uma vez em App.vue) 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 { readonly, ref } from 'vue';
import { useMessagesStore } from '../stores/messages';

const messageKey = ref<string | null>(null); // null: diálogo fechado
let answer: ((yes: boolean) => void) | null = null;

export function useConfirmation() {
  function confirm(key: string): Promise<boolean> {
    answer?.(false); // uma pergunta ainda aberta? conta como "não"
    // uma nova pergunta: as mensagens da ação anterior ficam obsoletas
    useMessagesStore().clear();
    messageKey.value = key;
    return new Promise<boolean>((resolve) => {
      answer = resolve;
    });
  }

  function respond(yes: boolean): void {
    messageKey.value = null;
    const r = answer;
    answer = null;
    r?.(yes);
  }

  return { messageKey: readonly(messageKey), confirm, respond };
}
  • linha 19: a mensagem é uma CHAVE de tradução: a janela a traduz para o idioma atual;
  • linha 20: uma pergunta em aberto (cenário improvável) recebe a resposta “não”;
  • linha 22: uma nova pergunta torna obsoletas as mensagens da ação anterior.

10.10.2. src/composables/useFormatting.ts

// =========================================================================
// composables/useFormatting.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, é responsabilidade
// do cliente. longDate() acompanha o idioma atual do vue-i18n.
// =========================================================================

import { useI18n } from 'vue-i18n';
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 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;
}

export function useFormatting() {
  const { locale } = useI18n();

  // "lundi 5 octobre 2026" / "Monday 5 October 2026"
  function longDate(day: string): string {
    return new Intl.DateTimeFormat(locale.value === '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`));
  }

  return { label, time, timeRange, longDate };
}

O servidor envia dados brutos ([startHour: 8, startMinute: 0], [day: "2026-10-05"]); formatar esses dados, o que depende do idioma, é responsabilidade do cliente:

  • linhas 13–39: funções comuns, não reativas, exportadas uma a uma;
  • linhas 42–54: um composable, porque o [longDate] precisa do idioma ATUAL, que ele obtém por meio de [useI18n()]. Quando o idioma muda, um template que exibe [longDate(...)] é recalculado;
  • linha 49: [new Date("2026-10-05T00:00:00Z")] é meia-noite UTC; exibida no fuso horário de Paris, ainda seria 5 de outubro, mas em Nova York seria 4 de outubro! Por isso solicitamos a exibição no fuso horário UTC.

10.10.3. src/composables/useForm.ts

// =========================================================================
// composables/useForm.ts - os erros de um formulário enviado ao servidor
// -------------------------------------------------------------------------
// Todos os formulários da aplicação seguem o mesmo padrão do
// exemplo 20: nenhuma regra é verificada no navegador (elas
// ficam em UM único lugar, o servidor) e, em caso de recusa:
//   - o erro de cada campo (ApiError.fields) é exibido sob o campo,
//     contornado em vermelho;
//   - a mensagem geral (ApiError.key) é exibida na parte inferior da página.
// Este composable agrupa esse estado e essas ações.
// =========================================================================

import { ref } from 'vue';
import { ApiError } from '../api/http-client';
import { useMessagesStore } from '../stores/messages';

export function useForm() {
  const messages = useMessagesStore();
  const errors = ref<Record<string, string>>({}); // campo -> chave da mensagem
  const params = ref<Record<string, string>>({}); // parâmetros das mensagens ({min}...)
  const submitting = ref(false);

  function clearErrors(): void {
    errors.value = {};
    params.value = {};
  }

  // executa o envio; retorna true se teve êxito. Em caso de ApiError, os
  // erros são exibidos e false é retornado.
  async function submit(action: () => Promise<void>): Promise<boolean> {
    clearErrors();
    submitting.value = true;
    try {
      await action();
      return true;
    } catch (e) {
      if (e instanceof ApiError) {
        errors.value = e.fields;
        params.value = e.params;
      }
      messages.showApiError(e);
      return false;
    } finally {
      submitting.value = false;
    }
  }

  return { errors, params, submitting, submit, clearErrors };
}

Todos os formulários da aplicação seguem a abordagem mostrada no Exemplo 20: nenhuma regra é validada no navegador; o servidor valida tudo, e os eventuais erros são exibidos abaixo dos campos. Este composable agrupa o estado e as ações comuns:

  • linhas 19–21: o erro de cada campo, os parâmetros das mensagens e um indicador de envio (o botão fica desabilitado durante o envio para evitar clique duplo);
  • linhas 30–46: executa o envio (uma função fornecida pela página); se ocorrer um [ApiError], limpa os erros dos campos, exibe a mensagem geral na parte inferior da página e devolve [false].

10.11. O roteador

// =========================================================================
// router.ts - 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 que agora são rotas do CLIENTE:
// createWebHistory produz endereços "limpos", sem #. O navegador
// envia uma requisição ao servidor apenas para a primeira página; depois disso,
// o roteador muda o endereço e o componente exibido.
//
// O outro lado da moeda: se o usuário recarregar /schedule (F5), o
// navegador realmente solicita /schedule ao servidor, que deve então
// devolver index.html (o Vite faz isso em desenvolvimento; em produção, veja
// web/client-spa.ts do servidor JSON).
//
// Cada rota carrega metadados (meta):
//   - title   : chave de tradução do título da aba;
//   - public  : acessível sem estar logado;
//   - roles   : os papéis permitidos (ausente = todos os papéis logados);
//   - type    : 'doctors' ou 'clients' para as páginas comuns a ambos.
//
// LEMBRETE: essas verificações são apenas uma COMODIDADE (não exibir uma
// página inútil). Os dados são protegidos pelo servidor, que
// verifica novamente o token e o papel a CADA requisição.
// =========================================================================

import { createRouter, createWebHistory } from 'vue-router';
import type { Role } from './api/types';
import type { PersonType } from './api/rdvmedecins.api';
import { i18n } from './i18n';
import { useSessionStore } from './stores/session';
import { useMessagesStore } from './stores/messages';
import { rdvApi } from './api/rdvmedecins.api';
import LoginView from './views/LoginView.vue';
import ScheduleView from './views/ScheduleView.vue';

declare module 'vue-router' {
  interface RouteMeta {
    title: string;
    public?: boolean;
    roles?: Role[];
    type?: PersonType;
  }
}

// as rotas para gerenciar médicos E pacientes (ADMIN), no mesmo modelo
function personRoutes(type: PersonType, title: string, addTitle: string, editTitle: string) {
  const roles: Role[] = ['ADMIN'];
  return [
    { path: `/${type}`, name: type, component: () => import('./views/PersonsView.vue'), meta: { title, roles, type } },
    {
      path: `/${type}/add`,
      name: `${type}-add`,
      component: () => import('./views/PersonFormView.vue'),
      meta: { title: addTitle, roles, type },
    },
    {
      path: `/${type}/:id(\\d+)/edit`, // (\\d+): o id deve ser um número
      name: `${type}-edit`,
      component: () => import('./views/PersonFormView.vue'),
      props: (route: { params: { id?: string | string[] } }) => ({ id: Number(route.params.id) }),
      meta: { title: editTitle, roles, type },
    },
  ];
}

export const router = createRouter({
  history: createWebHistory(),
  routes: [
    // "/": para /login, que por sua vez envia à página inicial do papel se estiver logado
    { path: '/', redirect: '/login' },
    { path: '/login', name: 'login', component: LoginView, meta: { title: 'LOGIN.TITLE', public: true } },
    { path: '/schedule', name: 'schedule', component: ScheduleView, meta: { title: 'SCHEDULE.PAGE_TITLE' } },
    ...personRoutes('doctors', 'DOCTORS.TITLE', 'DOCTORS.ADD', 'DOCTORS.EDIT'),
    ...personRoutes('clients', 'CLIENTS.TITLE', 'CLIENTS.ADD', 'CLIENTS.EDIT'),
    {
      path: '/register',
      name: 'register',
      component: () => import('./views/RegisterView.vue'),
      meta: { title: 'REGISTRATION.TITLE', public: true },
      // um guard ESPECÍFICO da rota: sem um passe (captcha resolvido na
      // página de login), de volta à página de login
      beforeEnter: async () => {
        const { valid } = await rdvApi.registrationAccessStatus().catch(() => ({ valid: false }));
        if (!valid) {
          useMessagesStore().flash('error', 'ERRORS.CAPTCHA_BEFORE_ACCOUNT');
          return { name: 'login' };
        }
        return true;
      },
    },
    {
      path: '/my-area',
      name: 'my-area',
      component: () => import('./views/PatientAreaView.vue'),
      meta: { title: 'AREA.TITLE', roles: ['USER'] },
    },
    {
      path: '/my-account',
      name: 'my-account',
      component: () => import('./views/MyAccountView.vue'),
      meta: { title: 'MY_ACCOUNT.TITLE', roles: ['USER'] },
    },
    {
      path: '/forbidden',
      name: 'forbidden',
      component: () => import('./views/ErrorView.vue'),
      props: { code: 403 },
      meta: { title: 'ERROR_PAGE.TITLE' },
    },
    {
      path: '/:pathMatch(.*)*',
      name: 'not-found',
      component: () => import('./views/ErrorView.vue'),
      props: { code: 404 },
      meta: { title: 'ERROR_PAGE.TITLE', public: true },
    },
  ],
});

// -------------------------------------------------------------------------
// o guard GLOBAL, antes de cada navegação
// -------------------------------------------------------------------------
router.beforeEach(async (to) => {
  const session = useSessionStore();
  // na primeira vez (inicialização, F5): perguntamos ao servidor quem está logado
  await session.check();

  if (to.meta.public) {
    // já logado: a página de login deixa de fazer sentido
    if (to.name === 'login' && session.loggedIn) {
      return session.homePage;
    }
    return true;
  }
  if (!session.loggedIn) {
    // a página solicitada é lembrada, para voltar a ela após o login
    return { name: 'login', query: { redirect: to.fullPath } };
  }
  if (to.meta.roles && !to.meta.roles.includes(session.role!)) {
    return { name: 'forbidden' };
  }
  return true;
});

// -------------------------------------------------------------------------
// após cada navegação: mensagens "flash", título da aba
// -------------------------------------------------------------------------
router.afterEach((to, from) => {
  // uma navegação que muda apenas a query (/schedule?...) ainda é uma
  // nova "página": como na aplicação HTML, as mensagens da
  // página anterior desaparecem, as mensagens flash aparecem
  if (to.fullPath !== from.fullPath) {
    useMessagesStore().newPage();
  }
  document.title = `${i18n.global.t(to.meta.title)} - ${i18n.global.t('APP.TITLE')}`;
});
  • linhas 36–43: metadados de nossas rotas: o título da aba (uma chave de tradução), o acesso público, os papéis autorizados e o tipo de usuário;
  • linhas 46–64: as três rotas de gerenciamento de médicos (listar, incluir, editar) e as mesmas três para os clientes, geradas por uma função. As páginas são carregadas sob demanda ([() => import(...)]): um paciente nunca baixará o código de gerenciamento de médicos;
  • linha 57: [(\d+)]: uma expressão regular restringe o parâmetro [id] a números. [/doctors/abc/edit] não corresponde a essa rota: a página “página não encontrada” é exibida;
  • linha 60: a propriedade [id] do componente, convertida em número;
  • linha 67: endereços “limpos”, sem [#];
  • linha 70: o endereço [/] leva a [/login], que por sua vez leva à página inicial do papel quando o usuário está logado;
  • linhas 82–89: um guard ESPECÍFICO de uma rota, executado antes de entrar nela: sem o passe (CAPTCHA resolvido na página de login), a criação de conta redireciona para a página de login com uma mensagem;
  • linha 107: as [props] também podem ser um objeto estático: a mesma página de erro é usada para os erros 403 e 404;
  • linhas 123–143: o guard GLOBAL, antes de cada navegação:
    • [await session.check()]: na primeira vez (na inicialização, F5), o servidor é consultado para saber quem está logado. O guard é [async]: a navegação espera a resposta;
    • uma página pública é sempre acessível; já a página de login, para um usuário logado, redireciona para a sua página inicial;
    • não logado: página de login, mantendo a página solicitada;
    • papel inválido: página 403;
  • linhas 148–156: após cada navegação: as mensagens flash são exibidas e o título da aba é traduzido. [i18n.global.t]: fora de um componente, o objeto [i18n] é usado diretamente.

10.12. Os componentes

10.12.1. src/components/NavBar.vue

<!--
  =========================================================================
  components/NavBar.vue - the navigation bar
  -------------------------------------------------------------------------
  Same content as that of the HTML application (views/partials/navbar.hbs):
  title, menus according to the role, FR / EN, role, name, logout.
  "Doctors" and "Patients" appear only for the ADMIN: a mere display
  convenience, the real protection being that of the server.
  =========================================================================
-->
<script setup lang="ts">
import { RouterLink, useRouter } from 'vue-router';
import { useI18n } from 'vue-i18n';
import { useSessionStore } from '../stores/session';
import { changeLanguage, LANGUAGES } from '../i18n';

const { t, locale } = useI18n();
const session = useSessionStore();
const router = useRouter();

async function logOut(): Promise<void> {
  await session.logOut().catch(() => {}); // mesmo que o servidor não responda
  router.push({ name: 'login' });
}
</script>

<template>
  <nav class="navbar navbar-expand-sm navbar-dark bg-primary rounded mb-4 px-3">
    <span class="navbar-brand mb-0">{{ t('APP.TITLE') }}</span>

    <ul v-if="session.loggedIn" class="navbar-nav me-auto">
      <li v-if="session.isPatient" class="nav-item">
        <!-- active-class: a classe Bootstrap do menu da página exibida -->
        <RouterLink class="nav-link" active-class="active" to="/my-area">{{ t('APP.MENU_MY_AREA') }}</RouterLink>
      </li>
      <li class="nav-item">
        <RouterLink class="nav-link" active-class="active" to="/schedule">{{ t('APP.MENU_SCHEDULE') }}</RouterLink>
      </li>
      <template v-if="session.isAdmin">
        <li class="nav-item">
          <RouterLink class="nav-link" active-class="active" to="/doctors">{{ t('APP.MENU_DOCTORS') }}</RouterLink>
        </li>
        <li class="nav-item">
          <RouterLink class="nav-link" active-class="active" to="/clients">{{ t('APP.MENU_PATIENTS') }}</RouterLink>
        </li>
      </template>
    </ul>
    <div v-else class="me-auto"></div>

    <div class="d-flex align-items-center gap-2">
      <!-- FR / EN: nenhuma requisição ao servidor, a página é traduzida novamente no lugar -->
      <div class="btn-group btn-group-sm" role="group" :aria-label="t('APP.LANGUAGE')">
        <button
          v-for="l in LANGUAGES"
          :key="l"
          type="button"
          class="btn"
          :class="locale === l ? 'btn-light' : 'btn-outline-light'"
          :aria-pressed="locale === l"
          @click="changeLanguage(l)"
        >
          {{ l.toUpperCase() }}
        </button>
      </div>

      <template v-if="session.user">
        <span class="badge text-bg-light text-primary">{{ session.user.role }}</span>
        <span class="text-white">{{ session.user.name }}</span>
        <button type="button" class="btn btn-sm btn-outline-light" @click="logOut">{{ t('APP.LOGOUT') }}</button>
      </template>
    </div>
  </nav>
</template>
  • linhas 21–24: logout, seguido da página de login. [.catch(() => {})]: mesmo que o servidor não responda, o cliente se desconecta;
  • linha 31: os menus só aparecem depois do login, conforme o papel: “My area” para um paciente, “Doctors” e “Patients” para o ADMIN. Isso serve apenas para conveniência de exibição; a verdadeira segurança é garantida pelo servidor;
  • linha 34: ao menu da página exibida é atribuída a classe [active];
  • linhas 53–63: os botões FR / EN. O [:aria-pressed] indica aos leitores de tela qual botão está pressionado;
  • linha 66: o papel, o nome e a função de logout.

10.12.2. src/components/SuccessMessage.vue e ErrorPanel.vue

<!--
  components/SuccessMessage.vue - the SUCCESS message, at the top of the page
  (appointment booked, doctor added...) - see stores/messages.ts.
  role="status": a screen reader announces it without interrupting the user.
-->
<script setup lang="ts">
import { useI18n } from 'vue-i18n';
import { useMessagesStore } from '../stores/messages';

const { t } = useI18n();
const messages = useMessagesStore();
</script>

<template>
  <div v-if="messages.success" class="alert alert-success" role="status">
    {{ t(messages.success.key, messages.success.params ?? {}) }}
  </div>
</template>
<!--
  components/ErrorPanel.vue - the error panel, at the BOTTOM of each page, on a
  light pink background (class .error-panel, see styles.css) - like
  views/partials/errors.hbs of the HTML application.
  role="alert": a screen reader announces the message as soon as it appears.
-->
<script setup lang="ts">
import { useI18n } from 'vue-i18n';
import { useMessagesStore } from '../stores/messages';

const { t } = useI18n();
const messages = useMessagesStore();
</script>

<template>
  <div v-if="messages.error" class="error-panel" role="alert">
    {{ t(messages.error.key, messages.error.params ?? {}) }}
  </div>
</template>

Dois componentes muito curtos que exibem as mensagens do store [messages], traduzidas para o idioma atual:

  • linha 16: um leitor de tela anuncia a mensagem de erro assim que ela aparece, mesmo que esteja na parte inferior da página; a mensagem de sucesso é [role="status"], anunciada sem interromper o usuário.

10.12.3. src/components/ConfirmDialog.vue

<!--
  =========================================================================
  components/ConfirmDialog.vue - the "Are you sure?" dialog
  -------------------------------------------------------------------------
  The one of example 12, completed for the keyboard like public/js/app.js
  of the HTML application:
    - on opening, the focus goes to "No, go back": an absent-minded press on
      Enter deletes nothing;
    - Escape closes the dialog (= No);
    - Tab and Shift+Tab stay INSIDE the dialog (otherwise the focus would go to
      the greyed-out page, behind);
    - on closing, the focus goes back to the element that had it (the
      "Delete" button clicked, for example).
  "No, go back" rather than "Cancel": the question is sometimes "Cancel this
  appointment?", and a "Cancel" button would be ambiguous there.
  =========================================================================
-->
<script setup lang="ts">
import { nextTick, useTemplateRef, watch } from 'vue';
import { useI18n } from 'vue-i18n';
import { useConfirmation } from '../composables/useConfirmation';

const { t } = useI18n();
const { messageKey, respond } = useConfirmation();
const dialog = useTemplateRef<HTMLElement>('dialog');
const noButton = useTemplateRef<HTMLButtonElement>('noButton');
let previousFocus: HTMLElement | null = null;

watch(messageKey, async (key, oldKey) => {
  if (key !== null && oldKey === null) {
    previousFocus = document.activeElement as HTMLElement | null;
    await nextTick(); // o diálogo agora está na página
    noButton.value?.focus();
  } else if (key === null) {
    previousFocus?.focus();
    previousFocus = null;
  }
});

function onKeydown(e: KeyboardEvent): void {
  if (e.key === 'Escape') {
    respond(false);
  } else if (e.key === 'Tab' && dialog.value) {
    const buttons = [...dialog.value.querySelectorAll<HTMLButtonElement>('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();
    }
  }
}
</script>

<template>
  <Teleport to="body">
    <div v-if="messageKey !== null" @keydown="onKeydown">
      <div class="modal-backdrop fade show"></div>
      <div
        ref="dialog"
        class="modal fade show d-block"
        tabindex="-1"
        role="alertdialog"
        aria-modal="true"
        aria-labelledby="confirmation-title"
        aria-describedby="confirmation-message"
        @click.self="respond(false)"
      >
        <div class="modal-dialog modal-dialog-centered">
          <div class="modal-content">
            <div class="modal-header">
              <h5 id="confirmation-title" class="modal-title">{{ t('CONFIRMATION.TITLE') }}</h5>
              <button type="button" class="btn-close" :aria-label="t('BOOKING_DIALOG.CLOSE_ARIA')" @click="respond(false)"></button>
            </div>
            <div class="modal-body">
              <p id="confirmation-message" class="mb-0">{{ t(messageKey) }}</p>
            </div>
            <div class="modal-footer">
              <button ref="noButton" type="button" class="btn btn-secondary" @click="respond(false)">{{ t('CONFIRMATION.NO') }}</button>
              <button type="button" class="btn btn-danger" @click="respond(true)">{{ t('CONFIRMATION.YES') }}</button>
            </div>
          </div>
        </div>
      </div>
    </div>
  </Teleport>
</template>

A janela do Exemplo 12, aprimorada para a navegação pelo teclado com base no script [public/js/app.js] da aplicação HTML:

  • linhas 29–38: ao abrir, o elemento que tinha o foco (o botão “Delete” em que se clicou, por exemplo) é guardado, e depois o foco é dado ao botão “No, go back”; ao fechar, o foco volta ao elemento guardado. Um usuário que navega pelo teclado recupera, assim, sua posição na página;
  • linhas 40–55: Esc é tratado como “Não”; Tab e Shift+Tab permanecem dentro da janela: ao chegar ao último botão, Tab volta ao primeiro (caso contrário, o foco iria para a página acinzentada ao fundo);
  • linha 60: a entrada pelo teclado é tratada pela própria janela: não é preciso anexar nem remover um listener no documento;
  • linha 68: para os leitores de tela, o título e a mensagem da janela;
  • linha 79: a mensagem, traduzida.

10.12.4. src/components/InputField.vue

Um campo de formulário completo, reutilizado por todos os formulários da aplicação:

<!--
  =========================================================================
  components/InputField.vue - a complete form field
  -------------------------------------------------------------------------
  Label + field + help message OR error message, with v-model (see
  example 08). All the forms of the application use it:

    <InputField v-model="form.lastName" id="lastName" label="PERSONS.LASTNAME_LABEL"
                :error="errors.lastName" :params="params" :maxlength="20" />

  label, help and error are translation KEYS. An error outlines the
  field in red (Bootstrap class is-invalid) and replaces the help.
  =========================================================================
-->
<script setup lang="ts">
import { useI18n } from 'vue-i18n';

const model = defineModel<string>({ required: true });

withDefaults(
  defineProps<{
    id: string;
    label: string;
    type?: 'text' | 'password';
    error?: string; // chave da mensagem de erro deste campo
    params?: Record<string, string>; // parâmetros das mensagens ({min}...)
    help?: string; // chave da mensagem de ajuda
    maxlength?: number;
    autocomplete?: string;
    required?: boolean;
  }>(),
  { type: 'text', error: undefined, params: () => ({}), help: undefined, maxlength: undefined, autocomplete: 'off', required: false },
);

const { t } = useI18n();
</script>

<template>
  <div>
    <label class="form-label" :for="id">{{ t(label) }}</label>
    <input
      :id="id"
      v-model="model"
      :type="type"
      class="form-control"
      :class="{ 'is-invalid': error }"
      :maxlength="maxlength"
      :autocomplete="autocomplete"
      :required="required"
      :aria-invalid="error ? 'true' : undefined"
      :aria-describedby="`${id}-message`"
    >
    <div v-if="error" :id="`${id}-message`" class="invalid-feedback">{{ t(error, params) }}</div>
    <div v-else-if="help" :id="`${id}-message`" class="form-text">{{ t(help, params) }}</div>
  </div>
</template>
  • linha 18: o campo é usado com [v-model] (veja o exemplo 08);
  • linhas 20–33: as props: o ID do campo e as CHAVES de tradução do rótulo, da dica e da mensagem de erro;
  • linha 46: um erro destaca o campo em vermelho;
  • linha 51: a mensagem de ajuda ou de erro é associada ao campo para os leitores de tela;
  • linhas 53–54: a mensagem de erro SUBSTITUI o texto de ajuda.

Quando colocado dentro de um componente pai, o componente também herda os atributos repassados pelo pai, mesmo que não sejam props: [<InputField class="col-sm-6" ...>] adiciona a classe [col-sm-6] ao seu elemento raiz, o [<div>] (são os chamados atributos “herdados”, [fallthrough attributes]).

10.12.5. src/components/PersonFields.vue

O título, o nome e o sobrenome são comuns a três formulários:

<!--
  =========================================================================
  components/PersonFields.vue - title, first name, last name
  -------------------------------------------------------------------------
  The identity fields, common to three forms: the ADMIN's doctor / client
  form, "Create a patient account" and "Manage my account" (the equivalent of the
  partial views/partials/personFields.hbs). Three named v-models:
      <PersonFields v-model:title="f.title" v-model:firstName="f.firstName"
                    v-model:lastName="f.lastName" :errors="errors" />
  =========================================================================
-->
<script setup lang="ts">
import { useI18n } from 'vue-i18n';
import InputField from './InputField.vue';

const title = defineModel<string>('title', { required: true });
const firstName = defineModel<string>('firstName', { required: true });
const lastName = defineModel<string>('lastName', { required: true });
defineProps<{ errors: Record<string, string> }>();

const { t } = useI18n();
const TITLES = ['Mr', 'Mme', 'Melle'];
</script>

<template>
  <div class="mb-3">
    <label class="form-label" for="title">{{ t('PERSONS.TITLE_LABEL') }}</label>
    <select id="title" v-model="title" class="form-select" :class="{ 'is-invalid': errors.title }">
      <option v-for="tt in TITLES" :key="tt" :value="tt">{{ tt }}</option>
    </select>
    <div v-if="errors.title" class="invalid-feedback">{{ t(errors.title) }}</div>
  </div>
  <div class="row g-3 mb-3">
    <InputField v-model="firstName" class="col-sm-6" id="firstName" label="PERSONS.FIRSTNAME_LABEL" :error="errors.firstName" :maxlength="20" required />
    <InputField v-model="lastName" class="col-sm-6" id="lastName" label="PERSONS.LASTNAME_LABEL" :error="errors.lastName" :maxlength="20" required />
  </div>
</template>
  • linhas 16–18: três campos [v-model] nomeados: o pai escreve [v-model:title="..."], [v-model:firstName="..."], [v-model:lastName="..."];
  • linha 34: os dois campos de texto são [InputField]. [firstName] é o [ref] do [defineModel]: a cadeia pai-filho -> PersonFields -> InputField -> [<input>] funciona nos dois sentidos.

Um componente pode ter vários elementos raiz (aqui, o [<div>] do título e a linha que contém os dois campos): isso é chamado de “fragmento”.

10.12.6. src/components/CaptchaField.vue

<!--
  =========================================================================
  components/CaptchaField.vue - the captcha image and the input field
  -------------------------------------------------------------------------
  Loads a captcha (GET /api/captcha) when displayed. The parent gets
  the input through v-model, and the identifier of the captcha through the exposed
  method captchaId(); it calls reload() after each attempt, because an
  image is used only ONCE (the server forgets it as soon as it has checked it).

  defineExpose: what a PARENT component can call on this component,
  thanks to a template ref (see LoginView.vue).

  v-html: the SVG image is inserted as is. Harmless HERE because
  it is built by our server (svg-captcha library) and does not
  contain anything that comes from a user - see example 17.
  =========================================================================
-->
<script setup lang="ts">
import { onMounted, ref } from 'vue';
import { useI18n } from 'vue-i18n';
import { rdvApi } from '../api/rdvmedecins.api';
import type { Captcha } from '../api/types';

const input = defineModel<string>({ required: true });
defineProps<{ error?: string }>();

const { t } = useI18n();
const captcha = ref<Captcha | null>(null);

async function reload(): Promise<void> {
  input.value = '';
  try {
    captcha.value = await rdvApi.captcha();
  } catch {
    captcha.value = null; // servidor inacessível: o login falhará com uma mensagem clara
  }
}

defineExpose({ reload, captchaId: () => captcha.value?.id ?? '' });
onMounted(reload);
</script>

<template>
  <div class="mb-3">
    <label class="form-label" for="captcha">{{ t('CAPTCHA.LABEL') }}</label>
    <div class="d-flex align-items-center gap-3 mb-2">
      <div class="captcha-image" role="img" :aria-label="t('CAPTCHA.IMAGE_ALT')" v-html="captcha?.svg ?? ''"></div>
      <a href="#" class="small" @click.prevent="reload">{{ t('CAPTCHA.NEW_IMAGE') }}</a>
    </div>
    <input id="captcha" v-model="input" type="text" maxlength="10" autocomplete="off" autocapitalize="off" spellcheck="false"
           class="form-control" :class="{ 'is-invalid': error }">
    <div v-if="error" class="invalid-feedback">{{ t(error) }}</div>
    <div v-else class="form-text">{{ t('CAPTCHA.HELP') }}</div>
  </div>
</template>
  • linhas 30–37: um novo CAPTCHA; o texto digitado anteriormente é apagado;
  • linha 39: o que o PAI pode chamar neste componente, por meio de uma referência de template (veja [LoginView.vue]). Sem o [defineExpose], um componente [<script setup>] não expõe nada;
  • linha 47: a imagem SVG, inserida como está: ela vem do nosso servidor (veja o Exemplo 17).

10.12.7. src/components/BookingDialog.vue

<!--
  =========================================================================
  components/BookingDialog.vue - the dialog to book a slot
  -------------------------------------------------------------------------
  Same dialog as views/partials/booking.hbs of the HTML application
  (and as the booking-dialog component of the Angular client): the
  Bootstrap classes of a modal dialog, displayed "hard-coded" (show d-block).

  The component does not talk to the server: it emits
    - 'confirm' with the chosen patient (null for a patient who books
      for themselves);
    - 'close'.
  It is the schedule page that decides what to do with it (ScheduleView.vue).
  =========================================================================
-->
<script setup lang="ts">
import { onMounted, onUnmounted, ref, useTemplateRef } from 'vue';
import { useI18n } from 'vue-i18n';
import type { Person } from '../api/types';
import { label } from '../composables/useFormatting';

const props = defineProps<{
  time: string; // "8:00 - 8:20"
  clients: Person[]; // ADMIN / DOCTOR: os pacientes entre os quais escolher
  patient: string | null; // USER: o paciente é ele mesmo
  submitting: boolean;
}>();

const emit = defineEmits<{ confirm: [clientId: number | null]; close: [] }>();

const { t } = useI18n();
const clientId = ref<number | null>(null);
const list = useTemplateRef<HTMLSelectElement>('list');
const confirmButton = useTemplateRef<HTMLButtonElement>('confirmButton');

function onEscape(e: KeyboardEvent): void {
  if (e.key === 'Escape') {
    emit('close');
  }
}

onMounted(() => {
  // o foco no primeiro elemento útil do diálogo
  (props.patient === null ? list.value : confirmButton.value)?.focus();
  document.addEventListener('keydown', onEscape);
});
onUnmounted(() => document.removeEventListener('keydown', onEscape));
</script>

<template>
  <Teleport to="body">
    <div class="modal-backdrop fade show"></div>
    <div class="modal fade show d-block" tabindex="-1" role="dialog" aria-modal="true" aria-labelledby="booking-title"
         @click.self="emit('close')">
      <div class="modal-dialog modal-dialog-centered">
        <form class="modal-content" @submit.prevent="emit('confirm', clientId)">
          <div class="modal-header">
            <h5 id="booking-title" class="modal-title">{{ t('BOOKING_DIALOG.TITLE') }}</h5>
            <button type="button" class="btn-close" :aria-label="t('BOOKING_DIALOG.CLOSE_ARIA')" @click="emit('close')"></button>
          </div>

          <div class="modal-body">
            <p>{{ t('BOOKING_DIALOG.SLOT', { time }) }}</p>
            <!-- a patient books for themselves: no list (and the server
                 would ignore a possible clientId anyway) -->
            <p v-if="patient !== null" class="mb-0">{{ t('BOOKING_DIALOG.PATIENT_LABEL') }}: <strong>{{ patient }}</strong></p>
            <template v-else>
              <label class="form-label" for="clientId">{{ t('BOOKING_DIALOG.PATIENT_LABEL') }}</label>
              <select id="clientId" ref="list" v-model="clientId" class="form-select">
                <option :value="null">{{ t('BOOKING_DIALOG.CHOOSE_PATIENT') }}</option>
                <option v-for="c in clients" :key="c.id" :value="c.id">{{ label(c) }}</option>
              </select>
            </template>
          </div>

          <div class="modal-footer">
            <button type="button" class="btn btn-secondary" @click="emit('close')">{{ t('BOOKING_DIALOG.CANCEL') }}</button>
            <button ref="confirmButton" type="submit" class="btn btn-primary" :disabled="submitting">{{ t('BOOKING_DIALOG.CONFIRM') }}</button>
          </div>
        </form>
      </div>
    </div>
  </Teleport>
</template>

A janela de reserva de consultas. Ela não se comunica com o servidor: emite [confirm] com o paciente selecionado ou [close]. A página do calendário decide o que fazer com isso.

  • linhas 22–27: o horário da consulta e, ou a lista de pacientes (ADMIN, DOCTOR), ou o nome do paciente logado (USER);
  • linhas 42–46: ao abrir, o foco vai para o primeiro elemento aplicável (a lista de pacientes ou o botão “Confirm”); a tecla Esc fecha a janela;
  • linha 56: um formulário de verdade: a tecla Enter confirma;
  • linha 66: um paciente faz a reserva para si mesmo: sem lista.

10.13. As páginas

10.13.1. src/views/LoginView.vue

<!--
  =========================================================================
  views/LoginView.vue - the login page (/login)
  -------------------------------------------------------------------------
  Same page as views/login.hbs of the HTML application: login,
  password, captcha, and a second button "Create a patient account" that checks
  the SAME captcha before opening the account creation.

  /login?login=jbernard: the login field is pre-filled (right after the
  creation of an account).
  /login?redirect=/doctors: after login, this page is opened
  (set by the router guard) rather than the home page of the role.
  =========================================================================
-->
<script setup lang="ts">
import { onMounted, reactive, ref, useTemplateRef } from 'vue';
import { useRoute, useRouter } from 'vue-router';
import { useI18n } from 'vue-i18n';
import { ApiError } from '../api/http-client';
import { rdvApi } from '../api/rdvmedecins.api';
import { useSessionStore } from '../stores/session';
import { useMessagesStore } from '../stores/messages';
import CaptchaField from '../components/CaptchaField.vue';

const { t } = useI18n();
const route = useRoute();
const router = useRouter();
const session = useSessionStore();
const messages = useMessagesStore();

const form = reactive({
  login: typeof route.query.login === 'string' ? route.query.login.slice(0, 30) : '',
  password: '',
  captcha: '',
});
const captchaError = ref<string | undefined>(undefined);
const submitting = ref(false);
const captchaField = useTemplateRef<InstanceType<typeof CaptchaField>>('captchaField');
const loginField = useTemplateRef<HTMLInputElement>('loginField');
const passwordField = useTemplateRef<HTMLInputElement>('passwordField');

// o foco: na senha se o login já estiver preenchido
onMounted(() => (form.login ? passwordField.value : loginField.value)?.focus());

// os dois botões compartilham esta sequência: envio e, em caso de falha,
// mensagem de erro e uma NOVA imagem (cada uma só é usada uma vez)
async function attempt(action: () => Promise<void>): Promise<void> {
  messages.clear();
  captchaError.value = undefined;
  submitting.value = true;
  try {
    await action();
  } catch (e) {
    messages.showApiError(e);
    if (e instanceof ApiError) {
      captchaError.value = e.fields.captcha;
    }
    await captchaField.value?.reload();
  } finally {
    submitting.value = false;
  }
}

function logIn(): Promise<void> {
  return attempt(async () => {
    await session.logIn(form.login.trim(), form.password, captchaField.value?.captchaId() ?? '', form.captcha);
    const redirect = route.query.redirect;
    // apenas um caminho INTERNO: nunca um redirecionamento para outro site
    router.push(typeof redirect === 'string' && redirect.startsWith('/') && !redirect.startsWith('//') ? redirect : session.homePage);
  });
}

function createAccount(): Promise<void> {
  return attempt(async () => {
    await rdvApi.registrationAccess(captchaField.value?.captchaId() ?? '', form.captcha);
    router.push({ name: 'register' });
  });
}
</script>

<template>
  <div class="row justify-content-center">
    <div class="col-sm-8 col-md-6 col-lg-5">
      <div class="card p-4">
        <h5 class="card-title mb-3">{{ t('LOGIN.TITLE') }}</h5>

        <form @submit.prevent="logIn">
          <div class="mb-3">
            <label class="form-label" for="login">{{ t('LOGIN.LOGIN_LABEL') }}</label>
            <input id="login" ref="loginField" v-model="form.login" type="text" class="form-control" autocomplete="username" required>
          </div>
          <div class="mb-3">
            <label class="form-label" for="password">{{ t('LOGIN.PASSWORD_LABEL') }}</label>
            <input id="password" ref="passwordField" v-model="form.password" type="password" class="form-control"
                   autocomplete="current-password" required>
          </div>

          <CaptchaField ref="captchaField" v-model="form.captcha" :error="captchaError" />

          <!-- type="submit": Enter em um campo aciona "Entrar" -->
          <button type="submit" class="btn btn-primary w-100" :disabled="submitting">{{ t('LOGIN.SUBMIT') }}</button>

          <!-- type="button": this button does not submit the form (no
               required check on login and password, useless here) -->
          <button type="button" class="btn btn-outline-primary w-100 mt-3" :disabled="submitting" @click="createAccount">
            {{ t('LOGIN.CREATE_ACCOUNT') }}
          </button>
          <div class="form-text text-center">{{ t('LOGIN.CREATE_ACCOUNT_HELP') }}</div>
        </form>

        <div class="text-muted small mt-3">
          {{ t('LOGIN.DEMO_ACCOUNTS') }}
          <ul class="mb-0 mt-1">
            <li><code>admin</code> - {{ t('LOGIN.DEMO_ADMIN') }}</li>
            <li><code>pelissier</code>, <code>tatou</code>, <code>dupont</code> - {{ t('LOGIN.DEMO_DOCTOR') }}</li>
            <li><code>martin</code>, <code>durand</code>, <code>bistrou</code>, <code>german</code> - {{ t('LOGIN.DEMO_USER') }}</li>
          </ul>
        </div>
      </div>
    </div>
  </div>
</template>
  • linha 32: [/login?login=jbernard] pré-preenche o campo de login (logo após a criação de uma conta);
  • linha 38: uma referência ao COMPONENTE [CaptchaField]: podemos chamar o que ele expõe ([reload()], [captchaId()]). [InstanceType<typeof CaptchaField>] é o seu tipo;
  • linha 43: o foco vai para o campo de senha se o nome de usuário já estiver preenchido;
  • linhas 47–62: os dois botões seguem a mesma sequência: envio; se malsucedido, aparece uma mensagem de erro, junto com um erro abaixo do campo do CAPTCHA, se for o caso, e uma NOVA imagem;
  • linhas 64–71: o login, seguido da página solicitada antes do login (parâmetro [redirect], definido pelo roteador) ou da página inicial do papel. Somente um caminho interno é aceito: ele deve começar com [/], mas não com [//] ([//site.com/...] refere-se a OUTRO site);
  • linhas 73–78: “Create a patient account”: o servidor verifica o CAPTCHA e emite um token; a página de criação de conta é então aberta;
  • linha 105: [type="button"]: este botão não envia o formulário. Na aplicação HTML, era um segundo botão para enviar o mesmo formulário a outro endereço ([formaction]).

10.13.2. src/views/ScheduleView.vue

A página principal. Como na aplicação HTML, TODO o seu estado está na URL:

1
2
3
/schedule                                           choice of the doctor and the day
/schedule?doctorId=1&day=2026-10-05                 the schedule
/schedule?doctorId=1&day=2026-10-05&book=7          + the booking dialog for slot 7
<!--
  =========================================================================
  views/ScheduleView.vue - the schedule page (/schedule)
  -------------------------------------------------------------------------
  Three blocks, like views/schedule.hbs of the HTML application:
    1. the choice of the doctor and of the day;
    2. the schedule of that doctor on that day;
    3. the dialog to book a slot.

  As in the HTML application, ALL the state of the page is in its URL:
      /schedule?doctorId=1&day=2026-10-05             the schedule
      /schedule?doctorId=1&day=2026-10-05&book=7      + the booking dialog
  The page can therefore be reloaded, bookmarked, and the browser's Back /
  Forward buttons can be used. The page FOLLOWS its URL: a watch on the
  query reloads the schedule; the user's actions, on the other hand, change
  the URL (router.push).

  What each user sees and can do is decided by the SERVER (fields
  patient, mine, bookable, appointmentId of each slot): the page merely
  displays it. A patient does not even receive the name of the other patients.
  =========================================================================
-->
<script setup lang="ts">
import { computed, onMounted, reactive, ref, watch } from 'vue';
import { RouterLink, useRoute, useRouter } from 'vue-router';
import { useI18n } from 'vue-i18n';
import { ApiError } from '../api/http-client';
import { rdvApi } from '../api/rdvmedecins.api';
import type { Schedule, ScheduleSlot, Person } from '../api/types';
import { today, isValidDate, label, useFormatting } from '../composables/useFormatting';
import { useConfirmation } from '../composables/useConfirmation';
import { useSessionStore } from '../stores/session';
import { useMessagesStore } from '../stores/messages';
import BookingDialog from '../components/BookingDialog.vue';

const { t } = useI18n();
const route = useRoute();
const router = useRouter();
const session = useSessionStore();
const messages = useMessagesStore();
const { timeRange, longDate } = useFormatting();
const { confirm } = useConfirmation();

const doctors = ref<Person[]>([]);
const clients = ref<Person[]>([]); // ADMIN / DOCTOR: para o diálogo de marcação
const schedule = ref<Schedule | null>(null);
const loading = ref(false);
const submitting = ref(false);

// os valores do formulário "médico + dia", copiados da URL
const choice = reactive<{ doctorId: number | null; day: string }>({ doctorId: null, day: today() });

// "3" -> 3 ; "", "abc", "-2", ausente -> null
function positiveInteger(value: unknown): number | null {
  const n = Number(value);
  return typeof value === 'string' && value !== '' && Number.isInteger(n) && n > 0 ? n : null;
}

// a agenda exibida, sem diálogo de marcação: a query "back"
const scheduleQuery = computed(() => ({ doctorId: String(choice.doctorId ?? ''), day: choice.day }));

// o horário cujo diálogo de marcação está aberto (?book=7),
// somente se puder ser marcado por este usuário
const slotToBook = computed<ScheduleSlot | null>(() => {
  const id = positiveInteger(route.query.book);
  return schedule.value?.slots.find((s) => s.id === id && s.bookable) ?? null;
});

// -------------------------------------------------------------------------
// carregando
// -------------------------------------------------------------------------
onMounted(async () => {
  try {
    doctors.value = await rdvApi.list('doctors');
    // a lista de pacientes: somente para quem tem permissão de lê-la
    if (session.isManager) {
      clients.value = await rdvApi.list('clients');
    }
  } catch (e) {
    messages.showApiError(e);
  }
});

// a agenda acompanha a URL (médico e dia)
watch(() => [route.query.doctorId, route.query.day], loadSchedule, { immediate: true });

async function loadSchedule(): Promise<void> {
  // o dia: o da URL se for válido, caso contrário hoje
  const rawDay = route.query.day;
  choice.day = today();
  if (rawDay !== undefined) {
    if (!isValidDate(rawDay)) {
      schedule.value = null;
      messages.showError('ERRORS.INVALID_DATE');
      return;
    }
    choice.day = rawDay;
  }
  // o médico: o da URL; sem médico, um DOCTOR vê a SUA agenda
  // (o servidor a encontra a partir do token)
  choice.doctorId = positiveInteger(route.query.doctorId);
  if (choice.doctorId === null && session.role !== 'DOCTOR') {
    schedule.value = null;
    return;
  }
  loading.value = true;
  try {
    schedule.value = await rdvApi.schedule(choice.doctorId, choice.day);
    choice.doctorId = schedule.value.doctor.id;
  } catch (e) {
    schedule.value = null;
    messages.showApiError(e);
  } finally {
    loading.value = false;
  }
}

// -------------------------------------------------------------------------
// ações
// -------------------------------------------------------------------------

// "Ver agenda": a URL é alterada, a agenda acompanha (watch acima)
function viewSchedule(): void {
  router.push({ query: scheduleQuery.value });
}

function closeBooking(): void {
  router.push({ query: scheduleQuery.value });
}

async function book(clientId: number | null): Promise<void> {
  const slot = slotToBook.value;
  if (slot === null) {
    return;
  }
  submitting.value = true;
  try {
    await rdvApi.book(choice.day, slot.id, session.isManager ? clientId : null);
    messages.flash('success', 'SCHEDULE.BOOKED');
  } catch (e) {
    if (e instanceof ApiError && e.key === 'ERRORS.CHOOSE_PATIENT') {
      // nenhum paciente escolhido: o diálogo permanece aberto
      messages.showError(e.key);
      return; // (finally executa de qualquer maneira)
    }
    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
    messages.flash('error', e.key, e.params);
  } finally {
    submitting.value = false;
  }
  await router.push({ query: scheduleQuery.value });
  await loadSchedule(); // o servidor é a referência: a agenda é lida novamente
}

async function cancel(s: ScheduleSlot): Promise<void> {
  if (s.appointmentId === null || !(await confirm('SCHEDULE.CANCEL_CONFIRM'))) {
    return;
  }
  try {
    await rdvApi.cancelAppointment(s.appointmentId);
    messages.showSuccess('SCHEDULE.CANCELLED');
  } catch (e) {
    messages.showApiError(e);
  }
  await loadSchedule();
}
</script>

<template>
  <!-- 1. a escolha do médico e do dia -->
  <form class="card p-3 mb-3" @submit.prevent="viewSchedule">
    <div class="row g-2 align-items-end">
      <div class="col-sm-5">
        <label class="form-label" for="doctorId">{{ t('DOCTOR_DAY_PICKER.DOCTOR_LABEL') }}</label>
        <select id="doctorId" v-model="choice.doctorId" class="form-select" required>
          <option :value="null">{{ t('DOCTOR_DAY_PICKER.CHOOSE_DOCTOR') }}</option>
          <option v-for="d in doctors" :key="d.id" :value="d.id">{{ label(d) }}</option>
        </select>
      </div>
      <div class="col-sm-4">
        <label class="form-label" for="day">{{ t('DOCTOR_DAY_PICKER.DAY_LABEL') }}</label>
        <input id="day" v-model="choice.day" type="date" class="form-control" required>
      </div>
      <div class="col-sm-3">
        <button type="submit" class="btn btn-primary w-100">{{ t('DOCTOR_DAY_PICKER.VIEW_SCHEDULE') }}</button>
      </div>
    </div>
  </form>

  <!-- paciente que já tem uma consulta futura: por que não há botão "Marcar" -->
  <div v-if="schedule?.info" class="alert alert-info">
    {{ t(schedule.info) }} <RouterLink to="/my-area" class="alert-link">{{ t('APP.MENU_MY_AREA') }}</RouterLink>
  </div>

  <!-- 2. a agenda -->
  <p v-if="loading && !schedule" class="text-muted">{{ t('APP.LOADING') }}</p>
  <div v-else-if="schedule" class="card p-3">
    <h5>{{ t('SCHEDULE.TITLE_PREFIX') }} {{ longDate(schedule.day) }} - {{ label(schedule.doctor) }}</h5>
    <table v-if="schedule.slots.length > 0" class="table table-hover align-middle">
      <thead>
        <tr>
          <th>{{ t('SCHEDULE.COLUMN_SLOT') }}</th>
          <th>{{ t('SCHEDULE.COLUMN_STATUS') }}</th>
          <th></th>
        </tr>
      </thead>
      <tbody>
        <tr v-for="s in schedule.slots" :key="s.id" :class="{ 'free-slot': s.bookable }">
          <td>{{ timeRange(s) }}</td>
          <td>
            <span v-if="s.free" class="badge text-bg-success">{{ t('SCHEDULE.FREE') }}</span>
            <span v-else-if="s.patient" class="badge" :class="s.mine ? 'text-bg-primary' : 'text-bg-secondary'">{{ label(s.patient) }}</span>
            <span v-else class="badge text-bg-secondary">{{ t('SCHEDULE.BOOKED_BY_OTHER') }}</span>
          </td>
          <td class="text-end">
            <!-- "Book" is a LINK: it adds ?book=... to the URL, which
                 opens the booking dialog -->
            <RouterLink v-if="s.bookable" class="btn btn-sm btn-outline-success" :to="{ query: { ...scheduleQuery, book: s.id } }">
              {{ t('SCHEDULE.BOOK') }}
            </RouterLink>
            <button v-if="s.appointmentId !== null" type="button" class="btn btn-sm btn-outline-danger" @click="cancel(s)">
              {{ t('SCHEDULE.CANCEL_APPOINTMENT') }}
            </button>
          </td>
        </tr>
      </tbody>
    </table>
    <p v-else class="text-muted mb-0">{{ t('SCHEDULE.NO_SLOTS') }}</p>
  </div>
  <p v-else class="text-muted">{{ t('SCHEDULE.EMPTY_STATE') }}</p>

  <!-- 3. o diálogo de marcação, somente se a URL contiver &book=... -->
  <BookingDialog
    v-if="slotToBook"
    :time="timeRange(slotToBook)"
    :clients="clients"
    :patient="session.isPatient ? (session.user?.name ?? '') : null"
    :submitting="submitting"
    @confirm="book"
    @close="closeBooking"
  />
</template>

Dados da página:

  • linhas 44–48: as listas, o calendário exibido e os indicadores de carregamento e de envio;
  • linha 51: os valores do formulário “médico + dia”. Eles são copiados DA URL; o usuário pode modificá-los sem nenhum efeito até clicar em “View schedule”;
  • linha 60: a [query] do calendário exibido, sem a janela de reserva;
  • linhas 64–67: o horário para o qual a janela está aberta: [?book=...], se ele existir E se puder ser reservado por este usuário. Uma URL criada manualmente ([book=] em um horário ocupado) portanto não abre nenhuma janela de reserva.

Carregamento:

  • linhas 72–82: a lista de médicos é visível para todos, enquanto a lista de pacientes é visível apenas para quem está autorizado a vê-la;
  • linha 85: a página ACOMPANHA a URL. [immediate]: o calendário é carregado assim que a página é exibida (uma URL nos favoritos, um F5); depois, sempre que o médico ou a data na URL mudam (ao clicar em “View schedule” ou nos botões Anterior/Próximo). Uma mudança apenas em [book] não recarrega o calendário: ela apenas abre ou fecha a janela (veja [slotToBook]);
  • linhas 87–116: o dia da URL (hoje, por padrão; ocorre um erro se ele não existir); o médico da URL; se nenhum médico for especificado, um médico logado vê o SEU calendário (o servidor o recupera pelo token), e o médico devolvido pelo servidor é então copiado para o formulário.

Ações:

  • linhas 123–125: “View schedule” não carrega nada por si só: ela altera a URL, e o calendário se atualiza de acordo;
  • linhas 131–157: a consulta:
    • se nenhum paciente for selecionado: o servidor usa o do token;
    • nenhum paciente selecionado (ADMIN, DOCTOR): a janela permanece aberta, exibindo a mensagem;
    • sucesso ou outra rejeição (horário ocupado nesse meio-tempo, paciente que já tem uma consulta): uma mensagem pop-up, depois a URL sem [book] (a janela se fecha), seguida de um recarregamento do calendário: a versão do servidor é definitiva;
  • linhas 159–170: cancelamento, após confirmação. O servidor devolve [appointmentId] para os horários que o usuário pode cancelar: para um ADMIN ou um DOCTOR, todos; para um paciente, os seus próprios (a aplicação HTML só permitia cancelar a partir de “My area”; a API também permite a partir do calendário).

O template:

  • linha 175: seleção do médico e do dia;
  • linha 195: um paciente que já tem uma consulta futura: por que não há botão “Book”;
  • linha 202: o dia, formatado no idioma atual;
  • linhas 216 e 217: o nome do paciente, se ele foi enviado; caso contrário, “Booked”;
  • linha 222: “Book” é um LINK: ele acrescenta [book=...] à URL. O botão Voltar do navegador, portanto, fecha a janela;
  • linhas 237–244: a janela, quando solicitada pela URL.

10.13.3. src/views/persons.config.ts

As páginas de gerenciamento de médicos e clientes são compartilhadas. O que as distingue:

// =========================================================================
// views/persons.config.ts - médicos ou pacientes?
// -------------------------------------------------------------------------
// As páginas para gerenciar médicos e pacientes são IDÊNTICAS: mesma
// lista, mesmo formulário. Como na aplicação HTML (classe abstrata
// PersonsController), são escritas UMA ÚNICA VEZ (PersonsView.vue,
// PersonFormView.vue); apenas o endereço da API e as
// chaves dos rótulos mudam, descritos aqui. O roteador informa o tipo na
// propriedade meta de cada rota (veja router.ts).
// =========================================================================

import type { PersonType } from '../api/rdvmedecins.api';

export interface PersonKeys {
  title: string; // "Médicos"
  add: string; // "Adicionar um médico"
  edit: string; // "Editar um médico"
  empty: string; // "Nenhum médico."
  confirmDelete: string;
  added: string; // "O médico {name} foi adicionado (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 "adicionado / atualizado / excluído"
export function messageParams(p: { firstName: string; lastName: string; login?: string }): Record<string, string> {
  return { name: `${p.firstName} ${p.lastName}`, login: p.login ?? '' };
}
  • linha 25: as chaves dos rótulos específicos de cada tipo, como nos controllers [DoctorsController] e [ClientsController] da aplicação HTML;
  • linhas 49–51: os parâmetros [{name}] e [{login}] das mensagens de “incluído/modificado/excluído”.

10.13.4. src/views/PersonsView.vue

<!--
  =========================================================================
  views/PersonsView.vue - the list of doctors OR of clients (ADMIN)
  -------------------------------------------------------------------------
  A single page for both: the type ('doctors' or 'clients') is in
  the metadata of the route (route.meta.type, see router.ts), the labels
  specific to each in persons.config.ts. Equivalent of
  views/persons/list.hbs of the HTML application.
  =========================================================================
-->
<script setup lang="ts">
import { computed, onMounted, ref } from 'vue';
import { RouterLink, useRoute } from 'vue-router';
import { useI18n } from 'vue-i18n';
import { rdvApi, type PersonType } from '../api/rdvmedecins.api';
import type { Person } from '../api/types';
import { useConfirmation } from '../composables/useConfirmation';
import { useMessagesStore } from '../stores/messages';
import { PERSON_KEYS, messageParams } from './persons.config';

const { t } = useI18n();
const route = useRoute();
const messages = useMessagesStore();
const { confirm } = useConfirmation();

const type = route.meta.type as PersonType;
const keys = PERSON_KEYS[type];
const persons = ref<Person[] | null>(null); // null: ainda não carregado
const empty = computed(() => persons.value !== null && persons.value.length === 0);

async function load(): Promise<void> {
  try {
    persons.value = await rdvApi.list(type);
  } catch (e) {
    messages.showApiError(e);
  }
}

async function remove(p: Person): Promise<void> {
  if (!(await confirm(keys.confirmDelete))) {
    return;
  }
  try {
    await rdvApi.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 load();
}

onMounted(load);
</script>

<template>
  <div class="d-flex justify-content-between align-items-center mb-3">
    <h4 class="mb-0">{{ t(keys.title) }}</h4>
    <RouterLink class="btn btn-primary" :to="`/${type}/add`">{{ t(keys.add) }}</RouterLink>
  </div>

  <div class="card p-3">
    <p v-if="persons === null" class="text-muted mb-0">{{ t('APP.LOADING') }}</p>
    <p v-else-if="empty" class="text-muted mb-0">{{ t(keys.empty) }}</p>
    <table v-else class="table table-hover align-middle mb-0">
      <thead>
        <tr>
          <th>{{ t('PERSONS.COLUMN_TITLE') }}</th>
          <th>{{ t('PERSONS.COLUMN_FIRSTNAME') }}</th>
          <th>{{ t('PERSONS.COLUMN_LASTNAME') }}</th>
          <th>{{ t('PERSONS.COLUMN_LOGIN') }}</th>
          <th></th>
        </tr>
      </thead>
      <tbody>
        <tr v-for="p in persons" :key="p.id">
          <td>{{ p.title }}</td>
          <td>{{ p.firstName }}</td>
          <td>{{ p.lastName }}</td>
          <td><code>{{ p.login }}</code></td>
          <td class="text-end">
            <div class="d-inline-flex gap-2">
              <RouterLink class="btn btn-sm btn-outline-primary" :to="`/${type}/${p.id}/edit`">{{ t('PERSONS.EDIT') }}</RouterLink>
              <button type="button" class="btn btn-sm btn-outline-danger" @click="remove(p)">{{ t('PERSONS.DELETE') }}</button>
            </div>
          </td>
        </tr>
      </tbody>
    </table>
  </div>
</template>
  • linha 26: o tipo de pessoas, lido dos metadados da rota. Ele não mudará durante a vida do componente: ao passar de [/doctors] para [/clients], a chave [:key] do [<RouterView>] recria a página;
  • linha 28: [null] enquanto a lista não tiver sido carregada: isso distingue “carregando” de “lista vazia”;
  • linhas 39–51: confirmação, exclusão, mensagem e recarregamento da lista. Se um médico ainda tiver consultas: o servidor devolve uma resposta 409, e a mensagem é exibida na parte inferior da página.

10.13.5. src/views/PersonFormView.vue

<!--
  =========================================================================
  views/PersonFormView.vue - creation OR update of a doctor
  or of a client (ADMIN)
  -------------------------------------------------------------------------
    /doctors/add               -> creation (no id prop)
    /doctors/3/edit            -> update (prop id = 3, see router.ts)
  (and the same addresses under /clients). Equivalent of
  views/persons/form.hbs of the HTML application.

  No rule is checked here: the server validates everything, and its errors
  are displayed under the fields (see composables/useForm.ts).
  The VERSION read with the record goes back with the update: if another
  ADMIN has changed it in the meantime, the server answers 409 CONCURRENT_UPDATE.
  =========================================================================
-->
<script setup lang="ts">
import { computed, onMounted, reactive } from 'vue';
import { RouterLink, useRoute, useRouter } from 'vue-router';
import { useI18n } from 'vue-i18n';
import { ApiError } from '../api/http-client';
import { rdvApi, type PersonType } from '../api/rdvmedecins.api';
import type { PersonData } from '../api/types';
import { useForm } from '../composables/useForm';
import { useMessagesStore } from '../stores/messages';
import PersonFields from '../components/PersonFields.vue';
import InputField from '../components/InputField.vue';
import { PERSON_KEYS, messageParams } from './persons.config';

const props = defineProps<{ id?: number }>();

const { t } = useI18n();
const route = useRoute();
const router = useRouter();
const messages = useMessagesStore();
const { errors, params, submitting, submit } = useForm();

const type = route.meta.type as PersonType;
const keys = PERSON_KEYS[type];
const creating = computed(() => props.id === undefined);

const form = reactive<PersonData>({ title: 'Mr', firstName: '', lastName: '', login: '', password: '', version: undefined });

// atualização: o registro é lido (incluindo sua versão)
onMounted(async () => {
  if (props.id === undefined) {
    return;
  }
  try {
    const p = await rdvApi.read(type, props.id);
    Object.assign(form, { title: p.title, firstName: p.firstName, lastName: p.lastName, login: p.login ?? '', version: p.version });
  } catch (e) {
    // registro que não existe (excluído nesse meio tempo...): de volta à lista
    if (e instanceof ApiError) {
      messages.flash('error', e.key, e.params);
      router.push(`/${type}`);
      return;
    }
    throw e;
  }
});

async function save(): Promise<void> {
  const succeeded = await submit(async () => {
    const p = props.id === undefined ? await rdvApi.add(type, form) : await rdvApi.edit(type, props.id, form);
    messages.flash('success', creating.value ? keys.added : keys.edited, messageParams(p));
  });
  if (succeeded) {
    router.push(`/${type}`);
  } else if (messages.error?.key === 'ERRORS.DOCTOR_NOT_FOUND' || messages.error?.key === 'ERRORS.PATIENT_NOT_FOUND') {
    // excluído nesse meio tempo por outro ADMIN: de volta à lista
    messages.flash('error', messages.error.key);
    router.push(`/${type}`);
  }
}
</script>

<template>
  <div class="row justify-content-center">
    <div class="col-md-8 col-lg-6">
      <div class="card p-4">
        <h5 class="card-title mb-3">{{ t(creating ? keys.add : keys.edit) }}</h5>
        <!-- novalidate: é o SERVIDOR quem valida (ele é a referência) -->
        <form novalidate @submit.prevent="save">
          <PersonFields v-model:title="form.title" v-model:firstName="form.firstName" v-model:lastName="form.lastName" :errors="errors" />

          <h6 class="mt-4 text-muted">{{ t('PERSONS.ACCOUNT_SECTION') }}</h6>
          <InputField v-model="form.login" class="mb-3" id="login" label="PERSONS.LOGIN_LABEL" :maxlength="30"
                      :error="errors.login" :help="creating ? 'PERSONS.LOGIN_HELP_CREATE' : 'PERSONS.LOGIN_HELP_EDIT'" />
          <!-- nunca preenchido previamente: a senha nunca volta do servidor -->
          <InputField v-model="form.password" class="mb-4" id="password" type="password" label="PERSONS.PASSWORD_LABEL"
                      :maxlength="72" autocomplete="new-password" :error="errors.password" :params="params"
                      :help="creating ? 'PERSONS.PASSWORD_HELP_CREATE' : 'PERSONS.PASSWORD_HELP_EDIT'" />

          <div class="d-flex gap-2">
            <button type="submit" class="btn btn-primary" :disabled="submitting">{{ t('PERSONS.SAVE') }}</button>
            <RouterLink class="btn btn-secondary" :to="`/${type}`">{{ t('PERSONS.BACK') }}</RouterLink>
          </div>
        </form>
      </div>
    </div>
  </div>
</template>
  • linha 30: criação sem [id], modificação com ele (a propriedade vem da rota; veja [router.ts]);
  • linha 36: erros do formulário (veja [useForm.ts]);
  • linhas 45–61: durante a modificação, lê-se o registro, incluindo a versão. Se ele não existir (excluído nesse meio-tempo), volta-se à lista com uma mensagem;
  • linhas 63–75: POST ou PUT; se der certo, exibe-se uma mensagem e volta-se à lista. Se a operação falhar, o [useForm] já exibiu os erros; se um registro tiver sido excluído nesse meio-tempo, o programa volta à lista;
  • linha 84: [novalidate]: o servidor faz essa validação;
  • linha 85: os três [v-model] nomeados;
  • linha 91: a senha nunca é pré-preenchida: ela nunca é devolvida pelo servidor.

10.13.6. src/views/RegisterView.vue

<!--
  =========================================================================
  views/RegisterView.vue - "Create a patient account" (/register, public)
  -------------------------------------------------------------------------
  One only gets here after typing the captcha of the login page
  (button "Create a patient account"): the server has then issued a
  pass, which the route guard has checked (see router.ts).
  Same fields as the ADMIN's form, but the login and the password
  are required, with confirmation. Equivalent of
  views/account/registration.hbs of the HTML application.
  =========================================================================
-->
<script setup lang="ts">
import { reactive } from 'vue';
import { RouterLink, useRouter } from 'vue-router';
import { useI18n } from 'vue-i18n';
import { rdvApi } from '../api/rdvmedecins.api';
import type { Registration } from '../api/types';
import { useForm } from '../composables/useForm';
import { useMessagesStore } from '../stores/messages';
import PersonFields from '../components/PersonFields.vue';
import InputField from '../components/InputField.vue';

const { t } = useI18n();
const router = useRouter();
const messages = useMessagesStore();
const { errors, params, submitting, submit } = useForm();

// 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';

const form = reactive<Registration>({ title: 'Mr', firstName: '', lastName: '', login: '', password: '', confirmation: '' });

async function create(): Promise<void> {
  let login = '';
  const succeeded = await submit(async () => {
    login = (await rdvApi.register(form)).login;
  });
  if (succeeded) {
    // de volta à página de login, com o login preenchido
    messages.flash('success', 'REGISTRATION.DONE', { login });
    router.push({ name: 'login', query: { login } });
  } else if (messages.error?.key === 'ERRORS.CAPTCHA_BEFORE_ACCOUNT') {
    // passe expirado (15 minutos): de volta ao captcha
    messages.flash('error', 'ERRORS.CAPTCHA_BEFORE_ACCOUNT');
    router.push({ name: 'login' });
  }
}
</script>

<template>
  <div class="row justify-content-center">
    <div class="col-md-8 col-lg-6">
      <div class="card p-4">
        <h5 class="card-title mb-1">{{ t('REGISTRATION.TITLE') }}</h5>
        <p class="text-muted small mb-3">{{ t('REGISTRATION.INTRO') }}</p>
        <form novalidate @submit.prevent="create">
          <PersonFields v-model:title="form.title" v-model:firstName="form.firstName" v-model:lastName="form.lastName" :errors="errors" />

          <h6 class="mt-4 text-muted">{{ t('PERSONS.ACCOUNT_SECTION') }}</h6>
          <InputField v-model="form.login" class="mb-3" id="login" label="PERSONS.LOGIN_LABEL" :maxlength="30"
                      autocomplete="username" required :error="errors.login" help="REGISTRATION.LOGIN_HELP" />
          <div class="row g-3 mb-3">
            <InputField v-model="form.password" class="col-sm-6" id="password" type="password" label="PERSONS.PASSWORD_LABEL"
                        :maxlength="72" autocomplete="new-password" required :error="errors.password"
                        :params="{ min: PASSWORD_MIN, ...params }" help="REGISTRATION.PASSWORD_HELP" />
            <InputField v-model="form.confirmation" class="col-sm-6" id="confirmation" type="password"
                        label="ACCOUNT.CONFIRMATION_LABEL" :maxlength="72" autocomplete="new-password" required
                        :error="errors.confirmation" />
          </div>
          <div class="d-flex gap-2">
            <button type="submit" class="btn btn-primary" :disabled="submitting">{{ t('REGISTRATION.SUBMIT') }}</button>
            <RouterLink class="btn btn-secondary" to="/login">{{ t('REGISTRATION.BACK_TO_LOGIN') }}</RouterLink>
          </div>
        </form>
      </div>
    </div>
  </div>
</template>
  • linha 31: o tamanho mínimo da senha, para a mensagem de ajuda (o servidor também o devolve em [params], junto com o erro);
  • linhas 35–49: criação da conta, seguida da página de login com o nome de usuário pré-preenchido. Se o token tiver expirado (15 minutos), o servidor responde com um erro 403: volte à página de login para resolver um novo CAPTCHA;
  • linha 67: os parâmetros da mensagem do campo; [...params] (o operador spread) copia os devolvidos pelo servidor.

O acesso a esta página é controlado pelo guard [beforeEnter] de sua rota (veja [router.ts]).

10.13.7. src/views/PatientAreaView.vue

<!--
  =========================================================================
  views/PatientAreaView.vue - "My area" (/my-area, USER role)
  -------------------------------------------------------------------------
  The home page of the patient, right after login:
    - two options: [Manage my account] and [View a schedule];
    - their upcoming appointment, if they have one, with the means to cancel it.
  Equivalent of views/patient/area.hbs of the HTML application.
  =========================================================================
-->
<script setup lang="ts">
import { onMounted, ref } from 'vue';
import { RouterLink } from 'vue-router';
import { useI18n } from 'vue-i18n';
import { rdvApi } from '../api/rdvmedecins.api';
import type { MyArea } from '../api/types';
import { useFormatting } from '../composables/useFormatting';
import { useConfirmation } from '../composables/useConfirmation';
import { useMessagesStore } from '../stores/messages';

const { t } = useI18n();
const messages = useMessagesStore();
const { label, timeRange, longDate } = useFormatting();
const { confirm } = useConfirmation();

const area = ref<MyArea | null>(null);

async function load(): Promise<void> {
  try {
    area.value = await rdvApi.myArea();
  } catch (e) {
    messages.showApiError(e);
  }
}

async function cancel(appointmentId: number): Promise<void> {
  if (!(await confirm('SCHEDULE.CANCEL_CONFIRM'))) {
    return;
  }
  try {
    await rdvApi.cancelAppointment(appointmentId);
    messages.showSuccess('SCHEDULE.CANCELLED');
  } catch (e) {
    messages.showApiError(e);
  }
  await load();
}

onMounted(load);
</script>

<template>
  <template v-if="area">
    <h4 class="mb-3">{{ t('AREA.HELLO', { name: label(area.patient) }) }}</h4>
    <div class="row g-3 mb-4">
      <div class="col-sm-6">
        <RouterLink class="card p-4 h-100 text-decoration-none option-card" to="/my-account">
          <h5 class="mb-1">{{ t('AREA.MANAGE_ACCOUNT') }}</h5>
          <span class="text-muted">{{ t('AREA.MANAGE_ACCOUNT_HELP') }}</span>
        </RouterLink>
      </div>
      <div class="col-sm-6">
        <RouterLink class="card p-4 h-100 text-decoration-none option-card" to="/schedule">
          <h5 class="mb-1">{{ t('AREA.VIEW_SCHEDULE') }}</h5>
          <span class="text-muted">{{ t('AREA.VIEW_SCHEDULE_HELP') }}</span>
        </RouterLink>
      </div>
    </div>

    <div class="card p-3">
      <h5>{{ t('AREA.MY_APPOINTMENT') }}</h5>
      <!-- normally only one (rule "one upcoming appointment at a time"),
           but the page can display several -->
      <div
        v-for="(a, i) in area.appointments"
        :key="a.id"
        class="d-flex flex-wrap justify-content-between align-items-center gap-2 py-2"
        :class="{ 'border-bottom': i < area.appointments.length - 1 }"
      >
        <div>
          <div class="fw-semibold">{{ longDate(a.day) }}, {{ timeRange(a.slot) }}</div>
          <div class="text-muted">
            {{ label(a.doctor) }} -
            <!-- a agenda do médico nesse dia: o paciente vê seu nome nela -->
            <RouterLink :to="{ path: '/schedule', query: { doctorId: a.doctor.id, day: a.day } }">{{ t('AREA.SEE_IN_SCHEDULE') }}</RouterLink>
          </div>
        </div>
        <button type="button" class="btn btn-outline-danger" @click="cancel(a.id)">{{ t('AREA.CANCEL_APPOINTMENT') }}</button>
      </div>
      <p v-if="area.appointments.length === 0" class="text-muted mb-0">{{ t('AREA.NO_APPOINTMENT') }}</p>
    </div>
  </template>
  <p v-else class="text-muted">{{ t('APP.LOADING') }}</p>
</template>
  • linhas 36–47: o paciente cancela a SUA consulta (o servidor rejeitaria a de outra pessoa);
  • linha 57: um card inteiro é um link;
  • linha 75: normalmente apenas uma consulta (a regra de “uma consulta futura por vez”), mas a página pode exibir várias;
  • linha 85: a agenda do médico naquele dia, na qual o paciente vê o seu nome.

10.13.8. src/views/MyAccountView.vue

<!--
  =========================================================================
  views/MyAccountView.vue - "Manage my account" (/my-account, USER role)
  -------------------------------------------------------------------------
  Two independent forms, like views/patient/account.hbs:
    1. the update (identity, login, optional new password);
    2. the deletion of the account - which also cancels its appointments.
  Both require the CURRENT password (checked by the server).
  =========================================================================
-->
<script setup lang="ts">
import { onMounted, reactive, ref } from 'vue';
import { RouterLink, useRouter } from 'vue-router';
import { useI18n } from 'vue-i18n';
import { rdvApi } from '../api/rdvmedecins.api';
import type { MyAccountUpdate } from '../api/types';
import { useForm } from '../composables/useForm';
import { useConfirmation } from '../composables/useConfirmation';
import { useSessionStore } from '../stores/session';
import { useMessagesStore } from '../stores/messages';
import PersonFields from '../components/PersonFields.vue';
import InputField from '../components/InputField.vue';

const { t } = useI18n();
const router = useRouter();
const session = useSessionStore();
const messages = useMessagesStore();
const { confirm } = useConfirmation();
// dois formulários, portanto dois conjuntos de erros
const update = useForm();
const deletion = useForm();

const form = reactive<MyAccountUpdate>({
  title: 'Mr',
  firstName: '',
  lastName: '',
  login: '',
  password: '',
  confirmation: '',
  currentPassword: '',
  version: 0,
});
const deletePassword = ref('');

onMounted(async () => {
  try {
    Object.assign(form, await rdvApi.myAccount());
  } catch (e) {
    messages.showApiError(e);
  }
});

async function save(): Promise<void> {
  const succeeded = await update.submit(async () => {
    // o servidor emitiu um NOVO token (nome, login): a barra de
    // navegação deve acompanhar
    session.update(await rdvApi.editMyAccount(form));
    messages.flash('success', 'MY_ACCOUNT.UPDATED');
  });
  // nunca deixe uma senha nos campos após um envio
  form.currentPassword = '';
  if (succeeded) {
    router.push('/my-area');
  }
}

async function remove(): Promise<void> {
  if (!(await confirm('MY_ACCOUNT.DELETE_CONFIRM'))) {
    return;
  }
  const succeeded = await deletion.submit(async () => {
    await rdvApi.deleteMyAccount(deletePassword.value);
  });
  deletePassword.value = '';
  if (succeeded) {
    session.forget(); // o servidor apagou o cookie do token
    messages.flash('success', 'MY_ACCOUNT.DELETED');
    router.push({ name: 'login' });
  }
}
</script>

<template>
  <div class="row justify-content-center">
    <div class="col-md-8 col-lg-6">
      <!-- 1. atualização -->
      <div class="card p-4 mb-4">
        <h5 class="card-title mb-3">{{ t('MY_ACCOUNT.TITLE') }}</h5>
        <form novalidate @submit.prevent="save">
          <PersonFields v-model:title="form.title" v-model:firstName="form.firstName" v-model:lastName="form.lastName" :errors="update.errors.value" />

          <h6 class="mt-4 text-muted">{{ t('PERSONS.ACCOUNT_SECTION') }}</h6>
          <InputField v-model="form.login" class="mb-3" id="login" label="PERSONS.LOGIN_LABEL" :maxlength="30"
                      autocomplete="username" required :error="update.errors.value.login" />
          <div class="row g-3 mb-3">
            <InputField v-model="form.password" class="col-sm-6" id="password" type="password" label="MY_ACCOUNT.NEW_PASSWORD_LABEL"
                        :maxlength="72" autocomplete="new-password" :error="update.errors.value.password"
                        :params="update.params.value" help="PERSONS.PASSWORD_HELP_EDIT" />
            <InputField v-model="form.confirmation" class="col-sm-6" id="confirmation" type="password"
                        label="ACCOUNT.CONFIRMATION_LABEL" :maxlength="72" autocomplete="new-password"
                        :error="update.errors.value.confirmation" />
          </div>
          <InputField v-model="form.currentPassword" class="mb-4" id="currentPassword" type="password"
                      label="MY_ACCOUNT.CURRENT_PASSWORD_LABEL" :maxlength="72" autocomplete="current-password" required
                      :error="update.errors.value.currentPassword" help="MY_ACCOUNT.CURRENT_PASSWORD_HELP" />
          <div class="d-flex gap-2">
            <button type="submit" class="btn btn-primary" :disabled="update.submitting.value">{{ t('PERSONS.SAVE') }}</button>
            <RouterLink class="btn btn-secondary" to="/my-area">{{ t('MY_ACCOUNT.BACK') }}</RouterLink>
          </div>
        </form>
      </div>

      <!-- 2. exclusão -->
      <div class="card p-4 border-danger">
        <h5 class="card-title text-danger mb-1">{{ t('MY_ACCOUNT.DELETE_TITLE') }}</h5>
        <p class="text-muted small">{{ t('MY_ACCOUNT.DELETE_HELP') }}</p>
        <form class="d-flex flex-wrap gap-2 align-items-end" novalidate @submit.prevent="remove">
          <InputField v-model="deletePassword" class="flex-grow-1" id="deletePassword" type="password"
                      label="MY_ACCOUNT.CURRENT_PASSWORD_LABEL" :maxlength="72" autocomplete="current-password" required
                      :error="deletion.errors.value.currentPassword" />
          <button type="submit" class="btn btn-danger" :disabled="deletion.submitting.value">{{ t('MY_ACCOUNT.DELETE_SUBMIT') }}</button>
        </form>
      </div>
    </div>
  </div>
</template>
  • linhas 30–31: dois formulários, portanto dois conjuntos de erros: um composable pode ser chamado quantas vezes se quiser, e cada chamada tem seu próprio estado;
  • linha 47: os valores lidos são copiados para o formulário, incluindo a versão;
  • linhas 53–65: o servidor emitiu um novo token (o nome e o login podem ter mudado); ele devolve o usuário conforme descrito por esse token, e a sessão é atualizada: a barra de navegação acompanha. A senha atual é apagada após cada envio;
  • linhas 67–80: confirmação, exclusão; o servidor apagou o cookie do token: o usuário é esquecido e redirecionado de volta à página de login;
  • linha 90: [update] é um objeto comum que CONTÉM [ref]s: no template, é preciso escrever [.value] (veja o Exemplo 11).

10.13.9. src/views/ErrorView.vue

<!--
  views/ErrorView.vue - the error page: 404 (unknown address) or 403
  (insufficient role, see the router guard). Equivalent of views/error.hbs.
-->
<script setup lang="ts">
import { computed } from 'vue';
import { RouterLink } from 'vue-router';
import { useI18n } from 'vue-i18n';

const props = defineProps<{ code: 403 | 404 }>();
const { t } = useI18n();
const message = computed(() => (props.code === 403 ? 'ERRORS.FORBIDDEN' : 'ERRORS.NOT_FOUND'));
</script>

<template>
  <div class="card p-4">
    <h4 class="text-danger">{{ t('ERROR_PAGE.TITLE') }} {{ code }}</h4>
    <p>{{ t(message) }}</p>
    <RouterLink to="/" class="btn btn-primary align-self-start">{{ t('ERROR_PAGE.BACK') }}</RouterLink>
  </div>
</template>

A página de erro para uma URL desconhecida (404) ou para uma página restrita ao papel do usuário (403).