Skip to content

11. 案例研究:RdvMedecins 应用程序

11.1. 问题描述

RdvMedecins 应用程序管理一家医疗诊所的预约。每位医生都有若干时间段(例如,从上午 8:00 到中午 12:00,每 20 分钟一个时间段);一个预约由日期、时间段和客户(患者)构成。这是对上一课中 [Symfony] 应用程序在 [Django] 中的精确移植(而上一课的应用程序本身又是从 [Laravel]、[Flask]、[Spring MVC] 和 [ASP.NET Core MVC] 版本移植而来):相同的数据库、相同的业务规则、相同的页面、相同的 URL、相同的文本。HTML 页面由服务器使用 [Django] 的模板生成;对数据库的访问通过 [Django] 的 ORM 进行。

应用程序由三种用户角色共用:

角色
对象
权限
ADMIN
管理员([admin])
查看日程,为任何患者预约和取消预约;管理(列出、添加、编辑、删除)医生和患者
DOCTOR
医生
查看日程,为任何患者预约和取消预约
USER
客户(患者)
查看日程但看不到其他患者的姓名;为自己预约;取消自己的预约;管理自己的账户;创建账户

主要管理规则:

  • 不能预约过去的时间;
  • 同一时间段在一天内只能被预约一次;
  • 一名患者同一时间只能有一个未来的预约;
  • 两名医生(或两名客户)不能有相同的名和姓,一个登录名只属于一个账户;
  • 有预约的医生不能被删除;客户被删除时,其预约一并删除;
  • 登录页面带有防机器人保护(验证码、限制尝试次数),创建患者账户需要先在该页面上通过验证码。

11.2. 使用应用程序

11.2.1. 登录页面

Image

该页面有两个按钮:登录和创建患者账户。两者都要求输入图像中显示的字符。FR / EN 按钮用于切换语言:

Image

错误(此处是验证码输入错误)显示在页面底部,背景为浅粉色:

Image

11.2.2. 管理员和医生看到的日历

登录后,管理员会进入日历页面。他们选择一位医生和一个日期:

Image

Image

每个时间段要么可预约(预约按钮),要么已被占用(患者姓名、取消按钮)。点击“预约”会打开一个窗口,要求输入患者信息。该窗口与页面的其余部分一样由服务器生成:URL 现在包含参数 [book=5],即所选时间段的编号:

Image

预约之后,一条消息会确认该预约:

Image

点击“取消”会弹出确认提示(这里是 Pélissier 医生,其导航栏中没有管理菜单):

Image

11.2.3. 患者门户

患者(角色 USER)进入“我的空间”:显示其未来的预约(可以取消),以及管理账户和查看日历的链接。这里,他们还没有预约:

Image

在日历中,他们看不到其他患者的姓名;这些姓名被替换为“Booked”:这个名称甚至不会出现在页面的源代码中。他们可以预约一个可用的时间段:

Image

预约窗口不会提示他选择患者:他是为自己预约。

Image

Image

他的仪表板现在显示其未来的预约,他可以取消它:

Image

由于他已有一个未来的预约,因此不能再预约另一个:“预约”按钮不会显示,而在另一天或另一位医生的日历上,会有一条消息说明原因:

Image

账户管理:编辑个人信息、修改密码,或删除账户(及其预约)。任何更改都需要输入当前密码:

Image

患者试图打开为管理员保留的页面(这里是手动输入的 [/doctors])时,会收到一个错误页面:

Image

11.2.4. 管理医生和患者

管理员多了两个菜单:医生和患者:

Image

Image

添加医生的表单,提交时带有错误:

Image

与现有医生同名的姓名会被拒绝,即使是用小写字母且带重音书写的也一样(数据库本身在比较姓名时不区分大小写和重音;参见示例 28):

Image

删除患者需要确认:

Image

11.2.5. 创建患者账户

在登录页面上,只有正确输入验证码,“创建患者账户”按钮才会打开表单:

Image

账户创建之后,用户被重定向到登录页面,其用户名已预先填好:

Image

11.2.6. 注销

登录令牌的有效期为两小时。超过这个时间(或者令牌被篡改),请求的页面会重定向到登录页面,并显示如下消息:

Image

11.3. 安装与运行

应用程序位于 [rdvmedecins2-django] 文件夹中,与 [examples] 文件夹相邻。它是一个独立的项目,有自己的 [requirements.txt] 和 [.env] 文件,以及自己的虚拟环境。该文件夹中的 [README.md] 文件包含以下全部内容。本文档的引言部分已经介绍过安装;这里我们补充更多细节。

11.3.1. 所需软件

两个软件包就足够了:

  • [Python] 3.12 或更高版本([Django] 6.1 需要 [Python] 3.12)。在终端中验证安装:
python --version
  • 在 [Linux] 和 [macOS] 下,该命令通常称为 [python3]。在 [Linux] 下,编译 [mysqlclient] 还需要一些系统软件包(参见附录);
  • 一个 [MySQL] 8.4 或更高版本的服务器,例如在 [Windows] 下运行的 [Laragon] 自带的服务器(参见附录)。[MariaDB] 10.11 或更高版本也可以。这些是 [Django] 6.1 要求的最低版本:对于 [MySQL] 8.0,[Django] 会拒绝连接([MySQL 8.4 or later is required])。

推荐的编辑器是 [Visual Studio Code],并安装扩展 [Python] 和 [Django] (参见附录);不过,所有操作都可以通过命令行完成。

11.3.2. 安装库

这些库并未随附:在应用程序文件夹中一次性创建一个虚拟环境,并在打开到 [rdvmedecins2-django] 文件夹的终端中把库安装到该环境中(必须连接互联网):

1
2
3
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

(在 [Linux] 和 [macOS] 下,第二条命令写作 [source .venv/bin/activate])。[pip] 读取文件 [requirements.txt] (下文讨论),下载 [Django]、[mysqlclient]、[PyJWT]、[bcrypt] 以及它们所依赖的库,并把它们安装到 [.venv] 文件夹中。每打开一个新终端都必须激活该环境(选定环境的解释器之后,[Visual Studio Code] 会自动完成这一步;参见引言)。

11.3.3. 创建数据库

[dbrdvmedecins2] 数据库由 [database/dbrdvmedecins2.sql] 脚本创建。使用 [Laragon] 时,打开 [HeidiSQL] 工具(数据库按钮),然后通过“文件 / 运行 SQL 文件”菜单运行该脚本(参见引言)。在命令行中,在应用程序文件夹下执行:

mysql -u root -p < database/dbrdvmedecins2.sql

选项 [-p] 会提示输入 [root] 的密码;如果该账户没有密码([Laragon] 就是这种情况),则省略它。这与应用程序其他版本使用的是同一个数据库:如果它已经存在,这一步是可选的。该脚本可以随时运行,以恢复为原始数据。

11.3.4. 配置数据库访问

所有安装配置都包含在文件 [.env] 中(下文将进一步讨论)。默认情况下,应用程序连接到 [MySQL] ,主机为 [127.0.0.1],端口 3306,使用用户 [root] 且无密码:这些是 [Laragon] 的默认设置。如果你的 [root] 账户有密码,请把它填写在该文件的 [DB_PASSWORD=] 一行中。系统环境变量优先于该文件(示例 25):这样就可以指定密码而不必把它写入项目文件。

11.3.5. 运行应用程序

在打开到 [rdvmedecins2-django] 文件夹的终端窗口中,激活虚拟环境后执行:

python manage.py runserver 8081
1
2
3
4
5
6
7
8
Watching for file changes with StatReloader
Performing system checks...

System check identified no issues (0 silenced).
September 27, 2026 - 19:30:12
Django version 6.1.1, using settings 'config.settings'
Starting WSGI development server at http://127.0.0.1:8081/
Quit the server with CONTROL-C.

然后,在浏览器中打开 URL [http://localhost:8081] ,并使用 [Ctrl-C] 停止应用程序。使用端口 8081 可以让你同时运行一个课程示例(端口 8000);应用程序的其他版本也使用端口 8081:不要同时运行它们。

11.3.6. 演示账户

每个账户的密码就是它的用户名;你还必须输入图像中显示的字符,大小写均可:

用户名
角色
[admin]
ADMIN(管理员)
[pelissier]、[tatou]、[dupont]
DOCTOR(医生)
[martin]、[durand]、[bistrou]、[german]
USER(患者)

探索该应用的指南:

  • [admin]:日程,Marie PELISSIER 女士,今天:有一个时间段已被 Brigitte BISTROU 女士预约。为 Jean MARTIN 先生预约一个时间段,然后试着再为他预约第二个预约(会被拒绝)。医生和患者菜单:添加、编辑、删除(有预约的 PELISSIER 医生无法删除);
  • [pelissier]:直接显示他的当日日程;手动输入的地址 [/doctors] 会返回 403 错误页面;
  • [martin]:我的空间,他的预约,其他患者显示为“Booked”的日历(查看页面的源代码:其中不会出现他们的姓名);管理我的账户;
  • 登录页面:创建患者账户,然后用新账户登录;
  • FR / EN 按钮:整个界面切换语言,包括日期。

11.3.7. 开发模式

随附的 [.env] 文件把应用程序配置为开发模式([DJANGO_DEBUG=1]):

  • 服务器控制台显示每个请求以及发送到数据库的每条 SQL 命令(示例 28)。例如,显示一个日历时(在打开连接的两条命令之后,示例 28;各行有所省略):
1
2
3
4
(0.000) SELECT `doctors`.`id`, ..., `users`.`role` FROM `doctors` INNER JOIN `users` ON (`doctors`.`user` = `users`.`id`) WHERE `doctors`.`id` = 1 ORDER BY `doctors`.`id` ASC LIMIT 1; args=(1,); alias=default
(0.003) SELECT `appointments`.`id`, ..., `clients`.`user` FROM `appointments` INNER JOIN `slots` ON (`appointments`.`slot_id` = `slots`.`id`) INNER JOIN `clients` ON (`appointments`.`client_id` = `clients`.`id`) WHERE (`appointments`.`day` = '2026-09-28' AND `slots`.`doctor_id` = 1); args=('2026-09-28', 1); alias=default
(0.000) SELECT `slots`.`id`, ..., `slots`.`end_minute` FROM `slots` WHERE `slots`.`doctor_id` = 1 ORDER BY `slots`.`start_hour` ASC, `slots`.`start_minute` ASC; args=(1,); alias=default
[27/Sep/2026 19:50:21] "GET /schedule?doctorId=1&day=2026-09-28 HTTP/1.1" 200 9186

这里可以识别出三个请求:医生及其账户(一次联接)、今天的预约及其患者,以及该医生的可用时间段。不过,下拉菜单中的医生列表并没有被检索;它来自缓存(见下文)。已登录的用户同样没有被检索;他们由其令牌标识(示例 25);

  • 发生意外异常时,会显示 [Django] 的调试页面(示例 03),其中包含异常消息和调用栈。在生产环境中,应用程序则会显示它自己的 500 错误页面;
  • 修改之后无需重启任何东西:当 [Python] 文件发生变化时,开发服务器会自动重启(示例 01),而被修改的模板会在下一个请求时重新读取。

[Python] 扩展在 [Visual Studio Code] 中的调试器也允许你单步调试应用程序:只需要一个“Django”风格的启动配置(文件 [.vscode/launch.json],扩展会提供创建它的选项),参数为 [runserver 8081 --noreload]。[django-debug-toolbar] 扩展(通过 [pip] 安装)会在每个页面旁边显示请求的详细信息:SQL 命令及其耗时、所用的模板、设置、信号……

11.3.8. 生产服务器

[Django] 开发服务器不适用于生产环境。在生产环境中,应用程序由 WSGI 服务器提供服务(示例 01):在 [Linux] 下用 [gunicorn] ([gunicorn config.wsgi:application --workers 4]),在 [Windows] 下用 [waitress] ([waitress-serve --port=8081 config.wsgi:application]),通常位于 Web 服务器([nginx]、[Apache])之后,由它接收 HTTPS 连接、自己提供静态文件,并把其余请求委托给 WSGI 服务器。在 [.env] 文件中,必须指定生产模式、更改密钥、声明站点名称,并说明站点通过 HTTPS 提供服务:

1
2
3
4
5
DJANGO_DEBUG=0
DJANGO_SECRET_KEY=a-long-random-string
DJANGO_ALLOWED_HOSTS=rdvmedecins.example.com
JWT_SECRET=another-long-random-string
COOKIE_SECURE=1

可以用 [Python] 本身得到合适的随机字符串:[python -c "import secrets; print(secrets.token_hex(32))"]。然后用两条命令准备应用程序:

python manage.py collectstatic
python manage.py check --deploy

第一条命令把所有静态文件(应用程序的静态文件和 [Django] 的静态文件)复制到 [var/static] 文件夹(设置 [STATIC_ROOT]),由 Web 服务器提供服务(示例 15)。第二条命令检查部署的安全设置,并指出缺失的设置(HSTS 头、到 HTTPS 的重定向等)。要用不再提供静态文件的开发服务器测试生产模式:[python manage.py runserver 8081 --insecure]。

11.3.9. 常见问题

使用 [MySQL] 时,[runserver] 命令在启动时就会连接数据库:它的项目检查(系统检查,示例 01)需要知道服务器的版本。因此,无法访问的数据库会使它无法启动:控制台会显示一长串调用栈,最后以该错误结束。例如,数据库不存在时:

django.db.utils.OperationalError: (1049, "Unknown database 'dbrdvmedecins2'")

生产服务器([gunicorn]……)不会执行这些检查:此时错误会出现在第一个查询数据库的页面的日志中(登录页面本身不查询数据库;登录过程才会查询)。最常见的消息:

消息
原因
[ModuleNotFoundError: No module named 'django']
虚拟环境未启用,或者 [pip install -r requirements.txt] 尚未执行
[Django 6.1 requires Python 3.12 or later] (安装期间)
[Python] 的版本低于 3.12
[OperationalError: (2002, "Can't connect to server on '127.0.0.1' ...")]
[MySQL] 未启动,或者没有监听 [127.0.0.1:3306]
[OperationalError: (1045, "Access denied for user 'root'@'localhost' ...")]
必须在 [MySQL] 的密码 [DB_PASSWORD] 中填写(参见“配置数据库访问”)
[OperationalError: (1049, "Unknown database 'dbrdvmedecins2'")]
脚本 [database/dbrdvmedecins2.sql] 尚未执行
[NotSupportedError: MySQL 8.4 or later is required]
[MySQL] 服务器版本过旧:请升级到 [MySQL] 8.4 或 [MariaDB] 10.11
[ImproperlyConfigured: JWT_SECRET must be at least 32 characters long (see .env).]
[.env] 中的令牌密钥太短
[Error: That port is already in use.]
端口 8081 已被占用(是否正在运行应用程序的另一个版本?):请停止它,或选择其他端口

11.4. 应用程序架构

Image

  • 浏览器把请求发送给服务器([runserver],或 [nginx] + [gunicorn]),服务器再通过 [config/wsgi.py] 文件中的 WSGI 应用程序把请求转发给 [Django] 。请求依次经过各个中间件层(参见关于生命周期的章节):请求语言([SetLanguage])、防 CSRF 保护、闪现消息,然后是身份验证:根据 Cookie 中的 JWT 令牌识别用户([Authentication]);路由之后,[AccessControl] 对未获授权的访问者拒绝其访问受保护页面。错误由 HTML 页面处理([ErrorPage]以及错误视图);
  • [web]:Web 层。视图([web/views]),每个模块一组页面,以及它们的路由([web/urls.py]);表单及其约束([web/forms.py]);模板模型([web/view_models.py])。它们都通过一个单一的对象 [ApplicationModel] ([web/application.py]),它缓存医生和客户的列表,并把其他请求转发给业务层;
  • [security]:JWT 令牌、身份验证和访问控制中间件、验证码、尝试次数限制,以及账户创建通行证;
  • [business]:业务规则和事务;[domain]:日历对象,由业务层计算;
  • [dao]:DAO 层,每张表(或每组表)一个模块;
  • [models]:ORM 的模型(示例 28),DAO 层通过它们从数据库读取数据并向数据库写入数据;
  • [templates]:模板,用于生成 HTML 页面;[locale]:法语词典;[static]:样式表、页面脚本,以及 [Bootstrap];
  • [config] 文件夹和 [.env] 文件:把一切整合在一起的配置。

应用程序文件夹(不包括 [.venv] 和 [var]):

rdvmedecins2-django/
├── business/
│   ├── README.md
│   ├── __init__.py
│   ├── business.py
│   ├── dates.py
│   ├── descriptor.py
│   ├── errors.py
│   ├── person_data.py
│   ├── provider.py
│   └── service.py
├── config/
│   ├── __init__.py
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
├── dao/
│   ├── README.md
│   ├── __init__.py
│   ├── appointments.py
│   ├── persons.py
│   ├── slots.py
│   └── users.py
├── database/
│   ├── README.md
│   └── dbrdvmedecins2.sql
├── domain/
│   ├── README.md
│   ├── __init__.py
│   └── schedule.py
├── locale/
│   └── fr/
│       └── LC_MESSAGES/
│           ├── django.mo
│           └── django.po
├── models/
│   ├── README.md
│   ├── __init__.py
│   ├── apps.py
│   └── models.py
├── security/
│   ├── README.md
│   ├── __init__.py
│   ├── access.py
│   ├── auth.py
│   ├── captcha_drawing.py
│   ├── captchas.py
│   ├── connected_user.py
│   ├── errors.py
│   ├── limiter.py
│   ├── middleware.py
│   ├── passwords.py
│   └── registration_pass.py
├── static/
│   ├── css/
│   │   └── styles.css
│   ├── js/
│   │   └── app.js
│   └── lib/
│       └── bootstrap/
├── templates/
│   ├── forms/
│   │   └── field.html
│   ├── fragments/
│   │   ├── booking.html
│   │   ├── captcha.html
│   │   ├── confirmation.html
│   │   ├── errors.html
│   │   ├── navbar.html
│   │   └── success.html
│   ├── persons/
│   │   ├── form.html
│   │   └── list.html
│   ├── README.md
│   ├── account.html
│   ├── area.html
│   ├── error.html
│   ├── layout.html
│   ├── login.html
│   ├── macros.html
│   ├── registration.html
│   └── schedule.html
├── web/
│   ├── templatetags/
│   │   ├── __init__.py
│   │   └── rdv.py
│   ├── views/
│   │   ├── README.md
│   │   ├── __init__.py
│   │   ├── area.py
│   │   ├── auth.py
│   │   ├── errors.py
│   │   ├── language.py
│   │   ├── persons.py
│   │   ├── registration.py
│   │   └── schedule.py
│   ├── README.md
│   ├── __init__.py
│   ├── application.py
│   ├── apps.py
│   ├── contexts.py
│   ├── forms.py
│   ├── middleware.py
│   ├── rendering.py
│   ├── urls.py
│   ├── utils.py
│   └── view_models.py
├── .env
├── .gitignore
├── README.md
├── manage.py
└── requirements.txt

这是一个典型的 [Django] 项目的结构(示例 01):一个配置包([config])、一个 [manage.py] 文件,以及若干代码包。其中只有两个是在 [Django] 应用,在 [INSTALLED_APPS] 中声明:[models],因为它包含 ORM 的模型([Django] 只在应用中查找模型),以及 [web],因为它包含一个标签库([templatetags],示例 16)。其他的([dao]、[business]、[security]、[domain])只是被其他包导入的 [Python] 包:它们无需向 [Django] 声明任何内容。[Django] 并不强制要求这些文件夹,典型的项目反而会按领域(日历、账户等)各设一个应用,每个应用有自己的模型、视图和模板;与案例研究的其他版本一样,我们更倾向于按层组织,如示例 28 所示。[Bootstrap] 这次是应用程序的一部分(文件夹 [static/lib/bootstrap]):案例研究是自包含的。

11.5. 数据库

[dbrdvmedecins2] 数据库有五张表:

  • [users]:获准登录的用户;
  • [doctors] 和 [clients]:医生和患者,各自关联到其用户账户;
  • [slots]:每位医生的可用时间段;
  • [appointments]:预约,在某一天内每个时间段对应一位客户。

11.5.1. database/dbrdvmedecins2.sql

-- =========================================================================
-- Database [dbrdvmedecins2] - MySQL 8
--
-- Evolution of [dbrdvmedecins]:
--   1. the [doctors] and [clients] tables get a [user] column,
--      foreign key to users(id): every doctor and every client is
--      now also a user able to log in;
--   2. a third role appears: DOCTOR (in addition to ADMIN and USER);
--   3. the script creates a [users] row for each doctor (role DOCTOR)
--      and for each client (role USER):
--        - login        = last name in lower case
--        - password     = last name in lower case, hashed with bcrypt (10 rounds)
--        - display name = first name + last name
--
--   4. uniqueness constraints, all NAMED (the application recognizes
--      the name of the violated constraint in the MySQL error message):
--        - unq_users_login                   : a login belongs to one account only;
--        - unq_doctors_first_name_last_name  : two doctors cannot have the
--                                              same first and last names;
--        - unq_clients_first_name_last_name  : same for the clients.
--      Beware: the utf8mb4_unicode_ci collation compares regardless of
--      case and accents - "Hélène DUPONT" and "helene dupont"
--      are therefore considered identical.
--
-- The [users] table must now be created BEFORE [doctors] and [clients]
-- (they reference it), and dropped AFTER them.
-- =========================================================================

-- the script is written in UTF-8
SET NAMES utf8mb4;

-- we start again from an empty database on each run of the script (handy in development)
CREATE DATABASE IF NOT EXISTS dbrdvmedecins2 CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
USE dbrdvmedecins2;

-- drop order: from the "child" tables to the "parent" tables
DROP TABLE IF EXISTS appointments;
DROP TABLE IF EXISTS slots;
DROP TABLE IF EXISTS clients;
DROP TABLE IF EXISTS doctors;
DROP TABLE IF EXISTS users;

-- -------------------------------------------------------------------------
-- table [users]: the users allowed to log in to the application
-- -------------------------------------------------------------------------
CREATE TABLE users (
  id       INT AUTO_INCREMENT PRIMARY KEY,
  version  INT NOT NULL DEFAULT 0,
  login    VARCHAR(30) NOT NULL,                 -- login identifier
  password VARCHAR(100) NOT NULL,                -- HASHED password (bcrypt) - never in clear
  name     VARCHAR(40) NOT NULL,                 -- name displayed once logged in
  role     VARCHAR(10) NOT NULL,                 -- 'ADMIN', 'DOCTOR' or 'USER'
  -- a login can belong to one account only
  CONSTRAINT unq_users_login UNIQUE (login)
);

-- -------------------------------------------------------------------------
-- table [doctors]: the doctors of the practice
-- -------------------------------------------------------------------------
CREATE TABLE doctors (
  id         INT AUTO_INCREMENT PRIMARY KEY,   -- primary key (technical identifier)
  version    INT NOT NULL DEFAULT 0,            -- row version number (optimistic lock)
  title      VARCHAR(5)  NOT NULL,              -- Melle, Mme, Mr
  last_name  VARCHAR(20) NOT NULL,
  first_name VARCHAR(20) NOT NULL,
  `user`     INT NOT NULL,                      -- foreign key -> users(id)
  CONSTRAINT fk_doctors_user FOREIGN KEY (`user`) REFERENCES users(id),
  -- one account per doctor, and one doctor per account
  CONSTRAINT unq_doctors_user UNIQUE (`user`),
  -- two doctors cannot have the same first and last names
  CONSTRAINT unq_doctors_first_name_last_name UNIQUE (first_name, last_name)
);

-- -------------------------------------------------------------------------
-- table [clients]: the doctors' patients
-- -------------------------------------------------------------------------
CREATE TABLE clients (
  id         INT AUTO_INCREMENT PRIMARY KEY,
  version    INT NOT NULL DEFAULT 0,
  title      VARCHAR(5)  NOT NULL,
  last_name  VARCHAR(20) NOT NULL,
  first_name VARCHAR(20) NOT NULL,
  `user`     INT NOT NULL,                      -- foreign key -> users(id)
  CONSTRAINT fk_clients_user FOREIGN KEY (`user`) REFERENCES users(id),
  -- one account per client, and one client per account
  CONSTRAINT unq_clients_user UNIQUE (`user`),
  -- two clients cannot have the same first and last names
  CONSTRAINT unq_clients_first_name_last_name UNIQUE (first_name, last_name)
);

-- -------------------------------------------------------------------------
-- table [slots]: the time slots of each doctor
-- -------------------------------------------------------------------------
CREATE TABLE slots (
  id           INT AUTO_INCREMENT PRIMARY KEY,
  version      INT NOT NULL DEFAULT 0,
  doctor_id    INT NOT NULL,                     -- foreign key -> doctors(id)
  start_hour   INT NOT NULL,                     -- start hour of the slot
  start_minute INT NOT NULL,                     -- start minute of the slot
  end_hour     INT NOT NULL,                     -- end hour of the slot
  end_minute   INT NOT NULL,                     -- end minute of the slot
  CONSTRAINT fk_slots_doctor FOREIGN KEY (doctor_id) REFERENCES doctors(id)
);

-- -------------------------------------------------------------------------
-- table [appointments]: the appointments booked by the clients
-- -------------------------------------------------------------------------
CREATE TABLE appointments (
  id         INT AUTO_INCREMENT PRIMARY KEY,
  version    INT NOT NULL DEFAULT 0,
  day        DATE NOT NULL,                      -- day of the appointment
  slot_id    INT NOT NULL,                       -- foreign key -> slots(id)
  client_id  INT NOT NULL,                       -- foreign key -> clients(id)
  CONSTRAINT fk_appointments_slot   FOREIGN KEY (slot_id)   REFERENCES slots(id),
  CONSTRAINT fk_appointments_client FOREIGN KEY (client_id) REFERENCES clients(id),
  -- the same slot, on the same day, can be booked only once
  CONSTRAINT unq1_appointments UNIQUE (day, slot_id)
);

-- =========================================================================
-- Demo data
-- =========================================================================

-- the users: passwords hashed with bcrypt (10 salt rounds)
--   admin/admin (ADMIN)
--   one DOCTOR account per doctor, one USER account per client
--   (the user/user demo account is gone: a USER account is
--   now ALWAYS a client's account, who can book and manage the account)
--   (login = password = last name in lower case)
INSERT INTO users (login, password, name, role) VALUES
  ('admin',     '$2b$10$YSNBJXXHX9mp13nPZb6YGu8M1jR6uvPwO1s2X73z0QAqBR7TOQjoq', 'Administrator',    'ADMIN'),
  -- doctors
  ('pelissier', '$2b$10$DnSDOK5ONrdMxTTr1NKCHOphR3WSp5QAyG9S9ueruw9HwlxI.16ba', 'Marie PELISSIER',  'DOCTOR'),
  ('tatou',     '$2b$10$PeovBO.gmJUKP4PglI/fwu4xtWOYSxoM5VTWjTj7uQ4wcd9P9.htS', 'Paul TATOU',       'DOCTOR'),
  ('dupont',    '$2b$10$az7wvPKC1h0EiAxXwu/PU.vYjzmB04rd5B7QnK0mvxp4niYIHVoc.', 'Sophie DUPONT',    'DOCTOR'),
  -- clients
  ('martin',    '$2b$10$GT6S5pp.WdGapFw/UmocXesbC6LEjJfZzgatCUyG9Sf4o1iBNlqZW', 'Jean MARTIN',      'USER'),
  ('durand',    '$2b$10$l2gl/zCder8E7Nh4VxGRX.0.SsO3FDiXt6YwqYq3v9nFzgC/jQCy6', 'Alice DURAND',     'USER'),
  ('bistrou',   '$2b$10$naeRp2YUU6c.QDl5itJMAum3Y5aHdUV6jwIcsbp0D.64jPG4F6E9m', 'Brigitte BISTROU', 'USER'),
  ('german',    '$2b$10$tTWxh3ROWF7NjhZOMnWDMOsZcnSWUiwwfy5C3G0.xhccTXALKyLeW', 'Luc GERMAN',       'USER');

-- the doctors: the [user] column is looked up from the login,
-- rather than assuming the values of the primary keys of [users]
INSERT INTO doctors (title, last_name, first_name, `user`) VALUES
  ('Mme',  'PELISSIER', 'Marie',  (SELECT id FROM users WHERE login = 'pelissier')),
  ('Mr',   'TATOU',     'Paul',   (SELECT id FROM users WHERE login = 'tatou')),
  ('Melle','DUPONT',    'Sophie', (SELECT id FROM users WHERE login = 'dupont'));

INSERT INTO clients (title, last_name, first_name, `user`) VALUES
  ('Mr',   'MARTIN',  'Jean',     (SELECT id FROM users WHERE login = 'martin')),
  ('Mme',  'DURAND',  'Alice',    (SELECT id FROM users WHERE login = 'durand')),
  ('Melle','BISTROU', 'Brigitte', (SELECT id FROM users WHERE login = 'bistrou')),
  ('Mr',   'GERMAN',  'Luc',      (SELECT id FROM users WHERE login = 'german'));

-- slots of doctor PELISSIER (doctor_id = 1): from 8:00 to 12:00 in 20-minute steps
INSERT INTO slots (doctor_id, start_hour, start_minute, end_hour, end_minute) VALUES
  (1, 8, 0, 8, 20), (1, 8, 20, 8, 40), (1, 8, 40, 9, 0),
  (1, 9, 0, 9, 20), (1, 9, 20, 9, 40), (1, 9, 40, 10, 0),
  (1, 10, 0, 10, 20), (1, 10, 20, 10, 40), (1, 10, 40, 11, 0),
  (1, 11, 0, 11, 20), (1, 11, 20, 11, 40), (1, 11, 40, 12, 0);

-- slots of doctor TATOU (doctor_id = 2): from 14:00 to 18:00 in 20-minute steps
INSERT INTO slots (doctor_id, start_hour, start_minute, end_hour, end_minute) VALUES
  (2, 14, 0, 14, 20), (2, 14, 20, 14, 40), (2, 14, 40, 15, 0),
  (2, 15, 0, 15, 20), (2, 15, 20, 15, 40), (2, 15, 40, 16, 0),
  (2, 16, 0, 16, 20), (2, 16, 20, 16, 40), (2, 16, 40, 17, 0),
  (2, 17, 0, 17, 20), (2, 17, 20, 17, 40), (2, 17, 40, 18, 0);

-- an appointment already booked, to see an occupied slot right away in the schedule
INSERT INTO appointments (day, slot_id, client_id) VALUES
  (CURDATE(), 2, 3);
  • 第 33 行:如果数据库不存在就创建它,字符集为 [utf8mb4] ,排序规则为 [utf8mb4_unicode_ci],比较字符串时不区分大小写和重音(示例 28);
  • 第 37–41 行:先删除各表再重新创建;该脚本会把数据库恢复到初始状态。顺序很重要:只要另一张表通过外键引用某张表,就不能删除这张表;
  • 第 46–55 行:users:登录名、由 [bcrypt] 哈希的密码(示例 25)、登录后显示的名称,以及角色([ADMIN]、[DOCTOR]或 [USER])。约束 [unq_users_login] 确保一个用户名只属于一个账户;
  • 第 60–72 行:每张表都有一个由数据库生成的主键 [id],以及一个列 [version],即乐观锁(示例 28)。列 [user] 是指向 [users(id)] 的外键:数据库会拒绝任何不是现有用户 ID 的值。由于 [user] 是 SQL 语言中的单词,所以用反引号括起来。三个约束:[fk_doctors_user] (外键)、[unq_doctors_user] (每位医生一个账户,每个账户一位医生),以及 [unq_doctors_first_name_last_name] (不允许同名者)。所有约束都有名称:应用程序通过名称识别被违反的约束;
  • 第 77–89 行:[clients] 表的列与之完全相同;
  • 第 94–103 行:时间段属于某位医生;其开始和结束时间以小时和分钟存储;
  • 第 108–118 行:预约由日期(类型 [DATE],不含时间)、时间段和客户构成。约束 [unq1_appointments] 防止同一时间段在同一天被预约两次:即使两名用户同时尝试预约,数据库也会强制执行这一规则;
  • 第 130–140 行:演示用户,其密码就是其登录名。哈希以 [$2b$10$] 开头:算法([bcrypt],变体 [2b])和成本(10:2^10 轮计算)。接下来是盐(22 个字符)和哈希。这些哈希由应用程序的 [Flask] 版本使用 [bcrypt] 库(来自 [Python],本版本同样使用它)计算得出;
  • 第 144–147 行:每位医生的 [user] 列通过基于登录名的子查询获得,而不是假定主键的值;
  • 第 170–171 行:在 PELISSIER 医生的第二个时间段为 BISTROU 女士安排了一个今天([CURDATE()])的预约:这样,日历立即就能显示该时间段已被预约。

与 [Django] 的惯常情况不同,数据库不是由 [Django] 的迁移创建的(示例 28):它与应用程序的其他版本共用,SQL 脚本对所有版本都是通用的。因此,模型被声明为 [managed = False],[python manage.py makemigrations] 命令无事可做。[python manage.py inspectdb] 命令用于将数据库与模型进行比较。

11.6. 项目配置

11.6.1. requirements.txt

1
2
3
4
5
# 应用的库:pip install -r requirements.txt
Django==6.1.1
mysqlclient==2.3.0
PyJWT==2.15.0
bcrypt==5.0.0

应用程序所需的四个库,带有确切的版本(参见引言):[Django]、[MySQL] 驱动([mysqlclient],示例 28)、JWT 令牌库([PyJWT],示例 25),以及用于数据库密码的 [bcrypt](见下文)。[pip] 还会安装它们所依赖的库([asgiref] 和 [sqlparse],是 [Django] 的依赖)。命令 [pip freeze] 会输出环境中已安装内容的确切列表,包括依赖项:这是获得锁定所有版本的文件的方法。较大的项目会使用项目管理工具,例如 [uv] 或 [Poetry],它们把所请求的库(文件 [pyproject.toml])与实际安装的确切版本(锁文件,例如 [composer.lock] 之于 [PHP])分开。

11.6.2. .env

# =========================================================================
# .env:专属于本次安装的设置,由
# config/settings.py 在启动时读取。每一行 NAME=value 都会成为进程的
# 一个环境变量;系统中真实的环境变量
# 优先于此文件。
# =========================================================================

# 1:开发(详细的错误页面);0:生产(见 README.md)
DJANGO_DEBUG=1
# Django 的密钥(签名、防 CSRF 令牌等)。生产环境中:使用另一个
# 值,要长且随机
DJANGO_SECRET_KEY=Hayf1oPBd4cm9qXHUGusMtUqCFqEyyj1nnwGxKvuJKYI0EDjjn
# 应用同意为其提供服务的主机名(以逗号分隔)
DJANGO_ALLOWED_HOSTS=localhost,127.0.0.1

# —— MySQL 数据库 [dbrdvmedecins2](脚本:database/dbrdvmedecins2.sql):
# 服务器、其端口、数据库、用户及其密码(Laragon 的设置:
# root,无密码)
DB_HOST=127.0.0.1
DB_PORT=3306
DB_NAME=dbrdvmedecins2
DB_USER=root
DB_PASSWORD=

# —— 身份验证(见 security/auth.py)
# JWT 令牌的密钥:至少 32 个字符(HMAC-SHA256)
JWT_SECRET=229b83fd9cc502aaebd911d2662753a8393b340edb296724
# 令牌的有效时长,以分钟为单位(120 分钟 = 2 小时)
JWT_DURATION_MINUTES=120
# 生产环境中为 1(站点通过 HTTPS 提供):Cookie 绝不以未加密方式传输
COOKIE_SECURE=0

# —— 防机器人保护(见 security/limiter.py)
# 同一 IP 地址对同一登录名允许的登录失败次数,之后
# 在该时长内封锁(以分钟为单位);若一个 IP 地址累计
# LOGIN_MAX_FAILURES_IP 次失败(所有登录名合计),该地址同样会被封锁(机器人会尝试
# 成千上万个不同的登录名)
LOGIN_MAX_FAILURES=5
LOGIN_MAX_FAILURES_IP=25
LOGIN_BLOCK_MINUTES=15
# 每个 IP 地址每小时最多创建的客户账户数。在教室里,所有
# 计算机通常通过同一个地址出网:必要时请调大
REGISTRATION_MAX_PER_HOUR=10

该文件包含特定于本次安装的设置(示例 25):这些设置因机器而异(数据库及其凭据),或者是机密(密钥)。在真实项目中,这个文件绝不会随代码一起发布:每次安装都有自己的文件,生产环境的机密通常通过真正的环境变量提供。[Django] 自身并不读取 [.env] 文件:由 [config/settings.py] 文件读取它(稍后介绍)。[python-dotenv] 库也能做同样的事,而 [django-environ] 还会增加值的转换功能。

  • 第 9 行:调试模式(示例 01):开发期间为 1(详细的错误页面、控制台中的 SQL 命令),生产环境中为 0;
  • 第 12 行:[Django] 的密钥,用于防 CSRF 令牌(示例 18)和所有签名(签名 Cookie、闪现消息,示例 20 和 23);
  • 第 14 行:接受的主机名(示例 01);
  • 第 19–23 行:数据库连接(示例 28);
  • 第 25–43 行:应用程序专用的设置:JWT 令牌(示例 25)、把 Cookie 设为 [Secure] 模式(稍后讨论),以及防机器人保护(示例 27)。

11.6.3. config/settings.py

设置文件包含全部配置,用 [Python] 编写(示例 01):

# =========================================================================
# config/settings.py:RdvMedecins 应用的配置。
#
# 专属于某次安装的设置(密码、密钥、阈值)
# 从环境变量中读取,开发环境中由 .env 文件提供
# 这些变量(见 read_env)。其余内容都写在这里。
# =========================================================================

import os
from pathlib import Path

# 项目文件夹(包含 manage.py 的那个)
BASE_DIR = Path(__file__).resolve().parent.parent


# -------------------------------------------------------------------------
# 读取 .env 文件:每一行 NAME=value 都会成为
# 环境变量,除非它已存在(setdefault):系统中真实的
# 环境变量优先于该文件。空行和
# 注释(#)会被忽略;值两侧的引号会被去掉
# -------------------------------------------------------------------------
def read_env(file: Path) -> None:
    if not file.exists():
        return
    for line in file.read_text(encoding="utf-8").splitlines():
        line = line.strip()
        if line and not line.startswith("#") and "=" in line:
            name, value = line.split("=", 1)
            os.environ.setdefault(name.strip(), value.strip().strip('"'))


read_env(BASE_DIR / ".env")


# 环境变量:文本、整数、布尔值(1/0)
def env(name: str, default: str = "") -> str:
    return os.environ.get(name, default)


def env_int(name: str, default: int) -> int:
    return int(env(name, str(default)))


def env_bool(name: str, default: bool) -> bool:
    return env(name, "1" if default else "0") == "1"


# —— 调试模式与安全
DEBUG = env_bool("DJANGO_DEBUG", False)
SECRET_KEY = env("DJANGO_SECRET_KEY")
ALLOWED_HOSTS = [h.strip() for h in env("DJANGO_ALLOWED_HOSTS", "localhost").split(",")]

# —— 应用:Django 自身(静态文件、闪现消息、
# 表单),以及我们的两个应用:models(各表)和 web(
# 模板标签)。其他文件夹(dao、business、security 等)是
# 普通的 Python 包:它们既没有模型也没有模板
INSTALLED_APPS = [
    "django.contrib.staticfiles",
    "django.contrib.messages",
    "django.forms",
    "models",
    "web",
]

# —— 中间件,按顺序排列(见示例 24):
#   - SetLanguage:请求的语言(Cookie rdvmedecins_language);
#   - CsrfViewMiddleware:每个 POST 请求的防 CSRF 令牌;
#   - MessageMiddleware:闪现消息;
#   - Authentication:用户,根据其 Cookie 中的 JWT 令牌确定;
#   - AccessControl:每个 URL 的访问规则(路由之后);
#   - ErrorPage:错误变成应用的页面
MIDDLEWARE = [
    "web.middleware.SetLanguage",
    "django.middleware.csrf.CsrfViewMiddleware",
    "django.contrib.messages.middleware.MessageMiddleware",
    "security.middleware.Authentication",
    "security.middleware.AccessControl",
    "web.middleware.ErrorPage",
]

ROOT_URLCONF = "config.urls"
WSGI_APPLICATION = "config.wsgi.application"

# —— 数据库:MySQL(或 MariaDB),dbrdvmedecins2 数据库
DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.mysql",
        "HOST": env("DB_HOST", "127.0.0.1"),
        "PORT": env("DB_PORT", "3306"),
        "NAME": env("DB_NAME", "dbrdvmedecins2"),
        "USER": env("DB_USER", "root"),
        "PASSWORD": env("DB_PASSWORD"),
        "OPTIONS": {"charset": "utf8mb4"},
    },
}

# —— 缓存:var/cache 文件夹的文件,由服务器的所有
# 进程共享(验证码、失败计数器、通行证、医生和客户
# 列表)。内存缓存(LocMemCache)会专属于
# 每个进程:生产服务器会启动多个进程
CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.filebased.FileBasedCache",
        "LOCATION": BASE_DIR / "var" / "cache",
    },
}

# —— 模板(templates 文件夹)及其上下文处理器
TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [BASE_DIR / "templates"],
        "APP_DIRS": True,
        "OPTIONS": {
            "context_processors": [
                "django.template.context_processors.request",
                "django.template.context_processors.i18n",
                "django.contrib.messages.context_processors.messages",
                # 已登录的用户,在所有模板中可用(见 web/contexts.py)
                "web.contexts.user",
            ],
        },
    },
]

# 表单字段使用 Bootstrap 5 的类来绘制(见
# 示例 18 和 templates/forms/field.html)
FORM_RENDERER = "web.rendering.BootstrapRenderer"

# —— 语言(见示例 22):默认英语,另有法语;
# 词典位于 locale 文件夹
LANGUAGE_CODE = "en"
LANGUAGES = [("fr", "Français"), ("en", "English")]
LOCALE_PATHS = [BASE_DIR / "locale"]
# 记住所选语言的 Cookie(见 web/views/language.py)
LANGUAGE_COOKIE_NAME = "rdvmedecins_language"

# —— 时区:医疗诊所所在的时区。它决定今天的日期(不允许
# 预约过去的时间,见 business/dates.py)
TIME_ZONE = "Europe/Paris"
USE_TZ = True

# —— 静态文件(static 文件夹):Bootstrap、样式表、脚本
STATIC_URL = "static/"
STATICFILES_DIRS = [BASE_DIR / "static"]
# 在生产环境中,collectstatic 会把所有静态文件收集到那里(见 README.md)
STATIC_ROOT = BASE_DIR / "var" / "static"

# —— 闪现消息:放在带签名的 Cookie 中(见示例 20)
MESSAGE_STORAGE = "django.contrib.messages.storage.cookie.CookieStorage"

# —— Cookie:页面的 JavaScript 绝不可读(HttpOnly,甚至包括
# Django 默认保持可读的防 CSRF Cookie),来自其他站点的
# POST 请求绝不会携带(Lax),生产环境中绝不以未加密方式传输(Secure)
COOKIE_SECURE = env_bool("COOKIE_SECURE", False)
CSRF_COOKIE_NAME = "rdvmedecins_csrf"
CSRF_COOKIE_SECURE = COOKIE_SECURE
CSRF_COOKIE_HTTPONLY = True
CSRF_COOKIE_SAMESITE = "Lax"
# 缺失或错误的防 CSRF 令牌:我们的 419 错误页面(见 web/views/errors.py)
CSRF_FAILURE_VIEW = "web.views.errors.csrf_rejected"

# —— 我们自己的设置:身份验证(见 security/auth.py)……
JWT_SECRET = env("JWT_SECRET")
JWT_DURATION_MINUTES = env_int("JWT_DURATION_MINUTES", 120)
# ……以及防机器人保护(见 security/limiter.py)
LOGIN_MAX_FAILURES = env_int("LOGIN_MAX_FAILURES", 5)
LOGIN_MAX_FAILURES_IP = env_int("LOGIN_MAX_FAILURES_IP", 25)
LOGIN_BLOCK_MINUTES = env_int("LOGIN_BLOCK_MINUTES", 15)
REGISTRATION_MAX_PER_HOUR = env_int("REGISTRATION_MAX_PER_HOUR", 10)

# —— 日志:在调试模式下,发送给数据库的 SQL 语句会写入
# 控制台(见示例 28)
LOGGING = {
    "version": 1,
    "disable_existing_loggers": False,
    "handlers": {"console": {"class": "logging.StreamHandler"}},
    "loggers": {
        "django.db.backends": {"handlers": ["console"], "level": "DEBUG"},
    },
}
  • 第 22–32 行:读取文件 [.env]。[read_text] 读取整个文件,而 [splitlines] 把它拆分成行。除注释外,每一行 [NAME=value] 都会成为该进程的一个环境变量([split("=", 1)]:只在第一个 [=] 处拆分,因为值本身可能包含它)。[setdefault] 不会覆盖已存在的变量:真正的环境变量优先于该文件(示例 25);
  • 第 36–45 行:三个小函数,读取环境变量(带默认值)并进行转换(转换为整数,或值为 1 或 0 的布尔值);
  • 第 49–51 行:调试模式、密钥和主机名,从环境中读取。如果 [.env] 不存在,调试模式就被禁用:这是安全的选择。[ALLOWED_HOSTS] 是一个列表,由以逗号分隔的名称字符串构造而成;
  • 第 57–63 行:应用(参见架构部分):来自 [Django] 的三个应用(静态文件,示例 15;闪现消息,示例 20;表单模板,示例 18)以及我们自己的两个;
  • 第 72–79 行:六个中间件,按请求经过它们的顺序排列(示例 24)。顺序很重要:首先设置语言,使所有页面——包括错误页面——都使用正确的语言;防 CSRF 保护先于身份验证;身份验证(识别用户)先于访问控制(评估用户);而 [ErrorPage] 是最后一个,却是第一个处理视图所抛出异常的([process_exception] 按相反的顺序调用,示例 24);
  • 第 85–95 行:数据库(示例 28),其参数来自环境;
  • 第 101–106 行:应用程序缓存(示例 27)。它以文件形式([FileBasedCache])存储在 [var/cache] 文件夹中,该文件夹由 [Django] 自己创建:与示例 27 中的内存缓存不同,它在服务器重启后依然存在(在开发服务器上,每次修改代码后都会重启),并且在生产服务器上由所有进程共享(参见关于作用域的章节)。应用程序在这个缓存中存储医生和客户列表、验证码、尝试次数计数器以及通行证。如果有多台服务器,则应选择共享缓存,例如 [Redis];
  • 第 109–124 行:模板(示例 13),包括应用的模板目录([APP_DIRS],对于 [django.forms] 中的模板,见示例 18),以及四个上下文处理器:请求、语言(示例 22)、闪现消息(示例 20),还有我们自己的处理器,它使已登录用户对所有模板可用(见下文);
  • 第 128 行:表单渲染引擎,使用来自 [Bootstrap] 的类(示例 18);
  • 第 132–136 行:语言和词典(示例 22)。语言 Cookie 使用应用专属的名称;
  • 第 140–141 行:事务所的时区。[USE_TZ = True] (默认值)使 [Django] 以协调世界时(UTC)运行,并在显示时将时间转换为该时区;[timezone.localdate()] 返回该时区的当前日期。当前日期用于一条业务规则(不得预约过去的时间):在巴黎,夏令时期间的午夜至凌晨 2:00 之间,协调世界时的日期仍是前一天;因此以事务所的时区为准;
  • 第 144–147 行:静态文件(示例 15):应用的 [static] 文件夹,以及 [collectstatic] 为生产环境收集这些文件的文件夹;
  • 第 150 行:闪现消息,存放在签名的 Cookie 中(示例 20);
  • 第 155–161 行:[Django] 的 Cookie。[COOKIE_SECURE] 从 [.env] 中读取,也将用于我们自己的 Cookie(令牌、语言等):在生产环境的 HTTPS 下,不会以明文传输任何 Cookie。防 CSRF 令牌 Cookie 使用应用专属的名称;它被设置为 [HttpOnly] (页面上的 [JavaScript] 不需要它:它自己不发送任何请求)和 [SameSite=Lax]。缺失或无效的防 CSRF 令牌将显示应用自己的页面(见下文),而不是 [Django] 的 403 页面(示例 18);
  • 第 164–170 行:应用专属的设置,从环境变量中读取:JWT 令牌(示例 25)和机器人防护(示例 27);
  • 第 174–181 行:SQL 命令日志,在调试模式下(示例 28)。

[python manage.py diffsettings] 命令显示所有与 [Django] 默认值不同的设置。

11.6.4. config/urls.py

# config/urls.py:主路由表

from django.urls import include, path

urlpatterns = [
    path("", include("web.urls")),
]

# Django 自己生成的错误页面的视图(见 web/views/errors.py):
# 在调试模式下,Django 会用自己的详细页面替换
# 400、404 和 500 错误的页面
handler400 = "web.views.errors.error_400"
handler403 = "web.views.errors.error_403"
handler404 = "web.views.errors.error_404"
handler500 = "web.views.errors.error_500"

应用的所有路由都在文件 [web/urls.py] 中(Web 层,稍后讨论),挂载在站点根路径下(示例 04)。[Django] 自己生成的四个错误页面视图(示例 24)在此处用字符串(函数的完整路径)指定:[Django] 会自行导入它们。

11.7. 启动应用

11.7.1. manage.py 和 config/wsgi.py

文件 [manage.py] 和 [config/wsgi.py] 来自示例 01:命令行工具,以及应用的 WSGI 入口,由开发服务器和生产服务器启动。启动时,[Django] 读取设置([config/settings.py] 文件再读取 [.env] 文件),加载 [INSTALLED_APPS] 中的应用(它们的模型、配置,示例 24),为每个中间件组件创建一个对象(示例 03),然后等待请求。启动时构建的所有对象在进程运行期间由所有请求共享:这适用于唯一的应用对象(业务层、[ApplicationModel] 外观),它们由各自的提供者在首次使用时创建(示例 06)。

启动时会检查两件事,出错将在处理任何请求之前关闭服务器:JWT 令牌密钥(过短则被拒绝;见 [security/auth.py]),以及使用 [MySQL] 时的数据库连接(见“常见问题”)。

11.8. 模型

ORM 的模型(示例 28):每张表一个类,位于 [models/models.py] 文件中,属于 [models] 应用。

11.8.1. models/apps.py

1
2
3
4
5
6
7
# models/apps.py:models 应用的配置

from django.apps import AppConfig


class ModelsConfig(AppConfig):
    name = "models"

应用配置(示例 24),仅保留名称。它不是必需的:[Django] 会自动生成一个;我们写出它,是为了让每个应用都有自己的配置。

11.8.2. models/models.py

# =========================================================================
# models/models.py:Django 模型,dbrdvmedecins2 数据库中
# 每张表对应一个类(见示例 28)。
#
# 这些表已经存在:它们由脚本
# database/dbrdvmedecins2.sql 创建,与应用其他版本使用的脚本相同。
# 每个模型通过 managed = False 告知 Django 这一点:Django 绝不
# 创建、修改或删除这些表(没有迁移)。
#
# 外键(ForeignKey、OneToOneField)以
# on_delete=DO_NOTHING 声明:删除某一行时,Django 不会自己去查找
# 引用它的行。由业务层按正确的
# 顺序删除必须删除的内容(见 business/service.py);
# 数据库约束无论如何都会拒绝不完整的删除。
#
# 所有表都有一个 [version] 列:乐观锁,DAO
# 层在其 UPDATE 中使用它(见 dao/persons.py)。
# =========================================================================

from django.db import models


# 用户的三种角色(列 users.role):
#   - ADMIN  :管理员 - 预约 + 医生和客户的管理;
#   - DOCTOR :医生 - 预订和取消预约;
#   - USER   :客户(患者)- 为自己预订,管理自己的账户。
# TextChoices:Django 枚举,其每个值都是字符串(即
# 存储在数据库中的那个);Role("ADMIN") 则是反向转换
class Role(models.TextChoices):
    ADMIN = "ADMIN"
    DOCTOR = "DOCTOR"
    USER = "USER"


# 允许登录的用户(表 [users])。每位医生和每位
# 客户都拥有自己的账户(表 [doctors] 和 [clients] 的 [user] 列)。
# SQL 唯一性约束:unq_users_login(一个登录名只属于一个
# 账户),在业务层中通过其名称识别(见 business/service.py)
class User(models.Model):
    id = models.AutoField(primary_key=True)
    version = models.IntegerField(default=0)
    login = models.CharField(max_length=30)
    # 密码的哈希值(bcrypt),绝不是密码本身
    password = models.CharField(max_length=100)
    # 登录后显示的名称:"Marie PELISSIER"
    name = models.CharField(max_length=40)
    # choices:该列的可能取值
    role = models.CharField(max_length=10, choices=Role.choices)

    class Meta:
        db_table = "users"
        managed = False

    def __str__(self):
        return self.login


# -------------------------------------------------------------------------
# 医生(表 [doctors])和客户(表
# [clients])的共同点:称谓、姓、名,以及关联的
# 用户账户([user] 列)。
#
# 这两张表的列完全相同:它们在这个抽象模型中只描述一次
# (abstract = True:"Person" 绝不会被创建,
# 也没有自己的表),Doctor 和 Client 继承它;各自只指定
# 自己的表名。
#
# 注意:这里的 [Client] 指的是医疗诊所的患者,而不是 HTTP
# 客户端!这是原始业务领域的词汇,保持不变。
# -------------------------------------------------------------------------
class Person(models.Model):
    id = models.AutoField(primary_key=True)
    version = models.IntegerField(default=0)
    # Mr, Mme, Melle
    title = models.CharField(max_length=5)
    last_name = models.CharField(max_length=20)
    first_name = models.CharField(max_length=20)
    # 与用户账户的关系:一个人只有一个账户,由
    # 外键 [user](db_column)指定。OneToOneField:每人一个账户,
    # 每个账户一个人。person.account 返回一个 User 对象,首次访问时从数据库读取,
    # 或者在查询本身要求时一并读取(select_related,见
    # dao/persons.py)。related_name:反向关系的名称,
    # user.doctor 或 user.client(%(class)s:模型的名称,小写)
    account = models.OneToOneField(User, db_column="user", on_delete=models.DO_NOTHING,
                                   related_name="%(class)s")

    class Meta:
        abstract = True

    # "Mme Alice DURAND"
    def label(self) -> str:
        return f"{self.title} {self.first_name} {self.last_name}"

    def __str__(self):
        return self.label()


# 一位医生(表 [doctors])。SQL 唯一性约束:unq_doctors_first_name_last_name
# (两位医生不能有相同的名和姓)
class Doctor(Person):
    class Meta:
        db_table = "doctors"
        managed = False


# 一位客户,也就是一位患者(表 [clients])。SQL 唯一性约束:
# unq_clients_first_name_last_name
class Client(Person):
    class Meta:
        db_table = "clients"
        managed = False


# 医生的一个时间段(表 [slots]):8:00 - 8:20,等等。这些
# 时间段由 SQL 脚本创建:应用只读取它们
class Slot(models.Model):
    id = models.AutoField(primary_key=True)
    version = models.IntegerField(default=0)
    # 同一位医生的多个时间段:一个外键,[doctor_id]
    doctor = models.ForeignKey(Doctor, db_column="doctor_id", on_delete=models.DO_NOTHING,
                               related_name="slots")
    start_hour = models.IntegerField()
    start_minute = models.IntegerField()
    end_hour = models.IntegerField()
    end_minute = models.IntegerField()

    class Meta:
        db_table = "slots"
        managed = False

    # "8:00 - 8:20";:02d:两位数字,"8:05" 而不是 "8:5"
    def time_range(self) -> str:
        return f"{self.start_hour}:{self.start_minute:02d} - {self.end_hour}:{self.end_minute:02d}"


# 一个预约(表 [appointments]):某位客户,在某个时间段,某一天。
# SQL 唯一性约束:unq1_appointments (day, slot_id) - 一个时间段每天
# 只能被预订一次;在业务层中通过其名称识别
class Appointment(models.Model):
    id = models.AutoField(primary_key=True)
    version = models.IntegerField(default=0)
    # DateField:[day] 列(SQL 类型 DATE)变成 Python 的 date 对象
    day = models.DateField()
    slot = models.ForeignKey(Slot, db_column="slot_id", on_delete=models.DO_NOTHING,
                             related_name="appointments")
    client = models.ForeignKey(Client, db_column="client_id", on_delete=models.DO_NOTHING,
                               related_name="appointments")

    class Meta:
        db_table = "appointments"
        managed = False
  • 第 29–32 行:三种角色,以 [Django] 枚举的形式定义([models.TextChoices]),它本身建立在 [Python] 的枚举([enum] 模块)之上:这是一种类型,其唯一可能的值就是它的成员:[Role.ADMIN]、[Role.DOCTOR]和 [Role.USER]。每个成员都有一个值,这里是基础字符串;[TextChoices] 的成员本身就是字符串:[Role.ADMIN == "ADMIN"] 为真。[Role("ADMIN")] 返回对应的成员(对于未知的值则抛出 [ValueError])。[Role.choices] 返回(值,标签)对的列表,可传给字段的 [choices] 参数;
  • 第 39–55 行:表 [users] 的结构:主键、版本号(乐观锁,示例 28),然后是各列。[choices] (第 48 行)记录该列的可能取值;[Django] 用它来依据该结构验证表单,并用于管理界面;数据库本身不做任何检查。[managed = False]:该表由 SQL 脚本创建(示例 28);
  • 第 71–95 行:表 [doctors] 和 [clients] 具有相同的列。它们共同的描述只写一次,放在一个抽象模型中([abstract = True],第 88 行):这种模型没有自己的表,只用于被继承。模型 [Doctor] 和 [Client] 继承它:每个都在自己的表中拥有 [Person] 的字段。([Django] 也支持真正的模型继承层次,其中每个子类都有一张与父类的表相关联的表;这里不是这种情况,两张表是相互独立的);
  • 第 84–85 行:与账户的关系。[OneToOneField]:一个人有一个账户,一个账户至多属于一个人。[db_column] 指明外键列 [user] (若无此参数,[Django] 会将其命名为 [account_id],即字段名后加 [_id])。[on_delete] 指定账户被删除时 [Django] 的行为:[DO_NOTHING],即什么也不做(第 10–14 行的注释解释了这一选择;[CASCADE] 还会删除该人员,而 [PROTECT] 则会拒绝删除)。属性 [account] 是一个 [User] 对象,而不是一个数字:这正是 ORM 的用途。当 ORM 读取一个人员时,如果查询指定了,它也会读取其账户([select_related];见 DAO 层);否则,它会在首次访问 [person.account] 时通过一次额外的查询获取。该数字本身始终可用,无需查询,名称为 [account_id]。[related_name] 指明反向关系:[user.doctor] 或 [user.client],即与某个账户关联的人员;[%(class)s] 会被替换为小写的模型名,这使继承该字段的两个模型各自得到不同的名称;
  • 第 91–95 行:人员的姓名,如“Ms. Alice DURAND”,所有页面都会使用;
  • 第 100–111 行:两个只指定自己的表的模型;其余一切都是继承的。[Client] 是诊所的患者,而不是 HTTP 客户端:这是原始业务领域的词汇,在应用的所有版本中都予以保留;
  • 第 116–133 行:一个预约时段。[ForeignKey] (第 120 行):同一位医生的多个预约时段,通过外键 [doctor_id];反向关系 [doctor.slots]返回医生的时段。方法 [time_range] 返回“8:00 - 8:20”:在 f-string 中,[{self.start_minute:02d}] 写出至少两位、以零填充的整数([8:05] 而不是 [8:5]);
  • 第 139–151 行:一次预约。列 [day] (SQL 类型 [DATE])变成 [date] 对象,属于 [Python] 类型([DateField]);[date] 对象是不可变的([day + timedelta(days=1)] 返回第二天,[day] 保持不变)。两个关系:一个指向时段,一个指向该预约的患者。

11.9. 领域:日程表

11.9.1. domain/schedule.py

# =========================================================================
# domain/schedule.py:医生某一天的日程。由业务层
# (BusinessService.get_doctor_day_schedule)计算出的"业务"对象,
# 它们不对应任何表,之后由日程视图(web/views/schedule.py)
# 格式化后供模板使用。
#
# frozen=True:属性由构造函数一次性设定 -
# 这正是计算出的对象所需要的,之后没有人会修改它。
# =========================================================================

from dataclasses import dataclass
from datetime import date

from models.models import Appointment, Doctor, Slot


# 一个时间段,以及在某一天可能预订在该时间段上的
# 预约(若时间段空闲则为 None)
@dataclass(frozen=True)
class DoctorDaySlot:
    slot: Slot
    appointment: Appointment | None


# 医生某一天的完整日程:其时间段的列表,
# 每个时间段要么空闲要么已被占用
@dataclass(frozen=True)
class DoctorDaySchedule:
    doctor: Doctor
    day: date
    doctor_day_slots: list[DoctorDaySlot]

两个不对应任何表的计算对象:某一天的一个时段及其可能的预约;一位医生某一天的日程,即其时段列表。它们是不可变的数据类(示例 03),属性带有类型:[Appointment | None] (一次预约,或者 [None] 表示空闲时段)、[list[DoctorDaySlot]] (时段列表)。[Python] 在运行时不验证这些类型,但编辑器([Pylance])和分析工具([mypy])会读取它们。

11.10. DAO 层

DAO 层(示例 28)集中存放查询:每张表一个模块(医生和患者共用一个),不含业务规则。它的方法不开启事务:业务层在自己的事务中调用它们。它们使用 ORM 的 [QuerySet] 编写(示例 28);其中的值是查询参数:不可能发生 SQL 注入。DAO 是类,业务层为每个 DAO 创建一个对象;它们没有状态:只是函数的集合。

11.10.1. dao/persons.py

# =========================================================================
# dao/persons.py:医生和客户共用的 DAO 层。
#
# 医生和客户的 DAO 本来会完全相同:PersonDao 类
# 只写一次。self.model 是所涉及的模型(Doctor 或
# Client):查询作用于它的表。
#
# 查询用 Django ORM 编写(见示例 28),由它翻译
# 成 SQL。值(名、姓等)成为 SQL 语句的参数:
# 没有字符串拼接,因此没有 SQL 注入。这些方法不开启
# 任何事务:由业务层在它自己的事务内部调用它们。
# =========================================================================

from django.db.models import F, QuerySet

from models.models import Client, Doctor, Person


class PersonDao:
    # model:模型的类,Doctor 或 Client(在 Python 中,类是
    # 和其他值一样的值,可以存放在变量中)
    def __init__(self, model: type[Person]):
        self.model = model

    # -----------------------------------------------------------------------
    # 对模型的表的查询,包含用户账户。
    # select_related("account"):与 [users] 表的 SQL 连接
    #   SELECT doctors.*, users.* FROM doctors INNER JOIN users ON ...
    # 账户由同一个查询一并加载。没有它,每次访问
    # person.account 都会触发它自己的查询
    # -----------------------------------------------------------------------
    def _query(self) -> QuerySet:
        return self.model.objects.select_related("account")

    # 按姓再按名排序的列表
    def list(self) -> list[Person]:
        return list(self._query().order_by("last_name", "first_name"))

    # 一个人员及其账户;若不存在则为 None
    def read(self, id: int) -> Person | None:
        return self._query().filter(id=id).first()

    # 用户账户为 [user_id] 的人员;account_id:外键
    # 本身的列,无需连接
    def read_by_user(self, user_id: int) -> Person | None:
        return self._query().filter(account_id=user_id).first()

    # 具有这个名和姓的人员,如果存在的话。比较
    # 由 MySQL 完成,因此使用数据库的排序规则(utf8mb4_unicode_ci:不区分
    # 大小写和重音)- 与 SQL 唯一性约束
    # 所用的规则完全相同
    def namesake(self, first_name: str, last_name: str) -> Person | None:
        return self._query().filter(first_name=first_name, last_name=last_name).first()

    # INSERT:由数据库生成 id,Django 将其存入创建的对象
    def add(self, title: str, last_name: str, first_name: str, account) -> Person:
        return self.model.objects.create(title=title, last_name=last_name, first_name=first_name, account=account)

    # -----------------------------------------------------------------------
    # 带乐观锁的 UPDATE(见示例 28):
    #   UPDATE doctors SET title = ?, last_name = ?, first_name = ?, version = version + 1
    #   WHERE id = ? AND version = ?
    # 若没有行被修改则返回 False:记录已发生变化(或已消失)
    # 自读取以来
    # -----------------------------------------------------------------------
    def update(self, id: int, version: int, title: str, last_name: str, first_name: str) -> bool:
        return self.model.objects.filter(id=id, version=version).update(
            title=title, last_name=last_name, first_name=first_name, version=F("version") + 1) == 1

    # DELETE FROM doctors WHERE id = ?
    def delete(self, id: int) -> None:
        self.model.objects.filter(id=id).delete()


# 医生的 DAO:一切都继承自 PersonDao
class DoctorDao(PersonDao):
    def __init__(self):
        super().__init__(Doctor)


# 客户的 DAO:即人员的 DAO,外加一个加锁方法
class ClientDao(PersonDao):
    def __init__(self):
        super().__init__(Client)

    # -----------------------------------------------------------------------
    # 在当前事务结束前,在某位客户的行上加锁
    # (SELECT ... FOR UPDATE),并返回其 id(若该客户不
    # 存在则为 None)。请求同一把锁的第二个事务会等待,直到
    # 第一个事务结束。select_for_update:Django 的
    # "悲观"锁,要求已打开的事务。
    # 用于预订预约(见 BusinessService.add_appointment):同一位患者的两个
    # 同时进行的预订因此会被依次处理,
    # 先后进行,第二个预订能看到第一个创建的预约。
    # values_list("id", flat=True):只取 id 这一列,不创建 Client 对象
    # -----------------------------------------------------------------------
    def lock(self, id: int) -> int | None:
        return Client.objects.select_for_update().filter(id=id).values_list("id", flat=True).first()
  • 第 19–23 行:医生和患者的 DAO 对象除了模型之外是相同的:[PersonDao] 类只创建一次,并在其构造函数中接收模型作为参数。[type[Person]] 是类(而非对象)的注解:[Person] 或其某个子类;
  • 第 32–33 行:基础查询,所有方法共用。[select_related("account")] 指示 ORM 通过连接同时获取每个人员的账户([INNER JOIN users];见上面的控制台输出):只需一次查询,而不是每人一次额外查询。如果没有它,显示带登录名的医生列表就需要先查询一次列表,再为每位医生各查询一次:这就是所谓的“N + 1 查询”问题,ORM 最常见的陷阱。方法名开头的下划线表示它是类的内部方法(示例 06);
  • 第 36–46 行:读取操作。[account_id] (第 46 行)指的是外键列本身:条件作用于人员表,无需连接;
  • 第 52–53 行:查找同名者。比较由 [MySQL] 使用数据库的排序规则执行:不区分大小写且忽略重音,与唯一性约束完全一致(示例 28);
  • 第 56–57 行:插入;[account] 是 [User] 的实例,它已经被插入;
  • 第 66–68 行:更新,带有乐观锁(示例 28):[update] 返回被修改的行数,如果版本号已变则为 0;
  • 第 71–72 行:删除,通过 [QuerySet]:[delete()] 对其指定的所有行发送一条 [DELETE];
  • 第 76–78 行:医生的 DAO,它继承了全部内容。[super().__init__(Doctor)] 用该模型调用父类的构造函数;
  • 第 82–98 行:患者的 DAO,多了一个方法。[select_for_update()] 会在查询中添加 [FOR UPDATE]:[MySQL] 会对读取的行加锁,直到当前事务结束。请求同一把锁的第二个事务会等待第一个事务完成。这是一种“悲观”锁:它阻塞事务,而不是像乐观锁那样事后检测冲突。它只允许在事务中使用(否则 ORM 会抛出异常)。[values_list("id", flat=True)] 只读取 [id] 列:得到整数列表,而不是对象。代码中的注释说明了这把锁的用途;我们在讨论业务层时会再回到这一点。

11.10.2. dao/slots.py

# dao/slots.py:时间段的 DAO 层

from models.models import Slot


class SlotDao:
    # 一个时间段及其医生(一次连接)
    def read(self, id: int) -> Slot | None:
        return Slot.objects.select_related("doctor").filter(id=id).first()

    # 某位医生的时间段,按时间顺序排列。doctor_id:外键的
    # 列,与一个 id 比较
    def list_by_doctor(self, doctor_id: int) -> list[Slot]:
        return list(Slot.objects.filter(doctor_id=doctor_id).order_by("start_hour", "start_minute"))

    # 删除某位医生的所有时间段(删除医生时):
    #   DELETE FROM slots WHERE doctor_id = ?
    def delete_by_doctor(self, doctor_id: int) -> None:
        Slot.objects.filter(doctor_id=doctor_id).delete()

医生的预约时段,按时间顺序排列;一个预约时段及其医生(连接查询);删除医生的预约时段(由于外键约束,这发生在删除医生之前)。

11.10.3. dao/appointments.py

# =========================================================================
# dao/appointments.py:预约的 DAO 层。
#
# [appointments] 表不直接引用医生:它通过时间段间接引用。
# 当过滤条件跟在关系之后时,Django ORM 会自己写出连接:
# slot__doctor_id(两个下划线:"该时间段的医生")。
# =========================================================================

from datetime import date

from models.models import Appointment, Client, Slot


class AppointmentDao:
    # 一个预约,及其客户和时间段
    def read(self, id: int) -> Appointment | None:
        return Appointment.objects.select_related("client", "slot").filter(id=id).first()

    # 某位医生在某一天的预约,连同其客户
    def doctor_day_appointments(self, doctor_id: int, day: date) -> list[Appointment]:
        return list(Appointment.objects.select_related("client")
                    .filter(day=day, slot__doctor_id=doctor_id))

    # -----------------------------------------------------------------------
    # 某位客户从 [since] 这一天起(含)的预约,按时间
    # 顺序排列,连同时间段以及该时间段的医生(两次连接:
    # select_related("slot__doctor"))。day__gte:day >= since(gte:
    # "greater than or equal",大于或等于)
    # -----------------------------------------------------------------------
    def client_upcoming_appointments(self, client_id: int, since: date) -> list[Appointment]:
        return list(Appointment.objects.select_related("slot__doctor")
                    .filter(client_id=client_id, day__gte=since)
                    .order_by("day", "slot__start_hour", "slot__start_minute"))

    # 某位客户从 [since] 这一天起(含)的预约数量:
    # count() 让数据库来计数(SELECT COUNT(*) ...)
    def count_client_upcoming(self, client_id: int, since: date) -> int:
        return Appointment.objects.filter(client_id=client_id, day__gte=since).count()

    # 某位医生的预约数量(过去的或未来的)
    def count_by_doctor(self, doctor_id: int) -> int:
        return Appointment.objects.filter(slot__doctor_id=doctor_id).count()

    # INSERT INTO appointments ...
    def add(self, day: date, slot: Slot, client: Client) -> Appointment:
        return Appointment.objects.create(day=day, slot=slot, client=client)

    def delete(self, id: int) -> None:
        Appointment.objects.filter(id=id).delete()

    # 删除某位客户的所有预约(过去的和未来的)
    def delete_by_client(self, client_id: int) -> None:
        Appointment.objects.filter(client_id=client_id).delete()
  • 第 20–22 行:医生某一天的预约。[appointments] 表不直接引用医生:[slot__doctor_id] (两个下划线)沿着关系找到时段,然后比较时段的 [doctor_id] 列。ORM 自己编写连接([INNER JOIN slots];见上面的控制台输出)。每个预约的患者由同一个查询获取;
  • 第 30–33 行:患者即将到来的预约。[select_related("slot__doctor")] 连接两张表:先是时段,再是该预约的医生(两次连接)。[day__gte]:后缀 [gte] (“大于或等于”,示例 28)使用 [>=] 进行比较。排序同样沿着关系进行;
  • 第 37–42 行:[count()] 统计基础查询的行数([SELECT COUNT(*)]),而无需读取各行;
  • 第 45–53 行:插入和删除。

11.10.4. dao/users.py

# dao/users.py:用户账户的 DAO 层。创建(或删除)
# 医生或客户的同时也会创建(或删除)其账户 - 见 business/service.py

from django.db.models import F

from models.models import User


class UserDao:
    # 如果没有用户使用该登录名,则为 None
    def read_by_login(self, login: str) -> User | None:
        return User.objects.filter(login=login).first()

    def add(self, login: str, hash: str, name: str, role: str) -> User:
        return User.objects.create(login=login, password=hash, name=name, role=role)

    # 带乐观锁的 UPDATE(见 dao/persons.py);hash 为 None 时:密码
    # 保持不变。**fields:字典,被“解包”为具名参数
    def update(self, id: int, version: int, login: str, name: str, hash: str | None) -> bool:
        fields = {"login": login, "name": name, "version": F("version") + 1}
        if hash is not None:
            fields["password"] = hash
        return User.objects.filter(id=id, version=version).update(**fields) == 1

    def delete(self, id: int) -> None:
        User.objects.filter(id=id).delete()

用户账户。修改操作(第 19–23 行)有一个可选参数:新密码的哈希值,或者 [None] 表示保留现有密码。要修改的列被组合成一个字典,由 [**fields] 作为命名参数传给 [update](字典的“解包”,示例 08)。

11.11. 业务层

业务层(示例 28):业务规则和事务。它对 Web 一无所知:没有请求、响应和模板。

11.11.1. business/dates.py

# business/dates.py:今天的日期。它用于业务规则(不能预约过去的
# 时间,每位患者只能有一个未来的预约),因此放在
# 业务层。Web 层复用它。

from datetime import date

from django.utils import timezone


# 今天,按应用的时区(TIME_ZONE 设置)计算
def today() -> date:
    return timezone.localdate()

今天的日期,按应用的时区计算([TIME_ZONE],见 [config/settings.py]):[timezone.localdate()] 先将协调世界时转换为该时区,再返回日期。当前日期用于两条业务规则(不得预约过去的时间、只能有一个即将到来的预约):因此在这里统一计算,只此一处。

11.11.2. business/errors.py

# =========================================================================
# business/errors.py:业务层在违反业务规则
# 时抛出的异常(登录名已被占用、医生仍有预约、
# 时段已被预约……)。
#
# 它带有一个代码(LOGIN_TAKEN……),Web 层可以据此判断,还带有
# 面向用户的消息。该消息会在显示时
# 按页面的语言翻译成法语或英语:gettext_lazy 返回
# “惰性”翻译,只有在请求其文本时才会计算
# (str),而不是在模块加载时(见示例 22 和 locale 文件夹)。
#
# BusinessError 不是异常故障:它是一种正常的应答(“该登录名
# 已被使用”),会显示给用户。任何其他异常才是真正的
# 故障,最终会进入 500 错误页面。
# =========================================================================

from django.utils.translation import gettext_lazy as _

# 业务错误的代码
LOGIN_TAKEN = "LOGIN_TAKEN"
DOCTOR_ALREADY_EXISTS = "DOCTOR_ALREADY_EXISTS"
CLIENT_ALREADY_EXISTS = "CLIENT_ALREADY_EXISTS"
DOCTOR_HAS_APPOINTMENTS = "DOCTOR_HAS_APPOINTMENTS"
SLOT_ALREADY_BOOKED = "SLOT_ALREADY_BOOKED"
CONCURRENT_UPDATE = "CONCURRENT_UPDATE"
DOCTOR_NOT_FOUND = "DOCTOR_NOT_FOUND"
CLIENT_NOT_FOUND = "CLIENT_NOT_FOUND"
PAST_DATE = "PAST_DATE"
PATIENT_HAS_APPOINTMENT = "PATIENT_HAS_APPOINTMENT"

# 每个代码对应的消息
MESSAGES = {
    LOGIN_TAKEN: _("This login is already used by another account."),
    DOCTOR_ALREADY_EXISTS: _("A doctor with this first and last name already exists."),
    CLIENT_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)."),
    CLIENT_NOT_FOUND: _("This patient does not exist (any more)."),
    PAST_DATE: _("Appointments cannot be booked for a past date."),
    PATIENT_HAS_APPOINTMENT: _("This patient already has an upcoming appointment: it must be cancelled "
                               "before booking another one."),
}


class BusinessError(Exception):
    def __init__(self, code: str):
        super().__init__(code)
        self.code = code

    # 消息,使用当前请求的语言;@property:写作
    # error.message,不带括号
    @property
    def message(self) -> str:
        return str(MESSAGES[self.code])
  • 第 20–29 行:业务错误代码和常量(示例 09)。Web 层可以检查错误代码,将其与表单中正确的字段关联起来(见下文);
  • 第 32–45 行:每个代码对应的消息,标记为“待翻译”。[gettext_lazy],以简短名称 [_] 导入(如示例 22 中所用),提供惰性翻译:一个仅在请求文本时才获取其译文的对象。标准翻译([gettext])会在模块加载时,即启动时,一次性以默认语言完成;而惰性翻译在每次显示内容时执行,使用当前请求的语言。并排书写的两个字符串会被 [Python] 连接起来(第 38 行);
  • 第 48–57 行:业务层异常(示例 28),它携带自己的代码。[message] 属性(示例 14)以请求的语言呈现消息;[str] 会强制执行惰性翻译。

[BusinessError] 不是错误:它是一种正常的响应(“此登录名已被使用”),会显示给用户。任何其他异常才是真正的错误,会导致 500 错误页面。

11.11.3. business/person_data.py

# business/person_data.py:在“医生”或“客户”表单中填写的数据,
# 由 Web 层传递给业务层

from dataclasses import dataclass


@dataclass(frozen=True)
class PersonData:
    title: str          # Mr, Mme, Melle
    last_name: str
    first_name: str
    # 创建时:可选(None),默认为小写的姓
    # 更新时:可选,缺省则登录名保持不变
    login: str | None = None
    # 创建时:可选,默认为登录名
    # 更新时:可选,缺省则密码保持不变
    password: str | None = None
    # 更新时:显示表单时记录的
    # 版本(乐观锁)
    version: int | None = None

人员的数据,由 Web 层传递给业务层(示例 28)。最后三个属性有默认值 [None]:它们是可选的。属性后面可以跟注释(第 9 行):注释从 [#] 延伸到行尾。

11.11.4. business/business.py

# =========================================================================
# business/business.py:业务层的契约:读取、日程、
# 预约、医生和客户的管理。
#
# 抽象类(ABC,见示例 06)描述一个类必须具备的
# 方法,但不说明如何实现。BusinessService(业务层)和
# ApplicationModel(Web 层的缓存)都继承自它;Python
# 会拒绝创建缺少抽象方法的类的对象。
#
# X | None:可能缺失的结果(不存在的医生……)。
# =========================================================================

from abc import ABC, abstractmethod
from datetime import date

from domain.schedule import DoctorDaySchedule
from models.models import Appointment, Client, Doctor, Slot

from .person_data import PersonData


class Business(ABC):
    # ———————————————— 读取
    @abstractmethod
    def get_all_clients(self) -> list[Client]: ...

    @abstractmethod
    def get_all_doctors(self) -> list[Doctor]: ...

    @abstractmethod
    def get_all_slots(self, doctor_id: int) -> list[Slot]: ...

    @abstractmethod
    def get_doctor_day_appointments(self, doctor_id: int, day: date) -> list[Appointment]: ...

    @abstractmethod
    def get_client_by_id(self, id: int) -> Client | None: ...

    @abstractmethod
    def get_doctor_by_id(self, id: int) -> Doctor | None: ...

    @abstractmethod
    def get_appointment_by_id(self, id: int) -> Appointment | None: ...

    @abstractmethod
    def get_slot_by_id(self, id: int) -> Slot | None: ...

    @abstractmethod
    def get_doctor_day_schedule(self, doctor_id: int, day: date) -> DoctorDaySchedule | None: ...

    # 客户(患者),其用户账户为 [user_id]
    @abstractmethod
    def get_client_by_user_id(self, user_id: int) -> Client | None: ...

    # 客户的预约,今天或未来的,附带时段和医生
    @abstractmethod
    def get_client_upcoming_appointments(self, client_id: int) -> list[Appointment]: ...

    # ———————————————— 预约(ADMIN、DOCTOR、USER)
    # 在以下情况抛出 BusinessError:
    #  - 日期已过(PAST_DATE);
    #  - 患者已有一个未来的预约(PATIENT_HAS_APPOINTMENT);
    #  - 该时段当天已被占用(SLOT_ALREADY_BOOKED)。
    @abstractmethod
    def add_appointment(self, day: date, slot: Slot, client: Client) -> Appointment: ...

    @abstractmethod
    def delete_appointment(self, appointment: Appointment) -> None: ...

    # ———————————————— 医生(ADMIN)
    # 创建医生及其用户账户(角色 DOCTOR)
    @abstractmethod
    def add_doctor(self, data: PersonData) -> Doctor: ...

    # 更新医生及其用户账户
    @abstractmethod
    def edit_doctor(self, id: int, data: PersonData) -> Doctor: ...

    # 删除医生、其时段及其账户 - 如果有预约则拒绝
    @abstractmethod
    def delete_doctor(self, id: int) -> None: ...

    # ———————————————— 客户
    # (由 ADMIN 执行;add_client 也用于患者注册,
    # edit_client 和 delete_client 由患者对自己的账户使用)
    # 创建客户及其用户账户(角色 USER)
    @abstractmethod
    def add_client(self, data: PersonData) -> Client: ...

    @abstractmethod
    def edit_client(self, id: int, data: PersonData) -> Client: ...

    # 删除客户、其账户及其所有预约(过去和未来的)
    @abstractmethod
    def delete_client(self, id: int) -> None: ...

业务层的契约,一个抽象类(示例 06):所有方法及其参数和类型,并在注释中说明它们所执行的规则。抽象方法的方法体可以与其签名写在同一行([: ...])。有两个类继承该契约:[BusinessService],即业务层本身,以及 [ApplicationModel],即 Web 层的外观(稍后讨论),因此在需要 [Business] 对象的任何地方,它都可以替代业务层。

11.11.5. business/descriptor.py

# business/descriptor.py:业务规则中区分医生和客户的
# 全部内容(见 business/service.py)。医生和客户遵循
# 相同的规则:公共代码只写一次,并由描述符进行参数化。

from collections.abc import Callable
from dataclasses import dataclass

from dao.persons import PersonDao


@dataclass(frozen=True)
class Descriptor:
    dao: PersonDao
    role: str                   # DOCTOR 或 USER
    not_found_code: str         # 如果此人不存在则报错
    already_exists_code: str    # 如果已存在相同的姓和名则报错
    # 可选(None):如果提供,只要该人员
    # 还有预约(count_appointments(id) > 0),就拒绝删除,并返回错误 has_appointments_code。
    # Callable[[int], int]:接收一个整数并返回一个整数的函数
    count_appointments: Callable[[int], int] | None
    has_appointments_code: str | None
    # 可选:必须在删除该人员之前删除的内容(通过外键
    # 引用该人员的行);接收其 id
    before_delete: Callable[[int], None] | None

医生和患者遵循相同的管理规则,只有少量细微差别:他们的账户角色、错误代码,以及什么会阻止或促成删除。描述符把这些细节集中在一起;通用代码位于 [BusinessService] 中,只定义一次,并接收描述符。最后三个属性是函数:[Callable[[int], int]] 声明一个接受整数并返回整数的函数(模块 [collections.abc] 提供这些抽象类型);[| None]:或者为空。

11.11.6. business/provider.py

# business/provider.py:业务层的提供者(见示例 06):
# 只有一个 BusinessService 对象,在第一个请求时创建,然后在服务器运行期间
# 由所有请求共享。它没有特定于某个请求的状态:
# 共享它是安全的,即使在多个线程之间也是如此

from functools import cache

from .service import BusinessService


@cache
def business() -> BusinessService:
    return BusinessService()

业务层提供者(示例 06):单个 [BusinessService] 对象,在第一个请求时创建,然后由所有请求共享。即使有多个执行线程(示例 20),这也是安全的:该对象没有特定于请求的状态(它的 DAO 对象也没有),并且每个线程都有自己的数据库连接([Django] 的 ORM 为每个执行线程打开一个连接)。

11.11.7. business/service.py

# =========================================================================
# business/service.py:业务层的实现。
#
# 医生和客户的管理遵循三条业务规则:
#
#   1. 一个人员(医生或客户)与其用户账户始终
#      同进退:它们一起创建、更新和删除,处于同一个
#      事务中 - 要么全部成功,要么什么都不写入;
#   2. 登录名在整个应用中唯一,并且两个医生(或两个
#      客户)不能有相同的名和姓;
#   3. 删除:
#      - 有预约的医生不能被删除(其患者
#        会在不知情的情况下失去预约):必须先
#        取消这些预约。其时间段随医生一起消失;
#      - 而客户则连同其所有预约(过去和未来的)一起消失 -
#        无论删除操作来自 ADMIN 还是患者本人。
#
# 此外还有两条预约规则,无论预约者的角色是什么
# (ADMIN、DOCTOR 或患者本人):
#   4. 不能预约过去的时间;
#   5. 一位患者同一时间只能有一个未来的预约。
#
# 医生和客户遵循完全相同的规则:公共代码只
# 写一次(_xxx_person 方法),并由一个描述符进行参数化,该描述符说明
# 处理的是哪种类型的人员。
#
# 事务由 _transaction 方法开启(位于文件末尾),
# 该方法还会把数据库报告的错误翻译为 BusinessError。
# =========================================================================

import re
from collections.abc import Callable
from datetime import date

from django.db import IntegrityError, transaction

from dao.slots import SlotDao
from dao.persons import ClientDao, DoctorDao
from dao.appointments import AppointmentDao
from dao.users import UserDao
from domain.schedule import DoctorDaySchedule, DoctorDaySlot
from models.models import Appointment, Client, Doctor, Person, Role, Slot
from security import passwords

from . import errors
from .dates import today
from .descriptor import Descriptor
from .person_data import PersonData
from .errors import BusinessError
from .business import Business

# -------------------------------------------------------------------------
# 数据库错误 -> BusinessError
#
# 当 UNIQUE 约束拒绝一次写入时,Django 会抛出 IntegrityError,
# 其消息来自 MySQL。消息中引用了约束的名称:
#   (1062, "Duplicate entry 'Marie-PELISSIER' for key 'doctors.unq_doctors_first_name_last_name'")
# (MySQL 8 会在名称前加上表名,MariaDB 则不会)。因此
# SQL 脚本为其所有约束命名。正则表达式 CONSTRAINT
# 提取该名称:(?:[^'.]*\.)? 跳过可选的前缀,([^']+) 捕获名称
# -------------------------------------------------------------------------
CONSTRAINT_ERRORS = {
    "unq_users_login": errors.LOGIN_TAKEN,
    "unq_doctors_first_name_last_name": errors.DOCTOR_ALREADY_EXISTS,
    "unq_clients_first_name_last_name": errors.CLIENT_ALREADY_EXISTS,
    "unq1_appointments": errors.SLOT_ALREADY_BOOKED,
}

CONSTRAINT = re.compile(r"for key '(?:[^'.]*\.)?([^']+)'")


# BusinessError CONCURRENT_UPDATE,在事务内部抛出,以便
# 回滚:某个 UPDATE 没有修改任何行(乐观锁)
class _StaleVersion(Exception):
    pass


class BusinessService(Business):
    # DAO,一次性创建;它们没有状态:每种 DAO 只用一个对象
    # 为所有请求服务
    def __init__(self):
        self.doctors = DoctorDao()
        self.clients = ClientDao()
        self.slots = SlotDao()
        self.appointments = AppointmentDao()
        self.users = UserDao()

        self.doctor = Descriptor(
            dao=self.doctors,
            role=Role.DOCTOR,
            not_found_code=errors.DOCTOR_NOT_FOUND,
            already_exists_code=errors.DOCTOR_ALREADY_EXISTS,
            # self.appointments.count_by_doctor:方法本身,不调用它(
            # 对象 self.appointments 的“绑定方法”,稍后才会调用)
            count_appointments=self.appointments.count_by_doctor,
            has_appointments_code=errors.DOCTOR_HAS_APPOINTMENTS,
            # 没有预约的医生可能仍有时间段:
            # 没有预约时这些时间段毫无意义,因此随医生一起删除(否则
            # 外键 slots.doctor_id 会禁止删除)
            before_delete=self.slots.delete_by_doctor)

        self.client = Descriptor(
            dao=self.clients,
            role=Role.USER,
            not_found_code=errors.CLIENT_NOT_FOUND,
            already_exists_code=errors.CLIENT_ALREADY_EXISTS,
            # 没有 count_appointments:客户的删除永远不会被拒绝;
            # 其预约(过去和未来的)随客户一起删除(否则
            # 外键 appointments.client_id 会禁止删除)
            count_appointments=None,
            has_appointments_code=None,
            before_delete=self.appointments.delete_by_client)

    # =======================================================================
    # 读取
    # =======================================================================

    def get_all_clients(self) -> list[Client]:
        return self.clients.list()

    def get_all_doctors(self) -> list[Doctor]:
        return self.doctors.list()

    def get_all_slots(self, doctor_id: int) -> list[Slot]:
        return self.slots.list_by_doctor(doctor_id)

    def get_doctor_day_appointments(self, doctor_id: int, day: date) -> list[Appointment]:
        return self.appointments.doctor_day_appointments(doctor_id, day)

    def get_client_by_id(self, id: int) -> Client | None:
        return self.clients.read(id)

    def get_doctor_by_id(self, id: int) -> Doctor | None:
        return self.doctors.read(id)

    def get_appointment_by_id(self, id: int) -> Appointment | None:
        return self.appointments.read(id)

    def get_slot_by_id(self, id: int) -> Slot | None:
        return self.slots.read(id)

    def get_client_by_user_id(self, user_id: int) -> Client | None:
        return self.clients.read_by_user(user_id)

    def get_client_upcoming_appointments(self, client_id: int) -> list[Appointment]:
        return self.appointments.client_upcoming_appointments(client_id, today())

    # 某医生在给定日期的日程:其时段,以及每个时段当天
    # 预约的情况(空闲则为 None)
    def get_doctor_day_schedule(self, doctor_id: int, day: date) -> DoctorDaySchedule | None:
        doctor = self.get_doctor_by_id(doctor_id)
        if doctor is None:
            return None
        # 字典推导式:时段编号 -> 该时段上预约的预约
        bookings = {a.slot_id: a for a in self.get_doctor_day_appointments(doctor_id, day)}
        # get(key):返回值,键不存在时返回 None
        doctor_day_slots = [DoctorDaySlot(slot, bookings.get(slot.id))
                            for slot in self.get_all_slots(doctor_id)]
        return DoctorDaySchedule(doctor, day, doctor_day_slots)

    # =======================================================================
    # 预约
    # =======================================================================

    # -----------------------------------------------------------------------
    # 在事务中预约:
    #   1. 不能预约过去的时间;
    #   2. 锁定患者所在的行(SELECT ... FOR UPDATE):如果同一
    #      患者同时预约两个时段(两个标签页、双击
    #      等……),第二个事务会等待第一个事务结束,然后看到
    #      它刚刚创建的预约;
    #   3. 每位患者只能有一个未来的预约;
    #   4. 最后是插入。如果该时段刚刚被另一位患者占用,
    #      则由 SQL 约束 unq1_appointments (day, slot_id) 拒绝
    #      插入 - 由 _transaction 翻译为 BusinessError。
    # 在方法内部定义的函数(work)可以看到
    # 该方法的变量(day、slot、client):这就是“闭包”
    # -----------------------------------------------------------------------
    def add_appointment(self, day: date, slot: Slot, client: Client) -> Appointment:
        def work():
            if day < today():
                raise BusinessError(errors.PAST_DATE)
            patient_id = self.clients.lock(client.id)
            if patient_id is None:
                raise BusinessError(errors.CLIENT_NOT_FOUND)
            if self.appointments.count_client_upcoming(patient_id, today()) > 0:
                raise BusinessError(errors.PATIENT_HAS_APPOINTMENT)
            return self.appointments.add(day, slot, client)
        return self._transaction(work)

    def delete_appointment(self, appointment: Appointment) -> None:
        # lambda:简化为一个表达式的匿名函数
        self._transaction(lambda: self.appointments.delete(appointment.id))

    # =======================================================================
    # 医生和客户 - 公共方法委托给公共
    # 方法,并传入合适的描述符
    # =======================================================================

    def add_doctor(self, data: PersonData) -> Doctor:
        return self._add_person(self.doctor, data)

    def edit_doctor(self, id: int, data: PersonData) -> Doctor:
        return self._edit_person(self.doctor, id, data)

    def delete_doctor(self, id: int) -> None:
        self._delete_person(self.doctor, id)

    def add_client(self, data: PersonData) -> Client:
        return self._add_person(self.client, data)

    def edit_client(self, id: int, data: PersonData) -> Client:
        return self._edit_person(self.client, id, data)

    # 客户、其账户及其所有预约(由 ADMIN 操作,或由患者本人
    # 在“管理我的账户”中操作:同一方法,同一规则)
    def delete_client(self, id: int) -> None:
        self._delete_person(self.client, id)

    # -----------------------------------------------------------------------
    # 创建:先创建用户账户,再创建人员(其通过外键 [user]
    # 引用该账户),在同一个事务中
    # -----------------------------------------------------------------------
    def _add_person(self, d: Descriptor, data: PersonData) -> Person:
        last_name = data.last_name.strip().upper()
        first_name = data.first_name.strip()
        # 数据库 dbrdvmedecins2 的规则:登录名 = 小写的姓,
        # 密码 = 登录名 - 除非 ADMIN(或患者)输入了其他值
        login = (data.login or last_name).lower()
        password = data.password or login

        def work():
            self._check_person_unique(d, first_name, last_name, None)
            self._check_login_free(login)
            account = self.users.add(login, passwords.hash_password(password), f"{first_name} {last_name}", d.role)
            return d.dao.add(data.title, last_name, first_name, account)
        return self._transaction(work)

    # -----------------------------------------------------------------------
    # 更新:人员及其账户(显示名称“名 姓(大写)”必须
    # 随之更新;登录名和密码仅在输入时才更改)。
    # -----------------------------------------------------------------------
    def _edit_person(self, d: Descriptor, id: int, data: PersonData) -> Person:
        def work():
            person = d.dao.read(id)
            if person is None:
                raise BusinessError(d.not_found_code)
            # 乐观锁:如果数据库中的版本不再是表单中的
            # 版本,说明在此期间有人修改了该记录 - 我们予以拒绝,
            # 而不是悄悄覆盖其修改
            if data.version is not None and data.version != person.version:
                raise BusinessError(errors.CONCURRENT_UPDATE)
            last_name = data.last_name.strip().upper()
            first_name = data.first_name.strip()
            self._check_person_unique(d, first_name, last_name, id)
            # 其账户:显示名称,以及(如果输入了)登录名和
            # 密码
            account = person.account
            login = data.login.lower() if data.login else account.login
            if login != account.login:
                self._check_login_free(login)
            hash = passwords.hash_password(data.password) if data.password else None
            # 带乐观锁的 UPDATE:如果记录(或账户)
            # 在上面的读取之后被修改,则不会修改任何行
            if not d.dao.update(id, person.version, data.title, last_name, first_name):
                raise _StaleVersion()
            if not self.users.update(account.id, account.version, login, f"{first_name} {last_name}", hash):
                raise _StaleVersion()
            # 重新读取的人员及其账户:已保存的值
            return d.dao.read(id)
        return self._transaction(work)

    # -----------------------------------------------------------------------
    # 删除,在同一个事务中,按外键
    # 要求的顺序:
    #   1. 如果仍有预约则可能拒绝(医生);
    #   2. 引用该人员的内容(医生的时段、
    #      客户的预约);
    #   3. 人员本身(其引用账户),然后是其账户。
    # -----------------------------------------------------------------------
    def _delete_person(self, d: Descriptor, id: int) -> None:
        def work():
            person = d.dao.read(id)
            if person is None:
                raise BusinessError(d.not_found_code)
            if d.count_appointments is not None and d.count_appointments(id) > 0:
                raise BusinessError(d.has_appointments_code)
            if d.before_delete is not None:
                d.before_delete(id)
            d.dao.delete(id)
            self.users.delete(person.account_id)
        self._transaction(work)

    # 拒绝同一类型的另一个人员已使用的名和姓
    # (current_id:正在更新的人员,他显然有权
    # 保留自己的名和姓;创建时为 None)
    def _check_person_unique(self, d: Descriptor, first_name: str, last_name: str,
                             current_id: int | None) -> None:
        namesake = d.dao.namesake(first_name, last_name)
        if namesake is not None and namesake.id != current_id:
            raise BusinessError(d.already_exists_code)

    def _check_login_free(self, login: str) -> None:
        if self.users.read_by_login(login) is not None:
            raise BusinessError(errors.LOGIN_TAKEN)

    # -----------------------------------------------------------------------
    # 在事务中运行 [work](transaction.atomic,见示例 28):
    # 如果函数正常结束,则提交事务(COMMIT);
    # 如果其中抛出异常(包括 BusinessError),则回滚
    # (ROLLBACK):不写入任何内容。
    #
    # “登录名空闲”和“名 + 姓唯一”的检查在写入之前进行,
    # 以便给出清晰的消息。但两个 ADMIN 可能
    # 同时保存相同的登录名(或相同的医生):在这种
    # 罕见情况下,由 SQL 唯一性约束拒绝第二次写入。
    # 同样,对同一记录的两次同时更新由
    # 乐观锁裁决。因此这些错误在事务外围被拦截,
    # 以翻译为 BusinessError。任何其他错误都是真正的故障:
    # 任其向上传播。
    # -----------------------------------------------------------------------
    def _transaction(self, work: Callable):
        try:
            with transaction.atomic():
                return work()
        except IntegrityError as e:
            # str(e):MySQL 的消息
            found = CONSTRAINT.search(str(e))
            if found and found.group(1) in CONSTRAINT_ERRORS:
                # from e:新异常保留引发它的那个异常的踪迹
                raise BusinessError(CONSTRAINT_ERRORS[found.group(1)]) from e
            raise
        except _StaleVersion as e:
            raise BusinessError(errors.CONCURRENT_UPDATE) from e

11.11.7.1. 依赖与描述符

  • 第 62–69 行:将数据库错误转换为业务错误(见下文“事务”);
  • 第 74–75 行:一个内部异常,用于表示没有任何效果的 [UPDATE] (乐观锁);
  • 第 81–86 行:DAO 对象,由构造函数一次性创建;
  • 第 88–112 行:两个描述符。这些函数是 DAO 的方法,不带括号传递(第 95 行):它们是绑定方法——保留对其对象引用的函数——稍后才会被调用([d.count_appointments(id)],第 286 行)。有预约的医生不能被删除;其时段随医生一起删除。患者与其预约一起删除。参数是具名的:可以立即看出每个值的用途。

11.11.7.2. 读取操作与日程表

  • 第 118–146 行:读取操作,委托给 DAO 层。当前日期在这里计算(第 146 行),而不是由 DAO 计算:这是一条业务规则(“即将到来的”);
  • 第 150–159 行:医生某一天的日程。一个只读字典(示例 18)将每个时段编号与当天该时段所预约的预约关联起来([a.slot_id]:外键,无需查询;见模板);然后,对医生的每个时段,取对应的预约,或者 [None]。无论有多少个时段,都只需两次查询:当天的预约和时段(外加医生的备注),如控制台所示(“开发模式”)。

11.11.7.3. 预约安排

  • 第 179–189 行:在事务中安排预约。在方法内部定义的函数 [work] 接收其参数([day]、[slot]、[client]):这是一个闭包(示例 08)。它被传给 [_transaction],后者在事务中执行它;
  • 第 181–182 行:不得预约过去的时间;
  • 第 183–185 行:对患者记录的“悲观”锁([SELECT ... FOR UPDATE];见 DAO 层)。原因如下。“只能有一个即将到来的预约”这条规则通过计数来验证(第 186 行),然后插入预约(第 188 行)。如果同一位患者同时预约两个时段(两个标签页、双击),两个事务可能都统计到零个预约,然后都插入预约:没有任何数据库约束能阻止这一点,因为这两个时段是不同的。对患者行的锁使第二个事务等待第一个事务完成:然后它统计到一个预约并失败。数据库自己无法强制执行这条规则:是业务层在数据库的协助下强制执行它;
  • 第 186–187 行:每位患者只能有一个即将到来的预约;
  • 第 188 行:插入。如果该时段刚刚被另一位患者占用,则是数据库约束 [unq1_appointments] 拒绝了这次插入,并由 [_transaction] 转换该错误(见下文);
  • 第 191–193 行:取消预约。[lambda: ...] 是一个匿名函数,只包含一个表达式(这里是一次调用):相当于一个三行的 [def] 函数。

11.11.7.4. 医生和患者的管理

  • 第 200–218 行:公开方法委托给通用方法,并使用正确的描述符;
  • 第 224–237 行:创建人员。姓氏转为大写([PELISSIER],数据库的约定),并去掉输入两端的空格。[dbrdvmedecins2] 数据库的规则:默认情况下,登录名是小写的姓氏,密码默认就是登录名([a or b]:如果 [a] 为“真”(非空字符串)就取它,否则取 [b] )。在事务中:先做验证(同名检查、登录名是否空闲),然后创建账户(带密码哈希;见 [security/passwords.py]),再创建人员,由其通过外键引用该账户:顺序是固定的;
  • 第 243–271 行:修改人员及其账户。表单的版本号与读取到的版本号进行比较(第 251 行):这是乐观锁的第一层,它会返回清晰的消息。第二层是 [UPDATE] (第 265–268 行):如果记录在读取操作(第 245 行)和写入操作之间被修改过,[UPDATE] 不会修改任何内容,异常 [_StaleVersion] 会回滚整个事务(因此账户也不会被修改)。只有在输入了登录名和密码时才会更改;显示的账户名跟随人员;
  • 第 281–292 行:删除,按外键决定的顺序进行:对该人员的引用(其时段或预约),然后是人员,再是其账户。[person.account_id] 是外键,无需查询即可读取;
  • 第 297–305 行:两项唯一性检查,在写入之前执行,以确保给出清晰的消息。正在被编辑的人员有权保留自己的名和姓:[current_id] 将其排除在外。

11.11.7.5. 数据库事务和错误

  • 第 322–334 行:每个写操作都在事务中执行([transaction.atomic],示例 28):如果 [work] 正常完成,事务就会提交([COMMIT]);如果发生异常(包括 [BusinessError]),则回滚([ROLLBACK]):什么都不会写入。因此业务层决定事务的范围:一个业务操作,一个事务;
  • 第 326–332 行:写入前执行的检查并不总是足够:两位管理员可能同时保存同一个登录名。此时,数据库的唯一性约束会拒绝第二次写入,ORM 会触发 [IntegrityError],其消息来自 [MySQL]:[(1062, "Duplicate entry 'Marie-PELISSIER' for key 'doctors.unq_doctors_first_name_last_name'")]。正则表达式 [CONSTRAINT] (第 69 行)提取约束的名称([search] 在字符串中搜索该表达式;[group(1)] 返回括号中第一个分组捕获的内容;[(?:...)] 是非捕获分组,而 [?] 使其可选:[MySQL] 8 会在名称前加上表名,[MariaDB] 则不会)。这就是 SQL 脚本为其所有约束命名的原因。已知的约束会变成相应的 [BusinessError];其他的 [IntegrityError] 则原样重新抛出([raise] 不带参数):这是真正的异常情况。[raise ... from e] 将原始异常附加到新异常上(示例 28);
  • 第 333–334 行:乐观锁失败会产生错误 [CONCURRENT_UPDATE]。异常 [_StaleVersion] 在 [atomic] 块内抛出以回滚事务,然后传播到块外。

异常在 [with transaction.atomic()] 块之外捕获,而不是在块内:数据库出错之后,事务不再有效,必须先回滚,而退出该块正是执行这一操作(示例 28)。

11.12. 身份验证与安全

[security] 文件涵盖与身份验证(用户是谁?)、权限(用户能否访问此页面?)以及机器人防护相关的所有内容。这是示例 25 到 27 的完整版本。

11.12.1. security/passwords.py

# =========================================================================
# security/passwords.py:使用 bcrypt 算法对密码进行哈希
# (bcrypt 库),10 轮,与 SQL 脚本的哈希相同。
#
# 哈希是单向的:无法从中恢复密码。
# 为了检查输入的密码,会用存储的哈希中包含的“盐”(一个
# 随机值)对其进行哈希,然后比较
# 两个结果:这就是 bcrypt.checkpw 所做的事。
#
# SQL 脚本的哈希以 $2b$ 开头;共享同一数据库的
# 应用其他版本的哈希,以 $2y$(PHP)或 $2a$(Java)开头:
# bcrypt 可以检查这三种形式。
#
# bcrypt 只考虑密码的前 72 个字节(并且
# 该库拒绝对更长的密码进行哈希):因此表单会限制
# 密码的长度(见 web/forms.py)。
# =========================================================================

import bcrypt

# 轮数:哈希需要 2^10 次基本计算
ROUNDS = 10
MAX_BYTES = 72


def hash_password(password: str) -> str:
    # encode:字符串转字节(UTF-8);decode:字节转字符串
    return bcrypt.hashpw(password.encode(), bcrypt.gensalt(ROUNDS)).decode()


def check_password(password: str, hash: str) -> bool:
    data = password.encode()
    if len(data) > MAX_BYTES:
        return False
    return bcrypt.checkpw(data, hash.encode())

数据库中的密码由 [bcrypt] 进行哈希(前面提到的 SQL 脚本),而不是 [Django] 的默认算法 PBKDF2(示例 25)。[bcrypt] 库可直接验证它们:

  • 第 26–28 行:密码的哈希。[gensalt(10)] 生成成本为 10 的随机盐;[hashpw] 计算哈希,其中包含算法、成本和盐(示例 25)。该库操作的是字节:[encode()] 将字符串转换为字节([UTF-8]),而 [decode()] 执行相反的操作;
  • 第 31–35 行:验证。[checkpw] 从存储的哈希中取出成本和盐,用它们对输入的密码进行哈希,并比较结果(以恒定时间比较,示例 23)。[bcrypt] 只考虑密码的前 72 个字节,而该库自第 5 版起拒绝对超过此长度的密码进行哈希(它会抛出异常):因此更长的密码会被直接拒绝。表单也会限制密码长度(Web 层,稍后讨论)。

[Django] 本可以用自己的 [BCryptPasswordHasher] 算法(设置 [PASSWORD_HASHERS])自行验证这些哈希:但它期望哈希带有前缀 [bcrypt$],而该数据库与应用的其他版本共用,那些版本不识别这个前缀。

11.12.2. security/connected_user.py

# =========================================================================
# security/connected_user.py:已登录用户,由其 JWT 令牌描述
# (见示例 25)。
#
# 我们令牌的声明(见 security/auth.py):
#   sub   :用户账户的 id(JWT 约定:“主题”),文本形式
#   login :登录名
#   name  :显示名称(“Marie PELISSIER”),用于导航栏
#   role  :ADMIN、DOCTOR 或 USER
#   iat, exp :令牌的创建日期和过期日期
#
# 该对象不来自数据库:每次请求时都会根据
# 令牌重建,其签名保证了内容的可靠。
# =========================================================================

from dataclasses import dataclass

from models.models import Role


@dataclass(frozen=True)
class ConnectedUser:
    user_id: int
    login: str
    name: str
    role: str

    # 由已校验令牌的声明所描述的用户;如果缺少声明
    # 或声明格式不符合预期,则为 None。@staticmethod:存放在
    # 类中的函数,既不接收对象也不接收类
    @staticmethod
    def from_claims(claims: dict) -> "ConnectedUser | None":
        role = claims.get("role")
        sub = str(claims.get("sub", ""))
        # Role.values:枚举的值;isdigit:仅包含数字
        if role not in Role.values or not sub.isdigit() or "login" not in claims or "name" not in claims:
            return None
        return ConnectedUser(int(sub), str(claims["login"]), str(claims["name"]), role)

    @property
    def is_admin(self) -> bool:
        return self.role == Role.ADMIN

    @property
    def is_doctor(self) -> bool:
        return self.role == Role.DOCTOR

    @property
    def is_patient(self) -> bool:
        return self.role == Role.USER

已登录用户,由其令牌描述(示例 25)。该对象不来自数据库:每次请求都根据令牌重新构造,令牌的签名保证其内容可信。

  • 第 31–38 行:静态方法([@staticmethod]):定义在类中的方法,既不接收对象也不接收类作为参数,调用方式为 [ConnectedUser.from_claims(claims)]。它根据已验证令牌中的声明构造用户对象。即使令牌由我们自己签发,也要仔细验证:未知的角色、不是数字的标识符或缺失的声明,都会导致用户被拒绝访问([None])。[Role.values] 是枚举值的列表;[isdigit] 验证字符串是否只由数字组成。返回类型的注解用引号括起来:此时该类尚未完全定义;
  • 第 40–50 行:供模板使用的三个属性(示例 26)。

11.12.3. security/auth.py

# =========================================================================
# security/auth.py:身份验证逻辑:
#   - validate()         :检查登录名 / 密码对;
#   - set_token()        :为已验证的用户构建 JWT 令牌,并
#                          放入响应的 Cookie 中;
#   - user()             :由令牌描述的用户。
#
# JWT 令牌通过什么传递?通过 Cookie(见示例 25):显示
# 普通 HTML 页面的浏览器因此会在每次请求时自动出示它。
# 该 Cookie 的选项对安全很重要:
#   - HttpOnly:页面的 JavaScript 无法读取该 Cookie(因此被注入的
#     脚本无法窃取令牌);
#   - SameSite=Lax:对于来自其他站点的 POST,浏览器不会发送该 Cookie
#     (对所谓 CSRF 攻击的第一重防护;第二重是
#     表单的防 CSRF 令牌);
#   - Secure:在生产环境(HTTPS)中,Cookie 绝不以未加密方式传输;
#   - 生命周期:Cookie 与令牌同时过期消失。
# =========================================================================

import time

import jwt
from django.conf import settings
from django.core.exceptions import ImproperlyConfigured

from dao.users import UserDao
from models.models import User

from . import passwords
from .connected_user import ConnectedUser

# 携带令牌的 Cookie 的名称
COOKIE = "rdvmedecins_jwt"

# HMAC-SHA256 要求密钥至少为 256 位:我们在模块
# 加载时就明确提示,而不是等库在后面失败
if len(settings.JWT_SECRET) < 32:
    raise ImproperlyConfigured("JWT_SECRET must be at least 32 characters long (see .env).")

_users = UserDao()


# 如果登录名不存在或密码错误,则为 None
def validate(login: str, password: str) -> User | None:
    user = _users.read_by_login(login)
    if user is None or not passwords.check_password(password, user.password):
        return None
    return user


# -------------------------------------------------------------------------
# [user] 的 JWT 令牌,放入承载它的 Cookie 中。该令牌
# 使用密钥签名(HMAC-SHA256):浏览器可以读取它(它没有
# 加密),但无法修改它 - 任何修改都会使签名
# 失效。
# -------------------------------------------------------------------------
def set_token(response, user: User):
    now = int(time.time())
    duration = settings.JWT_DURATION_MINUTES * 60
    claims = {
        "sub": str(user.id),
        "login": user.login,
        "name": user.name,
        "role": user.role,
        "iat": now,
        "exp": now + duration,
    }
    token = jwt.encode(claims, settings.JWT_SECRET, algorithm="HS256")
    response.set_cookie(COOKIE, token, max_age=duration, secure=settings.COOKIE_SECURE,
                        httponly=True, samesite="Lax")
    return response


# 清除令牌 Cookie:响应携带一个同名的空 Cookie,且已过期
def clear_token(response):
    response.delete_cookie(COOKIE, samesite="Lax")
    return response


# -------------------------------------------------------------------------
# 由令牌描述的用户;如果令牌已过期、被伪造或
# 格式错误,则为 None。jwt.decode 会检查签名和过期日期(声明 exp)。
# -------------------------------------------------------------------------
def user(token: str) -> ConnectedUser | None:
    try:
        claims = jwt.decode(token, settings.JWT_SECRET, algorithms=["HS256"])
    except jwt.InvalidTokenError:
        return None
    return ConnectedUser.from_claims(claims)

示例 25 中的身份验证服务,有几处不同:

  • 第 37–38 行:令牌密钥在模块加载时验证,也就是应用启动时:如果密钥太短,整个进程就会停止,并给出清晰的错误消息([ImproperlyConfigured] 是 [Django] 针对错误配置的异常),而不是像 [PyJWT] 那样只给出一个警告(示例 25);
  • 第 44–48 行:由 DAO 层(从数据库获取的账户)和密码模块验证用户名和密码。Web 层直接调用此模块:身份验证是安全问题,不是业务规则;
  • 第 57–71 行:生成令牌并将其存放在响应的 Cookie 中(示例 25)。账户 ID([sub])以明文书写:JWT 标准要求如此。该 Cookie 在生产环境中是 [Secure] 的([COOKIE_SECURE],见 [config/settings.py]);
  • 第 75–77 行:删除 Cookie:一个同名、为空且已过期的 Cookie(示例 25);
  • 第 84–89 行:用户由令牌标识,或者为 [None] (示例 25)。

11.12.4. security/access.py

# =========================================================================
# security/access.py:每个 URL 的访问规则。
#
# 规则按顺序检查;第一个其模式(正则
# 表达式)与 URL 路径匹配的规则生效:
#   - 少数公开 URL:主页、登录、语言选择、
#     账户创建;
#   - 仅限某些角色的 URL(一组角色:满足其中之一即可);
#   - 所有其他 URL 都要求已通过身份验证的用户(最后一条规则)。
# 这就是“除明确允许的以外一律禁止”的规则:之后添加的、
# 我们忘记保护的 URL 会被自动保护。
#
# AccessControl 中间件(见 security/middleware.py)应用这些规则:被
# 拒绝的匿名访客会被送到登录页面;没有所需角色的
# 已认证用户会得到 403 错误页面。
# =========================================================================

import re

from models.models import Role

# 两个特殊值,代替角色集合
PUBLIC = "PUBLIC"
AUTHENTICATED = "AUTHENTICATED"

# re.compile:正则表达式,一次性解析好
RULES = [
    (re.compile(r"^/$"), PUBLIC),
    (re.compile(r"^/(login|logout)$"), PUBLIC),
    (re.compile(r"^/language/"), PUBLIC),
    (re.compile(r"^/register"), PUBLIC),
    # 患者从“我的空间”取消自己的预约,而不是从日程中取消
    (re.compile(r"^/schedule/cancel$"), {Role.ADMIN, Role.DOCTOR}),
    (re.compile(r"^/(doctors|clients)"), {Role.ADMIN}),
    (re.compile(r"^/my-"), {Role.USER}),
    (re.compile(r"^/"), AUTHENTICATED),
]


# 路径 [path] 的规则:PUBLIC、AUTHENTICATED 或一组角色
def rule(path: str):
    for pattern, requirement in RULES:
        if pattern.match(path):
            return requirement
    return AUTHENTICATED

应用的访问规则,集中在一个列表中。示例 26 用装饰器保护每个视图;这里的保护是集中式的,就像 [Symfony] 的 [access_control] 规则所做的那样:

  • 第 27–37 行:每条规则将一个模式(正则表达式,由 [re.compile] 一次性编译)与一项要求关联起来:[PUBLIC]、[AUTHENTICATED],或者一组角色,其中任何一个都足够。[^] 标记路径的开头,[$] 标记其结尾;[(login|logout)]:二者之一。公开的 URL 页面有主页、登录、语言选择和账户创建。接下来是保留给特定角色的 URL 页面:从日程表取消预约(患者在“我的空间”中取消)、医生和患者的管理,以及患者的账户。最后一条规则 [^/] 适用于所有其余的 URL,并要求用户已通过身份验证;
  • 第 41–45 行:路径规则:第一条匹配的规则生效([match]:匹配字符串开头的表达式)。

这就是“除允许的之外一切禁止”的规则:之后添加的 URL(可能忘了加以保护)会自动受到保护。相反的错误(忘了设为公开的公开 URL)会立刻显现出来;而忘了保护某个页面的错误则不容易发现得多。

11.12.5. security/middleware.py

# =========================================================================
# security/middleware.py:两个安全中间件(见示例 24 至 26)。
#
#   1. 身份验证,在路由之前:用户是谁?根据其 Cookie 中的
#      JWT 令牌。它本身不拒绝任何请求:缺失或
#      无效的令牌会使访客保持匿名(request.user 为 None);
#      无效令牌的 Cookie 会在响应中被清除;
#   2. AccessControl,在路由之后(process_view):用户是否有权
#      访问此 URL?规则位于 security/access.py。没有
#      路由的 URL 不会走到这一步:它会得到 404 页面。
# =========================================================================

from django.contrib import messages
from django.core.exceptions import PermissionDenied
from django.shortcuts import redirect
from django.utils.translation import gettext as _

from . import access, auth


class Authentication:
    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        token = request.COOKIES.get(auth.COOKIE, "")
        request.user = auth.user(token) if token else None
        response = self.get_response(request)
        # 无效令牌(过期、被伪造):Cookie 会在响应中被清除,
        # 无论如何都如此 - 除非请求刚刚设置了新的 Cookie(
        # 登录成功)
        if token and request.user is None and auth.COOKIE not in response.cookies:
            auth.clear_token(response)
        return response


class AccessControl:
    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        return self.get_response(request)

    def process_view(self, request, view_func, view_args, view_kwargs):
        # path_info:URL 的路径,不含其参数
        requirement = access.rule(request.path_info)
        if requirement == access.PUBLIC:
            return None
        user = request.user
        if user is None:
            # 匿名访客:转到登录页面。如果他们有
            # 令牌 Cookie,说明其令牌已不再有效(过期、
            # 被伪造):其会话已过期,我们会告知他们
            if auth.COOKIE in request.COOKIES:
                messages.error(request, _("Your session has expired: please log in again."))
            return redirect("login")
        if requirement != access.AUTHENTICATED and user.role not in requirement:
            # 已认证,但没有所需角色:403 错误(handler403 视图,见 config/urls.py)
            raise PermissionDenied("insufficient role")
        return None

两个安全中间件组件:

  • 第 21–34 行:身份验证(示例 25),在路由之前。它不拒绝任何请求:缺失或无效的令牌只会让访客保持匿名。它会在响应中删除与无效令牌关联的 Cookie,无论响应是什么,除非响应设置了新的 Cookie(登录成功):[response.cookies] 是响应所设置的 Cookie 的字典;
  • 第 37–60 行:访问控制,在路由之后(其方法 [process_view],示例 24)。因此没有路由的 URL 不会到达这里:它直接得到 404 页面,而不会要求访客登录。[request.path_info] 是 URL 的路径,不含其参数。被拒绝访问的匿名访客会被重定向到登录页面;如果他们有令牌 Cookie,就说明其令牌已不再有效:一条弹出消息会告知他们会话已过期(见标题为“会话结束”的截图)。没有所需角色的已认证用户会触发 [PermissionDenied]:由于该异常是在 [process_view] 中而不是在视图中抛出的,[Django] 自己会通过应用的 [handler403] 视图(示例 24)将其转换为响应,无论是调试模式还是生产模式。

该消息由 [gettext] (第 16 行)翻译,而不是 [gettext_lazy]:它在请求期间用请求的语言翻译;惰性翻译只对模块加载时定义的文本有用。

11.12.6. security/errors.py

1
2
3
4
5
6
7
8
# security/errors.py:令牌有效,但它所指向的账户已不
# 存在:登录之后被删除了(被患者本人在另一个
# 标签页中删除,或被 ADMIN 删除)。该情况按会话过期处理:
# ErrorPage 中间件清除 Cookie 并重定向到登录页面。


class InvalidSession(Exception):
    pass

一种特殊情况:令牌有效,但它所指向的账户已不存在(患者在另一个标签页中删除了它,或者管理员删除了它)。需要该账户的视图会抛出此异常,[ErrorPage] 中间件将其视为会话过期(见下文)。

11.12.7. security/captchas.py 和 captcha_drawing.py

# =========================================================================
# security/captchas.py:验证码(CAPTCHA,“区分人类和机器人的测试”),
# 由服务器自己生成,不使用任何外部服务(见示例 27)。
#
# 工作原理:
#   1. generate() 随机生成一段文本,制作成图像,并把正确
#      答案存储在服务器的缓存中,键为一个随机标识符;
#   2. 页面显示该图像,并把标识符放在表单的隐藏字段
#      中(答案本身从不离开服务器);
#   3. verify(id, input) 将输入与预期答案比较,然后忘记
#      这个验证码:每张图像只能使用一次,机器人无法重放
#      已经找到的答案。
#
# 为什么用缓存,而不是模块的一个简单变量?因为生产环境的
# 服务器会启动多个进程(见 README.md),它们不共享
# 内存:检查验证码的请求不一定由生成它的
# 进程处理。而应用的缓存(文件,见
# config/settings.py)则由所有进程共享。
# =========================================================================

import secrets
from dataclasses import dataclass

from django.core.cache import cache

from . import captcha_drawing

# 图像的有效时长,单位为秒:10 分钟用于填写表单
LIFETIME = 600


# 一个验证码:其标识符,放入表单的隐藏字段 [captcha_id]
# 中,以及其图像(SVG),原样插入页面
@dataclass(frozen=True)
class Captcha:
    id: str
    svg: str


def generate() -> Captcha:
    text = captcha_drawing.random_text(5)        # 5 个字符
    id = secrets.token_hex(12)                     # 无法猜出的标识符
    # 缓存会在 10 分钟后自动忘记该答案
    cache.set(f"captcha.{id}", text, LIFETIME)
    return Captcha(id, captcha_drawing.svg(text))


# 如果 [answer] 是验证码 [id] 的正确答案则为 true(不区分
# 大小写)。无论结果如何,验证码都会被消耗。
def verify(id: str, answer: str) -> bool:
    # 标识符来自浏览器:24 个十六进制数字,或为空
    if len(id) != 24 or any(c not in "0123456789abcdef" for c in id) or not answer:
        return False
    expected = cache.get(f"captcha.{id}")
    # delete 在该项存在时返回 True:如果两个请求同时提交同一个
    # 验证码,只有一个真正删除了它 - 另一个会失败
    if expected is None or not cache.delete(f"captcha.{id}"):
        return False
    return expected.casefold() == answer.strip().casefold()

示例 27 中的验证码(CAPTCHA)服务,增加了两项预防措施:

  • 第 51–52 行:标识符来自浏览器;在将其用作缓存键之前,我们验证它由 24 个十六进制数字组成(即 [token_hex(12)] 生成的数字)。[any] 在生成表达式产生的任一元素为真时返回 [True];
  • 第 53–56 行:[cache.delete] 在元素存在时返回 [True] 。如果两个请求同时提交同一个验证码,只有一个能真正删除它;另一个失败。一张图片只能使用一次。

文件中的注释(第 17–22 行)解释了为什么验证码存储在缓存中(一组由所有服务器进程共享的文件),而不是存储在模块变量中。文件 [security/captcha_drawing.py] 与示例 27 中的相同,只是头部注释更长:每个字符都用线条绘制,绝不写成文本,否则机器人只需读取图像的源代码即可。

11.12.8. security/limiter.py

# =========================================================================
# security/limiter.py:针对机器人的第二道屏障(第一道是
# 验证码):对尝试次数进行计数,超过阈值后会被封锁
# 一段时间(见示例 27)。
#
#   - 登录:同一 IP 地址对同一登录名失败 LOGIN_MAX_FAILURES 次
#     (验证码错误或密码错误)后,该组合会被封锁,
#     直到 LOGIN_BLOCK_MINUTES 分钟的窗口结束,从
#     第一次失败开始计时。如果同一 IP 地址累计达到
#     LOGIN_MAX_FAILURES_IP 次失败(所有登录名合计),也会被封锁(机器人尝试
#     成千上万个不同的登录名);
#   - 账户创建:同一 IP 地址每小时最多创建 REGISTRATION_MAX_PER_HOUR 个
#     账户。
#
# 在教室里要小心:所有电脑通常通过
# 同一个 IP 地址访问互联网。这就是为什么登录封锁首先针对
# (IP,登录名)组合 - 输错密码的学生不会封锁
# 邻座的同学 - 以及为什么阈值是可配置的(.env 文件)。
#
# 每个计数器都存储在缓存中(见 security/captchas.py),并附带其窗口的
# 结束时间:{"count": 3, "end": 1790531419.2}。
# =========================================================================

import hashlib
import math
import time

from django.conf import settings
from django.core.cache import cache


# ———————————————————————————————— 登录
# 剩余封锁分钟数(0 = 允许尝试)
def login_block_minutes(ip: str, login: str) -> int:
    return max(_remaining_minutes(_login_key(ip, login), settings.LOGIN_MAX_FAILURES),
               _remaining_minutes(f"login_ip.{ip}", settings.LOGIN_MAX_FAILURES_IP))


# 再失败一次;第一次失败会开启一个 LOGIN_BLOCK_MINUTES 分钟的窗口,
# 窗口结束时,计数器从零重新开始
def login_failure(ip: str, login: str) -> None:
    duration = settings.LOGIN_BLOCK_MINUTES * 60
    _count(_login_key(ip, login), duration)
    _count(f"login_ip.{ip}", duration)


# 登录成功会重置该登录名的计数器
def login_success(ip: str, login: str) -> None:
    cache.delete(_login_key(ip, login))


# ———————————————————————————————— 注册
def registration_block_minutes(ip: str) -> int:
    return _remaining_minutes(f"registration.{ip}", settings.REGISTRATION_MAX_PER_HOUR)


def registration_success(ip: str) -> None:
    _count(f"registration.{ip}", 3600)


# ———————————————————————————————— 通用机制
# (IP,登录名)组合的键。登录名来自浏览器:它可能包含
# 任何内容(空格等……)。其 SHA-256 指纹由 64 个十六进制
# 数字组成,得到的缓存键始终有效
def _login_key(ip: str, login: str) -> str:
    fingerprint = hashlib.sha256(f"{ip}|{login.strip().lower()}".encode()).hexdigest()
    return f"login.{fingerprint}"


# 如果计数器已达到上限,则为距离窗口结束剩余的分钟数,
# 否则为 0;秒数向上取整到分钟(ceil):
# 30 秒 -> “1 分钟”
def _remaining_minutes(key: str, limit: int) -> int:
    state = cache.get(key)
    if state is None or state["count"] < limit:
        return 0
    return max(1, math.ceil((state["end"] - time.time()) / 60))


# 在当前窗口(或在一个新的、时长为
# [duration] 秒的窗口)中再记一次尝试。窗口结束时缓存会忘记计数器(超时)。
# 先读后写不是原子的:两次同时的尝试
# 可能只算作一次。对于失败计数器,这无关紧要
def _count(key: str, duration: int) -> None:
    state = cache.get(key) or {"count": 0, "end": time.time() + duration}
    state["count"] += 1
    cache.set(key, state, timeout=max(1, math.ceil(state["end"] - time.time())))

示例 27 中的尝试次数限制,做得更精细:

  • 第 34–49 行:登录。失败的尝试按每一对(IP 地址,用户名)计数:五次失败的尝试(设置 [LOGIN_MAX_FAILURES])会从第一次失败的尝试起,将该用户名从该地址封锁十五分钟。在教室里,所有电脑往往通过同一个 IP 地址访问互联网,输错密码的学生不会封锁他的邻座。不过,如果同一地址在所有登录名上累计 25 次失败的尝试,它也会被封锁:这对应于尝试数千个不同登录名的机器人。登录成功会清除该登录名的失败尝试;
  • 第 53–58 行:创建账户:每个 IP 地址每小时最多十个账户;
  • 第 65–67 行:这一对(IP,登录名)的键。登录名来自浏览器:它可以包含任何内容。它的 SHA-256 指纹([hashlib.sha256],来自标准库)由 64 个十六进制数字组成,得到始终有效且长度固定的缓存键;
  • 第 73–77 行:剩余的锁定分钟数,向上取整到下一分钟([math.ceil]:30 秒等于“1 分钟”);
  • 第 84–87 行:计数器,在固定窗口内(示例 27)。[cache.get(key) or {...}]:当前状态,或一个新状态。代码注释承认了示例 27 的弱点(两次同时发生的失败可能只算作一次);对于失败计数器来说,这不是严重的问题。

11.12.9. security/registration_pass.py

# =========================================================================
# security/registration_pass.py:账户创建的“通行证”。
#
# 要打开“创建患者账户”页面,必须先输入身份验证页面的
# 验证码(见 web/views/registration.py,POST
# /register/access)。服务器随后签发一个通行证:
#   - 一个随机标识符,存储在 HttpOnly Cookie 中;
#   - 有效期 15 分钟(填写表单的时间,即使在因输入错误
#     而多次尝试之后);
#   - 一旦创建账户即被消耗:一个已解出的验证码最多对应一个账户。
#     机器人无法批量创建账户。
#
# 没有有效通行证时,GET 和 POST /register 会重定向到
# 身份验证页面(见 @registration_pass_required 装饰器):直接输入
# URL /register 无法绕过验证码。
#
# 与验证码一样,通行证也保存在缓存中。
# =========================================================================

import secrets
from functools import wraps

from django.conf import settings
from django.contrib import messages
from django.core.cache import cache
from django.shortcuts import redirect
from django.utils.translation import gettext as _

COOKIE = "rdvmedecins_registration"
# 浏览器只会把该 Cookie 发送到 /register... 开头的地址
PATH = "/register"
# 通行证的有效期,单位为分钟
LIFETIME = 15


# 签发新通行证,放在响应的 Cookie 中
def issue(response):
    id = secrets.token_hex(12)
    cache.set(f"pass.{id}", True, LIFETIME * 60)
    response.set_cookie(COOKIE, id, max_age=LIFETIME * 60, path=PATH,
                        secure=settings.COOKIE_SECURE, httponly=True, samesite="Lax")
    return response


# 如果 [id] 是一个存在且未过期的通行证则为 true
def is_valid(id: str | None) -> bool:
    return bool(id) and id.isalnum() and cache.get(f"pass.{id}") is not None


# 通行证已被使用:将其忘记……
def consume(id: str | None) -> None:
    if id and id.isalnum():
        cache.delete(f"pass.{id}")


# ……并通过一个同名、同路径且已过期的 Cookie 清除其 Cookie
def clear_cookie(response):
    response.delete_cookie(COOKIE, path=PATH, samesite="Lax")
    return response


# -------------------------------------------------------------------------
# @registration_pass_required:一个装饰器(见示例 26),用在
# 需要通行证的视图上(GET 和 POST /register)。没有有效通行证时,
# 不会调用视图:返回身份验证页面,并附带一条消息
# -------------------------------------------------------------------------
def registration_pass_required(view):
    @wraps(view)
    def wrapper(request, *args, **kwargs):
        if not is_valid(request.COOKIES.get(COOKIE)):
            messages.error(request, _("To create an account, first type the characters shown in the image "
                                      "correctly, then click \"Create a patient account\"."))
            return redirect("login")
        return view(request, *args, **kwargs)
    return wrapper

账户创建令牌。要创建账户,必须先输入登录页面上的验证码(“创建患者账户”按钮):服务器随后签发一个令牌,即存储在缓存和 Cookie 中的随机标识符。没有通行令牌,账户创建页面会重定向到登录页面:直接输入 URL 或 [/register] 不会绕过验证码;而且通行令牌只能用于创建一个账户:机器人无法批量创建账户。

  • 第 29–33 行:浏览器只会向以 [/register] 开头的地址发送该 Cookie(Cookie 参数 [path]):它不会随其他请求一起传输;
  • 第 37–42 行:Cookie 的有效期为十五分钟——足够填写表单,即使输入有误需要重试多次;
  • 第 46–59 行:Cookie 的验证、使用和删除(要删除的 Cookie 必须具有相同的路径)。[isalnum] 验证标识符是否只由字母和数字组成;
  • 第 67–75 行:装饰器 [@registration_pass_required] (示例 26),应用于账户创建视图。

11.13. Web 层:共享服务

[web] 文件夹包含 Web 层的 [Django] 应用(在 [INSTALLED_APPS] 中声明;见 [config/settings.py];其文件 [web/apps.py] 只包含它的名称)。它汇集了路由、视图、表单,以及所有视图的共同之处:这就是本节的重点。

11.13.1. web/application.py

# =========================================================================
# web/application.py:业务层的缓存 / 外观(相当于应用其他版本的
# [ApplicationModel] 类):医生和客户的列表
# 从数据库读取一次,然后从缓存中提供。
#
# 为什么用 Django 的缓存,而不是简单地用该对象的一个属性?一个
# Python 进程确实会在两次请求之间保留其对象(见示例 20);
# 但生产环境的服务器会启动多个进程,每个进程都会有列表的
# 自己的副本:添加医生的 ADMIN 只会更新处理其请求的
# 那个进程中的副本。而应用的缓存(文件,见
# config/settings.py)则由所有进程共享。
#
# 这些列表可能变化(ADMIN 添加、更新、删除医生和
# 客户):因此每次写入都要经过这个外观,它会随后忘记
# 相关的列表;下一个需要它的请求会重新从数据库读取。这就是
# 业务层只有一个入口的全部意义:规则
# “写入 => 更新缓存”只在这里编写。
# =========================================================================

from datetime import date
from functools import cache as once

from django.core.cache import cache

from domain.schedule import DoctorDaySchedule
from business.person_data import PersonData
from business.provider import business
from business.business import Business
from models.models import Appointment, Client, Doctor, Slot

DOCTORS = "rdvmedecins.doctors"
CLIENTS = "rdvmedecins.clients"


# 与业务层相同的契约
class ApplicationModel(Business):
    def __init__(self):
        self.business = business()

    # ———————————————— 从缓存读取
    # get_or_set(key, function, timeout):如果缓存中有则返回缓存的值;否则
    # 调用该函数,并将其结果存入缓存(timeout=None:
    # 无时间限制)后再返回。对象以序列化形式存储在其中
    # (pickle 模块):每个读取它们的请求得到的都是副本
    def get_all_doctors(self) -> list[Doctor]:
        return cache.get_or_set(DOCTORS, self.business.get_all_doctors, timeout=None)

    def get_all_clients(self) -> list[Client]:
        return cache.get_or_set(CLIENTS, self.business.get_all_clients, timeout=None)

    # 医生,其用户账户为 [user_id] - 用于为已登录的医生
    # 预先选中其自己的日程
    def get_doctor_by_user_id(self, user_id: int) -> Doctor | None:
        return next((d for d in self.get_all_doctors() if d.account_id == user_id), None)

    # ———————————————— 简单委托
    def get_all_slots(self, doctor_id: int) -> list[Slot]:
        return self.business.get_all_slots(doctor_id)

    def get_doctor_day_appointments(self, doctor_id: int, day: date) -> list[Appointment]:
        return self.business.get_doctor_day_appointments(doctor_id, day)

    def get_client_by_id(self, id: int) -> Client | None:
        return self.business.get_client_by_id(id)

    def get_doctor_by_id(self, id: int) -> Doctor | None:
        return self.business.get_doctor_by_id(id)

    def get_appointment_by_id(self, id: int) -> Appointment | None:
        return self.business.get_appointment_by_id(id)

    def get_slot_by_id(self, id: int) -> Slot | None:
        return self.business.get_slot_by_id(id)

    def get_doctor_day_schedule(self, doctor_id: int, day: date) -> DoctorDaySchedule | None:
        return self.business.get_doctor_day_schedule(doctor_id, day)

    # 这里没有缓存:重要的是最新的数据(刚刚
    # 更新或删除了账户的患者)
    def get_client_by_user_id(self, user_id: int) -> Client | None:
        return self.business.get_client_by_user_id(user_id)

    def get_client_upcoming_appointments(self, client_id: int) -> list[Appointment]:
        return self.business.get_client_upcoming_appointments(client_id)

    def add_appointment(self, day: date, slot: Slot, client: Client) -> Appointment:
        return self.business.add_appointment(day, slot, client)

    def delete_appointment(self, appointment: Appointment) -> None:
        self.business.delete_appointment(appointment)

    # ———————————————— 写入 => 缓存被忘记
    # (delete:该项从缓存中移除)
    def add_doctor(self, data: PersonData) -> Doctor:
        doctor = self.business.add_doctor(data)
        cache.delete(DOCTORS)
        return doctor

    def edit_doctor(self, id: int, data: PersonData) -> Doctor:
        doctor = self.business.edit_doctor(id, data)
        cache.delete(DOCTORS)
        return doctor

    def delete_doctor(self, id: int) -> None:
        self.business.delete_doctor(id)
        cache.delete(DOCTORS)

    def add_client(self, data: PersonData) -> Client:
        client = self.business.add_client(data)
        cache.delete(CLIENTS)
        return client

    def edit_client(self, id: int, data: PersonData) -> Client:
        client = self.business.edit_client(id, data)
        cache.delete(CLIENTS)
        return client

    def delete_client(self, id: int) -> None:
        self.business.delete_client(id)
        cache.delete(CLIENTS)


# 外观的提供者:一个单一的共享对象(见 business/provider.py)
@once
def application() -> ApplicationModel:
    return ApplicationModel()

应用的所有版本都有一个 [ApplicationModel] 类:从 Web 层到业务层的唯一入口,它在内存中保存医生和患者的列表。几乎所有页面都会请求这些列表(日程表中的医生下拉列表、预约窗口中的患者列表、管理页面),而且它们很少变化。

[Python] 进程在一次请求到下一次请求之间会保留其对象(示例 20):因此 [Flask] 版本只是把这些列表存放在单个对象的属性中。头部注释解释了为什么这个版本改为把它们存放在 [Django] 的缓存中(示例 20):生产服务器会运行多个进程,每个进程都会有自己的列表副本。

  • 第 36 行:该类继承契约 [Business],与 [BusinessService] 一样:无论由哪个类提供服务,视图调用的都是相同的方法;
  • 第 45–49 行:[get_or_set(key, function, timeout)] 返回存储在该键下的值;如果不存在,就调用该函数(这里是业务层的一个绑定方法,不带括号传递,它从数据库读取列表),将其结果永久存入缓存([timeout=None]),并返回它。第一个需要该列表的请求从数据库读取它;后续请求则在缓存中找到它。缓存存储的是由模块 [pickle] 序列化的列表(示例 20),并在取回时重建它,连同已加载的关系:每个人员的账户,通过来自 DAO 层的连接 [select_related("account")] 获取。重建的对象是副本:它们用于显示,绝不用于写入(业务层总是从数据库重新读取它要修改的内容);
  • 第 53–54 行:与某个账户关联的医生,从缓存的列表中获取。[next(generator, None)] 返回生成表达式产生的第一个元素,如果没有则返回 [None](示例 06);
  • 第 57–90 行:契约中的其他方法只是委托给业务层。账户对应的患者([get_client_by_user_id])总是从数据库获取,而不是从缓存:重要的是最新的数据(比如刚刚修改或删除了账户的患者);
  • 第 94–120 行:更新操作。医生或患者的每次写操作都会清除相应的列表([delete]):下一个需要它的查询会再次从数据库读取。这正是设置唯一入口的意义所在:“写操作要更新缓存”这条规则只在这里实现。如果写操作失败([BusinessError]),异常会在 [delete] 之前退出该方法:列表不会被覆盖;它没有变化。如果有应用通过其他途径写入数据库(另一个程序、使用同一数据库的应用的另一个版本),缓存就会过时:这时只需清空 [var/cache] 文件夹即可;
  • 第 124–126 行:外观的提供者,仿照业务层的提供者:单个对象,在第一个请求时创建。[functools.cache],以名称 [once] 导入,存储函数的结果(示例 06):函数 [application()] 只执行一次,之后总是返回同一个对象。

11.13.2. web/utils.py

# =========================================================================
# web/utils.py:Web 层的小型工具函数:
#   - 日期:“yyyy-mm-dd”,星期几如“Wednesday 23 September 2026”;
#   - 输入:读取浏览器发送的正整数、日期;
#   - 用户:已登录用户及其患者(Client 模型)。
# =========================================================================

import re
from datetime import date, datetime

from django.utils import dateformat

from models.models import Client
from security.errors import InvalidSession
from security.connected_user import ConnectedUser

from .application import application


# ———————————————————————————————— 日期
# 如果 [text] 是 yyyy-mm-dd 格式的真实存在的日期,则返回该日期;否则为 None。
# strptime 会拒绝不存在的日期(“2026-02-30”)
def valid_date(text: str | None) -> date | None:
    if text is None or not re.fullmatch(r"\d{4}-\d{2}-\d{2}", text):
        return None
    try:
        return datetime.strptime(text, "%Y-%m-%d").date()
    except ValueError:
        return None


# "2026-09-23"
def iso(day: date) -> str:
    return day.isoformat()


# “Wednesday 23 September 2026” / “mercredi 23 septembre 2026”,按当前启用的
# 语言(见 web/middleware.py)。dateformat.format 的日期格式化方式与模板的
# date 过滤器相同:l 完整的星期名,j 日,
# F 完整的月份名,Y 年份;名称由 Django 翻译
def format_day(day: date) -> str:
    return dateformat.format(day, "l j F Y")


# ———————————————————————————————— 输入
# "3" -> 3;""、"abc"、"-2"、"+2"、None -> None
def positive_integer(value: str | None) -> int | None:
    if value is None or not re.fullmatch(r"\d{1,9}", value):
        return None
    n = int(value)
    return n if n > 0 else None


# ———————————————————————————————— 用户
# 已登录用户。受保护的视图只有在其存在时才会被调用(见
# security/middleware.py);出于预防,其缺失按
# 会话过期处理
def user(request) -> ConnectedUser:
    if request.user is None:
        raise InvalidSession()
    return request.user


# -------------------------------------------------------------------------
# 与已登录用户对应的患者(Client 模型)。
#
# JWT 令牌只包含账户的 id(users.id)。对于 USER 角色,
# 对应的客户通过 clients.user 列找到。
#
# 如果没有,说明账户在登录之后被删除了,
# 而其令牌仍然有效:按会话过期处理。
# -------------------------------------------------------------------------
def connected_patient(request) -> Client:
    client = application().get_client_by_user_id(user(request).user_id)
    if client is None:
        raise InvalidSession()
    return client


# 客户端的 IP 地址
def ip(request) -> str:
    return request.META.get("REMOTE_ADDR", "")

所有视图都需要的一些工具函数:

  • 第 23–29 行:参数 [yyyy-mm-dd] 形式的日期,或 [None]。两项检查:格式(正则表达式;[fullmatch] 要求整个字符串都匹配),然后是日期是否存在:[strptime] 对于 2 月 30 日会抛出 [ValueError] ;
  • 第 41–42 行:“Wednesday 23 September 2026”或“mercredi 23 septembre 2026”,取决于请求的语言。[dateformat.format] 像模板中的 [date] 过滤器那样格式化日期(示例 16),使用相同的格式代码;星期和月份的名称由 [Django] 自己以当前激活的语言翻译;
  • 第 47–51 行:查询参数是字符串,或 [None]。只接受数字(最多九位:数据库可接受的合理位数),并且该数必须严格为正;
  • 第 58–61 行:已登录用户,由 [Authentication] 中间件确定。受保护的视图只会为已认证的用户调用(访问控制),但仍然把缺少用户的情况当作会话过期处理;
  • 第 73–77 行:与已登录用户关联的患者([Client])。令牌只包含账户 ID;患者通过 [clients.user] 列来标识。如果它不存在,说明该账户在用户登录之后被删除了:[InvalidSession] ([ErrorPage] 中间件,稍后讨论);
  • 第 81–82 行:客户端的(IP)地址,供尝试次数限制器使用。[REMOTE_ADDR] 是建立连接的机器的地址。在反向代理之后(见“生产服务器”),它始终是代理的地址:这时就需要读取代理添加的头部([X-Forwarded-For]),而且只读它添加的那一个,因为浏览器可以发送任何头部。

11.13.3. web/contexts.py

# =========================================================================
# web/contexts.py:上下文处理器(见示例 15):所有页面
# 都需要的变量:
#   - user:已登录用户(或 None),用于导航栏;
#   - menu:导航栏菜单的条目,取决于角色。
#
# 菜单在这里用 Python 计算,而不是在模板中:“医生”和
# “患者”只对 ADMIN 显示。这只是显示上的便利:
# 真正的保护是访问规则(手动输入 /doctors 的
# USER 会得到 403 页面)。
# =========================================================================

from dataclasses import dataclass

from django.urls import reverse
from django.utils.translation import gettext_lazy as _

from security import auth


# 一个菜单条目:其 URL、其标签,以及它是否为当前页面对应的条目
@dataclass(frozen=True)
class MenuEntry:
    url: str
    label: str
    active: bool


def user(request):
    # 由 Authentication 中间件确定的用户。出于预防,如果它
    # 缺失(在该中间件之前发生错误而导致的错误页面),则
    # 直接从令牌中读取,使导航栏保持完整
    connected = getattr(request, "user", None)
    if connected is None and request.COOKIES.get(auth.COOKIE):
        connected = auth.user(request.COOKIES[auth.COOKIE])
    return {"user": connected, "menu": menu(request, connected)}


# 菜单条目:(路由名称,标签,使该条目处于
# 活动状态的路径前缀)
def menu(request, connected):
    if connected is None:
        return []
    entries = []
    if connected.is_patient:
        # 对 /my-area 和 /my-account 都处于活动状态
        entries.append(("area", _("My area"), ["/my-"]))
    entries.append(("schedule", _("Schedule"), ["/schedule"]))
    if connected.is_admin:
        entries.append(("doctors_list", _("Doctors"), ["/doctors"]))
        entries.append(("clients_list", _("Patients"), ["/clients"]))
    # any:只要有一个前缀匹配即为 true
    return [MenuEntry(reverse(route), label, any(request.path.startswith(p) for p in prefixes))
            for route, label, prefixes in entries]

上下文处理器(示例 15),在 [config/settings.py] 中声明:所有页面都需要的变量,位于所有模板的上下文中:

  • [user]:已登录用户,或 [None],用于导航栏。通常它来自 [Authentication] 中间件;[getattr(object, name, default)] 读取一个属性,如果它不存在则返回默认值。作为预防措施,如果它缺失,则直接从令牌中读取用户(第 34–35 行);
  • [menu]:导航栏的菜单项,取决于角色(第 41–54 行)。每个菜单项是一个 [MenuEntry] 对象(数据类,第 22–26 行):URL(由 [reverse] 生成,示例 04)、翻译后的标签,以及活动项标志——即当前显示页面所对应的菜单项——模板会将其高亮。[My area] 菜单项对所有以 [/my-] 开头的 URL 都处于活动状态:[/my-area] 和 [/my-account]。

菜单是在 [Python] 中计算的,而不是在模板中(模板中没有逻辑;稍后详述)。隐藏“医生”和“患者”菜单项只是为了显示上的方便:真正的保护来自访问规则。

11.13.4. web/templatetags/rdv.py

# =========================================================================
# web/templatetags/rdv.py:我们模板的标签(见示例 16),通过
# {% load rdv %} 加载。
#
#   {% success_zone %}:成功类闪现消息,位于页面顶部;
#   {% error_zone %}:错误区域,位于每个页面的底部,背景为浅粉色。
#   它汇集了三种可能的错误来源:
#     - [error]:所显示页面的错误(日期无效、验证码输错、
#       登录名已被占用……),由视图传入;
#     - 错误类闪现消息,由上一个视图在重定向之前
#       留下(时段已被预约、删除被拒绝……);
#     - 无效表单的输入错误(见示例 19):其
#       消息显示在字段下方;这里,如果没有其他
#       消息,则显示一句简单的“表单包含错误。”。
# =========================================================================

from django import template
from django.contrib import messages as flash
from django.utils.translation import gettext as _

register = template.Library()


# takes_context:函数接收调用它的模板的上下文;messages:
# 闪现消息上下文处理器的变量;level:消息的级别
@register.inclusion_tag("fragments/success.html", takes_context=True)
def success_zone(context):
    return {"texts": [m.message for m in context.get("messages", []) if m.level == flash.SUCCESS]}


@register.inclusion_tag("fragments/errors.html", takes_context=True)
def error_zone(context):
    texts = [m.message for m in context.get("messages", []) if m.level == flash.ERROR]
    if context.get("error"):
        texts.insert(0, context["error"])
    form = context.get("form")
    # 一个已绑定(已提交)且无效的表单,且没有任何其他消息
    if not texts and form is not None and form.is_bound and form.errors:
        texts.append(_("The form contains errors."))
    return {"texts": texts}

两个包含标签(示例 16),通过 [{% load rdv %}] 加载到模板中。每个标签返回一个小模板(一个片段,稍后讨论),其中包含函数返回的变量:

  • 第 26–28 行:[{% success_zone %}]:成功的闪现消息(示例 20),显示在页面顶部。[takes_context=True]:该函数接收调用它的模板的上下文,消息上下文处理器已将变量 [messages] 存放在其中。[level] 是消息的级别([flash.SUCCESS]、[flash.ERROR]……);
  • 第 31–40 行:[{% error_zone %}]:错误区域,位于每个页面的底部。它汇集了三种可能的错误来源:页面错误(变量 [error],由视图传入,并由 [insert(0, ...)] 放在列表的最前面)、闪现错误消息(由重定向之前的上一个视图设置),以及无效表单的输入错误,其消息显示在各字段下方:此时错误区域只显示一句话:“The form contains errors.” [is_bound]:表单已接收到输入(示例 19)。

两个标签读取同一个列表,各自只保留一个级别。已读取的消息列表会在请求结束时清除(示例 20):每条消息只显示一次。

11.13.5. web/middleware.py

# =========================================================================
# web/middleware.py:Web 层的两个中间件(见示例 24)。
# =========================================================================

from django.conf import settings
from django.contrib import messages
from django.core.exceptions import BadRequest, PermissionDenied
from django.http import Http404
from django.shortcuts import redirect
from django.utils import translation
from django.utils.translation import gettext as _

from security import auth
from security.errors import InvalidSession

from .views.errors import error_page


# -------------------------------------------------------------------------
# 请求的语言(见示例 22):如果 Cookie [rdvmedecins_language] 中的语言
# 是受支持的语言,则用它,否则用英语。它放在中间件列表的
# 最前面,对所有请求都生效,即使是那些最终
# 没有匹配路由的请求(404 页面):它们的错误页面也使用正确的语言
# -------------------------------------------------------------------------
class SetLanguage:
    # 受支持的语言;默认语言为 LANGUAGE_CODE
    LANGUAGES = [code for code, name in settings.LANGUAGES]

    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        language = request.COOKIES.get(settings.LANGUAGE_COOKIE_NAME)
        if language not in self.LANGUAGES:
            language = settings.LANGUAGE_CODE
        translation.activate(language)
        # 请求的语言,按 LocaleMiddleware 的方式存储(见示例 22)
        request.LANGUAGE_CODE = language
        return self.get_response(request)


# -------------------------------------------------------------------------
# 错误如何变成 HTML 页面。三种情况:
#   1. InvalidSession(登录之后账户被删除)-> 返回
#      登录页面,与会话过期时相同;
#   2. 视图抛出的 HTTP 错误:无效请求(BadRequest,400),
#      角色不足(PermissionDenied,403),对象未知(Http404)-> 错误
#      页面,使用原始代码;
#   3. 任何其他异常(真正的故障):Django 会将其写入
#      日志,并附带其堆栈跟踪;在生产环境(DEBUG 为 false)中,用户
#      看到的是 500 错误页面(handler500,见 config/urls.py)- 绝不会是堆栈
#      跟踪;在开发环境中则是 Django 调试页面。
# 被拒绝的 HTTP 方法(405)不是异常:装饰器
# require_GET 等会返回一个空的 405 响应,__call__ 会将其替换为我们的页面。
# -------------------------------------------------------------------------
class ErrorPage:
    CODES = {BadRequest: 400, PermissionDenied: 403, Http404: 404}

    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        response = self.get_response(request)
        if response.status_code == 405 and not response.content:
            page = error_page(request, 405)
            # Allow 头:接受的方法
            page["Allow"] = response["Allow"]
            return page
        return response

    def process_exception(self, request, exception):
        if isinstance(exception, InvalidSession):
            messages.error(request, _("Your session has expired: please log in again."))
            return auth.clear_token(redirect("login"))
        for cls, code in self.CODES.items():
            if isinstance(exception, cls):
                return error_page(request, code)
        return None

Web 层的两个中间件组件(示例 24)。回顾它们在 [config/settings.py] 的 [MIDDLEWARE] 列表中的顺序:[SetLanguage] 在前,[ErrorPage] 在后。

  • 第 25–39 行:请求语言;如果它与 [rdvmedecins_language] Cookie 中的语言一致,就使用该语言;否则使用英语。这是示例 16 中的 [SetLanguage] 中间件,而不是 [LocaleMiddleware] (示例 22):[LocaleMiddleware] 在没有 Cookie 时会选择浏览器的首选语言;应用的其他版本总是以英语启动,这个版本也是如此。支持的语言从 [LANGUAGES] 设置中读取(第 27 行,一个只读列表,在加载类时执行一次)。[translation.activate] (第 36 行)设置当前激活的语言(示例 16):用于翻译、日期以及模板中 [LANGUAGE_CODE] 变量的语言(上下文处理器 [i18n],示例 22)。语言还存储在 [request.LANGUAGE_CODE] 中(第 38 行),与 [LocaleMiddleware] 的做法一样,供需要访问它的视图使用。该中间件放在最前面,在任何其他处理之前应用于所有请求:所有页面,包括错误页面,都使用正确的语言;
  • 第 62–69 行:被拒绝的 HTTP 方法(对 [/logout] 的 GET 调用,它只接受 POST)不会抛出异常:装饰器 [require_GET]、[require_POST]……会返回一个没有内容的 405 响应。[__call__] 用错误页面替换它,同时保留 [Allow] 头部(允许的方法),405 响应必须包含该头部;
  • 第 71–78 行:视图抛出的异常([process_exception],示例 24)。[InvalidSession] (账户已被删除):显示“会话已过期”消息,删除令牌 Cookie,并转到登录页面。视图抛出的 HTTP 错误([BadRequest]、[PermissionDenied]、[Http404]):显示带有错误代码的错误页面,生产环境和开发环境都一样。任何其他异常都是真正的异常情况:该方法返回 [None],由 [Django] 自己处理;它会记录日志及其调用栈,然后在开发环境中显示其调试页面,在生产环境中显示 500 错误页面([handler500])。生产环境中的用户永远看不到应用的调用栈。
1
2
3
4
5
6
7
$ curl -si http://localhost:8081/logout
HTTP/1.1 405 Method Not Allowed
Content-Type: text/html; charset=utf-8
Allow: POST
...
<!doctype html>
...

405 代码(Method Not Allowed)在用户看来是页面未找到(错误页面消息,下面讨论)。不匹配任何路由的 URL 不会经过 [ErrorPage]:[Django] 在生产环境中直接调用 [handler404] 视图,在开发环境中显示其详细的 404 页面(示例 24)。

11.14. 词典

界面文本与应用的其他版本相同,那些版本把它存放在 JSON 文件中,以键标识([LOGIN.TITLE] 指向文本 [Sign in])。[Django] 的做法不同(示例 22):英文原文直接写在代码中([_("Sign in")])和模板中([{% translate "Sign in" %}]);它充当法语词典(文件 [locale/fr/LC_MESSAGES/django.po])中的键:

#: web/views/schedule.py:202 web/views/area.py:75
msgid "Appointment cancelled."
msgstr "Rendez-vous annulé."

#: web/views/auth.py:62 web/views/area.py:142
#, python-format
msgid "Too many failed attempts. Try again in %(minutes)d minute."
msgid_plural "Too many failed attempts. Try again in %(minutes)d minutes."
msgstr[0] "Trop de tentatives infructueuses. Réessayez dans %(minutes)d minute."
msgstr[1] ""
"Trop de tentatives infructueuses. Réessayez dans %(minutes)d minutes."

这个文件包含大约 140 条文本,此处不予重现。它由命令 [python manage.py makemessages -l fr] 生成,该命令会提取代码和模板中标记的所有文本,然后手工补全,并由 [python manage.py compilemessages] 编译为 [django.mo](示例 22)。编译后的 [django.mo] 文件随代码一起交付:应用在没有 [gettext] 工具的情况下也能运行。没有英语词典:没有译文的文本按原样显示,也就是显示为英语。

[#:] 行指明每条文本在哪里使用;[#, python-format] 标识带参数的文本([%(minutes)d]),[makemessages] 会验证其译文。[gettext] 实现了其他版本做不到的事情:复数形式(“1 minute”、“15 minutes”),代码中使用 [ngettext] (见下文),词典中使用 [msgid_plural] (示例 22)。还添加了一些文本:第 419 页上的消息,其他版本没有它。

表单错误消息以同样的方式翻译(见下文)。[Django] 自己生成的消息(数字过大、电子邮件地址无效等)使用来自 [Django] 的词典翻译。

11.15. 表单

“人员”表单是 [Django] 表单(示例 18 和 19):一个类描述字段及其约束;视图用用户的输入构建表单([PersonForm(request.POST)]),然后检查它是否有效([is_valid])。无效的表单会重新显示,展示用户的输入以及字段下方的错误消息(密码除外:[PasswordInput] 字段永远不会重新显示)。所有表单的防 CSRF 令牌都由 [CsrfViewMiddleware] 中间件验证。

11.15.1. web/forms.py

# =========================================================================
# web/forms.py:“人员”表单及其约束(见
# 示例 18 和 19)。三个表单共享相同的身份字段
# (称谓、名、姓):
#
#   PersonFieldsForm            称谓、名、姓
#    ├─ PersonForm              + 可选的登录名 / 密码、版本
#    │                            (ADMIN 添加或更新医生 / 客户)
#    ├─ RegistrationForm        + 必填的登录名 / 密码 / 确认密码
#    │                            (患者创建其账户)
#    └─ MyAccountForm           + 登录名、可选的新密码、必填的
#                                 当前密码、版本
#                                 (患者更新其账户)
#
# 子类继承自 PersonFieldsForm:它们拥有其字段,外加
# 各自的字段。经过验证的输入(cleaned_data)由 person_data() 方法转换为
# 供业务层使用的 PersonData。
#
# 标签、帮助文本和错误消息都经过翻译(gettext_lazy,
# 见 business/errors.py)。最大长度与 SQL 列的长度一致。
# =========================================================================

from django import forms
from django.core.exceptions import ValidationError
from django.core.validators import RegexValidator
from django.utils.translation import gettext_lazy as _

from business.person_data import PersonData
from security import passwords

TITLES = ["Mr", "Mme", "Melle"]
# 患者所选密码的最小长度
PASSWORD_MIN = 6

# 登录名:小写字母、数字、点、连字符、下划线 - 最多 30 个字符
LOGIN_FORMAT = RegexValidator(r"^[a-z0-9._-]{1,30}$", message=_(
    "At most 30 characters: unaccented lower-case letters, digits, dot, hyphen, underscore."))


# bcrypt 只考虑密码的前 72 个字节(见
# security/passwords.py);带重音的字母在 UTF-8 中占两个字节
def bcrypt_length(value: str) -> None:
    if len(value.encode()) > passwords.MAX_BYTES:
        raise ValidationError(_("The password must not exceed 72 characters."))


# -------------------------------------------------------------------------
# 登录名始终为小写:该字段在验证之前
# 转换输入(to_python 在验证器之前调用)
# -------------------------------------------------------------------------
class LoginField(forms.CharField):
    def to_python(self, value):
        text = super().to_python(value)
        return text.lower() if text else text


# 密码字段:从不重新显示,且不去除空格
# (strip=False:空格也是密码的一部分)
def password_field(label, required, help_text="", min_length=None):
    messages = {
        "required": _("The password is required."),
        # %(limit_value)d:最小长度,由 Django 放入消息中
        "min_length": _("The password must be at least %(limit_value)d characters long."),
    }
    return forms.CharField(label=label, required=required, help_text=help_text, strip=False,
                           min_length=min_length, validators=[bcrypt_length],
                           error_messages=messages,
                           widget=forms.PasswordInput(attrs={"maxlength": 72,
                                                             "autocomplete": "new-password"}))


# -------------------------------------------------------------------------
# 我们表单的父类(见示例 18):每个输入区域都会获得
# 适合它的 Bootstrap CSS 类;flag() 会用红色框出(类
# is-invalid)有输入错误的字段,以及业务错误
# 所指向的字段(登录名已被占用……),此时消息位于页面底部
# -------------------------------------------------------------------------
class BootstrapForm(forms.Form):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        for field in self.fields.values():
            css_class = "form-select" if isinstance(field.widget, forms.Select) else "form-control"
            field.widget.attrs["class"] = css_class

    def flag(self, fields=()):
        # errors:输入错误;|:两个集合的并集
        for name in set(self.errors) | set(fields):
            if name in self.fields:
                self.fields[name].widget.attrs["class"] += " is-invalid"
        return self


class PersonFieldsForm(BootstrapForm):
    title = forms.ChoiceField(label=_("Title"), choices=[(t, t) for t in TITLES], error_messages={
        "required": _("Choose a title from the list."),
        "invalid_choice": _("Choose a title from the list.")})
    first_name = forms.CharField(label=_("First name"), max_length=20, error_messages={
        "required": _("The first name is required."),
        "max_length": _("The first name must not exceed 20 characters.")})
    last_name = forms.CharField(label=_("Last name"), max_length=20, error_messages={
        "required": _("The last name is required."),
        "max_length": _("The last name must not exceed 20 characters.")})

    # 经过验证的输入 -> 业务层期望的数据。空
    # 字段为 None(或 None:空字符串为“假值”)
    def person_data(self) -> PersonData:
        d = self.cleaned_data
        return PersonData(d["title"], d["last_name"], d["first_name"], d.get("login") or None,
                          d.get("password") or None, d.get("version"))


# 医生或客户的表单(ADMIN):可选的登录名和
# 密码;creation=False:带版本的更新表单
class PersonForm(PersonFieldsForm):
    def __init__(self, *args, creation=True, **kwargs):
        super().__init__(*args, **kwargs)
        # 允许空字段:验证器只对已输入的值生效
        self.fields["login"] = LoginField(
            label=_("Login"), required=False, max_length=30, validators=[LOGIN_FORMAT],
            help_text=_("Optional: defaults to the last name in lower case.") if creation
            else _("Leave empty to keep it unchanged."),
            widget=forms.TextInput(attrs={"class": "form-control", "autocomplete": "off"}))
        self.fields["password"] = password_field(
            _("Password"), False,
            _("Optional: defaults to the login.") if creation
            else _("Leave empty to keep it unchanged."))
        self.fields["password"].widget.attrs["class"] = "form-control"
        # 更新:所显示记录的版本,放在隐藏字段中(
        # 乐观锁)
        if not creation:
            self.fields["version"] = forms.IntegerField(widget=forms.HiddenInput)


# -------------------------------------------------------------------------
# 密码及其确认:两个字段,由 clean 比较(见
# 示例 19)。注册(必填)和患者账户
# (可选:为空 = 密码不变)共用
# -------------------------------------------------------------------------
class WithConfirmation(PersonFieldsForm):
    def add_passwords(self, required: bool):
        self.fields["login"] = LoginField(
            label=_("Login"), max_length=30, validators=[LOGIN_FORMAT],
            help_text=_("Unaccented lower-case letters, digits, dot, hyphen, underscore.")
            if required else "",
            error_messages={"required": _("The login is required.")},
            widget=forms.TextInput(attrs={"class": "form-control", "autocomplete": "username"}))
        self.fields["password"] = password_field(
            _("Password") if required else _("New password"), required,
            _("At least 6 characters.") if required else _("Leave empty to keep it unchanged."),
            min_length=PASSWORD_MIN)
        self.fields["confirmation"] = password_field(_("Confirm password"), required)
        self.fields["confirmation"].error_messages["required"] = _("Please confirm the password.")
        for name in ("password", "confirmation"):
            self.fields[name].widget.attrs["class"] = "form-control"

    # 在每个字段验证之后,对整个表单进行验证
    def clean(self):
        data = super().clean()
        password = data.get("password")
        confirmation = data.get("confirmation")
        if password and password != confirmation and "confirmation" not in self.errors:
            self.add_error("confirmation", _("The confirmation does not match the password."))
        return data


# “创建患者账户”:登录名、密码和确认密码均为必填
class RegistrationForm(WithConfirmation):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.add_passwords(required=True)


# “管理我的账户”(患者):登录名必填,新密码可选,
# 当前密码必填,版本
class MyAccountForm(WithConfirmation):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.add_passwords(required=False)
        # 当前密码,任何账户更新都需要提供
        self.fields["current_password"] = forms.CharField(
            label=_("Current password"), strip=False,
            help_text=_("Required to save any change."),
            error_messages={"required": _("Enter your current password.")},
            widget=forms.PasswordInput(attrs={"class": "form-control", "maxlength": 72,
                                              "autocomplete": "current-password"}))
        self.fields["version"] = forms.IntegerField(widget=forms.HiddenInput)

三个表单共用身份字段(称谓、名、姓):管理员表单(用于医生或患者)、患者账户创建表单,以及“管理我的账户”。头部注释概述了它们的继承层次:它们共同的父类 [PersonFieldsForm] 定义身份字段;每个子类再添加各自的字段。标签、提示文字和消息采用惰性翻译([gettext_lazy]):它们在模块加载时定义,并在每次显示页面时按请求的语言翻译(业务层,前面已提到)。

  • 第 36–37 行:登录名表单,一个检查正则表达式的验证器([RegexValidator])。验证器是一个可调用对象,对不正确的值会抛出 [ValidationError] (示例 19);通过字段的参数 [validators] 将它指派给字段;
  • 第 42–44 行:写成简单函数的验证器。[bcrypt] 只考虑密码的前 72 个字节(安全层,前面已讨论):该限制针对字节,而不是字符([encode()]:带重音的字母在 [UTF-8] 中占两个字节);
  • 第 51–54 行:用户名始终为小写。一个自定义字段,是 [CharField] 的子类,重新定义了 [to_python],即把输入转换为 Python 值的方法:它在验证器之前被调用,因此验证器检查的是已经转换后的输入。[super().to_python(value)] 首先执行 [CharField] 的标准处理(去掉输入两端的空格);
  • 第 59–69 行:创建密码字段的函数。[strip=False]:不去除空格;它们可以是密码的一部分。[min_length]:最小长度,由 [Django] 自己检查;其消息包含 [%(limit_value)d],即 [Django] 放在那里的参数。[PasswordInput] 小部件永远不会重新绘制;HTML 属性 [maxlength] 阻止用户输入超过 72 个字符;[autocomplete="new-password"] 指示浏览器提示输入新密码,而不是用已保存的密码填充该字段;
  • 第 78–90 行:我们的表单的父类(示例 18)。它的构造函数为每个输入字段指定合适的 CSS 类 (列表使用 [form-select] ,其他字段使用 [form-control] )。[flag] 方法会为有输入错误的字段,以及被业务规则错误标记的字段(已被使用的用户名)添加 [is-invalid] 类(红色边框):[set(a) | set(b)] 是两个集合的并集。它返回表单本身:视图在把表单传给模板时调用它;
  • 第 93–102 行:称谓,一个列表([ChoiceField],示例 18);名和姓,最多 20 个字符,即 SQL 的列宽(输入区域中的 [maxlength] 字段由 [Django] 自己添加)。每条错误消息都被替换为我们自己的([error_messages],示例 19)。[invalid_choice] 是针对不在列表中的值(手工构造的请求)的消息。输入两端的空格由 [CharField] 去除;
  • 第 106–109 行:已验证的输入([cleaned_data]),转换为供业务层使用的 [PersonData] :业务层不了解表单。[d.get(key)] 对于表单没有的字段返回 [None];[x or None] 将空字符串转换为 [None] (保持不变,或使用默认值);
  • 第 114–131 行:管理员的表单。我们自己创建的参数 [creation] 用来区分创建和修改;它放在 [*args] 之后:它是一个必需的参数([PersonForm(request.POST, creation=False)])。该表单特有的字段由构造函数添加到 [self.fields] 字典中:它们的选项取决于 [creation] (提示文字不同:“Optional: defaults to the last name in lower case.”、“Leave empty to keep it unchanged.”)。用户名和密码是可选的([required=False]):验证器只作用于已输入的值,因此空字段会被接受。只有“修改”表单才有隐藏的“version”字段(乐观锁,业务层);
  • 第 139–163 行:密码及其确认,注册和患者的账户两者共用。两个字段通过表单的 [clean] 方法(示例 19)进行比较,该方法在每个字段验证之后调用。[add_error] 将消息附加到确认字段,除非该字段已经有错误(“Please confirm the password.”):每个字段只有一条消息。最小长度要求只适用于患者自己选择的密码(6 个字符);
  • 第 167–170 行:创建患者账户:登录名、密码和确认密码都是必填的;
  • 第 175–186 行:“管理我的账户”:新密码是可选的(留空:不变),当前密码是必填的。它不由表单验证,而由视图验证:不正确的密码必须被尝试次数限制器计为一次登录失败。[autocomplete="current-password"]:这里,浏览器可以建议已保存的密码。

11.15.2. web/rendering.py

1
2
3
4
5
6
7
8
9
# web/rendering.py:表单的渲染引擎(见示例 18):一个完整的
# 字段(标签、输入区域、帮助、错误)由模板
# templates/forms/field.html 绘制,使用 Bootstrap 5 类

from django.forms.renderers import TemplatesSetting


class BootstrapRenderer(TemplatesSetting):
    field_template_name = "forms/field.html"

示例 18 中的表单渲染引擎,由 [config/settings.py] 的设置 [FORM_RENDERER] 定义:每个完整的字段(标签、输入字段、提示文字、错误消息)都使用 [templates/forms/field.html] 模板渲染(稍后讨论),并使用来自 [Bootstrap] 的类。

11.16. 视图模型

# =========================================================================
# web/view_models.py:“视图模型”:由视图
# 一次性构建的对象,模板只负责读取。所有页面
# 遵循的规则:模板中不放逻辑。视图准备好
# 已格式化的数据(“Mme Marie PELISSIER”、“8:00 - 8:20”、
# selected = True……),并且已按用户的角色过滤;
# 模板只是把它们放进 HTML 中。
# =========================================================================

from dataclasses import dataclass


# 下拉列表的一个选项(医生、患者)
@dataclass(frozen=True)
class OptionView:
    id: int
    label: str
    selected: bool


# 所显示日程的一行(一个时段)
@dataclass(frozen=True)
class ScheduleRow:
    slot_id: int
    time_range: str         # "8:00 - 8:20"
    free: bool
    # 已占用时段显示的名称;None = “已预约”
    patient: str | None
    me: bool                # 已登录患者的预约
    bookable: bool          # 是否显示“预约”按钮?
    book_url: str
    # 仅在显示“取消”按钮时设置
    appointment_id: int | None


# 所显示的日程:医生、日期、各行
@dataclass(frozen=True)
class ScheduleView:
    doctor: str             # "Mme Marie PELISSIER"
    day: str                # "Wednesday 23 September 2026"
    rows: list[ScheduleRow]


# 时段的预约对话框
@dataclass(frozen=True)
class BookingView:
    slot_id: int
    time_range: str
    # ADMIN / DOCTOR:可供选择的患者
    clients: list[OptionView]
    # USER:患者就是其本人
    patient: str | None


# 患者空间中的一个未来预约
@dataclass(frozen=True)
class AppointmentView:
    id: int
    day: str                # "Wednesday 23 September 2026"
    time_range: str         # "8:00 - 8:20"
    doctor: str             # "Mme Marie PELISSIER"
    schedule_url: str       # 医生当天的日程

文件 [web/view_models.py] 包含视图模型:由视图构造、模板只需读取的对象。所有页面都遵循的规则:模板中没有逻辑。视图准备好已经格式化(“Ms. Marie PELISSIER”、“8:00 – 8:20”)并已按用户角色过滤的数据;模板只是把它们放入 HTML。这些是不可变的数据类([frozen=True],示例 08):视图模型一经构造就不再改变。

  • 第 14–18 行:下拉列表中的一个选项:ID、标签,以及该选项是否被选中。
  • 第 22–33 行:日程表中的一个条目:一个时段,以及已登录用户被授权查看它的哪些内容、对它做哪些操作。[patient] 仅在用户被授权查看患者姓名时才会填充;[bookable] 表示是否显示“预约”按钮;[appointment_id] 表示是否显示“取消”按钮;
  • 第 37–52 行:显示的日程表和预约窗口:对于管理员和医生,是可供选择的患者列表;对于患者,是其本人的姓名;
  • 第 56–62 行:患者区域中的一个即将到来的预约。

11.17. Web 层:路由和视图

11.17.1. 路由

# =========================================================================
# web/urls.py:应用的路由。其保护不在这里编写,
# 而在 security/access.py 中(每个 URL 前缀一条规则)。
# =========================================================================

from django.urls import path, re_path

from .views import area, auth, language, registration, schedule
from .views.persons import clients, doctors

urlpatterns = [
    # 登录
    path("", auth.home, name="home"),
    path("login", auth.login, name="login"),
    path("logout", auth.logout, name="logout"),
    # 语言:仅限 fr 或 en
    re_path(r"^language/(?P<code>fr|en)$", language.change, name="language"),
    # 日程
    path("schedule", schedule.show, name="schedule"),
    path("schedule/book", schedule.book, name="schedule_book"),
    path("schedule/cancel", schedule.cancel, name="schedule_cancel"),
    # 客户账户的创建
    path("register/access", registration.access, name="registration_access"),
    path("register", registration.registration, name="registration"),
    # 患者空间
    path("my-area", area.area, name="area"),
    path("my-area/cancel", area.cancel_appointment, name="area_cancel"),
    path("my-account", area.account, name="account"),
    path("my-account/delete", area.delete_account, name="account_delete"),
    # 医生和客户的管理:由两个 PersonManagement 对象构建的路由;
    # * 会“解包”它们返回的列表
    *doctors.urls(),
    *clients.urls(),
]

应用的路由,由 [config/urls.py] 挂载在站点根路径下。管理医生和患者的路由由两个对象生成(稍后讨论);[*list] 将一个列表的元素放入另一个列表(第 32–33 行)。命令 [show_urls] 在 [Django] 中并不存在(它来自一个扩展);由 [python manage.py shell] 启动的一个简短脚本可以列出所有路由及其名称:

$ python manage.py shell -v 0 -c "from django.urls import get_resolver; [print(f'{str(p.pattern):32} {p.name}') for p in get_resolver().url_patterns[0].url_patterns]"
                                 home
login                            login
logout                           logout
^language/(?P<code>fr|en)$       language
schedule                         schedule
schedule/book                    schedule_book
schedule/cancel                  schedule_cancel
register/access                  registration_access
register                         registration
my-area                          area
my-area/cancel                   area_cancel
my-account                       account
my-account/delete                account_delete
doctors                          doctors_list
doctors/add                      doctors_add
doctors/<int:id>/edit            doctors_edit
doctors/<int:id>/delete          doctors_delete
clients                          clients_list
clients/add                      clients_add
clients/<int:id>/edit            clients_edit
clients/<int:id>/delete          clients_delete

这些 URL 与应用其他版本的相同:它们没有末尾的斜杠([/schedule],而不是 [/schedule/]),并且编辑和删除医生是 POST 请求([/doctors/{id}/edit]、[/doctors/{id}/delete]),而不是示例 28 中的 PUT 和 DELETE。代码始终根据路由名称生成 URL([redirect("login")]、[reverse("schedule")]、[{% url 'schedule' %}] 在模板中,示例 04):更改 URL 只需修改它的路由。

每个路由接受的方法由视图中的 [require_GET]、[require_POST]和 [require_http_methods] 装饰器声明(示例 02)。访问规则不在视图中,而在前面看到的 [security/access.py] 文件中:每个 URL 前缀一条规则(管理员用 [^/(doctors|clients)] ,患者用 [^/my-] ……),最后一条规则要求所有其他 URL 的用户都已通过身份验证。应用中的 URL 正是为此而选定的:同一角色的所有页面都以相同的方式开头。

11.17.2. web/views/errors.py

# =========================================================================
# web/views/errors.py:错误页面(400、403、404、405、419、500),以及
# Django 在自行检测到错误时调用的视图(见 config/urls.py:
# handler400、handler403、handler404、handler500,以及 CSRF_FAILURE_VIEW 设置)。
# =========================================================================

from django.shortcuts import render
from django.utils.translation import gettext_lazy as _

# 每个代码对应的消息
MESSAGES = {
    400: _("The request is invalid."),
    403: _("Your role does not allow you to access this page."),
    404: _("This page does not exist."),
    405: _("This page does not exist."),
    419: _("The page has expired: reload it, then try again."),
    500: _("An unexpected error occurred. Please try again later."),
}


def error_page(request, code: int):
    return render(request, "error.html", {
        "page_title": _("Error"), "code": code, "message": MESSAGES.get(code, MESSAGES[500]),
    }, status=code)


# Django 检测到的错误的视图(exception:引发
# 错误的异常;500 视图不会收到它)
def error_400(request, exception):
    return error_page(request, 400)


def error_403(request, exception):
    return error_page(request, 403)


def error_404(request, exception):
    return error_page(request, 404)


def error_500(request):
    return error_page(request, 500)


# -------------------------------------------------------------------------
# 防 CSRF 令牌缺失或错误:该页面很可能是很久以前
# 在另一个标签页中显示的,在令牌 Cookie 更改之前……错误
# 419,页面过期的(非官方但很常见的)代码。reason:
# CsrfViewMiddleware 给出的拒绝原因(英文)
# -------------------------------------------------------------------------
def csrf_rejected(request, reason=""):
    return error_page(request, 419)

错误页面以及 [Django] 自己检测到的错误的视图:

  • 第 11–18 行:每个代码对应的消息。405 代码显示为“页面未找到”错误;
  • 第 21–24 行:错误页面,模板 [error.html],带有 HTTP 响应代码([status=code])。未知的代码得到 500 错误消息([dict.get(key, default)]);
  • 第 29–42 行:四个视图 [handler400]……[handler500],在 [config/urls.py] 中引用(示例 24)。它们的签名由 [Django] 决定:请求和导致错误的异常(500 错误除外);
  • 第 51–52 行:缺失或无效的防 CSRF 令牌。[CsrfViewMiddleware] 中间件在调用视图之前拒绝请求(示例 21),转而调用与 [CSRF_FAILURE_VIEW] 设置关联的视图(见 [config/settings.py]):419 错误页面,这是表示页面已过期的(非官方但被广泛使用的)代码。当页面在标签页中长时间保持打开,而令牌 Cookie 在此期间已经改变时,就会发生这种情况。页面随后显示:“The page has expired: reload it, then try again.” 它的参数 [reason] 是拒绝的原因,用英语书写,用于日志而不是给用户看。

11.17.3. web/views/language.py

# =========================================================================
# web/views/language.py:GET /language/fr、GET /language/en:导航栏中的
# FR / EN 两个按钮。公开路由:必须能在
# 登录之前切换语言。
#
# 所做的选择会记在 Cookie 中:在之后的每次请求中,中间件
# SetLanguage 会重新读取它并设置请求的语言。然后返回到
# 我们来的那个页面(见示例 22)。
# =========================================================================

from urllib.parse import urlsplit

from django.conf import settings
from django.shortcuts import redirect
from django.views.decorators.http import require_GET


# code:fr 或 en(见 web/urls.py:/language/de 会得到 404 页面)
@require_GET
def change(request, code):
    response = redirect(origin_page(request))
    response.set_cookie(settings.LANGUAGE_COOKIE_NAME, code, max_age=365 * 24 * 3600,
                        secure=settings.COOKIE_SECURE, httponly=True, samesite="Lax")
    return response


# -------------------------------------------------------------------------
# 上一个页面,取自浏览器发送的 HTTP “Referer” 头。只
# 保留其路径和参数(/schedule?...):重定向到请求提供的
# 完整地址会使用户被送到
# 另一个站点(即所谓“开放重定向”漏洞)。urlsplit 将 URL 拆分为
# 各组成部分:scheme(http)、netloc(主机)、path、query……
# -------------------------------------------------------------------------
def origin_page(request) -> str:
    referer = urlsplit(request.headers.get("Referer", ""))
    path = referer.path
    # “//site.com/...”会被浏览器理解为
    # 另一个站点上的地址:同样拒绝
    if not referer.scheme or not path.startswith("/") or path.startswith("//") \
            or path.startswith("/language/"):
        return "/"
    return f"{path}?{referer.query}" if referer.query else path

导航栏上的 FR / EN 按钮:所选语言存储在一个有效期一年的 Cookie 中(示例 22),然后浏览器返回到它来自的页面。该 Cookie 是 [HttpOnly] 的:页面上的 [JavaScript] 不需要读取它。它没有签名:[SetLanguage] 中间件会验证它的值,未知的值将使用英语(见关于作用域的章节)。

  • 第 20 行:[code] 等于 [fr] 或 [en]:该路由(一个正则表达式,[re_path],示例 02)只接受这两个值。[/language/de] 不匹配任何路由(404 页面);
  • 第 34–42 行:上一个页面由浏览器随请求发送的 HTTP 头部 [Referer] 指定。这个数据由客户端提供,因此是可疑的:如果直接重定向到请求中的完整 URL,攻击者就可以借助带有伪造 [/language/fr] 链接的 [Referer] ,把用户送到其自己的站点(即所谓的“开放重定向”漏洞)。因此,我们只保留路径和参数([/schedule?doctorId=1&...]),由标准库的 [urlsplit] 函数提取,它把 URL 拆分为各个部分([scheme]、[netloc]、[path]、[query]……)。以 [//] 开头的路径同样会被拒绝:浏览器会把 [//site.com/page] 解释为另一个站点上的地址。最后,不能返回到 [/language/...]:那会形成循环。行尾的反斜杠([\])会将([Python])语句延续到下一行。
1
2
3
4
5
6
7
8
9
$ curl -si http://localhost:8081/language/fr -H "Referer: http://localhost:8081/schedule?doctorId=1&day=2026-09-30"
HTTP/1.1 302 Found
Location: /schedule?doctorId=1&day=2026-09-30
Set-Cookie: rdvmedecins_language=fr; expires=Mon, 27 Sep 2027 17:56:57 GMT; HttpOnly; Max-Age=31536000; Path=/; SameSite=Lax
...
$ curl -si http://localhost:8081/language/fr -H "Referer: https://pirate.com//page"
HTTP/1.1 302 Found
Location: /
...

11.17.4. web/views/auth.py

# =========================================================================
# web/views/auth.py:登录的公开路由:
#   GET  /        重定向到该角色的主页(或 /login)
#   GET  /login   显示登录表单(带验证码)
#   POST /login   检查尝试次数限制、验证码、登录名 / 密码
#   POST /logout  退出登录
#
# 针对机器人的保护,按以下顺序:
#   1. 该 IP 地址对该登录名最近失败次数过多?
#      -> 立即拒绝,甚至不查看密码;
#   2. 验证码回答错误?-> 拒绝(计为一次失败);
#   3. 到这时才检查密码。
# 在第 1 步或第 2 步被拒绝的尝试,其密码永远不会被检查:
# 因此机器人即使反复尝试也学不到任何东西。
# =========================================================================

from django.shortcuts import redirect, render
from django.utils.translation import gettext as _, ngettext
from django.views.decorators.http import require_GET, require_http_methods, require_POST

from models.models import Role
from security import auth, captchas, limiter

from .. import utils


# 每个角色在登录之后的主页:其路由的名称
def home_page(role: str) -> str:
    return "area" if role == Role.USER else "schedule"


# GET /:该路由是公开的;如果有用户,则已知该用户
@require_GET
def home(request):
    if request.user is not None:
        return redirect(home_page(request.user.role))
    return redirect("login")


# GET /login[?login=xxx]:表单;可选参数会预填
# 登录名字段(用于创建账户之后,见 views/registration.py)。
# POST /login:登录
@require_http_methods(["GET", "POST"])
def login(request):
    if request.method == "POST":
        return log_in(request)
    # 已经登录(令牌仍然有效):直接前往主页
    if request.user is not None:
        return redirect(home_page(request.user.role))
    # [:30]:最多 30 个字符
    return page(request, request.GET.get("login", "")[:30], None)


def log_in(request):
    login = request.POST.get("login", "")
    password = request.POST.get("password", "")
    ip = utils.ip(request)
    # 1. 最近失败次数过多?ngettext:根据数量选择单数或复数
    minutes = limiter.login_block_minutes(ip, login)
    if minutes > 0:
        return page(request, login, ngettext(
            "Too many failed attempts. Try again in %(minutes)d minute.",
            "Too many failed attempts. Try again in %(minutes)d minutes.",
            minutes) % {"minutes": minutes})
    # 2. 验证码
    if not captchas.verify(request.POST.get("captcha_id", ""), request.POST.get("captcha", "")):
        limiter.login_failure(ip, login)
        return page(request, login, _("The characters you typed do not match the image. "
                                      "A new image is shown."))
    # 3. 密码
    user = auth.validate(login, password) if login and password else None
    if user is None:
        limiter.login_failure(ip, login)
        return page(request, login, _("Incorrect login or password."))
    limiter.login_success(ip, login)
    return auth.set_token(redirect(home_page(user.role)), user)


# POST /logout:清除令牌 Cookie,然后前往登录页面。
# 仅限 POST:放在另一个站点上的简单链接(GET),
# 无法在用户不知情的情况下使其退出登录
@require_POST
def logout(request):
    return auth.clear_token(redirect("login"))


# 表单,始终带有新的验证码(每张图像只使用
# 一次);重新显示输入的登录名,绝不显示密码。出现错误时:
# 返回 422 代码,与无效表单相同(见示例 19)
def page(request, login: str, error: str | None):
    return render(request, "login.html", {
        "page_title": _("Sign in"), "error": error, "login": login,
        "captcha": captchas.generate(),
    }, status=422 if error else 200)

连接,遵循示例 27:

  • 第 28–29 行:每个角色的主页及其路由名称:患者是“我的空间”,其他人是日程表;
  • 第 33–37 行:地址 [/] 重定向到角色的主页或登录页面。该路由是公开的(security/access.py):[request.user] 是由 [Authentication] 中间件确定的用户(如果有的话);
  • 第 43–51 行:已登录的用户会被直接带到其主页。URL 的可选参数 [login] 用于预填该字段(创建账户之后);[[:30]] 将其截断为 30 个字符;
  • 第 54–76 行:登录流程,按示例 27 所示的顺序:可能的封锁、验证码、密码(防 CSRF 令牌已由中间件验证)。对于被限制器或验证码拒绝的尝试,永远不会验证密码:机器人坚持尝试也学不到任何东西。[ngettext(singular, plural, number)] (第 61–64 行)按请求的语言,为该数字选择合适的格式(示例 22);参数 [%(minutes)d] 在翻译之后才被设置。如果尝试失败,页面会被直接渲染(不重定向):重新显示的表单总是带有新的验证码和已输入的登录名。如果成功,登录计数器会被重置为零,浏览器会带着令牌 Cookie 被重定向到该角色的主页;
  • 第 82–84 行:退出登录会删除令牌 Cookie(示例 25)。它只接受 POST,并附带防 CSRF 令牌:放在其他站点上的简单链接无法在用户不知情的情况下让其退出登录;
  • 第 90–94 行:登录页面。出错时返回代码 422(Unprocessable Content),例如表单无效(示例 19)。

登录页面接收变量 [page_title],即页面标题,它已经翻译好:所有视图都把它提供给各自的模板,用于 [<title>] 标签和页面标题(见下文)。

11.17.5. web/views/schedule.py

# =========================================================================
# web/views/schedule.py:日程页面:选择医生和日期,
# 显示该医生当天的日程,预约和取消预约。
#
#   GET  /schedule?doctorId=1&day=2026-09-23              页面
#   GET  /schedule?doctorId=1&day=2026-09-23&book=7       同一页面,并打开
#                                                         预约对话框
#                                                         (时段 7)
#   POST /schedule/book                                   创建预约
#   POST /schedule/cancel                                 取消预约
#
# 整个页面由其 URL 描述:可以重新加载、加入书签,
# 可以使用浏览器的“后退”按钮 - 而不需要一行
# JavaScript。
#
# 每种角色能看到什么、能做什么:
#
#   | 角色          | 已占用时段的显示                  | 预约               | 取消    |
#   |———————————————|———————————————————————————————————|————————————————————|—————————|
#   | ADMIN, DOCTOR | 患者姓名                          | 为某位患者         | 是      |
#   |               |                                   | 从列表中选择       |         |
#   | USER(患者)  | “已预约”,如果是其自己的预约则为  | 为自己预约,如果   | 否 (*)  |
#   |               | 其本人姓名                        | 没有未来的         |         |
#   |               |                                   | 预约               |         |
#
#   (*) 患者从其“我的空间”页面取消自己的预约。
#
# 保密性:对于患者,其他患者的姓名并不是
# 简单地被模板隐藏 - 而是根本不会传给模板。因此发送给浏览器的
# HTML 中并不包含它,甚至隐藏的也没有(否则只要“查看
# 页面源代码”就会暴露它)。
#
# 不能预约过去的时间:“预约”按钮只会出现在
# 今天和之后的日期(并且业务层无论如何也会
# 拒绝)。
#
# 安全:所有 /schedule URL 都要求已通过身份验证的用户,
# /schedule/cancel 要求 ADMIN 或 DOCTOR 角色(见 security/access.py)。
# =========================================================================

from dataclasses import dataclass
from datetime import date
from urllib.parse import urlencode

from django.contrib import messages
from django.core.exceptions import BadRequest
from django.shortcuts import redirect, render
from django.urls import reverse
from django.utils.translation import gettext as _
from django.views.decorators.http import require_GET, require_POST

from domain.schedule import DoctorDaySchedule
from business import errors
from business.dates import today
from business.errors import BusinessError
from models.models import Client, Person, Role

from .. import utils
from ..application import application
from ..view_models import BookingView, OptionView, ScheduleRow, ScheduleView


# 谁已登录,他们在此页面上被允许做什么?
@dataclass(frozen=True)
class Rights:
    manager: bool                      # ADMIN 或 DOCTOR
    patient: Client | None             # 已登录的客户(USER 角色),否则为 None
    patient_can_book: bool             # 没有即将到来预约的 USER


# -------------------------------------------------------------------------
# GET /schedule
# URL 参数按原始值读取(request.GET),以区分
# 缺失的参数(None)和为空的参数(?doctorId=)。
# -------------------------------------------------------------------------
@require_GET
def show(request):
    error = None
    user = utils.user(request)
    rights = compute_rights(request)
    app = application()
    # 日期:如果 URL 中的有效则用它,否则用今天
    day = today()
    raw_day = request.GET.get("day")
    if raw_day is not None:
        requested_day = utils.valid_date(raw_day)
        if requested_day is not None:
            day = requested_day
        else:
            error = _("The requested date is not valid.")
    bookable_day = day >= today()
    # 医生:URL 中的医生;没有的话,已登录的医生则为其本人
    raw_doctor_id = request.GET.get("doctorId")
    doctor_id = utils.positive_integer(raw_doctor_id)
    if raw_doctor_id is None and user.role == Role.DOCTOR:
        doctor = app.get_doctor_by_user_id(user.user_id)
        doctor_id = doctor.id if doctor else None
    # 医生的下拉列表
    doctors = [option(d, d.id == doctor_id) for d in app.get_all_doctors()]
    # 日程,如果已选择医生(且日期有效)
    schedule = None
    if doctor_id is not None and error is None:
        doctor_schedule = app.get_doctor_day_schedule(doctor_id, day)
        if doctor_schedule is None:
            error = _("This doctor does not exist (any more).")
        else:
            schedule = schedule_view(doctor_schedule, rights, bookable_day)
    # 预约对话框:仅当请求的时段可以被
    # 该用户预约时
    booking = None
    slot_id = utils.positive_integer(request.GET.get("book"))
    if schedule is not None and slot_id is not None:
        row = next((r for r in schedule.rows if r.slot_id == slot_id and r.bookable), None)
        if row is not None:
            booking = BookingView(
                row.slot_id,
                row.time_range,
                [option(c, False) for c in app.get_all_clients()] if rights.manager else [],
                rights.patient.label() if rights.patient else None)
    return render(request, "schedule.html", {
        "page_title": _("Schedule"),
        "error": error,
        "doctors": doctors,
        "doctor_id": doctor_id,
        "day": utils.iso(day),
        "schedule": schedule,
        "booking": booking,
        # 所显示的日程,不带预约对话框
        "back_url": schedule_url(doctor_id, day) if doctor_id is not None else reverse("schedule"),
        "info": patient_info(rights, schedule),
    })


# -------------------------------------------------------------------------
# POST /schedule/book   字段:doctorId、day、slotId、clientId
#
# 对于患者(USER),clientId 字段会被忽略:他们总是为
# 自己预约。信任浏览器发送的字段会使
# 聪明的患者能够以他人的名义预约。
#
# “Post / Redirect / Get”模式:无论结果如何,这里都不构建页面
# - 留下一条闪现消息并重定向到日程(见示例 20)。
# -------------------------------------------------------------------------
@require_POST
def book(request):
    doctor_id, day = requested_schedule(request)
    slot_id = utils.positive_integer(request.POST.get("slotId"))
    if doctor_id is None or slot_id is None:
        # -> “无效请求”页面(见 web/middleware.py)
        raise BadRequest("invalid schedule or slot")
    app = application()
    user = utils.user(request)
    if user.is_patient:
        client = utils.connected_patient(request)
    else:
        client_id = utils.positive_integer(request.POST.get("clientId"))
        if client_id is None:
            # 没有选择患者:重新打开预约对话框
            messages.error(request, _("Choose a patient."))
            return redirect(schedule_url(doctor_id, day, slot_id))
        client = app.get_client_by_id(client_id)
    slot = app.get_slot_by_id(slot_id)
    if client is None:
        messages.error(request, _("This patient does not exist (any more)."))
    elif slot is None or slot.doctor_id != doctor_id:
        messages.error(request, _("This slot does not exist (any more)."))
    else:
        try:
            # 规则(不在过去、每位患者只能有一个未来的
            # 预约、时段空闲)由业务层检查
            app.add_appointment(day, slot, client)
            messages.success(request, _("Appointment booked."))
        except BusinessError as e:
            # 规则相同,但当预约者是患者本人时
            # 使用第二人称的消息(“您已经有……”而不是“该患者……”)。
            # 其他异常(真正的故障)不会被捕获:500 页面
            if e.code == errors.PATIENT_HAS_APPOINTMENT and user.is_patient:
                messages.error(request, _("You already have an upcoming appointment: "
                                          "cancel it to book another one."))
            else:
                messages.error(request, e.message)
    return redirect(schedule_url(doctor_id, day))


# -------------------------------------------------------------------------
# POST /schedule/cancel   字段:appointmentId、doctorId、day
# (患者从“我的空间”取消自己的预约,而不是从这里)
# -------------------------------------------------------------------------
@require_POST
def cancel(request):
    doctor_id, day = requested_schedule(request)
    appointment_id = utils.positive_integer(request.POST.get("appointmentId"))
    if doctor_id is None or appointment_id is None:
        raise BadRequest("invalid schedule or appointment")
    app = application()
    appointment = app.get_appointment_by_id(appointment_id)
    if appointment is None:
        # 已被取消(被他人取消,或双击导致)
        messages.error(request, _("This appointment does not exist (any more)."))
    else:
        app.delete_appointment(appointment)
        messages.success(request, _("Appointment cancelled."))
    return redirect(schedule_url(doctor_id, day))


# -------------------------------------------------------------------------
# 谁已登录,他们在此页面上被允许做什么?
# -------------------------------------------------------------------------
def compute_rights(request) -> Rights:
    if not utils.user(request).is_patient:
        return Rights(manager=True, patient=None, patient_can_book=False)
    patient = utils.connected_patient(request)
    upcoming = application().get_client_upcoming_appointments(patient.id)
    # not list:列表为空时为 true
    return Rights(manager=False, patient=patient, patient_can_book=not upcoming)


# -------------------------------------------------------------------------
# 医生的日程,为模板格式化 - 并按权限过滤
# -------------------------------------------------------------------------
def schedule_view(doctor_schedule: DoctorDaySchedule, rights: Rights, bookable_day: bool) -> ScheduleView:
    doctor_id = doctor_schedule.doctor.id
    day = doctor_schedule.day
    rows = []
    for dds in doctor_schedule.doctor_day_slots:
        slot = dds.slot
        appointment = dds.appointment
        free = appointment is None
        # 是已登录患者的预约吗?
        me = appointment is not None and rights.patient is not None and appointment.client_id == rights.patient.id
        rows.append(ScheduleRow(
            slot_id=slot.id,
            time_range=slot.time_range(),
            free=free,
            # 保密性的关键点:患者只会收到其自己
            # 预约的姓名;其他预约则为 None(模板显示“已预约”)
            patient=appointment.client.label() if appointment is not None and (rights.manager or me) else None,
            me=me,
            bookable=free and bookable_day and (rights.manager or rights.patient_can_book),
            book_url=schedule_url(doctor_id, day, slot.id),
            appointment_id=appointment.id if appointment is not None and rights.manager else None))
    return ScheduleView(doctor_schedule.doctor.label(), utils.format_day(day), rows)


# ———————————————————————————————— 工具函数
# POST 表单的隐藏字段 doctorId / day;如果无效则为
# (None, None)
def requested_schedule(request) -> tuple[int | None, date | None]:
    doctor_id = utils.positive_integer(request.POST.get("doctorId"))
    day = utils.valid_date(request.POST.get("day"))
    return (None, None) if doctor_id is None or day is None else (doctor_id, day)


# /schedule?doctorId=1&day=2026-09-23[&book=7]:reverse 构建
# 路由的路径,urlencode 构建经过正确编码的 URL 参数(见示例 04)
def schedule_url(doctor_id: int, day: date, book: int | None = None) -> str:
    parameters = {"doctorId": doctor_id, "day": utils.iso(day)}
    if book is not None:
        parameters["book"] = book
    return f"{reverse('schedule')}?{urlencode(parameters)}"


def option(p: Person, selected: bool) -> OptionView:
    return OptionView(p.id, p.label(), selected)


# -------------------------------------------------------------------------
# 已有未来预约的患者的提示消息(说明为什么
# 没有“预约”按钮),或 None。如果其预约出现在
# 所显示的日程中(蓝色),则无需显示:刚刚预约之后
# 就是这种情况,此时该消息显得不合时宜
# -------------------------------------------------------------------------
def patient_info(rights: Rights, schedule: ScheduleView | None) -> str | None:
    if rights.patient is None or rights.patient_can_book:
        return None
    appointment_shown = schedule is not None and any(r.me for r in schedule.rows)
    return None if appointment_shown else _("You already have an upcoming appointment: "
                                            "cancel it to book another one.")

应用的主页面。头部注释概述了每个用户能看到什么、能做什么。

11.17.5.1. 页面的 URL 要素

整个页面由其 URL 描述:[/schedule?doctorId=1&day=2026-09-30] 显示 1 号医生当天的日程;[&book=4] 还会打开预约 4 号时段的窗口。无需一行 [JavaScript] 代码,你就可以重新加载页面、为其添加书签,或使用浏览器的“后退”按钮。页面顶部的表单(用于选择医生和日期)是一个 GET 表单(示例 17):它用新参数重新加载页面。预约窗口通过一个简单的链接打开,并通过指向同一页面但不带 [book] 参数的链接关闭。

11.17.5.2. GET /schedule

第 76–131 行:

  • URL 的参数作为原始数据读取([request.GET.get("day")]),不使用表单:缺失的参数([None])不是错误(默认为今天或没有医生);无效的日期是错误,显示在页面底部(医生和日期的选择仍然显示,但不显示日程表);不是正整数的医生或时段编号则直接被忽略;
  • 尚未选择医生的已登录用户会看到自己的日程:系统根据其账户查找其医生([get_doctor_by_user_id]);
  • 医生的下拉列表:一个列表推导式把每位医生的姓名转换为 [OptionView];
  • 日程表,按用户的权限格式化并过滤([schedule_view],见下文);
  • 预约窗口,仅当请求的时段可由该用户预约时才显示:如果患者试图为一个已被预订的时段构造 URL [&book=2] ,什么也得不到。[next(...)] 返回相应日程表的第一行,或 [None]。患者列表只提供给管理员和医生;患者只能看到自己的姓名;
  • 模板接收其变量([render],示例 13),包括 [page_title] 和 [error],它们由基础模板读取。

11.17.5.3. POST /schedule/book

第 144–182 行:

  • 预约表单的隐藏字段(医生、日期、时段)。无效;这只可能是手工构造的请求:[BadRequest],即“无效请求”页面(400),经由中间件 [ErrorPage];
  • 对于患者,字段 [clientId] 会被忽略:患者始终为自己预约([utils.connected_patient])。如果信任浏览器发送的字段,恶意患者就可以以他人的名义进行预约。对于管理员和医生,必须已选择了患者;否则预约窗口会带着一条消息重新打开;
  • 该时段必须属于页面上的医生([slot.doctor_id]:外键,无需查询);
  • 业务规则(不得预约过去的时间、只能有一个即将到来的预约、时段可用)由业务逻辑层验证。[BusinessError] 会变成一条闪现错误消息。同样的拒绝原因“只能有一个即将到来的预约”,对患者本人以第二人称显示(“You already have…”)。任何其他异常都不会被拦截:这是真正的错误(500 页面);
  • 在所有情况下,都适用 Post/Redirect/Get 模式(示例 20):弹出一条消息并重定向到日程表。

11.17.5.4. POST /schedule/cancel

第 189–203 行:管理员或医生取消预约(规则 [^/schedule/cancel$] 源自 [security/access.py])。已不存在的预约(已被他人取消,或由于双击)不是错误:只是一条消息。

11.17.5.5. 权限、格式化的日程表和工具函数

  • 第 64–68 行和 209–215 行:用户在页面上被授权做什么,放在一个数据类中:用户是管理员(ADMIN 或 DOCTOR)吗?是患者吗(是哪一位)?这位患者能预约吗(没有即将到来的预约)?[not list] 对于空列表为真;
  • 第 221–242 行:医生的日程,转换为供模板使用的行。保密问题在第 237 行:患者只会看到自己预约的姓名。对于其他人,属性 [patient] 被设置为 [None],模板显示“Booked”。姓名不是由模板屏蔽的:它从未传给模板,因此不会出现在页面的源代码中,否则很容易被读取。对于未来日期的空闲时段,“预约”按钮显示给管理员或可以预约的患者;“取消”按钮只显示给管理员。具名参数([slot_id=slot.id])使构造一个有八个属性的对象的代码易于阅读;
  • 第 248–251 行:POST 表单的隐藏字段。该函数返回一个元组,视图将其解包为两个变量([doctor_id, day = requested_schedule(request)],第 146 行和第 191 行);
  • 第 256–260 行:医生某一天日程的 URL。[reverse("schedule")] 返回路由的路径;[urlencode] 生成正确编码的参数:[/schedule?doctorId=1&day=2026-09-30];
  • 第 273–278 行:向患者解释为什么没有“预约”按钮的消息(他们已经有一个即将到来的预约),除非该预约就在显示的日程表中(预约之后马上显示的话,这条消息就会被移走)。[any(...)]:是否至少有一行满足条件?

11.17.6. web/views/persons.py

# =========================================================================
# web/views/persons.py:医生的管理和客户的管理(仅限
# ADMIN)是相同的:相同的列表、相同的表单、相同的规则。与其
# 把同样的视图写两遍,不如只写一次,作为一个类 PersonManagement
# 的方法;这个类的两个对象 doctors 和
# clients,只在区分它们的地方有所不同:版块的名称
# (doctors 或 clients)、文本,以及要调用的 ApplicationModel 的方法。
#
# 对象的方法通过对象(self)调用:视图 object.list(request)
# 因此知道处理的是哪个版块。urls() 方法构建该版块的
# 路由:
#
#   GET  /doctors                    列表                      doctors_list
#   GET  /doctors/add                空表单                    doctors_add
#   POST /doctors/add                创建                      doctors_add
#   GET  /doctors/{id}/edit          预填的表单                doctors_edit
#   POST /doctors/{id}/edit          更新                      doctors_edit
#   POST /doctors/{id}/delete        删除                      doctors_delete
#
# (/clients 下的 URL 同理)。模板也是通用的:
# templates/persons/list.html 和 persons/form.html。
#
# 安全:security/access.py 的规则 ^/(doctors|clients) 将所有这些
# URL 限定为 ADMIN - 包括之后可能添加的 URL。
# =========================================================================

from collections.abc import Callable
from dataclasses import dataclass

from django.contrib import messages
from django.http import Http404
from django.shortcuts import redirect, render
from django.urls import path, reverse
from django.utils.translation import gettext_lazy as _
from django.views.decorators.http import require_GET, require_http_methods, require_POST

from business import errors
from business.errors import BusinessError
from models.models import Person

from ..application import application
from ..forms import PersonForm

# 每种“输入”类业务错误(重复)所涉及的
# 表单字段:它们会被红框标出,消息位于页面底部
BUSINESS_ERROR_FIELDS = {
    errors.LOGIN_TAKEN: ["login"],
    errors.DOCTOR_ALREADY_EXISTS: ["first_name", "last_name"],
    errors.CLIENT_ALREADY_EXISTS: ["first_name", "last_name"],
}


# 每种人员类型特有的文本;%(name)s、%(login)s:消息的
# 参数
@dataclass(frozen=True)
class Texts:
    title: str                  # "Doctors"
    add: str                    # "Add a doctor"
    edit: str                   # "Edit a doctor"
    empty: str                  # "No doctors."
    confirm_delete: str         # "Delete this doctor... ?"
    added: str                  # "Doctor %(name)s has been added (login: %(login)s)."
    updated: str
    deleted: str


class PersonManagement:
    def __init__(self, section: str, texts: Texts, list_all: Callable, find: Callable,
                 create: Callable, update: Callable, remove: Callable):
        # “doctors”或“clients”:路径的开头以及路由名称的开头
        self.section = section
        self.texts = texts
        # 要调用的 ApplicationModel 的方法(函数,见下文)
        self.list_all = list_all
        self.find = find
        self.create = create
        self.update = update
        self.remove = remove

    # 该版块的路由;self.list:绑定到此对象的方法
    def urls(self):
        s = self.section
        return [
            path(f"{s}", require_GET(self.list), name=f"{s}_list"),
            path(f"{s}/add", require_http_methods(["GET", "POST"])(self.add), name=f"{s}_add"),
            path(f"{s}/<int:id>/edit", require_http_methods(["GET", "POST"])(self.edit),
                 name=f"{s}_edit"),
            path(f"{s}/<int:id>/delete", require_POST(self.delete), name=f"{s}_delete"),
        ]

    # -------------------------------------------------------------------
    # GET /doctors(或 /clients)
    # -------------------------------------------------------------------
    def list(self, request):
        return render(request, "persons/list.html", {
            "page_title": self.texts.title, "texts": self.texts, "section": self.section,
            "add_url": reverse(f"{self.section}_add"), "persons": self.list_all()})

    # -------------------------------------------------------------------
    # GET /doctors/add:空表单;POST:创建
    # -------------------------------------------------------------------
    def add(self, request):
        if request.method == "GET":
            return self.page(request, PersonForm(initial={"title": "Mr"}), None)
        form = PersonForm(request.POST)
        if not form.is_valid():
            return self.page(request, form, None)
        try:
            person = self.create(form.person_data())
        except BusinessError as e:
            return self.business_error(request, e, form, None)
        messages.success(request, str(self.texts.added) % parameters(person))
        return redirect(f"{self.section}_list")

    # -------------------------------------------------------------------
    # GET /doctors/{id}/edit:预填的表单;POST:更新。
    # <int:id>:由数字组成的参数(见示例 02):
    # /doctors/abc/edit 不匹配任何路由(404 页面)
    # -------------------------------------------------------------------
    def edit(self, request, id):
        person = self.find(id)
        if person is None:
            raise Http404("unknown person")
        if request.method == "GET":
            # 表单,用该人员的值预填(
            # 密码本身从不显示)
            form = PersonForm(creation=False, initial={
                "title": person.title, "first_name": person.first_name, "last_name": person.last_name,
                "login": person.account.login, "version": person.version})
            return self.page(request, form, person)
        form = PersonForm(request.POST, creation=False)
        if not form.is_valid():
            return self.page(request, form, person)
        try:
            person = self.update(id, form.person_data())
        except BusinessError as e:
            return self.business_error(request, e, form, person)
        messages.success(request, str(self.texts.updated) % parameters(person))
        return redirect(f"{self.section}_list")

    # -------------------------------------------------------------------
    # POST /doctors/{id}/delete(“您确定吗?”确认会在
    # 表单发送之前请求,见 static/js/app.js)
    # -------------------------------------------------------------------
    def delete(self, request, id):
        person = self.find(id)
        try:
            self.remove(id)
            messages.success(request, str(self.texts.deleted) % parameters(person))
        except BusinessError as e:
            messages.error(request, e.message)
        return redirect(f"{self.section}_list")

    # ———————————————————————————————— 内部函数
    # person 为 None:创建表单;否则:更新表单。
    # 被拒绝的表单(输入无效或违反业务规则):422 代码
    def page(self, request, form, person, error=None, invalid_fields=()):
        refused = error is not None or (form.is_bound and bool(form.errors))
        title = self.texts.add if person is None else self.texts.edit
        return render(request, "persons/form.html", {
            "page_title": title,
            "form": form.flag(invalid_fields),
            "error": error,
            "list_url": reverse(f"{self.section}_list"),
        }, status=422 if refused else 200)

    # 业务规则拒绝了写入:重新显示表单,带有
    # 用户的输入(不含密码)、业务层的消息
    # (位于页面底部),以及相关字段(如果有)用红框
    # 标出,让用户立即看到要更正什么
    def business_error(self, request, e: BusinessError, form, person):
        if e.code in (errors.DOCTOR_NOT_FOUND, errors.CLIENT_NOT_FOUND):
            # 在此期间被另一个 ADMIN 删除:返回列表
            messages.error(request, e.message)
            return redirect(f"{self.section}_list")
        return self.page(request, form, person, e.message, BUSINESS_ERROR_FIELDS.get(e.code, []))


# “已添加 / 已更新 / 已删除”消息的 %(name)s 和 %(login)s 参数
def parameters(person: Person | None) -> dict:
    if person is None:
        return {"name": "", "login": ""}
    return {"name": f"{person.first_name} {person.last_name}", "login": person.account.login}


# -------------------------------------------------------------------------
# 这两个对象。lambda:一个小型匿名函数,在请求时调用 ApplicationModel 的
# 正确方法。文本被“惰性”翻译
# (gettext_lazy):在显示时,按
# 请求的语言翻译,而不是在模块加载时
# -------------------------------------------------------------------------

doctors = PersonManagement(
    "doctors",
    Texts(_("Doctors"), _("Add a doctor"), _("Edit a doctor"), _("No doctors."),
          _("Delete this doctor, their time slots and their user account?"),
          _("Doctor %(name)s has been added (login: %(login)s)."),
          _("Doctor %(name)s has been updated."), _("Doctor %(name)s has been deleted.")),
    list_all=lambda: application().get_all_doctors(),
    find=lambda id: application().get_doctor_by_id(id),
    create=lambda data: application().add_doctor(data),
    update=lambda id, data: application().edit_doctor(id, data),
    remove=lambda id: application().delete_doctor(id))

clients = PersonManagement(
    "clients",
    Texts(_("Patients"), _("Add a patient"), _("Edit a patient"), _("No patients."),
          _("Delete this patient, their user account and all their appointments?"),
          _("Patient %(name)s has been added (login: %(login)s)."),
          _("Patient %(name)s has been updated."), _("Patient %(name)s has been deleted.")),
    list_all=lambda: application().get_all_clients(),
    find=lambda id: application().get_client_by_id(id),
    create=lambda data: application().add_client(data),
    update=lambda id, data: application().edit_client(id, data),
    remove=lambda id: application().delete_client(id))

医生和患者的管理是相同的:同样的列表、同样的表单、同样的规则。这些视图像类的方法一样只写一次,放在 [PersonManagement] 中;该类的两个对象 [doctors] 和 [clients],只在使它们互相区别的方面有所不同:栏目名称、文本,以及要调用的 [ApplicationModel] 方法。视图不必是函数:它可以是任何接收请求并返回响应的可调用对象。[self.list]是与对象关联的方法,就是这样一种视图:[Django] 用请求调用它,而该方法还会接收其对象([self]),即它所属的栏目。要为医生管理和患者管理两个栏目添加视图,只需在这里编写即可。

  • 第 46–50 行:每种业务逻辑录入错误所影响的字段:重复的用户名影响“登录名”字段;姓名冲突影响“名”和“姓”字段。这些字段将以红色高亮;
  • 第 55–64 行:每个栏目特有的文本,放在一个数据类中;
  • 第 68–78 行:构造函数。最后五个参数是函数([Callable]):读取列表、查找、创建、修改或删除人员;
  • 第 81–89 行:该栏目的路由。装饰器在这里作为函数调用([require_GET(self.list)]:被装饰的视图 [self.list]):这正是将语法 [@require_GET] 放在函数上方时所做的事情(示例 02)。路径和路由名称的前缀就是栏目名:视图 [list] 变成路由 [doctors_list]([/doctors])和 [clients_list]([/clients]);
  • 第 94–97 行:列表。模板由两个栏目共用:它从栏目接收文本,以及添加按钮的 URL;
  • 第 102–113 行:添加功能。一个视图同时处理 GET(空表单,称谓 [Mr] 通过 [initial] 选中,示例 18)和 POST(创建),如示例 19 所示。无效的输入会重新显示表单。有效的输入进入业务层,业务层可能拒绝该写操作(由于同名者或登录名已被使用);否则,闪现一条成功消息,用户回到列表(PRG 模式)。消息文本是惰性翻译:[str(...)] 在 [%] 运算符插入其参数之前先翻译它;
  • 第 120–139 行:修改,针对存在的人员;否则,[Http404] 返回 404 页面。[<int:id>] 对于 [id] 参数只接受数字(例如 02),并将其转换为整数。GET 表单预先填入了该人员的值及其版本号;POST 表单接收输入;
  • 第 145–152 行:删除。表单在浏览器中请求了确认(示例 21)。在删除之前先取回该人员,以便显示成功消息(“Doctor Paul TATOU has been deleted.”);
  • 第 157–165 行:表单,用于创建([person] 等于 [None])或修改。被拒绝的表单(输入无效或违反业务规则)以状态码 422 返回(示例 19)。这里,[flag] 以红色高亮有错误的字段;
  • 第 171–176 行:业务层拒绝了写操作。如果某人在此期间被删除了(被另一位管理员):返回列表。否则,表单会被直接重新显示(不重定向),就像输入错误时一样:它已经包含了用户的输入。此外还要加上业务层的消息(显示在页面底部的错误区域)和要以红色高亮的字段;
  • 第 180–183 行:成功消息的参数 [%(name)s] 和 [%(login)s] ;
  • 第 193–215 行:这两个对象。每个 [lambda] 在发出请求时调用 [ApplicationModel] 的相应方法:外观不是在模块加载时创建的,而是在首次使用时创建。

11.17.7. web/views/registration.py

# =========================================================================
# web/views/registration.py:“创建患者账户”:尚未
# 拥有账户的患者自己创建账户。公开路由(根据定义,此时
# 还没有账户):
#
#   POST /register/access     身份验证页面的“创建患者账户”
#                             按钮:检查该页面的验证码,
#                             然后打开表单
#   GET  /register            表单
#   POST /register            创建,然后返回登录页面
#
# 该路径由一个验证码保护以防机器人,即
# 身份验证页面的验证码:
#   1. “创建患者账户”按钮把登录表单发送到
#      /register/access;如果验证码输入正确,服务器会签发一个
#      通行证(见 security/registration_pass.py);
#   2. 没有有效通行证时,/register 会把用户送回
#      身份验证页面(装饰器 @registration_pass_required);
#   3. 通行证在创建时被消耗:一个已解出的验证码只允许创建
#      一个账户;
#   4. 此外,每小时每个 IP 地址创建的账户数量也有限制
#      (见 security/limiter.py)。
#
# 所创建的账户与 ADMIN 在“患者”页面中创建的完全相同
# (同一个业务层方法:add_client),区别在于患者
# 自己选择登录名和密码(必填,并需确认)。
# =========================================================================

from urllib.parse import urlencode

from django.contrib import messages
from django.shortcuts import redirect, render
from django.urls import reverse
from django.utils.translation import gettext as _, ngettext
from django.views.decorators.http import require_http_methods, require_POST

from business.errors import BusinessError
from security import captchas, limiter, registration_pass
from security.registration_pass import registration_pass_required

from .. import utils
from ..application import application
from ..forms import RegistrationForm
from .persons import BUSINESS_ERROR_FIELDS


# “创建的账户过多”消息,单数或复数形式
def too_many_accounts(minutes: int) -> str:
    return ngettext(
        "Too many accounts have been created from your connection. Try again in %(minutes)d minute.",
        "Too many accounts have been created from your connection. Try again in %(minutes)d minutes.",
        minutes) % {"minutes": minutes}


# -------------------------------------------------------------------------
# POST /register/access   字段:captcha_id、captcha(来自
# 身份验证页面;同时发送的登录名和密码会被忽略)
# -------------------------------------------------------------------------
@require_POST
def access(request):
    ip = utils.ip(request)
    # 该地址最近创建的账户过多:没必要再继续
    minutes = limiter.registration_block_minutes(ip)
    if minutes > 0:
        messages.error(request, too_many_accounts(minutes))
        return redirect("login")
    # 验证码缺失或错误:返回身份验证页面,并显示
    # 新图像(失败会计为一次登录失败)
    if not captchas.verify(request.POST.get("captcha_id", ""), request.POST.get("captcha", "")):
        limiter.login_failure(ip, "")
        messages.error(request, _("To create an account, first type the characters shown in the image "
                                  "correctly, then click \"Create a patient account\"."))
        return redirect("login")
    # 验证码正确:签发通行证并打开表单
    return registration_pass.issue(redirect("registration"))


# -------------------------------------------------------------------------
# GET /register:表单;POST /register:创建。
# 通行证在调用视图之前已被检查(@registration_pass_required)。
# 表单会验证所有输入(字段和确认密码):
# 用户可以一次性更正所有错误
# -------------------------------------------------------------------------
@require_http_methods(["GET", "POST"])
@registration_pass_required
def registration(request):
    if request.method == "GET":
        return page(request, RegistrationForm(initial={"title": "Mr"}))
    form = RegistrationForm(request.POST)
    if not form.is_valid():
        return page(request, form)
    ip = utils.ip(request)
    # 1. 该地址最近创建的账户过多?
    minutes = limiter.registration_block_minutes(ip)
    if minutes > 0:
        return page(request, form, too_many_accounts(minutes))
    # 2. 创建(客户 + USER 账户,在一个事务中)
    data = form.person_data()
    try:
        application().add_client(data)
    except BusinessError as e:
        # 登录名或名 + 姓已被占用:通行证仍然有效
        return page(request, form, e.message, BUSINESS_ERROR_FIELDS.get(e.code, []))
    # 3. 通行证已被使用:它不会允许创建第 2 个账户
    registration_pass.consume(request.COOKIES.get(registration_pass.COOKIE))
    limiter.registration_success(ip)
    # 4. 返回登录页面,登录名已预填
    messages.success(request, _("Your account has been created. You can now log in with "
                                "the login %(login)s.") % {"login": data.login})
    url = f"{reverse('login')}?{urlencode({'login': data.login})}"
    return registration_pass.clear_cookie(redirect(url))


# 表单;被拒绝的表单:422 代码
def page(request, form, error=None, invalid_fields=()):
    refused = error is not None or (form.is_bound and bool(form.errors))
    return render(request, "registration.html", {
        "page_title": _("Create a patient account"),
        "form": form.flag(invalid_fields), "error": error,
    }, status=422 if refused else 200)

患者自己创建患者账户。该流程由验证码保护,与登录页面上使用的是同一个。

  • 第 59–75 行:登录页面上的“创建患者账户”按钮将登录表单提交到此地址(之后它会变成模板 [login.html])。如果最近从该地址(IP)创建了过多账户,就没有必要继续了。如果验证码缺失或不正确:带着新的图片和一条消息返回登录页面;该失败计为一次登录失败的尝试(用户名为空)。如果验证码正确:令牌被存入 Cookie,用户被重定向到表单;
  • 第 84–91 行:表单。[@registration_pass_required] 装饰器(第 85 行)在调用视图之前检查令牌。装饰器的顺序很重要:最靠近函数的先应用;因此放在上方的 [require_http_methods] 会在任何其他检查之前拒绝被禁止的方法。表单验证全部输入,包括确认密码:用户一次就能看到他的所有错误;
  • 第 92–111 行:创建账户。患者及其账户使用与管理员相同的业务逻辑方法([add_client])创建;只有用户名和密码由患者自己选择。如果用户名或同名者已被占用:返回表单,不消耗令牌。创建账户会消耗令牌(一个通过的验证码对应一个账户),计入每小时的限额,并重定向到登录页面,预先填入用户名(参数 [?login=...],由 [urlencode] 生成),同时显示一条成功消息。通行证 Cookie 会被清除。

11.17.8. web/views/area.py

# =========================================================================
# web/views/area.py:患者(USER 角色)的个人页面,即其
# 登录之后立即看到的页面:
#
#   GET  /my-area                  主页:[Manage my account]、[View a
#                                  schedule],以及其未来的预约
#   POST /my-area/cancel           取消其预约
#   GET  /my-account               其账户的更新表单
#   POST /my-account               更新
#   POST /my-account/delete        删除账户(及其预约)
#
# 本模块的黄金法则:相关患者始终是令牌中的那一位
# (utils.connected_patient),绝不是浏览器发送的标识符。因此
# 患者既不能查看、也不能修改、更不能取消属于另一位患者的内容,
# 即使自己构造请求也不行。
#
# 账户的任何更新或删除都需要当前密码:
# 发现一个未关闭会话的人既无法更改
# 密码,也无法删除账户。当前密码的错误
# 会计为登录失败(同一限制)。
#
# 安全:所有这些 URL 都限定为 USER 角色(规则 ^/my- 见
# security/access.py)。
# =========================================================================

from django.contrib import messages
from django.shortcuts import redirect, render
from django.utils.translation import gettext as _, ngettext
from django.views.decorators.http import require_GET, require_http_methods, require_POST

from business.errors import BusinessError
from models.models import Client
from security import auth, limiter

from .. import utils
from ..application import application
from ..forms import MyAccountForm
from ..view_models import AppointmentView
from .schedule import schedule_url
from .persons import BUSINESS_ERROR_FIELDS


# -------------------------------------------------------------------------
# GET /my-area
# -------------------------------------------------------------------------
@require_GET
def area(request):
    patient = utils.connected_patient(request)
    appointments = [AppointmentView(
        a.id,
        utils.format_day(a.day),
        a.slot.time_range(),
        a.slot.doctor.label(),
        # 指向该医生当天日程的链接:患者可以在那里看到自己的姓名
        schedule_url(a.slot.doctor_id, a.day))
        for a in application().get_client_upcoming_appointments(patient.id)]
    return render(request, "area.html", {"page_title": _("My area"),
                                         "patient": patient.label(), "appointments": appointments})


# -------------------------------------------------------------------------
# POST /my-area/cancel   字段:appointmentId
# -------------------------------------------------------------------------
@require_POST
def cancel_appointment(request):
    patient = utils.connected_patient(request)
    appointment_id = utils.positive_integer(request.POST.get("appointmentId"))
    appointment = application().get_appointment_by_id(appointment_id) if appointment_id is not None else None
    # 不存在的预约和另一位患者的预约,得到相同的
    # 应答:不会泄露任何关于他人预约的信息
    if appointment is None or appointment.client_id != patient.id:
        messages.error(request, _("This appointment does not exist (any more)."))
    else:
        application().delete_appointment(appointment)
        messages.success(request, _("Appointment cancelled."))
    return redirect("area")


# -------------------------------------------------------------------------
# GET /my-account:表单,用患者的值预填;
# POST /my-account:更新
# -------------------------------------------------------------------------
@require_http_methods(["GET", "POST"])
def account(request):
    patient = utils.connected_patient(request)
    if request.method == "GET":
        return page(request, MyAccountForm(initial={
            "title": patient.title, "first_name": patient.first_name, "last_name": patient.last_name,
            "login": patient.account.login, "version": patient.version}))
    form = MyAccountForm(request.POST)
    if not form.is_valid():
        return page(request, form)
    # 当前密码;错误时:消息显示在字段下方(通过 add_error 添加到
    # 字段的错误),以及页面底部
    error = check_current_password(request, patient, form.cleaned_data["current_password"])
    if error is not None:
        form.add_error("current_password", error)
        return page(request, form, error)
    try:
        client = application().edit_client(patient.id, form.person_data())
    except BusinessError as e:
        return page(request, form, e.message, BUSINESS_ERROR_FIELDS.get(e.code, []))
    # 登录名和显示名称在令牌中:会签发新令牌,否则
    # 导航栏会保留旧名称
    messages.success(request, _("Your account has been updated."))
    return auth.set_token(redirect("area"), client.account)


# -------------------------------------------------------------------------
# POST /my-account/delete   字段:current_password
# 账户、客户及其所有预约一起消失,然后
# 患者被退出登录。
# -------------------------------------------------------------------------
@require_POST
def delete_account(request):
    patient = utils.connected_patient(request)
    error = check_current_password(request, patient, request.POST.get("current_password", ""))
    if error is not None:
        messages.error(request, error)
        return redirect("account")
    application().delete_client(patient.id)
    messages.success(request, _("Your account has been deleted."))
    return auth.clear_token(redirect("login"))


# ———————————————————————————————— 内部函数
# 账户页面;被拒绝的表单:422 代码
def page(request, form, error=None, invalid_fields=()):
    refused = error is not None or (form.is_bound and bool(form.errors))
    return render(request, "account.html", {
        "page_title": _("Manage my account"),
        "form": form.flag(invalid_fields), "error": error,
    }, status=422 if refused else 200)


# 如果当前密码正确则为 None;否则为错误消息
def check_current_password(request, patient: Client, password: str) -> str | None:
    ip = utils.ip(request)
    login = patient.account.login
    minutes = limiter.login_block_minutes(ip, login)
    if minutes > 0:
        return ngettext("Too many failed attempts. Try again in %(minutes)d minute.",
                        "Too many failed attempts. Try again in %(minutes)d minutes.",
                        minutes) % {"minutes": minutes}
    if not password or auth.validate(login, password) is None:
        limiter.login_failure(ip, login)
        return _("Incorrect current password.")
    return None

患者的个人页面。这个模块的黄金法则:所涉及的患者始终是与令牌关联的那一位([utils.connected_patient]),绝不是浏览器发送的标识符。因此,即使患者自己构造请求,也无法查看、修改或取消属于另一位患者的信息。

  • 第 46–58 行:我的空间:患者的姓名及其即将到来的预约,已格式化([AppointmentView]),每个预约都带有指向医生当天日程的链接。函数 [schedule_url] 属于日程表模块(第 39 行,[from .schedule import schedule_url]);
  • 第 64–76 行:取消他自己的预约。不存在的预约和另一位患者的预约得到相同的响应:不会泄露任何关于其他患者预约的信息(甚至包括其是否存在);
  • 第 83–92 行:“管理我的账户”表单,预先填入患者的信息,以及它的提交;
  • 第 95–106 行:修改。任何修改都需要当前密码:发现一个未退出会话的人无法修改密码或做任何其他事情。如果当前密码不正确,表单会重新显示,消息位于字段下方和页面底部。[add_error(field, message)] 向字段添加一个错误,就像验证检测到的一样(示例 19)。修改之后,会生成新的令牌:登录名和显示的姓名包含在令牌中,否则导航栏会一直保留旧的姓名,直到下次登录;
  • 第 114–123 行:删除账户、患者及其所有预约,使用与管理员相同的业务逻辑方法。页面上的这第二个表单是手写的(只有一个字段:当前密码)。随后患者被退出登录(令牌 Cookie 被清除);
  • 第 137–148 行:验证当前密码。它同样受尝试次数限制器约束,与登录一样:没有这一点,持有已打开会话的人就可以通过“管理我的账户”表单尝试数千个密码,从而找到正确的密码。

11.18. 模板

[templates] 文件夹中的模板(配置 [TEMPLATES] 来自 [config/settings.py]):一个父模板、若干片段、具名的表单片段,以及页面。

11.18.1. 父模板和片段

11.18.1.1. templates/layout.html

<!doctype html>
{% comment %}
  =========================================================================
  templates/layout.html
  —————————————————————————————————————————
  所有页面的父模板(见示例 15):每个页面
  (schedule.html、login.html 等)都扩展它({% extends %}),并填充它的
  [content] 块。

  Django 会转义用 {{ ... }} 显示的一切内容(字符 < > & " '
  变成 &lt; &gt; 等):例如防止通过输入的姓名进行 HTML 注入。
  若要按原样插入 HTML,必须显式声明
  (safe 过滤器,见 fragments/captcha.html)。

  消息:成功消息显示在页面顶部,错误消息显示在页面底部,背景为浅粉色
  (success_zone 和 error_zone 标签,见 web/templatetags/rdv.py)。

  模板共享页面的变量:[page_title](页面标题,
  由视图传入,已翻译)。LANGUAGE_CODE:请求的语言
  (见 web/middleware.py)。
  =========================================================================
{% endcomment %}
{% load static i18n rdv %}
<html lang="{{ LANGUAGE_CODE }}">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>{{ page_title }} - RdvMedecins</title>
  {# static:static 文件夹中某个文件的 URL #}
  <link rel="stylesheet" href="{% static 'lib/bootstrap/css/bootstrap.min.css' %}">
  <link rel="stylesheet" href="{% static 'css/styles.css' %}">
</head>
<body>
  <div class="container py-4">
    {% include "fragments/navbar.html" %}
    {% success_zone %}
    <main>
      {% block content %}{% endblock %}
    </main>
    {% error_zone %}
  </div>
  {# “确定吗?”对话框,在不需要时保持隐藏 #}
  {% include "fragments/confirmation.html" %}
  <script src="{% static 'js/app.js' %}"></script>
</body>
</html>

所有页面的父模板(示例 15):每个页面都扩展它([{% extends "layout.html" %}]),并填充它的 [content] 块(第 38 行)。

  • 第 23 行:所使用的标签库:[static] (静态文件)、[i18n] (翻译,示例 22),以及 [rdv],即我们自己的(Web 层,前面已述)。父模板不会把它的库传递给扩展它的模板:每个页面各自加载所需的库;
  • 第 24 行:页面的语言,[fr] 或 [en]:请求当前激活的语言,由 [SetLanguage] 中间件设置;
  • 第 28 行:页面标题,已由视图翻译好,视图通过变量 [page_title] 传入;
  • 第 30–31 行:[{% static %}] 标签根据 [static] 文件夹中的文件渲染出 URL(示例 15);
  • 第 35–40 行:导航栏、页面顶部的成功消息、页面内容,以及页面底部的错误区域。导航栏片段由 [{% include %}] (示例 15)插入:它可以访问页面的变量。两个消息区域是来自 [web/templatetags/rdv.py] 的包含标签;
  • 第 43–44 行:“Are you sure?”窗口,在需要之前一直隐藏,以及显示它的脚本。

头部注释(第 2–22 行)是一个 [{% comment %}] 标签:可以跨越多行的模板注释([{# ... #}] 适用于单行,示例 14)。它写在 [<!doctype html>] 之后:发送页面的第一行必须是文档类型声明。DTL 会对用 [{{ ... }}] (示例 14)显示的所有内容进行转义:用户输入的包含 HTML([<script>])的姓名会按原样显示,而不会被解释。这样可以防止 HTML(XSS)被轻而易举地注入到所有页面中。

11.18.1.2. templates/fragments/navbar.html

{% comment %}
  =========================================================================
  templates/fragments/navbar.html - 导航栏。

  标题、FR/EN、角色、姓名、退出登录,以及菜单,其条目取决于
  角色:它们由上下文处理器 web/contexts.py 计算
  (变量 menu),每个条目包含其 URL、标签,
  以及它是否为当前页面的条目("active" 类)。

  user:已登录的用户,或 None(见 web/contexts.py)。
  =========================================================================
{% endcomment %}
{% load i18n %}
<nav class="navbar navbar-expand-sm navbar-dark bg-primary rounded mb-4 px-3">
  <span class="navbar-brand mb-0">RdvMedecins</span>

  <ul class="navbar-nav me-auto">
    {% for entry in menu %}
    <li class="nav-item">
      <a class="nav-link{% if entry.active %} active{% endif %}" href="{{ entry.url }}">{{ entry.label }}</a>
    </li>
    {% endfor %}
  </ul>

  <div class="d-flex align-items-center gap-2">
    {# FR / EN:简单链接(GET /language/fr),当前语言高亮显示 #}
    {% get_available_languages as languages %}
    <div class="btn-group btn-group-sm" role="group" aria-label="FR / EN">
      {% for code, name in languages %}
      <a class="btn {% if code == LANGUAGE_CODE %}btn-light{% else %}btn-outline-light{% endif %}"
         href="{% url 'language' code %}">{{ code|upper }}</a>
      {% endfor %}
    </div>

    {% if user %}
    <span class="badge text-bg-light text-primary">{{ user.role }}</span>
    <span class="text-white">{{ user.name }}</span>
    {# logout 是 POST:一个只有按钮(和防 CSRF 令牌)的表单 #}
    <form method="post" action="{% url 'logout' %}" class="m-0">
      {% csrf_token %}
      <button type="submit" class="btn btn-sm btn-outline-light">{% translate "Log out" %}</button>
    </form>
    {% endif %}
  </div>
</nav>

导航栏。它只是显示 [web/contexts.py] 上下文处理器准备好的内容:已登录用户([user]),以及取决于角色的菜单项([menu])。

  • 第 17–23 行:菜单,每一项都有自己的 URL 和标签;[Bootstrap] 的 [active] 类会高亮当前显示页面所对应的菜单项;
  • 第 27–32 行:FR / EN 按钮,简单的链接([/language/fr]),当前激活的语言会高亮。[{% get_available_languages as languages %}] (库 [i18n])把设置 [LANGUAGES]——一个(代码,名称)对的列表——存入变量 [languages],循环会对其解包([{% for code, name in languages %}]);过滤器 [upper] 将代码转为大写。[{% url 'language' code %}] 为带参数的路由生成 URL(示例 15);
  • 第 35–43 行:对于已登录用户,显示其角色、姓名和退出登录按钮。退出登录是一个 POST 请求:一个只剩按钮的表单,带有防 CSRF 令牌([{% csrf_token %}],示例 21)。

11.18.1.3. templates/fragments/success.html 和 errors.html

1
2
3
4
{# templates/fragments/success.html - 成功消息(success_zone 标签,见 web/templatetags/rdv.py) #}
{% for text in texts %}
<div class="alert alert-success" role="status">{{ text }}</div>
{% endfor %}
{% comment %}
  templates/fragments/errors.html - 错误区,位于每个页面的底部,背景为
  浅粉色(类 .error-zone,见 static/css/styles.css)。消息
  由 error_zone 标签汇集(见 web/templatetags/rdv.py)。
  role="alert":页面一显示,屏幕阅读器就会播报该消息,
  即使它位于底部。
{% endcomment %}
{% if texts %}
<div class="error-zone" role="alert">
  {% for text in texts %}
  <div>{{ text }}</div>
  {% endfor %}
</div>
{% endif %}

两个包含标签的模板 [success_zone] 和 [error_zone] (Web 层,前面已述):它们接收由标签准备好的列表 [texts] 并显示它。[role="status"]:屏幕阅读器会播报成功消息。[role="alert"]:页面一显示,它就会播报错误区域,即使该区域位于底部。当页面较长时,错误区域仍固定在窗口底部(见下面的样式表)。

11.18.1.4. templates/fragments/confirmation.html

{% comment %}
  =========================================================================
  templates/fragments/confirmation.html - “确定吗?”模态对话框
  (见示例 21)。

  它取代浏览器的 window.confirm() 对话框,后者既不能
  设置样式,也不能翻译(其按钮保持浏览器的语言,而不是
  页面的语言)。

  整个页面只有一个对话框,起初隐藏(d-none)。它的标签
  在此由服务器翻译,与页面其余部分一样;小脚本
  static/js/app.js 只负责显示它,把表单特有的消息
  (data-confirmation 属性)放进去,并在
  用户确认后提交表单。
  =========================================================================
{% endcomment %}
{% load i18n %}
<div id="confirmation-modal" class="d-none">
  <div class="modal-backdrop fade show"></div>
  <div class="modal fade show d-block" tabindex="-1" role="alertdialog" aria-modal="true"
       aria-labelledby="confirmation-modal-title" aria-describedby="confirmation-modal-message">
    <div class="modal-dialog modal-dialog-centered">
      <div class="modal-content">
        <div class="modal-header">
          <h5 class="modal-title" id="confirmation-modal-title">{% translate "Confirmation" %}</h5>
          <button type="button" class="btn-close" data-action="no" aria-label="{% translate 'Close' %}"></button>
        </div>
        <div class="modal-body">
          <p class="mb-0" id="confirmation-modal-message"></p>
        </div>
        <div class="modal-footer">
          {# 用“不,返回”而不是“取消”:因为问题有时是“取消此预约吗?” #}
          <button type="button" class="btn btn-secondary" data-action="no">{% translate "No, go back" %}</button>
          <button type="button" class="btn btn-danger" data-action="yes">{% translate "Yes, confirm" %}</button>
        </div>
      </div>
    </div>
  </div>
</div>

示例 21 中的“Are you sure?”模态窗口,它取代了浏览器的 [window.confirm()] 对话框:该对话框无法正确设置格式,其按钮也保持浏览器的语言,而不是页面的语言。整个页面只有一个窗口,初始时隐藏(来自 [d-none] 的类 [Bootstrap]);它的标签由服务器翻译,与页面的其余部分一样。[static/js/app.js] 脚本负责显示它,把待确认表单中的消息(其 [data-confirmation] 属性)放入其中,并在用户确认时提交该表单。“取消”按钮的标签是“No, go back”而不是“Cancel”:有时问题是“Cancel this appointment?”,在这种语境下,“Cancel”按钮会有歧义。属性 [role="alertdialog"]、[aria-modal]、[aria-labelledby]和 [aria-describedby] 向屏幕阅读器描述该窗口:一个等待响应的对话框、它的标题和它的消息。

11.18.1.5. templates/fragments/booking.html

{% comment %}
  =========================================================================
  templates/fragments/booking.html - 日程的预约对话框。

  使用模态对话框真正的 Bootstrap 类(.modal、.modal-backdrop 等),
  并以“硬编码”方式(show d-block)使其可见,而不是通过
  Bootstrap 的 JavaScript。由服务器决定是否显示它(URL 的 &book=... 参数),
  关闭它就相当于跟随一个指向同一页面、但不带
  此参数的链接。

  该片段直接读取包含它的页面的变量
  (booking、doctor_id、day、back_url)。
  =========================================================================
{% endcomment %}
{% load i18n %}
<div class="modal-backdrop fade show"></div>
<div class="modal fade show d-block" tabindex="-1" role="dialog" aria-modal="true" aria-labelledby="booking-title">
  <div class="modal-dialog modal-dialog-centered">
    <form method="post" action="{% url 'schedule_book' %}" class="modal-content">
      <div class="modal-header">
        <h5 class="modal-title" id="booking-title">{% translate "Book this slot" %}</h5>
        <a class="btn-close" href="{{ back_url }}" aria-label="{% translate 'Close' %}"></a>
      </div>

      <div class="modal-body">
        <p>{% blocktranslate with time_range=booking.time_range %}Slot {{ time_range }}{% endblocktranslate %}</p>

        {# 除所选患者之外,服务器还必须知道的信息 #}
        {% csrf_token %}
        <input type="hidden" name="doctorId" value="{{ doctor_id }}">
        <input type="hidden" name="day" value="{{ day }}">
        <input type="hidden" name="slotId" value="{{ booking.slot_id }}">

        {# 患者为自己预约:无需从列表中选择(而且服务器无论如何都会忽略任何 clientId) #}
        {% if booking.patient %}
        <p class="mb-0">
          <span>{% translate "Patient" %}</span>:
          <strong>{{ booking.patient }}</strong>
        </p>
        {% else %}
        <label class="form-label" for="clientId">{% translate "Patient" %}</label>
        <select id="clientId" name="clientId" class="form-select" required autofocus>
          <option value="">{% translate "-- choose a patient --" %}</option>
          {% for client in booking.clients %}
          <option value="{{ client.id }}">{{ client.label }}</option>
          {% endfor %}
        </select>
        {% endif %}
      </div>

      <div class="modal-footer">
        <a class="btn btn-secondary" href="{{ back_url }}">{% translate "Cancel" %}</a>
        <button type="submit" class="btn btn-primary">{% translate "Confirm" %}</button>
      </div>
    </form>
  </div>
</div>

日程表的预约窗口。它使用 [Bootstrap] 模态窗口的真实类([modal]、[modal-backdrop]……),但以“硬编码”方式使其可见([show d-block]),而不是通过 [JavaScript] 来自 [Bootstrap]:当 URL 包含 [&book=...] 时,由服务器决定显示它。关闭它(使用 X 或“取消”按钮)相当于跟随一个指向同一页面但不带该参数的链接([back_url])。

  • 第 26 行:[{% blocktranslate with time_range=booking.time_range %}]:包含变量的翻译文本(示例 22)。在 [blocktranslate] 中只允许使用简单变量([{{ time_range }}],而不是 [{{ booking.time_range }}]):[with] 子句会创建一个;
  • 第 29–32 行:防 CSRF 令牌,以及服务器需要知道的内容:医生、日期和时段;
  • 第 35–48 行:患者为自己预约:显示其姓名,没有可供选择的列表(服务器无论如何都会忽略任何 [clientId] 字段)。管理员和医生从列表中选择患者;[required] 和 [autofocus]:浏览器要求必须选择,并把光标放在列表中。

11.18.1.6. templates/fragments/captcha.html

{% comment %}
  =========================================================================
  templates/fragments/captcha.html - 身份验证页面的验证码
  (见 security/captchas.py)。它同时保护登录和进入
  账户创建页面(按钮“创建患者账户”)。它读取页面的
  变量 [captcha]。

  captcha.svg|safe:SVG 图像原样插入页面,不经
  转义。这里是安全的,因为该 SVG 由服务器
  自己生成,不包含任何来自用户的内容;对用户输入则绝不能
  这样做。

  隐藏字段 captcha_id 告诉服务器要检查哪一个验证码;而正确
  答案绝不会发送给浏览器。“换一张图片”只是重新加载
  页面({% url 'login' %}:页面的 URL,不带其参数)。
  =========================================================================
{% endcomment %}
{% load i18n %}
<div class="mb-3">
  <label class="form-label" for="captcha">{% translate "Type the characters shown in the image" %}</label>
  <div class="d-flex align-items-center gap-3 mb-2">
    <div class="captcha-image" role="img" aria-label="{% translate 'Anti-robot verification image' %}">{{ captcha.svg|safe }}</div>
    <a class="small" href="{% url 'login' %}">{% translate "Another image" %}</a>
  </div>
  <input type="hidden" name="captcha_id" value="{{ captcha.id }}">
  <input id="captcha" name="captcha" type="text" maxlength="10" autocomplete="off" autocapitalize="off"
         spellcheck="false" required class="form-control">
  <div class="form-text">{% translate "Upper or lower case, it does not matter." %}</div>
</div>

验证码(示例 27)。[captcha.svg|safe] 原样插入 SVG 图像,不对其转义:否则浏览器会显示它的 XML 代码。这里这样做是安全的,因为该 SVG 由服务器生成,不包含任何用户提供的内容:对于用户输入,我们绝不会这样做。隐藏字段 [captcha_id] 告诉服务器要验证哪个验证码;答案本身绝不会发送给浏览器。“Another image”链接会重新加载登录页面,从而换一个验证码。输入字段的属性([autocomplete="off"]、[autocapitalize="off"]、[spellcheck="false"])可防止浏览器建议之前的输入,也防止手机键盘自动大写字母或纠正拼写。

11.18.2. 表单字段

11.18.2.1. templates/forms/field.html

{% comment %}
  templates/forms/field.html - 表单的一个完整字段:标签、
  输入区,然后是它的错误消息或帮助信息(见示例 18 和
  FORM_RENDERER 设置)。输入区用表单的 flag 方法
  框成红色(类 is-invalid)(见 web/forms.py)。
{% endcomment %}
<div class="mb-3">
  <label class="form-label" for="{{ field.id_for_label }}">{{ field.label }}</label>
  {{ field }}
  {% if field.errors %}<div class="invalid-feedback d-block" id="{{ field.auto_id }}_error">{% for error in field.errors %}{{ error }}{% if not forloop.last %}<br>{% endif %}{% endfor %}</div>{% endif %}
  {% if field.help_text and not field.errors %}<div class="form-text" id="{{ field.auto_id }}_helptext">{{ field.help_text }}</div>{% endif %}
</div>

完整字段的模板——即[BootstrapRenderer]渲染引擎(Web 层,见上文)的模板,如示例 18 所示:包含标签、输入字段([{{ field }}],其 CSS 类由表单提供),随后是错误消息,若没有错误则显示帮助文本。类 [invalid-feedback] (红色的消息)和 [form-text] (灰色的帮助文本)来自 [Bootstrap];[d-block] 使消息即使不紧跟在输入字段之后也能显示。一个字段可能有多个错误:它们之间用换行分隔([forloop.last],示例 14)。

标识符 [..._error] 和 [..._helptext] 并非随意选取:它们正是 [Django] 在输入字段的 [aria-describedby] 属性中引用的标识符,对于有错误的字段还会配合 [aria-invalid] 使用。这样,屏幕阅读器会在朗读字段的同时朗读错误消息或帮助文本:

1
2
3
4
5
<div class="mb-3">
  <label class="form-label" for="id_first_name">First name</label>
  <input type="text" name="first_name" maxlength="20" class="form-control is-invalid" required aria-invalid="true" aria-describedby="id_first_name_error" id="id_first_name">
  <div class="invalid-feedback d-block" id="id_first_name_error">The first name is required.</div>
</div>

红色边框([is-invalid])由表单的 [flag] 方法添加;[maxlength] 和 [required] 由 [Django] 根据字段的选项添加。[required] 属性并不会阻止提交空表单:应用程序中的表单带有 [novalidate] 属性(见下文);验证由服务器执行。

11.18.2.2. templates/macros.html

{% comment %}
  templates/macros.html - 表单的具名片段(见示例 15)。

  identity:身份字段(称谓、名、姓),三个表单共用:
  ADMIN 的医生/客户、“创建患者账户”和“管理我的
  账户”。它读取包含它的页面的 [form] 变量:
  {% include "macros.html#identity" %}。
{% endcomment %}
{% partialdef identity %}
  {{ form.title.as_field_group }}
  <div class="row g-3">
    <div class="col-sm-6">{{ form.first_name.as_field_group }}</div>
    <div class="col-sm-6">{{ form.last_name.as_field_group }}</div>
  </div>
{% endpartialdef %}

一个命名片段([{% partialdef %}],示例 15),供显示“人员”表单的三个页面使用:包括标识字段、称谓,然后是并排显示的名和姓(来自 [Bootstrap] 的网格:[row]、[col-sm-6])。每个字段由 [as_field_group] (示例 18)渲染,也就是由模板 [field.html] 渲染。页面使用 [{% include "macros.html#identity" %}] 插入该片段:片段从页面中读取变量 [form] 。

11.18.3. 页面

11.18.3.1. templates/login.html

{% extends "layout.html" %}
{% comment %}
  =========================================================================
  templates/login.html - 登录表单(见 web/views/auth.py)。
  一个手写的普通 HTML <form>:浏览器自己以 POST /login
  发送登录名、密码和验证码答案,无需 JavaScript。登录失败时,
  服务器返回此页面,其中保留已输入的登录名,附带新的
  验证码和错误信息,错误信息由父模板显示在页面底部。
  =========================================================================
{% endcomment %}
{% load i18n %}

{% block content %}
<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">{% translate "Sign in" %}</h5>

      <form method="post" action="{% url 'login' %}">
        {% csrf_token %}
        <div class="mb-3">
          <label class="form-label" for="login">{% translate "Login" %}</label>
          {# autofocus:布尔属性,条件为真时写出。光标定位到第一个要填写的字段 #}
          <input id="login" name="login" type="text" class="form-control" autocomplete="username"
                 value="{{ login }}" required{% if not login %} autofocus{% endif %}>
        </div>
        <div class="mb-3">
          <label class="form-label" for="password">{% translate "Password" %}</label>
          <input id="password" name="password" type="password" class="form-control"
                 autocomplete="current-password" required{% if login %} autofocus{% endif %}>
        </div>

        {% include "fragments/captcha.html" %}

        <button type="submit" class="btn btn-primary w-100">{% translate "Log in" %}</button>

        {% comment %}
          还没有账户:患者可以自己创建。它不是
          简单的链接:而是此表单的第二个提交按钮,指向
          另一个地址(formaction)。服务器在此先检查上面的验证码,
          再打开账户创建页面(见
          web/views/registration.py)。formnovalidate:浏览器不要求
          填写登录名和密码(创建账户时用不到)。在
          字段中按回车键总是触发表单的第一个按钮,即“登录”。
        {% endcomment %}
        <button type="submit" class="btn btn-outline-primary w-100 mt-3"
                formaction="{% url 'registration_access' %}" formnovalidate>{% translate "Create a patient account" %}</button>
        <div class="form-text text-center">{% translate "To create an account, first type the characters shown in the image." %}</div>
      </form>

      <div class="text-muted small mt-3">
        <span>{% translate "Demo accounts (password = login):" %}</span>
        <ul class="mb-0 mt-1">
          <li><code>admin</code> - <span>{% translate "ADMIN role: appointments + doctor and patient management" %}</span></li>
          <li><code>pelissier</code>, <code>tatou</code>, <code>dupont</code> - <span>{% translate "DOCTOR role: booking and cancelling appointments" %}</span></li>
          <li><code>martin</code>, <code>durand</code>, <code>bistrou</code>, <code>german</code> - <span>{% translate "USER role (patients): booking for themselves, managing their account" %}</span></li>
        </ul>
      </div>
    </div>
  </div>
</div>
{% endblock %}

登录表单是手工编写的 [<form>],通过 POST 发送到 [/login]。按照 DTL 的要求,[{% extends %}] 标签是模板中的第一个标签(第 1 行);注释紧随其后。

  • 第 24–30 行:登录失败后重新显示输入的登录名([login])。属性 [autofocus] 将光标置于第一个需要填写的字段:若用户名为空则是用户名,否则(登录失败后或创建账户后)是密码。布尔属性要么存在,要么不存在:[{% if not login %} autofocus{% endif %}];
  • 第 33 行:验证码(CAPTCHA);
  • 第 46–47 行:“创建患者账户”按钮不是链接;它是第二个按钮,将同一个表单提交到另一个地址(按钮属性 [formaction])。服务器在打开账户创建页面([registration.access])之前,会在此处验证验证码。[formnovalidate]:浏览器不要求填写用户名和密码(属性 [required]),因为创建账户时并不需要它们。在字段中按 Enter 键总是触发第一个表单提交按钮:登录;
  • 第 51–58 行:演示账户,用于测试。

11.18.3.2. templates/schedule.html

{% extends "layout.html" %}
{% comment %}
  =========================================================================
  templates/schedule.html - 主页面(见 web/views/schedule.py)。
  三个块:
    1. 选择医生和日期;
    2. 日程;
    3. 预约对话框(booking 片段)。
  可能出现的错误(日期无效、医生未知)由父模板显示在页面
  底部(error_zone 标签)。
  =========================================================================
{% endcomment %}
{% load i18n %}

{% block content %}
  {# 1. 选择医生和日期:一个 GET 表单,只是用 ?doctorId=...&day=... 重新加载此页面 #}
  <form method="get" action="{% url 'schedule' %}" class="card p-3 mb-3">
    <div class="row g-2 align-items-end">
      <div class="col-sm-5">
        <label class="form-label" for="doctorId">{% translate "Doctor" %}</label>
        <select id="doctorId" name="doctorId" class="form-select" required>
          <option value="">{% translate "-- choose a doctor --" %}</option>
          {% for doctor in doctors %}
          <option value="{{ doctor.id }}"{% if doctor.selected %} selected{% endif %}>{{ doctor.label }}</option>
          {% endfor %}
        </select>
      </div>
      <div class="col-sm-4">
        <label class="form-label" for="day">{% translate "Day" %}</label>
        <input id="day" name="day" type="date" class="form-control" value="{{ day }}" required>
      </div>
      <div class="col-sm-3">
        <button type="submit" class="btn btn-primary w-100">{% translate "View schedule" %}</button>
      </div>
    </div>
  </form>

  {# 已有即将到来预约的患者:因此没有“预约”按钮 #}
  {% if info %}
  <div class="alert alert-info">
    <span>{{ info }}</span>
    <a href="{% url 'area' %}" class="alert-link">{% translate "My area" %}</a>
  </div>
  {% endif %}

  {# 2. 日程 #}
  {% if schedule %}
  <div class="card p-3">
    <h5>{% translate "Schedule for" %} {{ schedule.day }} - {{ schedule.doctor }}</h5>

    {% if schedule.rows %}
    <table class="table table-hover align-middle">
      <thead>
        <tr>
          <th>{% translate "Slot" %}</th>
          <th>{% translate "Status" %}</th>
          <th></th>
        </tr>
      </thead>
      <tbody>
        {% for row in schedule.rows %}
        <tr{% if row.bookable %} class="free-slot"{% endif %}>
          <td>{{ row.time_range }}</td>
          <td>
            {% comment %}
              [patient] 仅在用户有权查看此
              姓名时才会设置(ADMIN、DOCTOR,或患者本人查看自己的预约),否则
              只显示“已预约”
            {% endcomment %}
            {% if row.free %}
            <span class="badge text-bg-success">{% translate "Free" %}</span>
            {% elif row.patient %}
            <span class="badge {% if row.me %}text-bg-primary{% else %}text-bg-secondary{% endif %}">{{ row.patient }}</span>
            {% else %}
            <span class="badge text-bg-secondary">{% translate "Booked" %}</span>
            {% endif %}
          </td>
          <td>
            {% comment %}
              所显示的按钮由视图(bookable、appointment_id)根据
              用户的角色决定。“预约”是一个简单的链接:它
              重新打开此页面,并带上该时段的预约对话框
            {% endcomment %}
            {% if row.bookable %}
            <a class="btn btn-sm btn-outline-success" href="{{ row.book_url }}">{% translate "Book" %}</a>
            {% endif %}
            {# “取消”会修改数据:因此是 POST #}
            {% if row.appointment_id %}
            <form method="post" action="{% url 'schedule_cancel' %}" class="m-0"
                  data-confirmation="{% translate 'Cancel this appointment?' %}">
              {% csrf_token %}
              <input type="hidden" name="appointmentId" value="{{ row.appointment_id }}">
              <input type="hidden" name="doctorId" value="{{ doctor_id }}">
              <input type="hidden" name="day" value="{{ day }}">
              <button type="submit" class="btn btn-sm btn-outline-danger">{% translate "Cancel" %}</button>
            </form>
            {% endif %}
          </td>
        </tr>
        {% endfor %}
      </tbody>
    </table>
    {% else %}
    <p class="text-muted mb-0">{% translate "This doctor has no time slots." %}</p>
    {% endif %}
  </div>
  {% else %}
  <p class="text-muted">{% translate 'Choose a doctor and a day, then click "View schedule".' %}</p>
  {% endif %}

  {# 3. 预约对话框,仅当 URL 包含 &book=... 时显示 #}
  {% if booking %}
  {% include "fragments/booking.html" %}
  {% endif %}
{% endblock %}

主页面。分为三个部分:选择医生和日期、日历以及预约窗口。

  • 第 17–36 行:选择医生和日期:一个 GET 表单(示例 17),它会重新加载页面,并在 URL 中带上 [?doctorId=...&day=...] 。日期是一个 [type="date"] 字段:浏览器显示日历,并以 [yyyy-mm-dd] 格式发送日期,无论它如何显示([30/09/2026] 在法语中);初始值([value])也使用这种格式书写;
  • 第 39–44 行:对于已有一个未到期预约的患者,说明为何没有“预约”按钮,并提供指向“我的空间”的链接;
  • 第 70–76 行:时段状态:空闲(绿色)、患者姓名(由已登录患者预约的显示为蓝色,否则为灰色)或“已预约”。模板本身不做任何判断:[row.patient] 仅在用户有权查看该姓名时才会显示;
  • 第 84–86 行:“预约”是一个简单的链接:它重新打开页面,并显示该时段的预约窗口([row.book_url])。它不修改任何内容:GET 就足够了;
  • 第 88–97 行:“取消”会修改数据:它是一个 POST 表单(示例 21),带有防 CSRF 令牌、要取消的预约,以及用于返回同一页面的信息(医生、日期)。[data-confirmation] 属性使页面的脚本请求确认;其文本由 [{% translate %}] 表示,放在单引号中,而该属性本身则放在双引号中;
  • 第 112–114 行:预约窗口,如果 URL 要求显示(并且该时段可预约)。

11.18.3.3. templates/persons/list.html

{% extends "layout.html" %}
{% comment %}
  =========================================================================
  templates/persons/list.html - 医生列表或客户列表(ADMIN)。
  两者共用一个模板:各自特有的文本通过
  [texts] 传入,[section]("doctors" 或 "clients")给出路由名称
  的开头部分(见 web/views/persons.py)。
  =========================================================================
{% endcomment %}
{% load i18n %}

{% block content %}
  <div class="d-flex justify-content-between align-items-center mb-3">
    <h4 class="mb-0">{{ texts.title }}</h4>
    <a class="btn btn-primary" href="{{ add_url }}">{{ texts.add }}</a>
  </div>

  <div class="card p-3">
    {% if persons %}
    <table class="table table-hover align-middle mb-0">
      <thead>
        <tr>
          <th>{% translate "Title" %}</th>
          <th>{% translate "First name" %}</th>
          <th>{% translate "Last name" %}</th>
          <th>{% translate "Login" %}</th>
          <th></th>
        </tr>
      </thead>
      <tbody>
        {# person.account.login:账户,由同一个查询加载(select_related) #}
        {% for person in persons %}
        <tr>
          <td>{{ person.title }}</td>
          <td>{{ person.first_name }}</td>
          <td>{{ person.last_name }}</td>
          <td><code>{{ person.account.login }}</code></td>
          <td class="text-end">
            <div class="d-inline-flex gap-2">
              {# section|add:"_edit":"doctors_edit",路由的名称 #}
              <a class="btn btn-sm btn-outline-primary"
                 href="{% url section|add:'_edit' person.id %}">{% translate "Edit" %}</a>
              {# data-confirmation:表单发送前会打开一个确认对话框(见 static/js/app.js) #}
              <form method="post" action="{% url section|add:'_delete' person.id %}" class="m-0"
                    data-confirmation="{{ texts.confirm_delete }}">
                {% csrf_token %}
                <button type="submit" class="btn btn-sm btn-outline-danger">{% translate "Delete" %}</button>
              </form>
            </div>
          </td>
        </tr>
        {% endfor %}
      </tbody>
    </table>
    {% else %}
    <p class="text-muted mb-0">{{ texts.empty }}</p>
    {% endif %}
  </div>
{% endblock %}

医生或客户列表:各自特有的文本存放在变量 [texts] 中,路由名称由节名称生成:[section|add:'_edit'] 得到 [doctors_edit] 或 [clients_edit] (过滤器 [add] 将两个数字相加,或如本例中那样将两个字符串连接)。[{% url %}] 因此接受一个计算得出的表达式作为路由名称,后接路由参数([person.id])。[person.account.login]:账户登录名,与列表一起加载(DAO 层),并随列表一起存入缓存。“删除”按钮是一个带确认的 POST 表单。

11.18.3.4. templates/persons/form.html

{% extends "layout.html" %}
{% comment %}
  =========================================================================
  templates/persons/form.html - 创建或更新医生或
  客户(ADMIN),使用 PersonForm 表单。

  当输入被拒绝时(字段为空、登录名已被占用等),视图会再次显示
  此页面,模板展示:
    - 已输入的值(密码除外);
    - 有问题的字段框成红色(Bootstrap 类 "is-invalid");
    - 在被验证拒绝的字段下方,显示其消息;
    - 页面的错误消息,位于页面底部(error_zone 标签)。
  表单发送到页面自身的 URL(没有 action 属性)。
  =========================================================================
{% endcomment %}
{% load i18n %}

{% block content %}
<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">{{ page_title }}</h5>

      <form method="post" novalidate>
        {% csrf_token %}
        {# 称谓、名、姓:三个表单共用的片段 #}
        {% include "macros.html#identity" %}

        <h6 class="mt-4 text-muted">{% translate "User account" %}</h6>
        {{ form.login.as_field_group }}
        {# 从不预填:密码绝不会回传给浏览器 #}
        {{ form.password.as_field_group }}
        {# 仅在更新模式下:记录的版本,放在隐藏字段中(乐观锁) #}
        {% if form.version %}{{ form.version }}{% endif %}

        <div class="d-flex gap-2 mt-4">
          <button type="submit" class="btn btn-primary">{% translate "Save" %}</button>
          <a class="btn btn-secondary" href="{{ list_url }}">{% translate "Back to the list" %}</a>
        </div>
      </form>
    </div>
  </div>
</div>
{% endblock %}

使用 [PersonForm] 表单创建或修改医生或客户。

  • 第 24 行:一个没有 [action] 属性的 POST 表单:它被发送到页面自身的 URL([/doctors/add] 或 [/doctors/3/edit])。[novalidate] 在提交表单时禁用浏览器验证([required]、[maxlength]……):由服务器执行验证,其结果具有权威性(示例 19);
  • 第 27 行:称谓、名和姓,通过片段 [identity] 实现;
  • 第 30–32 行:用户名和密码,它们从不预先填充。其提示信息在创建和修改时有所不同(取决于表单构造方式);
  • 第 34 行:仅用于编辑,隐藏的版本字段(乐观锁)。[{{ form.version }}] 单独生成输入字段,不带标签:[<input type="hidden" name="version" value="1" id="id_version">]。创建记录时,表单没有 [version] 字段:该变量为空,测试结果为 false。

不涉及任何字段的表单自身错误([non_field_errors],示例 19)无需显示:表单不会产生此类错误,而无效的防 CSRF 令牌会在视图之前被拒绝(419 页面)。

11.18.3.5. templates/registration.html

{% extends "layout.html" %}
{% comment %}
  =========================================================================
  templates/registration.html - “创建患者账户”(公开页面,见
  web/views/registration.py),使用 RegistrationForm 表单。身份字段
  与 ADMIN 表单相同(identity 片段),但登录名和
  密码为必填,并需确认。此处没有验证码:此页面
  只有在输入了身份验证页面的验证码之后才能进入
  (按钮“创建患者账户”)。
  =========================================================================
{% endcomment %}
{% load i18n %}

{% block content %}
<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">{% translate "Create a patient account" %}</h5>
      <p class="text-muted small mb-3">{% translate "With this account you can book your own appointments." %}</p>

      <form method="post" action="{% url 'registration' %}" novalidate>
        {% csrf_token %}
        {% include "macros.html#identity" %}

        <h6 class="mt-4 text-muted">{% translate "User account" %}</h6>
        {{ form.login.as_field_group }}
        {# 密码及其确认,并排显示 #}
        <div class="row g-3">
          <div class="col-sm-6">{{ form.password.as_field_group }}</div>
          <div class="col-sm-6">{{ form.confirmation.as_field_group }}</div>
        </div>

        <div class="d-flex gap-2 mt-3">
          <button type="submit" class="btn btn-primary">{% translate "Create my account" %}</button>
          <a class="btn btn-secondary" href="{% url 'login' %}">{% translate "Back to login" %}</a>
        </div>
      </form>
    </div>
  </div>
</div>
{% endblock %}

创建患者账户:标识字段,然后是用户名、密码和确认密码——均为必填字段——并排显示(第 28–31 行)。密码的帮助文本说明了最小长度:“至少 6 个字符。”此处没有验证码(CAPTCHA):只有在登录页面输入验证码之后才能到达此页面。

11.18.3.6. templates/area.html

{% extends "layout.html" %}
{% comment %}
  =========================================================================
  templates/area.html - “我的空间”:患者(USER 角色)的主页,
  登录后立即显示。
    - 两个选项:[Manage my account] 和 [View a schedule];
    - 其即将到来的预约(如果有),并提供取消的方式。
  =========================================================================
{% endcomment %}
{% load i18n %}

{% block content %}
  <h4 class="mb-3">{% blocktranslate %}Hello {{ patient }}{% endblocktranslate %}</h4>

  <div class="row g-3 mb-4">
    <div class="col-sm-6">
      <a class="card p-4 h-100 text-decoration-none option-card" href="{% url 'account' %}">
        <h5 class="mb-1">{% translate "Manage my account" %}</h5>
        <span class="text-muted">{% translate "Change my details or password, or delete my account." %}</span>
      </a>
    </div>
    <div class="col-sm-6">
      <a class="card p-4 h-100 text-decoration-none option-card" href="{% url 'schedule' %}">
        <h5 class="mb-1">{% translate "View a schedule" %}</h5>
        <span class="text-muted">{% translate "See a doctor's schedule and book a slot." %}</span>
      </a>
    </div>
  </div>

  <div class="card p-3">
    <h5>{% translate "My appointment" %}</h5>
    {% comment %}
      通常只有一个(规则“同一时间只有一个即将到来的预约”),但页面
      可以显示多个。{% for %} ... {% empty %}:一个循环,以及列表为空时
      显示的内容;forloop.last:是否为最后一个元素?
    {% endcomment %}
    {% for appointment in appointments %}
    <div class="d-flex flex-wrap justify-content-between align-items-center gap-2 py-2{% if not forloop.last %} border-bottom{% endif %}">
      <div>
        <div class="fw-semibold">{{ appointment.day }}, {{ appointment.time_range }}</div>
        <div class="text-muted">
          <span>{{ appointment.doctor }}</span> -
          <a href="{{ appointment.schedule_url }}">{% translate "see in the schedule" %}</a>
        </div>
      </div>
      <form method="post" action="{% url 'area_cancel' %}" class="m-0"
            data-confirmation="{% translate 'Cancel this appointment?' %}">
        {% csrf_token %}
        <input type="hidden" name="appointmentId" value="{{ appointment.id }}">
        <button type="submit" class="btn btn-outline-danger">{% translate "Cancel this appointment" %}</button>
      </form>
    </div>
    {% empty %}
    <p class="text-muted mb-0">{% translate "You have no upcoming appointment." %}</p>
    {% endfor %}
  </div>
{% endblock %}

“我的空间”,患者的主页:两张大卡片(“管理我的账户”“查看日程”),以及其即将到来的预约。

  • 第 13 行:[{% blocktranslate %}Hello {{ patient }}{% endblocktranslate %}]:一段含有变量的翻译文本(法语词典中为 [Bonjour %(patient)s]);
  • 第 37–55 行:[{% for %}] …… [{% empty %}] (示例 14)是一个循环,后面是列表为空时要显示的内容。通常,一名患者最多只有一个即将到来的预约;不过,该页面能够显示多个预约。[forloop.last] (示例 14):最后一项没有分隔符;
  • 第 46–51 行:每个预约都有一个取消表单(POST,带确认),它只发送预约的 ID:服务器会验证该预约是否属于已登录的患者。

11.18.3.7. templates/account.html

{% extends "layout.html" %}
{% comment %}
  =========================================================================
  templates/account.html - “管理我的账户”(USER 角色)。同一页面上有
  两个相互独立的表单:
    1. 更新(身份、登录名、可选的新密码),使用
       MyAccountForm 表单;
    2. 删除账户(同时会取消其预约):
       一个手写的表单。
  两者都需要当前密码(current_password 字段)。
  =========================================================================
{% endcomment %}
{% load i18n %}

{% block content %}
<div class="row justify-content-center">
  <div class="col-md-8 col-lg-6">

    {# 1. 更新;novalidate:由服务器负责验证(见示例 19) #}
    <div class="card p-4 mb-4">
      <h5 class="card-title mb-3">{% translate "Manage my account" %}</h5>

      <form method="post" action="{% url 'account' %}" novalidate>
        {% csrf_token %}
        {% include "macros.html#identity" %}

        <h6 class="mt-4 text-muted">{% translate "User account" %}</h6>
        {{ form.login.as_field_group }}
        <div class="row g-3">
          <div class="col-sm-6">{{ form.password.as_field_group }}</div>
          <div class="col-sm-6">{{ form.confirmation.as_field_group }}</div>
        </div>
        {{ form.current_password.as_field_group }}
        {# 记录的版本:一个隐藏字段(乐观锁) #}
        {{ form.version }}

        <div class="d-flex gap-2 mt-4">
          <button type="submit" class="btn btn-primary">{% translate "Save" %}</button>
          <a class="btn btn-secondary" href="{% url 'area' %}">{% translate "Back to my area" %}</a>
        </div>
      </form>
    </div>

    {% comment %}
      2. 删除。密码字段与第一个表单的字段同名
      (current_password),但 id 不同:同一页面中
      的两个元素不能有相同的 id
    {% endcomment %}
    <div class="card p-4 border-danger">
      <h5 class="card-title text-danger mb-1">{% translate "Delete my account" %}</h5>
      <p class="text-muted small">{% translate "Your account will be permanently deleted, together with all your appointments." %}</p>
      <form method="post" action="{% url 'account_delete' %}" class="d-flex flex-wrap gap-2 align-items-end"
            data-confirmation="{% translate 'Permanently delete your account? Any appointment you have will be cancelled.' %}">
        {% csrf_token %}
        <div class="flex-grow-1">
          <label class="form-label" for="delete_password">{% translate "Current password" %}</label>
          <input id="delete_password" name="current_password" type="password" maxlength="72"
                 autocomplete="current-password" required class="form-control">
        </div>
        <button type="submit" class="btn btn-danger">{% translate "Delete my account" %}</button>
      </form>
    </div>

  </div>
</div>
{% endblock %}

“管理我的账户”:同一页面上的两个独立表单。

  • 第 20–42 行:使用 [MyAccountForm] 表单进行更新:包括标识字段、登录名、新密码及其确认(可选)、当前密码(必填)以及隐藏的版本字段;
  • 第 49–62 行:账户删除,一个手写的表单,带有自己的当前密码字段和一个确认字段。该字段与第一个表单中的字段同名([current_password]),但 ID 不同:页面上的两个元素不能有相同的 ID,label 的属性 [for] 也体现了这一点。这两个表单相互独立:浏览器只发送被点击按钮所在表单的字段。

11.18.3.8. templates/error.html

{% extends "layout.html" %}
{% comment %}
  templates/error.html - 错误页面(400、403、404、405、419、500 等),
  由 web/views/errors.py 构建。
{% endcomment %}
{% load i18n %}

{% block content %}
<div class="row justify-content-center">
  <div class="col-md-8 col-lg-6">
    <div class="card p-4 text-center">
      <h1 class="display-4 text-danger">{{ code }}</h1>
      <p class="lead">{{ message }}</p>
      <div><a class="btn btn-primary" href="{% url 'home' %}">{% translate "Back to the home page" %}</a></div>
    </div>
  </div>
</div>
{% endblock %}

错误页面,由 [web/views/errors.py] 生成:HTTP 代码、消息,以及指向主页的链接([/],它会重定向到该角色的主页或登录页面)。它与其他页面一样继承父模板:导航栏(包括用户菜单)同样被包含在内。

11.19. 静态文件

名为 [static] 的文件夹包含服务器原样发送的文件(示例 15):[Bootstrap] ([lib/bootstrap],仅样式表及其许可证)、一个样式表和一个脚本。开发期间,[Django] 服务器自行提供这些文件([django.contrib.staticfiles] 应用);在生产环境中,它们通过命令 [var/static] 被复制到 [collectstatic],并由 Web 服务器提供(“生产服务器”)。

11.19.1. static/css/styles.css

/* =========================================================================
   static/css/styles.css - a few settings on top of Bootstrap
   (the same as in the other versions of this application).
   ========================================================================= */

body {
  background-color: #f5f7fa;
}

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

/* -------------------------------------------------------------------------
   .error-zone: the error messages, at the bottom of the page, on a light pink background
   (see templates/fragments/errors.html).
   position: sticky + bottom: if the page is taller than the window (a
   schedule of 12 slots, for example), the zone stays stuck to the bottom of the
   window instead of disappearing below the fold - without ever
   covering the content when the page is short.
   z-index: above the grey background of the booking dialog (.modal-backdrop).
   ------------------------------------------------------------------------- */
.error-zone {
  position: sticky;
  bottom: 1rem;
  z-index: 1060;
  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) */
.captcha-image svg {
  display: block;
  border: 1px solid #dee2e6;
  border-radius: 0.375rem;
}

针对 [Bootstrap] 的一些附加设置,与应用程序的其他版本相同。

  • 第 10–12 行:日历中可预约的时段在鼠标悬停时变为绿色;
  • 第 23–33 行:页面底部的错误区域具有浅粉色背景。[position: sticky] 配合 [bottom: 1rem]:如果页面高于窗口(日历有 12 个时段),该区域会固定在窗口底部,而不会消失在滚动条下方;如果页面较短,它停留在原位,不会遮盖任何内容。[z-index]:使其显示在预约窗口的灰色背景之上;
  • 第 36–43 行:两张大的“我的空间”卡片,鼠标悬停时会亮起;
  • 第 46–50 行:验证码(CAPTCHA)图像,带边框。

11.19.2. static/js/app.js

// =========================================================================
// static/js/app.js - 应用中唯一的 JavaScript。
// -------------------------------------------------------------------------
// 整个应用无需 JavaScript 即可工作。该脚本增加了一项
// 便利功能:在发送带有属性
// data-confirmation="..." 的表单之前,会弹出模态对话框询问“您确定吗?”
// (对话框本身位于页面中:templates/fragments/confirmation.html)。
// 如果禁用了 JavaScript,表单会直接发送,没有
// 确认 - 什么都不会出问题(“渐进增强”原则)。
//
// 为什么不用 window.confirm()?它的对话框无法设置样式,而且其
// 按钮保持浏览器的语言,而不是页面的语言。
// =========================================================================

(() => {
  const modal = document.getElementById('confirmation-modal');
  if (!modal) {
    return;
  }
  const message = document.getElementById('confirmation-modal-message');
  const noButton = modal.querySelector('.modal-footer [data-action="no"]');

  let pendingForm = null; // 用户确认后要发送的表单
  let previousFocus = null; // 关闭时要把焦点交还给的元素

  function open(form) {
    pendingForm = form;
    previousFocus = document.activeElement;
    // textContent(而不是 innerHTML):消息作为文本显示,
    // 绝不会被解释为 HTML
    message.textContent = form.dataset.confirmation;
    modal.classList.remove('d-none');
    // 焦点落在“否”上:无意中按下回车键不会删除任何内容
    noButton.focus();
  }

  function close() {
    modal.classList.add('d-none');
    pendingForm = null;
    if (previousFocus) {
      previousFocus.focus();
    }
  }

  // 1. 我们拦截要确认的表单的发送
  document.querySelectorAll('form[data-confirmation]').forEach((form) => {
    form.addEventListener('submit', (event) => {
      event.preventDefault();
      open(form);
    });
  });

  // 2. 对话框的按钮(是 / 否 / 关闭叉号)
  modal.addEventListener('click', (event) => {
    const action = event.target.closest('[data-action]')?.dataset.action;
    if (action === 'yes') {
      const form = pendingForm;
      close();
      // form.submit() 发送表单时不会再次触发
      // 'submit' 事件:不会再有新的确认请求
      form.submit();
    } else if (action === 'no') {
      close();
    } else if (event.target.classList.contains('modal')) {
      close(); // 点击灰色背景,即对话框之外
    }
  });

  // 3. 键盘:Escape 关闭对话框;Tab 停留在对话框内部
  //    (否则焦点会跑到后面变灰的页面上)
  modal.addEventListener('keydown', (event) => {
    if (event.key === 'Escape') {
      close();
    } else if (event.key === 'Tab') {
      const buttons = [...modal.querySelectorAll('button')];
      const first = buttons[0];
      const last = buttons[buttons.length - 1];
      if (event.shiftKey && document.activeElement === first) {
        event.preventDefault();
        last.focus();
      } else if (!event.shiftKey && document.activeElement === last) {
        event.preventDefault();
        first.focus();
      }
    }
  });
})();

应用程序中唯一的 [JavaScript] ——来自示例 21 的脚本——并做了一些补充。整个应用程序在没有 [JavaScript] 的情况下也能工作:该脚本只是增加便利,在提交带有 [data-confirmation] 属性的表单之前提供确认。如果 [JavaScript] 被禁用,表单将不经确认直接提交:不会有任何故障(渐进增强原则)。

  • 第 15–19 行:该脚本是一个定义后立即调用的函数([(() => { ... })()]);它的变量对页面的其余部分不可见。如果页面上没有确认窗口,它什么也不做;
  • 第 26–35 行:打开窗口:保存用户确认后要提交的表单,并在窗口中显示该表单的消息。[textContent],而不是 [innerHTML]:消息作为文本显示,绝不会被解释为 HTML。焦点移到“否”按钮:意外按下 Enter 不会删除任何内容;
  • 第 37–43 行:关闭窗口;焦点返回到之前拥有焦点的元素;
  • 第 46–51 行:拦截每个需要确认的表单的提交([preventDefault] 阻止提交),并打开窗口。[submit] 事件仅在浏览器完成验证之后才会发生:账户删除表单中必填的([required])当前密码,在提示出现之前就必须填写;
  • 第 54–67 行:窗口中的按钮。整个窗口只用一个处理程序:[closest('[data-action]')] 找到被点击的按钮或包含它的元素;[?.] 确保在没有匹配项时 [undefined] 不会返回错误。“是”通过 [form.submit()] 提交表单,这不会触发 [submit] 事件:因此不会再次出现确认提示。点击窗口外变灰的背景会关闭窗口;
  • 第 71–86 行:键盘。Esc 关闭窗口;Tab 键在按钮之间移动焦点,而不会离开窗口(否则焦点会移到其后变灰的页面上):这正是使用键盘导航的用户和屏幕阅读器用户所期望的。