Skip to content

10. Estudo de caso: o cliente Angular 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 [Angular]: 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 em um determinado dia, com marcação de consultas (janela de seleção de paciente) e cancelamento;
  • para o administrador, gerenciamento de médicos e clientes (listar, adicionar, editar, excluir);
  • para o paciente, um painel pessoal (mostrando as próximas consultas, 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, salvas nos favoritos e percorridas com os botões Voltar/Avançar do navegador.

10.2. Instalação e execução

O servidor JSON deve estar instalado e em execução (veja o capítulo "O servidor RdvMedecins: uma caixa-preta"). Para usar o cliente em um navegador, você não precisa do modo de teste do CAPTCHA: pode deixar o campo [CAPTCHA_TEST] em branco no arquivo [.env] do servidor.

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

npm install
npm start

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

Os exemplos também usam a porta 4200: primeiro, pare o exemplo em execução ([Ctrl-C]). Você também pode iniciar o cliente em outra porta: [npm start -- --port 4300].

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. A agenda, vista pelo administrador e pelos médicos

Ao fazer login como [admin], você é levado à agenda:

Image

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

Image

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

Image

A consulta é salva:

Image

"Cancel" pede confirmação:

Image

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

Image

10.3.3. O portal do paciente

Um paciente ([martin]) chega a "My area":

Image

Na agenda, ele vê "Booked" ao lado dos horários de consulta de outros pacientes:

Image

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

Image

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

Image

Seu painel mostra o seguinte:

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, que é reservado ao administrador:

Image

10.3.4. Gerenciamento de médicos e clientes

Image

Um cadastro preenchido incorretamente:

Image

Uma adição bem-sucedida:

Image

Um homônimo:

Image

O pedido de exclusã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 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; o título da aba do navegador também é traduzido:

Image

10.3.7. Sessão expirada, endereço desconhecido

Se o token expirar (ou se o cookie for excluído), 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

rdvmedecins-angular/
├── angular.json, package.json, tsconfig.json, proxy.conf.json
├── public/favicon.svg                the tab icon
└── src/
    ├── index.html                    THE page of the application
    ├── main.ts                       the startup
    ├── styles.css
    └── app/
        ├── app.config.ts             the configuration of the application
        ├── app.ts                    the layout shared by all the pages
        ├── app.routes.ts             the pages and their access rights
        ├── guards.ts                 the router guards
        ├── api/                      the API access layer
        ├── i18n/                     the languages
        ├── services/                 session, messages, confirmation, forms
        ├── pipes/                    the formatting
        ├── components/               the reusable components
        └── pages/                    the pages

Image

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

Aplicação HTML (NestJS)
Cliente Angular
O servidor gera cada página ([res.render])
O servidor retorna JSON; os componentes de [src/app/pages/] geram as páginas
[views/layout.hbs] e suas views parciais
[app.ts] e os componentes de [src/app/components/]
as rotas do controller ([@Get('my-area')])
rotas do cliente ([app.routes.ts]); o servidor só tem rotas /api/...
[JwtAuthGuard] e [RolesGuard] redirecionam para /login ou para uma página 403
guards do roteador; o servidor mantém seus próprios guards, que retornam 401 ou 403
mensagem flash em um cookie
mensagem flash em um serviço, [MessagesService]
dicionários lidos pelo servidor, helper [{{t}}]
dicionários no cliente, [ngx-translate]; o servidor retorna apenas chaves
idioma armazenado em um cookie
idioma armazenado no [localStorage]
formulário rejeitado: o servidor recarrega a página
formulário rejeitado: resposta 400/409; o cliente exibe os erros abaixo dos campos
Janela de confirmação: um pequeno script, [public/js/app.js]
um serviço e um componente, [ConfirmDialog]
A aplicação funciona sem JavaScript
A aplicação É JavaScript

O cliente [Vue.js] da lição anterior tem exatamente a mesma estrutura: as "stores" ([Pinia]) viraram serviços, os "composables" viraram serviços ou funções, e as views viraram páginas.

Todos os arquivos do cliente são apresentados a seguir. Eles são amplamente comentados; esses comentários fazem parte do curso.

10.4.1. Configuração do projeto

10.4.1.1. package.json

{
  "name": "rdvmedecins-angular",
  "version": "1.0.0",
  "description": "Angular client of the medical appointment booking application [RdvMedecins] - client of the JSON server [rdvmedecins-nestjs-json]",
  "private": true,
  "scripts": {
    "ng": "ng",
    "start": "ng serve",
    "build": "ng build"
  },
  "dependencies": {
    "@angular/common": "^22.2.0",
    "@angular/compiler": "^22.2.0",
    "@angular/core": "^22.2.0",
    "@angular/forms": "^22.2.0",
    "@angular/platform-browser": "^22.2.0",
    "@angular/router": "^22.2.0",
    "@ngx-translate/core": "^18.0.0",
    "bootstrap": "^5.3.8",
    "rxjs": "~7.8.0",
    "tslib": "^2.8.0"
  },
  "devDependencies": {
    "@angular/build": "^22.2.0",
    "@angular/cli": "^22.2.0",
    "@angular/compiler-cli": "^22.2.0",
    "typescript": "~6.0.2"
  }
}
  • linhas 8–9: [npm start] inicia o servidor de desenvolvimento; [npm run build] gera o build de produção;
  • linhas 11–22: as bibliotecas usadas pela aplicação: as do [Angular], [ngx-translate], [Bootstrap] e [RxJS];
  • linhas 23–28: as ferramentas de desenvolvimento: o compilador do [Angular], o comando [ng] e o [TypeScript].

10.4.1.2. angular.json

{
  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
  "version": 1,
  "cli": {
    "packageManager": "npm",
    "analytics": false
  },
  "projects": {
    "rdvmedecins-angular": {
      "projectType": "application",
      "root": "",
      "sourceRoot": "src",
      "prefix": "app",
      "architect": {
        "build": {
          "builder": "@angular/build:application",
          "options": {
            "browser": "src/main.ts",
            "tsConfig": "tsconfig.app.json",
            "assets": [{ "glob": "**/*", "input": "public" }],
            "styles": ["node_modules/bootstrap/dist/css/bootstrap.min.css", "src/styles.css"]
          },
          "configurations": {
            "production": {
              "budgets": [
                { "type": "initial", "maximumWarning": "800kB", "maximumError": "1MB" },
                { "type": "anyComponentStyle", "maximumWarning": "4kB", "maximumError": "8kB" }
              ],
              "outputHashing": "all"
            },
            "development": {
              "optimization": false,
              "extractLicenses": false,
              "sourceMap": true
            }
          },
          "defaultConfiguration": "production"
        },
        "serve": {
          "builder": "@angular/build:dev-server",
          "options": {
            "proxyConfig": "proxy.conf.json"
          },
          "configurations": {
            "production": { "buildTarget": "rdvmedecins-angular:build:production" },
            "development": { "buildTarget": "rdvmedecins-angular:build:development" }
          },
          "defaultConfiguration": "development"
        }
      }
    }
  }
}

Desta vez, apenas um projeto, na raiz da pasta (linha 11):

  • linha 18: o ponto de entrada da aplicação;
  • linha 20: o conteúdo da pasta [public] é copiado sem alterações para a aplicação compilada (o ícone);
  • linha 21: as folhas de estilo globais: a do [Bootstrap], seguida da nossa;
  • linhas 24–30: a configuração de produção. Os budgets disparam um aviso (ou um erro) se a aplicação ultrapassar o tamanho especificado; [outputHashing] adiciona uma impressão digital do conteúdo ao nome de cada arquivo (veja o capítulo "Implantação");
  • linha 37: [ng build] gera a versão de produção por padrão;
  • linha 42: o proxy do servidor de desenvolvimento;
  • linha 48: [ng serve] usa a configuração de desenvolvimento (código não otimizado, "source maps" para o depurador).

10.4.1.3. tsconfig.json, tsconfig.app.json, proxy.conf.json

{
  "compilerOptions": {
    "strict": true,
    "noImplicitOverride": true,
    "noPropertyAccessFromIndexSignature": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "skipLibCheck": true,
    "isolatedModules": true,
    "experimentalDecorators": true,
    "importHelpers": true,
    "resolveJsonModule": true,
    "target": "ES2022",
    "module": "preserve"
  },
  "angularCompilerOptions": {
    "strictInjectionParameters": true,
    "strictInputAccessModifiers": true,
    "strictTemplates": true
  },
  "files": [],
  "references": [
    {
      "path": "./tsconfig.app.json"
    }
  ]
}
  • Linha 3: o modo estrito do [TypeScript];
  • linha 14: a importação dos arquivos JSON (os dicionários);
  • linha 21: o compilador do [Angular] também verifica os tipos nos templates.
1
2
3
4
{
  "extends": "./tsconfig.json",
  "include": ["src/**/*.ts"]
}
1
2
3
4
5
6
{
  "/api": {
    "target": "http://localhost:8080",
    "secure": false
  }
}

O proxy do Exemplo 22: as requisições /api/... são encaminhadas ao servidor JSON.

10.4.2. Inicialização da aplicação

10.4.2.1. index.html

<!doctype html>
<!--
  index.html - A página da aplicação (Single Page Application).
  O servidor nunca envia outra: todo o resto é construído no
  navegador pelo Angular, em <app-root>. lang e title são
  atualizados pela aplicação conforme o idioma e a página exibida.
-->
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>RdvMedecins</title>
  <base href="/">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link rel="icon" href="favicon.svg" type="image/svg+xml">
</head>
<body>
  <app-root></app-root>
  <!-- sem JavaScript, uma aplicação Angular não consegue exibir nada: avisamos isso -->
  <noscript>RdvMedecins requires JavaScript. / RdvMedecins a besoin de JavaScript.</noscript>
</body>
</html>
  • Linha 17: o elemento em que o [Angular] exibe o componente raiz;
  • linha 19: sem [JavaScript], uma aplicação [Angular] não consegue exibir nada: avisamos isso.

10.4.2.2. src/main.ts

// =========================================================================
// main.ts - a inicialização da aplicação
// -------------------------------------------------------------------------
// O componente raiz (App) e a configuração da aplicação
// (app.config.ts). As folhas de estilo (Bootstrap, styles.css) são
// declaradas em angular.json.
// =========================================================================

import { bootstrapApplication } from '@angular/platform-browser';
import { App } from './app/app';
import { appConfig } from './app/app.config';

bootstrapApplication(App, appConfig).catch((error) => console.error(error));

10.4.2.3. src/app/app.config.ts

// =========================================================================
// app.config.ts - a configuração da aplicação
// -------------------------------------------------------------------------
//   - o roteador, suas rotas (app.routes.ts), os parâmetros de rota
//     passados aos inputs das páginas e o título da aba traduzido;
//   - HttpClient, com o interceptor dos erros e do 401;
//   - ngx-translate (francês e inglês).
// =========================================================================

import { ApplicationConfig, provideBrowserGlobalErrorListeners } from '@angular/core';
import { provideHttpClient, withInterceptors } from '@angular/common/http';
import { provideRouter, TitleStrategy, withComponentInputBinding } from '@angular/router';
import { routes } from './app.routes';
import { apiInterceptor } from './api/api.interceptor';
import { provideI18n } from './i18n/i18n';
import { TranslatedTitle } from './i18n/title.strategy';

export const appConfig: ApplicationConfig = {
  providers: [
    // os erros não tratados são reportados no console do navegador
    provideBrowserGlobalErrorListeners(),
    provideRouter(routes, withComponentInputBinding()),
    { provide: TitleStrategy, useClass: TranslatedTitle },
    provideHttpClient(withInterceptors([apiInterceptor])),
    provideI18n(),
  ],
};
  • linha 21: erros não tratados (como uma promise rejeitada que ninguém está aguardando) são reportados no console do navegador;
  • linha 22: o roteador, com os parâmetros de rota repassados aos inputs da página (exemplo 17);
  • Linha 23: [TitleStrategy] é o serviço do roteador que define o título da aba após cada navegação. Nós substituímos o serviço do [Angular] pelo nosso ([i18n/title.strategy.ts]), que traduz o título. Este é o ponto central da injeção de dependência: você pode substituir uma classe do framework pela sua própria sem alterar mais nada;
  • linha 24: o cliente HTTP, com o nosso interceptor;
  • linha 25: [ngx-translate].

10.4.2.4. src/app/app.ts

// =========================================================================
// app.ts - o componente raiz: o LAYOUT comum a todas as páginas
// -------------------------------------------------------------------------
// O equivalente de views/layout.hbs da aplicação HTML:
//   - a barra de navegação;
//   - uma mensagem de sucesso no TOPO;
//   - a página atual (<router-outlet>);
//   - o painel de erros na PARTE INFERIOR;
//   - o diálogo de confirmação, uma vez para a aplicação inteira.
// =========================================================================

import { Component } from '@angular/core';
import { RouterOutlet } from '@angular/router';
import { NavBar } from './components/nav-bar/nav-bar';
import { SuccessMessage } from './components/success-message';
import { ErrorPanel } from './components/error-panel';
import { ConfirmDialog } from './components/confirm-dialog/confirm-dialog';

@Component({
  selector: 'app-root',
  imports: [RouterOutlet, NavBar, SuccessMessage, ErrorPanel, ConfirmDialog],
  template: `
    <div class="container py-4">
      <app-nav-bar />
      <app-success-message />
      <router-outlet />
      <app-error-panel />
    </div>
    <app-confirm-dialog />
  `,
})
export class App {}
  • Linhas 22–30: o template comum a todas as páginas: a barra de navegação, a mensagem de sucesso, a página atual, a área de erros e a janela de confirmação (Exemplo 16).

10.4.2.5. src/styles.css

/* =========================================================================
   styles.css - alguns ajustes sobre o Bootstrap
   (extraídos de public/css/styles.css da aplicação HTML)
   ========================================================================= */

body {
  background-color: #f5f7fa;
}

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

/* -------------------------------------------------------------------------
   .error-panel: as mensagens de erro, na parte inferior da página, sobre um fundo
   rosa claro (veja components/error-panel.ts).
   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 acinzentado 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 dele.
   ------------------------------------------------------------------------- */
.error-panel {
  position: sticky;
  bottom: 1rem;
  z-index: 1060;
  pointer-events: none;
  margin-top: 1.5rem;
  padding: 0.75rem 1rem;
  background-color: #fdecef; /* rosa claro */
  border: 1px solid #f5c2c7;
  border-radius: 0.375rem;
  color: #842029;
}

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

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

/* a imagem do captcha (SVG de 150 x 50 pixels), inserida por [innerHTML]:
   somente um estilo GLOBAL, como este, consegue alcançá-la */
.captcha-image svg {
  display: block;
  border: 1px solid #dee2e6;
  border-radius: 0.375rem;
}
  • Linhas 24–35: a área de erros na parte inferior da página;
  • linhas 49–53: a imagem do CAPTCHA. Como no Exemplo 24, um [<svg>] inserido por [[innerHTML]] só recebe estilo de um estilo global.

10.4.3. A camada de acesso à API

10.4.3.1. src/app/api/types.ts

// =========================================================================
// api/types.ts - os objetos JSON trocados com o servidor
// -------------------------------------------------------------------------
// A tradução, em interfaces TypeScript, da API descrita no
// capítulo "O servidor, uma caixa-preta". O compilador verifica assim que o cliente
// só usa campos que realmente existem.
// =========================================================================

export type Role = 'ADMIN' | 'DOCTOR' | 'USER';

// POST /api/auth/login, GET /api/auth/me, PUT /api/my-account
export interface User {
  login: string;
  name: string; // nome exibido: "Marie PELISSIER"
  role: Role;
}

// GET /api/captcha
export interface Captcha {
  id: string;
  svg: string;
}

// um título, um nome, um sobrenome
export interface Identity {
  title: string;
  firstName: string;
  lastName: string;
}

// um médico ou um cliente: GET /api/doctors, GET /api/clients/:id...
export interface Person extends Identity {
  id: number;
  version: number; // bloqueio otimista: a ser reenviado em 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; // o mesmo
  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 ocupada por outro paciente
  mine: boolean; // a consulta do paciente logado
  bookable: boolean;
  appointmentId: number | null; // definido se o usuário pode 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;
}

A tradução para interfaces [TypeScript] da API descrita no capítulo "O servidor RdvMedecins: uma caixa-preta". A palavra-chave [extends] evita repetir campos comuns: uma [Person] é uma [Identity] (título, nome, sobrenome) com um identificador e uma versão.

10.4.3.2. src/app/api/api-error.ts

// =========================================================================
// api/api-error.ts - UMA classe para todos os erros da API
// -------------------------------------------------------------------------
// Extraído de common/api-error.ts dos exemplos. Qualquer erro de uma requisição
// (resposta 4xx / 5xx do servidor, servidor inacessível, resposta de um proxy)
// torna-se um ApiError, que carrega a CHAVE de tradução da mensagem, seus
// parâmetros e o erro de cada campo de um formulário rejeitado.
// =========================================================================

import { HttpErrorResponse } from '@angular/common/http';

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

export function toApiError(e: unknown): ApiError {
  if (e instanceof ApiError) {
    return e;
  }
  if (!(e instanceof HttpErrorResponse)) {
    return new ApiError(0, 'ERRORS.SERVER_ERROR');
  }
  const body = (typeof e.error === 'object' && e.error !== null ? e.error : {}) as {
    key?: string;
    params?: Record<string, string>;
    fields?: Record<string, string>;
  };
  return new ApiError(
    e.status,
    // sem key: não foi o nosso servidor que respondeu, mas a rede
    // ou um proxy (ng serve: 500 sem corpo; nginx: 502, 504...)
    body.key ?? (e.status === 0 || e.status >= 500 ? 'ERRORS.SERVER_UNREACHABLE' : 'ERRORS.SERVER_ERROR'),
    body.params,
    body.fields,
  );
}

O arquivo [common/api-error.ts] do Exemplo 24.

10.4.3.3. src/app/api/api.interceptor.ts

// =========================================================================
// api/api.interceptor.ts - o interceptor de TODAS as requisições à API
// -------------------------------------------------------------------------
// Extraído de common/errors.interceptor.ts dos exemplos, com uma novidade:
// o tratamento centralizado da resposta 401.
//
// Um 401 pode chegar 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, nós o tratamos
// AQUI, uma só vez: esquecemos o usuário, preparamos a mensagem
// "sessão expirada" e voltamos à página de login.
//
// Algumas requisições tratam seu 401 por conta própria (o login, GET
// /api/auth/me...): elas avisam isso com um TOKEN DE CONTEXTO
// (HttpContextToken), uma informação anexada à requisição, que
// o interceptor lê (veja api/rdvmedecins.api.ts).
// =========================================================================

import { inject } from '@angular/core';
import { HttpContextToken, HttpInterceptorFn } from '@angular/common/http';
import { Router } from '@angular/router';
import { catchError, throwError } from 'rxjs';
import { toApiError } from './api-error';
import { SessionService } from '../services/session.service';
import { MessagesService } from '../services/messages.service';

// true: a requisição trata por conta própria um possível 401 (false por padrão)
export const IGNORE_401 = new HttpContextToken<boolean>(() => false);

export const apiInterceptor: HttpInterceptorFn = (req, next) => {
  // inject: os serviços que serão necessários (no contexto de injeção
  // do interceptor, ANTES de a requisição ser enviada)
  const session = inject(SessionService);
  const messages = inject(MessagesService);
  const router = inject(Router);

  return next(req).pipe(
    catchError((e: unknown) => {
      const error = toApiError(e);
      if (error.statusCode === 401 && !req.context.get(IGNORE_401)) {
        session.forget();
        messages.flash('error', 'ERRORS.SESSION_EXPIRED');
        router.navigate(['/login']);
      }
      return throwError(() => error);
    }),
  );
};

O interceptor do Exemplo 24, com um novo recurso: o tratamento centralizado da resposta 401. Um 401 pode ocorrer a qualquer momento: o token expirou, a conta foi excluída... Em vez de tratar esse caso em cada página, nós o tratamos aqui, uma única vez.

  • Linha 28: um token de contexto ([HttpContextToken]) — informação anexada a uma requisição que o interceptor pode ler. Por padrão, ele vale [false];
  • Linhas 33–35: o interceptor injeta os serviços de que precisará. [inject] deve ser chamado no início da função: mais tarde, em [catchError], o contexto de injeção não existe mais;
  • linha 39: qualquer erro se torna um [ApiError];
  • linhas 40–44: uma resposta 401 para uma requisição que não a trata por conta própria: o usuário é esquecido, a mensagem "sessão expirada" é preparada (ela será exibida na próxima página) e o usuário é redirecionado para a página de login;
  • linha 45: o erro é repassado, em todos os casos, ao código que fez a requisição.

10.4.3.4. src/app/api/rdvmedecins.api.ts

// =========================================================================
// api/rdvmedecins.api.ts - um método por rota da API
// -------------------------------------------------------------------------
// A "camada de acesso a dados" do cliente: os componentes chamam estes
// métodos tipados, sem saber nada sobre as URLs, o HttpClient ou o JSON. Se
// a API mudar, apenas este arquivo muda.
// Cada método retorna uma PROMISE (firstValueFrom): os componentes
// encadeiam as requisições com async / await. Em caso de falha, a promise
// é rejeitada com um ApiError (veja api.interceptor.ts).
// =========================================================================

import { inject, Injectable } from '@angular/core';
import { HttpClient, HttpContext, HttpParams } from '@angular/common/http';
import { firstValueFrom } from 'rxjs';
import { IGNORE_401 } from './api.interceptor';
import {
  Schedule,
  Captcha,
  PersonData,
  Registration,
  MyAccountUpdate,
  MyAccount,
  MyArea,
  Person,
  User,
} from './types';

// /api/doctors ou /api/clients: ambos são tratados da mesma forma
export type PersonType = 'doctors' | 'clients';

type Empty = Record<string, never>;
type Method = 'GET' | 'POST' | 'PUT' | 'DELETE';

@Injectable({ providedIn: 'root' })
export class RdvMedecinsApi {
  private readonly http = inject(HttpClient);

  // a própria requisição; isPublic: true para as rotas que tratam
  // o 401 por conta própria (rotas públicas, GET /api/auth/me)
  private request<T>(method: Method, url: string, body?: unknown, isPublic = false, params?: HttpParams): Promise<T> {
    return firstValueFrom(
      this.http.request<T>(method, `/api${url}`, {
        body,
        params,
        context: new HttpContext().set(IGNORE_401, isPublic),
      }),
    );
  }

  // ──────────────────────────────────────────────── login (rotas públicas)
  captcha(): Promise<Captcha> {
    return this.request<Captcha>('GET', '/captcha', undefined, true);
  }
  me(): Promise<User> {
    return this.request<User>('GET', '/auth/me', undefined, true);
  }
  logIn(login: string, password: string, captchaId: string, captcha: string): Promise<User> {
    return this.request<User>('POST', '/auth/login', { login, password, captchaId, captcha }, true);
  }
  logOut(): Promise<Empty> {
    return this.request<Empty>('POST', '/auth/logout', {}, true);
  }

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

  // ──────────────────────────────────────────────── agenda e consultas
  // doctorId null: para um médico logado, a SUA agenda
  schedule(doctorId: number | null, day: string): Promise<Schedule> {
    let params = new HttpParams().set('day', day);
    if (doctorId !== null) {
      params = params.set('doctorId', doctorId);
    }
    return this.request<Schedule>('GET', '/schedule', undefined, false, params);
  }
  book(day: string, slotId: number, clientId: number | null): Promise<{ id: number }> {
    return this.request<{ id: number }>('POST', '/appointments', { day, slotId, clientId: clientId ?? undefined });
  }
  cancelAppointment(appointmentId: number): Promise<Empty> {
    return this.request<Empty>('DELETE', `/appointments/${appointmentId}`);
  }

  // ──────────────────────────────────────────────── médicos e clientes
  list(type: PersonType): Promise<Person[]> {
    return this.request<Person[]>('GET', `/${type}`);
  }
  read(type: PersonType, id: number): Promise<Person> {
    return this.request<Person>('GET', `/${type}/${id}`);
  }
  add(type: PersonType, data: PersonData): Promise<Person> {
    return this.request<Person>('POST', `/${type}`, data);
  }
  edit(type: PersonType, id: number, data: PersonData): Promise<Person> {
    return this.request<Person>('PUT', `/${type}/${id}`, data);
  }
  remove(type: PersonType, id: number): Promise<Empty> {
    return this.request<Empty>('DELETE', `/${type}/${id}`);
  }

  // ──────────────────────────────────────────────── a área do paciente
  myArea(): Promise<MyArea> {
    return this.request<MyArea>('GET', '/my-area');
  }
  myAccount(): Promise<MyAccount> {
    return this.request<MyAccount>('GET', '/my-account');
  }
  editMyAccount(data: MyAccountUpdate): Promise<User> {
    return this.request<User>('PUT', '/my-account', data);
  }
  deleteMyAccount(currentPassword: string): Promise<Empty> {
    return this.request<Empty>('DELETE', '/my-account', { currentPassword });
  }
}

A camada de acesso à API: um método por rota.

  • Linhas 40–48: um único método trata todas as requisições. [http.request] aceita o método HTTP como parâmetro; [firstValueFrom] o transforma em uma promise;
  • linha 45: a requisição carrega o token de contexto [IGNORE_401]: true para as rotas que tratam o 401 por conta própria. Uma senha incorreta retorna um 401: isso não é uma sessão expirada! Da mesma forma, [GET /api/auth/me] retorna um 401 quando ninguém está logado, o que é normal;
  • linhas 77–83: [HttpParams] gera os parâmetros da URL (?day=...&doctorId=...). Um objeto [HttpParams] não muda: [set] retorna um novo objeto;
  • linha 85: [clientId ?? undefined]: se um [clientId] estiver ausente, ele simplesmente não é enviado;
  • Linhas 92–106: médicos e clientes são tratados da mesma forma: o tipo (['doctors'] ou ['clients']) faz parte do endereço;
  • linha 119: um DELETE com um corpo contendo a senha atual, necessária para excluir a conta.

10.4.4. Idiomas

10.4.4.1. src/app/i18n/i18n.ts

// =========================================================================
// i18n/i18n.ts - francês e inglês (ngx-translate, veja o exemplo 21)
// -------------------------------------------------------------------------
// Os dicionários fr.json e 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 só retorna CHAVES
// ('ERRORS.LOGIN_TAKEN'): elas são as mesmas dos dicionários.
//
// O idioma escolhido é armazenado no localStorage (uma preferência, não um
// dado sensível); na falta dele, usa-se o idioma do navegador.
// =========================================================================

import { Provider } from '@angular/core';
import { provideTranslateLoader, provideTranslateService, TranslateLoader, TranslationObject } from '@ngx-translate/core';
import { Observable, of } from 'rxjs';
import fr from './fr.json';
import en from './en.json';

export type Language = 'fr' | 'en';
export const LANGUAGES: Language[] = ['fr', 'en'];
export const STORAGE_KEY = 'rdvmedecins.language';

// os dicionários fazem parte do código da aplicação: nenhuma requisição
class DictionariesLoader implements TranslateLoader {
  getTranslation(language: string): Observable<TranslationObject> {
    return of(language === 'en' ? en : fr);
  }
}

export 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 importância
  }
  return navigator.language.toLowerCase().startsWith('fr') ? 'fr' : 'en';
}

export function provideI18n(): Provider[] {
  return provideTranslateService({
    loader: provideTranslateLoader(DictionariesLoader),
    fallbackLang: 'en',
    lang: initialLanguage(),
  });
}

A configuração do [ngx-translate] do Exemplo 21:

  • Linhas 30–40: o idioma de origem é o último selecionado pelo usuário; caso contrário, francês se o idioma do navegador for o francês e inglês em qualquer outro caso. O acesso ao [localStorage] pode falhar (em certos modos de navegação privada), por isso o ignoramos nesse caso.

10.4.4.2. src/app/i18n/language.service.ts

// =========================================================================
// i18n/language.service.ts - o idioma atual e a maneira de trocá-lo
// =========================================================================

import { inject, Injectable } from '@angular/core';
import { TranslateService } from '@ngx-translate/core';
import { STORAGE_KEY, Language } from './i18n';

@Injectable({ providedIn: 'root' })
export class LanguageService {
  private readonly translate = inject(TranslateService);
  // um signal: 'fr' ou 'en'
  readonly language = this.translate.currentLang;

  constructor() {
    document.documentElement.lang = this.translate.getCurrentLang() ?? 'en';
  }

  // trocar o idioma: a aplicação inteira é traduzida de novo de uma vez
  change(language: Language): void {
    this.translate.use(language);
    document.documentElement.lang = language;
    try {
      localStorage.setItem(STORAGE_KEY, language);
    } catch {
      // sem importância
    }
  }
}
  • linha 13: o idioma atual, um signal;
  • linhas 20–28: mudança de idioma: a página é retraduzida (linha 21), o atributo [lang] da página é atualizado (linha 22) e a seleção é salva (linha 24).

10.4.4.3. src/app/i18n/title.strategy.ts

// =========================================================================
// i18n/title.strategy.ts - o título da aba, traduzido
// -------------------------------------------------------------------------
// Cada rota declara um título (title: 'SCHEDULE.PAGE_TITLE', veja
// app.routes.ts). Por padrão, o Angular o escreve TAL QUAL na aba. Uma
// TitleStrategy substitui esse comportamento: updateTitle() é chamado após
// cada navegação; buildTitle() fornece o título da rota exibida
// (aqui, uma chave), que nós traduzimos. E quando o idioma muda, o
// último título é traduzido de novo.
// A classe é declarada em app.config.ts:
//     { provide: TitleStrategy, useClass: TranslatedTitle }
// =========================================================================

import { inject, Injectable } from '@angular/core';
import { Title } from '@angular/platform-browser';
import { RouterStateSnapshot, TitleStrategy } from '@angular/router';
import { TranslateService } from '@ngx-translate/core';

@Injectable({ providedIn: 'root' })
export class TranslatedTitle extends TitleStrategy {
  private readonly title = inject(Title);
  private readonly translate = inject(TranslateService);
  private key: string | undefined;

  constructor() {
    super();
    this.translate.onLangChange.subscribe(() => this.apply());
  }

  override updateTitle(snapshot: RouterStateSnapshot): void {
    this.key = this.buildTitle(snapshot);
    this.apply();
  }

  private apply(): void {
    const application = this.translate.instant('APP.TITLE');
    this.title.setTitle(this.key ? `${this.translate.instant(this.key)} - ${application}` : application);
  }
}

Cada rota declara um título, que neste caso é uma chave de tradução ('SCHEDULE.PAGE_TITLE'). Por padrão, o [Angular] o escreveria como está na aba. Esta classe substitui o serviço [TitleStrategy] do roteador (app.config.ts, linha 23):

  • linha 20: ela herda a classe [TitleStrategy] do [Angular];
  • linhas 30–33: [updateTitle] é chamado pelo roteador após cada navegação; [buildTitle], que é herdado, fornece o título declarado pela rota exibida;
  • linhas 35–38: o título traduzido, seguido do nome da aplicação: "Schedule - RdvMedecins";
  • linha 27: quando o idioma muda, o último título é retraduzido.

10.4.4.4. Os dicionários

Os dicionários [fr.json] e [en.json] são os da aplicação HTML do curso de [NestJS], complementados com algumas chaves específicas do cliente ([ERRORS.SERVER_UNREACHABLE]...). Apenas a sintaxe dos parâmetros muda: [{{min}}] para o [ngx-translate]. O servidor JSON retorna as mesmas chaves.

{
  "APP": {
    "TITLE": "RdvMedecins",
    "LOGOUT": "Se déconnecter",
    "MENU_SCHEDULE": "Agenda",
    "MENU_DOCTORS": "Médecins",
    "MENU_PATIENTS": "Clients",
    "MENU_MY_AREA": "Mon espace",
    "LOADING": "Chargement...",
    "LANGUAGE": "Langue"
  },
  "LOGIN": {
    "TITLE": "Connexion",
    "LOGIN_LABEL": "Login",
    "PASSWORD_LABEL": "Mot de passe",
    "SUBMIT": "Se connecter",
    "ERROR": "Login ou mot de passe incorrect.",
    "DEMO_ACCOUNTS": "Comptes de démonstration (mot de passe = login) :",
    "DEMO_ADMIN": "rôle ADMIN : rendez-vous + gestion des médecins et des clients",
    "DEMO_DOCTOR": "rôle DOCTOR : prise et annulation de rendez-vous",
    "DEMO_USER": "rôle USER (patients) : réservation pour eux-mêmes, gestion de leur compte",
    "CREATE_ACCOUNT": "Créer un compte client",
    "CREATE_ACCOUNT_HELP": "Pour créer un compte, recopiez d'abord les caractères de l'image."
  },
  "DOCTOR_DAY_PICKER": {
    "DOCTOR_LABEL": "Médecin",
    "CHOOSE_DOCTOR": "-- choisir un médecin --",
    "DAY_LABEL": "Jour",
    "VIEW_SCHEDULE": "Voir l'agenda"
  },
  "SCHEDULE": {
    "PAGE_TITLE": "Agenda",
    "TITLE_PREFIX": "Agenda du",
    "COLUMN_SLOT": "Créneau",
    "COLUMN_STATUS": "Statut",
    "FREE": "Libre",
    "BOOK": "Réserver",
    "CANCEL_APPOINTMENT": "Annuler",
    "CANCEL_CONFIRM": "Annuler ce rendez-vous ?",
    "EMPTY_STATE": "Choisissez un médecin et un jour, puis cliquez sur « Voir l'agenda ».",
    "NO_SLOTS": "Ce médecin n'a aucun créneau horaire.",
    "BOOKED": "Rendez-vous enregistré.",
    "CANCELLED": "Rendez-vous annulé.",
    "BOOKED_BY_OTHER": "Réservé",
    "ALREADY_BOOKED_INFO": "Vous avez déjà un rendez-vous à venir : annulez-le pour en prendre un autre."
  },
  "BOOKING_DIALOG": {
    "TITLE": "Réserver ce créneau",
    "CLOSE_ARIA": "Fermer",
    "SLOT": "Créneau de {{time}}",
    "PATIENT_LABEL": "Patient",
    "CHOOSE_PATIENT": "-- choisir un patient --",
    "CANCEL": "Annuler",
    "CONFIRM": "Confirmer"
  },
  "PERSONS": {
    "COLUMN_TITLE": "Titre",
    "COLUMN_FIRSTNAME": "Prénom",
    "COLUMN_LASTNAME": "Nom",
    "COLUMN_LOGIN": "Login",
    "EDIT": "Modifier",
    "DELETE": "Supprimer",
    "SAVE": "Enregistrer",
    "BACK": "Retour à la liste",
    "TITLE_LABEL": "Titre",
    "FIRSTNAME_LABEL": "Prénom",
    "LASTNAME_LABEL": "Nom",
    "LOGIN_LABEL": "Login",
    "PASSWORD_LABEL": "Mot de passe",
    "LOGIN_HELP_CREATE": "Facultatif : par défaut, le nom en minuscules.",
    "LOGIN_HELP_EDIT": "Laisser vide pour ne pas le changer.",
    "PASSWORD_HELP_CREATE": "Facultatif : par défaut, identique au login.",
    "PASSWORD_HELP_EDIT": "Laisser vide pour ne pas le changer.",
    "ACCOUNT_SECTION": "Compte utilisateur"
  },
  "DOCTORS": {
    "TITLE": "Médecins",
    "ADD": "Ajouter un médecin",
    "EDIT": "Modifier un médecin",
    "EMPTY": "Aucun médecin.",
    "DELETE_CONFIRM": "Supprimer ce médecin, ses créneaux horaires et son compte utilisateur ?",
    "ADDED": "Le médecin {{name}} a été ajouté (login : {{login}}).",
    "UPDATED": "Le médecin {{name}} a été modifié.",
    "DELETED": "Le médecin {{name}} a été supprimé."
  },
  "CLIENTS": {
    "TITLE": "Clients",
    "ADD": "Ajouter un client",
    "EDIT": "Modifier un client",
    "EMPTY": "Aucun client.",
    "DELETE_CONFIRM": "Supprimer ce client, son compte utilisateur et tous ses rendez-vous ?",
    "ADDED": "Le client {{name}} a été ajouté (login : {{login}}).",
    "UPDATED": "Le client {{name}} a été modifié.",
    "DELETED": "Le client {{name}} a été supprimé."
  },
  "ERROR_PAGE": {
    "TITLE": "Erreur",
    "BACK": "Retour à l'accueil"
  },
  "ERRORS": {
    "LOGIN_TAKEN": "Ce login est déjà utilisé par un autre compte.",
    "DOCTOR_ALREADY_EXISTS": "Un médecin portant ce prénom et ce nom existe déjà.",
    "PATIENT_ALREADY_EXISTS": "Un client portant ce prénom et ce nom existe déjà.",
    "DOCTOR_HAS_APPOINTMENTS": "Ce médecin a des rendez-vous : annulez-les avant de le supprimer.",
    "SLOT_ALREADY_BOOKED": "Ce créneau vient d'être réservé par quelqu'un d'autre.",
    "CONCURRENT_UPDATE": "Cette fiche a été modifiée entre-temps par un autre utilisateur. Revenez à la liste et rouvrez-la avant de recommencer.",
    "DOCTOR_NOT_FOUND": "Ce médecin n'existe pas (ou plus).",
    "PATIENT_NOT_FOUND": "Ce client n'existe pas (ou plus).",
    "SLOT_NOT_FOUND": "Ce créneau n'existe pas (ou plus).",
    "APPOINTMENT_NOT_FOUND": "Ce rendez-vous n'existe pas (ou plus).",
    "INVALID_DATE": "La date demandée n'est pas valide.",
    "CHOOSE_PATIENT": "Choisissez un patient.",
    "INVALID_FORM": "Le formulaire contient des erreurs.",
    "INVALID_TITLE": "Choisissez un titre dans la liste.",
    "FIRSTNAME_REQUIRED": "Le prénom est obligatoire.",
    "FIRSTNAME_TOO_LONG": "Le prénom ne doit pas dépasser 20 caractères.",
    "LASTNAME_REQUIRED": "Le nom est obligatoire.",
    "LASTNAME_TOO_LONG": "Le nom ne doit pas dépasser 20 caractères.",
    "INVALID_LOGIN": "30 caractères au plus : lettres minuscules non accentuées, chiffres, point, tiret, souligné.",
    "PASSWORD_TOO_LONG": "Le mot de passe ne doit pas dépasser 72 caractères.",
    "SESSION_EXPIRED": "Votre session a expiré : reconnectez-vous.",
    "BAD_REQUEST": "La requête est invalide.",
    "FORBIDDEN": "Votre rôle ne vous permet pas d'accéder à cette page.",
    "NOT_FOUND": "Cette page n'existe pas.",
    "SERVER_ERROR": "Une erreur inattendue s'est produite. Réessayez plus tard.",
    "TOO_MANY_ATTEMPTS": "Trop de tentatives infructueuses. Réessayez dans {{minutes}} minute(s).",
    "WRONG_CAPTCHA": "Les caractères recopiés ne correspondent pas à l'image. Une nouvelle image vous est proposée.",
    "TOO_MANY_ACCOUNTS": "Trop de comptes ont été créés depuis votre connexion. Réessayez dans {{minutes}} minute(s).",
    "LOGIN_REQUIRED": "Le login est obligatoire.",
    "PASSWORD_REQUIRED": "Le mot de passe est obligatoire.",
    "PASSWORD_TOO_SHORT": "Le mot de passe doit comporter au moins {{min}} caractères.",
    "CONFIRMATION_REQUIRED": "Confirmez le mot de passe.",
    "PASSWORDS_DIFFER": "La confirmation ne correspond pas au mot de passe.",
    "CURRENT_PASSWORD_REQUIRED": "Saisissez votre mot de passe actuel.",
    "WRONG_CURRENT_PASSWORD": "Mot de passe actuel incorrect.",
    "PAST_DATE": "On ne peut pas prendre de rendez-vous à une date passée.",
    "PATIENT_HAS_UPCOMING_APPOINTMENT": "Ce patient a déjà un rendez-vous à venir : il faut l'annuler avant d'en prendre un autre.",
    "CAPTCHA_BEFORE_ACCOUNT": "Pour créer un compte, recopiez d'abord correctement les caractères de l'image, puis cliquez sur « Créer un compte client ».",
    "AUTH_REQUIRED": "Connectez-vous pour accéder à cette page.",
    "JSON_REQUIRED": "Requête refusée : le serveur attend du JSON.",
    "SERVER_UNREACHABLE": "Le serveur ne répond pas. Réessayez plus tard."
  },
  "CAPTCHA": {
    "LABEL": "Recopiez les caractères de l'image",
    "IMAGE_ALT": "Image de vérification anti-robots",
    "NEW_IMAGE": "Autre image",
    "HELP": "Majuscules ou minuscules, peu importe."
  },
  "REGISTRATION": {
    "TITLE": "Créer un compte client",
    "INTRO": "Ce compte vous permettra de prendre vous-même vos rendez-vous.",
    "LOGIN_HELP": "Lettres minuscules non accentuées, chiffres, point, tiret, souligné.",
    "PASSWORD_HELP": "Au moins {{min}} caractères.",
    "SUBMIT": "Créer mon compte",
    "BACK_TO_LOGIN": "Retour à la connexion",
    "DONE": "Votre compte a été créé. Vous pouvez vous connecter avec le login {{login}}."
  },
  "ACCOUNT": {
    "CONFIRMATION_LABEL": "Confirmation du mot de passe"
  },
  "AREA": {
    "TITLE": "Mon espace",
    "HELLO": "Bonjour {{name}}",
    "MANAGE_ACCOUNT": "Gérer mon compte",
    "MANAGE_ACCOUNT_HELP": "Modifier mes informations, mon mot de passe, ou supprimer mon compte.",
    "VIEW_SCHEDULE": "Voir un agenda",
    "VIEW_SCHEDULE_HELP": "Consulter l'agenda d'un médecin et réserver un créneau.",
    "MY_APPOINTMENT": "Mon rendez-vous",
    "SEE_IN_SCHEDULE": "voir dans l'agenda",
    "CANCEL_APPOINTMENT": "Annuler ce rendez-vous",
    "NO_APPOINTMENT": "Vous n'avez aucun rendez-vous à venir."
  },
  "MY_ACCOUNT": {
    "TITLE": "Gérer mon compte",
    "NEW_PASSWORD_LABEL": "Nouveau mot de passe",
    "CURRENT_PASSWORD_LABEL": "Mot de passe actuel",
    "CURRENT_PASSWORD_HELP": "Obligatoire pour enregistrer une modification.",
    "BACK": "Retour à mon espace",
    "DELETE_TITLE": "Supprimer mon compte",
    "DELETE_HELP": "Votre compte sera définitivement supprimé, ainsi que tous vos rendez-vous.",
    "DELETE_CONFIRM": "Supprimer définitivement votre compte ? Votre rendez-vous éventuel sera annulé.",
    "DELETE_SUBMIT": "Supprimer mon compte",
    "UPDATED": "Votre compte a été modifié.",
    "DELETED": "Votre compte a été supprimé."
  },
  "CONFIRMATION": {
    "TITLE": "Confirmation",
    "NO": "Non, revenir",
    "YES": "Oui, confirmer"
  }
}
{
  "APP": {
    "TITLE": "RdvMedecins",
    "LOGOUT": "Log out",
    "MENU_SCHEDULE": "Schedule",
    "MENU_DOCTORS": "Doctors",
    "MENU_PATIENTS": "Patients",
    "MENU_MY_AREA": "My area",
    "LOADING": "Loading...",
    "LANGUAGE": "Language"
  },
  "LOGIN": {
    "TITLE": "Login",
    "LOGIN_LABEL": "Login",
    "PASSWORD_LABEL": "Password",
    "SUBMIT": "Log in",
    "ERROR": "Incorrect login or password.",
    "DEMO_ACCOUNTS": "Demo accounts (password = login):",
    "DEMO_ADMIN": "ADMIN role: appointments + doctor and patient management",
    "DEMO_DOCTOR": "DOCTOR role: booking and cancelling appointments",
    "DEMO_USER": "USER role (patients): booking for themselves, managing their account",
    "CREATE_ACCOUNT": "Create a patient account",
    "CREATE_ACCOUNT_HELP": "To create an account, first type the characters shown in the image."
  },
  "DOCTOR_DAY_PICKER": {
    "DOCTOR_LABEL": "Doctor",
    "CHOOSE_DOCTOR": "-- choose a doctor --",
    "DAY_LABEL": "Day",
    "VIEW_SCHEDULE": "View schedule"
  },
  "SCHEDULE": {
    "PAGE_TITLE": "Schedule",
    "TITLE_PREFIX": "Schedule for",
    "COLUMN_SLOT": "Slot",
    "COLUMN_STATUS": "Status",
    "FREE": "Free",
    "BOOK": "Book",
    "CANCEL_APPOINTMENT": "Cancel",
    "CANCEL_CONFIRM": "Cancel this appointment?",
    "EMPTY_STATE": "Choose a doctor and a day, then click \"View schedule\".",
    "NO_SLOTS": "This doctor has no time slots.",
    "BOOKED": "Appointment booked.",
    "CANCELLED": "Appointment cancelled.",
    "BOOKED_BY_OTHER": "Booked",
    "ALREADY_BOOKED_INFO": "You already have an upcoming appointment: cancel it to book another one."
  },
  "BOOKING_DIALOG": {
    "TITLE": "Book this slot",
    "CLOSE_ARIA": "Close",
    "SLOT": "Slot {{time}}",
    "PATIENT_LABEL": "Patient",
    "CHOOSE_PATIENT": "-- choose a patient --",
    "CANCEL": "Cancel",
    "CONFIRM": "Confirm"
  },
  "PERSONS": {
    "COLUMN_TITLE": "Title",
    "COLUMN_FIRSTNAME": "First name",
    "COLUMN_LASTNAME": "Last name",
    "COLUMN_LOGIN": "Login",
    "EDIT": "Edit",
    "DELETE": "Delete",
    "SAVE": "Save",
    "BACK": "Back to the list",
    "TITLE_LABEL": "Title",
    "FIRSTNAME_LABEL": "First name",
    "LASTNAME_LABEL": "Last name",
    "LOGIN_LABEL": "Login",
    "PASSWORD_LABEL": "Password",
    "LOGIN_HELP_CREATE": "Optional: defaults to the last name in lower case.",
    "LOGIN_HELP_EDIT": "Leave empty to keep it unchanged.",
    "PASSWORD_HELP_CREATE": "Optional: defaults to the login.",
    "PASSWORD_HELP_EDIT": "Leave empty to keep it unchanged.",
    "ACCOUNT_SECTION": "User account"
  },
  "DOCTORS": {
    "TITLE": "Doctors",
    "ADD": "Add a doctor",
    "EDIT": "Edit a doctor",
    "EMPTY": "No doctors.",
    "DELETE_CONFIRM": "Delete this doctor, their time slots and their user account?",
    "ADDED": "Doctor {{name}} has been added (login: {{login}}).",
    "UPDATED": "Doctor {{name}} has been updated.",
    "DELETED": "Doctor {{name}} has been deleted."
  },
  "CLIENTS": {
    "TITLE": "Patients",
    "ADD": "Add a patient",
    "EDIT": "Edit a patient",
    "EMPTY": "No patients.",
    "DELETE_CONFIRM": "Delete this patient, their user account and all their appointments?",
    "ADDED": "Patient {{name}} has been added (login: {{login}}).",
    "UPDATED": "Patient {{name}} has been updated.",
    "DELETED": "Patient {{name}} has been deleted."
  },
  "ERROR_PAGE": {
    "TITLE": "Error",
    "BACK": "Back to the home page"
  },
  "ERRORS": {
    "LOGIN_TAKEN": "This login is already used by another account.",
    "DOCTOR_ALREADY_EXISTS": "A doctor with this first and last name already exists.",
    "PATIENT_ALREADY_EXISTS": "A patient with this first and last name already exists.",
    "DOCTOR_HAS_APPOINTMENTS": "This doctor has appointments: cancel them before deleting the doctor.",
    "SLOT_ALREADY_BOOKED": "This slot has just been booked by someone else.",
    "CONCURRENT_UPDATE": "This record was changed by another user in the meantime. Go back to the list and reopen it before trying again.",
    "DOCTOR_NOT_FOUND": "This doctor does not exist (any more).",
    "PATIENT_NOT_FOUND": "This patient does not exist (any more).",
    "SLOT_NOT_FOUND": "This slot does not exist (any more).",
    "APPOINTMENT_NOT_FOUND": "This appointment does not exist (any more).",
    "INVALID_DATE": "The requested date is not valid.",
    "CHOOSE_PATIENT": "Choose a patient.",
    "INVALID_FORM": "The form contains errors.",
    "INVALID_TITLE": "Choose a title from the list.",
    "FIRSTNAME_REQUIRED": "The first name is required.",
    "FIRSTNAME_TOO_LONG": "The first name must not exceed 20 characters.",
    "LASTNAME_REQUIRED": "The last name is required.",
    "LASTNAME_TOO_LONG": "The last name must not exceed 20 characters.",
    "INVALID_LOGIN": "At most 30 characters: unaccented lower-case letters, digits, dot, hyphen, underscore.",
    "PASSWORD_TOO_LONG": "The password must not exceed 72 characters.",
    "SESSION_EXPIRED": "Your session has expired: please log in again.",
    "BAD_REQUEST": "The request is invalid.",
    "FORBIDDEN": "Your role does not allow you to access this page.",
    "NOT_FOUND": "This page does not exist.",
    "SERVER_ERROR": "An unexpected error occurred. Please try again later.",
    "TOO_MANY_ATTEMPTS": "Too many failed attempts. Try again in {{minutes}} minute(s).",
    "WRONG_CAPTCHA": "The characters you typed do not match the image. A new image is shown.",
    "TOO_MANY_ACCOUNTS": "Too many accounts have been created from your connection. Try again in {{minutes}} minute(s).",
    "LOGIN_REQUIRED": "The login is required.",
    "PASSWORD_REQUIRED": "The password is required.",
    "PASSWORD_TOO_SHORT": "The password must be at least {{min}} characters long.",
    "CONFIRMATION_REQUIRED": "Please confirm the password.",
    "PASSWORDS_DIFFER": "The confirmation does not match the password.",
    "CURRENT_PASSWORD_REQUIRED": "Enter your current password.",
    "WRONG_CURRENT_PASSWORD": "Incorrect current password.",
    "PAST_DATE": "Appointments cannot be booked for a past date.",
    "PATIENT_HAS_UPCOMING_APPOINTMENT": "This patient already has an upcoming appointment: it must be cancelled before booking another one.",
    "CAPTCHA_BEFORE_ACCOUNT": "To create an account, first type the characters shown in the image correctly, then click \"Create a patient account\".",
    "AUTH_REQUIRED": "Please log in to access this page.",
    "JSON_REQUIRED": "Request refused: the server expects JSON.",
    "SERVER_UNREACHABLE": "The server does not respond. Please try again later."
  },
  "CAPTCHA": {
    "LABEL": "Type the characters shown in the image",
    "IMAGE_ALT": "Anti-robot verification image",
    "NEW_IMAGE": "Another image",
    "HELP": "Upper or lower case, it does not matter."
  },
  "REGISTRATION": {
    "TITLE": "Create a patient account",
    "INTRO": "With this account you can book your own appointments.",
    "LOGIN_HELP": "Unaccented lower-case letters, digits, dot, hyphen, underscore.",
    "PASSWORD_HELP": "At least {{min}} characters.",
    "SUBMIT": "Create my account",
    "BACK_TO_LOGIN": "Back to login",
    "DONE": "Your account has been created. You can now log in with the login {{login}}."
  },
  "ACCOUNT": {
    "CONFIRMATION_LABEL": "Confirm password"
  },
  "AREA": {
    "TITLE": "My area",
    "HELLO": "Hello {{name}}",
    "MANAGE_ACCOUNT": "Manage my account",
    "MANAGE_ACCOUNT_HELP": "Change my details or password, or delete my account.",
    "VIEW_SCHEDULE": "View a schedule",
    "VIEW_SCHEDULE_HELP": "See a doctor's schedule and book a slot.",
    "MY_APPOINTMENT": "My appointment",
    "SEE_IN_SCHEDULE": "see in the schedule",
    "CANCEL_APPOINTMENT": "Cancel this appointment",
    "NO_APPOINTMENT": "You have no upcoming appointment."
  },
  "MY_ACCOUNT": {
    "TITLE": "Manage my account",
    "NEW_PASSWORD_LABEL": "New password",
    "CURRENT_PASSWORD_LABEL": "Current password",
    "CURRENT_PASSWORD_HELP": "Required to save any change.",
    "BACK": "Back to my area",
    "DELETE_TITLE": "Delete my account",
    "DELETE_HELP": "Your account will be permanently deleted, together with all your appointments.",
    "DELETE_CONFIRM": "Permanently delete your account? Any appointment you have will be cancelled.",
    "DELETE_SUBMIT": "Delete my account",
    "UPDATED": "Your account has been updated.",
    "DELETED": "Your account has been deleted."
  },
  "CONFIRMATION": {
    "TITLE": "Confirmation",
    "NO": "No, go back",
    "YES": "Yes, confirm"
  }
}

10.4.5. Os serviços

10.4.5.1. src/app/services/session.service.ts

// =========================================================================
// services/session.service.ts - QUEM está logado?
// -------------------------------------------------------------------------
// O usuário logado (ou null) e o que se deduz dele (é o ADMIN?
// um paciente?), em um serviço raiz baseado em signals (veja o exemplo 20).
//
// O token JWT em si NÃO está aqui: ele está em um cookie httpOnly que
// somente o navegador manipula. O serviço guarda apenas a DESCRIÇÃO do
// usuário, retornada pelo servidor ({ login, name, role }).
//
// Na partida (e depois de um F5), o serviço está vazio: check() pergunta
// ao servidor, uma única vez, quem está logado (GET /api/auth/me).
// =========================================================================

import { computed, inject, Injectable, signal } from '@angular/core';
import { RdvMedecinsApi } from '../api/rdvmedecins.api';
import { Role, User } from '../api/types';

@Injectable({ providedIn: 'root' })
export class SessionService {
  private readonly api = inject(RdvMedecinsApi);
  private readonly _user = signal<User | null>(null);
  // a pergunta "quem está logado?" já foi feita ao servidor?
  private checking: Promise<void> | null = null;

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

  // a página inicial de cada papel, logo após o login
  readonly homePage = computed(() => (this.isPatient() ? '/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)
  check(): Promise<void> {
    this.checking ??= this.api
      .me()
      .then((u) => this._user.set(u))
      .catch(() => this._user.set(null)); // 401: ninguém; ou servidor inacessível
    return this.checking;
  }

  async logIn(login: string, password: string, captchaId: string, captcha: string): Promise<void> {
    this._user.set(await this.api.logIn(login, password, captchaId, captcha));
  }

  // o usuário mudou de nome ou de login (PUT /api/my-account)
  update(u: User): void {
    this._user.set(u);
  }

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

  // sem perguntar nada ao servidor: sessão expirada, conta excluída
  forget(): void {
    this._user.set(null);
  }
}

O usuário logado, em um serviço de signals (exemplo 20):

  • linha 22: o estado: o usuário ou [null]. O token em si não está aqui: ele está em um cookie que somente o navegador manipula;
  • linhas 26–32: o que os componentes leem: o usuário e o que se deduz dele (o usuário está logado? É ADMIN? É um paciente?);
  • linha 35: a página inicial de cada papel;
  • linhas 39–45: na inicialização (e após um F5), o serviço não sabe quem está logado: ele pergunta ao servidor. [check] é chamado pelo guard do roteador antes de CADA navegação, mas só consulta o servidor na primeira vez: a promise é mantida (linha 40, [??=]: "se ela ainda não existe") e é retornada a cada chamada seguinte. Se duas navegações ocorrem em sequência próxima, ambas aguardam a mesma resposta;
  • linha 43: 401 (ninguém) ou servidor inacessível: nenhum usuário;
  • linhas 56–62: logout; [finally]: o usuário é esquecido mesmo que o servidor não responda;
  • linhas 65–67: esquecer o usuário sem enviar uma requisição ao servidor: é o que o interceptor faz em um 401.

10.4.5.2. src/app/services/messages.service.ts

// =========================================================================
// services/messages.service.ts - as mensagens exibidas ao usuário
// -------------------------------------------------------------------------
// Mesma apresentação da aplicação HTML:
//   - um SUCESSO é exibido no TOPO da página (banner verde);
//   - um ERRO na PARTE INFERIOR, sobre um fundo rosa claro (painel "fixo").
// Uma mensagem é uma CHAVE de tradução (+ seus parâmetros): ela é portanto traduzida
// de novo por conta própria se o usuário trocar o idioma.
//
// As mensagens "flash": uma ação que termina com uma mudança de
// página (marcar consulta, adicionar um médico...) deixa sua mensagem com flash();
// ela será exibida na PRÓXIMA página e depois desaparecerá na
// navegação seguinte. O serviço sabe disso porque escuta os eventos do roteador
// (fim de cada navegação). Era, no lado do servidor, o papel do
// cookie de curta duração "rdvmedecins_flash".
// =========================================================================

import { Injectable, inject, signal } from '@angular/core';
import { NavigationEnd, Router } from '@angular/router';
import { ApiError } from '../api/api-error';

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

@Injectable({ providedIn: 'root' })
export class MessagesService {
  readonly success = signal<Message | null>(null);
  readonly error = signal<Message | null>(null);
  // as mensagens a exibir na próxima página
  private pending: { success: Message | null; error: Message | null } | null = null;

  constructor() {
    // uma nova página (inclusive quando só a query muda, /schedule?...):
    // as mensagens da página anterior desaparecem, as mensagens flash
    // aparecem. Um serviço raiz vive enquanto a aplicação viver:
    // não é preciso cancelar a inscrição.
    inject(Router).events.subscribe((e) => {
      if (e instanceof NavigationEnd) {
        this.newPage();
      }
    });
  }

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

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

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

  clear(): void {
    this.success.set(null);
    this.error.set(null);
  }

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

  private newPage(): void {
    this.success.set(this.pending?.success ?? null);
    this.error.set(this.pending?.error ?? null);
    this.pending = null;
  }
}

Mensagens exibidas ao usuário, como na aplicação HTML: uma mensagem de sucesso no topo da página e uma mensagem de erro na parte inferior. Uma mensagem é uma chave de tradução: ela se traduz automaticamente se o usuário trocar de idioma.

  • Linhas 29–30: as duas mensagens da página atual;
  • linhas 58–63: um [ApiError] se torna a mensagem de erro da página; qualquer outro erro é um problema do lado do cliente, que pode ser reportado;
  • linhas 71–74: uma mensagem flash para a próxima página. Uma ação que termina com uma mudança de página (um médico adicionado, retorno à lista) exibe assim a sua mensagem;
  • linhas 39–43: o serviço escuta os eventos do roteador (exemplo 17). Ao final de cada navegação (linhas 76–80), as mensagens da página anterior desaparecem e as mensagens flash aparecem. No lado do servidor, esse era o papel de um cookie de curta duração.

10.4.5.3. src/app/services/confirmation.service.ts

// =========================================================================
// services/confirmation.service.ts - "Are you sure?"
// -------------------------------------------------------------------------
// Extraído do exemplo 16: confirm(key) abre o diálogo de confirmação
// (components/confirm-dialog.ts, colocado uma só vez em App) 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 this.confirmation.confirm('SCHEDULE.CANCEL_CONFIRM')) { ... }
// =========================================================================

import { inject, Injectable, signal } from '@angular/core';
import { MessagesService } from './messages.service';

@Injectable({ providedIn: 'root' })
export class ConfirmationService {
  private readonly messages = inject(MessagesService);
  private readonly _messageKey = signal<string | null>(null); // null: diálogo fechado
  readonly messageKey = this._messageKey.asReadonly();
  private answer: ((yes: boolean) => void) | null = null;

  confirm(key: string): Promise<boolean> {
    this.answer?.(false); // uma pergunta ainda aberta? conta como "não"
    // uma nova pergunta: as mensagens da ação anterior estão desatualizadas
    this.messages.clear();
    this._messageKey.set(key);
    return new Promise<boolean>((resolve) => {
      this.answer = resolve;
    });
  }

  respond(yes: boolean): void {
    this._messageKey.set(null);
    const r = this.answer;
    this.answer = null;
    r?.(yes);
  }
}

O serviço do Exemplo 16. A mensagem agora é uma chave de tradução (linha 18), e uma nova pergunta limpa as mensagens da ação anterior (linha 25).

10.4.5.4. src/app/services/form-submission.ts

// =========================================================================
// services/form-submission.ts - enviando um formulário ao servidor
// -------------------------------------------------------------------------
// Todos os formulários da aplicação seguem o mesmo padrão do
// exemplo 25: nenhuma regra é verificada no navegador (elas
// ficam em UM único lugar, o servidor), e em caso de rejeição:
//   - o erro de cada campo (ApiError.fields) é associado ao campo do
//     signal form, que o exibe com contorno vermelho;
//   - a mensagem geral (ApiError.key) é exibida no pé da página.
// Esta classe reúne esses passos. Uma página cria uma por formulário:
//
//     protected readonly submission = new FormSubmission(this.f);
//     if (await this.submission.submit(() => this.api.register(this.model()))) { ... }
//
// Ele é usado em um contexto de injeção (inicialização de um campo
// da classe do componente): é ali que obtém o serviço de mensagens.
// =========================================================================

import { inject, signal } from '@angular/core';
import { FieldTree, isFieldTree, submit, ValidationError } from '@angular/forms/signals';
import { ApiError } from '../api/api-error';
import { MessagesService } from './messages.service';

export class FormSubmission<T> {
  private readonly messages = inject(MessagesService);
  // os parâmetros das mensagens de erro ({min}...), retornados pelo servidor
  readonly params = signal<Record<string, string>>({});

  constructor(private readonly form: FieldTree<T>) {}

  // executa o envio; retorna true se teve êxito. Em caso de ApiError, os
  // erros são exibidos e false é retornado.
  // ignoreValidators: envia mesmo que as regras do schema do formulário
  // (se houver) não sejam atendidas
  async submit(action: () => Promise<unknown>, ignoreValidators = false): Promise<boolean> {
    this.params.set({});
    let succeeded = false;
    await submit(this.form, {
      ignoreValidators: ignoreValidators ? 'all' : 'pending',
      action: async () => {
        try {
          await action();
          succeeded = true;
          return null; // nenhum erro
        } catch (e) {
          this.messages.showApiError(e); // (relança qualquer erro que não seja um ApiError)
          const error = e as ApiError;
          this.params.set(error.params);
          return this.fieldErrors(error);
        }
      },
    });
    return succeeded;
  }

  // { lastName: 'ERRORS.LASTNAME_REQUIRED' } -> um erro associado ao campo f.lastName
  private fieldErrors(e: ApiError): ValidationError.WithOptionalFieldTree[] {
    const fields = this.form as unknown as Record<string, unknown>;
    return Object.entries(e.fields)
      .filter(([name]) => isFieldTree(fields[name]))
      .map(([name, key]) => ({ kind: 'server', message: key, fieldTree: fields[name] as FieldTree<unknown> }));
  }
}

Todos os formulários da aplicação seguem o padrão mostrado no Exemplo 25: as regras são validadas pelo servidor e, se um formulário for rejeitado, o erro de cada campo é exibido abaixo dele, com uma mensagem de erro geral na parte inferior da página. Esta classe agrupa essas ações para que não precisem ser repetidas em cada página:

  • linha 24: uma classe genérica: [T] é o tipo do modelo do formulário;
  • linha 25: [inject] na inicialização de um campo: a classe deve ser criada em um contexto de injeção, isto é, durante a inicialização de um campo do componente (linha 12);
  • linha 27: os parâmetros das mensagens de erro ([{{min}}]...), retornados pelo servidor;
  • linhas 35–54: o envio. [submit] (exemplo 25) executa a ação; o método retorna [true] se a ação foi bem-sucedida;
  • linha 39: [ignoreValidators]: por padrão (['pending']), [submit] não executa a ação se o formulário tiver erros de validação (a página de login tem um schema com dois campos obrigatórios). ['all']: envia a requisição mesmo assim (veja a página de login);
  • linha 46: a mensagem geral;
  • linhas 57–62: erros de campo. [isFieldTree] verifica se o formulário realmente tem um campo com esse nome: o servidor pode reportar um erro para um campo que o formulário não exibe.

10.4.6. Formatação

10.4.6.1. src/app/pipes/formatting.ts

// =========================================================================
// pipes/formatting.ts - a exibição de pessoas, horários e dias
// -------------------------------------------------------------------------
// O servidor envia dados BRUTOS (startHour: 8, startMinute: 0; day:
// "2026-10-05"); a formatação, que depende do idioma, é responsabilidade
// do cliente. Funções, usadas pelo código, e pipes (arquivo
// formatting.pipes.ts), usados pelos templates.
// =========================================================================

import { 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)}`;
}

// data de hoje, no formato "yyyy-MM-dd" (o de <input type="date"> e o da API)
export function today(): string {
  const d = new Date();
  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
}

// true se [day] for uma data que existe, no formato yyyy-MM-dd
export function isValidDate(day: unknown): day is string {
  if (typeof day !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(day)) {
    return false;
  }
  const date = new Date(`${day}T00:00:00Z`);
  return !isNaN(date.getTime()) && date.toISOString().slice(0, 10) === day;
}

// "lundi 5 octobre 2026" / "Monday 5 October 2026"
export function longDate(day: string, language: string | null): string {
  return new Intl.DateTimeFormat(language === 'en' ? 'en-GB' : 'fr-FR', {
    dateStyle: 'full',
    timeZone: 'UTC', // "2026-10-05T00:00:00Z" deve continuar sendo dia 5, independentemente do fuso horário
  }).format(new Date(`${day}T00:00:00Z`));
}

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

  • linhas 34–40: esta data é válida? [2026-02-30] tem o formato correto, mas não existe: [new Date] a converteria para 2 de março. Por isso verificamos se ela é lida de forma idêntica. [day is string]: se a função retorna true, o [TypeScript] sabe que [day] é uma string;
  • linhas 43–48: [Intl.DateTimeFormat], fornecido pelo navegador, escreve a data no idioma solicitado. O fuso horário UTC impede que um navegador situado a oeste de Greenwich exiba o dia anterior.

10.4.6.2. src/app/pipes/formatting.pipes.ts

// =========================================================================
// pipes/formatting.pipes.ts - as funções de formatting.ts, como pipes
// -------------------------------------------------------------------------
//     {{ doctor | label }}                 "Mme Marie PELISSIER"
//     {{ slot | timeRange }}               "8:00 - 8:20"
//     {{ day | longDate: language() }}     "Monday 5 October 2026"
// longDate recebe o idioma como parâmetro: um pipe puro só é recalculado
// se um de seus argumentos mudar - trocar o idioma, portanto, o recalcula.
// =========================================================================

import { Pipe, PipeTransform } from '@angular/core';
import { Slot, Identity } from '../api/types';
import { timeRange, longDate, label } from './formatting';

@Pipe({ name: 'label' })
export class LabelPipe implements PipeTransform {
  transform(p: Identity): string {
    return label(p);
  }
}

@Pipe({ name: 'timeRange' })
export class TimeRangePipe implements PipeTransform {
  transform(s: Slot): string {
    return timeRange(s);
  }
}

@Pipe({ name: 'longDate' })
export class LongDatePipe implements PipeTransform {
  transform(day: string, language: string | null): string {
    return longDate(day, language);
  }
}

As mesmas funções, como pipes, para os templates. [longDate] recebe o idioma como parâmetro: um pipe puro (exemplo 09) só é recalculado se um de seus argumentos mudar; mudar o idioma, portanto, dispara um recálculo.

10.4.7. O roteador

10.4.7.1. src/app/app.routes.ts

// =========================================================================
// app.routes.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 agora são rotas do CLIENTE. O
// navegador envia uma requisição ao servidor apenas para a primeira
// página; depois, o roteador muda o endereço e o componente exibido.
//
// O outro lado da moeda: se o usuário recarregar /schedule (F5), o
// navegador pede /schedule ao servidor, que deve então
// retornar index.html (ng serve faz isso em desenvolvimento; em produção,
// veja web/client-spa.ts do servidor JSON).
//
// Todas as páginas são FILHAS de uma rota sem componente,
// que carrega o guard sessionGuard (canActivateChild): ele se aplica, assim,
// a cada uma delas. Cada rota declara:
//   - title: chave de tradução do título da aba (veja i18n/title.strategy.ts);
//   - data : public (acessível sem login), roles (os papéis
//             permitidos), type ('doctors' ou 'clients'), code (403, 404).
// Graças a withComponentInputBinding (app.config.ts), os parâmetros do
// endereço (:id, ?day=...) E os dados (type, code) chegam aos
// INPUTS dos componentes das páginas.
// =========================================================================

import { Routes } from '@angular/router';
import { PersonType } from './api/rdvmedecins.api';
import { Role } from './api/types';
import { registrationGuard, sessionGuard, numericId } from './guards';
import { LoginPage } from './pages/login/login';
import { SchedulePage } from './pages/schedule/schedule';

// as rotas que gerenciam os médicos E os clientes (ADMIN), no mesmo
// modelo; as páginas são carregadas sob demanda (loadComponent)
function personRoutes(type: PersonType, title: string, addTitle: string, editTitle: string): Routes {
  const data = { roles: ['ADMIN'] as Role[], type };
  return [
    { path: type, loadComponent: () => import('./pages/persons/persons'), title: title, data },
    { path: `${type}/add`, loadComponent: () => import('./pages/person-form/person-form'), title: addTitle, data },
    {
      path: `${type}/:id/edit`,
      canMatch: [numericId],
      loadComponent: () => import('./pages/person-form/person-form'),
      title: editTitle,
      data,
    },
  ];
}

export const routes: Routes = [
  {
    path: '',
    canActivateChild: [sessionGuard],
    children: [
      // "/": vai para /login, que por sua vez vai para a página inicial do papel se o usuário estiver logado
      { path: '', pathMatch: 'full', redirectTo: 'login' },
      { path: 'login', component: LoginPage, title: 'LOGIN.TITLE', data: { public: true } },
      { path: 'schedule', component: SchedulePage, title: 'SCHEDULE.PAGE_TITLE' },
      ...personRoutes('doctors', 'DOCTORS.TITLE', 'DOCTORS.ADD', 'DOCTORS.EDIT'),
      ...personRoutes('clients', 'CLIENTS.TITLE', 'CLIENTS.ADD', 'CLIENTS.EDIT'),
      {
        path: 'register',
        loadComponent: () => import('./pages/register/register'),
        title: 'REGISTRATION.TITLE',
        data: { public: true },
        canActivate: [registrationGuard],
      },
      {
        path: 'my-area',
        loadComponent: () => import('./pages/patient-area/patient-area'),
        title: 'AREA.TITLE',
        data: { roles: ['USER'] },
      },
      {
        path: 'my-account',
        loadComponent: () => import('./pages/my-account/my-account'),
        title: 'MY_ACCOUNT.TITLE',
        data: { roles: ['USER'] },
      },
      { path: 'forbidden', loadComponent: () => import('./pages/error/error'), title: 'ERROR_PAGE.TITLE', data: { code: 403 } },
      {
        path: '**',
        loadComponent: () => import('./pages/error/error'),
        title: 'ERROR_PAGE.TITLE',
        data: { code: 404, public: true },
      },
    ],
  },
];

As mesmas URLs da aplicação HTML (/login, /schedule, /doctors, /my-area...), mas agora são rotas do cliente:

  • linhas 50–53: todas as páginas são filhas ([children]) de uma rota sem componente, que carrega o guard [sessionGuard]: [canActivateChild] o aplica a cada uma delas sem precisar repeti-lo;
  • linha 55: o endereço / leva à página de login, que por sua vez redireciona para a página inicial do papel se o usuário estiver logado;
  • linhas 56–57: as duas páginas mais visitadas fazem parte do arquivo principal; as demais são carregadas sob demanda ([loadComponent]);
  • [title]: a chave de tradução do título da aba;
  • [data]: [public] (acessível sem estar logado), [roles] (papéis autorizados; ausente: todos os papéis logados), [type] (['doctors'] ou ['clients']), [code] (403, 404). Graças a [withComponentInputBinding], os dados da rota também são repassados aos inputs do componente da página, assim como os parâmetros do endereço;
  • linhas 34–47: as três rotas do gerenciamento de médicos e as do gerenciamento de clientes são geradas pela mesma função: os dois gerenciamentos usam as mesmas páginas, com um [type] diferente;
  • linha 41: [canMatch]: um guard que determina se a rota corresponde ao endereço. Se ele falhar, o roteador tenta as rotas seguintes: /doctors/abc/edit leva, portanto, a uma página 404;
  • linha 65: um guard específico da página de criação de conta;
  • linha 79: a página 403, para a qual o guard redireciona;
  • linhas 80–85: qualquer outro endereço: a página 404.

10.4.7.2. src/app/guards.ts

// =========================================================================
// guards.ts - os guards do roteador
// -------------------------------------------------------------------------
// sessionGuard: o guard de TODAS as páginas (veja app.routes.ts). Antes
// de cada navegação:
//   1. na primeira vez (inicialização, F5), pergunta ao servidor quem está
//      logado (SessionService.check);
//   2. verifica os direitos descritos nos dados da rota:
//        - public: acessível sem login;
//        - roles : os papéis permitidos (ausente = todos os papéis logados).
//
// LEMBRETE: essas verificações são apenas uma COMODIDADE (não exibir uma
// página inútil). A proteção dos dados é garantida pelo servidor, que
// verifica o token e o papel novamente a CADA requisição.
//
// AVISO: inject() só é permitido no INÍCIO de um guard, antes de qualquer
// await (depois disso, o "contexto de injeção" é perdido).
// =========================================================================

import { inject } from '@angular/core';
import { CanActivateChildFn, CanActivateFn, CanMatchFn, Router } from '@angular/router';
import { Role } from './api/types';
import { RdvMedecinsApi } from './api/rdvmedecins.api';
import { SessionService } from './services/session.service';
import { MessagesService } from './services/messages.service';

export const sessionGuard: CanActivateChildFn = async (route, state) => {
  const session = inject(SessionService);
  const router = inject(Router);
  await session.check();

  if (route.data['public']) {
    // já logado: a página de login deixa de fazer sentido
    if (route.routeConfig?.path === 'login' && session.loggedIn()) {
      return router.parseUrl(session.homePage());
    }
    return true;
  }
  if (!session.loggedIn()) {
    // a página solicitada é memorizada, para voltar a ela após o login
    return router.createUrlTree(['/login'], { queryParams: { redirect: state.url } });
  }
  const roles = route.data['roles'] as Role[] | undefined;
  if (roles && !roles.includes(session.role()!)) {
    return router.createUrlTree(['/forbidden']);
  }
  return true;
};

// um guard ESPECÍFICO da rota /register: sem um passe (captcha
// resolvido na página de login), volta para a página de login
export const registrationGuard: CanActivateFn = async () => {
  const api = inject(RdvMedecinsApi);
  const messages = inject(MessagesService);
  const router = inject(Router);
  const { valid } = await api.registrationAccessStatus().catch(() => ({ valid: false }));
  if (!valid) {
    messages.flash('error', 'ERRORS.CAPTCHA_BEFORE_ACCOUNT');
    return router.createUrlTree(['/login']);
  }
  return true;
};

// /doctors/3/edit: a rota CORRESPONDE apenas se o 2º segmento do
// endereço for um número (/doctors/abc/edit leva à página 404)
export const numericId: CanMatchFn = (_route, segments) => /^\d+$/.test(segments[1]?.path ?? '');
  • Linha 27: um guard pode ser [async]: o roteador aguarda a sua resposta;
  • Linhas 28–30: ATENÇÃO: [inject] só é permitido no início do guard, antes de qualquer [await]; depois disso, o contexto de injeção é perdido;
  • linha 30: na primeira vez, o servidor é consultado para saber quem está logado;
  • linhas 32–38: uma página pública; mas a página de login deixa de fazer sentido para um usuário logado (linha 34). [parseUrl] converte um endereço em [UrlTree], o valor que dispara um redirecionamento;
  • linhas 39–42: não logado: para a página de login, mantendo a página solicitada;
  • linhas 43–46: um papel inválido: redireciona para a página 403;
  • linhas 52–62: criar uma conta exige um "passe", obtido ao resolver o CAPTCHA na página de login. Sem ele, o usuário é devolvido à página de login com uma mensagem;
  • linha 66: o guard [canMatch] recebe os segmentos do endereço: [['doctors', '3', 'edit']].

Esses guards são apenas uma conveniência: a proteção dos dados é garantida pelo servidor, que reverifica o token e o papel a cada requisição.

10.4.8. Os componentes

10.4.8.1. src/app/components/nav-bar

// =========================================================================
// components/nav-bar/nav-bar.ts - a barra de navegação
// -------------------------------------------------------------------------
// Mesmo conteúdo da aplicação HTML (views/partials/navbar.hbs):
// título, menus conforme o papel, FR / EN, papel, nome, logout.
// "Doctors" e "Patients" aparecem apenas para o ADMIN: uma mera
// comodidade de exibição, sendo a proteção real a do servidor.
// =========================================================================

import { Component, inject } from '@angular/core';
import { Router, RouterLink, RouterLinkActive } from '@angular/router';
import { TranslatePipe } from '@ngx-translate/core';
import { SessionService } from '../../services/session.service';
import { LanguageService } from '../../i18n/language.service';
import { LANGUAGES } from '../../i18n/i18n';

@Component({
  selector: 'app-nav-bar',
  imports: [RouterLink, RouterLinkActive, TranslatePipe],
  templateUrl: './nav-bar.html',
})
export class NavBar {
  protected readonly session = inject(SessionService);
  protected readonly languages = inject(LanguageService);
  protected readonly LANGUAGES = LANGUAGES;
  private readonly router = inject(Router);

  protected async logOut(): Promise<void> {
    await this.session.logOut().catch(() => {}); // mesmo que o servidor não responda
    this.router.navigate(['/login']);
  }
}
  • Linha 29: faz logout, mesmo que o servidor não responda; depois retorna à página de login.
<nav class="navbar navbar-expand-sm navbar-dark bg-primary rounded mb-4 px-3">
  <span class="navbar-brand mb-0">{{ 'APP.TITLE' | translate }}</span>

  @if (session.loggedIn()) {
    <ul class="navbar-nav me-auto">
      @if (session.isPatient()) {
        <li class="nav-item">
          <!-- routerLinkActive: a classe Bootstrap do menu da página exibida -->
          <a class="nav-link" routerLink="/my-area" routerLinkActive="active">{{ 'APP.MENU_MY_AREA' | translate }}</a>
        </li>
      }
      <li class="nav-item">
        <a class="nav-link" routerLink="/schedule" routerLinkActive="active">{{ 'APP.MENU_SCHEDULE' | translate }}</a>
      </li>
      @if (session.isAdmin()) {
        <li class="nav-item">
          <a class="nav-link" routerLink="/doctors" routerLinkActive="active">{{ 'APP.MENU_DOCTORS' | translate }}</a>
        </li>
        <li class="nav-item">
          <a class="nav-link" routerLink="/clients" routerLinkActive="active">{{ 'APP.MENU_PATIENTS' | translate }}</a>
        </li>
      }
    </ul>
  } @else {
    <div 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 próprio lugar -->
    <div class="btn-group btn-group-sm" role="group" [attr.aria-label]="'APP.LANGUAGE' | translate">
      @for (l of LANGUAGES; track l) {
        <button type="button" class="btn" [class]="languages.language() === l ? 'btn-light' : 'btn-outline-light'"
                [attr.aria-pressed]="languages.language() === l" (click)="languages.change(l)">
          {{ l.toUpperCase() }}
        </button>
      }
    </div>

    @if (session.user(); as u) {
      <span class="badge text-bg-light text-primary">{{ u.role }}</span>
      <span class="text-white">{{ u.name }}</span>
      <button type="button" class="btn btn-sm btn-outline-light" (click)="logOut()">{{ 'APP.LOGOUT' | translate }}</button>
    }
  </div>
</nav>
  • Linhas 4–23: os menus, conforme o papel;
  • linhas 31–36: os botões FR / EN; [aria-pressed] indica aos leitores de tela qual botão está pressionado;
  • linhas 39–43: papel, nome, logout.

10.4.8.2. src/app/components/success-message.ts e error-panel.ts

// =========================================================================
// components/success-message.ts - a mensagem de SUCESSO, no topo da página
// (consulta agendada, médico adicionado...) - veja services/messages.service.ts.
// role="status": um leitor de tela a anuncia sem interromper o usuário.
// =========================================================================

import { Component, inject } from '@angular/core';
import { TranslatePipe } from '@ngx-translate/core';
import { MessagesService } from '../services/messages.service';

@Component({
  selector: 'app-success-message',
  imports: [TranslatePipe],
  template: `
    @if (messages.success(); as m) {
      <div class="alert alert-success" role="status">{{ m.key | translate: m.params }}</div>
    }
  `,
})
export class SuccessMessage {
  protected readonly messages = inject(MessagesService);
}
// =========================================================================
// components/error-panel.ts - o painel de erros, na PARTE INFERIOR de cada página,
// sobre um fundo rosa claro (classe .error-panel, veja styles.css) - como
// views/partials/errors.hbs da aplicação HTML.
// role="alert": um leitor de tela anuncia a mensagem assim que ela aparece.
// =========================================================================

import { Component, inject } from '@angular/core';
import { TranslatePipe } from '@ngx-translate/core';
import { MessagesService } from '../services/messages.service';

@Component({
  selector: 'app-error-panel',
  imports: [TranslatePipe],
  template: `
    @if (messages.error(); as m) {
      <div class="error-panel" role="alert">{{ m.key | translate: m.params }}</div>
    }
  `,
})
export class ErrorPanel {
  protected readonly messages = inject(MessagesService);
}

Dois pequenos componentes que exibem as mensagens do serviço [MessagesService], traduzidas junto com seus parâmetros. Os papéis [status] e [alert] fazem os leitores de tela anunciarem as mensagens.

10.4.8.3. src/app/components/confirm-dialog

// =========================================================================
// components/confirm-dialog/confirm-dialog.ts
// -------------------------------------------------------------------------
// O diálogo "Are you sure?" do exemplo 16, completado para o teclado
// como public/js/app.js da aplicação HTML:
//   - ao abrir, o foco vai para "No, go back": um pressionar distraído de
//     Enter não exclui nada;
//   - Escape fecha o diálogo (= No);
//   - Tab e Shift+Tab permanecem DENTRO do diálogo (senão o foco iria para
//     a página acinzentada, atrás);
//   - ao fechar, o foco volta ao elemento que o tinha (o botão
//     "Delete" clicado, por exemplo).
// "No, go back" em vez de "Cancel": a pergunta às vezes é "Cancel this
// appointment?", e um botão "Cancel" seria ambíguo nesse caso.
// =========================================================================

import { Component, effect, ElementRef, inject, untracked, viewChild } from '@angular/core';
import { TranslatePipe } from '@ngx-translate/core';
import { ConfirmationService } from '../../services/confirmation.service';

@Component({
  selector: 'app-confirm-dialog',
  imports: [TranslatePipe],
  templateUrl: './confirm-dialog.html',
})
export class ConfirmDialog {
  protected readonly confirmation = inject(ConfirmationService);
  private readonly dialog = viewChild<ElementRef<HTMLElement>>('dialog');
  private readonly noButton = viewChild<ElementRef<HTMLButtonElement>>('noButton');
  private previousFocus: HTMLElement | null = null;

  constructor() {
    // o diálogo abre (o botão "No" aparece) ou fecha
    effect(() => {
      const button = this.noButton();
      untracked(() => {
        if (button) {
          this.previousFocus = document.activeElement as HTMLElement | null;
          button.nativeElement.focus();
        } else {
          this.previousFocus?.focus();
          this.previousFocus = null;
        }
      });
    });
  }

  protected onKeydown(e: KeyboardEvent): void {
    const dialog = this.dialog()?.nativeElement;
    if (e.key === 'Escape') {
      this.confirmation.respond(false);
    } else if (e.key === 'Tab' && dialog) {
      const buttons = [...dialog.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();
      }
    }
  }

  // um clique no fundo acinzentado (e não no próprio diálogo) = No
  protected onBackdropClick(e: MouseEvent): void {
    if (e.target === e.currentTarget) {
      this.confirmation.respond(false);
    }
  }
}

A janela do Exemplo 16, com suporte a teclado adicionado:

  • linhas 34–45: um effect que acompanha o aparecimento e o desaparecimento do botão "No". Na abertura, o elemento que tinha o foco é guardado e o foco é dado ao botão "No"; no fechamento, o foco volta ao elemento guardado (o botão "Delete" em que se clicou, por exemplo). [untracked]: os signals lidos nessa função não se tornam dependências do effect;
  • linhas 48–64: o teclado. Esc responde "não"; Tab e Shift+Tab permanecem dentro da janela: do último botão, volta-se ao primeiro, e vice-versa. Caso contrário, o foco iria para a página esmaecida por trás;
  • linhas 67–71: um clique no fundo esmaecido responde "não".
@if (confirmation.messageKey(); as key) {
  <div (keydown)="onKeydown($event)">
    <div class="modal-backdrop fade show"></div>
    <div #dialog class="modal fade show d-block" tabindex="-1" role="alertdialog" aria-modal="true"
         aria-labelledby="confirmation-title" aria-describedby="confirmation-message" (click)="onBackdropClick($event)">
      <div class="modal-dialog modal-dialog-centered">
        <div class="modal-content">
          <div class="modal-header">
            <h5 id="confirmation-title" class="modal-title">{{ 'CONFIRMATION.TITLE' | translate }}</h5>
            <button type="button" class="btn-close" [attr.aria-label]="'BOOKING_DIALOG.CLOSE_ARIA' | translate"
                    (click)="confirmation.respond(false)"></button>
          </div>
          <div class="modal-body">
            <p id="confirmation-message" class="mb-0">{{ key | translate }}</p>
          </div>
          <div class="modal-footer">
            <button #noButton type="button" class="btn btn-secondary" (click)="confirmation.respond(false)">
              {{ 'CONFIRMATION.NO' | translate }}
            </button>
            <button type="button" class="btn btn-danger" (click)="confirmation.respond(true)">{{ 'CONFIRMATION.YES' | translate }}</button>
          </div>
        </div>
      </div>
    </div>
  </div>
}
  • linha 2: as teclas pressionadas são escutadas no elemento que contém a janela;
  • linha 14: a mensagem, uma chave traduzida.

10.4.8.4. src/app/components/input-field.ts

// =========================================================================
// components/input-field.ts - um campo de formulário completo
// -------------------------------------------------------------------------
// Rótulo + campo + mensagem de ajuda OU mensagem de erro. Todos os
// formulários da aplicação o utilizam, com um signal form:
//
//   <app-input-field [formField]="f.lastName" fieldId="lastName" label="PERSONS.LASTNAME_LABEL" [maxChars]="20" />
//
// É um CONTROLE DE FORMULÁRIO "CASEIRO": ao implementar a interface
// FormValueControl, ele aceita [formField] como um <input> comum.
// O contrato é simples:
//   - value (um model()): o valor do campo, lido E escrito pelo
//     formulário;
//   - errors (um input opcional do contrato): se o componente
//     o declara, a diretiva [formField] coloca nele os erros do campo -
//     aqui, os retornados pelo SERVIDOR (veja pages/person-form.ts).
// label, help e a mensagem dos erros são CHAVES de tradução.
// =========================================================================

import { booleanAttribute, Component, computed, input, model } from '@angular/core';
import { FormValueControl, ValidationError } from '@angular/forms/signals';
import { TranslatePipe } from '@ngx-translate/core';

@Component({
  selector: 'app-input-field',
  imports: [TranslatePipe],
  // um componente é exibido "inline" por padrão: fazemos dele um bloco,
  // para que as classes definidas pelo pai (mb-3, col-sm-6) sejam aplicadas
  styles: `
    :host {
      display: block;
    }
  `,
  template: `
    <label class="form-label" [for]="fieldId()">{{ label() | translate }}</label>
    <input class="form-control" [id]="fieldId()" [type]="type()" [value]="value()" (input)="onInput($event)"
           [class.is-invalid]="error()" [attr.maxlength]="maxChars() ?? null" [autocomplete]="autocomplete()"
           [required]="mandatory()" [attr.aria-invalid]="error() ? 'true' : null" [attr.aria-describedby]="fieldId() + '-message'">
    @if (error(); as e) {
      <div class="invalid-feedback" [id]="fieldId() + '-message'">{{ e | translate: params() }}</div>
    } @else if (help(); as h) {
      <div class="form-text" [id]="fieldId() + '-message'">{{ h | translate: params() }}</div>
    }
  `,
})
export class InputField implements FormValueControl<string> {
  // o contrato FormValueControl
  readonly value = model('');
  readonly errors = input<readonly ValidationError.WithOptionalFieldTree[]>([]);

  // nossos próprios inputs
  // o id do <input> (não "id": um atributo id permaneceria TAMBÉM em
  // <app-input-field>, e a página teria dois elementos com o mesmo id)
  readonly fieldId = input.required<string>();
  readonly label = input.required<string>(); // chave de tradução
  readonly type = input<'text' | 'password'>('text');
  readonly help = input<string>(); // chave da mensagem de ajuda
  readonly params = input<Record<string, string>>({}); // parâmetros das mensagens ({min}...)
  readonly maxChars = input<number>();
  readonly autocomplete = input('off');
  readonly mandatory = input(false, { transform: booleanAttribute });

  // o primeiro erro do campo (sua chave de tradução), se houver
  protected readonly error = computed(() => this.errors()[0]?.message);

  protected onInput(event: Event): void {
    this.value.set((event.target as HTMLInputElement).value);
  }
}

Um campo de formulário completo: rótulo, campo, dica ou mensagem de erro. Todos os formulários da aplicação o utilizam. É um controle de formulário personalizado: ao respeitar o contrato [FormValueControl], ele aceita a diretiva [[formField]] como um [<input>] comum:

  • linha 46: a classe implementa a interface [FormValueControl<string>]: o compilador verifica se ela respeita o contrato;
  • linha 48: [value], um [model()] (Exemplo 11): o valor do campo que a diretiva [[formField]] lê E escreve;
  • linha 49: [errors], um input opcional do contrato: se o componente o declara, a diretiva armazena ali os erros do campo;
  • linhas 54–61: inputs específicos do componente. O identificador do elemento [<input>] chama-se [fieldId], e não [id]: um atributo [id] definido em [<app-input-field>] também permaneceria definido nesse elemento, e a página teria dois elementos com o mesmo identificador;
  • linha 61: [booleanAttribute] converte a presença do atributo ([mandatory], sem valor) em [true];
  • linha 64: o primeiro erro do campo: sua chave de tradução;
  • Linhas 36–38: o elemento [<input>] exibe o valor e o devolve a cada tecla digitada (linhas 66–68). [aria-invalid] e [aria-describedby] associam o campo à sua mensagem para os leitores de tela;
  • linhas 39–43: a mensagem de erro ou, caso contrário, a mensagem de ajuda, traduzidas junto com seus parâmetros;
  • linhas 29–33: [:host] refere-se ao próprio elemento do componente ([<app-input-field>]). Um elemento desconhecido do navegador é exibido "em linha": ele é convertido em bloco para que as classes aplicadas pelo pai ([col-sm-6]) tenham efeito.

10.4.8.5. src/app/components/person-fields.ts

// =========================================================================
// components/person-fields.ts - título, nome, sobrenome
// -------------------------------------------------------------------------
// Os campos de identidade, comuns a três formulários: médico / cliente do
// ADMIN, "Create a patient account" e "Manage my account" (o equivalente do
// partial views/partials/personFields.hbs). O pai passa a ele os três
// CAMPOS de seu signal form:
//     <app-person-fields [title]="f.title" [firstName]="f.firstName" [lastName]="f.lastName" />
// Um campo (FieldTree) é um valor como qualquer outro: ele pode ser passado
// como input de um componente, que o vincula a seus próprios elementos HTML.
// =========================================================================

import { Component, input } from '@angular/core';
import { FieldTree, FormField } from '@angular/forms/signals';
import { TranslatePipe } from '@ngx-translate/core';
import { InputField } from './input-field';

@Component({
  selector: 'app-person-fields',
  imports: [FormField, TranslatePipe, InputField],
  template: `
    <div class="mb-3">
      <label class="form-label" for="title">{{ 'PERSONS.TITLE_LABEL' | translate }}</label>
      <!-- title(): o campo recebido como input; title()(): seu estado -->
      @let titleError = title()().errors()[0]?.message;
      <select id="title" class="form-select" [formField]="title()" [class.is-invalid]="titleError">
        @for (t of TITLES; track t) {
          <option [value]="t">{{ t }}</option>
        }
      </select>
      @if (titleError) {
        <div class="invalid-feedback">{{ titleError | translate }}</div>
      }
    </div>
    <div class="row g-3 mb-3">
      <app-input-field class="col-sm-6" fieldId="firstName" label="PERSONS.FIRSTNAME_LABEL" [formField]="firstName()" [maxChars]="20" mandatory />
      <app-input-field class="col-sm-6" fieldId="lastName" label="PERSONS.LASTNAME_LABEL" [formField]="lastName()" [maxChars]="20" mandatory />
    </div>
  `,
})
export class PersonFields {
  readonly title = input.required<FieldTree<string>>();
  readonly firstName = input.required<FieldTree<string>>();
  readonly lastName = input.required<FieldTree<string>>();
  protected readonly TITLES = ['Mr', 'Mme', 'Melle'];
}

Os campos de título, nome e sobrenome, comuns a três formulários. O pai repassa a este componente os três campos de seu formulário baseado em signals:

  • linhas 42–44: um campo ([FieldTree]) é um valor como qualquer outro: ele pode ser recebido como input;
  • linha 25: [title()] é o campo recebido como input; [title()()] é o seu estado;
  • linha 26: a lista de títulos é vinculada ao campo por meio de [[formField]];
  • linhas 36–37: os outros dois campos são repassados aos componentes [InputField].

10.4.8.6. src/app/components/captcha-field.ts

// =========================================================================
// components/captcha-field.ts - a imagem do captcha e o campo de entrada
// -------------------------------------------------------------------------
// Um controle de formulário "caseiro" (FormValueControl, veja input-field.ts)
// que carrega um captcha (GET /api/captcha) assim que é criado. O pai:
//   - vincula o input ao seu formulário: [formField]="f.captcha";
//   - obtém o próprio componente com viewChild(CaptchaField), para
//     chamar seus métodos PÚBLICOS: captchaId(), e reload() após
//     cada tentativa, porque uma imagem só pode ser usada UMA vez (o servidor
//     a esquece assim que a verifica).
//
// [innerHTML] + bypassSecurityTrustHtml: a imagem SVG é inserida tal
// como está. Inofensivo AQUI porque é gerada pelo nosso servidor
// (biblioteca svg-captcha) e não contém nada que venha de um
// usuário - veja o exemplo 22.
// =========================================================================

import { Component, computed, inject, input, model, signal } from '@angular/core';
import { DomSanitizer } from '@angular/platform-browser';
import { FormValueControl, ValidationError } from '@angular/forms/signals';
import { TranslatePipe } from '@ngx-translate/core';
import { RdvMedecinsApi } from '../api/rdvmedecins.api';
import { Captcha } from '../api/types';

@Component({
  selector: 'app-captcha-field',
  imports: [TranslatePipe],
  styles: `
    :host {
      display: block;
    }
  `,
  template: `
    <div class="mb-3">
      <label class="form-label" for="captcha">{{ 'CAPTCHA.LABEL' | translate }}</label>
      <div class="d-flex align-items-center gap-3 mb-2">
        <div class="captcha-image" role="img" [attr.aria-label]="'CAPTCHA.IMAGE_ALT' | translate" [innerHTML]="svg()"></div>
        <a href="#" class="small" (click)="$event.preventDefault(); reload()">{{ 'CAPTCHA.NEW_IMAGE' | translate }}</a>
      </div>
      <input id="captcha" type="text" maxlength="10" autocomplete="off" autocapitalize="off" spellcheck="false"
             class="form-control" [class.is-invalid]="error()" [value]="value()" (input)="onInput($event)">
      @if (error(); as e) {
        <div class="invalid-feedback">{{ e | translate }}</div>
      } @else {
        <div class="form-text">{{ 'CAPTCHA.HELP' | translate }}</div>
      }
    </div>
  `,
})
export class CaptchaField implements FormValueControl<string> {
  readonly value = model('');
  readonly errors = input<readonly ValidationError.WithOptionalFieldTree[]>([]);

  private readonly api = inject(RdvMedecinsApi);
  private readonly sanitizer = inject(DomSanitizer);
  private readonly captcha = signal<Captcha | null>(null);
  protected readonly svg = computed(() => this.sanitizer.bypassSecurityTrustHtml(this.captcha()?.svg ?? ''));
  protected readonly error = computed(() => this.errors()[0]?.message);

  constructor() {
    this.reload();
  }

  // uma nova imagem e um campo vazio
  async reload(): Promise<void> {
    this.value.set('');
    try {
      this.captcha.set(await this.api.captcha());
    } catch {
      this.captcha.set(null); // servidor inacessível: o login falhará com uma mensagem clara
    }
  }

  // o identificador da imagem exibida, a ser enviado com a resposta
  captchaId(): string {
    return this.captcha()?.id ?? '';
  }

  protected onInput(event: Event): void {
    this.value.set((event.target as HTMLInputElement).value);
  }
}

A imagem do CAPTCHA e seu campo de entrada: outro controle de formulário personalizado.

  • linha 61: uma imagem é carregada assim que o componente é criado;
  • linhas 65–72: [reload] é público: a página de login o chama após cada tentativa, pois uma imagem só é usada uma vez;
  • linhas 75–77: o ID da imagem exibida, a ser enviado junto com a resposta;
  • linha 37: a imagem SVG (exemplo 22), com texto alternativo para leitores de tela;
  • linha 40: [autocapitalize] e [spellcheck]: sem capitalização automática nem verificação ortográfica em um celular.

A página pai obtém este componente por meio de [viewChild(CaptchaField)] (exemplo 13) para chamar seus métodos públicos.

10.4.8.7. src/app/components/booking-dialog

// =========================================================================
// components/booking-dialog/booking-dialog.ts
// -------------------------------------------------------------------------
// O diálogo para agendar um horário. Mesmo diálogo de
// views/partials/booking.hbs da aplicação HTML: as classes Bootstrap
// de um diálogo modal, exibido "fixo no código" (show d-block).
//
// O componente não conversa com o servidor: ele emite
//   - confirm, com o paciente escolhido (null para um paciente que agenda
//     para si mesmo);
//   - close.
// É a página da agenda que decide o que fazer com isso (pages/schedule.ts).
// =========================================================================

import { afterNextRender, Component, ElementRef, input, output, signal, viewChild } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { TranslatePipe } from '@ngx-translate/core';
import { Person } from '../../api/types';
import { LabelPipe } from '../../pipes/formatting.pipes';

@Component({
  selector: 'app-booking-dialog',
  imports: [FormsModule, TranslatePipe, LabelPipe],
  // Escape, em qualquer lugar da página: fechamos
  host: { '(document:keydown.escape)': 'close.emit()' },
  templateUrl: './booking-dialog.html',
})
export class BookingDialog {
  readonly time = input.required<string>(); // "8:00 - 8:20"
  readonly clients = input<readonly Person[]>([]); // ADMIN / DOCTOR: os pacientes entre os quais escolher
  readonly patient = input<string | null>(null); // USER: o paciente é ele mesmo
  readonly submitting = input(false);

  readonly confirm = output<number | null>();
  readonly close = output<void>();

  protected readonly clientId = signal<number | null>(null);
  private readonly list = viewChild<ElementRef<HTMLSelectElement>>('list');
  private readonly confirmButton = viewChild.required<ElementRef<HTMLButtonElement>>('confirmButton');

  constructor() {
    // quando exibido, o foco no primeiro elemento útil do diálogo
    afterNextRender(() => (this.list() ?? this.confirmButton()).nativeElement.focus());
  }

  // um clique no fundo acinzentado (e não no próprio diálogo) fecha o diálogo
  protected onBackdropClick(e: MouseEvent): void {
    if (e.target === e.currentTarget) {
      this.close.emit();
    }
  }
}

A janela de reserva de horário. Ela não se comunica com o servidor: recebe o que exibe e envia a decisão do usuário; é a página da agenda que executa a ação.

  • Linhas 29–32: inputs: o horário, os pacientes entre os quais escolher (ADMIN, DOCTOR) ou o próprio paciente (USER), e um indicador de "envio em andamento";
  • Linhas 34–35: outputs: confirmar, com o paciente selecionado; fechar;
  • linha 25: Esc fecha a janela;
  • linha 43: [afterNextRender] (exemplo 13): assim que a janela é exibida, o foco vai para a lista de pacientes ou, caso contrário, para o botão de confirmação.
<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)="onBackdropClick($event)">
  <div class="modal-dialog modal-dialog-centered">
    <form class="modal-content" (ngSubmit)="confirm.emit(clientId())">
      <div class="modal-header">
        <h5 id="booking-title" class="modal-title">{{ 'BOOKING_DIALOG.TITLE' | translate }}</h5>
        <button type="button" class="btn-close" [attr.aria-label]="'BOOKING_DIALOG.CLOSE_ARIA' | translate"
                (click)="close.emit()"></button>
      </div>

      <div class="modal-body">
        <p>{{ 'BOOKING_DIALOG.SLOT' | translate: { time: time() } }}</p>
        <!-- um paciente marca para si mesmo: nenhuma lista (e o servidor
             ignoraria de qualquer forma um eventual clientId) -->
        @if (patient() !== null) {
          <p class="mb-0">{{ 'BOOKING_DIALOG.PATIENT_LABEL' | translate }}: <strong>{{ patient() }}</strong></p>
        } @else {
          <label class="form-label" for="clientId">{{ 'BOOKING_DIALOG.PATIENT_LABEL' | translate }}</label>
          <select #list id="clientId" name="clientId" class="form-select" [(ngModel)]="clientId">
            <option [ngValue]="null">{{ 'BOOKING_DIALOG.CHOOSE_PATIENT' | translate }}</option>
            @for (c of clients(); track c.id) {
              <option [ngValue]="c.id">{{ c | label }}</option>
            }
          </select>
        }
      </div>

      <div class="modal-footer">
        <button type="button" class="btn btn-secondary" (click)="close.emit()">{{ 'BOOKING_DIALOG.CANCEL' | translate }}</button>
        <button #confirmButton type="submit" class="btn btn-primary" [disabled]="submitting()">
          {{ 'BOOKING_DIALOG.CONFIRM' | translate }}
        </button>
      </div>
    </form>
  </div>
</div>
  • linha 5: um formulário: a tecla Enter confirma;
  • linhas 16–26: um paciente faz a reserva para si mesmo: sem lista;
  • linhas 21–24: [[ngValue]] (exemplo 05): o valor de cada opção é um número ou [null];
  • linha 31: o botão fica desabilitado durante o envio: nada de reserva dupla por duplo clique.

10.4.9. As páginas

10.4.9.1. src/app/pages/login

// =========================================================================
// pages/login/login.ts - a página de login (/login)
// -------------------------------------------------------------------------
// Mesma página de views/login.hbs da aplicação HTML: login, senha,
// captcha, e um segundo botão "Create a patient account" que verifica o
// MESMO captcha antes de abrir a criação da conta.
//
// /login?login=jbernard: o campo de login vem preenchido (logo após a
// criação de uma conta).
// /login?redirect=/doctors: após o login, esta página é aberta
// (colocada ali pelo guard do roteador) em vez da página inicial do papel.
// Esses dois parâmetros chegam como INPUTS do componente.
// =========================================================================

import { afterNextRender, Component, inject, input, signal, viewChild } from '@angular/core';
import { Router } from '@angular/router';
import { form, FormField, required } from '@angular/forms/signals';
import { TranslatePipe } from '@ngx-translate/core';
import { RdvMedecinsApi } from '../../api/rdvmedecins.api';
import { SessionService } from '../../services/session.service';
import { MessagesService } from '../../services/messages.service';
import { FormSubmission } from '../../services/form-submission';
import { CaptchaField } from '../../components/captcha-field';

@Component({
  selector: 'app-login',
  imports: [FormField, TranslatePipe, CaptchaField],
  templateUrl: './login.html',
})
export class LoginPage {
  readonly login = input<string>(); // ?login=...
  readonly redirect = input<string>(); // ?redirect=...

  private readonly api = inject(RdvMedecinsApi);
  private readonly session = inject(SessionService);
  private readonly messages = inject(MessagesService);
  private readonly router = inject(Router);

  protected readonly model = signal({ login: '', password: '', captcha: '' });
  // duas regras: login e senha obrigatórios. [formField] então define
  // o atributo HTML required nos dois campos, e o navegador se recusa
  // a enviar o formulário enquanto estiverem vazios
  protected readonly f = form(this.model, (p) => {
    required(p.login);
    required(p.password);
  });
  private readonly submission = new FormSubmission(this.f);
  // o componente captcha, para chamar seus métodos captchaId() e reload()
  private readonly captchaField = viewChild.required(CaptchaField);

  constructor() {
    afterNextRender(() => {
      // os inputs agora são conhecidos: o login da URL, se houver
      const login = (this.login() ?? '').slice(0, 30);
      this.model.update((m) => ({ ...m, login }));
      // o foco: na senha se o login já estiver preenchido
      (login ? this.f.password : this.f.login)().focusBoundControl();
    });
  }

  // os dois botões compartilham este fluxo: envio e, em caso de falha,
  // mensagem de erro e NOVA imagem (cada uma só pode ser usada uma vez)
  private async attempt(action: () => Promise<unknown>, ignoreValidators = false): Promise<void> {
    this.messages.clear();
    await this.submission.submit(async () => {
      try {
        await action();
      } catch (e) {
        // a nova imagem ANTES de o erro ser associado ao campo:
        // reload() esvazia o campo, o que apagaria o erro
        await this.captchaField().reload();
        throw e;
      }
    }, ignoreValidators);
  }

  protected async logIn(event: Event): Promise<void> {
    event.preventDefault();
    const { login, password, captcha } = this.model();
    await this.attempt(async () => {
      await this.session.logIn(login.trim(), password, this.captchaField().captchaId(), captcha);
      const redirect = this.redirect();
      // apenas um caminho INTERNO: nunca um redirecionamento para outro site
      const internal = redirect !== undefined && redirect.startsWith('/') && !redirect.startsWith('//');
      await this.router.navigateByUrl(internal ? redirect : this.session.homePage());
    });
  }

  protected async createAccount(): Promise<void> {
    await this.attempt(async () => {
      await this.api.registrationAccess(this.captchaField().captchaId(), this.model().captcha);
      await this.router.navigate(['/register']);
    }, true); // login e senha não são usados aqui: suas regras são ignoradas
  }
}

A página de login: nome de usuário, senha, CAPTCHA e um segundo botão "Create a patient account" que verifica o MESMO CAPTCHA antes de permitir a criação da conta.

  • Linhas 31–32: dois parâmetros de URL: /login?login=jbernard preenche previamente o nome de usuário (logo após a criação da conta); /login?redirect=/doctors, definido pelo guard, indica a página a abrir após o login;
  • Linhas 43–46: o único formulário da aplicação com um schema: nome de usuário e senha são obrigatórios. A diretiva [[formField]] define então o atributo HTML [required] nos dois campos, e o navegador se recusa a enviar o formulário enquanto eles estiverem vazios;
  • linha 47: o envio do formulário (services/form-submission.ts);
  • linha 49: o componente do captcha, para chamar seus métodos;
  • linhas 52–58: [afterNextRender]: assim que a página é exibida, os inputs são conhecidos. O login vindo da URL é copiado para o formulário (limitado a 30 caracteres) e o foco é colocado no primeiro campo vazio. [focusBoundControl()] coloca o foco no elemento vinculado ao campo por [[formField]];
  • Linhas 63–75: os dois botões seguem esta sequência: enviar e, se falhar, uma nova imagem (cada uma é usada apenas uma vez). A ordem importa: [reload] limpa o campo do CAPTCHA, o que removeria o erro associado a esse campo; por isso recarregamos a imagem ANTES, para disparar o erro novamente, e então o [FormSubmission] o associa ao campo;
  • linhas 77–87: login, seguido da navegação para a página solicitada ou para a página inicial do papel. Como no Exemplo 18, apenas um caminho interno é aceito (linha 84);
  • linhas 89–94: o segundo botão. O servidor verifica o CAPTCHA e define um "passe" (um cookie); a página de criação de conta é então aberta. O nome de usuário e a senha não são usados aqui: as regras do schema são ignoradas (linha 93).
<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">{{ 'LOGIN.TITLE' | translate }}</h5>

      <form (submit)="logIn($event)">
        <div class="mb-3">
          <label class="form-label" for="login">{{ 'LOGIN.LOGIN_LABEL' | translate }}</label>
          <input id="login" type="text" class="form-control" autocomplete="username" [formField]="f.login">
        </div>
        <div class="mb-3">
          <label class="form-label" for="password">{{ 'LOGIN.PASSWORD_LABEL' | translate }}</label>
          <input id="password" type="password" class="form-control" autocomplete="current-password"
                 [formField]="f.password">
        </div>

        <!-- um controle "caseiro", vinculado ao campo captcha do formulário -->
        <app-captcha-field [formField]="f.captcha" />

        <!-- type="submit": Enter em um campo aciona "Log in" -->
        <button type="submit" class="btn btn-primary w-100" [disabled]="f().submitting()">{{ 'LOGIN.SUBMIT' | translate }}</button>

        <!-- type="button": este botão não envia o formulário (nenhuma verificação de
             required no login e na senha, inútil aqui) -->
        <button type="button" class="btn btn-outline-primary w-100 mt-3" [disabled]="f().submitting()" (click)="createAccount()">
          {{ 'LOGIN.CREATE_ACCOUNT' | translate }}
        </button>
        <div class="form-text text-center">{{ 'LOGIN.CREATE_ACCOUNT_HELP' | translate }}</div>
      </form>

      <div class="text-muted small mt-3">
        {{ 'LOGIN.DEMO_ACCOUNTS' | translate }}
        <ul class="mb-0 mt-1">
          <li><code>admin</code> - {{ 'LOGIN.DEMO_ADMIN' | translate }}</li>
          <li><code>pelissier</code>, <code>tatou</code>, <code>dupont</code> - {{ 'LOGIN.DEMO_DOCTOR' | translate }}</li>
          <li><code>martin</code>, <code>durand</code>, <code>bistrou</code>, <code>german</code> - {{ 'LOGIN.DEMO_USER' | translate }}</li>
        </ul>
      </div>
    </div>
  </div>
</div>
  • linha 6: sem [novalidate] aqui: o navegador sinaliza um nome de usuário ou senha vazio;
  • linha 18: o controle de CAPTCHA personalizado, vinculado ao campo [captcha] do formulário;
  • linha 21: o botão fica desabilitado durante o envio ([submitting()]);
  • linha 25: [type="button"]: este botão não envia o formulário, portanto o navegador não exige nome de usuário e senha.

10.4.9.2. src/app/pages/schedule

// =========================================================================
// pages/schedule/schedule.ts - a página da agenda (/schedule)
// -------------------------------------------------------------------------
// Três blocos, como views/schedule.hbs da aplicação HTML:
//   1. a escolha do médico e do dia;
//   2. a agenda desse médico nesse dia;
//   3. o diálogo para agendar um horário.
//
// Como na aplicação HTML, TODO o estado da página está em sua URL:
//     /schedule?doctorId=1&day=2026-10-05           a agenda
//     /schedule?doctorId=1&day=2026-10-05&book=7    + o diálogo de agendamento
// A página pode, portanto, ser recarregada, adicionada aos favoritos, e os
// botões Voltar / Avançar do navegador funcionam. A página SEGUE sua URL: os três
// parâmetros chegam como INPUTS (signals), e um effect recarrega
// a agenda quando o médico ou o dia muda; as ações do
// usuário, por sua vez, mudam a URL (router.navigate).
//
// O que cada um vê e pode fazer é decidido pelo SERVIDOR (campos
// patient, mine, bookable, appointmentId de cada horário): a página apenas
// o exibe. Um paciente não recebe sequer o nome dos outros pacientes.
// =========================================================================

import { Component, computed, effect, inject, input, signal, untracked } from '@angular/core';
import { Router, RouterLink } from '@angular/router';
import { FormsModule } from '@angular/forms';
import { TranslatePipe } from '@ngx-translate/core';
import { ApiError } from '../../api/api-error';
import { RdvMedecinsApi } from '../../api/rdvmedecins.api';
import { Schedule, ScheduleSlot, Person } from '../../api/types';
import { today, isValidDate, timeRange } from '../../pipes/formatting';
import { TimeRangePipe, LongDatePipe, LabelPipe } from '../../pipes/formatting.pipes';
import { LanguageService } from '../../i18n/language.service';
import { SessionService } from '../../services/session.service';
import { MessagesService } from '../../services/messages.service';
import { ConfirmationService } from '../../services/confirmation.service';
import { BookingDialog } from '../../components/booking-dialog/booking-dialog';

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

@Component({
  selector: 'app-schedule',
  imports: [FormsModule, RouterLink, TranslatePipe, TimeRangePipe, LongDatePipe, LabelPipe, BookingDialog],
  templateUrl: './schedule.html',
})
export class SchedulePage {
  // os parâmetros da URL (undefined se estiverem ausentes)
  readonly doctorId = input<string>();
  readonly day = input<string>();
  readonly book = input<string>();

  private readonly api = inject(RdvMedecinsApi);
  private readonly router = inject(Router);
  protected readonly session = inject(SessionService);
  private readonly messages = inject(MessagesService);
  private readonly confirmation = inject(ConfirmationService);
  protected readonly language = inject(LanguageService).language;

  protected readonly doctors = signal<Person[]>([]);
  protected readonly clients = signal<Person[]>([]); // ADMIN / DOCTOR: para o diálogo de agendamento
  protected readonly schedule = signal<Schedule | null>(null);
  protected readonly loading = signal(false);
  protected readonly submitting = signal(false);

  // os valores do formulário "médico + dia", copiados da URL
  protected readonly doctorChoice = signal<number | null>(null);
  protected readonly dayChoice = signal(today());

  // a agenda exibida, sem diálogo de agendamento: a consulta "voltar"
  protected readonly scheduleQuery = computed(() => ({ doctorId: String(this.doctorChoice() ?? ''), day: this.dayChoice() }));

  // o horário cujo diálogo de agendamento está aberto (?book=7),
  // somente se puder ser agendado por este usuário
  protected readonly slotToBook = computed<ScheduleSlot | null>(() => {
    const id = positiveInteger(this.book());
    return this.schedule()?.slots.find((c) => c.id === id && c.bookable) ?? null;
  });

  // o nome do paciente logado (USER), ou null para ADMIN e DOCTOR
  protected readonly patient = computed(() => (this.session.isPatient() ? (this.session.user()?.name ?? '') : null));

  constructor() {
    this.loadLists();
    // a agenda segue a URL (médico e dia): o effect LÊ os dois inputs,
    // e o carregamento é feito sem rastreamento (untracked)
    effect(() => {
      const doctorId = this.doctorId();
      const day = this.day();
      untracked(() => this.loadSchedule(doctorId, day));
    });
  }

  // -------------------------------------------------------------------------
  // carregamento
  // -------------------------------------------------------------------------
  private async loadLists(): Promise<void> {
    try {
      this.doctors.set(await this.api.list('doctors'));
      // a lista de pacientes: apenas para quem tem permissão para lê-la
      if (this.session.isManager()) {
        this.clients.set(await this.api.list('clients'));
      }
    } catch (e) {
      this.messages.showApiError(e);
    }
  }

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

  // a agenda da URL atual, lida novamente (após um agendamento, um cancelamento)
  private reload(): Promise<void> {
    return this.loadSchedule(this.doctorId(), this.day());
  }

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

  // "View schedule": a URL é alterada, a agenda a segue (effect acima)
  protected viewSchedule(): void {
    this.router.navigate(['/schedule'], { queryParams: this.scheduleQuery() });
  }

  protected closeBooking(): void {
    this.router.navigate(['/schedule'], { queryParams: this.scheduleQuery() });
  }

  protected async confirmBooking(clientId: number | null): Promise<void> {
    const slot = this.slotToBook();
    if (slot === null) {
      return;
    }
    this.submitting.set(true);
    try {
      await this.api.book(this.dayChoice(), slot.id, this.session.isManager() ? clientId : null);
      this.messages.flash('success', 'SCHEDULE.BOOKED');
    } catch (e) {
      if (e instanceof ApiError && e.key === 'ERRORS.CHOOSE_PATIENT') {
        // nenhum paciente escolhido: o diálogo permanece aberto
        this.messages.showError(e.key);
        return; // (finally é executado 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
      this.messages.flash('error', e.key, e.params);
    } finally {
      this.submitting.set(false);
    }
    await this.router.navigate(['/schedule'], { queryParams: this.scheduleQuery() });
    await this.reload(); // o servidor é a referência: a agenda é lida novamente
  }

  protected async cancel(c: ScheduleSlot): Promise<void> {
    if (c.appointmentId === null || !(await this.confirmation.confirm('SCHEDULE.CANCEL_CONFIRM'))) {
      return;
    }
    try {
      await this.api.cancelAppointment(c.appointmentId);
      this.messages.showSuccess('SCHEDULE.CANCELLED');
    } catch (e) {
      this.messages.showApiError(e);
    }
    await this.reload();
  }

  protected timeRange(c: ScheduleSlot): string {
    return timeRange(c);
  }
}

A página mais rica em recursos da aplicação. Como na aplicação HTML, TODO o estado da página está contido na URL: /schedule?doctorId=1&day=2026-10-05 exibe uma agenda, &book=7 acrescenta a janela de reserva. Assim, você pode recarregar a página, salvá-la nos favoritos e usar os botões Voltar/Avançar. O princípio: a página acompanha sua URL, e as ações do usuário alteram a URL.

  • linhas 51–53: os três parâmetros da URL, como input;
  • linhas 39–42: um parâmetro de endereço pode conter qualquer coisa; ele é validado;
  • linhas 69–70: os valores do formulário "médico + dia", copiados da URL;
  • linha 73: os parâmetros da agenda exibida, sem a janela de reserva;
  • linhas 77–80: o horário para o qual a janela de reserva está aberta, calculado a partir do endereço ([?book=7]) e da agenda: somente se puder ser reservado por este usuário. Um [computed]: quando o endereço muda, a janela abre ou fecha automaticamente;
  • linhas 89–93: um effect que depende dos dois inputs [doctorId] e [day]: a agenda é recarregada quando qualquer um deles muda. O recarregamento é executado em [untracked]: os signals que ele lê e modifica não se tornam dependências do effect. O input [book] não é lido: abrir ou fechar a janela não recarrega a agenda;
  • linhas 99–109: médicos e, para quem tem permissão para vê-los, pacientes;
  • linhas 111–141: carregamento da agenda. Uma data inválida é reportada (linhas 115–118); sem um médico, um DOCTOR vê a SUA PRÓPRIA agenda: o servidor a obtém a partir do token (linhas 126–129);
  • linhas 153–159: "View schedule" e o fechamento da janela alteram o endereço; a agenda o acompanha;
  • linhas 161–187: a marcação da consulta. Em caso de sucesso, uma mensagem flash é preparada (linha 169); ela será exibida após a linha 185, que fecha a janela. Se nenhum paciente tiver sido selecionado, a janela permanece aberta (linhas 171–175). Qualquer outro erro (horário ocupado nesse meio-tempo etc.) será exibido na agenda, com a janela fechada. Em todos os casos, a agenda é lida novamente: o registro do servidor é definitivo (linha 186);
  • linhas 189–200: cancelamento, após confirmação.
<!-- 1. a escolha do médico e do dia -->
<form class="card p-3 mb-3" (ngSubmit)="viewSchedule()">
  <div class="row g-2 align-items-end">
    <div class="col-sm-5">
      <label class="form-label" for="doctorId">{{ 'DOCTOR_DAY_PICKER.DOCTOR_LABEL' | translate }}</label>
      <select id="doctorId" name="doctorId" class="form-select" required [(ngModel)]="doctorChoice">
        <option [ngValue]="null">{{ 'DOCTOR_DAY_PICKER.CHOOSE_DOCTOR' | translate }}</option>
        @for (d of doctors(); track d.id) {
          <option [ngValue]="d.id">{{ d | label }}</option>
        }
      </select>
    </div>
    <div class="col-sm-4">
      <label class="form-label" for="day">{{ 'DOCTOR_DAY_PICKER.DAY_LABEL' | translate }}</label>
      <input id="day" name="day" type="date" class="form-control" required [(ngModel)]="dayChoice">
    </div>
    <div class="col-sm-3">
      <button type="submit" class="btn btn-primary w-100">{{ 'DOCTOR_DAY_PICKER.VIEW_SCHEDULE' | translate }}</button>
    </div>
  </div>
</form>

@let s = schedule();

<!-- paciente que já tem uma consulta futura: por isso não há botão "Book" -->
@if (s?.info; as info) {
  <div class="alert alert-info">
    {{ info | translate }} <a routerLink="/my-area" class="alert-link">{{ 'APP.MENU_MY_AREA' | translate }}</a>
  </div>
}

<!-- 2. a agenda -->
@if (loading() && !s) {
  <p class="text-muted">{{ 'APP.LOADING' | translate }}</p>
} @else if (s) {
  <div class="card p-3">
    <h5>{{ 'SCHEDULE.TITLE_PREFIX' | translate }} {{ s.day | longDate: language() }} - {{ s.doctor | label }}</h5>
    @if (s.slots.length > 0) {
      <table class="table table-hover align-middle">
        <thead>
          <tr>
            <th>{{ 'SCHEDULE.COLUMN_SLOT' | translate }}</th>
            <th>{{ 'SCHEDULE.COLUMN_STATUS' | translate }}</th>
            <th></th>
          </tr>
        </thead>
        <tbody>
          @for (c of s.slots; track c.id) {
            <tr [class.free-slot]="c.bookable">
              <td>{{ c | timeRange }}</td>
              <td>
                @if (c.free) {
                  <span class="badge text-bg-success">{{ 'SCHEDULE.FREE' | translate }}</span>
                } @else if (c.patient; as p) {
                  <span class="badge" [class]="c.mine ? 'text-bg-primary' : 'text-bg-secondary'">{{ p | label }}</span>
                } @else {
                  <span class="badge text-bg-secondary">{{ 'SCHEDULE.BOOKED_BY_OTHER' | translate }}</span>
                }
              </td>
              <td class="text-end">
                <!-- "Book" é um LINK: ele adiciona &book=... à URL, o que
                     abre o diálogo de marcação -->
                @if (c.bookable) {
                  <a class="btn btn-sm btn-outline-success" routerLink="/schedule" [queryParams]="{ doctorId: scheduleQuery().doctorId, day: scheduleQuery().day, book: c.id }">
                    {{ 'SCHEDULE.BOOK' | translate }}
                  </a>
                }
                @if (c.appointmentId !== null) {
                  <button type="button" class="btn btn-sm btn-outline-danger" (click)="cancel(c)">
                    {{ 'SCHEDULE.CANCEL_APPOINTMENT' | translate }}
                  </button>
                }
              </td>
            </tr>
          }
        </tbody>
      </table>
    } @else {
      <p class="text-muted mb-0">{{ 'SCHEDULE.NO_SLOTS' | translate }}</p>
    }
  </div>
} @else {
  <p class="text-muted">{{ 'SCHEDULE.EMPTY_STATE' | translate }}</p>
}

<!-- 3. o diálogo de agendamento, somente se a URL contiver &book=... -->
@if (slotToBook(); as c) {
  <app-booking-dialog [time]="timeRange(c)" [clients]="clients()" [patient]="patient()"
                           [submitting]="submitting()" (confirm)="confirmBooking($event)"
                           (close)="closeBooking()" />
}
  • linhas 2–21: seleção do médico e do dia, com [ngModel] (exemplo 05);
  • linha 23: [@let]: a agenda, lida uma vez;
  • linhas 26–30: um paciente que já tem uma consulta futura: o servidor envia uma mensagem explicando por que não há o botão "Book";
  • linha 37: a data por extenso, no idioma local;
  • linhas 52–58: o estado do horário: disponível, o paciente (exibido em azul) ou "Booked" quando o servidor não enviou o nome do paciente;
  • linhas 63–67: "Book" é um link: ele acrescenta &book=... à URL, o que abre a janela de reserva;
  • linhas 87–91: a janela de reserva, somente se a URL contiver &book=... e o horário puder ser reservado.

10.4.9.3. src/app/pages/persons/persons.config.ts

// =========================================================================
// pages/persons/persons.config.ts - médicos ou clientes?
// -------------------------------------------------------------------------
// As páginas que gerenciam os médicos e os clientes são IDÊNTICAS: mesma
// lista, mesmo formulário. Como na aplicação HTML (classe abstrata
// PersonsController), são escritas UMA ÚNICA vez (persons.ts,
// person-form.ts); somente o endereço da API e as chaves dos rótulos
// mudam, descritos aqui. O roteador fornece o tipo nos
// dados de cada rota (veja app.routes.ts).
// =========================================================================

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

export interface PersonKeys {
  title: string; // "Doctors"
  add: string; // "Add a doctor"
  edit: string; // "Edit a doctor"
  empty: string; // "No doctor."
  confirmDelete: string;
  added: string; // "Doctor {{name}} has been added (login: {{login}})."
  edited: string;
  deleted: string;
}

export const PERSON_KEYS: Record<PersonType, PersonKeys> = {
  doctors: {
    title: 'DOCTORS.TITLE',
    add: 'DOCTORS.ADD',
    edit: 'DOCTORS.EDIT',
    empty: 'DOCTORS.EMPTY',
    confirmDelete: 'DOCTORS.DELETE_CONFIRM',
    added: 'DOCTORS.ADDED',
    edited: 'DOCTORS.UPDATED',
    deleted: 'DOCTORS.DELETED',
  },
  clients: {
    title: 'CLIENTS.TITLE',
    add: 'CLIENTS.ADD',
    edit: 'CLIENTS.EDIT',
    empty: 'CLIENTS.EMPTY',
    confirmDelete: 'CLIENTS.DELETE_CONFIRM',
    added: 'CLIENTS.ADDED',
    edited: 'CLIENTS.UPDATED',
    deleted: 'CLIENTS.DELETED',
  },
};

// {{name}} e {{login}} das mensagens "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 ?? '' };
}

As páginas de gerenciamento de médicos e de clientes são idênticas: mesma lista, mesmo formulário. Como na aplicação HTML (classe abstrata [PersonsController]), são escritas uma só vez; só mudam o endereço da API e as chaves dos rótulos, descritos aqui:

  • linha 25: [Record<PersonType, PersonKeys>]: o compilador exige exatamente uma entrada para cada tipo, nem mais, nem menos;
  • linhas 49–51: os parâmetros das mensagens "adicionado / modificado / excluído".

10.4.9.4. src/app/pages/persons

// =========================================================================
// pages/persons/persons.ts - a lista de médicos OU de clientes (ADMIN)
// -------------------------------------------------------------------------
// Uma única página para ambos: o tipo ('doctors' ou 'clients') está nos
// dados da rota (data.type, veja app.routes.ts) e chega como
// INPUT do componente; os rótulos específicos de cada um estão em
// persons.config.ts. Equivalente a views/persons/list.hbs da
// aplicação HTML.
// "export default": a rota carrega a página sob demanda (loadComponent).
// =========================================================================

import { Component, computed, inject, input, OnInit, signal } from '@angular/core';
import { RouterLink } from '@angular/router';
import { TranslatePipe } from '@ngx-translate/core';
import { RdvMedecinsApi, PersonType } from '../../api/rdvmedecins.api';
import { Person } from '../../api/types';
import { MessagesService } from '../../services/messages.service';
import { ConfirmationService } from '../../services/confirmation.service';
import { PERSON_KEYS, messageParams } from './persons.config';

@Component({
  selector: 'app-persons',
  imports: [RouterLink, TranslatePipe],
  templateUrl: './persons.html',
})
export default class PersonsPage implements OnInit {
  readonly type = input.required<PersonType>(); // data.type da rota

  private readonly api = inject(RdvMedecinsApi);
  private readonly messages = inject(MessagesService);
  private readonly confirmation = inject(ConfirmationService);

  protected readonly keys = computed(() => PERSON_KEYS[this.type()]);
  protected readonly persons = signal<Person[] | null>(null); // null: ainda não carregado

  // ngOnInit em vez do construtor: os inputs (type) já são conhecidos
  ngOnInit(): void {
    this.load();
  }

  private async load(): Promise<void> {
    try {
      this.persons.set(await this.api.list(this.type()));
    } catch (e) {
      this.messages.showApiError(e);
    }
  }

  protected async remove(p: Person): Promise<void> {
    if (!(await this.confirmation.confirm(this.keys().confirmDelete))) {
      return;
    }
    try {
      await this.api.remove(this.type(), p.id);
      this.messages.showSuccess(this.keys().deleted, messageParams(p));
    } catch (e) {
      // um médico que ainda tem consultas: 409 ERRORS.DOCTOR_HAS_APPOINTMENTS
      this.messages.showApiError(e);
    }
    await this.load();
  }
}
  • linha 26: [export default]: a rota carrega a página sob demanda (exemplo 17);
  • linha 27: o tipo (['doctors'] ou ['clients']) vem dos dados de input da rota;
  • linha 33: as chaves dos rótulos deste tipo;
  • linha 34: [null]: a lista ainda não foi carregada;
  • Linhas 37–39: [ngOnInit] (Exemplo 13) em vez do construtor: os inputs já são conhecidos;
  • linhas 49–61: exclusão, após confirmação. Um médico que ainda tem consultas não pode ser excluído: o servidor retorna uma resposta 409 e sua mensagem é exibida.
<div class="d-flex justify-content-between align-items-center mb-3">
  <h4 class="mb-0">{{ keys().title | translate }}</h4>
  <a class="btn btn-primary" [routerLink]="['/', type(), 'add']">{{ keys().add | translate }}</a>
</div>

<div class="card p-3">
  @let list = persons();
  @if (list === null) {
    <p class="text-muted mb-0">{{ 'APP.LOADING' | translate }}</p>
  } @else if (list.length === 0) {
    <p class="text-muted mb-0">{{ keys().empty | translate }}</p>
  } @else {
    <table class="table table-hover align-middle mb-0">
      <thead>
        <tr>
          <th>{{ 'PERSONS.COLUMN_TITLE' | translate }}</th>
          <th>{{ 'PERSONS.COLUMN_FIRSTNAME' | translate }}</th>
          <th>{{ 'PERSONS.COLUMN_LASTNAME' | translate }}</th>
          <th>{{ 'PERSONS.COLUMN_LOGIN' | translate }}</th>
          <th></th>
        </tr>
      </thead>
      <tbody>
        @for (p of list; track p.id) {
          <tr>
            <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">
                <a class="btn btn-sm btn-outline-primary" [routerLink]="['/', type(), p.id, 'edit']">{{ 'PERSONS.EDIT' | translate }}</a>
                <button type="button" class="btn btn-sm btn-outline-danger" (click)="remove(p)">{{ 'PERSONS.DELETE' | translate }}</button>
              </div>
            </td>
          </tr>
        }
      </tbody>
    </table>
  }
</div>
  • linha 3: [['/', type(), 'add']]: /doctors/add ou /clients/add;
  • linhas 8–12: durante o carregamento, uma lista vazia, uma lista;
  • linha 32: /doctors/3/edit.

10.4.9.5. src/app/pages/person-form

// =========================================================================
// pages/person-form/person-form.ts - criação OU atualização
// de um médico ou de um cliente (ADMIN)
// -------------------------------------------------------------------------
//     /doctors/add               -> criação (sem input id)
//     /doctors/3/edit            -> atualização (input id = 3)
// (e os mesmos endereços em /clients). Equivalente a
// views/persons/form.hbs da aplicação HTML.
//
// Nenhuma regra é verificada aqui: o servidor valida tudo, e seus erros
// são exibidos sob os campos (veja services/form-submission.ts).
// A VERSÃO lida com o registro volta com a atualização: se outro
// ADMIN o atualizou nesse meio-tempo, o servidor responde 409 CONCURRENT_UPDATE.
// =========================================================================

import { Component, computed, inject, input, numberAttribute, OnInit, signal } from '@angular/core';
import { Router, RouterLink } from '@angular/router';
import { form, FormField } from '@angular/forms/signals';
import { TranslatePipe } from '@ngx-translate/core';
import { ApiError } from '../../api/api-error';
import { RdvMedecinsApi, PersonType } from '../../api/rdvmedecins.api';
import { PersonData } from '../../api/types';
import { MessagesService } from '../../services/messages.service';
import { FormSubmission } from '../../services/form-submission';
import { PersonFields } from '../../components/person-fields';
import { InputField } from '../../components/input-field';
import { PERSON_KEYS, messageParams } from '../persons/persons.config';

@Component({
  selector: 'app-person-form',
  imports: [RouterLink, FormField, TranslatePipe, PersonFields, InputField],
  templateUrl: './person-form.html',
})
export default class PersonFormPage implements OnInit {
  readonly type = input.required<PersonType>(); // data.type da rota
  // o parâmetro :id do endereço, convertido em número; ausente em uma criação
  readonly id = input(undefined, { transform: (v: string | undefined) => (v === undefined ? undefined : numberAttribute(v)) });

  private readonly api = inject(RdvMedecinsApi);
  private readonly messages = inject(MessagesService);
  private readonly router = inject(Router);

  protected readonly keys = computed(() => PERSON_KEYS[this.type()]);
  protected readonly creating = computed(() => this.id() === undefined);

  protected readonly model = signal<PersonData>({ title: 'Mr', firstName: '', lastName: '', login: '', password: '', version: undefined });
  protected readonly f = form(this.model); // sem validator: o servidor valida
  protected readonly submission = new FormSubmission(this.f);

  // atualização: o registro é lido (incluindo sua versão)
  async ngOnInit(): Promise<void> {
    const id = this.id();
    if (id === undefined) {
      return;
    }
    try {
      const p = await this.api.read(this.type(), id);
      this.model.set({ title: p.title, firstName: p.firstName, lastName: p.lastName, login: p.login ?? '', password: '', version: p.version });
    } catch (e) {
      // registro que não existe (excluído nesse meio-tempo...): volta para a lista
      if (!(e instanceof ApiError)) {
        throw e;
      }
      this.messages.flash('error', e.key, e.params);
      this.router.navigate(['/', this.type()]);
    }
  }

  protected async save(event: Event): Promise<void> {
    event.preventDefault();
    const id = this.id();
    const succeeded = await this.submission.submit(async () => {
      const data = this.model();
      const p = id === undefined ? await this.api.add(this.type(), data) : await this.api.edit(this.type(), id, data);
      this.messages.flash('success', this.creating() ? this.keys().added : this.keys().edited, messageParams(p));
    });
    const key = this.messages.error()?.key;
    if (succeeded) {
      this.router.navigate(['/', this.type()]);
    } else if (key === 'ERRORS.DOCTOR_NOT_FOUND' || key === 'ERRORS.PATIENT_NOT_FOUND') {
      // excluído nesse meio-tempo por outro ADMIN: volta para a lista
      this.messages.flash('error', key);
      this.router.navigate(['/', this.type()]);
    }
  }
}

Criação (/doctors/add) OU modificação (/doctors/3/edit) de um médico ou de um cliente:

  • linha 37: o parâmetro de endereço [:id], que está ausente em uma criação. A opção [transform] o converte em número ([numberAttribute]);
  • linha 44: criação ou modificação?
  • linhas 46–48: o formulário, sem validador (o servidor valida tudo), e seu envio;
  • linhas 51–67: para uma atualização, o registro é lido, inclusive sua versão; ele será atualizado com as alterações (bloqueio otimista). Um registro inexistente (/doctors/999/edit) redireciona para a lista com uma mensagem;
  • linhas 69–85: salvamento. Em caso de sucesso, uma mensagem flash é preparada e o usuário é redirecionado para a lista (linhas 75 e 78–79). Se um registro foi excluído nesse meio-tempo por outro administrador, o usuário também é redirecionado para a lista (linhas 80–84); qualquer outro erro mantém o formulário exibido, junto com seus erros.
<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">{{ (creating() ? keys().add : keys().edit) | translate }}</h5>
      <!-- novalidate: é o SERVIDOR que valida (ele é a referência) -->
      <form novalidate (submit)="save($event)">
        <app-person-fields [title]="f.title" [firstName]="f.firstName" [lastName]="f.lastName" />

        <h6 class="mt-4 text-muted">{{ 'PERSONS.ACCOUNT_SECTION' | translate }}</h6>
        <app-input-field class="mb-3" fieldId="login" label="PERSONS.LOGIN_LABEL" [maxChars]="30" [formField]="f.login"
                          [help]="creating() ? 'PERSONS.LOGIN_HELP_CREATE' : 'PERSONS.LOGIN_HELP_EDIT'" />
        <!-- nunca preenchido previamente: a senha nunca volta do servidor -->
        <app-input-field class="mb-4" fieldId="password" type="password" label="PERSONS.PASSWORD_LABEL" [maxChars]="72"
                          autocomplete="new-password" [formField]="f.password" [params]="submission.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]="f().submitting()">{{ 'PERSONS.SAVE' | translate }}</button>
          <a class="btn btn-secondary" [routerLink]="['/', type()]">{{ 'PERSONS.BACK' | translate }}</a>
        </div>
      </form>
    </div>
  </div>
</div>
  • linha 6: [novalidate]: o servidor valida o formulário;
  • linha 7: título, nome e sobrenome, em um único componente;
  • linhas 10–15: o nome de usuário e a senha, com uma mensagem de ajuda diferente para a criação e para a modificação. A senha nunca é preenchida previamente: ela nunca é retornada pelo servidor;
  • linha 14: parâmetros das mensagens de erro retornadas pelo servidor (comprimento mínimo da senha, por exemplo).

10.4.9.6. src/app/pages/register

// =========================================================================
// pages/register/register.ts - "Create a patient account" (/register)
// -------------------------------------------------------------------------
// Só se chega aqui depois de copiar o captcha da página de login
// (botão "Create a patient account"): o servidor então emitiu um
// passe, que o guard da rota verificou (veja guards.ts).
// Mesmos campos do formulário do ADMIN, mas o login e a senha
// são obrigatórios, com confirmação. Equivalente a
// views/account/registration.hbs da aplicação HTML.
// =========================================================================

import { Component, computed, inject, signal } from '@angular/core';
import { Router, RouterLink } from '@angular/router';
import { form, FormField } from '@angular/forms/signals';
import { TranslatePipe } from '@ngx-translate/core';
import { RdvMedecinsApi } from '../../api/rdvmedecins.api';
import { Registration } from '../../api/types';
import { MessagesService } from '../../services/messages.service';
import { FormSubmission } from '../../services/form-submission';
import { PersonFields } from '../../components/person-fields';
import { InputField } from '../../components/input-field';

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

@Component({
  selector: 'app-register',
  imports: [RouterLink, FormField, TranslatePipe, PersonFields, InputField],
  templateUrl: './register.html',
})
export default class RegisterPage {
  private readonly api = inject(RdvMedecinsApi);
  private readonly messages = inject(MessagesService);
  private readonly router = inject(Router);

  protected readonly model = signal<Registration>({ title: 'Mr', firstName: '', lastName: '', login: '', password: '', confirmation: '' });
  protected readonly f = form(this.model);
  protected readonly submission = new FormSubmission(this.f);
  // os parâmetros da mensagem de ajuda E dos erros da senha
  protected readonly passwordParams = computed(() => ({ min: PASSWORD_MIN, ...this.submission.params() }));

  protected async create(event: Event): Promise<void> {
    event.preventDefault();
    let login = '';
    const succeeded = await this.submission.submit(async () => {
      login = (await this.api.register(this.model())).login;
    });
    if (succeeded) {
      // volta para a página de login, com o login preenchido
      this.messages.flash('success', 'REGISTRATION.DONE', { login });
      this.router.navigate(['/login'], { queryParams: { login } });
    } else if (this.messages.error()?.key === 'ERRORS.CAPTCHA_BEFORE_ACCOUNT') {
      // passe expirado (15 minutos): volta para o captcha
      this.messages.flash('error', 'ERRORS.CAPTCHA_BEFORE_ACCOUNT');
      this.router.navigate(['/login']);
    }
  }
}

Criação de uma conta de paciente. Aqui só é possível prosseguir com o token emitido pelo servidor após a resolução do CAPTCHA (guards.ts):

  • linha 25: o comprimento mínimo da senha; para a mensagem de ajuda: o mesmo valor do servidor;
  • linha 41: os parâmetros da mensagem de ajuda e das mensagens de erro da senha. Os parâmetros do servidor, se algum for retornado, têm precedência (eles são colocados por último);
  • linhas 46–48: envio; o servidor retorna o nome de usuário da conta criada;
  • linhas 49–52: retorno à página de login, com o nome de usuário preenchido previamente;
  • linhas 53–57: o token expirou (15 minutos): retorno ao CAPTCHA.
<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">{{ 'REGISTRATION.TITLE' | translate }}</h5>
      <p class="text-muted small mb-3">{{ 'REGISTRATION.INTRO' | translate }}</p>
      <form novalidate (submit)="create($event)">
        <app-person-fields [title]="f.title" [firstName]="f.firstName" [lastName]="f.lastName" />

        <h6 class="mt-4 text-muted">{{ 'PERSONS.ACCOUNT_SECTION' | translate }}</h6>
        <app-input-field class="mb-3" fieldId="login" label="PERSONS.LOGIN_LABEL" [maxChars]="30" autocomplete="username"
                          mandatory [formField]="f.login" help="REGISTRATION.LOGIN_HELP" />
        <div class="row g-3 mb-3">
          <app-input-field class="col-sm-6" fieldId="password" type="password" label="PERSONS.PASSWORD_LABEL" [maxChars]="72"
                            autocomplete="new-password" mandatory [formField]="f.password" [params]="passwordParams()"
                            help="REGISTRATION.PASSWORD_HELP" />
          <app-input-field class="col-sm-6" fieldId="confirmation" type="password" label="ACCOUNT.CONFIRMATION_LABEL"
                            [maxChars]="72" autocomplete="new-password" mandatory [formField]="f.confirmation" />
        </div>
        <div class="d-flex gap-2">
          <button type="submit" class="btn btn-primary" [disabled]="f().submitting()">{{ 'REGISTRATION.SUBMIT' | translate }}</button>
          <a class="btn btn-secondary" routerLink="/login">{{ 'REGISTRATION.BACK_TO_LOGIN' | translate }}</a>
        </div>
      </form>
    </div>
  </div>
</div>
  • linha 7: título, nome, sobrenome;
  • linhas 10–17: nome de usuário, senha e confirmação da senha, desta vez obrigatórios (o atributo [mandatory] é apenas uma indicação: quem decide é o servidor).

10.4.9.7. src/app/pages/patient-area

// =========================================================================
// pages/patient-area/patient-area.ts - "My area" (/my-area, papel USER)
// -------------------------------------------------------------------------
// A página inicial do paciente, logo após o login:
//   - duas opções: [Manage my account] e [View a schedule];
//   - sua próxima consulta, se houver, com a opção de cancelá-la.
// Equivalente a views/patient/area.hbs da aplicação HTML.
// =========================================================================

import { Component, inject, signal } from '@angular/core';
import { RouterLink } from '@angular/router';
import { TranslatePipe } from '@ngx-translate/core';
import { RdvMedecinsApi } from '../../api/rdvmedecins.api';
import { MyArea } from '../../api/types';
import { TimeRangePipe, LongDatePipe, LabelPipe } from '../../pipes/formatting.pipes';
import { LanguageService } from '../../i18n/language.service';
import { MessagesService } from '../../services/messages.service';
import { ConfirmationService } from '../../services/confirmation.service';

@Component({
  selector: 'app-patient-area',
  imports: [RouterLink, TranslatePipe, TimeRangePipe, LongDatePipe, LabelPipe],
  templateUrl: './patient-area.html',
})
export default class PatientAreaPage {
  private readonly api = inject(RdvMedecinsApi);
  private readonly messages = inject(MessagesService);
  private readonly confirmation = inject(ConfirmationService);
  protected readonly language = inject(LanguageService).language;

  protected readonly area = signal<MyArea | null>(null);

  constructor() {
    this.load();
  }

  private async load(): Promise<void> {
    try {
      this.area.set(await this.api.myArea());
    } catch (e) {
      this.messages.showApiError(e);
    }
  }

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

A página inicial do paciente: duas opções ("Manage my account", "View a schedule") e sua próxima consulta, que ele pode cancelar (linhas 45–56).

@if (area(); as a) {
  <h4 class="mb-3">{{ 'AREA.HELLO' | translate: { name: (a.patient | label) } }}</h4>
  <div class="row g-3 mb-4">
    <div class="col-sm-6">
      <a class="card p-4 h-100 text-decoration-none option-card" routerLink="/my-account">
        <h5 class="mb-1">{{ 'AREA.MANAGE_ACCOUNT' | translate }}</h5>
        <span class="text-muted">{{ 'AREA.MANAGE_ACCOUNT_HELP' | translate }}</span>
      </a>
    </div>
    <div class="col-sm-6">
      <a class="card p-4 h-100 text-decoration-none option-card" routerLink="/schedule">
        <h5 class="mb-1">{{ 'AREA.VIEW_SCHEDULE' | translate }}</h5>
        <span class="text-muted">{{ 'AREA.VIEW_SCHEDULE_HELP' | translate }}</span>
      </a>
    </div>
  </div>

  <div class="card p-3">
    <h5>{{ 'AREA.MY_APPOINTMENT' | translate }}</h5>
    <!-- normalmente apenas uma (regra "uma consulta futura por vez"),
         mas a página pode exibir várias -->
    @for (appointment of a.appointments; track appointment.id; let last = $last) {
      <div class="d-flex flex-wrap justify-content-between align-items-center gap-2 py-2" [class.border-bottom]="!last">
        <div>
          <div class="fw-semibold">{{ appointment.day | longDate: language() }}, {{ appointment.slot | timeRange }}</div>
          <div class="text-muted">
            {{ appointment.doctor | label }} -
            <!-- a agenda do médico nesse dia: o paciente vê seu nome ali -->
            <a routerLink="/schedule" [queryParams]="{ doctorId: appointment.doctor.id, day: appointment.day }">{{ 'AREA.SEE_IN_SCHEDULE' | translate }}</a>
          </div>
        </div>
        <button type="button" class="btn btn-outline-danger" (click)="cancel(appointment.id)">{{ 'AREA.CANCEL_APPOINTMENT' | translate }}</button>
      </div>
    } @empty {
      <p class="text-muted mb-0">{{ 'AREA.NO_APPOINTMENT' | translate }}</p>
    }
  </div>
} @else {
  <p class="text-muted">{{ 'APP.LOADING' | translate }}</p>
}
  • linha 2: um parâmetro de tradução calculado por um pipe;
  • linha 22: [$last]: a última linha não tem borda;
  • linha 29: um link para a agenda do médico naquele dia.

10.4.9.8. src/app/pages/my-account

// =========================================================================
// pages/my-account/my-account.ts - "Manage my account" (/my-account, papel USER)
// -------------------------------------------------------------------------
// Dois formulários independentes, como views/patient/account.hbs:
//   1. a atualização (identidade, login, nova senha opcional);
//   2. a exclusão da conta - que também cancela suas consultas.
// Ambos exigem a senha ATUAL (verificada pelo servidor).
// Dois formulários, portanto dois modelos, duas árvores de campos e dois
// objetos FormSubmission (dois conjuntos de erros).
// =========================================================================

import { Component, inject, signal } from '@angular/core';
import { Router, RouterLink } from '@angular/router';
import { form, FormField } from '@angular/forms/signals';
import { TranslatePipe } from '@ngx-translate/core';
import { RdvMedecinsApi } from '../../api/rdvmedecins.api';
import { MyAccountUpdate } from '../../api/types';
import { SessionService } from '../../services/session.service';
import { MessagesService } from '../../services/messages.service';
import { ConfirmationService } from '../../services/confirmation.service';
import { FormSubmission } from '../../services/form-submission';
import { PersonFields } from '../../components/person-fields';
import { InputField } from '../../components/input-field';

@Component({
  selector: 'app-my-account',
  imports: [RouterLink, FormField, TranslatePipe, PersonFields, InputField],
  templateUrl: './my-account.html',
})
export default class MyAccountPage {
  private readonly api = inject(RdvMedecinsApi);
  private readonly session = inject(SessionService);
  private readonly messages = inject(MessagesService);
  private readonly confirmation = inject(ConfirmationService);
  private readonly router = inject(Router);

  // 1. a atualização
  protected readonly model = signal<MyAccountUpdate>({
    title: 'Mr',
    firstName: '',
    lastName: '',
    login: '',
    password: '',
    confirmation: '',
    currentPassword: '',
    version: 0,
  });
  protected readonly f = form(this.model);
  protected readonly update = new FormSubmission(this.f);

  // 2. a exclusão: um formulário com um único campo
  protected readonly deletionModel = signal({ currentPassword: '' });
  protected readonly fs = form(this.deletionModel);
  protected readonly deletion = new FormSubmission(this.fs);

  constructor() {
    this.load();
  }

  private async load(): Promise<void> {
    try {
      const account = await this.api.myAccount();
      this.model.update((m) => ({ ...m, ...account }));
    } catch (e) {
      this.messages.showApiError(e);
    }
  }

  protected async save(event: Event): Promise<void> {
    event.preventDefault();
    const succeeded = await this.update.submit(async () => {
      // o servidor emitiu um NOVO token (nome, login): a barra de
      // navegação deve acompanhar
      this.session.update(await this.api.editMyAccount(this.model()));
      this.messages.flash('success', 'MY_ACCOUNT.UPDATED');
    });
    if (succeeded) {
      this.router.navigate(['/my-area']);
    } else {
      // nunca uma senha deixada no campo após um envio rejeitado;
      // o próprio campo (e não o modelo) é alterado para não apagar
      // os erros que o servidor acabou de associar a ele... exceto o seu próprio
      this.f.currentPassword().value.set('');
    }
  }

  protected async deleteAccount(event: Event): Promise<void> {
    event.preventDefault();
    if (!(await this.confirmation.confirm('MY_ACCOUNT.DELETE_CONFIRM'))) {
      return;
    }
    const succeeded = await this.deletion.submit(() => this.api.deleteMyAccount(this.deletionModel().currentPassword));
    if (succeeded) {
      this.session.forget(); // o servidor limpou o cookie do token
      this.messages.flash('success', 'MY_ACCOUNT.DELETED');
      this.router.navigate(['/login']);
    }
  }
}

Dois formulários independentes: modificação da conta e exclusão da conta. Ambos exigem a senha atual, que é verificada pelo servidor. Dois formulários, portanto dois modelos, duas árvores de campos e dois [FormSubmission]: os erros de um não aparecem no outro.

  • Linhas 60–67: a conta é lida e seus valores são copiados para o modelo (inclusive a versão);
  • linha 74: após uma alteração, o servidor retorna o usuário atualizado (e emitiu um novo token): a barra de navegação deve se atualizar de acordo;
  • Linha 83: após um envio rejeitado, a senha atual é limpa. Atualizamos o campo (e não o formulário inteiro): apenas o erro desse campo desaparece; os outros permanecem exibidos;
  • linhas 87–98: exclusão da conta, após confirmação. O servidor excluiu o cookie do token: o usuário é esquecido e a página volta para a página de login.
<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">{{ 'MY_ACCOUNT.TITLE' | translate }}</h5>
      <form novalidate (submit)="save($event)">
        <app-person-fields [title]="f.title" [firstName]="f.firstName" [lastName]="f.lastName" />

        <h6 class="mt-4 text-muted">{{ 'PERSONS.ACCOUNT_SECTION' | translate }}</h6>
        <app-input-field class="mb-3" fieldId="login" label="PERSONS.LOGIN_LABEL" [maxChars]="30" autocomplete="username"
                          mandatory [formField]="f.login" />
        <div class="row g-3 mb-3">
          <app-input-field class="col-sm-6" fieldId="password" type="password" label="MY_ACCOUNT.NEW_PASSWORD_LABEL"
                            [maxChars]="72" autocomplete="new-password" [formField]="f.password"
                            [params]="update.params()" help="PERSONS.PASSWORD_HELP_EDIT" />
          <app-input-field class="col-sm-6" fieldId="confirmation" type="password" label="ACCOUNT.CONFIRMATION_LABEL"
                            [maxChars]="72" autocomplete="new-password" [formField]="f.confirmation" />
        </div>
        <app-input-field class="mb-4" fieldId="currentPassword" type="password" label="MY_ACCOUNT.CURRENT_PASSWORD_LABEL"
                          [maxChars]="72" autocomplete="current-password" mandatory [formField]="f.currentPassword"
                          help="MY_ACCOUNT.CURRENT_PASSWORD_HELP" />
        <div class="d-flex gap-2">
          <button type="submit" class="btn btn-primary" [disabled]="f().submitting()">{{ 'PERSONS.SAVE' | translate }}</button>
          <a class="btn btn-secondary" routerLink="/my-area">{{ 'MY_ACCOUNT.BACK' | translate }}</a>
        </div>
      </form>
    </div>

    <!-- 2. exclusão -->
    <div class="card p-4 border-danger">
      <h5 class="card-title text-danger mb-1">{{ 'MY_ACCOUNT.DELETE_TITLE' | translate }}</h5>
      <p class="text-muted small">{{ 'MY_ACCOUNT.DELETE_HELP' | translate }}</p>
      <form class="d-flex flex-wrap gap-2 align-items-end" novalidate (submit)="deleteAccount($event)">
        <app-input-field class="flex-grow-1" fieldId="deletePassword" type="password" label="MY_ACCOUNT.CURRENT_PASSWORD_LABEL"
                          [maxChars]="72" autocomplete="current-password" mandatory [formField]="fs.currentPassword" />
        <button type="submit" class="btn btn-danger" [disabled]="fs().submitting()">{{ 'MY_ACCOUNT.DELETE_SUBMIT' | translate }}</button>
      </form>
    </div>
  </div>
</div>

10.4.9.9. src/app/pages/error/error.ts

// =========================================================================
// pages/error/error.ts - a página de erro: 404 (endereço desconhecido) ou 403
// (papel insuficiente, veja guards.ts). Equivalente a views/error.hbs.
// O código chega como input, a partir dos dados da rota (data.code).
// =========================================================================

import { Component, computed, input } from '@angular/core';
import { RouterLink } from '@angular/router';
import { TranslatePipe } from '@ngx-translate/core';

@Component({
  selector: 'app-error',
  imports: [RouterLink, TranslatePipe],
  template: `
    <div class="card p-4">
      <h4 class="text-danger">{{ 'ERROR_PAGE.TITLE' | translate }} {{ code() }}</h4>
      <p>{{ message() | translate }}</p>
      <a routerLink="/" class="btn btn-primary align-self-start">{{ 'ERROR_PAGE.BACK' | translate }}</a>
    </div>
  `,
})
export default class ErrorPage {
  readonly code = input.required<403 | 404>();
  protected readonly message = computed(() => (this.code() === 403 ? 'ERRORS.FORBIDDEN' : 'ERRORS.NOT_FOUND'));
}

A página de erro, 403 ou 404: o código é repassado como input a partir dos dados da rota ([data.code]).