Skip to content

10. 案例研究:RdvMedecins 应用程序的 Angular 客户端

10.1. 问题描述

[RdvMedecins]应用程序允许用户在医生诊所预约。[NestJS]课程将其编写为 HTML 应用程序,由服务器生成页面。这里我们编写的是[Angular]客户端:同样的页面,由浏览器根据服务器上的 JSON 数据生成,该服务器在“RdvMedecins 服务器:一个黑盒”一章中有所描述。

客户端必须提供 HTML 应用程序所提供的一切:

  • 受验证码(CAPTCHA)保护的登录页面,并可创建患者账户;
  • 某位医生某一天的日程,支持预约(患者选择窗口)和取消;
  • 对于管理员:医生和客户的管理(列表、添加、编辑、删除);
  • 对于患者:个人仪表板(显示即将到来的预约,可以取消)和账户管理;
  • 两种语言:法语和英语;
  • 唯一的 URL([/schedule?doctorId=1&day=...]),可以重新加载、添加书签,并可使用浏览器的“后退/前进”按钮进行导航。

10.2. 安装与运行

必须安装并运行 JSON 服务器(参见“RdvMedecins 服务器:一个黑盒”一章)。在浏览器中使用该客户端时,无需验证码测试模式:可以在服务器的[.env]文件中将[CAPTCHA_TEST]字段留空。

在打开到[rdvmedecins-angular]文件夹的控制台窗口中:

npm install
npm start

然后在浏览器中打开 http://localhost:4200。演示账户列在登录页面上(密码 = 登录名)。

各示例同样使用 4200 端口:首先停止当前正在运行的示例([Ctrl-C])。也可以在其他端口上启动客户端:[npm start -- --port 4300]。

10.3. 使用应用程序

10.3.1. 登录页面

Image

密码错误:页面底部会出现一条消息,并显示一张新图片(每张图片只能使用一次):

Image

10.3.2. 管理员和医生所见的日历

以[admin]身份登录后,会进入日历页面:

Image

选择一位医生和一个日期,然后点击“查看日程”。URL 变为[/schedule?doctorId=1&day=2026-10-05]:

Image

“预约”会打开预约窗口。URL 变为[/schedule?doctorId=1&day=2026-10-05&book=3]:重新加载页面(F5)会重新打开同一个窗口。

Image

预约已保存:

Image

“取消”会提示确认:

Image

医生直接进入他自己的当日日程:

Image

10.3.3. 患者门户

一位患者([martin])进入“我的空间”:

Image

在日历中,他们会在其他患者的预约时段旁看到“已预约”:

Image

他们无需选择患者,即可为自己预约:

Image

他的预约显示在他的名下;“预约”按钮不再可用(只允许一个即将到来的预约),并有一条消息说明原因:

Image

他的仪表板显示如下内容:

Image

“管理我的账户”:任何更改都需要当前密码;这些错误来自服务器端:

Image

如果他输入保留给管理员的地址 /doctors:

Image

10.3.4. 管理医生和客户

Image

填写不正确的输入:

Image

添加成功:

Image

同名同姓:

Image

删除一位已有预约安排的医生的请求被拒绝:

Image

10.3.5. 创建账户

在登录页面上,输入验证码,然后点击“创建患者账户”。填写不正确的表单随后被服务器拒绝:

Image

账户创建后,返回登录页面;登录字段已被预先填好:

Image

10.3.6. 法语界面

FR / EN 按钮可当场翻译页面,无需向服务器发出任何请求;浏览器标签页标题也会被翻译:

Image

10.3.7. 会话过期,未知地址

如果令牌过期(或 Cookie 被删除),下一次请求会收到 401 响应;客户端被重定向到登录页面:

Image

未知地址:

Image

10.4. 客户端架构

rdvmedecins-angular/
├── angular.json, package.json, tsconfig.json, proxy.conf.json
├── public/favicon.svg                标签页图标
└── src/
    ├── index.html                    应用程序的唯一页面
    ├── main.ts                       启动
    ├── styles.css
    └── app/
        ├── app.config.ts             应用程序的配置
        ├── app.ts                    所有页面共享的布局
        ├── app.routes.ts             页面及其访问权限
        ├── guards.ts                 路由守卫
        ├── api/                      API 访问层
        ├── i18n/                     语言
        ├── services/                 会话、消息、确认、表单
        ├── pipes/                    格式化
        ├── components/               可复用组件
        └── pages/                    页面

Image

下表将[NestJS]课程中的 HTML 应用程序与本客户端进行了对比:

HTML 应用程序(NestJS)
Angular 客户端
服务器生成每个页面([res.render])
服务器返回 JSON;[src/app/pages/] 中的组件生成页面
[views/layout.hbs] 及其局部视图
[app.ts] 以及[src/app/components/]中的组件
控制器路由([@Get('my-area')])
客户端路由([app.routes.ts]);服务器只有 /api/... 路由
[JwtAuthGuard] 和 [RolesGuard] 重定向到 /login 或 403 页面
路由器守卫;服务器保留自己的守卫,返回 401 或 403
存放在 Cookie 中的闪现消息
存放在服务中的闪现消息,[MessagesService]
由服务器读取的字典,辅助函数 [{{t}}]
客户端中的字典,[ngx-translate];服务器只返回键
语言存放在 Cookie 中
语言存放在[localStorage]中
表单被拒绝:服务器重新加载页面
表单被拒绝:400/409 响应;客户端在字段下方显示错误
确认窗口:一个小脚本,[public/js/app.js]
一个服务和一个组件,[ConfirmDialog]
应用程序无需 JavaScript 即可运行
应用程序本身就是 JavaScript

上一课中的[Vue.js] 客户端具有完全相同的结构:“store”([Pinia])变成了服务,“组合式函数”变成了服务或函数,视图变成了页面。

客户端的所有文件都显示在下方。它们带有大量注释;这些注释是课程的一部分。

10.4.1. 项目配置

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"
  }
}
  • 第 8–9 行:[npm start] 启动开发服务器;[npm run build] 构建生产版本;
  • 第 11–22 行:应用程序使用的库:[Angular]、[ngx-translate]、[Bootstrap]和[RxJS]的库;
  • 第 23–28 行:开发工具:[Angular]编译器、[ng]命令和[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"
        }
      }
    }
  }
}

这次只有一个项目,位于文件夹根目录(第 11 行):

  • 第 18 行:应用程序的入口点;
  • 第 20 行:[public]文件夹的内容会原样复制到构建后的应用程序中(图标);
  • 第 21 行:全局样式表:先是[Bootstrap]的样式表,然后是我们自己的;
  • 第 24–30 行:生产配置。如果应用程序超出指定的大小,budgets 会触发警告(或错误);[outputHashing] 会在每个文件的名称中添加内容指纹(参见“部署”一章);
  • 第 37 行:[ng build] 默认构建生产版本;
  • 第 42 行:开发服务器代理;
  • 第 48 行:[ng serve] 使用开发配置(未优化的代码,供调试器使用的“source maps”)。

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"
    }
  ]
}
  • 第 3 行:[TypeScript]的严格模式;
  • 第 14 行:JSON 文件(字典)的导入;
  • 第 21 行:[Angular]编译器还会检查模板中的类型。
1
2
3
4
{
  "extends": "./tsconfig.json",
  "include": ["src/**/*.ts"]
}
1
2
3
4
5
6
{
  "/api": {
    "target": "http://localhost:8080",
    "secure": false
  }
}

示例 22 中的代理:/api/... 请求被转发到 JSON 服务器。

10.4.2. 启动应用程序

10.4.2.1. index.html

<!doctype html>
<!--
  index.html - 应用程序的页面(单页应用)。
  服务器从不发送其他页面:其余一切都由 Angular 在
  浏览器中的 <app-root> 内构建。lang 和 title 由应用程序
  根据语言和显示的页面更新。
-->
<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>
  <!-- 没有 JavaScript,Angular 应用什么也无法显示:我们对此作出提示 -->
  <noscript>RdvMedecins requires JavaScript. / RdvMedecins a besoin de JavaScript.</noscript>
</body>
</html>
  • 第 17 行:[Angular] 显示根组件的元素;
  • 第 19 行:没有 [JavaScript],[Angular] 应用程序就无法显示任何内容:我们对此作出提示。

10.4.2.2. src/main.ts

// =========================================================================
// main.ts - 应用的启动
// -------------------------------------------------------------------------
// 根组件(App)和应用的配置
// (app.config.ts)。样式表(Bootstrap、styles.css)在
// 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 - 应用的配置
// -------------------------------------------------------------------------
//   - 路由器、它的路由(app.routes.ts)、传递给页面输入的
//     路由参数,以及翻译后的标签页标题;
//   - HttpClient,带有错误拦截器和 401 拦截器;
//   - ngx-translate(法语和英语)。
// =========================================================================

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: [
    // 未处理的错误会报告到浏览器控制台
    provideBrowserGlobalErrorListeners(),
    provideRouter(routes, withComponentInputBinding()),
    { provide: TitleStrategy, useClass: TranslatedTitle },
    provideHttpClient(withInterceptors([apiInterceptor])),
    provideI18n(),
  ],
};
  • 第 21 行:未处理的错误(例如没有人等待的被拒绝的 promise)会报告到浏览器控制台;
  • 第 22 行:路由器,路由参数会传递给页面的输入(示例 17);
  • 第 23 行:[TitleStrategy] 是在每次导航后设置标签页标题的路由器服务。我们用自己的服务(替换[Angular] 自带的那个[i18n/title.strategy.ts]),它会翻译标题。这正是依赖注入的意义所在:你可以用自己的类替换框架的类,而无需改动其他任何内容;
  • 第 24 行:HTTP 客户端,带有我们的拦截器;
  • 第 25 行:[ngx-translate]。

10.4.2.4. src/app/app.ts

// =========================================================================
// app.ts - 根组件:所有页面共用的布局
// -------------------------------------------------------------------------
// 相当于 HTML 应用的 views/layout.hbs:
//   - 导航栏;
//   - 顶部的成功消息;
//   - 当前页面(<router-outlet>);
//   - 底部的错误面板;
//   - 确认对话框,整个应用只有一个。
// =========================================================================

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 {}
  • 第 22–30 行:所有页面共用的模板:导航栏、成功消息、当前页面、错误区域和确认窗口(示例 16)。

10.4.2.5. src/styles.css

/* =========================================================================
   styles.css - 在 Bootstrap 之上的少量设置
   (取自 HTML 应用程序的 public/css/styles.css)
   ========================================================================= */

body {
  background-color: #f5f7fa;
}

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

/* -------------------------------------------------------------------------
   .error-panel:错误消息,位于页面底部,浅粉色
   背景(参见 components/error-panel.ts)。
   position: sticky + bottom:如果页面比窗口高,
   面板会固定在窗口底部,而不是消失在
   可视区域以下——并且在页面较短时
   绝不会遮挡内容。z-index:高于模态对话框的灰色背景。
   pointer-events: none:面板中没有任何可点击的内容;如果它
   与某个按钮重叠,点击会穿透它。
   ------------------------------------------------------------------------- */
.error-panel {
  position: sticky;
  bottom: 1rem;
  z-index: 1060;
  pointer-events: none;
  margin-top: 1.5rem;
  padding: 0.75rem 1rem;
  background-color: #fdecef; /* 浅粉色 */
  border: 1px solid #f5c2c7;
  border-radius: 0.375rem;
  color: #842029;
}

/* 患者“我的空间”页面的两个大选项 */
.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);
}

/* 验证码图片(150 x 50 像素的 SVG),由 [innerHTML] 插入:
   只有像这样的全局样式才能作用于它 */
.captcha-image svg {
  display: block;
  border: 1px solid #dee2e6;
  border-radius: 0.375rem;
}
  • 第 24–35 行:页面底部的错误区域;
  • 第 49–53 行:验证码图像。与示例 24 中一样,由[<svg>] 通过[[innerHTML]] 插入的内容只能通过全局样式来设置样式。

10.4.3. API 访问层

10.4.3.1. src/app/api/types.ts

// =========================================================================
// api/types.ts - 与服务器交换的 JSON 对象
// -------------------------------------------------------------------------
// 把“服务器,一个黑盒”一章中描述的 API 翻译成
// TypeScript 接口。这样编译器就能检查客户端
// 只使用真正存在的字段。
// =========================================================================

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; // 显示名称:"Marie PELISSIER"
  role: Role;
}

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

// 称谓、名、姓
export interface Identity {
  title: string;
  firstName: string;
  lastName: string;
}

// 医生或客户端:GET /api/doctors, GET /api/clients/:id...
export interface Person extends Identity {
  id: number;
  version: number; // 乐观锁:更新时需要发回
  login?: string; // 仅限 ADMIN
}

// 创建 / 更新一个人时发送的内容(ADMIN)
export interface PersonData extends Identity {
  login: string; // '' = 默认值(创建)或保持不变(更新)
  password: string; // 同上
  version?: number;
}

export interface Slot {
  id: number;
  startHour: number;
  startMinute: number;
  endHour: number;
  endMinute: number;
}

// 日程的一行,带有已登录用户的权限
export interface ScheduleSlot extends Slot {
  free: boolean;
  patient: Identity | null; // null:空闲,或被其他患者预约
  mine: boolean; // 已登录患者的预约
  bookable: boolean;
  appointmentId: number | null; // 如果用户可以取消则设置
}

// GET /api/schedule?doctorId=...&day=...
export interface Schedule {
  doctor: Person;
  day: string; // "yyyy-MM-dd"
  slots: ScheduleSlot[];
  info: string | null; // 翻译键(已有预约的患者)
}

// 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; // '' = 保持不变
  confirmation: string;
  currentPassword: string;
  version: number;
}

// POST /api/register
export interface Registration extends Identity {
  login: string;
  password: string;
  confirmation: string;
}

将“RdvMedecins 服务器,一个黑盒”一章中描述的 API 翻译为[TypeScript]接口。关键字[extends] 可避免重复公共字段:[Person] 是一个 [Identity](称谓、名、姓)外加一个标识符和一个版本。

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

// =========================================================================
// api/api-error.ts - 用一个类处理 API 的所有错误
// -------------------------------------------------------------------------
// 取自示例的 common/api-error.ts。请求的任何错误
// (服务器的 4xx / 5xx 响应、服务器不可达、代理的响应)
// 都会变成 ApiError,它携带消息的翻译 KEY、
// 消息参数,以及被拒绝表单中每个字段的错误。
// =========================================================================

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

export class ApiError extends Error {
  constructor(
    public readonly statusCode: number, // 0:服务器没有响应
    public readonly key: string, // 翻译键:'ERRORS.LOGIN_TAKEN'
    public readonly params: Record<string, string> = {},
    public readonly fields: Record<string, string> = {}, // 每个字段的错误
  ) {
    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,
    // 没有 key:响应的不是我们的服务器,而是网络
    // 或代理(ng serve:无请求体的 500;nginx:502、504...)
    body.key ?? (e.status === 0 || e.status >= 500 ? 'ERRORS.SERVER_UNREACHABLE' : 'ERRORS.SERVER_ERROR'),
    body.params,
    body.fields,
  );
}

示例 24 中的[common/api-error.ts]文件。

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

// =========================================================================
// api/api.interceptor.ts - 所有 API 请求的拦截器
// -------------------------------------------------------------------------
// 取自示例的 common/errors.interceptor.ts,并增加了新内容:
// 对 401 响应的集中处理。
//
// 401 可能随时出现:令牌已过期(2 小时)、
// 账户已被删除、服务器用另一个密钥重新启动了……
// 与其在每个组件中处理这种情况,不如
// 在这里统一处理一次:忘记该用户,准备好
// “会话已过期”消息,并返回登录页面。
//
// 有些请求自己处理 401(登录、GET
// /api/auth/me...):它们通过一个上下文令牌
// (HttpContextToken)来声明,这是附加在请求上的一条信息,
// 由拦截器读取(参见 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:该请求自己处理可能出现的 401(默认为 false)
export const IGNORE_401 = new HttpContextToken<boolean>(() => false);

export const apiInterceptor: HttpInterceptorFn = (req, next) => {
  // inject:需要用到的服务(在拦截器的注入上下文中,
  // 请求发送之前)
  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);
    }),
  );
};

示例 24 中的拦截器,增加了一项新功能:对 401 响应的集中式处理。401 可能随时出现:令牌已过期、账户已被删除……与其在每个页面上处理这种情况,不如在这里统一处理一次。

  • 第 28 行:一个上下文令牌 ([HttpContextToken])——附加在请求上、拦截器可以读取的信息。默认情况下,其值为[false];
  • 第 33–35 行:拦截器注入它将需要的服务。[inject] 必须在函数开头调用:稍后在[catchError]中,注入上下文已不复存在;
  • 第 39 行:任何错误都会变成[ApiError];
  • 第 40–44 行:对于自身不处理 401 的请求,遇到 401 响应时:用户被遗忘,准备好“会话已过期”消息(将在下一页显示),并将用户重定向到登录页面;
  • 第 45 行:无论何种情况,错误都会传递给发出该请求的代码。

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

// =========================================================================
// api/rdvmedecins.api.ts - API 的每条路由对应一个方法
// -------------------------------------------------------------------------
// 客户端的“数据访问层”:组件调用这些带类型的
// 方法,而对 URL、HttpClient 或 JSON 一无所知。如果
// API 发生变化,只需修改这个文件。
// 每个方法返回一个 PROMISE(firstValueFrom):组件
// 用 async / await 串联请求。失败时,promise
// 以 ApiError 被拒绝(参见 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 或 /api/clients:两者的处理方式相同
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);

  // 请求本身;isPublic:对于自己处理 401 的路由为 true
  // (公开路由、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),
      }),
    );
  }

  // ------------------------------------------------ 登录(公开路由)
  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);
  }

  // ------------------------------------------------ 创建账户(公开)
  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);
  }

  // ------------------------------------------------ 日程和预约
  // doctorId 为 null:对已登录的医生,表示他/她自己的日程
  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}`);
  }

  // ------------------------------------------------ 医生和客户
  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}`);
  }

  // ------------------------------------------------ 患者的空间
  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 });
  }
}

API 访问层:每个路由对应一个方法。

  • 第 40–48 行:由一个方法处理所有请求。[http.request] 接受 HTTP 方法作为参数;[firstValueFrom] 将其转换为 promise;
  • 第 45 行:请求携带上下文令牌[IGNORE_401]:对于自行处理 401 的路由为 true。密码错误会返回 401:这并不是会话过期!同样,当没有人登录时,[GET /api/auth/me] 会返回 401,这是正常的;
  • 第 77–83 行:[HttpParams] 生成 URL 参数(?day=...&doctorId=...)。[HttpParams] 对象不会改变:[set] 返回一个新对象;
  • 第 85 行:[clientId ?? undefined]:如果缺少 [clientId],则根本不发送它;
  • 第 92–106 行:医生和客户的处理方式相同:类型(['doctors'] 或 ['clients'])是地址的一部分;
  • 第 119 行:带有包含当前密码的请求体的 DELETE,删除账户时必须提供。

10.4.4. 语言

10.4.4.1. src/app/i18n/i18n.ts

// =========================================================================
// i18n/i18n.ts - 法语和英语(ngx-translate,参见示例 21)
// -------------------------------------------------------------------------
// fr.json 和 en.json 字典来自 NestJS 课程
// (i18n/*.json),并补充了少量客户端特有的键
// (ERRORS.SERVER_UNREACHABLE...)。JSON 服务器只返回 KEY
// ('ERRORS.LOGIN_TAKEN'):它们与字典中的键相同。
//
// 所选语言存储在 localStorage 中(这是偏好设置,不是
// 敏感数据);若没有,则使用浏览器的语言。
// =========================================================================

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

// 字典是应用代码的一部分:不发起请求
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 不可用(严格的隐私浏览模式等):无所谓
  }
  return navigator.language.toLowerCase().startsWith('fr') ? 'fr' : 'en';
}

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

示例 21 中的[ngx-translate] 配置:

  • 第 30–40 行:源语言是用户最后选择的语言;否则,如果浏览器语言是法语则使用法语,其他情况则使用英语。访问[localStorage] 可能会失败(在某些隐私浏览模式下),因此在这种情况下我们跳过它。

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

// =========================================================================
// i18n/language.service.ts - 当前语言,以及切换语言的方式
// =========================================================================

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);
  // 一个信号:'fr' 或 'en'
  readonly language = this.translate.currentLang;

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

  // 切换语言:整个应用会立即重新翻译
  change(language: Language): void {
    this.translate.use(language);
    document.documentElement.lang = language;
    try {
      localStorage.setItem(STORAGE_KEY, language);
    } catch {
      // 无关紧要
    }
  }
}
  • 第 13 行:当前语言,一个信号;
  • 第 20–28 行:切换语言:页面被重新翻译(第 21 行),页面的[lang]属性被更新(第 22 行),所选语言被保存(第 24 行)。

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

// =========================================================================
// i18n/title.strategy.ts - 翻译后的标签页标题
// -------------------------------------------------------------------------
// 每条路由都声明一个标题(title: 'SCHEDULE.PAGE_TITLE',参见
// app.routes.ts)。默认情况下,Angular 会原样写入标签页。
// TitleStrategy 取代了这一行为:每次导航之后
// 都会调用 updateTitle();buildTitle() 给出所显示路由的标题
// (这里是一个 key),我们对它进行翻译。而当语言变化时,
// 最近一次的标题会被重新翻译。
// 该类在 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);
  }
}

每个路由都会声明一个标题,这里它是一个翻译键('SCHEDULE.PAGE_TITLE')。默认情况下,[Angular] 会将其原样写入标签页。这个类取代了路由器的[TitleStrategy]服务(app.config.ts,第 23 行):

  • 第 20 行:它继承了[TitleStrategy]类,该类来自[Angular];
  • 第 30–33 行:[updateTitle] 由路由器在每次导航后调用;[buildTitle]是继承而来的,提供所显示路由声明的标题;
  • 第 35–38 行:翻译后的标题,后面跟着应用程序名称:“Schedule - RdvMedecins”;
  • 第 27 行:当语言改变时,最后一个标题会被重新翻译。

10.4.4.4. 字典

字典[fr.json] 和[en.json] 来自[NestJS]课程中的 HTML 应用程序,并补充了一些客户端专用的键([ERRORS.SERVER_UNREACHABLE]……)。只有其参数语法有所变化:[{{min}}] 用于[ngx-translate]。JSON 服务器返回相同的键。

{
  "APP": {
    "TITLE": "RdvMedecins",
    "LOGOUT": "Se déconnecter",
    "MENU_SCHEDULE": "Agenda",
    "MENU_DOCTORS": "Médecins",
    "MENU_PATIENTS": "Clients",
    "MENU_MY_AREA": "Mon espace",
    "LOADING": "Chargement...",
    "LANGUAGE": "Langue"
  },
  "LOGIN": {
    "TITLE": "Connexion",
    "LOGIN_LABEL": "Login",
    "PASSWORD_LABEL": "Mot de passe",
    "SUBMIT": "Se connecter",
    "ERROR": "Login ou mot de passe incorrect.",
    "DEMO_ACCOUNTS": "Comptes de démonstration (mot de passe = login) :",
    "DEMO_ADMIN": "rôle ADMIN : rendez-vous + gestion des médecins et des clients",
    "DEMO_DOCTOR": "rôle DOCTOR : prise et annulation de rendez-vous",
    "DEMO_USER": "rôle USER (patients) : réservation pour eux-mêmes, gestion de leur compte",
    "CREATE_ACCOUNT": "Créer un compte client",
    "CREATE_ACCOUNT_HELP": "Pour créer un compte, recopiez d'abord les caractères de l'image."
  },
  "DOCTOR_DAY_PICKER": {
    "DOCTOR_LABEL": "Médecin",
    "CHOOSE_DOCTOR": "-- choisir un médecin --",
    "DAY_LABEL": "Jour",
    "VIEW_SCHEDULE": "Voir l'agenda"
  },
  "SCHEDULE": {
    "PAGE_TITLE": "Agenda",
    "TITLE_PREFIX": "Agenda du",
    "COLUMN_SLOT": "Créneau",
    "COLUMN_STATUS": "Statut",
    "FREE": "Libre",
    "BOOK": "Réserver",
    "CANCEL_APPOINTMENT": "Annuler",
    "CANCEL_CONFIRM": "Annuler ce rendez-vous ?",
    "EMPTY_STATE": "Choisissez un médecin et un jour, puis cliquez sur « Voir l'agenda ».",
    "NO_SLOTS": "Ce médecin n'a aucun créneau horaire.",
    "BOOKED": "Rendez-vous enregistré.",
    "CANCELLED": "Rendez-vous annulé.",
    "BOOKED_BY_OTHER": "Réservé",
    "ALREADY_BOOKED_INFO": "Vous avez déjà un rendez-vous à venir : annulez-le pour en prendre un autre."
  },
  "BOOKING_DIALOG": {
    "TITLE": "Réserver ce créneau",
    "CLOSE_ARIA": "Fermer",
    "SLOT": "Créneau de {{time}}",
    "PATIENT_LABEL": "Patient",
    "CHOOSE_PATIENT": "-- choisir un patient --",
    "CANCEL": "Annuler",
    "CONFIRM": "Confirmer"
  },
  "PERSONS": {
    "COLUMN_TITLE": "Titre",
    "COLUMN_FIRSTNAME": "Prénom",
    "COLUMN_LASTNAME": "Nom",
    "COLUMN_LOGIN": "Login",
    "EDIT": "Modifier",
    "DELETE": "Supprimer",
    "SAVE": "Enregistrer",
    "BACK": "Retour à la liste",
    "TITLE_LABEL": "Titre",
    "FIRSTNAME_LABEL": "Prénom",
    "LASTNAME_LABEL": "Nom",
    "LOGIN_LABEL": "Login",
    "PASSWORD_LABEL": "Mot de passe",
    "LOGIN_HELP_CREATE": "Facultatif : par défaut, le nom en minuscules.",
    "LOGIN_HELP_EDIT": "Laisser vide pour ne pas le changer.",
    "PASSWORD_HELP_CREATE": "Facultatif : par défaut, identique au login.",
    "PASSWORD_HELP_EDIT": "Laisser vide pour ne pas le changer.",
    "ACCOUNT_SECTION": "Compte utilisateur"
  },
  "DOCTORS": {
    "TITLE": "Médecins",
    "ADD": "Ajouter un médecin",
    "EDIT": "Modifier un médecin",
    "EMPTY": "Aucun médecin.",
    "DELETE_CONFIRM": "Supprimer ce médecin, ses créneaux horaires et son compte utilisateur ?",
    "ADDED": "Le médecin {{name}} a été ajouté (login : {{login}}).",
    "UPDATED": "Le médecin {{name}} a été modifié.",
    "DELETED": "Le médecin {{name}} a été supprimé."
  },
  "CLIENTS": {
    "TITLE": "Clients",
    "ADD": "Ajouter un client",
    "EDIT": "Modifier un client",
    "EMPTY": "Aucun client.",
    "DELETE_CONFIRM": "Supprimer ce client, son compte utilisateur et tous ses rendez-vous ?",
    "ADDED": "Le client {{name}} a été ajouté (login : {{login}}).",
    "UPDATED": "Le client {{name}} a été modifié.",
    "DELETED": "Le client {{name}} a été supprimé."
  },
  "ERROR_PAGE": {
    "TITLE": "Erreur",
    "BACK": "Retour à l'accueil"
  },
  "ERRORS": {
    "LOGIN_TAKEN": "Ce login est déjà utilisé par un autre compte.",
    "DOCTOR_ALREADY_EXISTS": "Un médecin portant ce prénom et ce nom existe déjà.",
    "PATIENT_ALREADY_EXISTS": "Un client portant ce prénom et ce nom existe déjà.",
    "DOCTOR_HAS_APPOINTMENTS": "Ce médecin a des rendez-vous : annulez-les avant de le supprimer.",
    "SLOT_ALREADY_BOOKED": "Ce créneau vient d'être réservé par quelqu'un d'autre.",
    "CONCURRENT_UPDATE": "Cette fiche a été modifiée entre-temps par un autre utilisateur. Revenez à la liste et rouvrez-la avant de recommencer.",
    "DOCTOR_NOT_FOUND": "Ce médecin n'existe pas (ou plus).",
    "PATIENT_NOT_FOUND": "Ce client n'existe pas (ou plus).",
    "SLOT_NOT_FOUND": "Ce créneau n'existe pas (ou plus).",
    "APPOINTMENT_NOT_FOUND": "Ce rendez-vous n'existe pas (ou plus).",
    "INVALID_DATE": "La date demandée n'est pas valide.",
    "CHOOSE_PATIENT": "Choisissez un patient.",
    "INVALID_FORM": "Le formulaire contient des erreurs.",
    "INVALID_TITLE": "Choisissez un titre dans la liste.",
    "FIRSTNAME_REQUIRED": "Le prénom est obligatoire.",
    "FIRSTNAME_TOO_LONG": "Le prénom ne doit pas dépasser 20 caractères.",
    "LASTNAME_REQUIRED": "Le nom est obligatoire.",
    "LASTNAME_TOO_LONG": "Le nom ne doit pas dépasser 20 caractères.",
    "INVALID_LOGIN": "30 caractères au plus : lettres minuscules non accentuées, chiffres, point, tiret, souligné.",
    "PASSWORD_TOO_LONG": "Le mot de passe ne doit pas dépasser 72 caractères.",
    "SESSION_EXPIRED": "Votre session a expiré : reconnectez-vous.",
    "BAD_REQUEST": "La requête est invalide.",
    "FORBIDDEN": "Votre rôle ne vous permet pas d'accéder à cette page.",
    "NOT_FOUND": "Cette page n'existe pas.",
    "SERVER_ERROR": "Une erreur inattendue s'est produite. Réessayez plus tard.",
    "TOO_MANY_ATTEMPTS": "Trop de tentatives infructueuses. Réessayez dans {{minutes}} minute(s).",
    "WRONG_CAPTCHA": "Les caractères recopiés ne correspondent pas à l'image. Une nouvelle image vous est proposée.",
    "TOO_MANY_ACCOUNTS": "Trop de comptes ont été créés depuis votre connexion. Réessayez dans {{minutes}} minute(s).",
    "LOGIN_REQUIRED": "Le login est obligatoire.",
    "PASSWORD_REQUIRED": "Le mot de passe est obligatoire.",
    "PASSWORD_TOO_SHORT": "Le mot de passe doit comporter au moins {{min}} caractères.",
    "CONFIRMATION_REQUIRED": "Confirmez le mot de passe.",
    "PASSWORDS_DIFFER": "La confirmation ne correspond pas au mot de passe.",
    "CURRENT_PASSWORD_REQUIRED": "Saisissez votre mot de passe actuel.",
    "WRONG_CURRENT_PASSWORD": "Mot de passe actuel incorrect.",
    "PAST_DATE": "On ne peut pas prendre de rendez-vous à une date passée.",
    "PATIENT_HAS_UPCOMING_APPOINTMENT": "Ce patient a déjà un rendez-vous à venir : il faut l'annuler avant d'en prendre un autre.",
    "CAPTCHA_BEFORE_ACCOUNT": "Pour créer un compte, recopiez d'abord correctement les caractères de l'image, puis cliquez sur « Créer un compte client ».",
    "AUTH_REQUIRED": "Connectez-vous pour accéder à cette page.",
    "JSON_REQUIRED": "Requête refusée : le serveur attend du JSON.",
    "SERVER_UNREACHABLE": "Le serveur ne répond pas. Réessayez plus tard."
  },
  "CAPTCHA": {
    "LABEL": "Recopiez les caractères de l'image",
    "IMAGE_ALT": "Image de vérification anti-robots",
    "NEW_IMAGE": "Autre image",
    "HELP": "Majuscules ou minuscules, peu importe."
  },
  "REGISTRATION": {
    "TITLE": "Créer un compte client",
    "INTRO": "Ce compte vous permettra de prendre vous-même vos rendez-vous.",
    "LOGIN_HELP": "Lettres minuscules non accentuées, chiffres, point, tiret, souligné.",
    "PASSWORD_HELP": "Au moins {{min}} caractères.",
    "SUBMIT": "Créer mon compte",
    "BACK_TO_LOGIN": "Retour à la connexion",
    "DONE": "Votre compte a été créé. Vous pouvez vous connecter avec le login {{login}}."
  },
  "ACCOUNT": {
    "CONFIRMATION_LABEL": "Confirmation du mot de passe"
  },
  "AREA": {
    "TITLE": "Mon espace",
    "HELLO": "Bonjour {{name}}",
    "MANAGE_ACCOUNT": "Gérer mon compte",
    "MANAGE_ACCOUNT_HELP": "Modifier mes informations, mon mot de passe, ou supprimer mon compte.",
    "VIEW_SCHEDULE": "Voir un agenda",
    "VIEW_SCHEDULE_HELP": "Consulter l'agenda d'un médecin et réserver un créneau.",
    "MY_APPOINTMENT": "Mon rendez-vous",
    "SEE_IN_SCHEDULE": "voir dans l'agenda",
    "CANCEL_APPOINTMENT": "Annuler ce rendez-vous",
    "NO_APPOINTMENT": "Vous n'avez aucun rendez-vous à venir."
  },
  "MY_ACCOUNT": {
    "TITLE": "Gérer mon compte",
    "NEW_PASSWORD_LABEL": "Nouveau mot de passe",
    "CURRENT_PASSWORD_LABEL": "Mot de passe actuel",
    "CURRENT_PASSWORD_HELP": "Obligatoire pour enregistrer une modification.",
    "BACK": "Retour à mon espace",
    "DELETE_TITLE": "Supprimer mon compte",
    "DELETE_HELP": "Votre compte sera définitivement supprimé, ainsi que tous vos rendez-vous.",
    "DELETE_CONFIRM": "Supprimer définitivement votre compte ? Votre rendez-vous éventuel sera annulé.",
    "DELETE_SUBMIT": "Supprimer mon compte",
    "UPDATED": "Votre compte a été modifié.",
    "DELETED": "Votre compte a été supprimé."
  },
  "CONFIRMATION": {
    "TITLE": "Confirmation",
    "NO": "Non, revenir",
    "YES": "Oui, confirmer"
  }
}
{
  "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. 服务

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

// =========================================================================
// services/session.service.ts - 谁已登录?
// -------------------------------------------------------------------------
// 已登录的用户(或 null),以及由此推导出的内容(是不是 ADMIN?
// 是不是患者?),放在一个基于信号的根服务中(参见示例 20)。
//
// JWT 令牌本身不在这里:它在 httpOnly Cookie 中,
// 只有浏览器才会处理它。该服务只保存用户的描述
// (服务器返回的 { login, name, role })。
//
// 启动时(以及按 F5 之后),服务是空的:check() 向
// 服务器询问,且只询问一次,谁已登录(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);
  // 是否已经向服务器问过“谁已登录?”这个问题?
  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 和 DOCTOR:可以为任何患者预约和取消预约
  readonly isManager = computed(() => this.role() === 'ADMIN' || this.role() === 'DOCTOR');

  // 每个角色登录后立即进入的主页
  readonly homePage = computed(() => (this.isPatient() ? '/my-area' : '/schedule'));

  // 在每次导航之前由路由守卫调用;只在第一次
  // 查询服务器(promise 会被保留并复用)
  check(): Promise<void> {
    this.checking ??= this.api
      .me()
      .then((u) => this._user.set(u))
      .catch(() => this._user.set(null)); // 401:无人登录;或服务器不可达
    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));
  }

  // 用户已更改名称或登录名(PUT /api/my-account)
  update(u: User): void {
    this._user.set(u);
  }

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

  // 不询问服务器任何内容:会话已过期、账户已被删除
  forget(): void {
    this._user.set(null);
  }
}

已登录的用户,位于一个信号服务中(示例 20):

  • 第 22 行:状态:用户,或[null]。令牌本身不在这里:它在只有浏览器才会处理的 Cookie 中;
  • 第 26–32 行:组件读取的内容:用户,以及由此推断出的内容(用户是否已登录?是 ADMIN 吗?是患者吗?);
  • 第 35 行:每个角色的主页;
  • 第 39–45 行:启动时(以及按 F5 之后),服务并不知道谁已登录:它会询问服务器。[check] 在每次导航之前由路由器守卫调用,但只在第一次时查询服务器:promise 被保留下来(第 40 行,[??=]:“如果它尚不存在”),并在之后每次调用时返回。如果两次导航紧接着发生,它们会等待同一个响应;
  • 第 43 行:401(没有人登录)或服务器不可达:没有用户;
  • 第 56–62 行:登出;[finally]:即使服务器没有响应,用户也会被遗忘;
  • 第 65–67 行:在不向服务器发送请求的情况下忘记用户:这正是拦截器在遇到 401 时所做的事。

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

// =========================================================================
// services/messages.service.ts - 向用户显示的消息
// -------------------------------------------------------------------------
// 与 HTML 应用的呈现相同:
//   - 成功消息显示在页面顶部(绿色横幅);
//   - 错误消息显示在底部,浅粉色背景(“粘性”面板)。
// 消息是一个翻译 KEY(及其参数):因此如果用户切换语言,
// 它会自行重新翻译。
//
// “flash”消息:以页面跳转结束的操作
// (预约、添加医生……)通过 flash() 留下它的消息;
// 该消息会显示在下一个页面上,然后在
// 再下一次导航时消失。服务之所以知道这一点,是因为它监听路由器事件
// (每次导航结束)。在服务器端,这是
// 短期 Cookie "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);
  // 下一个页面要显示的消息
  private pending: { success: Message | null; error: Message | null } | null = null;

  constructor() {
    // 新页面(包括仅查询参数变化时,/schedule?...):
    // 上一页的消息消失,flash 消息
    // 出现。根服务与应用同生命周期:
    // 无需取消订阅。
    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);
  }

  // ApiError -> 页面的消息;其他任何错误都是
  // 客户端的异常,会被放行(浏览器控制台)
  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);
  }

  // 用于下一个页面
  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;
  }
}

向用户显示的消息,与 HTML 应用程序中一样:页面顶部的成功消息,页面底部的错误消息。消息是一个翻译键:如果用户切换语言,它会自动重新翻译。

  • 第 29–30 行:当前页面上的两条消息;
  • 第 58–63 行:[ApiError] 会成为页面的错误消息;任何其他错误属于客户端问题,允许报告;
  • 第 71–74 行:为下一个页面准备的 flash 消息。以页面跳转结束的操作(添加了医生、返回列表)因此会显示其消息;
  • 第 39–43 行:服务监听路由器事件(示例 17)。每次导航结束时(第 76–80 行),上一页的消息消失,flash 消息出现。在服务器端,这是短期 Cookie 的作用。

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

// =========================================================================
// services/confirmation.service.ts - “您确定吗?”
// -------------------------------------------------------------------------
// 取自示例 16:confirm(key) 打开确认对话框
// (components/confirm-dialog.ts,在 App 中只放置一次),并返回
// 一个 promise,其结果为 true(是)或 false(否)。消息是一个翻译
// KEY:对话框会把它翻译成当前语言。
//
//     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:对话框关闭
  readonly messageKey = this._messageKey.asReadonly();
  private answer: ((yes: boolean) => void) | null = null;

  confirm(key: string): Promise<boolean> {
    this.answer?.(false); // 还有未决的问题?视为“否”
    // 新问题:上一个操作的消息已经过时
    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);
  }
}

示例 16 中的服务。消息现在是一个翻译键(第 18 行),新的提问会清除上一个操作的消息(第 25 行)。

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

// =========================================================================
// services/form-submission.ts - 向服务器提交表单
// -------------------------------------------------------------------------
// 应用的所有表单都遵循与示例 25 相同的模式:
// 浏览器中不检查任何规则(规则
// 只存在于一个地方,即服务器),被拒绝时:
//   - 每个字段的错误(ApiError.fields)会附加到信号表单
//     的对应字段上,并以红色边框显示;
//   - 通用消息(ApiError.key)显示在页面底部。
// 这个类把这些步骤集中起来。每个页面为每个表单创建一个:
//
//     protected readonly submission = new FormSubmission(this.f);
//     if (await this.submission.submit(() => this.api.register(this.model()))) { ... }
//
// 它在注入上下文中使用(组件类字段的初始化):
// 它在那里获取消息服务。
// =========================================================================

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);
  // 服务器返回的错误消息参数({min}...)
  readonly params = signal<Record<string, string>>({});

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

  // 执行提交;成功则返回 true。遇到 ApiError 时,
  // 显示错误并返回 false。
  // ignoreValidators:即使表单模式的规则
  // (如果有)不满足,也照常提交
  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; // 无错误
        } catch (e) {
          this.messages.showApiError(e); // (重新抛出所有不是 ApiError 的错误)
          const error = e as ApiError;
          this.params.set(error.params);
          return this.fieldErrors(error);
        }
      },
    });
    return succeeded;
  }

  // { lastName: 'ERRORS.LASTNAME_REQUIRED' } -> 附加到字段 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> }));
  }
}

应用程序中的所有表单都遵循示例 25 所示的模式:规则由服务器验证,如果表单被拒绝,每个字段的错误会显示在该字段下方,页面底部显示一条通用错误消息。该类把这些操作集中在一起,这样就不必在每个页面上重复:

  • 第 24 行:一个 泛型类:[T] 是表单模型类型;
  • 第 25 行:[inject] 位于字段初始化中:该类必须在注入上下文中创建,即在组件字段初始化期间(第 12 行);
  • 第 27 行:错误消息的参数([{{min}}]……),由服务器返回;
  • 第 35–54 行:提交。[submit](示例 25)执行操作;该方法返回 [true] 表示操作成功;
  • 第 39 行:[ignoreValidators]:默认情况下(['pending']),[submit] 在表单存在验证错误时不执行操作(登录页面有一个包含两个必填字段的模式)。['all']:仍然发送请求(见登录页面);
  • 第 46 行:通用消息;
  • 第 57–62 行:字段错误。[isFieldTree] 验证表单确实有该名称的字段:服务器可能报告表单并未显示的字段的错误。

10.4.6. 格式化

10.4.6.1. src/app/pipes/formatting.ts

// =========================================================================
// pipes/formatting.ts - 医生、时间和日期的显示格式
// -------------------------------------------------------------------------
// 服务器发送的是原始数据(startHour: 8, startMinute: 0;day:
// "2026-10-05"),依赖于语言的格式化是客户端的
// 职责。函数供代码使用,管道(文件
// formatting.pipes.ts)供模板使用。
// =========================================================================

import { Slot, Identity } from '../api/types';

// "Mme Alice DURAND"
export function label(p: Identity): string {
  return `${p.title} ${p.firstName} ${p.lastName}`;
}

// "8:05" 而不是 "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)}`;
}

// 今天的日期,格式为 "yyyy-MM-dd"(即 <input type="date"> 和 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')}`;
}

// 如果 [day] 是真实存在的日期(yyyy-MM-dd 格式),则返回 true
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" 无论时区如何都必须仍是 5 日
  }).format(new Date(`${day}T00:00:00Z`));
}

服务器发送原始数据([startHour: 8, startMinute: 0];[day: "2026-10-05"]);格式化取决于语言,由客户端负责:

  • 第 34–40 行:这是有效日期吗?[2026-02-30] 格式正确,但并不存在:[new Date] 会把它转换为 3 月 2 日。因此我们验证它读回后是否相同。[day is string]:如果函数返回 true,[TypeScript] 就知道 [day] 是字符串;
  • 第 43–48 行:[Intl.DateTimeFormat]由浏览器提供,以所请求的语言书写日期。UTC 时区可避免位于格林尼治以西的浏览器显示前一天。

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

// =========================================================================
// pipes/formatting.pipes.ts - formatting.ts 中的函数,以管道形式提供
// -------------------------------------------------------------------------
//     {{ doctor | label }} "Mme Marie PELISSIER"
//     {{ slot | timeRange }} "8:00 - 8:20"
//     {{ day | longDate: language() }} "Monday 5 October 2026"
// longDate 接收语言作为参数:纯管道只有在其某个参数变化时才会重新计算,
// 因此切换语言会使它重新计算。
// =========================================================================

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

同样的函数,以管道的形式用于模板。[longDate] 接收语言作为参数:纯管道(示例 09)只有在其某个参数改变时才会重新计算;因此,更改语言会触发重新计算。

10.4.7. 路由器

10.4.7.1. src/app/app.routes.ts

// =========================================================================
// app.routes.ts - 应用的页面及其访问权限
// -------------------------------------------------------------------------
// 与 HTML 应用相同的地址(/login、/schedule、/doctors、
// /my-area...),但现在它们是客户端的路由。
// 浏览器只在加载第一个页面时向服务器发送请求;
// 之后由路由器改变地址和显示的组件。
//
// 另一面:如果用户重新加载 /schedule(F5),
// 浏览器确实会向服务器请求 /schedule,服务器此时必须
// 返回 index.html(开发时 ng serve 会这样做;生产环境中,
// 参见 JSON 服务器的 web/client-spa.ts)。
//
// 所有页面都是一个无组件路由的子路由,
// 该路由带有 sessionGuard 守卫(canActivateChild):因此它作用于
// 每个子页面。每条路由声明:
//   - title:标签页标题的翻译键(参见 i18n/title.strategy.ts);
//   - data:public(无需登录即可访问)、roles(允许的
//             角色)、type('doctors' 或 'clients')、code(403、404)。
// 借助 withComponentInputBinding(app.config.ts),地址中的参数
// (:id、?day=...)以及 data(type、code)会传入
// 页面组件的输入属性中。
// =========================================================================

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

// 管理医生和客户(ADMIN)的路由,采用相同的
// 模式;页面按需加载(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: [
      // "/":转到 /login,若已登录则由 /login 再转到该角色的主页
      { 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 },
      },
    ],
  },
];

与 HTML 应用程序相同的 URL(/login、/schedule、/doctors、/my-area……),但它们现在是客户端路由:

  • 第 50–53 行:所有页面都是某个无组件路由的子路由([children]),该路由带有守卫[sessionGuard]:[canActivateChild] 将其应用于每个子路由,无需重复;
  • 第 55 行:地址 / 指向登录页面,如果用户已登录,登录页面再重定向到该角色的主页;
  • 第 56–57 行:两个访问量最大的页面包含在主文件中;其余页面按需加载([loadComponent]);
  • [title]:标签页标题的翻译键;
  • [data]:[public](无需登录即可访问),[roles](授权角色;缺省:所有已登录角色),[type](['doctors'] 或 ['clients']),[code](403、404)。得益于 [withComponentInputBinding],路由数据也会传入页面组件的 输入,例如地址参数;
  • 第 34–47 行:医生管理系统的三个路由和客户管理系统的路由由同一个函数生成:两个系统使用相同的页面,只是 [type] 不同;
  • 第 41 行:[canMatch]:一个判断路由是否匹配地址的守卫。如果失败,路由器会尝试后续路由:因此 /doctors/abc/edit 会指向 404 页面;
  • 第 65 行:账户创建页面专用的守卫;
  • 第 79 行:403 页面,守卫将用户重定向到该页面;
  • 第 80–85 行:任何其他地址:404 页面。

10.4.7.2. src/app/guards.ts

// =========================================================================
// guards.ts - 路由器的守卫
// -------------------------------------------------------------------------
// sessionGuard:所有页面的守卫(参见 app.routes.ts)。每次
// 导航之前:
//   1. 第一次(启动、F5)时,它向服务器询问当前
//      登录的是谁(SessionService.check);
//   2. 它检查路由的 data 中描述的权限:
//        - public:无需登录即可访问;
//        - roles:允许的角色(缺省 = 所有已登录角色)。
//
// 提醒:这些检查只是一种便利(不显示无用的
// 页面)。数据的保护由服务器保证,服务器会在
// 每个请求中再次检查令牌和角色。
//
// 警告:inject() 只能在守卫的开头、任何 await 之前使用
// (之后"注入上下文"就丢失了)。
// =========================================================================

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']) {
    // 已经登录:登录页不再有意义
    if (route.routeConfig?.path === 'login' && session.loggedIn()) {
      return router.parseUrl(session.homePage());
    }
    return true;
  }
  if (!session.loggedIn()) {
    // 记住所请求的页面,以便登录后返回
    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;
};

// /register 路由专用的守卫:没有通行证(在登录页
// 解决验证码后获得),则返回登录页
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:只有当地址的第 2 段
// 是数字时才匹配该路由(/doctors/abc/edit 会转到 404 页面)
export const numericId: CanMatchFn = (_route, segments) => /^\d+$/.test(segments[1]?.path ?? '');
  • 第 27 行:守卫可以是 [async]:路由器会等待其响应;
  • 第 28–30 行:注意:[inject] 只允许出现在守卫的开头,即在任何 [await] 之前;此后注入上下文就丢失了;
  • 第 30 行:第一次时,向服务器询问当前登录的是谁;
  • 第 32–38 行:公共页面;但登录页面对已登录用户不再有意义(第 34 行)。[parseUrl] 将地址转换为 [UrlTree],这是触发重定向的值;
  • 第 39–42 行:未登录:跳转到登录页面,同时保留所请求的页面;
  • 第 43–46 行:无效角色:重定向到 403 页面;
  • 第 52–62 行:创建账户需要一张“通行证”,通过在登录页面解决验证码(CAPTCHA)获得。没有它,用户会被带回登录页面并收到一条消息;
  • 第 66 行:守卫 [canMatch] 接收地址段:[['doctors', '3', 'edit']]。

这些守卫只是为了方便:数据保护由服务器保证,服务器在每次请求时都会重新验证令牌和角色。

10.4.8. 组件

10.4.8.1. src/app/components/nav-bar

// =========================================================================
// components/nav-bar/nav-bar.ts - 导航栏
// -------------------------------------------------------------------------
// 与 HTML 应用(views/partials/navbar.hbs)的内容相同:
// 标题、按角色显示的菜单、FR / EN、角色、姓名、退出。
// "Doctors" 和 "Patients" 仅对 ADMIN 显示:这只是显示上的
// 便利,真正的保护在服务器端。
// =========================================================================

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(() => {}); // 即使服务器没有响应
    this.router.navigate(['/login']);
  }
}
  • 第 29 行:注销,即使服务器没有响应;然后返回登录页面。
<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:所显示页面对应菜单的 Bootstrap 类 -->
          <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:不向服务器发送请求,页面就地重新翻译 -->
    <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>
  • 第 4–23 行:菜单,取决于角色;
  • 第 31–36 行:FR / EN 按钮;[aria-pressed] 向屏幕阅读器指示哪个按钮被按下;
  • 第 39–43 行:角色、姓名、注销。

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

// =========================================================================
// components/success-message.ts - 成功消息,位于页面顶部
// (预约成功、添加医生...)- 参见 services/messages.service.ts。
// role="status":屏幕阅读器会播报它,而不会打断用户。
// =========================================================================

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 - 错误面板,位于每个页面的底部,背景为
// 浅粉色(类 .error-panel,参见 styles.css)- 与
// HTML 应用的 views/partials/errors.hbs 相同。
// role="alert":消息一出现,屏幕阅读器就会播报。
// =========================================================================

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

两个小组件,显示来自[MessagesService]服务的消息,并连同参数一起翻译。[status]和[alert]角色会让屏幕阅读器播报这些消息。

10.4.8.3. src/app/components/confirm-dialog

// =========================================================================
// components/confirm-dialog/confirm-dialog.ts
// -------------------------------------------------------------------------
// 示例 16 中的 "Are you sure?" 对话框,为键盘操作做了完善,
// 与 HTML 应用的 public/js/app.js 一样:
//   - 打开时,焦点移到 "No, go back":心不在焉地按下
//     Enter 不会删除任何东西;
//   - Escape 关闭对话框(= No);
//   - Tab 和 Shift+Tab 只在对话框内部循环(否则焦点会跑到
//     后面变灰的页面上);
//   - 关闭时,焦点回到原先拥有焦点的元素(例如
//     被点击的 "Delete" 按钮)。
// 用 "No, go back" 而不是 "Cancel":因为有时问题是 "Cancel this
// appointment?",此时 "Cancel" 按钮会有歧义。
// =========================================================================

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() {
    // 对话框打开(出现 "No" 按钮)或关闭
    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();
      }
    }
  }

  // 点击变灰的背景(而不是对话框本身)= No
  protected onBackdropClick(e: MouseEvent): void {
    if (e.target === e.currentTarget) {
      this.confirmation.respond(false);
    }
  }
}

示例 16 中的窗口,增加了键盘支持:

  • 第 34–45 行:一个跟踪“否”按钮出现和消失的 effect。打开时,保留原本拥有焦点的元素,并把焦点交给“否”按钮;关闭时,焦点回到保留的元素(例如被点击的“删除”按钮)。[untracked]:在该函数中读取的信号不会成为 effect 的依赖项;
  • 第 48–64 行:键盘。Esc 回答“否”;Tab 和 Shift+Tab 停留在窗口内:从最后一个按钮回到第一个,反之亦然。否则,焦点会移到后面变灰的页面上;
  • 第 67–71 行:点击变灰的背景会回答“否”。
@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>
}
  • 第 2 行:在包含窗口的元素上监听按键;
  • 第 14 行:消息,一个翻译键。

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

// =========================================================================
// components/input-field.ts - 完整的表单字段
// -------------------------------------------------------------------------
// 标签 + 字段 + 帮助信息或错误信息。应用的所有
// 表单都使用它,配合信号表单:
//
//   <app-input-field [formField]="f.lastName" fieldId="lastName" label="PERSONS.LASTNAME_LABEL" [maxChars]="20" />
//
// 这是一个"自制"的表单控件:通过实现接口
// FormValueControl,它可以像普通的 <input> 一样接受 [formField]。
// 契约很简单:
//   - value(一个 model()):字段的值,由表单读取并
//     写入;
//   - errors(契约中可选的输入):如果组件
//     声明了它,[formField] 指令就会把字段的错误放入其中 -
//     这里是服务器返回的错误(参见 pages/person-form.ts)。
// label、help 和错误消息都是翻译键。
// =========================================================================

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],
  // 组件默认以 "inline" 方式显示:我们把它改成块级元素,
  // 这样父组件设置的类(mb-3、col-sm-6)才能生效
  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> {
  // FormValueControl 契约
  readonly value = model('');
  readonly errors = input<readonly ValidationError.WithOptionalFieldTree[]>([]);

  // 我们自己的输入
  // <input> 的 id(不用 "id":id 属性也会同时保留在
  // <app-input-field> 上,页面就会有两个 id 相同的元素)
  readonly fieldId = input.required<string>();
  readonly label = input.required<string>(); // 翻译键
  readonly type = input<'text' | 'password'>('text');
  readonly help = input<string>(); // 帮助信息的键
  readonly params = input<Record<string, string>>({}); // 消息的参数({min}...)
  readonly maxChars = input<number>();
  readonly autocomplete = input('off');
  readonly mandatory = input(false, { transform: booleanAttribute });

  // 字段的第一个错误(其翻译键),如果有的话
  protected readonly error = computed(() => this.errors()[0]?.message);

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

一个完整的表单字段:标签、字段、提示或错误消息。应用程序中的所有表单都使用它。它是一个 自定义表单控件:遵循 [FormValueControl] 契约,它接受 [[formField]] 指令,就像接受普通的 [<input>] 一样:

  • 第 46 行:该类实现 [FormValueControl<string>] 接口:编译器会验证它是否符合契约;
  • 第 48 行:[value],一个 [model()](示例 11):字段的值,[[formField]] 指令对其既读又写;
  • 第 49 行:[errors],契约的一个可选输入:如果组件声明了它,指令会把字段的错误存放在那里;
  • 第 54–61 行:组件专有的输入。元素 [<input>] 的标识符命名为 [fieldId],而不是 [id]:因为 [id] 属性如果设置在 [<app-input-field>] 上,也会保留在该元素上,页面就会有两个具有相同标识符的元素;
  • 第 61 行:[booleanAttribute] 将属性的存在([mandatory],不带值) 转换为 [true];
  • 第 64 行:字段的第一个错误:其翻译键;
  • 第 36–38 行:[<input>] 元素显示值,并在每次按键时返回它(第 66–68 行)。[aria-invalid] 和 [aria-describedby] 为屏幕阅读器将字段与其消息关联起来;
  • 第 39–43 行:错误消息,否则为帮助消息,连同其参数一起翻译;
  • 第 29–33 行:[:host] 指组件元素本身([<app-input-field>])。浏览器不认识的元素按“内联”显示:把它转换为块级元素,这样父级应用的类([col-sm-6])才能生效。

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

// =========================================================================
// components/person-fields.ts - 称谓、名、姓
// -------------------------------------------------------------------------
// 身份字段,三个表单共用:ADMIN 的医生 / 客户表单、
// "Create a patient account" 和 "Manage my account"(相当于
// 局部视图 views/partials/personFields.hbs)。父组件向它传入其信号表单的
// 三个字段:
//     <app-person-fields [title]="f.title" [firstName]="f.firstName" [lastName]="f.lastName" />
// 字段(FieldTree)和其他值一样,是一个普通的值:它可以作为
// 组件的输入传入,由组件将其绑定到自己的 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():作为输入接收的字段;title()():它的状态 -->
      @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'];
}

称谓、名和姓字段,三个表单共用。父级把基于信号的表单中的这三个 字段 传递给该组件:

  • 第 42–44 行:字段([FieldTree])和其他值一样,是一个值:可以作为输入接收;
  • 第 25 行:[title()] 是作为输入接收的字段;[title()()] 是它的状态;
  • 第 26 行:称谓列表通过 [[formField]] 与字段绑定;
  • 第 36–37 行:另外两个字段传递给 [InputField] 组件。

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

// =========================================================================
// components/captcha-field.ts - 验证码图片和输入字段
// -------------------------------------------------------------------------
// 一个"自制"的表单控件(FormValueControl,参见 input-field.ts),
// 创建后立即加载验证码(GET /api/captcha)。父组件:
//   - 将输入绑定到其表单:[formField]="f.captcha";
//   - 用 viewChild(CaptchaField) 获取组件本身,以便
//     调用它的公共方法:captchaId(),以及每次尝试之后调用 reload(),
//     因为一张图片只能使用一次(服务器
//     校验后就会立即忘掉它)。
//
// [innerHTML] + bypassSecurityTrustHtml:SVG 图片按原样
// 插入。在这里是无害的,因为它由我们的服务器生成
// (svg-captcha 库),不包含任何来自
// 用户的内容 - 参见示例 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();
  }

  // 新图片,以及空字段
  async reload(): Promise<void> {
    this.value.set('');
    try {
      this.captcha.set(await this.api.captcha());
    } catch {
      this.captcha.set(null); // 服务器不可达:登录将失败并给出明确的消息
    }
  }

  // 所显示图片的标识符,随答案一起发送
  captchaId(): string {
    return this.captcha()?.id ?? '';
  }

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

验证码(CAPTCHA)图片及其输入字段:另一个自定义表单控件。

  • 第 61 行:组件创建后立即加载一张图片;
  • 第 65–72 行:[reload] 是 public:登录页面在每次尝试后调用它,因为每张图片只使用一次;
  • 第 75–77 行:所显示图片的 ID,随答案一起发送;
  • 第 37 行:SVG 图片(示例 22),带有供屏幕阅读器使用的替代文本;
  • 第 40 行:[autocapitalize] 和 [spellcheck]:在手机上不自动大写,也不进行拼写检查。

父页面通过 [viewChild(CaptchaField)](示例 13)获取该组件,以调用其公共方法。

10.4.8.7. src/app/components/booking-dialog

// =========================================================================
// components/booking-dialog/booking-dialog.ts
// -------------------------------------------------------------------------
// 预约时间段的对话框。与 HTML 应用的
// views/partials/booking.hbs 是同一个对话框:使用模态对话框的 Bootstrap
// 类,以"硬编码"方式显示(show d-block)。
//
// 该组件不与服务器通信:它发出
//   - confirm,附带所选的患者(患者为自己
//     预约时为 null);
//   - close。
// 如何处理这些事件由日程页面决定(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:关闭
  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:可供选择的患者
  readonly patient = input<string | null>(null); // USER:患者就是他本人
  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() {
    // 显示时,焦点落在对话框的第一个有用元素上
    afterNextRender(() => (this.list() ?? this.confirmButton()).nativeElement.focus());
  }

  // 点击变灰的背景(而不是对话框本身)会关闭对话框
  protected onBackdropClick(e: MouseEvent): void {
    if (e.target === e.currentTarget) {
      this.close.emit();
    }
  }
}

预订时段窗口。它不与服务器通信:它接收要显示的内容,并发送用户的决定;执行操作的是日历页面。

  • 第 29–32 行:输入:时间段、可供选择的患者(ADMIN、DOCTOR),或患者本人(USER),以及一个“正在发送”指示器;
  • 第 34–35 行:输出:确认(携带所选患者);关闭;
  • 第 25 行:Esc 关闭窗口;
  • 第 43 行:[afterNextRender](示例 13):窗口显示后,焦点移到患者列表,否则移到确认按钮。
<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>
        <!-- 患者为自己预约:没有列表(并且服务器
             无论如何都会忽略可能存在的 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>
  • 第 5 行:一个表单:Enter 键确认;
  • 第 16–26 行:患者为自己预订:没有列表;
  • 第 21–24 行:[[ngValue]](示例 05):每个选项的值是一个数字,或 [null];
  • 第 31 行:提交期间按钮被禁用:双击不会导致重复预订。

10.4.9. 页面

10.4.9.1. src/app/pages/login

// =========================================================================
// pages/login/login.ts - 登录页(/login)
// -------------------------------------------------------------------------
// 与 HTML 应用的 views/login.hbs 是同一个页面:登录名、密码、
// 验证码,以及第二个按钮 "Create a patient account",它会先校验
// 相同的验证码,再打开账户创建页面。
//
// /login?login=jbernard:登录名字段被预先填好(紧接在
// 创建账户之后)。
// /login?redirect=/doctors:登录后打开该页面
// (由路由器守卫设置),而不是该角色的主页。
// 这两个参数作为组件的输入传入。
// =========================================================================

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: '' });
  // 两条规则:登录名和密码必填。随后 [formField] 会在
  // 两个字段上设置 HTML 的 required 属性,只要它们为空,
  // 浏览器就拒绝提交表单
  protected readonly f = form(this.model, (p) => {
    required(p.login);
    required(p.password);
  });
  private readonly submission = new FormSubmission(this.f);
  // 验证码组件,用于调用其 captchaId() 和 reload() 方法
  private readonly captchaField = viewChild.required(CaptchaField);

  constructor() {
    afterNextRender(() => {
      // 输入现已就绪:若 URL 中有登录名,则取用它
      const login = (this.login() ?? '').slice(0, 30);
      this.model.update((m) => ({ ...m, login }));
      // 焦点:如果登录名已填写,则落在密码上
      (login ? this.f.password : this.f.login)().focusBoundControl();
    });
  }

  // 两个按钮共用此流程:提交,然后在失败时
  // 显示错误消息并换新图片(每张图片只能使用一次)
  private async attempt(action: () => Promise<unknown>, ignoreValidators = false): Promise<void> {
    this.messages.clear();
    await this.submission.submit(async () => {
      try {
        await action();
      } catch (e) {
        // 在把错误附加到字段之前先换新图片:
        // reload() 会清空字段,从而会清除该错误
        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();
      // 只允许内部路径:绝不重定向到其他站点
      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); // 这里不使用登录名和密码:它们的规则被忽略
  }
}

登录页面:用户名、密码、验证码(CAPTCHA),以及第二个“创建患者账户”按钮,它在允许创建账户之前验证同一个验证码。

  • 第 31–32 行:两个 URL 参数:/login?login=jbernard 预填用户名(紧接在创建账户之后);由守卫设置的 /login?redirect=/doctors 指定登录后要打开的页面;
  • 第 43–46 行:应用程序中唯一带有 模式的表单:用户名和密码为必填。于是 [[formField]] 指令会在两个字段上设置 HTML 属性 [required],只要它们为空,浏览器就拒绝提交表单;
  • 第 47 行:提交表单(services/form-submission.ts);
  • 第 49 行:验证码组件,用于调用其方法;
  • 第 52–58 行:[afterNextRender]:页面显示后,输入已知。URL 中的登录名被复制到表单中(限 30 个字符),焦点设置在第一个空字段上。[focusBoundControl()] 把焦点设置到由 [[formField]] 与字段关联的元素上;
  • 第 63–75 行:两个按钮都遵循这个顺序:提交,然后如果失败,就换一张新图片(每张只使用一次)。顺序很重要:[reload] 会清空验证码字段,这会移除与该字段关联的错误;因此我们要“先”重新加载图片,以便再次触发该错误,[FormSubmission] 随后会把它与字段关联起来;
  • 第 77–87 行:登录,随后导航到所请求的页面或该角色的主页。与示例 18 一样,只接受内部路径(第 84 行);
  • 第 89–94 行:第二个按钮。服务器验证验证码并设置一张“通行证”(一个 Cookie);随后打开账户创建页面。这里不使用用户名和密码:模式规则被忽略(第 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>

        <!-- 一个"自制"控件,绑定到表单的验证码字段 -->
        <app-captcha-field [formField]="f.captcha" />

        <!-- type="submit":在字段中按 Enter 会触发 "Log in" -->
        <button type="submit" class="btn btn-primary w-100" [disabled]="f().submitting()">{{ 'LOGIN.SUBMIT' | translate }}</button>

        <!-- type="button":此按钮不提交表单(登录名和密码
             不做必填检查,此处无用) -->
        <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>
  • 第 6 行:这里没有 [novalidate]:浏览器会提示用户名或密码为空;
  • 第 18 行:自定义验证码控件,与表单中的 [captcha] 字段关联;
  • 第 21 行:提交期间按钮被禁用([submitting()]);
  • 第 25 行:[type="button"]:该按钮不提交表单,因此浏览器不要求填写用户名和密码。

10.4.9.2. src/app/pages/schedule

// =========================================================================
// pages/schedule/schedule.ts - 日程页面(/schedule)
// -------------------------------------------------------------------------
// 三个区块,与 HTML 应用的 views/schedule.hbs 一样:
//   1. 选择医生和日期;
//   2. 该医生在当天的日程;
//   3. 预约时间段的对话框。
//
// 与 HTML 应用一样,页面的全部状态都在其 URL 中:
//     /schedule?doctorId=1&day=2026-10-05 日程
//     /schedule?doctorId=1&day=2026-10-05&book=7 + 预约对话框
// 因此页面可以重新加载、加入书签,浏览器的后退 / 前进
// 按钮也能正常工作。页面跟随它的 URL:三个
// 参数作为输入(信号)传入,当医生或日期改变时,
// 一个 effect 会重新加载日程;而用户的操作
// 则会改变 URL(router.navigate)。
//
// 每个人能看到什么、能做什么由服务器决定(每个时间段的
// patient、mine、bookable、appointmentId 字段):页面只是
// 将其显示出来。患者甚至收不到其他患者的姓名。
// =========================================================================

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", 缺失 -> 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 {
  // URL 的参数(若不存在则为 undefined)
  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:用于预约对话框
  protected readonly schedule = signal<Schedule | null>(null);
  protected readonly loading = signal(false);
  protected readonly submitting = signal(false);

  // "医生 + 日期"表单的值,从 URL 复制而来
  protected readonly doctorChoice = signal<number | null>(null);
  protected readonly dayChoice = signal(today());

  // 所显示的日程,不含预约对话框:"返回"查询
  protected readonly scheduleQuery = computed(() => ({ doctorId: String(this.doctorChoice() ?? ''), day: this.dayChoice() }));

  // 预约对话框已打开的时间段(?book=7),
  // 仅当该用户可以预约它时
  protected readonly slotToBook = computed<ScheduleSlot | null>(() => {
    const id = positiveInteger(this.book());
    return this.schedule()?.slots.find((c) => c.id === id && c.bookable) ?? null;
  });

  // 已登录患者(USER)的姓名,ADMIN 和 DOCTOR 则为 null
  protected readonly patient = computed(() => (this.session.isPatient() ? (this.session.user()?.name ?? '') : null));

  constructor() {
    this.loadLists();
    // 日程跟随 URL(医生和日期):effect 会读取两个输入,
    // 而加载则在 untracked 中进行
    effect(() => {
      const doctorId = this.doctorId();
      const day = this.day();
      untracked(() => this.loadSchedule(doctorId, day));
    });
  }

  // -------------------------------------------------------------------------
  // 加载
  // -------------------------------------------------------------------------
  private async loadLists(): Promise<void> {
    try {
      this.doctors.set(await this.api.list('doctors'));
      // 患者列表:仅对有权读取它的人
      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> {
    // 日期:若 URL 中的有效则用它,否则用今天
    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);
    }
    // 医生:取 URL 中的;没有医生时,DOCTOR 看到的是自己的日程
    // (服务器根据令牌找到它)
    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);
    }
  }

  // 当前 URL 的日程,重新读取(预约或取消之后)
  private reload(): Promise<void> {
    return this.loadSchedule(this.doctorId(), this.day());
  }

  // -------------------------------------------------------------------------
  // 操作
  // -------------------------------------------------------------------------

  // "View schedule":URL 被改变,日程随之更新(见上面的 effect)
  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') {
        // 没有选择患者:对话框保持打开
        this.messages.showError(e.key);
        return; // (finally 无论如何都会执行)
      }
      if (!(e instanceof ApiError)) {
        throw e;
      }
      // 时间段在此期间被占用、患者已有预约等情况:消息将
      // 显示在日程页面上,对话框关闭
      this.messages.flash('error', e.key, e.params);
    } finally {
      this.submitting.set(false);
    }
    await this.router.navigate(['/schedule'], { queryParams: this.scheduleQuery() });
    await this.reload(); // 以服务器为准:重新读取日程
  }

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

应用程序中功能最丰富的页面。与 HTML 应用程序一样,页面的全部状态都包含在其 URL 中:/schedule?doctorId=1&day=2026-10-05 显示一个日历,&book=7 则加上预订窗口。因此可以重新加载页面、将其加入书签,并使用后退/前进按钮。原则是:页面跟随其 URL,而用户的操作改变URL。

  • 第 51–53 行:三个 URL 参数,作为输入;
  • 第 39–42 行:地址参数可以包含任何内容;要对其进行验证;
  • 第 69–70 行:“医生 + 日期”表单的值,从 URL 复制而来;
  • 第 73 行:所显示日历的参数,不含预订窗口;
  • 第 77–80 行:预订窗口所打开的时间段,根据地址([?book=7])和日历计算得出:仅当该用户可预订时才有。这是一个 [computed]:地址变化时,窗口自动打开或关闭;
  • 第 89–93 行:一个依赖于两个输入 [doctorId] 和 [day] 的 effect:其中任何一个变化时,日历都会重新加载。重新加载在 [untracked] 中执行:其中读取和修改的信号不会成为该 effect 的依赖项。输入 [book] 不会被读取:打开或关闭窗口不会重新加载日历;
  • 第 99–109 行:医生,以及对有权查看患者的用户显示的患者;
  • 第 111–141 行:加载日历。无效日期会被报告(第 115–118 行);没有指定医生时,DOCTOR 看到的是他自己的日历:服务器从令牌中获取(第 126–129 行);
  • 第 153–159 行:“查看日程”和关闭窗口会改变地址;日历随之更新;
  • 第 161–187 行:预约预订。如果成功,会准备一条 flash 消息(第 169 行);它将在第 185 行之后显示,该行关闭窗口。如果没有选择患者,窗口保持打开(第 171–175 行)。任何其他错误(时间段在此期间被占用等)都会显示在日历上,同时窗口关闭。在所有情况下,都会重新读取日历:以服务器的记录为准(第 186 行);
  • 第 189–200 行:取消,需经确认。
<!-- 1. 选择医生和日期 -->
<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();

<!-- 已有即将到来预约的患者:这就是没有 "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. 日程 -->
@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" 是一个链接:它向 URL 添加 &book=...,由此
                     打开预订对话框 -->
                @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. 预约对话框,仅当 URL 包含 &book=... 时 -->
@if (slotToBook(); as c) {
  <app-booking-dialog [time]="timeRange(c)" [clients]="clients()" [patient]="patient()"
                           [submitting]="submitting()" (confirm)="confirmBooking($event)"
                           (close)="closeBooking()" />
}
  • 第 2–21 行:选择医生和日期,使用 [ngModel](示例 05);
  • 第 23 行:[@let]:日历,只读取一次;
  • 第 26–30 行:已经有一个即将到来的预约的患者:服务器发送一条消息,解释为什么没有“预订”按钮;
  • 第 37 行:以本地语言完整拼写的日期;
  • 第 52–58 行:时间段的状态:可用、患者(以蓝色显示),或在服务器没有发送患者姓名时显示“已预订”;
  • 第 63–67 行:“预订”是一个 链接:它在 URL 中加上 &book=...,从而打开预订窗口;
  • 第 87–91 行:预订窗口,仅当 URL 包含 &book=... 且该时间段可预订时才显示。

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

// =========================================================================
// pages/persons/persons.config.ts - 医生还是客户?
// -------------------------------------------------------------------------
// 管理医生和客户的页面是相同的:同样的
// 列表,同样的表单。如同 HTML 应用(抽象类
// PersonsController),它们只写一次(persons.ts、
// person-form.ts);只有 API 的地址和标签的键
// 不同,在此处描述。路由器在每条路由的
// data 中给出类型(参见 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}} 和 {{login}},用于 "added / updated / deleted" 消息
export function messageParams(p: { firstName: string; lastName: string; login?: string }): Record<string, string> {
  return { name: `${p.firstName} ${p.lastName}`, login: p.login ?? '' };
}

管理医生和客户的页面是相同的:同样的列表,同样的表单。与 HTML 应用程序一样(抽象类 [PersonsController]),它们只写一次;唯一变化的是 API 地址和标签键,这里对此进行了描述:

  • 第 25 行:[Record<PersonType, PersonKeys>]:编译器要求每种类型恰好有一个条目,不多也不少;
  • 第 49–51 行:“已添加 / 已修改 / 已删除”消息的参数。

10.4.9.4. src/app/pages/persons

// =========================================================================
// pages/persons/persons.ts - 医生或客户的列表(ADMIN)
// -------------------------------------------------------------------------
// 两者共用一个页面:类型('doctors' 或 'clients')位于
// 路由的 data 中(data.type,参见 app.routes.ts),并作为
// 组件的输入传入;各自特有的标签位于
// persons.config.ts。相当于
// HTML 应用的 views/persons/list.hbs。
// "export default":路由按需加载该页面(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

  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:尚未加载

  // 用 ngOnInit 而不是构造函数:此时输入(type)已经就绪
  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) {
      // 仍有预约的医生:409 ERRORS.DOCTOR_HAS_APPOINTMENTS
      this.messages.showApiError(e);
    }
    await this.load();
  }
}
  • 第 26 行:[export default]:路由按需加载该页面(示例 17);
  • 第 27 行:类型(['doctors'] 或 ['clients']) 来自路由的输入数据;
  • 第 33 行:此类型的标签键;
  • 第 34 行:[null]:列表尚未加载;
  • 第 37–39 行:[ngOnInit](示例 13)而不是构造函数:此时输入已经可用;
  • 第 49–61 行:删除,需经确认。仍有预约的医生不能被删除:服务器返回 409 响应,并显示其消息。
<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>
  • 第 3 行:[['/', type(), 'add']]:/doctors/add 或 /clients/add;
  • 第 8–12 行:加载期间、空列表、列表;
  • 第 32 行:/doctors/3/edit。

10.4.9.5. src/app/pages/person-form

// =========================================================================
// pages/person-form/person-form.ts - 创建或更新
// 医生或客户(ADMIN)
// -------------------------------------------------------------------------
//     /doctors/add -> 创建(没有 id 输入)
//     /doctors/3/edit -> 更新(输入 id = 3)
// (/clients 下的地址同理)。相当于
// HTML 应用的 views/persons/form.hbs。
//
// 这里不检查任何规则:一切由服务器验证,其错误
// 显示在字段下方(参见 services/form-submission.ts)。
// 随记录一起读取的版本号会在更新时一并回传:如果另一位
// ADMIN 在此期间更新了它,服务器会响应 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
  // 地址中的 :id 参数,转换为数字;创建时不存在
  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); // 无验证器:由服务器验证
  protected readonly submission = new FormSubmission(this.f);

  // 更新:读取记录(包括其版本号)
  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) {
      // 记录不存在(期间被删除等):返回列表
      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') {
      // 期间被另一位 ADMIN 删除:返回列表
      this.messages.flash('error', key);
      this.router.navigate(['/', this.type()]);
    }
  }
}

创建(/doctors/add)或修改(/doctors/3/edit)医生或客户:

  • 第 37 行:地址参数 [:id],创建时不存在。选项 [transform] 将其转换为数字([numberAttribute]);
  • 第 44 行:是创建还是修改?
  • 第 46–48 行:没有验证器的表单(服务器验证一切),及其提交;
  • 第 51–67 行:对于更新,会读取记录,包括 其版本;将用这些修改对其进行更新(乐观锁)。不存在的记录(/doctors/999/edit)会重定向到列表并显示一条消息;
  • 第 69–85 行:保存。成功后会闪现一条消息,用户被重定向到列表(第 75 行和第 78–79 行)。如果记录在此期间已被另一位管理员删除,用户同样被重定向到列表(第 80–84 行);任何其他错误都会使表单继续显示,并附带其错误信息。
<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:由服务器验证(以服务器为准) -->
      <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'" />
        <!-- 绝不预填:密码绝不会从服务器返回 -->
        <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>
  • 第 6 行:[novalidate]:由服务器验证表单;
  • 第 7 行:称谓、名和姓,位于同一个组件中;
  • 第 10–15 行:用户名和密码,创建和修改时使用不同的帮助消息。密码从不预填:服务器从不返回它;
  • 第 14 行:服务器返回的错误消息所用的参数(例如密码的最小长度)。

10.4.9.6. src/app/pages/register

// =========================================================================
// pages/register/register.ts - "Create a patient account"(/register)
// -------------------------------------------------------------------------
// 只有在抄写了登录页的验证码之后才能到达这里
// ("Create a patient account" 按钮):服务器随后签发了一张
// 通行证,由路由的守卫检查过(参见 guards.ts)。
// 字段与 ADMIN 表单相同,但登录名和密码
// 为必填,且需确认。相当于
// HTML 应用的 views/account/registration.hbs。
// =========================================================================

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

// 患者所选密码的最小长度:与服务器相同的值
// (服务器在 PASSWORD_TOO_SHORT 错误中也会返回 {min})
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);
  // 密码帮助信息和错误的参数
  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) {
      // 返回登录页,登录名已预填
      this.messages.flash('success', 'REGISTRATION.DONE', { login });
      this.router.navigate(['/login'], { queryParams: { login } });
    } else if (this.messages.error()?.key === 'ERRORS.CAPTCHA_BEFORE_ACCOUNT') {
      // 通行证已过期(15 分钟):返回验证码页
      this.messages.flash('error', 'ERRORS.CAPTCHA_BEFORE_ACCOUNT');
      this.router.navigate(['/login']);
    }
  }
}

创建患者账户。只有持有服务器在验证码(CAPTCHA)通过后颁发的令牌,才能继续(guards.ts):

  • 第 25 行:密码的最小长度;用于帮助消息:与服务器的值相同;
  • 第 41 行:帮助消息和密码错误消息的参数。如果服务器返回了参数,则以服务器的参数为准(它们被放在最后);
  • 第 46–48 行:提交;服务器返回所创建账户的用户名;
  • 第 49–52 行:返回登录页面,并预填用户名;
  • 第 53–57 行:令牌已过期(15 分钟):返回验证码页面。
<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>
  • 第 7 行:称谓、名、姓;
  • 第 10–17 行:用户名、密码和确认密码——这次为必填([mandatory] 属性只是提示:由服务器决定)。

10.4.9.7. src/app/pages/patient-area

// =========================================================================
// pages/patient-area/patient-area.ts - "My area"(/my-area,角色 USER)
// -------------------------------------------------------------------------
// 患者的主页,登录后立即显示:
//   - 两个选项:[Manage my account] 和 [View a schedule];
//   - 他或她即将到来的预约(如果有),并可取消该预约。
// 相当于 HTML 应用的 views/patient/area.hbs。
// =========================================================================

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();
  }
}

患者的主页:两个选项(“管理我的账户”“查看日程”)以及其即将到来的预约,患者可以取消该预约(第 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>
    <!-- 通常只有一个(规则“同一时间只有一个即将到来的预约”),
         但页面可以显示多个 -->
    @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 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>
}
  • 第 2 行:由管道计算出的翻译参数;
  • 第 22 行:[$last]:最后一行没有边框;
  • 第 29 行:指向该日医生日历的链接。

10.4.9.8. src/app/pages/my-account

// =========================================================================
// pages/my-account/my-account.ts - "Manage my account"(/my-account,角色 USER)
// -------------------------------------------------------------------------
// 两个独立的表单,如同 views/patient/account.hbs:
//   1. 更新(身份、登录名、可选的新密码);
//   2. 删除账户 - 同时也会取消其预约。
// 两者都需要当前密码(由服务器检查)。
// 两个表单,因此有两个模型、两棵字段树和两个
// FormSubmission 对象(两组错误)。
// =========================================================================

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. 更新
  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. 删除:只有一个字段的表单
  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 () => {
      // 服务器已签发新的令牌(姓名、登录名):导航
      // 栏必须随之更新
      this.session.update(await this.api.editMyAccount(this.model()));
      this.messages.flash('success', 'MY_ACCOUNT.UPDATED');
    });
    if (succeeded) {
      this.router.navigate(['/my-area']);
    } else {
      // 提交被拒绝后,字段中绝不能残留密码;
      // 改的是字段本身(而不是模型),以免清除
      // 服务器刚附加到它上的错误...(它自己的错误除外)
      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(); // 服务器已清除令牌的 cookie
      this.messages.flash('success', 'MY_ACCOUNT.DELETED');
      this.router.navigate(['/login']);
    }
  }
}

两个相互独立的表单:账户修改和账户删除。两者都需要当前密码,由服务器验证。两个表单,因此有两个模型、两棵字段树,以及两个[FormSubmission]:一个表单中的错误不会出现在另一个表单中。

  • 第 60–67 行:读取账户,并将其值复制到模型中(包括版本号);
  • 第 74 行:修改之后,服务器返回更新后的用户(并已颁发新的令牌):导航栏必须随之更新;
  • 第 83 行:提交被拒绝后,清除当前密码。我们更新的是字段(而不是整个表单):只有该字段的错误消失;其他错误仍然显示;
  • 第 87–98 行:确认后删除账户。服务器已删除令牌 Cookie:用户被遗忘,页面返回登录页面。
<div class="row justify-content-center">
  <div class="col-md-8 col-lg-6">
    <!-- 1. 更新 -->
    <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. 删除 -->
    <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 - 错误页面:404(未知地址)或 403
// (角色不足,参见 guards.ts)。相当于 views/error.hbs。
// 代码从路由的 data(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'));
}

错误页面,403 或 404:错误码作为输入从路由数据传入([data.code])。