11. 案例研究:RdvMedecins 应用程序
11.1. 问题描述
RdvMedecins 应用程序用于管理一家医疗诊所的预约。每位医生都有若干时间段(例如从上午 8:00 到中午 12:00,每 20 分钟一个);一次预约由日期、时间段和客户(患者)组成。这是用 [Flask] 对上一课中 [Spring MVC] 应用程序的精确移植(而那个应用程序本身又是从 [ASP.NET Core MVC] 版本移植而来的):相同的数据库、相同的业务规则,相同的页面、相同的 URL、相同的翻译字典。HTML 页面由服务器使用 [Jinja2] 视图生成;数据库访问由 [SQLAlchemy] 负责。
三种用户角色共用该应用程序:
角色 | 对象 | 可执行的操作 |
ADMIN | 管理员([admin]) | 查看日程,为任何患者预约和取消预约;管理(列出、添加、编辑、删除)医生和客户 |
DOCTOR | 医生 | 查看日程,为任何患者预约和取消预约 |
USER | 客户(患者) | 查看日程,但看不到其他患者的姓名;为自己预约;取消自己的预约;管理自己的账户;创建账户 |
主要管理规则:
- 不得预约过去的时间;
- 同一个时间段在一天内只能被预约一次;
- 一名患者同一时间只能有一个未来的预约;
- 两名医生(或两名客户)不能有相同的名和姓,一个登录名只属于一个账户;
- 有预约的医生不能被删除;删除客户时会连同其预约一起删除;
- 登录页面有防机器人保护(验证码、限制尝试次数),创建客户账户需要先在该页面上通过验证码。
11.2. 应用程序的使用
11.2.1. 登录页面

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

出现错误(这里是验证码输入错误)时,错误信息显示在页面底部,背景为浅粉色:

11.2.2. 管理员和医生看到的日历
登录之后,管理员会进入日历页面。他选择一位医生和一天:


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

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

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

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

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

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


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

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

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

患者如果试图打开仅限管理员访问的页面(这里是手动输入的 [/doctors]),会收到一个错误页面:

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


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

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

删除患者需要确认:

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

账户创建完成后,用户会被重定向回登录页面,并且用户名已经填好:

11.2.6. 会话结束
登录令牌的有效期为两小时。在此之后(或者令牌被篡改时),所请求的页面会重定向到登录页面,并显示如下消息:

11.3. 安装与执行
该应用程序位于 [rdvmedecins2-flask] 文件夹中,与 [examples] 文件夹并列。它是一个独立的项目,有自己的 [requirements.txt] 文件和虚拟环境。该文件夹中的 [README.md] 文件包含以下全部内容。本文档的引言已经介绍过安装;这里我们提供更多细节。
11.3.1. 所需软件
只需两个软件:
- [Python] 3.12 或更高版本(应用程序使用了 3.12 版本引入的泛型类语法)。在终端中验证安装:
- 一个 [MySQL] 8 服务器,例如在 [Laragon] 中、运行于 [Windows] 下的那个(参见附录)。[MariaDB] 同样可用:应用程序已用它测试过。
各个库由 [pip] 从 [PyPI] 仓库(*Python Package Index*)下载:因此,安装时必须连接互联网。推荐的编辑器是 [Visual Studio Code],并搭配 Microsoft 的 [Python] 扩展(参见附录);不过,所有操作也都可以通过命令行完成。
11.3.2. 创建数据库
[dbrdvmedecins2] 数据库由 [database/dbrdvmedecins2.sql] 脚本创建。使用 [Laragon],打开 [HeidiSQL] 工具(“数据库”按钮),然后通过“文件 / 运行 SQL”菜单运行该脚本。在命令行中,于应用程序文件夹下执行:
| mysql -u root -p < database/dbrdvmedecins2.sql
|
[-p] 选项会提示输入 [root] 的密码;如果该账户没有密码(如 [Laragon] 的情况),则省略它。这与 [ASP.NET Core] 和 [Spring MVC] 版本所使用的数据库是同一个:如果它已经存在,这一步是可选的。该脚本可以随时运行,以恢复到原始数据。
11.3.3. 配置数据库访问
所有配置设置都在文件 [config.py] 中(下文讨论)。默认情况下,应用程序连接到 [MySQL] 所在的 [localhost],端口 3306,使用用户 [root] 且没有密码:这些是 [Laragon] 的默认设置。如果你的 [root] 账户有密码,最简单的方法是在该文件中的 [DB_PASSWORD = ""] 这一行填入密码。为避免把密码写在项目文件中,你也可以通过环境变量来指定,它优先于文件中的设置。其名称与文件中的变量名相同,前面加上 [FLASK_] (示例 25):
| export FLASK_DB_PASSWORD=myPassword # Linux、macOS
set FLASK_DB_PASSWORD=myPassword # Windows(cmd)
$env:FLASK_DB_PASSWORD="myPassword" # Windows(PowerShell)
|
该变量只在定义它的终端中有效;然后从该终端启动应用程序。
11.3.4. 启动应用程序
在一个打开到 [rdvmedecins2-flask] 文件夹的终端窗口中,已创建并激活虚拟环境,且已安装各个库(参见引言):
引言中已展示过控制台输出。接下来,在浏览器中打开 URL [http://localhost:8081] ,并使用 [Ctrl-C] 停止应用程序。
11.3.5. 演示账户
每个账户的密码就是它的用户名;你还必须输入图片中的字符,大小写均可:
登录名 | 角色 |
[admin] | ADMIN(管理员) |
[pelissier]、[tatou]、[dupont] | DOCTOR(医生) |
[martin]、[durand]、[bistrou]、[german] | USER(患者) |
探索该应用的指南:
- [admin]:日程, Marie PELISSIER 女士,今天:有一个时间段已被 Brigitte BISTROU 女士预约。为 Jean MARTIN 先生预约一个时间段,然后尝试为他预约第二个(会被拒绝)。医生和患者菜单:添加、编辑、删除(有预约的 PELISSIER 医生无法被删除);
- [pelissier]:直接显示他的每日日程;手动输入地址 [/doctors] 会返回 403 错误页面;
- [martin]:我的专区, 其预约、日历(其他患者显示为“已预约”);管理我的账户;
- 登录页面:创建患者账户,然后使用新账户登录;
- FR / EN 按钮:整个界面切换语言,包括日期。
11.3.6. 开发模式
[app.py] 文件使用 [dev] 配置文件([config_dev.py] 文件,稍后讨论)启动应用程序:此时控制台会显示 [SQLAlchemy] 发送给数据库的每一条 SQL 命令。开发服务器的调试模式增加了两项功能:
- 自动重新加载:只要修改了某个 [.py] 文件,应用程序就会自动重启。被修改的 [templates/*.html] 视图会在下次显示该页面时重新加载;
- 异常调试页面 (示例 03),在这里被 [PROPAGATE_EXCEPTIONS = False] 设置禁用了(见下文):应用程序即使在开发期间也会显示它自己的错误页面,而异常调用栈则写入控制台。
[Visual Studio Code] 调试器也允许你单步执行应用程序:在代码行的边距处单击以设置断点,然后通过“运行 / 启动调试”菜单([app.py] 文件,[F5] 键)启动,选择“Python Debugger”,再选择“Python File”。应避免自动重新加载(它会在单独的进程中启动应用程序,而调试器不会跟踪该进程):使用命令 [flask --app rdvmedecins run --port 8081] (不带 [--debug])启动应用程序即可禁用它。
11.3.7. 生产服务器
[Werkzeug] 开发服务器不适用于生产环境:它在启动时自己就这样声明。在生产环境中,应用程序部署到 WSGI 服务器 (参见关于生命周期的章节)。应用程序在其 [requirements.txt] 文件中声明了一个:[Waitress],一个用 [Python] 编写的服务器,它在 [Windows] 上和在 [Linux] 上一样运行良好。它已经安装在虚拟环境中:
| waitress-serve --port=8081 --call rdvmedecins:create_app
|
| INFO:waitress:Serving on http://0.0.0.0:8081
|
选项 [--call] 指定要调用的工厂([create_app],位于 [rdvmedecins] 包中)来获取应用程序。以这种方式启动时,应用程序没有 [dev] 配置文件(控制台不会显示 SQL 命令),也不处于调试模式。[Waitress] 通过多个线程并行处理多个请求(默认四个;选项 [--threads])。在 [Linux] 下,[Gunicorn] 也被广泛使用;不过,它无法在 [Windows] 下运行。在这两种情况下,WSGI 服务器通常都放在 Web 服务器([nginx]、[Apache])之后,由后者以 HTTPS 方式处理请求,并将其转发给应用程序。
在生产环境中,你还必须修改密钥,并通过环境变量指明站点通过 HTTPS 提供服务:
| export FLASK_SECRET_KEY="<a long random string>"
export FLASK_JWT_SECRET="<another long random string>"
export FLASK_COOKIE_SECURE=true
|
可以使用 [Python] 本身获得合适的随机字符串:[python -c "import secrets; print(secrets.token_urlsafe(48))"]。
11.3.8. 常见问题
启动时,应用程序会读取医生和客户的列表:如果数据库无法访问,应用程序会立即停止,并在控制台中显示错误。这个错误之前有一长串调用栈;相关的消息位于末尾,在 [(Background on this error at: ...)] 这一行之前。例如,数据库不存在时:
| ...
sqlalchemy.exc.OperationalError: (pymysql.err.OperationalError) (1049, "Unknown database 'dbunknown'")
(Background on this error at: https://sqlalche.me/e/21/e3q8)
|
最常见的消息:
消息 | 原因 |
[Can't connect to MySQL server on 'localhost' ([Errno 111] Connection refused)] ([[WinError 10061]] 在 [Windows] 下) | [MySQL] 尚未启动,或没有监听 [localhost:3306] |
[Access denied for user 'root'@'localhost'] | 必须输入 [MySQL] 的密码(参见“配置数据库访问”) |
[Unknown database 'dbrdvmedecins2'] | 脚本 [database/dbrdvmedecins2.sql] 尚未执行 |
[JWT_SECRET must be at least 32 characters long (see config.py).] | [config.py] (或变量 [FLASK_JWT_SECRET])中的令牌密钥太短 |
[ModuleNotFoundError: No module named 'flask'] | 虚拟环境未启用,或者库没有安装在其中 |
[Address already in use] 或 [Port 8081 is in use by another program] | 端口 8081 已被占用(是否正在运行 [Spring MVC] 版本?):停止它,或者在 [app.py] 中更改端口 |
['cryptography' package is required for sha256_password or caching_sha2_password auth methods] | [MySQL] 账户使用的是来自 [MySQL] 8 的身份验证设置:由 [cryptography] 库(由 [PyMySQL[rsa]] 安装,参见 [requirements.txt])缺失 |
启动时在 [SyntaxError] [class ...[T: ...]] 这一行出现 | [Python] 的版本低于 3.12 |
11.4. 应用程序架构

- 浏览器将请求发送给服务器([Werkzeug] 开发服务器,或 [Waitress]),服务器再将请求转发给 [Flask] 应用程序。每个请求首先经过 [before_request] 函数(参见关于生命周期的章节):请求语言,然后是用户——根据其 Cookie 中的 JWT 令牌来识别——以及访问规则,该规则会对无权查看受保护页面的访问者拒绝访问这些页面([auth/security.py]);
- [controllers]:Web 层控制器,应用程序的每个部分对应一个蓝图。它们都经过同一个对象 [ApplicationModel] (文件夹 [web]),该对象在内存中存储医生和客户的列表,并将其他请求转发给业务层;
- [auth]:身份验证、JWT 令牌、验证码、尝试次数限制和账户创建;
- [web]:Web 层的公共元素:缓存和 [ApplicationModel] 外观、翻译、闪现消息、验证、所有视图共用的变量以及错误页面;[forms]:表单;[WTForms];[models]:视图模板;
- [business]:业务规则和事务;
- [repositories]:DAO 层,每个表对应一个类;
- [entities]:[SQLAlchemy] 从数据库读取并写入数据库的实体;[domain]:日历对象,由业务层计算;
- [templates]:[Jinja2] 视图,用于生成 HTML 页面;[i18n]:字典,由翻译器使用;[static]:样式表、页面脚本和 [Bootstrap];
- [rdvmedecins/__init__.py]:[create_app] 构建器,负责组装所有内容;[config.py]:配置。
应用程序文件夹:
| rdvmedecins2-flask/
├── app.py
├── config.py
├── config_dev.py
├── database/
│ ├── dbrdvmedecins2.sql
│ └── README.md
├── rdvmedecins/
│ ├── __init__.py
│ ├── auth/
│ │ ├── auth_service.py
│ │ ├── captcha.py
│ │ ├── captcha_drawing.py
│ │ ├── connected_user.py
│ │ ├── limiter.py
│ │ ├── passwords.py
│ │ ├── README.md
│ │ ├── registration_pass.py
│ │ └── security.py
│ ├── business/
│ │ ├── business.py
│ │ ├── dates.py
│ │ ├── exception.py
│ │ ├── person_data.py
│ │ ├── README.md
│ │ └── service.py
│ ├── controllers/
│ │ ├── area.py
│ │ ├── auth.py
│ │ ├── clients.py
│ │ ├── doctors.py
│ │ ├── language.py
│ │ ├── persons.py
│ │ ├── README.md
│ │ ├── registration.py
│ │ └── schedule.py
│ ├── domain/
│ │ ├── README.md
│ │ └── schedule.py
│ ├── entities/
│ │ ├── appointment.py
│ │ ├── base.py
│ │ ├── person.py
│ │ ├── README.md
│ │ ├── role.py
│ │ ├── slot.py
│ │ └── user.py
│ ├── forms/
│ │ ├── forms.py
│ │ ├── README.md
│ │ └── rules.py
│ ├── i18n/
│ │ ├── en.json
│ │ └── fr.json
│ ├── models/
│ │ ├── README.md
│ │ └── view_models.py
│ ├── repositories/
│ │ ├── appointment_repository.py
│ │ ├── client_repository.py
│ │ ├── doctor_repository.py
│ │ ├── person_repository.py
│ │ ├── README.md
│ │ ├── slot_repository.py
│ │ └── user_repository.py
│ ├── static/
│ │ ├── css/
│ │ │ └── styles.css
│ │ ├── js/
│ │ │ └── app.js
│ │ └── lib/
│ │ └── bootstrap/
│ ├── templates/
│ │ ├── account.html
│ │ ├── area.html
│ │ ├── error.html
│ │ ├── fragments/
│ │ │ ├── booking.html
│ │ │ ├── captcha.html
│ │ │ ├── confirmation.html
│ │ │ ├── errors.html
│ │ │ ├── flash.html
│ │ │ ├── navbar.html
│ │ │ └── person_fields.html
│ │ ├── layout.html
│ │ ├── login.html
│ │ ├── persons/
│ │ │ ├── form.html
│ │ │ └── list.html
│ │ ├── README.md
│ │ ├── registration.html
│ │ └── schedule.html
│ └── web/
│ ├── application_model.py
│ ├── common_model.py
│ ├── errors.py
│ ├── flash.py
│ ├── README.md
│ ├── services.py
│ ├── translator.py
│ ├── utils.py
│ └── validation.py
├── README.md
└── requirements.txt
|
每个包文件夹中还包含一个名为 [__init__.py] 的文件——通常为空——它把该文件夹变成一个 [Python] 包:正是它使得可以编写 [from rdvmedecins.entities import Doctor]。这一次,[Bootstrap] 是应用程序的一部分(文件夹 [static/lib/bootstrap]):案例研究是自包含的。
请注意对 [rdvmedecins] 包所做的选择:应用程序不再是一个简单的 [app.py] 模块,而是一个包,其 [__init__.py] 文件包含 [create_app] 工厂。这是 [Flask] 文档针对这种规模的应用程序所推荐的结构:位于根目录的 [app.py] 文件仅用于启动开发服务器。
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–54 行:users:登录名、密码 经哈希处理,使用 [bcrypt] (示例 25)、登录后显示的名称,以及角色([ADMIN]、[DOCTOR]、或 [USER])。约束 [unq_users_login] 确保一个用户名只属于一个账户;
- 第 60–71 行:每张表都有一个由数据库生成的主键 [id],以及一个列 [version],即乐观锁(示例 28)。列 [user] 是一个引用 外键 的列,引用的是 [users(id)]:数据库会拒绝任何不是现有用户 ID 的值。由于 [user] 是 SQL 的保留字,因此用反引号括起来。三个约束:[fk_doctors_user] (外键)、[unq_doctors_user] (每位医生一个账户,每个账户一位医生)以及 [unq_doctors_first_name_last_name] (不允许同名)。所有约束都有名称:应用程序通过名称来识别被违反的约束;
- 第 77–88 行:[clients] 表的列与之完全相同;
- 第 94–102 行:时间段属于某位医生;其起止时间以小时和分钟存储;
- 第 108–117 行:预约由日期(类型 [DATE],不含时间)、时间段和客户组成。约束 [unq1_appointments] 防止同一时间段在同一天被预约两次:即使两个用户同时预约,数据库也会强制执行这条规则;
- 第 130–140 行:演示用户,其密码就是其登录名。哈希以 [$2b$10$] 开头:算法([bcrypt],变体 [2b])和成本(10)。接下来是盐和哈希值;
- 第 144–147 行:每位医生的 [user] 列是通过基于登录名的子查询获取的,而不是假定主键的值;
- 第 170–171 行:为 PELISSIER 医生的第二个时间段、BISTROU 女士预约的、已安排在今天([CURDATE()])的预约:这样,日历一打开就能立刻显示出一个已被预约的时间段。
11.6. 项目配置
11.6.1. requirements.txt
| # 应用所用的库:pip install -r requirements.txt
Flask==3.1.3
Flask-WTF==1.3.0
SQLAlchemy==2.1.1
PyMySQL[rsa]==1.2.3
PyJWT==2.15.0
bcrypt==5.0.0
Babel==2.18.0
# 用于生产环境的 WSGI 服务器(见 README.md)
waitress==3.0.2
|
应用程序的各个库及其确切的版本([==])。指定版本可以确保应用程序在所有机器上的运行方式一致,即使是一年之后。[PyMySQL[rsa]] 会安装驱动程序 [PyMySQL] 及其可选依赖 [rsa],也就是 [cryptography] 库,它是 [MySQL] 8 的身份验证方法所必需的。[pip install -r requirements.txt] 会安装这些库以及它们所依赖的库([Werkzeug]、[Jinja2]、[WTForms]……)。命令 [pip freeze] 会显示虚拟环境中已安装内容的完整列表。
11.6.2. config.py
| # =========================================================================
# config.py - 应用的配置。
#
# Flask 只保留大写的变量(见 rdvmedecins/__init__.py,
# app.config.from_pyfile)。每个值都可以在不修改该
# 文件的情况下,由带 FLASK_ 前缀的环境变量替换:
# 于是 DB_PASSWORD 写作 FLASK_DB_PASSWORD(app.config.from_prefixed_env)。
# 这些变量的值在可能时按 JSON 读取:
# FLASK_LOGIN_MAX_FAILURES=3 得到数字 3,FLASK_COOKIE_SECURE=true 得到布尔值 True。
# =========================================================================
# MySQL 数据库 [dbrdvmedecins2](脚本:database/dbrdvmedecins2.sql):
# 服务器、端口、用户及其密码(Laragon 的默认设置:
# root,无密码)、数据库
DB_HOST = "localhost"
DB_PORT = 3306
DB_USER = "root"
DB_PASSWORD = ""
DB_NAME = "dbrdvmedecins2"
# True:发送到数据库的 SQL 语句会显示在控制台中
SQL_ECHO = False
# Flask 的密钥:它为会话 Cookie(flash
# 消息、anti-CSRF 令牌)签名。在生产环境中务必更改。
SECRET_KEY = "change-me-too-to-a-long-random-string"
# 身份验证(见 rdvmedecins/auth/)
# JWT 令牌的密钥:至少 32 个字符(HMAC-SHA256)。
# 在生产环境中务必更改(长随机字符串)。
JWT_SECRET = "change-me-to-a-long-random-string"
# 令牌的有效时长,单位为秒(7200 秒 = 2 小时);携带
# 令牌的 Cookie 具有相同的有效期
JWT_EXPIRES_IN_SECONDS = 7200
# 生产环境中为 True(站点通过 HTTPS 提供服务):应用的 Cookie
# 于是绝不会通过未加密的连接发送
COOKIE_SECURE = False
# 防范机器人(见 rdvmedecins/auth/limiter.py)
# 登录:同一 IP 地址对同一登录名允许的失败次数……
LOGIN_MAX_FAILURES = 5
# ……超过后将封锁这么长的时间(如果整个 IP 地址累计的失败次数
# 达到 5 倍(所有登录名合计),也会被封锁)
LOGIN_BLOCK_MINUTES = 15
# 创建客户账户:每个 IP 地址每小时最多创建的账户数。
# 在教室里,所有计算机通常通过同一个地址出网:
# 如有需要请调高。
REGISTRATION_MAX_PER_HOUR = 10
|
应用程序配置,由 [app.config.from_pyfile] 读取(示例 25):
- 第 15–19 行:数据库访问:服务器、端口、用户名和密码,以及数据库。这些值用于构造 [SQLAlchemy] 的 URL 连接字符串(见下文);
- 第 22 行:显示 SQL 命令,默认禁用;
- 第 26 行:[Flask] 的密钥,用于对会话 Cookie 签名(示例 20);
- 第 31–34 行:用于对 JWT 令牌签名的密钥,以及它们的有效期:两小时;
- 第 37 行:在生产环境中,应用程序的 Cookie 带有属性 [Secure];浏览器只会通过 HTTPS 连接发送它们;
- 第 41–48 行:机器人防护设置:允许的登录失败尝试次数及由此产生的封锁时长;单个 IP 地址每小时可以创建的客户账户数量。
每个值都可以被带有前缀 [FLASK_] 的环境变量替换。文件中的两个密钥只是开发用的值:在生产环境中必须替换它们(参见“生产服务器”)。
11.6.3. config_dev.py
| # =========================================================================
# config_dev.py - 在开发环境中补充 config.py(见 app.py,它以
# "dev" 配置启动应用):SQLAlchemy 发送的 SQL 语句
# 会显示在控制台中。
# =========================================================================
SQL_ECHO = True
|
开发配置文件:第二个文件,在 [config.py] 之后读取,其中的值会替换第一个文件中的值。这里只有一项:显示 SQL 命令。我们还可以为测试编写一个 [config_test.py] ,使用不同的数据库。
11.7. 启动应用程序
11.7.1. app.py
| # =========================================================================
# app.py - 以开发模式启动应用: python app.py
#
# Flask 开发服务器(Werkzeug),端口 8081,带有:
# - "dev" 配置(config_dev.py:显示 SQL 语句);
# - debug=True:只要某个 .py 文件被修改,应用就会自动重启,
# 并且重新加载页面时会再次读取被修改的视图。
# 在生产环境中使用真正的 WSGI 服务器(见 README.md:waitress)。
# =========================================================================
from rdvmedecins import create_app
if __name__ == "__main__":
create_app(profile="dev").run(port=8081, debug=True)
|
这个文件用于启动开发中的应用程序:以 [create_app] 工厂和 [dev] 配置文件调用,然后将应用程序交给运行在 8081 端口、处于调试模式的开发服务器。在生产环境中不使用该文件:由 WSGI 服务器调用 [create_app] (参见“生产服务器”)。
11.7.2. rdvmedecins/__init__.py
应用程序构建器。这个文件把其他所有内容整合在一起:它是应用程序的“蓝图”。
| # =========================================================================
# rdvmedecins/__init__.py
# -------------------------------------------------------------------------
# 应用工厂(见示例 02):create_app 构建并
# 配置 Flask 应用。一切都在这里装配:
# 1. 配置(config.py、config_dev.py、FLASK_... 变量);
# 2. 数据库访问:SQLAlchemy 的 engine 和会话工厂;
# 3. 共享对象:DAO -> 业务层 -> 缓存(ApplicationModel)、
# 身份验证、验证码、限流器、注册通行证、翻译器 -
# 这就是依赖注入,只不过是 "手工" 编写的;
# 4. 每个请求上运行的内容:语言、身份验证;
# 5. 蓝图(控制器)、错误处理器、
# anti-CSRF 保护。
#
# 这个文件使 [rdvmedecins] 成为一个 Python 包:执行 "from rdvmedecins
# import create_app" 时会运行此文件。
# =========================================================================
from pathlib import Path
from flask import Flask, g, request
from flask_wtf.csrf import CSRFProtect
from sqlalchemy import URL, create_engine
from sqlalchemy.orm import sessionmaker
from rdvmedecins.auth import security
from rdvmedecins.auth.auth_service import AuthService
from rdvmedecins.auth.captcha import CaptchaService
from rdvmedecins.auth.limiter import AttemptLimiter
from rdvmedecins.auth.registration_pass import RegistrationPass
from rdvmedecins.controllers.schedule import schedule
from rdvmedecins.controllers.auth import auth
from rdvmedecins.controllers.clients import clients
from rdvmedecins.controllers.area import area
from rdvmedecins.controllers.registration import registration
from rdvmedecins.controllers.language import language
from rdvmedecins.controllers.doctors import doctors
from rdvmedecins.business.service import BusinessService
from rdvmedecins.repositories.client_repository import ClientRepository
from rdvmedecins.repositories.slot_repository import SlotRepository
from rdvmedecins.repositories.doctor_repository import DoctorRepository
from rdvmedecins.repositories.appointment_repository import AppointmentRepository
from rdvmedecins.repositories.user_repository import UserRepository
from rdvmedecins.web import errors, common_model, translator
from rdvmedecins.web.application_model import ApplicationModel
from rdvmedecins.web.translator import Translator
# 项目文件夹(包含 config.py 的那个),即本包的父文件夹
ROOT = Path(__file__).resolve().parent.parent
def create_app(profile: str | None = None) -> Flask:
app = Flask(__name__)
app.jinja_env.trim_blocks = True
app.jinja_env.lstrip_blocks = True
# 1. 配置:先是 config.py,如果有配置档,则接着是 config_<profile>.py,
# 然后是 FLASK_... 环境变量
app.config.from_pyfile(ROOT / "config.py")
if profile:
app.config.from_pyfile(ROOT / f"config_{profile}.py")
app.config.from_prefixed_env()
app.config.update(
# Flask 会话 Cookie(flash 消息、anti-CSRF 令牌)
SESSION_COOKIE_NAME="rdvmedecins_session",
SESSION_COOKIE_SAMESITE="Lax",
SESSION_COOKIE_SECURE=app.config["COOKIE_SECURE"],
# 只要浏览器会话持续,anti-CSRF 令牌就保持有效
WTF_CSRF_TIME_LIMIT=None,
# 未处理的异常会交给我们的错误处理器
# (500 页面),即使在调试模式下也是如此
PROPAGATE_EXCEPTIONS=False,
)
# 2. 数据库访问。SQLAlchemy 的连接 URL
# (mysql+pymysql://root:@localhost:3306/dbrdvmedecins2?charset=utf8mb4),
# 由 URL.create 构建:包含特殊字符(@、:、/...)的
# 密码会被正确编码。str(...):变量
# FLASK_DB_PASSWORD=123456 会被当作数字读取(见 config.py)
url = URL.create("mysql+pymysql", username=str(app.config["DB_USER"]),
password=str(app.config["DB_PASSWORD"]), host=app.config["DB_HOST"],
port=int(app.config["DB_PORT"]), database=app.config["DB_NAME"],
query={"charset": "utf8mb4"})
# engine 管理一个连接池;pool_pre_ping:连接在复用之前
# 会先经过测试;pool_recycle:连接在一小时后
# 被更新(MySQL 会自行关闭空闲时间
# 过长的连接)
engine = create_engine(url, echo=app.config["SQL_ECHO"], pool_pre_ping=True,
pool_recycle=3600)
# expire_on_commit=False:读取的对象在事务结束后
# 仍可使用(供视图、缓存使用)
sessions = sessionmaker(engine, expire_on_commit=False)
# 3. 共享对象,一次性创建
business = BusinessService(sessions, DoctorRepository(), ClientRepository(),
SlotRepository(), AppointmentRepository(), UserRepository())
# 缓存会读取医生和客户:数据库不可达时,应用
# 就在此处、在启动时停止
app.extensions["rdvmedecins.application"] = ApplicationModel(business)
auth_service = AuthService(sessions, UserRepository(), app.config["JWT_SECRET"],
app.config["JWT_EXPIRES_IN_SECONDS"], app.config["COOKIE_SECURE"])
app.extensions["rdvmedecins.auth"] = auth_service
app.extensions["rdvmedecins.captchas"] = CaptchaService()
app.extensions["rdvmedecins.limiter"] = AttemptLimiter(
app.config["LOGIN_MAX_FAILURES"], app.config["LOGIN_BLOCK_MINUTES"],
app.config["REGISTRATION_MAX_PER_HOUR"])
app.extensions["rdvmedecins.passes"] = RegistrationPass()
trans = Translator(Path(app.root_path) / "i18n")
# 4. 每个请求上,按注册顺序:
# 语言(rdvmedecins_language Cookie,否则为英语)……
@app.before_request
def set_language():
g.language = translator.language(request.cookies.get(translator.LANGUAGE_COOKIE))
# ……然后是用户,以及访问规则(见 auth/security.py)
security.register(app, auth_service)
# 所有视图共用的变量
common_model.register(app, trans)
# 5. 控制器、错误页面、anti-CSRF 保护
for blueprint in (auth, language, schedule, doctors, clients, registration, area):
app.register_blueprint(blueprint)
errors.register(app)
# 每个 POST 请求都必须回传页面的 anti-CSRF 令牌
# (隐藏字段 csrf_token):否则返回 400 响应
CSRFProtect(app)
return app
|
- 第 48 行:项目文件夹,其中包含 [config.py]:即此文件所在文件夹的父文件夹([parent.parent]);
- 第 52–54 行:应用程序;[__name__] 在这里等同于 [rdvmedecins],即包名:因此 [Flask] 会在包文件夹中查找 [templates] 和 [static] 文件夹;
- 第 58–61 行:配置,分三步:[config.py] 文件、配置文件(如果有的话)以及环境变量。每个来源都会覆盖前面各来源的值;
- 第 62–71 行:针对 [Flask] 和 [Flask-WTF] 的一些设置,写在这里而不是 [config.py] 中,因为它们不打算被更改。[SESSION_COOKIE_NAME] 重命名会话 Cookie(默认:[session]),以免与由 [localhost] 提供服务的另一个应用程序的 Cookie 冲突,如示例中所示;[SESSION_COOKIE_SAMESITE] 和 [SESSION_COOKIE_SECURE] 为它指定属性 [SameSite=Lax] ,在生产环境中还有 [Secure] (示例 25)。[WTF_CSRF_TIME_LIMIT=None]:默认情况下,防 CSRF 令牌只在一小时内有效,打开时间超过一小时的表单会被拒绝;这里它在浏览器会话期间一直有效。[PROPAGATE_EXCEPTIONS=False]:在调试模式下,[Flask] 允许某些异常一直向上传播到调试页面;这个设置确保它们会经过我们的错误处理器;
- 第 79–82 行:[SQLAlchemy] 的 URL 登录令牌(示例 28),由 [URL.create] 根据各组成部分生成。手工书写 URL 时,应当编码密码中的特殊字符([@]、[:]、[/]……),这些字符在 URL 中另有含义;[URL.create] 会自行完成这一点。[str(...)] 和 [int(...)] 可防止环境变量的类型转换:[FLASK_DB_PASSWORD=123456] 会被解释为数字;
- 第 87–88 行:引擎及其连接池。[pool_recycle=3600] 会在一小时后更新连接;[MySQL] 会自动关闭闲置时间过长(默认八小时)的连接;
- 第 91 行:会话工厂(示例 28);
- 第 94–106 行:共享对象,一次性创建,并存储在 [app.extensions] 中(示例 06)。这就是手工编写的依赖注入:每个对象在其构造函数中接收它所需的对象。业务层接收会话工厂和 DAO 层的五个类;[ApplicationModel] 缓存接收业务层;身份验证服务接收会话工厂、DAO 的用户类和令牌配置。[app.extensions] 中的键以 [rdvmedecins.] 为前缀,以免与各扩展中的键冲突([Flask-WTF] 也把它的对象存放在那里)。[ApplicationModel] 的构造函数会读取医生和客户的列表:如果数据库无法访问,应用程序会在启动时就在此处停止,而不是等到第一个请求时;
- 第 107 行:翻译服务(示例 22);
- 第 111–113 行:第一个函数 [before_request],从 [rdvmedecins_language] Cookie 中获取请求语言;
- 第 116 行:第二个变量:请求用户,以及访问规则(参见 [auth/security.py])。顺序很重要:未授权访问者被重定向到的登录页面需要知道语言;
- 第 118 行:所有视图共用的变量(示例 15 中的上下文处理器,参见 [web/common_model.py]);
- 第 121–122 行:应用程序的七个蓝图;
- 第 123 行:错误处理器(参见 [web/errors.py]);
- 第 126 行:对所有请求(POST,示例 21)的 CSRF 保护。
这个文件相当于 [Spring Boot] 应用程序的启动类和配置类,以及 [ASP.NET Core] 应用程序的 [Program.cs] 文件。主要区别在于:[Flask] 不会自行创建或注入任何东西。应用程序中存在的一切都是在这里显式创建的,你可以追踪每个对象从创建到使用的全过程。
11.8. 实体
[entities] 文件夹为每张表包含一个类:即 实体 ,[SQLAlchemy] 据此从数据库读取并写入数据库(示例 28)。除非另有说明,它们的属性以列名命名。
11.8.1. entities/base.py
| # =========================================================================
# entities/base.py
# -------------------------------------------------------------------------
# 所有实体的父类,以及所有表共有的
# 两列:标识符 [id] 和版本号 [version]。
#
# "声明式" SQLAlchemy:Base 的每个子类描述一张表
# (__tablename__),每个 Mapped[...] 属性描述一列。SQLAlchemy 在启动时读取
# 这些声明,以得知哪个类对应哪张表,
# 哪个属性对应哪一列。
# =========================================================================
from sqlalchemy.orm import DeclarativeBase, Mapped, declared_attr, mapped_column
class Base(DeclarativeBase):
pass
# 一个 MIXIN:没有表的类,其列会添加到
# 继承它的类的列中(Doctor、Client、Slot、Appointment、User)
class WithIdAndVersion:
# 主键,由数据库生成(AUTO_INCREMENT 列):
# SQLAlchemy 在每次 INSERT 之后回读其值。尚未
# 保存的实体,其 id 为 None。
id: Mapped[int] = mapped_column(primary_key=True)
# 乐观锁。SQLAlchemy 发送的每个 UPDATE 都带有
# 条件 "WHERE id = ... AND version = <读取到的值>",并写入
# 加 1 后的版本号。如果在此期间有人修改了该行,
# 就没有任何行被更新:SQLAlchemy 会抛出 StaleDataError
# (见 business/service.py)。
version: Mapped[int] = mapped_column()
# @declared_attr:为每个子类计算的属性;
# version_id_col:用作乐观锁的列
@declared_attr.directive
def __mapper_args__(cls):
return {"version_id_col": cls.version}
|
- 第 15–16 行:所有实体的父类(示例 28);
- 第 21–39 行:所有表共有的两个列 [id] 和 [version],只定义一次。[WithIdAndVersion] 是一个混入类(mixin):它没有对应的表,也从不单独创建,而是供子类继承其列。因此,一个实体继承自两个类:[class User(WithIdAndVersion, Base)] (多重继承 ,来自 [Python]);
- 第 37–39 行:乐观锁(示例 28)。[__mapper_args__] 必须引用[version] 列,且是每个子类的该列,而不是混入类的:[@declared_attr.directive] 装饰器把这个方法变成computed 属性,作用于每个继承该混入类的类。[SQLAlchemy] 在解析子类时调用它,并把子类作为参数传入([cls])。
11.8.2. entities/role.py
| # =========================================================================
# entities/role.py
# -------------------------------------------------------------------------
# 用户的三种角色(users.role 列):
# - ADMIN :管理员,负责预约以及医生和客户的管理;
# - DOCTOR :医生,预订和取消预约;
# - USER :客户(患者),为自己预订,管理自己的账户。
#
# 枚举(Enum):不可能有其他值。StrEnum:它的
# 值同时也是字符串("ADMIN"),原样存放在数据库中,
# 与 SQL 脚本的做法一致(见 user.py)。
# =========================================================================
from enum import StrEnum
class Role(StrEnum):
ADMIN = "ADMIN"
DOCTOR = "DOCTOR"
USER = "USER"
|
枚举:一种其可能取值一经确定就固定不变的类型([Role.ADMIN]、[Role.DOCTOR]、[Role.USER])。[StrEnum] (标准模块 [enum],[Python] 3.11):每个值同时也是一个字符串,等于 ["ADMIN"]等。因此,它可以与字符串比较、写入 JWT 令牌,或包含在页面中,而无需转换。
11.8.3. entities/user.py
| # =========================================================================
# entities/user.py
# -------------------------------------------------------------------------
# 允许登录应用的用户([users] 表)。
# 每个医生和每个客户都有各自的用户账户([doctors] 和 [clients]
# 表的 [user] 列,见 person.py)。
#
# SQL 唯一性约束:unq_users_login(一个登录名只属于一个
# 账户)。它由脚本 database/dbrdvmedecins2.sql 创建;
# 业务层通过它的名称来识别它(见 business/service.py)。
# =========================================================================
from sqlalchemy import Enum, String
from sqlalchemy.orm import Mapped, mapped_column
from rdvmedecins.entities.base import WithIdAndVersion, Base
from rdvmedecins.entities.role import Role
class User(WithIdAndVersion, Base):
__tablename__ = "users"
login: Mapped[str] = mapped_column(String(30))
# 经过哈希的密码(bcrypt),绝不存明文
password: Mapped[str] = mapped_column(String(100))
# 登录后显示的名称:对医生或客户而言,
# 是 "名 姓"(例如:"Marie PELISSIER")
name: Mapped[str] = mapped_column(String(40))
# ADMIN、DOCTOR 或 USER,在数据库中存为文本。
# native_enum=False:普通的 VARCHAR 列(而不是 MySQL 的 ENUM 类型)
role: Mapped[Role] = mapped_column(Enum(Role, native_enum=False, length=10))
|
- 第 19 行:该实体从混入类继承 ID 和版本,并从 [Base] 继承其余部分;
- 第 24 行:哈希后的密码;
- 第 30 行:类型为 [Role] 的属性。[SQLAlchemy] 的 [Enum] 类型在写入时将枚举转换为文本(["ADMIN"]),在读取时将文本转换为枚举。[native_enum=False]:该列是一个简单的 [VARCHAR],与 SQL 脚本中一致,而不是 [ENUM] 这种 [MySQL] 特有的类型。
11.8.4. entities/person.py
| # =========================================================================
# entities/person.py
# -------------------------------------------------------------------------
# 医生([doctors] 表)和客户([clients] 表):一个
# 称谓、一个姓、一个名,以及关联的用户账户([user] 列)。
#
# 两张表的列完全相同:它们在 Person mixin 中只描述
# 一次,Doctor 和 Client 都继承自它。在 mixin 中声明的
# 关系必须由 @declared_attr 方法声明:
# SQLAlchemy 为每个子类调用它,因此每个子类都会得到属于自己的关系。
#
# 注意:这里的 [Client] 指的是诊所的患者,而不是
# HTTP 客户端!这是原始业务领域的词汇,原样
# 保留([clients] 表)。
#
# SQL 唯一性约束:unq_doctors_first_name_last_name、unq_clients_first_name_last_name
# (两个医生或两个客户不能有相同的名和
# 姓):由 SQL 脚本创建,在业务层中通过名称识别。
# =========================================================================
from sqlalchemy import ForeignKey, String
from sqlalchemy.orm import Mapped, declared_attr, mapped_column, relationship
from rdvmedecins.entities.base import WithIdAndVersion, Base
from rdvmedecins.entities.user import User
class Person(WithIdAndVersion):
title: Mapped[str] = mapped_column(String(5)) # Melle、Mme、Mr
last_name: Mapped[str] = mapped_column(String(20))
first_name: Mapped[str] = mapped_column(String(20))
# 指向 users(id) 的外键,读取为一个普通数字:这样无需加载 User
# 就能知道账户的 id。"user" 是该
# 列的名称(SQL 关键字,如果数据库管理系统需要,SQLAlchemy 会自己
# 用反引号 `user` 括起来);user_id 则是 Python 属性的名称
@declared_attr
def user_id(cls) -> Mapped[int]:
return mapped_column("user", ForeignKey("users.id"))
# -----------------------------------------------------------------------
# 与用户账户的关系:一个医生(一个客户)有一个
# 账户。relationship:[user] 属性是一个 User 对象,而不是
# 数字。SQLAlchemy 只在被要求时才从数据库读取它:在
# 查询中(joinedload 选项,见 repositories/),或者在第一次访问
# 该属性时,前提是会话仍处于打开状态。
# -----------------------------------------------------------------------
@declared_attr
def user(cls) -> Mapped[User]:
return relationship()
class Doctor(Person, Base):
__tablename__ = "doctors"
class Client(Person, Base):
__tablename__ = "clients"
|
- 第 27 行:由于 [doctors] 和 [clients] 表的列完全相同,因此它们在混入类 [Person] 中只描述一次,而该混入类本身继承自混入类 [WithIdAndVersion];
- 第 29–31 行:普通列,声明方式与示例 28 相同;
- 第 9–39 行:指向用户账户的外键 。在混入类中,充当外键的列必须使用 [@declared_attr] 方法来声明:这样每个子类都会得到自己的列。[ForeignKey("users.id")] 指定被引用的列;[mapped_column] 的第一个参数是该列在表中的名称([user]),它与 [Python] 属性的名称([user_id])不同;
- 第 37–50 行:指向账户的关系 :属性 [user] 是一个 [User] 对象,而不是一个数字。[SQLAlchemy] 会推断外键连接。关系不是列:它是获取关联对象的一种手段。默认情况下,[SQLAlchemy] 只在第一次访问该属性时才从数据库读取它(懒加载),这要求会话仍处于打开状态;
- 第 53–58 行:两个实体,它们只有表不同。
请注意术语:这里的 [Client] 指的是医疗诊所的患者 ,而不是 HTTP 客户端。这是原始应用程序中的术语,这里原样保留。
11.8.5. entities/slot.py
| # =========================================================================
# entities/slot.py
# -------------------------------------------------------------------------
# 医生的一个时间段([slots] 表):8:00 - 8:20,等等。
# =========================================================================
from sqlalchemy import ForeignKey
from sqlalchemy.orm import Mapped, mapped_column, relationship
from rdvmedecins.entities.base import WithIdAndVersion, Base
from rdvmedecins.entities.person import Doctor
class Slot(WithIdAndVersion, Base):
__tablename__ = "slots"
start_hour: Mapped[int] # 时段的开始小时
start_minute: Mapped[int] # 时段的开始分钟
end_hour: Mapped[int] # 时段的结束小时
end_minute: Mapped[int] # 时段的结束分钟
# 同一个医生有多个时间段:外键 [doctor_id]
# (一个数字),以及关系 [doctor](Doctor 对象)
doctor_id: Mapped[int] = mapped_column(ForeignKey("doctors.id"))
doctor: Mapped[Doctor] = relationship()
|
预约时间段及其医生:外键 [doctor_id] (一个数字)和关系 [doctor] (对象)。没有使用混入类,关系直接声明为属性。
11.8.6. entities/appointment.py
| # =========================================================================
# entities/appointment.py
# -------------------------------------------------------------------------
# 一个预约([appointments] 表):某个客户,在某个时间段,在某一天。
#
# SQL 唯一性约束:unq1_appointments (day, slot_id):一个时间段
# 每天只能被预订一次。由 SQL 脚本创建,在业务层中通过
# 名称识别。
# =========================================================================
from datetime import date
from sqlalchemy import ForeignKey
from sqlalchemy.orm import Mapped, mapped_column, relationship
from rdvmedecins.entities.base import WithIdAndVersion, Base
from rdvmedecins.entities.slot import Slot
from rdvmedecins.entities.person import Client
class Appointment(WithIdAndVersion, Base):
__tablename__ = "appointments"
# date:不带时间的日期,与 SQL 的 DATE 类型
# ([day] 列)完全对应
day: Mapped[date]
client_id: Mapped[int] = mapped_column(ForeignKey("clients.id"))
client: Mapped[Client] = relationship()
slot_id: Mapped[int] = mapped_column(ForeignKey("slots.id"))
slot: Mapped[Slot] = relationship()
|
- 第 25 行:[Python] 的 [date] 类型,即不含时间的日期,与 SQL 类型 [DATE] 完全对应;
- 第 27–31 行:两个外键及其关系。
11.8.7. entities/__init__.py
| # =========================================================================
# entities/ - 实体:dbrdvmedecins2 数据库的每张表对应一个类。
# 该文件汇集了各个导入:在应用的其他地方,"from rdvmedecins.entities import
# Doctor" 就足够了。
# =========================================================================
from rdvmedecins.entities.base import Base
from rdvmedecins.entities.slot import Slot
from rdvmedecins.entities.person import Client, Doctor, Person
from rdvmedecins.entities.role import Role
from rdvmedecins.entities.appointment import Appointment
from rdvmedecins.entities.user import User
__all__ = ["Base", "Client", "Slot", "Doctor", "Person", "Role", "Appointment", "User"]
|
包的 [__init__.py] 文件在导入该包时执行。这个文件从各自的模块导入实体;在其他地方,[from rdvmedecins.entities import Doctor] 就足够了,无需知道该类定义在哪个模块中。列表 [__all__] 声明包所公开的名称。
11.9. SQLAlchemy:会话与关系加载
示例 28 介绍了 [SQLAlchemy] 的基础知识。案例研究还用到了它的另外两个相互关联的方面。
所读取对象的生命周期。业务层中的每个方法都会打开一个会话和一个事务,并在退出时关闭它们(示例 28)。它返回的实体随后处于分离状态:它们不再与任何会话关联。得益于 [expire_on_commit=False] 设置,它们的普通属性仍然可以读取。但是,尚未加载的关系再也无法加载:这需要查询数据库,而此时已经没有会话了。此时访问该属性会抛出 [DetachedInstanceError] 异常。[Spring Boot] 搭配 [Hibernate],通过 [open-in-view] 设置(在请求期间保持会话打开)解决的正是这个问题,而案例研究的 [Spring MVC] 版本出于与我们相同的原因禁用了它:视图不应触发 SQL 请求。因此规则是:DAO 层的每个方法都要显式加载调用方将会需要的关系。
加载选项。[SQLAlchemy] 提供了几种在加载实体的同时加载关系的方式:
- [joinedload(Doctor.user)]:向查询添加一个连接 ([LEFT OUTER JOIN users ...]),并用其列来构造 [User] 对象。一次查询就返回医生及其账户;
- [contains_eager(Appointment.slot)]:当查询已经包含连接时([select(Appointment).join(Appointment.slot)],其目的是对被连接表中的列进行过滤),此选项指示 [SQLAlchemy] 使用该连接中的列来填充关系,而不是再添加第二个连接;
- 这些选项可以链接起来,以便通过另一个关系来加载关系:[contains_eager(Appointment.slot).joinedload(Slot.doctor)] 会加载每个预约的时间段,然后加载每个时间段的医生。
它们相当于 [JPA] 的 [JOIN FETCH] 以及 [Entity Framework Core] 的 [Include]。
11.10. 领域:日历
11.10.1. domain/schedule.py
| # =========================================================================
# domain/schedule.py
# -------------------------------------------------------------------------
# 计算得出的 "业务" 对象,不对应任何表:
# - DoctorDaySlot:一个时间段,以及在某一天
# 可能预订在该时间段上的预约(时间段空闲时为 None);
# - DoctorDaySchedule:医生在某一天的完整日程,
# 即其时间段的列表,每个时间段要么空闲要么已预订。由
# BusinessService.get_doctor_day_schedule 计算,并由
# controllers/schedule.py 转换为 HTML 表格。
#
# frozen=True:不可变对象,其字段由构造函数一次性
# 设定好:这正是
# 计算得出的对象所需要的,之后没有人会修改它。
# =========================================================================
from dataclasses import dataclass
from datetime import date
from rdvmedecins.entities import Slot, Doctor, Appointment
@dataclass(frozen=True)
class DoctorDaySlot:
slot: Slot
appointment: Appointment | None
@dataclass(frozen=True)
class DoctorDaySchedule:
doctor: Doctor
day: date
doctor_day_slots: list[DoctorDaySlot]
|
两个不对应任何表的类:医生一天的日程,由业务层计算得出。[DoctorDaySlot] 将一个时间段与当天为该时间段预约的预约关联起来,如果该时间段可用,则关联 [None] ;[DoctorDaySchedule] 把医生、日期以及该医生的时间段列表组合在一起。它们是不可变的 [dataclass] 对象([frozen=True]):一个事后无人修改的计算所得对象。
11.11. DAO 层
[repositories] 文件夹(DAO 类的通用英文名称为“repositories”)为每个实体包含一个类。与示例 28 一样,每个方法都接收由业务层打开的会话,并且不包含业务逻辑。
11.11.1. repositories/person_repository.py
| # =========================================================================
# repositories/person_repository.py
# -------------------------------------------------------------------------
# 医生和客户共用的 DAO 层。
#
# 每个方法都接收由业务层打开的 SQLAlchemy 会话(SESSION)
# (见 business/service.py):同一操作的所有查询
# 因而使用同一个连接和同一个事务。
#
# 查询使用 SQLAlchemy 对象(select、where、
# order_by……)编写,它们作用于类及其属性;SQLAlchemy
# 将其翻译为 SQL。各个值(first_name、last_name……)成为查询的参数:
# 没有字符串拼接,因此不存在 SQL 注入。
#
# 医生和客户的 DAO 本应完全相同:这个
# 泛型类只需写一次。[T: Person]:类型参数,
# 它是 Doctor 或 Client;self.entity 是对应的类。
# =========================================================================
from sqlalchemy import delete, select
from sqlalchemy.orm import Session, joinedload
from rdvmedecins.entities import Person
class PersonRepository[T: Person]:
def __init__(self, entity: type[T]):
self.entity = entity
# 按姓再按名排序的列表,包含用户账户。
# joinedload(user):通过连接同时带回账户
# (SELECT ... FROM doctors LEFT OUTER JOIN users ...)。没有它,
# 账户就只能在第一次访问时读取:会话关闭后就无法读取了
# 这些列表由缓存保存在内存中
# (web/application_model.py),远在请求结束之后。
def list(self, session: Session) -> list[T]:
e = self.entity
query = select(e).options(joinedload(e.user)).order_by(e.last_name, e.first_name)
return list(session.scalars(query))
# 一个人员及其账户;如果不存在则为 None
def read(self, session: Session, id: int) -> T | None:
return session.get(self.entity, id, options=[joinedload(self.entity.user)])
# 用户账户为 [user_id] 的人员
def read_by_user(self, session: Session, user_id: int) -> T | None:
e = self.entity
query = select(e).options(joinedload(e.user)).where(e.user_id == user_id)
return session.scalars(query).first()
# 具有这个名和姓的人员(如果有的话)。比较
# 由 MySQL 完成,因此使用数据库的排序规则
# (utf8mb4_unicode_ci:不区分大小写和重音):
# 与 SQL 唯一性约束的规则完全相同。
def namesake(self, session: Session, first_name: str, last_name: str) -> T | None:
e = self.entity
return session.scalars(select(e).where(e.first_name == first_name, e.last_name == last_name).limit(1)).first()
def add(self, session: Session, person: T) -> T:
session.add(person)
return person
# 直接发送给数据库的 DELETE,不先读取该人员
def remove(self, session: Session, id: int):
session.execute(delete(self.entity).where(self.entity.id == id))
|
- 第 25 行:一个泛型类,使用 [Python] 3.12 的语法(PEP 695)编写。[T] 是一个类型参数:该类将以 [PersonRepository[Doctor]] 或 [PersonRepository[Client]] 的形式使用。[T: Person] 将 [T] 限制为继承自 [Person] 的类。类型在运行时不会被 [Python] 检查(示例 06):它们为代码提供文档,并让编辑器知道,对于医生的 DAO,[list()] 返回的是 [Doctor] 的列表。在 [Python] 3.12 之前,人们会这样写:[T = TypeVar("T", bound=Person)] ,然后是 [class PersonRepository(Generic[T])];
- 第 27–28 行:类型参数在运行时并不存在:因此,实际的类([Doctor] 或 [Client])被传递给构造函数,并存储在 [self.entity] 中。[type[T]] 是某个类 (而不是对象)的类型;
- 第 36–39 行:已排序的列表,包含每个人员的计数,通过连接([joinedload])加载。这在这里至关重要:这些列表由缓存 [ApplicationModel] 保存在内存中,远远晚于会话结束的时间;
- 第 42–43 行:按主键读取也接受加载选项;
- 第 46–49 行:与某个账户关联的人员——我们据此识别登录的客户;
- 第 55–57 行:查找同名者。比较由 [MySQL] 使用数据库的排序规则执行:这恰好就是唯一性约束的规则;
- 第 59–61 行:添加,不带 [flush]:由业务层决定何时发送 SQL 命令;
- 第 64–65 行:直接发送到数据库的 [DELETE] 。
11.11.2. repositories/doctor_repository.py
| # =========================================================================
# repositories/doctor_repository.py
# -------------------------------------------------------------------------
# 医生的 DAO:一切都继承自 PersonRepository。
# =========================================================================
from rdvmedecins.entities import Doctor
from rdvmedecins.repositories.person_repository import PersonRepository
class DoctorRepository(PersonRepository[Doctor]):
def __init__(self):
super().__init__(Doctor)
|
医生的 DAO 类继承自 [PersonRepository[Doctor]] ,并把 [Doctor] 类传递给其父类的构造函数;其余的一切都是继承来的。
11.11.3. repositories/client_repository.py
| # =========================================================================
# repositories/client_repository.py
# -------------------------------------------------------------------------
# 客户的 DAO:即人员的 DAO,外加一个加锁的方法。
# =========================================================================
from sqlalchemy import select
from sqlalchemy.orm import Session
from rdvmedecins.entities import Client
from rdvmedecins.repositories.person_repository import PersonRepository
class ClientRepository(PersonRepository[Client]):
def __init__(self):
super().__init__(Client)
# -----------------------------------------------------------------------
# 在客户的那一行上加锁,直到当前
# 事务结束(SELECT ... FOR UPDATE),并返回其 id(如果
# 客户不存在则返回 None)。请求同一把
# 锁的第二个事务会等待,直到第一个事务结束。
# 用于预订预约(见 BusinessService.add_appointment):
# 同一患者的两次同时预订因此会
# 一个接一个地处理,第二个会看到第一个创建的预约。
# with_for_update:在查询中添加 "FOR UPDATE"。
# -----------------------------------------------------------------------
def lock(self, session: Session, id: int) -> int | None:
return session.scalars(select(Client.id).where(Client.id == id).with_for_update()).first()
|
- 第 28–29 行:多了一个方法,它在客户的记录上放置一把锁 :[with_for_update()] 会在查询中添加 [FOR UPDATE] ([SELECT clients.id FROM clients WHERE clients.id = ? FOR UPDATE])。在事务结束之前,任何请求同一把锁的其他事务都会等待。业务层在安排预约时使用它:因此,针对同一患者的两个同时发生的预约会一个接着一个地处理,第二个预约能看到第一个创建的预约(规则:每位患者只能有一个未来的预约)。这种悲观锁 是对乐观锁的补充:乐观锁检测某一行的并发修改,而悲观锁则防止两个事务同时基于相同的数据做出决定。
11.11.4. repositories/slot_repository.py
| # =========================================================================
# repositories/slot_repository.py
# -------------------------------------------------------------------------
# [Slot] 实体的 DAO 层。
# =========================================================================
from sqlalchemy import delete, select
from sqlalchemy.orm import Session, joinedload
from rdvmedecins.entities import Slot
class SlotRepository:
# 一个时间段及其医生
def read(self, session: Session, id: int) -> Slot | None:
return session.get(Slot, id, options=[joinedload(Slot.doctor)])
# 某个医生的时间段,按时间顺序排列
def list_by_doctor(self, session: Session, doctor_id: int) -> list[Slot]:
query = (select(Slot).where(Slot.doctor_id == doctor_id)
.order_by(Slot.start_hour, Slot.start_minute))
return list(session.scalars(query))
# 删除某个医生的所有时间段(删除医生时):
# DELETE FROM slots WHERE doctor_id = ?
def delete_by_doctor(self, session: Session, doctor_id: int):
session.execute(delete(Slot).where(Slot.doctor_id == doctor_id))
|
一个预约时间段(带医生)、某位医生按时间顺序排列的预约时间段,以及医生的预约时间段的删除(当医生被删除时)。
11.11.5. repositories/appointment_repository.py
| # =========================================================================
# repositories/appointment_repository.py
# -------------------------------------------------------------------------
# [Appointment] 实体的 DAO 层。
#
# join(Appointment.slot):SQL 连接,根据两个类之间的关系(RELATIONSHIP)
# 编写(SQLAlchemy 知道外键)。contains_eager:
# 被连接的表的列同时也用来填充该关系
# (appointment.slot),无需再发起新的查询。
# =========================================================================
from datetime import date
from sqlalchemy import delete, func, select
from sqlalchemy.orm import Session, contains_eager, joinedload
from rdvmedecins.entities import Slot, Appointment
class AppointmentRepository:
# 一个预约、它的客户和它的时间段
def read(self, session: Session, id: int) -> Appointment | None:
return session.get(Appointment, id, options=[joinedload(Appointment.client), joinedload(Appointment.slot)])
# 某个医生在某一天的预约,包含客户和时间段。
# [appointments] 表不直接引用医生:我们通过时间段来关联。
def doctor_day_appointments(self, session: Session, doctor_id: int, day: date) -> list[Appointment]:
query = (select(Appointment).join(Appointment.slot)
.options(contains_eager(Appointment.slot), joinedload(Appointment.client))
.where(Slot.doctor_id == doctor_id, Appointment.day == day))
return list(session.scalars(query))
# 某个客户从 [since] 这一天(含)起的预约,
# 按时间顺序排列,包含时间段及该时间段所属的医生
def client_upcoming_appointments(self, session: Session, client_id: int, since: date) -> list[Appointment]:
query = (select(Appointment).join(Appointment.slot)
.options(contains_eager(Appointment.slot).joinedload(Slot.doctor))
.where(Appointment.client_id == client_id, Appointment.day >= since)
.order_by(Appointment.day, Slot.start_hour, Slot.start_minute))
return list(session.scalars(query))
# 某个客户从 [since] 这一天(含)起的预约数量
def count_client_upcoming(self, session: Session, client_id: int, since: date) -> int:
query = select(func.count(Appointment.id)).where(Appointment.client_id == client_id, Appointment.day >= since)
return session.scalar(query)
# 某个医生的预约数量(过去的或未来的)
def count_by_doctor(self, session: Session, doctor_id: int) -> int:
query = select(func.count(Appointment.id)).join(Appointment.slot).where(Slot.doctor_id == doctor_id)
return session.scalar(query)
def add(self, session: Session, appointment: Appointment) -> Appointment:
session.add(appointment)
return appointment
# 删除一个预约:DELETE FROM appointments WHERE id = ?
def remove(self, session: Session, id: int):
session.execute(delete(Appointment).where(Appointment.id == id))
# 删除某个客户的所有预约(过去的和未来的)
def delete_by_client(self, session: Session, client_id: int):
session.execute(delete(Appointment).where(Appointment.client_id == client_id))
|
- 第 27–31 行:某位医生在指定日期的预约。表 [appointments] 不直接引用医生:它要通过预约时间段。[join(Appointment.slot)] 根据关系来书写连接;过滤条件作用于被连接表中的列([Slot.doctor_id])。[contains_eager] 复用该连接来填充 [appointment.slot];[joinedload] 加载客户:日程通过一条 SQL 查询构建出来;
- 第 35–39 行:某位客户未来的预约,包含其时间段以及分配给每个时间段的医生;
- 第 43–45 行:[func.count] 生成 SQL 函数 [COUNT],而 [session.scalar] (单数形式);[session.scalar] 返回第一行的第一列:即计数;
- 第 48–50 行:某位医生的预约数量,用于判断该医生能否被删除;
- 第 61–62 行:删除某位客户的预约(当该客户被删除时)。
11.11.6. repositories/user_repository.py
| # =========================================================================
# repositories/user_repository.py
# -------------------------------------------------------------------------
# [User] 实体的 DAO 层。创建(或删除)医生或
# 客户时,也会创建(或删除)其账户:见 business/service.py。
# =========================================================================
from sqlalchemy import delete, select
from sqlalchemy.orm import Session
from rdvmedecins.entities import User
class UserRepository:
# 如果没有用户使用该登录名则为 None
def read_by_login(self, session: Session, login: str) -> User | None:
return session.scalars(select(User).where(User.login == login)).first()
def add(self, session: Session, user: User) -> User:
session.add(user)
return user
def remove(self, session: Session, id: int):
session.execute(delete(User).where(User.id == id))
|
按登录名读取用户(用于登录),以及添加和删除账户。
11.12. 业务层
[business] 文件夹包含业务规则,而且只包含这些规则。它不了解 [Flask]、HTML 或 HTTP 请求:它可以原样用于命令行应用程序或 API。
11.12.1. business/dates.py
| # =========================================================================
# business/dates.py
# -------------------------------------------------------------------------
# 今天的日期。它被业务规则使用(不得在过去
# 预订,每位患者只能有一个即将到来的预约):因此它位于
# 业务层。Web 层复用它。
# =========================================================================
from datetime import date
# 今天的日期,使用服务器的时区
def today() -> date:
return date.today()
|
当前日期用于两条业务规则(不得预约过去的时间,每位患者只能有一个未来的预约):它属于业务层。把它隔离在一个函数中还有另一个好处:自动化测试可以用固定日期来替换它。
11.12.2. business/exception.py
| # =========================================================================
# business/exception.py
# -------------------------------------------------------------------------
# 当违反业务规则(登录名已被占用、医生仍有预约、时间段
# 已被预订……)时,由业务层抛出的异常。它不携带文本,而是携带
# 翻译键(例如:"ERRORS.LOGIN_TAKEN"):由 Web 层
# 在显示页面时将其翻译为
# 法语或英语(见 i18n/fr.json、i18n/en.json)。
# BusinessException 不是异常状况:它是一种正常的
#
# 响应("该登录名已被占用"),会显示给用户。任何其他
# 异常才是真正的异常状况,最终会落到 500 错误页面。
# 消息的翻译键
# =========================================================================
class BusinessException(Exception):
def __init__(self, key: str, params: dict[str, str] | None = None):
super().__init__(key)
# 消息的可能参数({minutes}……)
self.key = key
# business/person_data.py
self.params = params or {}
|
业务层的异常不像示例 28 那样携带文本,而是携带一个翻译键 ([ERRORS.LOGIN_TAKEN])和若干参数:业务层并不知道用户正在以哪种语言查看页面。Web 层将翻译该键。[super().__init__(key)] 把键传递给 [Exception] 类的构造函数:如果记录该异常的日志,显示的就是这个值。
[BusinessException] 不是错误:它是一种正常的响应(“此用户名已被占用”),会显示给用户。任何其他异常才是真正的错误,会导致 500 错误页面。
11.12.3. business/person_data.py
| # =========================================================================
# "医生" 或 "客户" 表单中键入的数据,
# -------------------------------------------------------------------------
# 即 Web 层传递给业务层的形式。
# 创建时:可选(None),默认为小写的姓
# =========================================================================
from dataclasses import dataclass
@dataclass(frozen=True)
class PersonData:
title: str # Mr、Mme、Melle
last_name: str
first_name: str
# 编辑时:可选,如果缺失则登录名保持不变
# 创建时:可选,默认为登录名
login: str | None = None
# 编辑时:可选,如果缺失则密码保持不变
# 编辑时:显示表单时该记录的
password: str | None = None
# 版本号
# (乐观锁,见 entities/base.py)
version: int | None = None
|
来自“医生”或“客户”表单的数据,由 Web 层传递(示例 28)。登录名、密码和版本是可选的:注释解释了它们在创建和修改时缺失意味着什么。
11.12.4. business/business.py
| # =========================================================================
# business/business.py
# -------------------------------------------------------------------------
# 业务层的契约:读取、日程、预约、医生
# 和客户的管理。
#
# Protocol 描述对象必须具有的方法,而不说明
# 它们如何编写(相当于接口)。BusinessService(业务层)和
# ApplicationModel(Web 层的缓存)都
# 遵守它。Python 在运行时不做任何检查:是
# 分析工具(例如 VS Code 的)会报告不一致之处。
#
# T | None:可能缺失的结果(不存在的医生……)。
# =========================================================================
from datetime import date
from typing import Protocol
from rdvmedecins.domain.schedule import DoctorDaySchedule
from rdvmedecins.entities import Client, Slot, Doctor, Appointment
from rdvmedecins.business.person_data import PersonData
class Business(Protocol):
# 读取
def get_all_clients(self) -> list[Client]: ...
def get_all_doctors(self) -> list[Doctor]: ...
def get_all_slots(self, doctor_id: int) -> list[Slot]: ...
def get_doctor_day_appointments(self, doctor_id: int, day: date) -> list[Appointment]: ...
def get_client_by_id(self, id: int) -> Client | None: ...
def get_doctor_by_id(self, id: int) -> Doctor | None: ...
def get_appointment_by_id(self, id: int) -> Appointment | None: ...
def get_slot_by_id(self, id: int) -> Slot | None: ...
def get_doctor_day_schedule(self, doctor_id: int, day: date) -> DoctorDaySchedule | None: ...
# 用户账户为 [user_id] 的客户(患者)
def get_client_by_user_id(self, user_id: int) -> Client | None: ...
# 某个客户今天或未来的预约,包含时间段和医生
def get_client_upcoming_appointments(self, client_id: int) -> list[Appointment]: ...
# 预约(ADMIN、DOCTOR、USER)
# 在以下情况下抛出 BusinessException:
# - 日期已过去("ERRORS.PAST_DATE");
# - 患者已有一个即将到来的预约("ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT");
# - 该时间段在当天已被占用("ERRORS.SLOT_ALREADY_BOOKED")。
def add_appointment(self, day: date, slot: Slot, client: Client) -> Appointment: ...
def delete_appointment(self, appointment: Appointment) -> None: ...
# 医生(ADMIN)
# 创建医生及其用户账户(DOCTOR 角色)
def add_doctor(self, data: PersonData) -> Doctor: ...
# 编辑医生及其用户账户
def edit_doctor(self, id: int, data: PersonData) -> Doctor: ...
# 删除医生、其时间段及其账户:如果有预约则拒绝
def delete_doctor(self, id: int) -> None: ...
# 客户
# (由 ADMIN 执行;add_client 也用于患者的注册,
# edit_client 和 delete_client 由患者对自己的账户使用)
# 创建客户及其用户账户(USER 角色)
def add_client(self, data: PersonData) -> Client: ...
def edit_client(self, id: int, data: PersonData) -> Client: ...
# 删除客户、其账户及其所有预约(过去的和未来的)
def delete_client(self, id: int) -> None: ...
|
- 第 23 行:业务层的契约:其方法的列表,以及它们的参数和返回值。[Protocol] (标准模块 [typing])是 [Python] 中相当于接口的东西:它描述对象必须具有的方法,而不规定这些方法如何实现。只要一个类具有这些方法,它就符合该协议,而无需显式声明(这称为结构化类型,或*鸭子类型*:“如果它走起来像鸭子……”)。有两个类符合它:[BusinessService],即业务层,以及 [ApplicationModel],即 Web 层的缓存(稍后讨论)。[Python] 在运行时不会检查任何东西:是分析工具(例如 [Visual Studio Code] 中的那个)来标记不一致之处;
- 第 26 行:协议方法的方法体简化为 [...] ([Ellipsis] 对象,属于 [Python],它什么也不做);
- 第 55–78 行:注释说明了每个方法的业务逻辑和错误代码。
11.12.5. business/service.py
业务层的实现。这是应用程序中最重要的文件。
| # =========================================================================
# business/service.py
# -------------------------------------------------------------------------
# 业务层的实现。
#
# 医生和客户的管理遵循三条业务规则:
#
# 1. 一个人员(医生或客户)及其用户账户始终
# 同生共灭:它们在同一个事务中一起创建、编辑和
# 删除:要么全部成功,要么什么都不写入;
# 2. 登录名在整个应用中唯一,并且两个医生(或
# 两个客户)不能有相同的名和姓;
# 3. 删除:
# - 有预约的医生不能被删除(其
# 患者会在毫不知情的情况下失去预约):必须
# 先取消这些预约。其时间段随医生一起消失;
# - 而客户则连同其所有预约(过去的和
# 未来的)一起消失:无论删除是来自 ADMIN 还是来自
# 患者本人。
#
# 此外还有两条预订预约的规则,无论
# 预订者的角色是什么(ADMIN、DOCTOR 或患者本人):
# 4. 不得在过去预约;
# 5. 每位患者同一时间只能有一个即将到来的预约。
#
# 医生和客户遵循完全相同的规则:公共代码
# 只编写一次(私有方法 _xxx_person),并由一个
# 小的 "描述符" 参数化,它说明我们处理的是哪种类型的人员。
#
# 事务由 _transaction 方法(位于文件末尾)打开,
# 该方法还会把数据库在 SQL 语句发送给它时报告的
# 错误翻译为 BusinessException。
# =========================================================================
import re
from collections.abc import Callable
from dataclasses import dataclass
from datetime import date
from sqlalchemy.exc import IntegrityError
from sqlalchemy.orm import Session, sessionmaker
from sqlalchemy.orm.exc import StaleDataError
from rdvmedecins.auth.passwords import hash_password
from rdvmedecins.domain.schedule import DoctorDaySchedule, DoctorDaySlot
from rdvmedecins.entities import Client, Slot, Doctor, Person, Role, Appointment, User
from rdvmedecins.business import dates
from rdvmedecins.business.person_data import PersonData
from rdvmedecins.business.exception import BusinessException
from rdvmedecins.repositories.client_repository import ClientRepository
from rdvmedecins.repositories.slot_repository import SlotRepository
from rdvmedecins.repositories.doctor_repository import DoctorRepository
from rdvmedecins.repositories.person_repository import PersonRepository
from rdvmedecins.repositories.appointment_repository import AppointmentRepository
from rdvmedecins.repositories.user_repository import UserRepository
# 业务规则中区分医生和客户的一切内容
@dataclass(frozen=True)
class Descriptor:
dao: PersonRepository
factory: type[Person] # Doctor 或 Client
role: Role # DOCTOR 或 USER
not_found_key: str # 人员不存在时的消息
already_exists_key: str # 相同的名和姓已存在时的消息
# 可选(None):如果提供,只要该人员有预约
# (count_appointments > 0),删除就会被拒绝,并附带消息 has_appointments_key
count_appointments: Callable[[Session, int], int] | None
has_appointments_key: str | None
# 可选:必须在该人员之前删除的内容(通过外键
# 引用它的那些行)
before_delete: Callable[[Session, int], None] | None
# -----------------------------------------------------------------------
# 数据库错误 -> BusinessException
#
# 当 UNIQUE 约束拒绝一次写入时,SQLAlchemy 会抛出
# IntegrityError,其 [orig] 属性是原始错误,即
# PyMySQL 驱动的错误。其消息会引用约束的名称:
# Duplicate entry 'Marie-PELISSIER' for key 'doctors.unq_doctors_first_name_last_name'
# (MySQL 8 会在名称前加上表名,MariaDB 则不会)。这就是
# SQL 脚本为其所有约束命名的原因。
# -----------------------------------------------------------------------
CONSTRAINT_MESSAGES = {
"unq_users_login": "ERRORS.LOGIN_TAKEN",
"unq_doctors_first_name_last_name": "ERRORS.DOCTOR_ALREADY_EXISTS",
"unq_clients_first_name_last_name": "ERRORS.PATIENT_ALREADY_EXISTS",
"unq1_appointments": "ERRORS.SLOT_ALREADY_BOOKED",
}
CONSTRAINT = re.compile(r"for key '(?:[^'.]*\.)?([^']+)'")
class BusinessService:
# 所有依赖都由应用工厂提供
# (见 rdvmedecins/__init__.py):这是 "手工" 进行的
# 依赖注入。sessions:SQLAlchemy 会话的工厂。
def __init__(self, sessions: sessionmaker, doctors: DoctorRepository,
clients: ClientRepository, slots: SlotRepository, appointments: AppointmentRepository,
users: UserRepository):
self._sessions = sessions
self._doctors = doctors
self._clients = clients
self._slots = slots
self._appointments = appointments
self._users = users
self._doctor = Descriptor(
dao=doctors, factory=Doctor, role=Role.DOCTOR,
not_found_key="ERRORS.DOCTOR_NOT_FOUND",
already_exists_key="ERRORS.DOCTOR_ALREADY_EXISTS",
count_appointments=appointments.count_by_doctor,
has_appointments_key="ERRORS.DOCTOR_HAS_APPOINTMENTS",
# 没有预约的医生仍可能有时间段:
# 没有医生,这些时间段就没有意义,因此随医生一起删除(否则
# 外键 slots.doctor_id 会禁止删除)
before_delete=slots.delete_by_doctor)
self._client = Descriptor(
dao=clients, factory=Client, role=Role.USER,
not_found_key="ERRORS.PATIENT_NOT_FOUND",
already_exists_key="ERRORS.PATIENT_ALREADY_EXISTS",
# 没有 count_appointments:客户的删除永远不会被拒绝;
# 其预约(过去的和未来的)随客户一起删除(否则
# 外键 appointments.client_id 会禁止删除)
count_appointments=None, has_appointments_key=None,
before_delete=appointments.delete_by_client)
# =======================================================================
# 读取:在读取期间使用一个会话;读取的对象之后
# 仍可使用(expire_on_commit=False,见 rdvmedecins/__init__.py)
# =======================================================================
def _read[R](self, work: Callable[[Session], R]) -> R:
with self._sessions() as session:
return work(session)
def get_all_clients(self) -> list[Client]:
return self._read(self._clients.list)
def get_all_doctors(self) -> list[Doctor]:
return self._read(self._doctors.list)
def get_all_slots(self, doctor_id: int) -> list[Slot]:
return self._read(lambda s: self._slots.list_by_doctor(s, doctor_id))
def get_doctor_day_appointments(self, doctor_id: int, day: date) -> list[Appointment]:
return self._read(lambda s: self._appointments.doctor_day_appointments(s, doctor_id, day))
def get_client_by_id(self, id: int) -> Client | None:
return self._read(lambda s: self._clients.read(s, id))
def get_doctor_by_id(self, id: int) -> Doctor | None:
return self._read(lambda s: self._doctors.read(s, id))
def get_appointment_by_id(self, id: int) -> Appointment | None:
return self._read(lambda s: self._appointments.read(s, id))
def get_slot_by_id(self, id: int) -> Slot | None:
return self._read(lambda s: self._slots.read(s, id))
def get_client_by_user_id(self, user_id: int) -> Client | None:
return self._read(lambda s: self._clients.read_by_user(s, user_id))
def get_client_upcoming_appointments(self, client_id: int) -> list[Appointment]:
return self._read(lambda s: self._appointments.client_upcoming_appointments(s, client_id, dates.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
time_slots = self.get_all_slots(doctor_id)
# 时间段编号 -> 预订在该时间段上的预约(字典推导式)
bookings = {a.slot_id: a for a in self.get_doctor_day_appointments(doctor_id, day)}
doctor_day_slots = [DoctorDaySlot(slot, bookings.get(slot.id))
for slot in time_slots]
return DoctorDaySchedule(doctor, day, doctor_day_slots)
# =======================================================================
# 预约
# =======================================================================
# -----------------------------------------------------------------------
# 在一个事务中预订预约:
# 1. 不得在过去预约;
# 2. 患者所在的行被锁定(SELECT ... FOR UPDATE):如果
# 同一患者在同一时刻预订两个时间段(两个标签页、
# 双击……),第二个事务会等待
# 第一个事务结束,然后看到它刚刚创建的预约;
# 3. 每位患者只能有一个即将到来的预约;
# 4. 最后是插入。如果该时间段刚刚被另一位
# 患者占用,则由 SQL 约束 unq1_appointments (day, slot_id)
# 拒绝插入,并由 _transaction 翻译为 BusinessException。
# -----------------------------------------------------------------------
def add_appointment(self, day: date, slot: Slot, client: Client) -> Appointment:
def work(session: Session) -> Appointment:
today = dates.today()
if day < today:
raise BusinessException("ERRORS.PAST_DATE")
patient_id = self._clients.lock(session, client.id)
if patient_id is None:
raise BusinessException("ERRORS.PATIENT_NOT_FOUND")
if self._appointments.count_client_upcoming(session, patient_id, today) > 0:
raise BusinessException("ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT")
# 知道时间段和患者的 id 就足以编写
# 外键:无需在会话中再次读取这些对象
return self._appointments.add(session, Appointment(day=day, slot_id=slot.id,
client_id=patient_id))
return self._transaction(work)
def delete_appointment(self, appointment: Appointment) -> None:
self._transaction(lambda session: self._appointments.remove(session, 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)
# -----------------------------------------------------------------------
# 创建:用户账户和人员,在同一个事务中。
# -----------------------------------------------------------------------
def _add_person(self, d: Descriptor, data: PersonData):
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(session: Session):
self._check_person_unique(session, d, first_name, last_name, None)
self._check_login_free(session, login)
user = User(login=login, password=hash_password(password), name=f"{first_name} {last_name}", role=d.role)
person = d.factory(title=data.title, last_name=last_name, first_name=first_name, user=user)
# 人员引用其账户:SQLAlchemy 先插入
# 账户(以获得其 id),再插入人员
d.dao.add(session, person)
# flush:INSERT 立即发出(而不是在 COMMIT 时);
# 因此违反的约束会在这里抛出其错误
session.flush()
return person
return self._transaction(work)
# -----------------------------------------------------------------------
# 编辑:人员及其账户(显示的名称 "名 姓"
# 必须随之更新;登录名和密码只有在
# 键入了新值时才会改变)。
# -----------------------------------------------------------------------
def _edit_person(self, d: Descriptor, id: int, data: PersonData):
def work(session: Session):
person = d.dao.read(session, id)
if person is None:
raise BusinessException(d.not_found_key)
# 乐观锁:如果数据库中的版本号不再是
# 表单中的版本号,说明在此期间有人编辑过这条记录:我们拒绝,
# 而不是悄悄覆盖他们的修改。
# (如果并发的编辑发生在这次读取之后,则由
# UPDATE 的 "WHERE version = ..." 子句检测到它。)
if data.version is not None and data.version != person.version:
raise BusinessException("ERRORS.CONCURRENT_UPDATE")
last_name = data.last_name.strip().upper()
first_name = data.first_name.strip()
self._check_person_unique(session, d, first_name, last_name, id)
# 我们只是修改这些对象:它们被会话
# "跟踪",会话会自己发送所需的 UPDATE
person.title = data.title
person.last_name = last_name
person.first_name = first_name
user = person.user
user.name = f"{first_name} {last_name}"
if data.login and data.login.lower() != user.login:
login = data.login.lower()
self._check_login_free(session, login)
user.login = login
if data.password:
user.password = hash_password(data.password)
session.flush()
return person
return self._transaction(work)
# -----------------------------------------------------------------------
# 删除,在一个事务中,按外键
# 所要求的顺序:
# 1. 如果仍有预约则可能拒绝(医生);
# 2. 引用该人员的内容(医生的时间段、
# 客户的预约);
# 3. 人员本身(它引用其账户);
# 4. 其账户。
# -----------------------------------------------------------------------
def _delete_person(self, d: Descriptor, id: int) -> None:
def work(session: Session):
person = d.dao.read(session, id)
if person is None:
raise BusinessException(d.not_found_key)
if d.count_appointments is not None and d.count_appointments(session, id) > 0:
raise BusinessException(d.has_appointments_key)
if d.before_delete is not None:
d.before_delete(session, id)
d.dao.remove(session, id)
self._users.remove(session, person.user_id)
self._transaction(work)
# 拒绝同一类型的另一个人员已使用的名和姓
# (current_id:正在编辑的人员,他显然
# 有权保留自己的名和姓;创建时为 None)
@staticmethod
def _check_person_unique(session: Session, d: Descriptor, first_name: str, last_name: str,
current_id: int | None):
namesake = d.dao.namesake(session, first_name, last_name)
if namesake is not None and namesake.id != current_id:
raise BusinessException(d.already_exists_key)
def _check_login_free(self, session: Session, login: str):
if self._users.read_by_login(session, login) is not None:
raise BusinessException("ERRORS.LOGIN_TAKEN")
# -----------------------------------------------------------------------
# 在一个事务中运行 [work]:
# sessions.begin() -> 一个会话及其事务(START TRANSACTION);
# 离开 with 块时:如果一切顺利则 COMMIT;如果有
# 异常离开(包括 BusinessException),则 ROLLBACK:什么都不会写入。
#
# "登录名空闲" 和 "名加姓唯一" 的检查在
# 写入之前进行,以给出清晰的消息。但两个 ADMIN 可能
# 在同一时刻保存相同的登录名(或同一个医生):在这种
# 罕见情况下,由 SQL 唯一性约束拒绝第二次
# 写入。因此数据库错误在事务外围被拦截,
# 以便翻译为同一个 BusinessException:
# - StaleDataError:UPDATE "WHERE id = ... AND version = ..."
# 没有修改任何行(乐观锁);
# - IntegrityError:数据库的某个约束拒绝了写入。
# 任何其他错误都是真正的异常状况:放行不处理。
# -----------------------------------------------------------------------
def _transaction[R](self, work: Callable[[Session], R]) -> R:
try:
with self._sessions.begin() as session:
return work(session)
except StaleDataError:
raise BusinessException("ERRORS.CONCURRENT_UPDATE")
except IntegrityError as e:
match = CONSTRAINT.search(str(e.orig))
if match and match.group(1) in CONSTRAINT_MESSAGES:
raise BusinessException(CONSTRAINT_MESSAGES[match.group(1)])
raise
|
11.12.5.1. 描述符
医生和客户遵循完全相同的业务规则,只有少数细微差别:DAO 不同、其账户的角色不同、错误消息不同,以及删除规则不同。与其把每个方法写两遍,不如把公共代码只写一次(方法 [_add_person]、[_edit_person]、[_delete_person]),并通过一个描述符 来配置,由它指明正在处理哪种类型的人员:
- 第 59–71 行:描述符是一个不可变的 [dataclass]。它的三个字段是函数:[Callable[[Session, int], int]] 是这样一种函数的类型:接收一个会话和一个整数,并返回一个整数。[count_appointments] 统计某个人员的预约数量(用于阻止删除已有预约的医生);[before_delete] 删除对该人员的引用(医生的时间段、客户的预约);
- 第 109–118 行:医生的描述符。[appointments.count_by_doctor] 是与对象 [appointments] 相关联的方法 (示例 22):这是一个将接收会话和 ID 的函数;
- 第 120–128 行:客户的描述符:不拒绝删除([count_appointments=None]),但会先删除其所有预约。
11.12.5.2. 读取操作与日程
- 第 135–137 行:读取操作由一个小型通用方法处理:[R] 是结果类型,与函数 [work] 的结果类型相同。会话由 [self._sessions()] 打开(不带 [begin]),在函数执行期间保持打开,然后由 [with] 块关闭。[SQLAlchemy] 仍会在第一次请求时启动一个事务([BEGIN (implicit)] 出现在控制台中);由于没有写入任何内容,关闭会话即取消该事务([ROLLBACK]):这些就是应用程序启动时控制台显示的行;
- 第 139–167 行:每个读取操作都会指示 [_read] 去调用相应的 DAO 方法。当 DAO 方法除会话之外还有其他参数时,由一个匿名函数 ([lambda s: ...])来提供这些参数;
- 第 171–180 行:医生某一天的日程。当天的预约存放在一个字典 ([{key: value for ...}])中,该字典将每个时间段编号与其对应的预约关联起来;然后每个时间段都与其预约关联,或与 [None] ([bookings.get(slot.id)])关联。三次读取,分属三个会话:它们之间的任何不一致(两次读取之间有人预约了)都无关紧要,因为日程只是用于显示。
11.12.5.3. 预约
- 第 198–213 行:该方法定义了一个内部函数 [work],其中包含要在事务中执行的操作,并把它传给方法 [_transaction] (见下文)。按顺序检查的规则如下:- 不允许预约过去的日期([day < today]:[Python] 中的日期可以用常规运算符进行比较);- 患者的记录被锁定 ([lock],参见 [ClientRepository]):如果同一患者同时预约两个时间段(两个标签页、双击),第二个事务会等待第一个事务完成,然后看到它所创建的预约;- 每位患者只能有一个未来的预约;- 最后是插入。预约使用时间段ID 和患者 ID 来创建:只需知道外键的值即可,无需重新读取对象。构造函数的具名参数([Appointment(day=..., slot_id=...)])由 [SQLAlchemy] 提供给任何没有自己构造函数的实体。
- 还有一种情形:在显示日程与进行预订之间,该时间段刚刚被另一位患者占用。此时,数据库约束 [unq1_appointments] 会在 [COMMIT] 操作期间阻止插入。[_transaction] 方法会把这个错误转换为 [BusinessException];
- 第 215–216 行:取消预约。权限检查(患者只能取消自己的预约)由了解当前用户的 Web 层完成。
11.12.5.4. 医生和客户的管理
- 第 223–241 行:公共方法委托给通用方法,并使用正确的描述符;
- 第 246–267 行:创建。姓氏首字母大写,名字中的空格被去除;默认用户名是小写的姓氏,密码就是用户名(SQL 脚本中演示账户的规则)。在事务中:先做验证(无同名者、登录名可用),然后创建账户和人员。人员通过其关系 ([user=user])获得账户:[SQLAlchemy] 知道必须先插入账户以获得其 ID,然后再插入人员。[session.flush()] 会立即发送 [INSERT] :违反约束时会在事务中触发错误,并且返回的人员已带有其 ID;
- 第 274–309 行:更新。将表单中的版本与数据库中的版本进行比较(乐观锁,示例 28);然后只需更新已检索到的对象:它们由会话跟踪,会话会自行发送必要的 [UPDATE] 记录。显示的账户名跟随名字和姓氏;只有在输入了登录名和密码时才会更改它们;
- 第 320–332 行:删除,按外键决定的顺序进行:可能的拒绝(有预约的医生)、删除对该人员的引用、人员本身,然后是其账户。若顺序相反,数据库会拒绝每一个 [DELETE]。所有这些都发生在同一个事务中:只要有一步失败,所有步骤都不会执行;
- 第 337–342 行:同名者会被拒绝,除非是当前正在编辑的那个人,他有权保留自己的名和姓;
- 第 344–346 行:一个用户名只能属于一个账户。
11.12.5.5. 事务与唯一性约束
- 第 365–375 行:所有更新都通过这个方法进行。[sessions.begin()] 打开一个会话及其事务;退出 [with] 块时,如果一切顺利,事务会被提交([COMMIT]),如果发生异常(包括 [ROLLBACK] 之外的 [BusinessException]),则会回滚;
- 第 369–370 行:乐观锁检测到了并发修改(示例 28);
- 第 371–374 行:数据库约束拒绝了此次写入。写入之前所做的检查(用户名唯一、无同名者)在绝大多数情况下都能给出清晰的消息;但是,两位管理员可能同时注册同一个用户名,或者两位患者可能预约同一个时间段。此时唯一性约束会拒绝第二次写入,[SQLAlchemy] 会抛出一个 [IntegrityError]。它的原始消息([e.orig],即 [PyMySQL] 的错误)会引用约束的名称(这里是使用 [MariaDB] 时,同一天第二次预订同一时间段的情形):
| (1062, "Duplicate entry '2026-09-26-2' for key 'unq1_appointments'")
|
- 正则表达式 [CONSTRAINT] (第 91 行)提取这个名称。[MySQL] 8 会加上带表名的前缀(['appointments.unq1_appointments']),[MariaDB] 则不会: 部分 [(?:[^'.]*\.)?] 接受这个可选前缀([(?:...)] 是一个非捕获组,[?] 使其成为可选)。字典 [CONSTRAINT_MESSAGES] (第 84–88 行)把每个已知约束与其消息的键关联起来。这就是 SQL 脚本为什么要给其所有约束命名的原因;
- 第 375 行:任何其他错误都是真正的异常:[raise] 不带参数,会重新抛出当前异常,最终导致显示 500 错误页面。
请注意所有写入方法的结构:一个包含各项操作的内部函数 [work] 被传给 [_transaction],由后者在事务中执行它并转换错误。这相当于 ***[@Transactional]*** 注解在 *[Spring]* 中的作用,只用寥寥几行就实现了:函数和其他对象一样,可以作为参数传递。
11.13. 身份验证
[auth] 文件夹整合了示例 25 至 27 中的机制,但有三点不同:访问规则被反转(除已声明为公开的内容外,一切都被禁止)、用户从数据库中获取,以及创建客户账户受到一张“通行证”的保护。
11.13.1. auth/passwords.py
| # =========================================================================
# auth/passwords.py
# -------------------------------------------------------------------------
# 密码哈希:bcrypt,10 轮,版本 $2b$,与 SQL 脚本中的
# 哈希相同。
#
# bcrypt 只考虑密码的前 72 个字节(带重音的
# 字符在 UTF-8 中占两个字节);bcrypt 库
# 甚至会拒绝更长的密码。因此我们只传给它这
# 72 个字节,创建时和验证时都是如此。
# =========================================================================
import bcrypt
def _bytes(password: str) -> bytes:
return password.encode("utf-8")[:72]
# 要存入数据库的哈希:"$2b$10$" + 盐 + 结果
def hash_password(password: str) -> str:
return bcrypt.hashpw(_bytes(password), bcrypt.gensalt(rounds=10)).decode("ascii")
# checkpw 使用已存储哈希中包含的 "盐" 对键入的密码进行哈希,
# 然后比较两个结果
def verify(password: str, hashed: str) -> bool:
return bcrypt.checkpw(_bytes(password), hashed.encode("ascii"))
|
- 第 15–16 行:[bcrypt] 只考虑密码的前 72 字节 ,而且该库的第 5 版会拒绝更长的密码(示例 25)。因此,无论是创建还是验证时,都只把这 72 个字节传给它:更长的密码会被接受,但第 72 个字节之后的字符会被忽略。带重音的字符在 [UTF-8] 中占两个字节;
- 第 20–21 行:哈希以文本形式存储:[decode("ascii")] 把 [bcrypt] 返回的字节转换为字符串;
- 第 26–27 行:验证(示例 25)。该模块由身份验证和业务层(创建账户、修改密码)使用。
11.13.2. auth/connected_user.py
| # =========================================================================
# auth/connected_user.py
# -------------------------------------------------------------------------
# JWT 令牌包含什么,以及如何重新读取它。
#
# 我们令牌的声明(见 AuthService.set_token):
# sub :用户账户的 id(JWT 约定:"subject"),以文本形式
# login :登录名
# name :显示的名称("Marie PELISSIER"),用于导航栏
# role :ADMIN、DOCTOR 或 USER
# iat、exp:令牌的创建日期和过期日期
# =========================================================================
from dataclasses import dataclass
from rdvmedecins.entities import Role
# 已连接的用户,以类型化的形式表示
@dataclass(frozen=True)
class ConnectedUser:
user_id: int
login: str
name: str
role: Role
# 由已验证令牌的声明所描述的用户;如果
# 缺少某个声明或其格式不符合预期,则为 None
@staticmethod
def of(claims: dict) -> "ConnectedUser | None":
try:
return ConnectedUser(int(claims["sub"]), claims["login"], claims["name"],
Role(claims["role"]))
except (KeyError, ValueError, TypeError):
return None
@property
def is_admin(self) -> bool:
return self.role == Role.ADMIN
@property
def is_patient(self) -> bool:
return self.role == Role.USER
|
- 第 20–24 行:已登录的用户,以类型化形式表示:示例 25 把令牌的断言字典存放在 [g.user] 中;本应用程序存放的是这个对象,编辑器知道它的属性([g.user.role]),其角色是枚举 [Role] 中的一个值;
- 第 29–34 行:根据已验证令牌的断言构造对象。结果类型写在引号中(["ConnectedUser | None"]):当 [Python] 读取该方法定义时,类 [ConnectedUser] 尚未完全定义,因此不能直接使用它的名称。令牌缺少断言([KeyError])或取值异常([ValueError]:未知的角色,或不是数字的 [sub] )时,结果为 [None]:用户未通过身份验证;
- 第 36–42 行:两个属性:[@property] 装饰器把方法转换为计算属性,使用时不带括号:[g.user.is_admin]。
令牌包含账户 ID([sub],按 JWT 标准要求为文本形式)、登录名、显示名称和角色:这是导航栏和访问规则所需的全部信息,无需在每次请求时都查询数据库。
11.13.3. auth/auth_service.py
| # =========================================================================
# auth/auth_service.py
# -------------------------------------------------------------------------
# 身份验证逻辑:
# - validate_user():检查登录名 / 密码对;
# - set_token():为已验证的用户构建 JWT 令牌
# 并将其放入响应的 Cookie 中;
# - clear_token():删除该 Cookie;
# - current_user():由请求的 Cookie 所描述的用户。
#
# JWT 令牌在哪里传递?
# 使用 JavaScript 客户端时,由客户端代码保存令牌,
# 并自行将其添加到每个请求中("Authorization: Bearer
# ..." 请求头)。显示普通 HTML 页面的浏览器做不到
# 这一点:要让它在每个请求中自动出示令牌,
# 就必须把令牌存放在 COOKIE 中。该 Cookie 的选项对
# 安全性很重要:
# - HttpOnly:页面的 JavaScript 无法读取该 Cookie(因此
# 注入的脚本无法窃取令牌);
# - SameSite=Lax:对于来自其他站点的 POST,浏览器不会发送该 Cookie
# (这是针对所谓 CSRF 攻击的第一道防护;
# 第二道是表单的防 CSRF 令牌,参见 rdvmedecins/__init__.py);
# - Secure:在生产环境(HTTPS)中,Cookie 绝不会以明文传输;
# - Max-Age:Cookie 与令牌同时过期消失。
# =========================================================================
from datetime import datetime, timedelta, timezone
import jwt
from flask import Request, Response
from rdvmedecins.auth.passwords import verify
from rdvmedecins.auth.connected_user import ConnectedUser
from rdvmedecins.entities import User
from rdvmedecins.repositories.user_repository import UserRepository
# 携带令牌的 Cookie 的名称
JWT_COOKIE = "rdvmedecins_jwt"
class AuthService:
def __init__(self, sessions, users: UserRepository, secret: str, duration_seconds: int,
cookie_secure: bool):
# HMAC-SHA256 要求密钥至少 256 位:我们在启动时
# 就明确提示,而不是等到第一次登录时才提示
if len(secret.encode("utf-8")) < 32:
raise RuntimeError("JWT_SECRET must be at least 32 characters long (see config.py).")
self._sessions = sessions
self._users = users
self._secret = secret
self._duration = timedelta(seconds=duration_seconds)
self._cookie_secure = cookie_secure
# 如果登录名不存在或密码错误,则为 None
def validate_user(self, login: str, password: str) -> User | None:
with self._sessions() as session:
user = self._users.read_by_login(session, login)
if user is None or not verify(password, user.password):
return None
return user
# -----------------------------------------------------------------------
# 构建 [user] 的 JWT 令牌并将其放入 Cookie。
# 令牌经过密钥签名(HMAC-SHA256):浏览器
# 可以读取它(它未加密),但无法修改它,因为任何
# 修改都会使签名失效。
# -----------------------------------------------------------------------
def set_token(self, response: Response, user: User):
now = datetime.now(timezone.utc)
claims = {
"sub": str(user.id),
"login": user.login,
"name": user.name,
"role": user.role.value,
"iat": now,
"exp": now + self._duration,
}
token = jwt.encode(claims, self._secret, algorithm="HS256")
response.set_cookie(JWT_COOKIE, token, max_age=self._duration, path="/", httponly=True,
samesite="Lax", secure=self._cookie_secure)
# 清除 Cookie:重新设置它,内容为空,生存时间为零
@staticmethod
def clear_token(response: Response):
response.delete_cookie(JWT_COOKIE, path="/")
# 请求中存在的令牌,无论是否有效
@staticmethod
def token_of(request: Request) -> str | None:
return request.cookies.get(JWT_COOKIE)
# -----------------------------------------------------------------------
# 由请求的 Cookie 所描述的用户;如果没有令牌,
# 或令牌已过期、被伪造或格式错误,则为 None。
# jwt.decode 同时检查签名和过期日期(exp 声明)。
# -----------------------------------------------------------------------
def current_user(self, request: Request) -> ConnectedUser | None:
token = self.token_of(request)
if not token:
return None
try:
claims = jwt.decode(token, self._secret, algorithms=["HS256"])
except jwt.InvalidTokenError:
return None
return ConnectedUser.of(claims)
|
- 第 46–47 行:过短的签名密钥会在应用程序启动时就被报告,而不是等到第一次登录时:[create_app] 创建该服务,异常会带着这条消息终止应用程序;
- 第 55–60 行:验证用户名和密码。服务通过 DAO 读取用户,所用会话仅在这次读取期间保持打开;密码验证([bcrypt],速度很慢)在会话关闭之后进行,以避免不必要地占用数据库连接;
- 第 68–80 行:令牌(示例 25)及其 Cookie [rdvmedecins_jwt]。[user.role.value]:枚举值,即字符串 ["USER"]。在生产环境中,Cookie 会被赋予 [Secure] 属性([COOKIE_SECURE]);
- 第 84–85 行:删除 Cookie。这是一个静态方法:它不需要对象,直接在类上调用([AuthService.clear_token(response)]);
- 第 97–105 行:由请求 Cookie 所标识的用户,或 [None]。
11.13.4. auth/security.py
安全的核心:对每个请求的身份验证以及访问规则。
| # =========================================================================
# auth/security.py
# -------------------------------------------------------------------------
# 谁可以访问什么,以及如何在每个
# 请求中识别用户(参见示例 25 和 26)。
#
# 对于每个请求,authenticate 函数(应用的
# before_request):
# 1. 从 Cookie 中读取令牌,检查其签名和过期日期,
# 并将用户存入 g.user(如果没有则为 None);
# 2. 应用访问规则:所有操作都需要已通过身份验证的
# 用户,但标有 @public 的操作(登录、
# 创建账户、选择语言)和静态文件除外。
# 这就是"除允许的之外一律禁止"的规则:以后新增的、
# 忘记加以保护的操作,默认也是受保护的。
# 只有这时 Flask 才会调用该操作,其装饰器
# @roles_required(...) 会检查角色。
#
# 两种失败情况,两种适合 HTML 应用的响应:
# - 没有已通过身份验证的用户(没有令牌、令牌过期或被伪造)
# -> 重定向到登录页面;
# - 角色不足 -> 返回 403 响应,由 web/errors.py 将其转为页面。
# =========================================================================
from functools import wraps
from flask import abort, current_app, g, redirect, request, url_for
from rdvmedecins.auth.auth_service import AuthService
from rdvmedecins.entities import Role
from rdvmedecins.web.flash import flash_error
# 令牌有效,但它所指向的账户已不存在:该账户在登录之后
# 已被删除(由患者本人在另一个
# 标签页中删除,或由 ADMIN 删除)。这种情况按会话过期处理:
# web/errors.py 清除 Cookie 并重定向回登录页面。
class InvalidSession(Exception):
pass
# 一个将某个操作标记为公开的装饰器(参见示例 24)
def public(action):
action.public = True
return action
def register(app, auth_service: AuthService):
@app.before_request
def authenticate():
g.user = auth_service.current_user(request)
# 没有匹配的路由(随后会出现 404 页面),或是静态文件
if request.endpoint is None or request.endpoint == "static":
return None
action = current_app.view_functions[request.endpoint]
if getattr(action, "public", False) or g.user is not None:
return None
# before_request 返回的响应会终止处理:
# 不会调用该操作
return to_login()
# -----------------------------------------------------------------------
# 没有已通过身份验证的用户 -> 登录页面。如果存在
# Cookie,则其令牌已失效:会话已过期。
# 随后清除该 Cookie,并通过 flash 消息提醒用户。
# -----------------------------------------------------------------------
def to_login():
response = redirect(url_for("auth.show_login"))
if AuthService.token_of(request):
AuthService.clear_token(response)
flash_error("ERRORS.SESSION_EXPIRED")
return response
# -----------------------------------------------------------------------
# 用户的角色必须是 [roles] 之一;否则返回 403 响应。
# require_roles 由蓝图的 before_request 调用(蓝图的所有
# 操作,参见 controllers/persons.py);roles_required 是
# 操作的装饰器(参见示例 26)。
# -----------------------------------------------------------------------
def require_roles(*roles: Role):
if g.user is None:
raise InvalidSession()
if g.user.role not in roles:
abort(403)
def roles_required(*roles: Role):
def decorator(action):
@wraps(action)
def protected_action(*args, **kwargs):
require_roles(*roles)
return action(*args, **kwargs)
return protected_action
return decorator
|
- 第 37–38 行:针对一种特殊情况的异常:令牌有效,但它所指向的账户已不存在(患者在另一个标签页中删除了它,或被管理员删除)。需要该账户的操作会抛出此异常;错误处理器将其视为会话已过期(参见 [web/errors.py]);
- 第 42–44 行:将操作标记为公开的装饰器(示例 24);
- 第 50–60 行:应用程序的 [before_request] 函数。首先,对所有请求(包括公开请求)都要验证用户身份:登录页面必须知道用户是否已经登录。接着是访问规则:不匹配任何路由的请求([request.endpoint is None]:随后将显示 404 页面)或请求静态文件的请求被允许;标记为公开的操作被允许;已通过身份验证的用户被允许。否则,函数返回一个响应(重定向到登录页面),这会终止处理:不会调用该操作。
这就是“除非明确允许,否则一切禁止”的规则:之后新增的操作——即使你忘了对它加以保护——也会自动受到保护。在公开操作上忘记加 [@public] 会立刻被发现(页面会重定向到登录页面);而未能保护一个私有操作则不会马上显现:默认规则必须是最安全的。这同样也是 [Spring MVC] 版本的规则([anyRequest().authenticated()]);
- 第 68–73 行:重定向到登录页面。如果请求中包含令牌 Cookie,就意味着该令牌已不再有效(已过期或被篡改):Cookie 会被删除,并通过弹出消息向用户说明其会话已过期(上文所示的会话结束消息截图);
- 第 82–86 行:授权。参数 [*roles] 以元组形式接受任意数量的角色:[require_roles(Role.ADMIN, Role.DOCTOR)]。不在列表中的角色会得到 403 错误。[g.user is None] 这个测试本不应为真(访问规则已经过滤掉了匿名访问者),除非 [require_roles] 是从公开操作中被调用的:这提供了额外一层安全保障;
- 第 89–98 行:示例 26 中的带参数装饰器,它调用 [require_roles]。[require_roles] 也可以单独使用,放在蓝图的 [before_request] 中,一次性保护该蓝图的所有操作(参见 [controllers/persons.py])。
11.13.5. auth/captcha_drawing.py
图像渲染与示例 27 相同,原样复制。其头部注释强调了一个重要的点:每个字符都是用线条([<path>] 元素)绘制的,绝不写成文本([<text>] 元素);否则,机器人只需读取图像的源代码即可。
11.13.6. auth/captcha.py
| # =========================================================================
# auth/captcha.py
# -------------------------------------------------------------------------
# 由服务器自己生成的验证码(CAPTCHA,"区分人类与机器人的测试"),
# 不依赖任何外部服务:几个扭曲的字符,
# 被线条打乱,放在一张 SVG 图像中(参见 captcha_drawing.py)。
# 人类很容易读出它们;而只会循环发送
# 表单的机器人则无法做到。
#
# 工作原理:
# 1. generate() 绘制一段随机文本,生成图像,并把
# 正确答案保存在服务器的内存中,使用随机标识符作为键;
# 2. 页面显示图像,并将标识符放入表单的
# 隐藏字段中(答案本身绝不离开服务器);
# 3. verify(id, typed) 将输入与预期答案比较,然后
# 遗忘这个验证码:每张图像只能使用一次,机器人无法
# 重放已找到的答案。
#
# 整个服务器只有一个 CaptchaService 对象,由多个
# 请求并行使用(服务器在多个线程上处理它们):
# 锁(Lock)保证同一时刻只有一个线程读取或修改
# 待处理验证码的字典。
#
# 接受的限制:仅限单个进程的内存。若有多个进程
# 或多台服务器,则需要共享存储。
# =========================================================================
import secrets
from dataclasses import dataclass
from datetime import datetime, timedelta
from threading import Lock
from rdvmedecins.auth import captcha_drawing
# 图像的有效期:有 10 分钟时间填写表单
LIFETIME = timedelta(minutes=10)
# 内存保护:超过此上限,所有待处理的验证码都会被清除
MAX_CAPTCHAS = 10_000
# 一个验证码:id,放入表单的隐藏字段 "captchaId";
# svg,图像,原样插入页面
@dataclass(frozen=True)
class Captcha:
id: str
svg: str
class CaptchaService:
def __init__(self):
# id -> (预期答案, 过期日期)
self._pending: dict[str, tuple[str, datetime]] = {}
self._lock = Lock()
def generate(self) -> Captcha:
text = captcha_drawing.random_text(5) # 5 个字符
id = secrets.token_urlsafe(16) # 一个随机标识符,无法猜测
with self._lock:
self._purge()
self._pending[id] = (text, datetime.now() + LIFETIME)
return Captcha(id, captcha_drawing.svg(text))
# 如果 [typed] 是验证码 [id] 的正确答案(不区分
# 大小写),则为 true。无论结果如何,验证码都会被消耗:如果两个
# 请求同时提交同一个验证码,只有一个
# 能将其移除(pop,在锁内),另一个失败。
def verify(self, id: str | None, typed: str | None) -> bool:
with self._lock:
expected = self._pending.pop(id, None) if id else None
if expected is None or typed is None:
return False
text, expires = expected
return expires > datetime.now() and text.lower() == typed.strip().lower()
# (在锁内调用)
def _purge(self):
now = datetime.now()
for id in [id for id, (_, expires) in self._pending.items() if expires <= now]:
del self._pending[id]
if len(self._pending) >= MAX_CAPTCHAS:
self._pending.clear()
|
示例 27 中的服务,并增加了:[_purge] 方法(第 77–82 行),每次创建验证码时调用,用于丢弃已过期的验证码。没有它,那些已显示但从未使用的验证码(例如打开登录页面后又放弃)会在内存中不断累积。[MAX_CAPTCHAS] 起到保险作用:即使机器人请求数百万次登录页面,也无法耗尽服务器的内存。数字 [10_000] 中使用了下划线,用来分隔千位以便阅读([Python] 会忽略它)。待删除的标识符列表是在删除循环之前构建的:在遍历字典的同时不能删除它的键。
11.13.7. auth/limiter.py
| # =========================================================================
# auth/limiter.py
# -------------------------------------------------------------------------
# 对抗机器人的第二道防线(第一道是验证码):我们对
# 尝试次数计数,超过阈值就封锁一段时间。
#
# - 登录:同一 IP 地址对同一登录名失败(验证码错误或
# 密码错误)LOGIN_MAX_FAILURES 次后,该
# 组合会被封锁 LOGIN_BLOCK_MINUTES 分钟。如果同一 IP 地址累计的
# 失败次数(所有登录名合计)达到该值的 5 倍,也会被
# 封锁(机器人会尝试成千上万个不同的登录名);
# - 创建账户:同一 IP 地址每小时最多创建
# REGISTRATION_MAX_PER_HOUR 个账户。
#
# 注意,在教室里:所有计算机通常通过同一个 IP 地址
# 访问互联网。因此登录封锁首先针对
# (IP, 登录名)组合:输错密码的学生
# 不会连累邻座的同学;阈值也可以
# 在 config.py 中设置。
#
# 整个服务器只有一个对象,由并行的请求调用:
# 所有公共方法都会获取锁:同一时刻只有一个线程
# 读取并修改计数器。
# =========================================================================
import math
from datetime import datetime, timedelta
from threading import Lock
ONE_HOUR = timedelta(hours=1)
class Counter:
def __init__(self, start: datetime):
self.number = 0 # 当前窗口内已计数的尝试次数
self.start = start # 计数窗口的开始时间
self.blocked_until = datetime.min # 未被封锁时为 datetime.min
class AttemptLimiter:
def __init__(self, login_max_failures: int, login_block_minutes: int,
registration_max_per_hour: int):
self._counters: dict[str, Counter] = {}
self._lock = Lock()
self._max_login_failures = login_max_failures
self._login_block_duration = timedelta(minutes=login_block_minutes)
self._max_registrations = registration_max_per_hour
# —— 登录
# 剩余封锁的分钟数(0 = 允许尝试)
def login_block_minutes(self, ip: str, login: str) -> int:
with self._lock:
return max(self._remaining_minutes(self._login_key(ip, login)),
self._remaining_minutes(self._ip_key(ip)))
def login_failure(self, ip: str, login: str):
with self._lock:
self._count(self._login_key(ip, login), self._max_login_failures,
self._login_block_duration, self._login_block_duration)
self._count(self._ip_key(ip), self._max_login_failures * 5,
self._login_block_duration, self._login_block_duration)
# 登录成功会重置该登录名的计数器
def login_success(self, ip: str, login: str):
with self._lock:
self._counters.pop(self._login_key(ip, login), None)
# —— 注册
def registration_block_minutes(self, ip: str) -> int:
with self._lock:
return self._remaining_minutes(f"registration|{ip}")
# 一小时的窗口;一旦达到配额,就封锁到该小时结束
def registration_success(self, ip: str):
with self._lock:
self._count(f"registration|{ip}", self._max_registrations, ONE_HOUR, ONE_HOUR)
# —— 通用机制
# (私有方法总是在锁内调用)
def _remaining_minutes(self, key: str) -> int:
counter = self._counters.get(key)
if counter is None:
return 0
remaining = (counter.blocked_until - datetime.now()).total_seconds()
# 向上取整到分钟:剩余封锁 30 秒 -> "1 minute"
return max(0, math.ceil(remaining / 60))
# 对一次尝试计数;如果在窗口内达到阈值,则封锁
def _count(self, key: str, maximum: int, window: timedelta, block: timedelta):
now = datetime.now()
self._purge(now)
counter = self._counters.get(key)
if counter is None or now - counter.start > window:
counter = Counter(now)
self._counters[key] = counter
counter.number += 1
if counter.number >= maximum:
counter.blocked_until = now + block
counter.number = 0 # 封锁结束后,从零重新开始
counter.start = counter.blocked_until
# 我们清除不再有用的计数器(既未被封锁,也不是最近的)
def _purge(self, now: datetime):
if len(self._counters) < 1000:
return
for key in [key for key, c in self._counters.items()
if c.blocked_until < now and now - c.start > ONE_HOUR]:
del self._counters[key]
@staticmethod
def _login_key(ip: str, login: str) -> str:
return f"login|{ip}|{login.strip().lower()}"
@staticmethod
def _ip_key(ip: str) -> str:
return f"ip|{ip}"
|
示例 27 中限流器的更完整版本:
- 登录阻止首先针对二元组 (IP 地址,登录名):在教室里,所有计算机往往通过同一个 IP 地址访问互联网,输错密码的学生不应该阻止他的邻座。不过,如果一个地址在所有登录名上累计了五倍的失败次数,该地址也会被阻止:这就是尝试数千个不同登录名的机器人的情形(第 57–61 行);
- 账户创建被限制为每个 IP 地址每小时只能创建一定数量的账户(第 71–78 行);
- 计数器存储在同一个字典中,键以其用途为前缀([login|...]、[ip|...]、[registration|...]);
- 第 92–103 行:计数器在一个时间窗口内统计尝试次数;窗口结束之后发生的尝试会开启一个新窗口。达到阈值时,该键被锁定,计数器清零;
- 第 106–111 行:一旦计数器条目超过 1,000 个,就会丢弃那些不再使用的条目(既未被阻止也不是最近的)。
与验证码一样,限流器把数据存储在进程的内存中:对于由单个进程提供服务的应用程序(开发服务器、[Waitress])这是可以接受的,但不适用于多进程或多服务器,因为它们不会共享计数器(那时就需要共享存储,例如 [Redis])。
11.13.8. auth/registration_pass.py
| # =========================================================================
# auth/registration_pass.py
# -------------------------------------------------------------------------
# 创建账户的"通行证"。
#
# 要打开"创建患者账户"页面,必须先输入
# 身份验证页面的验证码(参见
# controllers/registration.py,POST /register/access)。随后服务器会签发
# 一张通行证:
# - 一个随机标识符,存放在 HttpOnly Cookie 中;
# - 有效期 15 分钟(足够填写表单,即使在
# 输入错误后多次重试);
# - 一旦创建账户就被消耗:解出一个验证码最多只能创建一个
# 账户。机器人无法批量创建账户。
#
# 没有有效的通行证,GET 和 POST /register 会重定向回
# 身份验证页面:直接输入 URL /register 无法
# 绕过验证码。
#
# 与验证码一样,通行证保存在进程的内存中。
# =========================================================================
import secrets
from datetime import datetime, timedelta
from threading import Lock
from flask import Response
COOKIE = "rdvmedecins_registration"
LIFETIME = timedelta(minutes=15)
MAX_PASSES = 10_000
class RegistrationPass:
def __init__(self):
# id -> 过期日期
self._passes: dict[str, datetime] = {}
self._lock = Lock()
# 签发一张新通行证;返回其标识符
def issue(self) -> str:
id = secrets.token_urlsafe(16)
with self._lock:
self._purge()
self._passes[id] = datetime.now() + LIFETIME
return id
# 如果 [id] 是一张存在且未过期的通行证,则为 true
def is_valid(self, id: str | None) -> bool:
with self._lock:
expires = self._passes.get(id) if id else None
return expires is not None and expires > datetime.now()
# 通行证已被使用:将其清除
def consume(self, id: str | None):
with self._lock:
self._passes.pop(id, None)
# (在锁内调用)
def _purge(self):
now = datetime.now()
for id in [id for id, expires in self._passes.items() if expires <= now]:
del self._passes[id]
if len(self._passes) >= MAX_PASSES:
self._passes.clear()
# 浏览器只会向 /register 地址发送该 Cookie...
def set_cookie(response: Response, id: str, secure: bool):
response.set_cookie(COOKIE, id, max_age=LIFETIME, path="/register", httponly=True,
samesite="Lax", secure=secure)
# ...并通过重新设置为空、生存时间为零来清除它
def clear_cookie(response: Response):
response.delete_cookie(COOKIE, path="/register")
|
创建患者账户是一个公开页面:机器人可能批量创建账户。因此它由登录页面的验证码保护:“创建患者账户”按钮会把这个验证码发送给服务器,如果验证码正确,服务器就会颁发一个令牌:
- 第 42–47 行:一个随机标识符,有效期 15 分钟,与验证码一样存储在内存中;
- 第 50–53 行:注册页面对每个请求都验证通行证——GET 与 POST 同样处理;
- 第 56–58 行:创建账户会消耗通行证:一个已解答的验证码最多对应一个账户;
- 第 70–72 行:通行证存储在 Cookie 中。它的属性 [path="/register"], 限制了浏览器附带它的请求:只有以 [/register] 开头的地址才会带上它;
- 第 76–77 行:要删除 Cookie,必须指定与设置它时相同的路径。
11.13.9. controllers/auth.py
登录控制器,它使用了上述所有服务。
| # =========================================================================
# controllers/auth.py
# -------------------------------------------------------------------------
# 登录的公开路由:
# GET / 重定向到该角色的主页(或重定向到 /login)
# GET /login 显示登录表单(含验证码)
# POST /login 检查尝试次数限制、验证码、登录名 / 密码
# POST /logout 退出登录
#
# 按以下顺序防范机器人:
# 1. 该 IP 地址对此登录名最近失败次数过多?
# -> 立即拒绝,甚至不看密码;
# 2. 验证码答案错误? -> 拒绝(计为一次失败);
# 3. 只有这时才验证密码。
# 在第 1 步或第 2 步被拒绝的尝试,其密码绝不会
# 被检查:因此机器人不断尝试也学不到任何信息。
# =========================================================================
from flask import Blueprint, g, redirect, render_template, request, url_for
from rdvmedecins.auth.auth_service import AuthService
from rdvmedecins.auth.security import public
from rdvmedecins.entities import Role
from rdvmedecins.models.view_models import LoginModel, Message
from rdvmedecins.web.services import auth_service, captchas, limiter
auth = Blueprint("auth", __name__)
# 每个角色登录后的主页
def home_page(role: Role) -> str:
return url_for("area.patient_area") if role == Role.USER else url_for("schedule.show")
# 访问者的 IP 地址。在反向代理(nginx 等)之后,它会是
# 代理的地址:此时应用必须用 Werkzeug 的
# ProxyFix 中间件包装,它会读取 X-Forwarded-For 请求头。
def ip_address() -> str:
return request.remote_addr or ""
# -----------------------------------------------------------------------
# GET /
# 该路由是公开的:如果有用户,已由
# auth/security.py(g.user)确定,但不要求任何条件。
# -----------------------------------------------------------------------
@auth.get("/")
@public
def home():
return redirect(home_page(g.user.role) if g.user else url_for("auth.show_login"))
# -----------------------------------------------------------------------
# GET /login[?login=xxx]:可选参数用于预填登录名
# 字段(在创建账户后立即使用,参见 controllers/registration.py)
# -----------------------------------------------------------------------
@auth.get("/login")
@public
def show_login():
# 已登录(令牌仍然有效):直接前往主页
if g.user:
return redirect(home_page(g.user.role))
return form(request.args.get("login", "")[:30], None)
# -----------------------------------------------------------------------
# POST /login
# request.form.get:字段缺失时返回 None(而不是 400 错误)-
# 由代码决定如何处理它。
# -----------------------------------------------------------------------
@auth.post("/login")
@public
def log_in():
login = (request.form.get("login") or "").strip()
password = request.form.get("password") or ""
ip = ip_address()
# 1. 最近失败次数过多?
minutes = limiter().login_block_minutes(ip, login)
if minutes > 0:
return form(login, Message("ERRORS.TOO_MANY_ATTEMPTS", {"minutes": str(minutes)}))
# 2. 验证码
if not captchas().verify(request.form.get("captchaId"), request.form.get("captcha")):
limiter().login_failure(ip, login)
return form(login, Message("ERRORS.WRONG_CAPTCHA"))
# 3. 密码
user = auth_service().validate_user(login, password) if login and password else None
if user is None:
limiter().login_failure(ip, login)
return form(login, Message("LOGIN.ERROR"))
limiter().login_success(ip, login)
response = redirect(home_page(user.role))
auth_service().set_token(response, user)
return response
# -----------------------------------------------------------------------
# POST /logout:清除令牌的 Cookie,然后前往登录
# 页面。仅限 POST:放在其他站点上的简单链接(GET)
# 无法在用户不知情的情况下将其退出登录。
# -----------------------------------------------------------------------
@auth.post("/logout")
@public
def log_out():
response = redirect(url_for("auth.show_login"))
AuthService.clear_token(response)
return response
# 表单,始终带有新的验证码(每张图像只
# 使用一次);重新显示已输入的登录名,绝不显示密码
def form(login: str, error: Message | None):
model = LoginModel("LOGIN.TITLE", error, login, captchas().generate())
return render_template("login.html", model=model)
|
- 第 24 行:共享服务通过 [web/services.py] 模块(稍后讨论)中的一些小函数获得,这些函数从 [app.extensions] 中取出它们;
- 第 30–31 行:每个角色都有自己的主页:患者是患者门户,其他角色是日程表;
- 第 37–38 行:访问者的 IP 地址。在反向代理([nginx]、[Apache])之后,这将是代理的地址,对所有访问者都相同:此时需要把应用程序包装在 [ProxyFix] 中间件中,该中间件来自 [Werkzeug] (参见关于生命周期的章节),它从代理添加的 [X-Forwarded-For] 头中读取原始地址;
- 第 46–49 行:站点的公开根路径:它重定向到用户的主页或登录页面;
- 第 56–62 行:登录页面。已经登录的用户(其令牌仍然有效)会被直接送到其主页。可选参数 [login] 用于预填字段(在创建账户之后);[[:30]] 把它的长度限制为用户名的长度;
- 第 70–96 行:登录过程,分三步,按此顺序:可能的阻止、验证码,最后才是密码。在前两步中被拒绝的尝试绝不会检查密码:机器人即使反复尝试也学不到任何东西。[request.form.get(...) or ""]:空字段会返回空字符串。错误消息是一个 [Message] 对象:一个翻译键及其参数(稍后讨论);
- 第 104–109 行:注销,使用 POST(示例 25)。它是公开的:会话已过期的用户必须能够点击“注销”,而不必先被重定向;
- 第 114–116 行:登录页面,同样带有新的验证码。它的模板是一个 [LoginModel] 对象(参见 [models/view_models.py])。
请注意,登录表单没有使用 [WTForms]:它的三个字段没有验证规则(空用户名只会导致登录失败),并且与应用程序中的所有表单一样,该表单由 [CSRFProtect] 防御 CSRF 攻击。
11.14. Web 层:共享服务
[web] 文件夹包含各控制器共有的内容。其中的每个模块都回答所有控制器都会问自己的一个问题:如何获得服务、翻译文本、在重定向之后显示消息、重新显示被拒绝的表单,或把错误转换为页面。
11.14.1. web/services.py
| # =========================================================================
# web/services.py
# -------------------------------------------------------------------------
# 应用的共享对象(参见示例 06):它们由应用工厂
# (rdvmedecins/__init__.py)创建一次,并
# 存放在 app.extensions 字典中。这些小函数
# 为处理当前请求的应用在那里找到
# 它们(current_app);它们还为分析工具提供其类型。
# =========================================================================
from flask import current_app
from rdvmedecins.auth.auth_service import AuthService
from rdvmedecins.auth.captcha import CaptchaService
from rdvmedecins.auth.limiter import AttemptLimiter
from rdvmedecins.auth.registration_pass import RegistrationPass
from rdvmedecins.web.application_model import ApplicationModel
def application() -> ApplicationModel:
return current_app.extensions["rdvmedecins.application"]
def auth_service() -> AuthService:
return current_app.extensions["rdvmedecins.auth"]
def captchas() -> CaptchaService:
return current_app.extensions["rdvmedecins.captchas"]
def limiter() -> AttemptLimiter:
return current_app.extensions["rdvmedecins.limiter"]
def passes() -> RegistrationPass:
return current_app.extensions["rdvmedecins.passes"]
|
由工厂创建并存放在 [app.extensions] 中的共享对象,通过这些小函数来获取(示例 06)。它们省去了在每个控制器中重复书写字典键的麻烦,并向分析工具提供它们的类型 :在控制器中,编辑器知道 [application()] 是一个 [ApplicationModel] ,并会提示它的方法。
11.14.2. web/translator.py
| # =========================================================================
# web/translator.py
# -------------------------------------------------------------------------
# 界面的法语 / 英语翻译(参见示例 22)。
#
# 这些字典与应用的 NestJS、
# ASP.NET Core 和 Spring MVC 版本中的字典是同一批文件(i18n/fr.json、i18n/en.json),
# 启动时只读取一次。
#
# 在视图中,使用 t 函数(参见 web/common_model.py):
# {{ t("LOGIN.TITLE") }} 不带参数;
# {{ t("AREA.HELLO", name=model.patient) }} 命名参数;
# {{ t(message.key, message.params) }} 参数字典。
#
# 当前语言:g.language,在每个请求中根据 Cookie 设置
# (参见 rdvmedecins/__init__.py,set_language 函数)。
# =========================================================================
import json
import re
from pathlib import Path
from flask import g
LANGUAGES = ("fr", "en")
DEFAULT_LANGUAGE = "en"
# 记住所选语言的 Cookie(参见 controllers/language.py)
LANGUAGE_COOKIE = "rdvmedecins_language"
# {name}:文本中的参数
PARAMETER = re.compile(r"\{(\w+)\}")
# 与 [code] 匹配的受支持语言:"fr" -> "fr";"de" 或 None -> "en"
def language(code: str | None) -> str:
return code if code in LANGUAGES else DEFAULT_LANGUAGE
class Translator:
def __init__(self, folder: Path):
# 语言 -> (完整键 "LOGIN.TITLE" -> 文本)
self._dictionaries: dict[str, dict[str, str]] = {}
for code in LANGUAGES:
with open(folder / f"{code}.json", encoding="utf-8") as file:
self._dictionaries[code] = self._flatten(json.load(file))
# -----------------------------------------------------------------------
# translate("DOCTORS.ADDED", {"name": "Marie PELISSIER"})
# -> 在该语言的字典中查找 "DOCTORS.ADDED",并
# 用其值替换 {name}。所请求语言中缺失的键
# 会到英语中查找;若处处缺失,则显示
# 键本身(这样遗漏会被立即发现)。
# 参数:一个字典,和/或命名参数。
# -----------------------------------------------------------------------
def translate(self, key: str | None, params: dict | None = None, **others) -> str:
if not key:
return ""
text = self._dictionaries[language(g.get("language"))].get(key)
if text is None:
text = self._dictionaries[DEFAULT_LANGUAGE].get(key, key)
values = {**(params or {}), **others}
if not values:
return text
return PARAMETER.sub(lambda m: str(values.get(m.group(1), m.group(0))), text)
# { "LOGIN": { "TITLE": "Login" } } -> { "LOGIN.TITLE": "Login" }
@classmethod
def _flatten(cls, node: dict, prefix: str = "") -> dict[str, str]:
result = {}
for key, value in node.items():
full_key = f"{prefix}.{key}" if prefix else key
if isinstance(value, dict):
result.update(cls._flatten(value, full_key))
else:
result[full_key] = value
return result
|
示例 22 中的翻译器,增加了三点:
- 第 56–65 行:文本的参数可以通过字典(第二个参数 [params])、具名参数([**others])或两者一起提供。应用程序消息([Message] 类,稍后讨论)以字典携带其参数;而视图则更喜欢使用具名参数。[{**a, **b}] 会创建一个合并了 [a] 和 [b] 的字典;
- 第 61 行:所请求语言中缺失的键,会先在英语中查找,然后才原样显示;
- 第 59 行:如果 [g.get("language")] 返回 [None] ,如果 [g] 没有 [language] 属性,而不是抛出异常:即使在设置语言的 [before_request] 函数之前发生了错误,翻译器也能工作。
语言 Cookie 的名称以应用程序名称为前缀([rdvmedecins_language]),与令牌和通行证一样:Cookie 与域名([localhost])关联,而不与端口关联。否则,同样由 [localhost] 提供服务的那些示例就可能读取到该应用程序的 Cookie。
11.14.3. web/common_model.py
| # =========================================================================
# web/common_model.py
# -------------------------------------------------------------------------
# 所有视图都需要的内容,无论是哪个页面(参见示例
# 15):"上下文处理器"在每个视图构建之前运行,
# 将其变量添加到所有视图的模型中:
# - user :已连接的用户(或 None),用于导航栏;
# - language :"fr" 或 "en";
# - path :请求的 URL(导航栏的当前菜单项,
# 验证码的"另一张图片"链接);
# - t :翻译函数(参见 web/translator.py)。
# flash 消息由布局读取(get_flashed_messages)。
# =========================================================================
from flask import g, request
from rdvmedecins.web.translator import Translator
def register(app, translator: Translator):
@app.context_processor
def common_model():
return {
"user": g.get("user"),
"language": g.get("language", "en"),
"path": request.path,
"t": translator.translate,
}
|
示例 15 中的上下文处理器:有四个变量可用于所有视图,而无需操作来提供它们:已登录的用户(用于导航栏)、语言(用于页面的 [lang] 属性以及 FR / EN 按钮)、所请求 URL 的路径(用于当前菜单和验证码中的“换一张图片”链接),以及翻译函数 [t]。如果该属性不存在(例如在身份验证之前构造出的错误页面),[g.get("user")] 会返回 [None] 。
11.14.4. web/flash.py
| # =========================================================================
# web/flash.py
# -------------------------------------------------------------------------
# "flash"消息:只显示一次的消息,显示在下一个
# 页面上(参见示例 20)。它是所有表单
# 使用的"Post / Redirect / Get"模式的天然补充:
# 成功的 POST 不构建页面,而是重定向(302)到
# GET 页面;然而,消息必须在重定向后继续存在。
#
# Flask 把它们存放在会话(SESSION)中,也就是由密钥(SECRET_KEY)签名的
# Cookie 中:服务器保持无状态,在两个请求之间
# 不在内存中保留任何东西。浏览器可以读取此 Cookie(它
# 未加密),但若不让签名露馅,就无法修改它。
#
# 一条消息不包含文本,而是包含一个翻译键及其
# 参数:它在显示时按页面的语言进行翻译
# (参见 templates/layout.html)。其类别:"success"(显示在
# 页面顶部)或 "danger"(错误,显示在底部)。
# =========================================================================
from flask import flash
def flash_success(key: str, **params):
flash({"key": key, "params": params}, "success")
def flash_error(key: str, **params):
flash({"key": key, "params": params}, "danger")
|
示例 20 中的闪现消息。消息不是文本,而是一个字典:翻译键及其参数。它将在显示时由模板翻译成页面的语言。[Flask] 把消息存放在会话中,而会话就是一个 Cookie:为此,它把消息转换为 JSON,JSON 接受由字符串组成的字典。消息类别([success] 或 [danger],取自 [Bootstrap] 的颜色名称)决定其位置:成功消息位于页面顶部,错误消息位于页面底部。
11.14.5. web/errors.py
| # =========================================================================
# web/errors.py
# -------------------------------------------------------------------------
# 错误如何变成 HTML 页面。三个处理器分担
# 这项工作(参见示例 24):
#
# 1. InvalidSession(账户在登录后被删除)-> 返回
# 登录页面,与会话过期时相同;
# 2. HTTP 错误:abort(400)、abort(403)(角色不足)、未知
# 页面(404)、不支持的方法(405)、防 CSRF 令牌
# 缺失或错误(400)…… -> 显示错误页面,并保留原始状态码;
# 3. 任何其他异常(真正的异常情况)-> 写入服务器
# 的日志,附带其堆栈跟踪;用户看到的是
# 500 错误页面,绝不会看到堆栈跟踪。
# =========================================================================
from flask import current_app, redirect, render_template, url_for
from werkzeug.exceptions import HTTPException
from rdvmedecins.auth.auth_service import AuthService
from rdvmedecins.auth.security import InvalidSession
from rdvmedecins.models.view_models import ErrorModel
from rdvmedecins.web.flash import flash_error
MESSAGES = {
400: "ERRORS.BAD_REQUEST",
403: "ERRORS.FORBIDDEN",
404: "ERRORS.NOT_FOUND",
}
def error_page(code: int):
model = ErrorModel("ERROR_PAGE.TITLE", None, code, MESSAGES.get(code, "ERRORS.SERVER_ERROR"))
# 页面保留错误码(404 仍是 404……)
return render_template("error.html", model=model), code
def register(app):
@app.errorhandler(InvalidSession)
def invalid_session(e):
response = redirect(url_for("auth.show_login"))
AuthService.clear_token(response)
flash_error("ERRORS.SESSION_EXPIRED")
return response
@app.errorhandler(HTTPException)
def http_error(e: HTTPException):
return error_page(e.code or 500)
# Exception:所有异常的父类;该处理器
# 只接收没有更具体的处理器处理过的异常
@app.errorhandler(Exception)
def anomaly(e: Exception):
current_app.logger.exception("unexpected error")
return error_page(500)
|
示例 24 中的错误处理器:
- 第 31–34 行:错误页面,带有原始错误代码(404 页面仍然是 404 响应)和根据代码选择的已翻译消息;
- 第 39–44 行:登录之后账户已被删除:重定向到登录页面,与会话过期时一样;
- 第 46–48 行:所有 HTTP 错误:[abort(403)]、未知页面(404)、被禁止的方法(405)、缺失或无效的防 CSRF 令牌(400,由 [CSRFProtect] 处理)等;
- 第 52–55 行:任何其他异常,即真正的异常情况(编程错误、变得无法访问的数据库)。[current_app.logger] 是应用程序的日志 (标准模块 [logging] 的一个对象);它的方法 [exception] 把消息写入日志,并附上当前异常的调用栈。然而,用户只会看到 500 错误页面:绝不会看到调用栈,因为它会泄露应用程序的内部细节。[Flask] 总是选择最具体的处理器:HTTP 错误由第二个处理器处理,而不是由这个处理器处理。
11.14.6. web/application_model.py
| # =========================================================================
# web/application_model.py
# -------------------------------------------------------------------------
# 业务层的缓存 / 外观(相当于应用早期版本中的
# [ApplicationModel] 类):
# 医生和客户端列表在启动时读取一次,随后
# 从内存中提供。
#
# 这些列表可能会变化(ADMIN 添加、编辑、删除
# 医生和客户端):因此每次写入都经过这个外观,
# 它会在写入后立即重新加载相关列表。这正是
# 业务层只有唯一入口的意义所在:规则"写入 =>
# 重新加载缓存"只写在这里。
#
# 整个应用只有一个对象,由
# 在多个线程上并行处理的请求使用。因此列表绝不会就地修改:
# 它会被一个新的列表整体替换。在 Python 中,
# 属性的赋值是原子的:读取列表的线程看到的
# 是旧列表或新列表,绝不会是构建到一半的列表。
# =========================================================================
from datetime import date
from rdvmedecins.domain.schedule import DoctorDaySchedule
from rdvmedecins.entities import Client, Slot, Doctor, Appointment
from rdvmedecins.business.person_data import PersonData
from rdvmedecins.business.business import Business
# 与业务层(Business)相同的契约
class ApplicationModel:
def __init__(self, business: Business):
self._business = business
# 两个列表的初始加载,在应用启动时进行。
# 读取错误(数据库无法访问……)不会被捕获:
# 它会终止服务器,而不是让服务器以"空"状态启动
self._doctors: list[Doctor] = []
self._clients: list[Client] = []
self._reload_doctors()
self._reload_clients()
def _reload_doctors(self):
self._doctors = list(self._business.get_all_doctors())
def _reload_clients(self):
self._clients = list(self._business.get_all_clients())
# —— 从缓存读取
def get_all_doctors(self) -> list[Doctor]:
return self._doctors
def get_all_clients(self) -> list[Client]:
return self._clients
# 用户账户为 [user_id] 的医生:用于为已连接的医生
# 预选其自己的日程
def get_doctor_by_user_id(self, user_id: int) -> Doctor | None:
return next((d for d in self._doctors if d.user_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)
# —— 写入 => 重新加载
def add_doctor(self, data: PersonData) -> Doctor:
doctor = self._business.add_doctor(data)
self._reload_doctors()
return doctor
def edit_doctor(self, id: int, data: PersonData) -> Doctor:
doctor = self._business.edit_doctor(id, data)
self._reload_doctors()
return doctor
def delete_doctor(self, id: int) -> None:
self._business.delete_doctor(id)
self._reload_doctors()
def add_client(self, data: PersonData) -> Client:
client = self._business.add_client(data)
self._reload_clients()
return client
def edit_client(self, id: int, data: PersonData) -> Client:
client = self._business.edit_client(id, data)
self._reload_clients()
return client
def delete_client(self, id: int) -> None:
self._business.delete_client(id)
self._reload_clients()
|
Web 层的缓存及其面向业务层的接口:
- 第 32–40 行:医生和患者的列表在启动时读取一次。每次显示日程时都会用到它们(医生的下拉列表、患者列表):把它们保存在内存中,可避免每个页面发出两次 SQL 请求。读取错误不会被捕获:它会导致应用程序在启动时崩溃(参见“常见问题”);
- 第 50–59 行:从缓存中取得的数据。[get_doctor_by_user_id] 用于识别已登录的医生,以便预先选中其自己的日程;
- 第 63–96 行:其他读取操作以及预约操作只是被转发给业务层。[get_client_by_user_id] 不使用缓存:刚刚修改或删除了账户的患者必须看到最新的数据;
- 第 100–126 行:每次对医生或客户的更新都会刷新相应的列表。这就是业务层只有单一入口点的好处:“先更新,再刷新缓存”这条规则只在这里实现。
这个唯一的对象会被多个线程中并行处理的请求使用:因此,列表绝不会被原地修改(通过 [append] 或 [remove]);而是用一个新列表整体替换它。在 [Python] 中,给属性赋值是原子操作:读取列表的线程看到的要么是旧版本,要么是新版本,绝不会是构造了一半的列表。因此无需加锁。
[ApplicationModel] 遵守 [Business] 契约(它拥有与 [BusinessService] 相同的方法):对控制器而言,它就是业务层。我们可以在不改动控制器的情况下去掉缓存,只需直接把 [BusinessService] 放入 [app.extensions]即可。
11.14.7. web/validation.py
| # =========================================================================
# web/validation.py
# -------------------------------------------------------------------------
# 重新显示被拒绝的表单所需的内容:逐个字段的输入错误,
# 以及要用红色轮廓标出的字段。
# =========================================================================
from flask_wtf import FlaskForm
from rdvmedecins.models.view_models import FormState, Message
# -----------------------------------------------------------------------
# 已验证的表单(参见 forms/forms.py)-> 字典
# 字段 -> 消息的键,每个字段只保留第一条消息:
# { "last_name": "ERRORS.LASTNAME_REQUIRED", ... }
#
# 我们的消息是翻译键("ERRORS....")。WTForms 自己
# 写的(英文)消息会被替换为键
# ERRORS.INVALID_FORM。
# -----------------------------------------------------------------------
def errors_of(form: FlaskForm) -> dict[str, str]:
errors = {}
for field, messages in form.errors.items():
message = str(messages[0])
errors[field] = message if message.startswith("ERRORS.") else "ERRORS.INVALID_FORM"
return errors
# -----------------------------------------------------------------------
# 每个"输入"业务错误所涉及的表单字段
# (重复):它们会被红色轮廓标出,消息显示在页面底部
# -----------------------------------------------------------------------
BUSINESS_ERROR_FIELDS = {
"ERRORS.LOGIN_TAKEN": ["login"],
"ERRORS.DOCTOR_ALREADY_EXISTS": ["first_name", "last_name"],
"ERRORS.PATIENT_ALREADY_EXISTS": ["first_name", "last_name"],
}
# 要(重新)显示的表单状态:在被验证拒绝的每个字段下方显示一条消息
# (errors),以及要用红色轮廓标出的字段,
# 即这些字段加上可能的其他字段(other_fields)
def state(errors: dict[str, str], other_fields: list[str] | None = None) -> FormState:
return FormState(dict(errors), set(errors) | set(other_fields or []))
# 页面的唯一错误消息,显示在页面底部:如果有 [error]
# 则为 [error],否则如果有字段错误,则为 "The form contains errors.",
# 否则为空
def page_message(errors: dict[str, str], error: Message | None) -> Message | None:
if error is not None:
return error
return Message("ERRORS.INVALID_FORM") if errors else None
|
重新显示被拒绝的表单所需的内容:
- 第 21–26 行:[WTForms] 表单(示例 19)的错误,以“字段 → 消息键”字典的形式给出,每个字段只保留第一条消息。我们的验证器的消息是翻译键([ERRORS.LASTNAME_REQUIRED],参见 [forms/forms.py]);[WTForms] 自行生成的英文消息会被替换为一个通用键;
- 第 33–36 行:有些业务逻辑错误与特定字段有关,例如已被占用的用户名或拼写相同的姓名。它们的错误消息显示在页面底部,同时受影响的字段会以红色突出显示,使用户能立即看出需要更正什么(参见上文拼写相同姓名的截图);
- 第 43–44 行:待重新显示的表单状态:字段下方的消息,以及所有要以红色突出显示的字段。[set(errors)] 是字典键的集合;运算符 [|] 对两个集合求并集;
- 第 50–53 行:通用的页脚消息。
11.14.8. web/utils.py
| # =========================================================================
# web/utils.py
# -------------------------------------------------------------------------
# Web 层的小型工具函数:
# - 标签:"Mme Alice DURAND";
# - 日期:"yyyy-mm-dd",时间 "8:05",日子 "Wednesday 23 September 2026";
# - 输入:读取浏览器发送的正整数;
# - 用户:已连接的用户及其患者(Client 实体)。
# =========================================================================
import re
from datetime import date, datetime
from babel.dates import format_date
from flask import g
from rdvmedecins.auth.security import InvalidSession
from rdvmedecins.auth.connected_user import ConnectedUser
from rdvmedecins.entities import Client, Slot, Person
# —— 标签
# "Mme Alice DURAND"
def label(p: Person) -> str:
return f"{p.title} {p.first_name} {p.last_name}"
# —— 日期
# URL 和 <input type="date"> 字段中的日期格式
ISO_FORMAT = re.compile(r"\d{4}-\d{2}-\d{2}")
# 如果 [text] 是 yyyy-mm-dd 格式的真实存在的日期,则为该日期;否则为 None。
# strptime 会检查日期是否存在:"2026-02-30" 会被拒绝
def valid_date(text: str | None) -> date | None:
if text is None or not ISO_FORMAT.fullmatch(text):
return None
try:
return datetime.strptime(text, "%Y-%m-%d").date()
except ValueError:
return None
def iso(day: date) -> str:
return day.isoformat()
# "8:05" 而不是 "8:5"
def format_time(h: int, m: int) -> str:
return f"{h}:{m:02d}"
def time(s: Slot) -> str:
return f"{format_time(s.start_hour, s.start_minute)} - {format_time(s.end_hour, s.end_minute)}"
# "mercredi 23 septembre 2026" / "Wednesday 23 September 2026",取决于
# 请求的语言(g.language)。Babel 格式:EEEE 完整的星期几,
# d 日,MMMM 完整的月份,y 年
def format_day(day: date) -> str:
return format_date(day, "EEEE d MMMM y", locale=g.language)
# —— 输入
# "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
# —— 用户
# 已连接的用户(参见 auth/security.py)。受保护的操作
# 只有在用户存在时才会被调用;作为预防措施,用户缺失
# 按会话过期处理。
def user() -> ConnectedUser:
if g.user is None:
raise InvalidSession()
return g.user
# -----------------------------------------------------------------------
# 与已连接用户对应的患者(Client 实体)。
#
# JWT 令牌只包含账户(users.id)的 id。对于 USER
# 角色,通过 clients.user 列找到对应的客户端。
#
# 如果找不到,说明该账户在登录之后已被删除,
# 而其令牌仍然有效:按过期的
# 会话处理(参见 InvalidSession)。
# -----------------------------------------------------------------------
def connected_patient(application) -> Client:
patient = application.get_client_by_user_id(user().user_id)
if patient is None:
raise InvalidSession()
return patient
|
多个控制器使用的工具函数:
- 第 24 行:人员的称谓,“Mme Alice DURAND”;
- 第 31–42 行:解析 [yyyy-mm-dd] 格式的日期,该格式与日程中 URL 输入所用的格式([day=2026-09-26])以及 [<input type="date">] 字段所用的格式相同。正则表达式检查格式([fullmatch]:整个字符串都必须匹配),而 [strptime] 检查日期是否存在。无效日期的结果是 [None]:由操作决定后续处理;
- 第 50–51 行:格式 [02d] 输出用零填充的两位整数:[8:05];
- 第 61–62 行:用 [Babel] (示例 16)以请求所用的语言完整写出的日期。这里明确指定了格式:[EEEE],完整拼写的星期几;[d],日;[MMMM],完整拼写的月份;[y],年份;
- 第 69–73 行:读取浏览器发送的标识符(URL 参数、隐藏字段)。[\d{1,9}]:一到九位数字,这样就排除了字符、空格以及对 [INT] 列而言过大的数字。来自浏览器的任何内容都可能被修改过:使用之前必须先验证;
- 第 82–85 行:已登录的用户;若缺失(在受保护的操作中不应出现这种情况),则视为会话已过期;
- 第 98–102 行:与已登录用户对应的患者(实体 [Client])。令牌只包含账户 ID:患者通过 [clients.user] 列来识别。如果它不存在,就意味着该账户在用户登录之后已被删除。
11.15. 视图的表单和模板
| # =========================================================================
# forms/rules.py
# -------------------------------------------------------------------------
# "person"表单通用的输入规则,以及 WTForms 的过滤器
# (参见示例 19):在验证之前转换所收到值的
# 函数。
# =========================================================================
TITLES = ("Mr", "Mme", "Melle")
# 登录名:小写字母、数字、点、连字符、下划线,最多 30 个字符
LOGIN_FORMAT = r"^[a-z0-9._-]{1,30}$"
# 患者所选密码的最小长度
PASSWORD_MIN = 6
# " dupont " -> "dupont" ; " " -> None
def clean(value):
if not isinstance(value, str):
return value
return value.strip() or None
# " Dupont " -> "dupont":登录名始终为小写
def login(value):
value = clean(value)
return value.lower() if isinstance(value, str) else value
# 空字段 -> None;对于密码,空格不会被删除
# (它们可能是密码的一部分)
def empty_to_none(value):
return value if value else None
# 隐藏字段 [version]:一个整数,如果缺失或为空则为 None。
# 不是数字的文本:会引发 ValueError,WTForms 将其转为
# 字段错误,并附带此消息(一个翻译键)
def version(value):
if value in (None, ""):
return None
try:
return int(value)
except (TypeError, ValueError):
raise ValueError("ERRORS.INVALID_FORM")
|
所有表单共有的输入规则,以及 [WTForms] 过滤器 (示例 19):
- 第 8–14 行:允许的称谓、用户名的格式(小写字母、数字、句点、连字符、下划线,最多 30 个字符),以及患者所选密码的最小长度;
- 第 18–21 行:输入内容前后的空格会被去除;空输入会变成 [None]。[a or b] 等价于 [b] ,当 [a] 为“假”时(此处即空字符串);
- 第 25–27 行:用户名始终为小写;
- 第 32–33 行:对于密码,空格不会被去除,因为它们可能是密码的一部分;
- 第 39–45 行:隐藏的版本字段(乐观锁):一个整数,或 [None]。返回 [ValueError] 之类值的过滤器会触发字段错误,错误消息与该异常的消息一致:提交了数字以外任何内容的浏览器都会收到“无效表单”错误。
| # =========================================================================
# forms/forms.py
# -------------------------------------------------------------------------
# "person"表单的字段及其约束(参见示例
# 19 和 28)。三个表单共用相同的身份字段
# (称谓、名、姓):
#
# PersonFields 称谓、名、姓
# ├─ PersonForm + 可选的登录名 / 密码、version
# │ (ADMIN 添加或编辑医生 / 客户端)
# ├─ RegistrationForm + 必填的登录名 / 密码 / 确认密码
# │ (患者创建自己的账户)
# └─ MyAccountForm + 登录名、可选的新密码、
# 必填的当前密码、version
# (患者编辑自己的账户)
#
# 继承自另一个 WTForms 类的类,也会继承其字段。
#
# 绑定:PersonForm() 自己从当前 POST 请求(request.form)中读取
# 同名字段,并对其应用过滤器
# (去掉多余空格、登录名转小写等)。
# 验证:form.validate() 随后按顺序检查每个
# 字段的约束;第一个失败的约束会把其消息存入
# form.<field>.errors. These messages are translation KEYS (see i18n/*.json)
#
# 这些表单在这里只用于读取和验证输入:视图
# 根据视图模型自行编写 <input> 标签
# (参见 models/view_models.py)。
# =========================================================================
from flask_wtf import FlaskForm
from wtforms import PasswordField, StringField
from wtforms.validators import AnyOf, DataRequired, InputRequired, Length, Optional, Regexp
from rdvmedecins.forms import rules
# —— 公共基类
class PersonFields(FlaskForm):
title = StringField(validators=[AnyOf(rules.TITLES, message="ERRORS.INVALID_TITLE")])
# 最大长度 = SQL 列的长度(VARCHAR(20))。
# 字段为空时,DataRequired 会终止该字段的验证:因此
# Length 的消息绝不会添加到该字段上
first_name = StringField(filters=[rules.clean], validators=[
DataRequired("ERRORS.FIRSTNAME_REQUIRED"),
Length(max=20, message="ERRORS.FIRSTNAME_TOO_LONG")])
last_name = StringField(filters=[rules.clean], validators=[
DataRequired("ERRORS.LASTNAME_REQUIRED"),
Length(max=20, message="ERRORS.LASTNAME_TOO_LONG")])
# —— ADMIN
class PersonForm(PersonFields):
# 可选(参见 business/person_data.py):Optional 会终止
# 空字段的验证,且不报错
login = StringField(filters=[rules.login], validators=[
Optional(), Regexp(rules.LOGIN_FORMAT, message="ERRORS.INVALID_LOGIN")])
# 可选;最多 72 个字符(超出部分 bcrypt 会忽略)
password = PasswordField(filters=[rules.empty_to_none], validators=[
Optional(strip_whitespace=False), Length(max=72, message="ERRORS.PASSWORD_TOO_LONG")])
# 编辑表单的隐藏字段(乐观锁)
version = StringField(filters=[rules.version])
# —— 患者注册
class RegistrationForm(PersonFields):
# InputRequired:输入不能为空
login = StringField(filters=[rules.login], validators=[
InputRequired("ERRORS.LOGIN_REQUIRED"),
Regexp(rules.LOGIN_FORMAT, message="ERRORS.INVALID_LOGIN")])
# 两个 Length 约束,各带一条消息
password = PasswordField(filters=[rules.empty_to_none], validators=[
InputRequired("ERRORS.PASSWORD_REQUIRED"),
Length(min=rules.PASSWORD_MIN, message="ERRORS.PASSWORD_TOO_SHORT"),
Length(max=72, message="ERRORS.PASSWORD_TOO_LONG")])
confirmation = PasswordField(filters=[rules.empty_to_none], validators=[
InputRequired("ERRORS.CONFIRMATION_REQUIRED")])
# —— "管理我的账户"
class MyAccountForm(PersonFields):
login = StringField(filters=[rules.login], validators=[
InputRequired("ERRORS.LOGIN_REQUIRED"),
Regexp(rules.LOGIN_FORMAT, message="ERRORS.INVALID_LOGIN")])
# 可选:为空 = 密码不变
password = PasswordField(filters=[rules.empty_to_none], validators=[
Optional(strip_whitespace=False),
Length(min=rules.PASSWORD_MIN, message="ERRORS.PASSWORD_TOO_SHORT"),
Length(max=72, message="ERRORS.PASSWORD_TOO_LONG")])
confirmation = PasswordField(filters=[rules.empty_to_none])
# 当前密码,任何账户编辑都需要提供
current_password = PasswordField(filters=[rules.empty_to_none], validators=[
InputRequired("ERRORS.CURRENT_PASSWORD_REQUIRED")])
version = StringField(filters=[rules.version])
|
- 第 38–51 行:三个表单共有的字段:称谓、名、姓。验证器的消息是翻译键:视图会把它们翻译成页面的语言。[AnyOf] 验证器接受列表中的某个值。最大长度与 SQL 列的长度一致:更长的输入会被数据库拒绝;
- 第 55–67 行:管理员表单:登录名和可选的密码([Optional] 验证器遇到空字段时会停止验证而不报告错误;[strip_whitespace=False]:由空格组成的密码不被视为空),以及版本;
- 第 71–85 行:患者注册表单:用户名、密码和确认密码都是必填的。两个验证器 [Length],各有自己的消息:太短、太长;
- 第 89–107 行:“管理我的账户”:一个可选的新密码,以及当前密码,任何修改都必须提供当前密码。
一个 [WTForms] 类若继承自另一个类,就会继承其字段:这三个表单共享 [PersonFields] 的字段。密码与确认密码的比较不是由 [EqualTo] 验证器(示例 19)处理的,而是由操作来完成,这样操作就可以选择消息和相关字段。
请注意,这些表单只用于读取和验证用户输入:视图不会调用 [WTForms] 字段来渲染它们(示例 18);相反,视图根据视图模板编写自己的 [<input>] 标签。这种做法使三个表单的视图保持一致,并让操作完全掌控显示的内容(例如绝不显示密码)。这也是应用程序之前各版本所采用的做法。
11.15.3. models/view_models.py
| # =========================================================================
# models/view_models.py
# -------------------------------------------------------------------------
# "视图模型":每个操作传递给其视图的内容,
# 名称为 [model]。它们是数据类:由操作
# 一次性构建的对象,视图只负责读取
# ({{ model.schedule.rows }}……)。
#
# 所有页面都遵循的规则:视图中不放逻辑。
# 操作准备好已经格式化的数据("Mme Marie
# PELISSIER"、"8:00 - 8:20"、selected = True……),并已根据
# 用户的角色过滤;视图只负责把它们放进 HTML。
#
# 每个页面模型有两个字段,由布局(templates/layout.html)读取:
# page_title,页面标题的键;以及 error,页面的唯一错误消息,
# 显示在页面底部(None:没有错误)。
# =========================================================================
from dataclasses import dataclass, field
from rdvmedecins.auth.captcha import Captcha
from rdvmedecins.forms import rules
# 一条待翻译的消息:其键和参数
@dataclass(frozen=True)
class Message:
key: str
params: dict[str, str] = field(default_factory=dict)
# 下拉列表的一个选项(医生、患者)
@dataclass(frozen=True)
class OptionView:
id: int
label: str
selected: bool
# —— 登录
@dataclass
class LoginModel:
page_title: str
error: Message | None
login: str
captcha: Captcha
# —— 日程
@dataclass(frozen=True)
class ScheduleRowView:
slot_id: int
time: str # "8:00 - 8:20"
free: bool
patient: str | None # 已预订时段所显示的姓名;None = "Booked"
mine: bool # 已连接患者的预约
bookable: bool # 是否显示"预订"按钮?
book_url: str
appointment_id: int | None # 仅当显示"取消"按钮时才填写
@dataclass(frozen=True)
class ScheduleView:
doctor: str
day: str
rows: list[ScheduleRowView]
@dataclass(frozen=True)
class BookingView:
slot_id: int
time: str
clients: list[OptionView] # ADMIN / DOCTOR:可供选择的患者
patient: str | None # USER:患者就是其本人
@dataclass
class ScheduleModel:
page_title: str
error: Message | None
doctors: list[OptionView]
doctor_id: int | None
day: str # "yyyy-mm-dd"
schedule: ScheduleView | None
booking: BookingView | None
back_url: str # 所显示的日程,不含预订对话框
# 已有即将到来的预约的患者:解释
# 为何没有"预订"按钮的消息
info: str | None
# —— "person"表单
# 表单字段中显示的值(绝不包含密码)
@dataclass(frozen=True)
class PersonValues:
title: str = "Mr"
first_name: str = ""
last_name: str = ""
login: str = ""
version: int | None = None
# 被拒绝的表单的状态:显示在每个字段下方的消息
# (字段 -> 消息的键),以及要用红色轮廓标出的字段(Bootstrap
# 类 is-invalid):有消息的字段,加上可能的其他字段
# (名 + 姓重复、登录名已被占用等)
@dataclass(frozen=True)
class FormState:
errors: dict[str, str] = field(default_factory=dict)
invalid_fields: set[str] = field(default_factory=set)
def error_of(self, field: str) -> str | None:
return self.errors.get(field)
def invalid_class(self, field: str) -> str:
return "is-invalid" if field in self.invalid_fields else ""
# 称谓列表的一个选项
@dataclass(frozen=True)
class TitleOption:
value: str
selected: bool
# 公共片段 person_fields.html 所使用的内容(称谓、名、姓):
# 一个基类,三个表单模型都从它继承
@dataclass
class FormView:
page_title: str
error: Message | None
values: PersonValues
state: FormState
# 一个属性:像特性一样读取(model.titles),但是计算得出的
@property
def titles(self) -> list[TitleOption]:
return [TitleOption(t, t == self.values.title) for t in rules.TITLES]
@property
def password_min(self) -> int:
return rules.PASSWORD_MIN
@dataclass
class PersonFormModel(FormView):
creating: bool # True:添加;False:编辑
action: str # POST 的 URL
list_url: str
@dataclass
class RegistrationModel(FormView):
pass
@dataclass
class MyAccountModel(FormView):
pass
# —— 医生 / 客户端列表
# 每种人员类型特有的翻译键
@dataclass(frozen=True)
class PersonKeys:
title: str # "Doctors"
add: str # "Add a doctor"
edit: str # "Edit a doctor"
empty: str # "No doctors."
confirm_delete: str # "Delete this doctor and their account?"
added: str # "Doctor {name} has been added (login: {login})."
edited: str
deleted: str
@dataclass(frozen=True)
class PersonView:
title: str
first_name: str
last_name: str
login: str
edit_url: str
delete_url: str
@dataclass
class PersonListModel:
page_title: str
error: Message | None
keys: PersonKeys
add_url: str
persons: list[PersonView]
# —— 患者的区域
@dataclass(frozen=True)
class AppointmentView:
id: int
day: str
time: str
doctor: str
schedule_url: str
@dataclass
class AreaModel:
page_title: str
error: Message | None
patient: str
appointments: list[AppointmentView]
# —— 错误页面
@dataclass
class ErrorModel:
page_title: str
error: Message | None
code: int
message: str
|
视图模型 (*view models*):每个操作传给其视图的内容,名称为 [model]。所有页面都遵循的规则是:视图中没有逻辑。操作准备好已格式化的数据(“Mme Marie PELISSIER”、“8:00 – 8:20”),并已根据用户角色过滤;视图只需把这些数据放入 HTML。
- 第 26–28 行:一条待翻译的消息:一个键及其参数。[field(default_factory=dict)]:默认值是为每个对象创建的新的空字典。不能写成 [= {}]:这个字典只会创建一次,并被所有对象共享;
- 第 33–36 行:下拉列表中的一个选项;
- 第 41–45 行:登录页面的模板。每个页面模板都有两个供模板读取的字段:[page_title],页面标题键;以及 [error],显示在页面底部的错误消息;
- 第 50–58 行:日程中的一行,已针对已登录用户填充好:当用户是患者时,对于被其他患者占用的时间段,[patient] 等于 [None] (视图将显示“已预订”);[bookable] 表示是否显示“预订”按钮;[appointment_id] 仅在要显示“取消”按钮时才会填充。所有这些决定都由操作做出;
- 第 69–73 行:预订窗口:对管理员或医生是患者列表,对患者则是患者本人的姓名;
- 第 77–88 行:日程页面的模板;
- 第 108–116 行:被拒绝表单的状态,包含视图调用的两个方法:字段的消息,以及将其标红的 CSS 类;
- 第 129–142 行:三个表单模板的基类,由公共片段 [person_fields.html] 使用。它的两个属性 计算称谓列表(包括所选的称谓)和密码的最小长度;
- 第 146–158 行:三个表单模板继承自 [FormView]。继承自另一个类的 [dataclass] 会把自己的字段添加到父类的字段之后;
- 第 166–174 行:医生或客户特有的翻译键:同一个视图同时显示这两个列表;
- 第 198–211 行:患者区域;
- 第 216–220 行:错误页面。
11.16. Web 层:控制器
[controllers] 文件夹为应用程序的每个部分包含一个蓝图(登录控制器 [controllers/auth.py] 已在身份验证部分介绍过):
蓝图 | 地址 |
[language] | [GET /language/<code>] |
[schedule] | [GET /schedule], [POST /schedule/book], [POST /schedule/cancel] |
[doctors]、[clients] | [/doctors/...]、[/clients/...]:列表、添加、编辑、删除 |
[registration] | [POST /register/access]、[GET] 和 [POST /register] |
[area] | [/my-area], [/my-area/cancel], [/my-account], [/my-account/delete] |
所有操作都遵循相同的模式:读取并验证请求,调用业务层(通过 [ApplicationModel]),构建视图模型;或者,对于 POST 这类操作,发出一条闪现消息并重定向(PRG 流程,示例 20)。
11.16.1. controllers/language.py
| # =========================================================================
# controllers/language.py
# -------------------------------------------------------------------------
# GET /language/fr、GET /language/en:导航栏中的 FR / EN
# 两个按钮。公开路由:必须能在登录之前
# 更改语言。
#
# 选择会记在 Cookie 中:在随后的每个请求中,
# set_language 函数(参见 rdvmedecins/__init__.py)会重新读取它并设置
# 请求的语言(g.language)。然后回到来源页面。
# =========================================================================
from datetime import timedelta
from urllib.parse import urlsplit
from flask import Blueprint, abort, current_app, redirect, request
from rdvmedecins.auth.security import public
from rdvmedecins.web.translator import LANGUAGE_COOKIE, LANGUAGES
language = Blueprint("language", __name__)
@language.get("/language/<code>")
@public
def change(code: str):
if code not in LANGUAGES:
abort(404) # -> 404 错误页面(参见 web/errors.py)
response = redirect(origin_page())
response.set_cookie(LANGUAGE_COOKIE, code, max_age=timedelta(days=365), path="/",
httponly=True, samesite="Lax", secure=current_app.config["COOKIE_SECURE"])
return response
# -----------------------------------------------------------------------
# 上一个页面,根据浏览器发送的 HTTP "Referer"
# 请求头。只保留其路径(/schedule?...):如果重定向到
# 请求提供的完整地址,就可能把
# 用户送到另一个站点(即所谓的"开放重定向"漏洞)。
# -----------------------------------------------------------------------
def origin_page() -> str:
referer = request.headers.get("Referer")
if not referer:
return "/"
url = urlsplit(referer)
path = url.path
# "//site.com/..." 会被浏览器理解为
# 位于其他站点:同样被拒绝
if not url.scheme or not path.startswith("/") or path.startswith("//") \
or path.startswith("/language/"):
return "/"
return f"{path}?{url.query}" if url.query else path
|
示例 22 中的语言选择,在 [origin_page] (第 40–51 行)中增加了两项预防措施:没有协议([Referer] 、[http]、[https])的 [Referer]不是完整的地址;而本身就是 [/language/...] 地址的 Referer 会重定向回这个操作,形成循环。在这两种情况下,用户都会被重定向回站点的根路径。Cookie 的生存期由 [timedelta] 指定:[set_cookie] 同样接受它,就像接受秒数一样。
应用程序的主页面,面向所有角色。
| # =========================================================================
# controllers/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(患者) | "Booked",如果是其本人的预约则显示 | 为自己预订,如果 | 否 (*) |
# | | 其本人姓名 | 没有即将到来的 | |
# | | | 预约 | |
#
# (*) 患者在其"我的区域"页面中取消自己的预约。
#
# 保密性:对于患者,其他患者的姓名
# 并不是简单地由视图隐藏,而是根本不会放入传递给视图的
# 模型中。因此发送到浏览器的 HTML 并不包含这些姓名,
# 即使是隐藏的也没有(否则只需"查看页面源代码"就会暴露)。
#
# 不能预订过去的时间:只有今天及之后的日子才会
# 出现"预订"按钮(而且业务层
# 无论如何也会拒绝)。
#
# 安全性:所有 /schedule URL 都需要已通过身份验证的用户
# (参见 auth/security.py:所有不是 @public 的内容)。操作上的 @roles_required
# 还额外要求具有所列角色之一。没有有效令牌:
# 返回 /login;角色不足:显示 403 页面。
# =========================================================================
from dataclasses import dataclass
from datetime import date
from flask import Blueprint, abort, redirect, render_template, request, url_for
from rdvmedecins.auth.security import roles_required
from rdvmedecins.domain.schedule import DoctorDaySchedule
from rdvmedecins.entities import Client, Person, Role
from rdvmedecins.business import dates
from rdvmedecins.business.exception import BusinessException
from rdvmedecins.models.view_models import (ScheduleModel, ScheduleView, ScheduleRowView, Message,
OptionView, BookingView)
from rdvmedecins.web import utils
from rdvmedecins.web.flash import flash_error, flash_success
from rdvmedecins.web.services import application
schedule = Blueprint("schedule", __name__, url_prefix="/schedule")
# 控制器对用户了解的信息,用于决定显示什么
@dataclass(frozen=True)
class Rights:
manager: bool # ADMIN 或 DOCTOR
patient: Client | None # 已连接的客户端(USER 角色),否则为 None
patient_can_book: bool # 没有即将到来的预约的 USER
# -----------------------------------------------------------------------
# GET /schedule
# URL 参数按原始值读取(request.args.get),以便
# 区分缺失的参数(None)和空参数(?doctorId=)。
# -----------------------------------------------------------------------
@schedule.get("")
def show():
error = None
user = utils.user()
rights = compute_rights()
# 日期:URL 中的日期(如果有效),否则为今天
day = dates.today()
raw_day = request.args.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 = "ERRORS.INVALID_DATE"
day_bookable = day >= dates.today()
# 医生:URL 中的医生;没有的话,对于已连接的医生,则为其本人
raw_doctor_id = request.args.get("doctorId")
doctor_id = utils.positive_integer(raw_doctor_id)
if raw_doctor_id is None and user.role == Role.DOCTOR:
doctor = application().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 application().get_all_doctors()]
# 如果选定了医生(且日期有效),则为日程
view = None
if doctor_id is not None and error is None:
doctor_schedule = application().get_doctor_day_schedule(doctor_id, day)
if doctor_schedule is None:
error = "ERRORS.DOCTOR_NOT_FOUND"
else:
view = schedule_view(doctor_schedule, rights, day_bookable)
# 预订对话框:仅当所请求的时段
# 可由该用户预订时才显示
booking = None
slot_id = utils.positive_integer(request.args.get("book"))
if view is not None and slot_id is not None:
row = next((r for r in view.rows if r.slot_id == slot_id and r.bookable),
None)
if row is not None:
booking = BookingView(
row.slot_id,
row.time,
[option(c, False) for c in application().get_all_clients()]
if rights.manager else [],
utils.label(rights.patient) if rights.patient else None)
model = ScheduleModel(
page_title="SCHEDULE.PAGE_TITLE",
error=Message(error) if error else None,
doctors=doctors,
doctor_id=doctor_id,
day=utils.iso(day),
schedule=view,
booking=booking,
back_url=schedule_url(doctor_id, day) if doctor_id is not None else url_for("schedule.show"),
info=patient_info(rights, view))
return render_template("schedule.html", model=model)
# -----------------------------------------------------------------------
# POST /schedule/book 字段:doctorId、day、slotId、clientId
#
# 对于患者(USER),clientId 字段会被忽略:他们始终为
# 自己预订。信任浏览器发送的字段,
# 会让聪明的患者得以以他人的名义预订。
#
# "Post / Redirect / Get"模式:无论结果如何,这里都不
# 构建页面,而是设置一条 flash 消息并重定向
# 到日程页面(参见示例 20)。
# -----------------------------------------------------------------------
@schedule.post("/book")
@roles_required(Role.ADMIN, Role.DOCTOR, Role.USER)
def book():
doctor_id, day = read_schedule_request()
slot_id = utils.positive_integer(request.form.get("slotId"))
if doctor_id is None or slot_id is None:
abort(400) # -> "invalid request" 页面(参见 web/errors.py)
user = utils.user()
if user.is_patient:
client = utils.connected_patient(application())
else:
client_id = utils.positive_integer(request.form.get("clientId"))
if client_id is None:
# 未选择患者:重新打开预订对话框
flash_error("ERRORS.CHOOSE_PATIENT")
return redirect(schedule_url(doctor_id, day, slot_id))
client = application().get_client_by_id(client_id)
slot = application().get_slot_by_id(slot_id)
if client is None:
flash_error("ERRORS.PATIENT_NOT_FOUND")
elif slot is None or slot.doctor_id != doctor_id:
flash_error("ERRORS.SLOT_NOT_FOUND")
else:
try:
# 规则(不能在过去、每位患者只能有一个即将到来的
# 预约、时段空闲)由业务层检查
application().add_appointment(day, slot, client)
flash_success("SCHEDULE.BOOKED")
except BusinessException as e:
# 同一规则,但当预订的是患者本人时,使用第二人称
# 消息("You already have...",而不是
# "This patient...")。其他异常(真正的
# 异常情况)不会被捕获:显示 500 页面。
if e.key == "ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT" and user.is_patient:
flash_error("SCHEDULE.ALREADY_BOOKED_INFO")
else:
flash_error(e.key, **e.params)
return redirect(schedule_url(doctor_id, day))
# -----------------------------------------------------------------------
# POST /schedule/cancel 字段:appointmentId、doctorId、day
# (患者在"我的区域"取消自己的预约,而不是在这里)
# -----------------------------------------------------------------------
@schedule.post("/cancel")
@roles_required(Role.ADMIN, Role.DOCTOR)
def cancel():
doctor_id, day = read_schedule_request()
appointment_id = utils.positive_integer(request.form.get("appointmentId"))
if doctor_id is None or appointment_id is None:
abort(400)
appointment = application().get_appointment_by_id(appointment_id)
if appointment is None:
# 已被取消(被他人取消,或双击所致)
flash_error("ERRORS.APPOINTMENT_NOT_FOUND")
else:
application().delete_appointment(appointment)
flash_success("SCHEDULE.CANCELLED")
return redirect(schedule_url(doctor_id, day))
# -----------------------------------------------------------------------
# 谁已连接,他们在此页面上可以做什么?
# -----------------------------------------------------------------------
def compute_rights() -> Rights:
if not utils.user().is_patient:
return Rights(True, None, False)
patient = utils.connected_patient(application())
upcoming = application().get_client_upcoming_appointments(patient.id)
return Rights(False, patient, not upcoming)
# -----------------------------------------------------------------------
# 医生的日程,已为视图格式化,并根据权限过滤
# -----------------------------------------------------------------------
def schedule_view(doctor_schedule: DoctorDaySchedule, rights: Rights, day_bookable: bool) -> ScheduleView:
doctor_id = doctor_schedule.doctor.id
day = doctor_schedule.day
rows = []
for dds in doctor_schedule.doctor_day_slots:
slot, appointment = dds.slot, dds.appointment
free = appointment is None
# 已连接患者的预约?
mine = appointment is not None and rights.patient is not None and appointment.client_id == rights.patient.id
rows.append(ScheduleRowView(
slot_id=slot.id,
time=utils.time(slot),
free=free,
# 保密性的关键点:患者只会收到
# 自己预约的姓名;其他的则为 None(视图显示 "Booked")
patient=utils.label(appointment.client) if appointment is not None and (rights.manager or mine) else None,
mine=mine,
bookable=free and day_bookable 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(utils.label(doctor_schedule.doctor), utils.format_day(day), rows)
# —— 工具函数
# POST 表单的隐藏字段 doctorId / day;如果无效则为 (None, None)
def read_schedule_request() -> tuple[int | None, date | None]:
doctor_id = utils.positive_integer(request.form.get("doctorId"))
day = utils.valid_date(request.form.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]:url_for 会在
# URL 末尾添加不属于路径变量的参数
def schedule_url(doctor_id: int, day: date, book: int | None = None) -> str:
if book is None:
return url_for("schedule.show", doctorId=doctor_id, day=utils.iso(day))
return url_for("schedule.show", doctorId=doctor_id, day=utils.iso(day), book=book)
def option(p: Person, selected: bool) -> OptionView:
return OptionView(p.id, utils.label(p), selected)
# -----------------------------------------------------------------------
# 已有即将到来的预约的患者所看到的提示消息
# (为何没有"预订"按钮),或 None。如果其
# 预约出现在所显示的日程中(蓝色),则无用:这种情况正是
# 在他们刚刚预订之后,此时该消息就不合适了。
# -----------------------------------------------------------------------
def patient_info(rights: Rights, view: ScheduleView | None) -> str | None:
if rights.patient is None or rights.patient_can_book:
return None
appointment_shown = view is not None and any(row.mine for row in view.rows)
return None if appointment_shown else "SCHEDULE.ALREADY_BOOKED_INFO"
|
11.16.2.1. 页面的 URL
整个页面由其 URL 描述:[/schedule?doctorId=1&day=2026-09-26] 显示 1 号医生当天的日程;[&book=4] 还会打开 4 号时间段的预订窗口。因此,预约预订窗口不是由 [JavaScript] 打开的:而是服务器生成包含该窗口的页面。这意味着可以重新加载页面、将其加入书签、使用浏览器的“后退”按钮,并且应用程序在没有 [JavaScript] 的情况下也能工作(应用程序唯一的脚本用于确认窗口,没有它也能工作;参见示例 21)。
11.16.2.2. GET /schedule
- 第 65–68 行:为确定显示内容,操作所了解的用户信息:是“管理者”(ADMIN 或 DOCTOR),还是可以预订或不能预订的患者;
- 第 83–91 行:日期:如果 URL 中指定的日期有效,则使用它;否则使用今天。参数以原始格式读取([request.args.get]),以便区分缺失的参数([None]:使用默认值,不报错)和无效的参数(报告错误)。只有今天及之后的日期才可预订;
- 第 94–98 行:医生:使用 URL 中指定的医生;否则,对已登录的医生就是其本人:医生登录后可以直接查看自己的每日日程;
- 第 101 行:医生的下拉列表,从缓存中读取,并突出显示所选医生;
- 第 104–110 行:日程,前提是选中了医生且日期有效。不存在的医生(手动修改了 URL 中的 ID)会触发错误消息,而不是错误页面;
- 第 114–125 行:预订窗口,仅当所请求的时间段存在并且该用户可以预订它时才显示:如果患者在 URL 中为一个已被预订的时间段添加 [&book=2] ,将什么也看不到。[next(...)] 查找对应的日程条目(示例 21)。窗口对管理员显示患者列表;对每位患者,则显示其本人的姓名;
- 第 127–137 行:页面模板。[back_url] 是不带预订窗口的日程 URL;窗口中的“取消”按钮会把你带到那里。
11.16.2.3. POST /schedule/book
- 第 152 行:所有角色都可以预订。装饰器记录了这条规则,并在将来出现第四种角色时保护它;
- 第 154–157 行:表单的隐藏字段。无效字段只可能来自手工构造的请求:错误 400;
- 第 160–168 行:预约所属的患者。对患者而言,它始终是患者本人:字段 [clientId] 会被忽略。信任浏览器发送的字段会让患者能够替他人预订。对于没有选择患者的管理员,预订窗口会带着一条消息重新打开;
- 第 170–189 行:验证(患者存在,时间段存在且属于日程中的医生),然后进行预订。业务规则由业务逻辑层验证;[BusinessException] 会变成一条闪现错误消息。当患者自己进行预订时,“只能有一个未来的预约”这条消息会做相应调整(用“您已经有……”而不是“该患者已经有……”);
- 第 190 行:无论何种情况,都返回日程(PRG 模式)。
11.16.2.4. POST /schedule/cancel
- 第 197–211 行:取消预约,仅限管理员(患者在自己的账户中取消预约)。已被取消的预约(被他人取消或双击所致)会显示一条消息,而不是错误。
11.16.2.5. 权限、格式化的日程和工具函数
- 第 217–222 行:用户权限。对患者而言,需要查看其未来的预约:空列表为“不正确”,因此使用 [not upcoming];
- 第 228–248 行:该日的日程,已格式化以便显示,并根据权限进行了过滤。患者保密性正体现在这里(第 243 行):对患者而言,其他患者的姓名不仅仅是不显示;它们根本不会被放入模板。因此,发送给浏览器的 HTML 中并不包含它,即使是隐藏的也没有(否则,简单的“查看源代码”就会泄露出来)。只有存在可用的时间段、可预订的日期以及有权预订的用户时,才会出现“预订”按钮;“取消”按钮只对管理员出现;
- 第 254–257 行:POST 表单中经过验证的隐藏字段 [doctorId] and [day] ;
- 第 262–265 行:日程的 URL。[url_for] 会把不属于路径变量的具名参数作为参数添加到 URL 中(示例 16);
- 第 278–282 行:针对已有未来预约的患者的提示消息:它解释了为什么缺少“预订”按钮。如果患者自己的预约出现在日程中(以蓝色显示),即预订之后立刻出现的情况,则不显示该消息。[any(...)] 在任一条件为真时返回 [True] 。
11.16.3. controllers/persons.py
医生和客户的管理仅限管理员使用,且完全相同:同样的列表、同样的表单、同样的规则。我们不把相同的操作写两遍,而是在一个蓝图工厂中只写一次。
| # =========================================================================
# controllers/persons.py
# -------------------------------------------------------------------------
# 医生的管理和客户端的管理(仅限 ADMIN)是
# 相同的:同样的列表、同样的表单、同样的规则。与其
# 把相同的操作写两遍,不如只写一次,放在
# 蓝图工厂中:create_blueprint 函数根据一个"配置"构建
# 完整的蓝图,该配置说明要调用什么,以及
# 要显示哪些标签。controllers/doctors.py 和 controllers/clients.py
# 各自用自己的配置调用它。这样,对于每一个,我们都得到:
#
# GET /doctors 列表
# GET /doctors/add 空表单
# POST /doctors/add 创建
# GET /doctors/<id>/edit 预填的表单
# POST /doctors/<id>/edit 编辑
# POST /doctors/<id>/delete 删除
#
# (/clients 下的 URL 也是如此)。视图也是通用的:
# templates/persons/list.html 和 templates/persons/form.html。
#
# 安全性:蓝图自己的 before_request 要求 ADMIN 角色。它
# 在蓝图的每个操作之前运行,包括以后
# 添加到其中的操作:规则只需写一次,一劳永逸。
# =========================================================================
from collections.abc import Callable
from dataclasses import dataclass
from flask import Blueprint, abort, redirect, render_template, url_for
from rdvmedecins.auth.security import require_roles
from rdvmedecins.entities import Person, Role
from rdvmedecins.forms.forms import PersonForm
from rdvmedecins.business.person_data import PersonData
from rdvmedecins.business.exception import BusinessException
from rdvmedecins.models.view_models import (PersonKeys, FormState, PersonFormModel,
PersonListModel, Message, PersonView,
PersonValues)
from rdvmedecins.web import validation
from rdvmedecins.web.flash import flash_error, flash_success
# -----------------------------------------------------------------------
# 每种人员类型必须提供的内容。最后五个字段
# 是函数:doctors.py 和 clients.py 在其中放入 lambda,
# 它们调用 ApplicationModel 的方法(get_all_doctors……)。
# -----------------------------------------------------------------------
@dataclass(frozen=True)
class PersonsConfig:
name: str # "doctors" 或 "clients":蓝图的名称,以及 URL 的开头
keys: PersonKeys
list: Callable[[], list[Person]] # () -> 列表
find: Callable[[int], Person | None] # id -> 人员
add: Callable[[PersonData], Person] # data -> 所创建的人员
edit: Callable[[int, PersonData], Person] # (id, data) -> 所编辑的人员
delete: Callable[[int], None] # id -> 无
def create_blueprint(config: PersonsConfig) -> Blueprint:
bp = Blueprint(config.name, __name__, url_prefix=f"/{config.name}")
# 该蓝图中某个操作的 URL:url("list_persons") -> "/doctors"
def url(action: str, **params) -> str:
return url_for(f"{config.name}.{action}", **params)
# 该蓝图的所有操作都仅限 ADMIN
@bp.before_request
def admin_only():
require_roles(Role.ADMIN)
# -------------------------------------------------------------------
# GET /doctors(或 /clients)
# -------------------------------------------------------------------
@bp.get("")
def list_persons():
persons = [PersonView(p.title, p.first_name, p.last_name, login(p),
url("edit_form", id=p.id),
url("delete", id=p.id))
for p in config.list()]
model = PersonListModel(config.keys.title, None, config.keys, url("add_form"),
persons)
return render_template("persons/list.html", model=model)
# -------------------------------------------------------------------
# GET /doctors/add
# -------------------------------------------------------------------
@bp.get("/add")
def add_form():
return show_form(None, PersonValues(), {}, None, None)
# -------------------------------------------------------------------
# POST /doctors/add
# PersonForm() 读取输入;validate() 检查输入。
# -------------------------------------------------------------------
@bp.post("/add")
def add():
form = PersonForm()
if not form.validate():
return show_form(None, entered_values(form), validation.errors_of(form),
None, None)
try:
person = config.add(data(form))
except BusinessException as e:
return show_business_error(None, entered_values(form), e)
flash_success(config.keys.added, **params(person))
return redirect(url("list_persons"))
# -------------------------------------------------------------------
# GET /doctors/<id>/edit
# <int:id>:id 必须由数字组成:/doctors/abc/edit
# 不匹配任何路由(404 页面)
# -------------------------------------------------------------------
@bp.get("/<int:id>/edit")
def edit_form(id: int):
person = config.find(id)
if person is None:
abort(404)
values = PersonValues(person.title, person.first_name, person.last_name, login(person),
person.version)
return show_form(id, values, {}, None, None)
# -------------------------------------------------------------------
# POST /doctors/<id>/edit
# -------------------------------------------------------------------
@bp.post("/<int:id>/edit")
def edit(id: int):
form = PersonForm()
if not form.validate():
return show_form(id, entered_values(form), validation.errors_of(form),
None, None)
try:
person = config.edit(id, data(form))
except BusinessException as e:
return show_business_error(id, entered_values(form), e)
flash_success(config.keys.edited, **params(person))
return redirect(url("list_persons"))
# -------------------------------------------------------------------
# POST /doctors/<id>/delete
# (在发送表单之前会请求"Are you sure?"确认,
# 参见 static/js/app.js)
# -------------------------------------------------------------------
@bp.post("/<int:id>/delete")
def delete(id: int):
person = config.find(id)
try:
config.delete(id)
flash_success(config.keys.deleted, **params(person))
except BusinessException as e:
flash_error(e.key, **e.params)
return redirect(url("list_persons"))
# —— 内部函数
# id 为 None:创建表单;否则:编辑表单。
# errors:字段 -> 消息的键;error:页面底部消息的键;
# other_fields:要额外用红色轮廓标出的字段
def show_form(id: int | None, values: PersonValues, errors: dict[str, str],
error: str | None, other_fields: list[str] | None):
creating = id is None
state: FormState = validation.state(errors, other_fields)
model = PersonFormModel(
page_title=config.keys.add if creating else config.keys.edit,
error=validation.page_message(errors, Message(error) if error else None),
values=values,
state=state,
creating=creating,
action=url("add") if creating else url("edit", id=id),
list_url=url("list_persons"))
return render_template("persons/form.html", model=model)
# 某条业务规则拒绝了写入:重新显示表单,
# 并带上用户的输入和业务层的消息
def show_business_error(id: int | None, values: PersonValues, e: BusinessException):
if e.key in ("ERRORS.DOCTOR_NOT_FOUND", "ERRORS.PATIENT_NOT_FOUND"):
# 在此期间已被另一个 ADMIN 删除:返回列表
flash_error(e.key)
return redirect(url("list_persons"))
# 消息显示在页面底部;所涉及的字段(如果有)会
# 用红色轮廓标出,让用户立刻看出要改正什么
return show_form(id, values, {}, e.key, validation.BUSINESS_ERROR_FIELDS.get(e.key))
return bp
# 用户输入的内容(不含密码:它绝不会被送回
# 浏览器)。form.<field>.data:经过过滤器之后的值
def entered_values(form: PersonForm) -> PersonValues:
return PersonValues(form.title.data or "", form.first_name.data or "", form.last_name.data or "",
form.login.data or "", form.version.data)
# 已验证的表单 -> 业务层期望的数据
def data(form: PersonForm) -> PersonData:
return PersonData(form.title.data, form.last_name.data, form.first_name.data, form.login.data,
form.password.data, form.version.data)
# "已添加 / 已编辑 / 已删除"消息中的 {name} 和 {login}
def params(person: Person | None) -> dict[str, str]:
if person is None:
return {"name": "", "login": ""}
return {"name": f"{person.first_name} {person.last_name}", "login": login(person)}
def login(person: Person) -> str:
return person.user.login if person.user else ""
|
- 第 49–56 行:每种实体类型必须提供的内容:蓝图名称(同时也是 URL 的开头部分)、翻译键,以及五个函数:列表、查找、添加、编辑和删除。这与业务层描述符的做法相同;
- 第 59–60 行:工厂创建一个蓝图,其名称和 URL 前缀来自配置。这些操作是 内部函数 ,属于 [create_blueprint]:它们可以访问工厂的变量 [config]。每次调用 [create_blueprint] 都会创建一个带有各自操作的新蓝图;
- 第 63–64 行:此蓝图中某个操作的 URL:[url("list_persons")] returns [/doctors] 对医生蓝图返回如上,对客户蓝图则返回 [/clients] ;
- 第 67–69 行:蓝图级的 [before_request]:它在该蓝图中的每个操作之前运行(并且仅限于这个蓝图),在应用程序级的 before_request 之后执行。因此所有操作都只限管理员使用,包括以后可能添加的操作:规则只写一次,适用于所有操作;
- 第 74–82 行:列表。[@bp.get("")]:路由就是蓝图本身的前缀([/doctors]);
- 第 95–106 行:添加操作:表单验证(输入错误,显示在字段下方)、调用业务层(业务错误,显示在页面底部),然后是闪现消息并重定向到列表。闪现消息接收参数:人员的姓名和登录名;
- 第 113–120 行:编辑表单,预先填入记录的版本(乐观锁)。不存在的人员会得到 404 页面;
- 第 125–136 行:更新,仿照添加操作;
- 第 143–151 行:删除操作,事先由确认窗口确认(示例 21)。业务层的拒绝(有预约的医生)会导致一条闪现错误消息;
- 第 158–170 行:添加表单([id] 等于 [None])或编辑表单,以及它的状态(值、错误、标红的字段);
- 第 174–181 行:业务错误:已被另一位管理员删除的人员会被送回列表;其他情况则重新显示表单,并将相关字段标红;
- 第 188–190 行:要重新显示的值:用户输入的内容,绝不包括密码;
- 第 194–196 行:已验证的表单,转换为供业务层使用的数据;
- 第 200–203 行:“已添加/已修改/已删除”消息的参数。
11.16.4. controllers/doctors.py 和 controllers/clients.py
| # =========================================================================
# controllers/doctors.py
# -------------------------------------------------------------------------
# 医生的管理(仅限 ADMIN 角色)。所有操作都
# 由 controllers/persons.py 构建:这里只需说明要调用
# 什么,以及要显示哪些标签。
#
# 配置中的函数是 LAMBDA(没有名字、
# 就地编写的函数):application() 只在
# 操作运行时(即请求期间)才被调用,在导入此模块时
# ApplicationModel 还不存在。
# =========================================================================
from rdvmedecins.controllers.persons import PersonsConfig, create_blueprint
from rdvmedecins.models.view_models import PersonKeys
from rdvmedecins.web.services import application
doctors = create_blueprint(PersonsConfig(
name="doctors",
keys=PersonKeys(
title="DOCTORS.TITLE",
add="DOCTORS.ADD",
edit="DOCTORS.EDIT",
empty="DOCTORS.EMPTY",
confirm_delete="DOCTORS.DELETE_CONFIRM",
added="DOCTORS.ADDED",
edited="DOCTORS.UPDATED",
deleted="DOCTORS.DELETED"),
list=lambda: application().get_all_doctors(),
find=lambda id: application().get_doctor_by_id(id),
add=lambda data: application().add_doctor(data),
edit=lambda id, data: application().edit_doctor(id, data),
delete=lambda id: application().delete_doctor(id)))
|
医生蓝图,由 [create_blueprint] 连同其配置一起生成。配置函数是匿名函数 ([lambda]),它们调用 [ApplicationModel]。为什么不直接写 [list=application().get_all_doctors] 呢?因为这个模块在被导入时(即启动时)就会执行,早于 应用程序的创建:[application()] 需要 [current_app],因而会失败。匿名函数把调用推迟到操作在请求期间执行时。
| # =========================================================================
# controllers/clients.py
# -------------------------------------------------------------------------
# 客户端(诊所的患者)的管理,仅限 ADMIN 角色。
# 原理与 controllers/doctors.py 相同(参见其注释)。
# =========================================================================
from rdvmedecins.controllers.persons import PersonsConfig, create_blueprint
from rdvmedecins.models.view_models import PersonKeys
from rdvmedecins.web.services import application
clients = create_blueprint(PersonsConfig(
name="clients",
keys=PersonKeys(
title="CLIENTS.TITLE",
add="CLIENTS.ADD",
edit="CLIENTS.EDIT",
empty="CLIENTS.EMPTY",
confirm_delete="CLIENTS.DELETE_CONFIRM",
added="CLIENTS.ADDED",
edited="CLIENTS.UPDATED",
deleted="CLIENTS.DELETED"),
list=lambda: application().get_all_clients(),
find=lambda id: application().get_client_by_id(id),
add=lambda data: application().add_client(data),
edit=lambda id, data: application().edit_client(id, data),
delete=lambda id: application().delete_client(id)))
|
客户蓝图,遵循相同的模式。
11.16.5. controllers/registration.py
| # =========================================================================
# controllers/registration.py
# -------------------------------------------------------------------------
# "创建患者账户":还没有账户的患者
# 自己创建账户。公开路由(根据定义,
# 此时还没有账户):
#
# POST /register/access 身份验证页面的"创建患者账户"
# 按钮:检查该页面的验证码,
# 然后打开表单
# GET /register 表单
# POST /register 创建,然后返回登录页面
#
# 该流程只用一个验证码来防范机器人,即
# 身份验证页面的验证码:
# 1. "创建患者账户"按钮将登录表单发送
# 到 /register/access;如果验证码输入正确,服务器
# 会签发一张通行证(参见 auth/registration_pass.py);
# 2. 没有有效的通行证,/register 会重定向回
# 身份验证页面:直接输入 URL 没有用;
# 3. 通行证在创建账户时被消耗:解出一个验证码
# 只能创建一个账户;
# 4. 此外,每个 IP 地址每小时创建的账户数
# 也有限制(参见 auth/limiter.py)。
#
# 所创建的账户与 ADMIN 在"患者"页面中
# 创建的完全一样(同一个业务层方法:add_client),区别
# 在于患者自己选择登录名和密码(必填,
# 并需确认)。
# =========================================================================
from flask import Blueprint, current_app, redirect, render_template, request, url_for
from rdvmedecins.auth import registration_pass
from rdvmedecins.auth.security import public
from rdvmedecins.controllers.auth import ip_address
from rdvmedecins.forms.forms import RegistrationForm
from rdvmedecins.business.person_data import PersonData
from rdvmedecins.business.exception import BusinessException
from rdvmedecins.models.view_models import RegistrationModel, Message, PersonValues
from rdvmedecins.web import validation
from rdvmedecins.web.flash import flash_error, flash_success
from rdvmedecins.web.services import application, captchas, limiter, passes
registration = Blueprint("registration", __name__, url_prefix="/register")
# -----------------------------------------------------------------------
# POST /register/access 字段:captchaId、captcha(来自
# 身份验证页面;同时发送的登录名和密码会被忽略)
# -----------------------------------------------------------------------
@registration.post("/access")
@public
def access():
ip = ip_address()
# 该地址最近创建的账户过多:无需再继续
minutes = limiter().registration_block_minutes(ip)
if minutes > 0:
flash_error("ERRORS.TOO_MANY_ACCOUNTS", minutes=str(minutes))
return redirect(url_for("auth.show_login"))
# 验证码缺失或错误:返回身份验证页面,并显示
# 新的图像(失败计为一次登录失败)
if not captchas().verify(request.form.get("captchaId"), request.form.get("captcha")):
limiter().login_failure(ip, "")
flash_error("ERRORS.CAPTCHA_BEFORE_ACCOUNT")
return redirect(url_for("auth.show_login"))
# 验证码正确:签发通行证并打开表单
response = redirect(url_for("registration.form"))
registration_pass.set_cookie(response, passes().issue(), current_app.config["COOKIE_SECURE"])
return response
# -----------------------------------------------------------------------
# GET /register
# -----------------------------------------------------------------------
@registration.get("")
@public
def form():
if not passes().is_valid(request.cookies.get(registration_pass.COOKIE)):
return back_to_login()
return show(PersonValues(), {}, None, None)
# -----------------------------------------------------------------------
# POST /register
# -----------------------------------------------------------------------
@registration.post("")
@public
def create():
pass_id = request.cookies.get(registration_pass.COOKIE)
if not passes().is_valid(pass_id):
return back_to_login()
ip = ip_address()
form = RegistrationForm()
form.validate()
values = PersonValues(form.title.data or "Mr", form.first_name.data or "",
form.last_name.data or "", form.login.data or "", None)
# 1. 该地址最近创建的账户过多?
minutes = limiter().registration_block_minutes(ip)
if minutes > 0:
return show(values, {}, Message("ERRORS.TOO_MANY_ACCOUNTS", {"minutes": str(minutes)}),
None)
# 2. 一次性给出所有输入错误(字段 + 确认):
# 用户一次就能全部改正
errors = validation.errors_of(form)
if "password" not in errors and "confirmation" not in errors \
and form.password.data != form.confirmation.data:
errors["confirmation"] = "ERRORS.PASSWORDS_DIFFER"
if errors:
return show(values, errors, None, None)
# 3. 创建(客户端 + USER 账户,在一个事务中)
try:
application().add_client(PersonData(form.title.data, form.last_name.data,
form.first_name.data, form.login.data,
form.password.data))
except BusinessException as e:
# 登录名或名 + 姓已被占用:通行证仍然有效
return show(values, {}, Message(e.key), validation.BUSINESS_ERROR_FIELDS.get(e.key))
# 4. 通行证已被使用:它不会允许创建第二个账户
passes().consume(pass_id)
limiter().registration_success(ip)
# 5. 返回登录页面,并预填登录名
flash_success("REGISTRATION.DONE", login=form.login.data)
response = redirect(url_for("auth.show_login", login=form.login.data))
registration_pass.clear_cookie(response)
return response
# —— 内部函数
# 没有有效的通行证:返回身份验证页面
def back_to_login():
flash_error("ERRORS.CAPTCHA_BEFORE_ACCOUNT")
return redirect(url_for("auth.show_login"))
# 表单;绝不会把密码送回浏览器
def show(values: PersonValues, errors: dict[str, str], error: Message | None,
other_fields: list[str] | None):
model = RegistrationModel("REGISTRATION.TITLE", validation.page_message(errors, error),
values, validation.state(errors, other_fields))
return render_template("registration.html", model=model)
|
- 第 51–72 行:登录页面上的“创建患者账户”按钮把登录表单提交给这个操作(使用 [formaction] 属性,示例 20)。它先检查账户创建的限制,再检查登录页面上的验证码;如果验证码正确,就颁发一个令牌([auth/registration_pass.py])并重定向到注册表单。失败会被计为一次失败的登录尝试(用户名为空);
- 第 78–83 行:表单,仅在持有有效通行证时可用:直接键入地址 [/register] 会重定向到登录页面;
- 第 89–133 行:创建账户:- 再次检查通行证;- 调用 [form.validate()] ,但忽略其结果:我们希望一次性得到所有输入错误,包括密码与确认密码之间的任何不一致,这一点随后由操作来验证(前提是两个字段本身都有效)。用户可以一次改正所有错误;- 使用与管理员相同的业务逻辑方法创建客户及其账户;- 通行证被消耗,创建操作由限流器计数;- 返回登录页面,并显示一条消息,同时预填登录名(来自 URL 的参数 [login] )。通行证 Cookie 被清除。
11.16.6. controllers/area.py
患者的个人页面。
| # =========================================================================
# controllers/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),绝不是浏览器
# 发送的标识符。因此患者既无法查看、编辑,也无法取消
# 属于其他患者的内容,即使自己构造请求也不行。
#
# 任何账户的编辑或删除都需要当前
# 密码:即使有人发现了一个未退出的会话,
# 也无法更改密码或删除账户。当前密码
# 错误会计为登录失败(适用同一限制)。
# =========================================================================
from flask import Blueprint, redirect, render_template, request, url_for
from rdvmedecins.auth.auth_service import AuthService
from rdvmedecins.auth.security import require_roles
from rdvmedecins.controllers.auth import ip_address
from rdvmedecins.entities import Client, Role
from rdvmedecins.forms.forms import MyAccountForm
from rdvmedecins.business.person_data import PersonData
from rdvmedecins.business.exception import BusinessException
from rdvmedecins.models.view_models import (AreaModel, Message, MyAccountModel, AppointmentView,
PersonValues)
from rdvmedecins.web import utils, validation
from rdvmedecins.web.flash import flash_error, flash_success
from rdvmedecins.web.services import application, auth_service, limiter
area = Blueprint("area", __name__)
# 该蓝图的所有操作都仅限 USER 角色
@area.before_request
def patient_only():
require_roles(Role.USER)
# -----------------------------------------------------------------------
# GET /my-area
# -----------------------------------------------------------------------
@area.get("/my-area")
def patient_area():
patient = utils.connected_patient(application())
appointments = [AppointmentView(
a.id,
utils.format_day(a.day),
utils.time(a.slot),
utils.label(a.slot.doctor),
# 指向医生当天日程的链接:患者会在那里看到自己的姓名
url_for("schedule.show", doctorId=a.slot.doctor_id, day=utils.iso(a.day)))
for a in application().get_client_upcoming_appointments(patient.id)]
model = AreaModel("AREA.TITLE", None, utils.label(patient), appointments)
return render_template("area.html", model=model)
# -----------------------------------------------------------------------
# POST /my-area/cancel 字段:appointmentId
# -----------------------------------------------------------------------
@area.post("/my-area/cancel")
def cancel_appointment():
patient = utils.connected_patient(application())
appointment_id = utils.positive_integer(request.form.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:
flash_error("ERRORS.APPOINTMENT_NOT_FOUND")
else:
application().delete_appointment(appointment)
flash_success("SCHEDULE.CANCELLED")
return redirect(url_for("area.patient_area"))
# -----------------------------------------------------------------------
# GET /my-account
# -----------------------------------------------------------------------
@area.get("/my-account")
def account_form():
patient = utils.connected_patient(application())
values = PersonValues(patient.title, patient.first_name, patient.last_name, patient.user.login,
patient.version)
return show(values, {}, None, None)
# -----------------------------------------------------------------------
# POST /my-account
# -----------------------------------------------------------------------
@area.post("/my-account")
def edit_account():
patient = utils.connected_patient(application())
form = MyAccountForm()
form.validate()
values = PersonValues(form.title.data or patient.title, form.first_name.data or "",
form.last_name.data or "", form.login.data or "", form.version.data)
errors = validation.errors_of(form)
if "password" not in errors and form.password.data is not None \
and form.password.data != form.confirmation.data:
errors["confirmation"] = "ERRORS.PASSWORDS_DIFFER"
if errors:
return show(values, errors, None, None)
# 当前密码
password_error = check_current_password(patient, form.current_password.data)
if password_error is not None:
# 密码错误:消息也显示在字段下方
field_errors = ({"current_password": password_error.key}
if password_error.key == "ERRORS.WRONG_CURRENT_PASSWORD" else {})
return show(values, field_errors, password_error, None)
try:
client = application().edit_client(patient.id, PersonData(
form.title.data, form.last_name.data, form.first_name.data, form.login.data,
form.password.data, # None = 不变
form.version.data))
except BusinessException as e:
return show(values, {}, Message(e.key), validation.BUSINESS_ERROR_FIELDS.get(e.key))
# 登录名和显示的姓名都在令牌中:因此会签发
# 一个新令牌,否则导航栏会一直显示旧的姓名
flash_success("MY_ACCOUNT.UPDATED")
response = redirect(url_for("area.patient_area"))
auth_service().set_token(response, client.user)
return response
# -----------------------------------------------------------------------
# POST /my-account/delete 字段:delete_password
# 账户、客户端及其所有预约会一起消失,
# 然后患者被退出登录。
# -----------------------------------------------------------------------
@area.post("/my-account/delete")
def delete_account():
patient = utils.connected_patient(application())
password_error = check_current_password(
patient, request.form.get("delete_password"))
if password_error is not None:
flash_error(password_error.key, **password_error.params)
return redirect(url_for("area.account_form"))
application().delete_client(patient.id)
flash_success("MY_ACCOUNT.DELETED")
response = redirect(url_for("auth.show_login"))
AuthService.clear_token(response)
return response
# —— 内部函数
# 如果当前密码正确则为 None;否则为错误消息
def check_current_password(patient: Client, password: str | None) -> Message | None:
ip = ip_address()
login = patient.user.login
minutes = limiter().login_block_minutes(ip, login)
if minutes > 0:
return Message("ERRORS.TOO_MANY_ATTEMPTS", {"minutes": str(minutes)})
ok = bool(password) and auth_service().validate_user(login, password) is not None
if not ok:
limiter().login_failure(ip, login)
return Message("ERRORS.WRONG_CURRENT_PASSWORD")
return None
def show(values: PersonValues, errors: dict[str, str], error: Message | None,
other_fields: list[str] | None):
model = MyAccountModel("MY_ACCOUNT.TITLE", validation.page_message(errors, error), values,
validation.state(errors, other_fields))
return render_template("account.html", model=model)
|
- 第 43–45 行:该蓝图中的所有操作都仅限 USER 角色使用;
- 第 51–63 行:患者的仪表板:其未来的预约,已格式化,每个预约都带有指向该日医生日程的链接。患者始终是与令牌关联的那一位([utils.connected_patient]),绝不是浏览器发送的标识符:患者无法查看、修改或取消其他患者的信息;
- 第 69–81 行:取消患者的预约。不存在的预约和其他患者的预约会得到相同的响应:不会泄露任何关于其他患者预约的信息(否则,患者就可以发现哪些预约编号是存在的);
- 第 87–92 行:用户的账户表单,已预先填写;
- 第 98–133 行:编辑:验证字段和确认密码,检查当前密码,然后调用业务层。登录名和显示名称在令牌中:操作会颁发一个新令牌;否则,导航栏会一直保留旧名称,直到下次登录;
- 第 141–153 行:删除账户,同样由当前密码保护。账户、客户及其所有预约会一并删除;患者被注销;
- 第 159–169 行:当前密码可以保护账户,防止任何人利用一个未关闭的会话。输错会被计为登录失败,适用相同的限制:因此不能用来猜测密码。
11.17. 视图
[templates] 文件夹包含应用程序的 [Jinja2] 视图:一个模板、七个片段和八个页面。它们都遵循同一条规则:视图中没有逻辑。操作向它们传递预先准备好的模板([models/view_models.py]);视图只是把数据放入 HTML,并使用 [t] 函数翻译文本。它们不包含任何硬编码文本:一切都通过字典获得。
11.17.1. 模板和片段
11.17.1.1. templates/layout.html
| <!doctype html>
{# =========================================================================
templates/layout.html
—————————————————————————
所有页面通用的布局(参见示例 15):每个页面
(schedule.html、login.html……)扩展它({% extends %})并填充其块
[content]。
Jinja2 会转义用 {{ ... }} 显示的所有内容(字符
< > & " ' 变成 < >……):以防止 HTML 注入,
例如通过输入的姓名。要原样插入 HTML,必须
显式请求(safe 过滤器,参见 fragments/captcha.html)。
消息:成功消息显示在页面顶部,错误消息显示在底部,位于
浅粉色背景上(errors.html 片段)。
布局共享页面的变量:[model](由操作传入的
视图模型,参见 models/view_models.py),它从中读取
页面标题的键;[language]、[user]、[path]、[t],由 web/common_model.py 添加到
所有视图中。
========================================================================= #}
<html lang="{{ language }}">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
{# t(key):键的翻译;这里的键是一个变量(model.page_title) #}
<title>{{ t(model.page_title) }} - {{ t("APP.TITLE") }}</title>
<link rel="stylesheet" href="{{ url_for('static', filename='lib/bootstrap/css/bootstrap.min.css') }}">
<link rel="stylesheet" href="{{ url_for('static', filename='css/styles.css') }}">
</head>
<body>
{# 上一个请求设置的 flash 消息:只读取一次
(get_flashed_messages 会立即清除它们),然后拆分:成功消息
放在顶部,错误消息放在底部 #}
{% set flashes = get_flashed_messages(with_categories=true) %}
<div class="container py-4">
{% include "fragments/navbar.html" %}
{% include "fragments/flash.html" %}
<main>
{% block content %}{% endblock %}
</main>
{% include "fragments/errors.html" %}
</div>
{# "Are you sure?" 对话框,在需要之前一直隐藏 #}
{% include "fragments/confirmation.html" %}
<script src="{{ url_for('static', filename='js/app.js') }}"></script>
</body>
</html>
|
- 第 22 行:页面语言,由上下文处理器提供;
- 第 27 行:页面标题。标题键是一个变量 ([model.page_title]):每个页面模板都提供一个(示例 22 的做法,使用视图模板而不是 [{% set %}] 变量);
- 第 28 行:[Bootstrap] 是应用程序的一部分,位于其 [static] 文件夹中;
- 第 35 行:闪现消息由模板读取一次 ;[get_flashed_messages] 会立刻忘掉它们,第二次调用将返回空列表。使用 [with_categories=true] 时,该函数返回(类别,消息)元组。变量 [flashes] 随后由显示它们的两个片段读取:成功消息在顶部,错误消息在底部。由 [{% set %}] 定义的变量对由 [{% include %}] 包含的片段可见;
- 第 37–42 行:导航栏、成功消息、页面内容和错误区域;
- 第 45–46 行:确认窗口以及管理它的脚本(示例 21)。
11.17.1.2. templates/fragments/navbar.html
| {# =========================================================================
templates/fragments/navbar.html:导航栏。
标题、FR/EN、角色、姓名、退出登录,以及一个菜单,其条目
取决于角色:"Doctors" 和 "Patients" 只对
ADMIN 显示。这只是显示上的便利:真正的保护是
操作中的角色检查(手动输入 /doctors 的 USER
会得到 403 页面)。患者(USER)另外还有其"My area"菜单。
当前页面的菜单项会高亮显示("active" 类):
[path] 是请求的 URL(参见 web/common_model.py)。一个宏
只写一次菜单项的 HTML;其可选参数 [prefix]
(默认为 href),是使该条目处于激活状态的路径的开头。
========================================================================= #}
{% macro entry(href, key, prefix=none) %}
<li class="nav-item">
<a class="nav-link{{ ' active' if path.startswith(prefix or href) }}" href="{{ href }}">{{ t(key) }}</a>
</li>
{% endmacro %}
<nav class="navbar navbar-expand-sm navbar-dark bg-primary rounded mb-4 px-3">
<span class="navbar-brand mb-0">{{ t("APP.TITLE") }}</span>
{% if user %}
<ul class="navbar-nav me-auto">
{% if user.is_patient %}
{# 对 /my-area 和 /my-account 都激活 #}
{{ entry("/my-area", "APP.MENU_MY_AREA", "/my-") }}
{% endif %}
{{ entry("/schedule", "APP.MENU_SCHEDULE") }}
{% if user.is_admin %}
{{ entry("/doctors", "APP.MENU_DOCTORS") }}
{{ entry("/clients", "APP.MENU_PATIENTS") }}
{% endif %}
</ul>
{% else %}
<div class="me-auto"></div>
{% endif %}
<div class="d-flex align-items-center gap-2">
{# FR / EN:简单链接(GET /language/fr),当前语言高亮显示 #}
<div class="btn-group btn-group-sm" role="group" aria-label="FR / EN">
{% for code in ["fr", "en"] %}
<a class="btn {{ 'btn-light' if language == code else 'btn-outline-light' }}" href="/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>
{# 退出登录是一个 POST:只有按钮(和防 CSRF 令牌)的表单 #}
<form method="post" action="/logout" class="m-0">
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
<button type="submit" class="btn btn-sm btn-outline-light">{{ t("APP.LOGOUT") }}</button>
</form>
{% endif %}
</div>
</nav>
|
- 第 15–19 行:一个菜单项,如果当前页面的路径以其前缀开头,就会突出显示(类 [active])。参数 [prefix] 是可选的(对 [none] 而言,在 [Jinja2] 中就如同 [None] 在 [Python] 中一样);否则,它就是该项的地址([prefix or href])。“我的区域”项以 [/my-] 为前缀:对 [/my-area] 和 [/my-account] 它都处于激活状态;
- 第 23–37 行:菜单取决于角色:患者看到“我的区域”,管理员看到“医生”和“患者”。这只是一种显示上的便利;真正的安全性来自对操作的基于角色的控制。手动输入 [/doctors] 的患者将收到 403 错误页面;
- 第 42–44 行:FR 和 EN 按钮只是指向 [/language/fr] and [/language/en] 的链接;
- 第 48–54 行:角色、用户名和注销:一个简化为按钮的 POST 表单,带有防 CSRF 令牌。
11.17.1.3. templates/fragments/flash.html
| {# =========================================================================
templates/fragments/flash.html:上一个操作设置的成功消息
(预约已保存、医生已添加……),
只显示一次,位于页面顶部(参见 web/flash.py)。
错误类的 flash 消息显示在页面底部,由
fragments/errors.html 负责。
[flashes]:(类别, 消息)对的列表,由布局读取。
t(message.key, message.params):键为
message.key 的消息,参数为 {name}、
{login}……等值的字典(参见 web/translator.py)。
========================================================================= #}
{% for category, message in flashes if category == "success" %}
<div class="alert alert-success" role="status">{{ t(message.key, message.params) }}</div>
{% endfor %}
|
- 第 13 行:[for] 循环在 [Jinja2] 中可以对其元素进行过滤:[for ... in ... if condition] 只遍历满足条件的元素。每个元素是一对值,两个部分分别存入两个变量;
- 第 14 行:消息是一个字典(参见 [web/flash.py]):包含它的键和参数。[Jinja2] 中的点号表示法也可以读取字典的键(示例 13)。
11.17.1.4. templates/fragments/errors.html
| {# =========================================================================
templates/fragments/errors.html:错误区域,位于每个
页面的底部,浅粉色背景(.error-zone 类,参见 static/css/styles.css)。
它汇集了两种可能的错误来源:
- model.error:所显示页面的错误(表单被拒绝、登录名
或名 + 姓已被使用、日期无效、密码错误……);
- 错误类的 flash 消息,由上一个操作在
重定向之前设置(时段已被预订、删除被拒绝……)。
for 循环可以过滤其元素:"for ... in ... if condition"。
role="alert":页面一显示,屏幕阅读器就会朗读该消息,
即使它位于底部。
========================================================================= #}
{% set flash_errors = flashes | selectattr(0, "equalto", "danger") | list %}
{% if model.error or flash_errors %}
<div class="error-zone" role="alert">
{% if model.error %}
<div>{{ t(model.error.key, model.error.params) }}</div>
{% endif %}
{% for category, message in flash_errors %}
<div>{{ t(message.key, message.params) }}</div>
{% endfor %}
</div>
{% endif %}
|
- 第 15 行:错误闪现消息,由两个过滤器提取:[selectattr(0, "equalto", "danger")] 只保留那些 [0] 属性(这一对值的第一个元素,即类别)等于 ["danger"] 的元素;[list] 把结果转换为列表(这类过滤器返回的是迭代器 ,它只能遍历一次,也无法检查是否为空);
- 第 16–25 行:错误区域汇集了两个错误来源:所显示页面的错误(被拒绝的表单、无效的日期),以及重定向之前由上一个操作产生的错误(时间段已被占用、删除被拒绝)。只有至少存在一个错误时,该区域才会出现。
11.17.1.5. templates/fragments/confirmation.html
| {# =========================================================================
templates/fragments/confirmation.html:"Are you sure?" 模态对话框。
它取代了浏览器的 window.confirm() 框,后者既无法
设置样式,也无法翻译(其按钮使用的是
浏览器的语言,而不是页面的语言)。
整个页面只有一个对话框,起初是隐藏的(d-none)。它的
标签在这里由服务器翻译,与页面的其余部分一样;
小脚本 static/js/app.js 只负责显示它,把
表单特有的消息(data-confirmation 属性)放进去,并在
用户确认时发送表单。
与预订对话框(fragments/booking.html)使用相同的 Bootstrap 类。
========================================================================= #}
<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">{{ t("CONFIRMATION.TITLE") }}</h5>
<button type="button" class="btn-close" data-action="no" aria-label="{{ t('BOOKING_DIALOG.CLOSE_ARIA') }}"></button>
</div>
<div class="modal-body">
<p class="mb-0" id="confirmation-modal-message"></p>
</div>
<div class="modal-footer">
{# "No, go back" 而不是 "Cancel":问题有时是
"Cancel this appointment?",此时 "Cancel" 按钮会产生歧义 #}
<button type="button" class="btn btn-secondary" data-action="no">{{ t("CONFIRMATION.NO") }}</button>
<button type="button" class="btn btn-danger" data-action="yes">{{ t("CONFIRMATION.YES") }}</button>
</div>
</div>
</div>
</div>
</div>
|
示例 21 中的确认窗口,标签由服务器翻译(浏览器的 [window.confirm()] 对话框以浏览器的语言而不是页面的语言显示其按钮),带有关闭按钮和无障碍属性:[aria-labelledby] 和 [aria-describedby] 指向窗口的标题和消息,屏幕阅读器会在窗口打开时朗读它们。“不,返回”按钮比“取消”更合适:问题有时是“取消此预约?”,在这种语境下“取消”按钮会有歧义。
11.17.1.6. templates/fragments/captcha.html
| {# =========================================================================
templates/fragments/captcha.html:身份验证页面的验证码
(参见 auth/captcha.py)。它同时保护登录和
创建账户的入口("Create a patient account" 按钮)。
一个宏,其参数是一个 Captcha 对象(id、svg)。
safe 过滤器:SVG 图像被原样插入页面,不经
转义。这里这样做是无害的,因为该 SVG 由
服务器自己构建,不含任何来自用户的内容;对于用户输入,
绝不能这样做。
隐藏字段 captchaId 告诉服务器要检查哪一个验证码;正确
答案本身绝不会发送给浏览器。
"Another image" 只是重新加载页面([path] = 当前 URL)。
宏看不到调用它的页面的变量("with
context":导入时它能看到 login.html 的变量):这里是 t 和 path。
========================================================================= #}
{% macro captcha(captcha) %}
<div class="mb-3">
<label class="form-label" for="captcha">{{ t("CAPTCHA.LABEL") }}</label>
<div class="d-flex align-items-center gap-3 mb-2">
<div class="captcha-image" role="img" aria-label="{{ t('CAPTCHA.IMAGE_ALT') }}">{{ captcha.svg | safe }}</div>
<a class="small" href="{{ path }}">{{ t("CAPTCHA.NEW_IMAGE") }}</a>
</div>
<input type="hidden" name="captchaId" 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">{{ t("CAPTCHA.HELP") }}</div>
</div>
{% endmacro %}
|
- 第 18 行:一个接收 [Captcha] 对象的宏;
- 第 22 行:SVG 图像,原样插入(示例 27)。属性 [role="img"] 及其 [aria-label] 向屏幕阅读器描述该图像;
- 第 23 行:“换一张图片”链接只是重新加载页面:每次视图都会生成新的验证码;
- 第 25–27 行:验证码 ID 和输入字段。[autocapitalize="off"] 和 [spellcheck="false"] 可防止手机修改输入内容(首字母大写、拼写检查)。
默认情况下,被导入的宏无法访问导入它的页面的变量:由上下文处理器提供的函数 [t] 和变量 [path] 对它来说是未知的。这就是 [login.html] 使用 [with context] 引用来导入它的原因。
11.17.1.7. templates/fragments/person_fields.html
| {# =========================================================================
templates/fragments/person_fields.html:身份字段(称谓、
名、姓),三个表单通用:ADMIN 的医生/客户端表单、
"Create a patient account" 和 "Manage my account"。
该片段由 {% include %} 插入,读取插入它的
页面的 [model] 变量(一个 FormView,参见 models/view_models.py):
值、每个字段下方的消息、用红色轮廓标出的字段。
selected:布尔属性,选项被选中时写出,否则省略。
state.invalid_class(field):对被拒绝的字段返回 "is-invalid"(Bootstrap 的红色轮廓),
否则返回 ""。
========================================================================= #}
{% set state = model.state %}
<div class="mb-3">
<label class="form-label" for="title">{{ t("PERSONS.TITLE_LABEL") }}</label>
<select id="title" name="title" class="form-select {{ state.invalid_class('title') }}">
{% for title in model.titles %}
<option value="{{ title.value }}"{{ " selected" if title.selected }}>{{ title.value }}</option>
{% endfor %}
</select>
{% if state.error_of("title") %}
<div class="invalid-feedback">{{ t(state.error_of("title")) }}</div>
{% endif %}
</div>
<div class="row g-3 mb-3">
<div class="col-sm-6">
<label class="form-label" for="first_name">{{ t("PERSONS.FIRSTNAME_LABEL") }}</label>
<input id="first_name" name="first_name" type="text" maxlength="20" required
class="form-control {{ state.invalid_class('first_name') }}" value="{{ model.values.first_name }}">
{% if state.error_of("first_name") %}
<div class="invalid-feedback">{{ t(state.error_of("first_name")) }}</div>
{% endif %}
</div>
<div class="col-sm-6">
<label class="form-label" for="last_name">{{ t("PERSONS.LASTNAME_LABEL") }}</label>
<input id="last_name" name="last_name" type="text" maxlength="20" required
class="form-control {{ state.invalid_class('last_name') }}" value="{{ model.values.last_name }}">
{% if state.error_of("last_name") %}
<div class="invalid-feedback">{{ t(state.error_of("last_name")) }}</div>
{% endif %}
</div>
</div>
|
身份字段(称谓、名、姓),应用程序中的三个表单都共有这些字段。该片段通过 [{% include %}] 插入,它从插入它的页面中读取变量 [model] :即继承自 [FormView] 的模板。
- 第 16–20 行:称谓列表,由模板的 [titles] 属性计算,并突出显示所选的称谓;
- 第 29–30 行:名字输入字段,带有要重新显示的值,如果该字段被拒绝,则带有类 [is-invalid] ([state.invalid_class('first_name')]);
- 第 31–33 行:字段下方的消息,已翻译。
属性 [maxlength] 和 [required] 是浏览器的控制。应用程序的表单包含属性 [novalidate] (示例 19):提交之前不会执行这些检查;验证由服务器处理。[maxlength] 则始终会阻止用户输入超过列所能容纳的字符数。
11.17.1.8. templates/fragments/booking.html
| {# =========================================================================
templates/fragments/booking.html:日程的预订
对话框。
模态对话框的真正的 Bootstrap 类(.modal、
.modal-backdrop……),以"硬编码"方式(show d-block)而不是
由 Bootstrap 的 JavaScript 显示。决定显示它的是服务器
(URL 的 &book=... 参数),而关闭它就等于跟随一个指向
同一页面但不带此参数的链接。
该片段直接读取插入它的页面的 [model] 变量
(一个 ScheduleModel)。
========================================================================= #}
{% set booking = model.booking %}
<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="/schedule/book" class="modal-content">
<div class="modal-header">
<h5 class="modal-title" id="booking-title">{{ t("BOOKING_DIALOG.TITLE") }}</h5>
<a class="btn-close" href="{{ model.back_url }}" aria-label="{{ t('BOOKING_DIALOG.CLOSE_ARIA') }}"></a>
</div>
<div class="modal-body">
<p>{{ t("BOOKING_DIALOG.SLOT", time=booking.time) }}</p>
{# 除所选患者之外,服务器还必须知道的信息 #}
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
<input type="hidden" name="doctorId" value="{{ model.doctor_id }}">
<input type="hidden" name="day" value="{{ model.day }}">
<input type="hidden" name="slotId" value="{{ booking.slot_id }}">
{# 患者为自己预订:没有可供选择的列表
(而且服务器无论如何都会忽略可能存在的 clientId) #}
{% if booking.patient %}
<p class="mb-0">
<span>{{ t("BOOKING_DIALOG.PATIENT_LABEL") }}</span>:
<strong>{{ booking.patient }}</strong>
</p>
{% else %}
<label class="form-label" for="clientId">{{ t("BOOKING_DIALOG.PATIENT_LABEL") }}</label>
<select id="clientId" name="clientId" class="form-select" required autofocus>
<option value="">{{ t("BOOKING_DIALOG.CHOOSE_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="{{ model.back_url }}">{{ t("BOOKING_DIALOG.CANCEL") }}</a>
<button type="submit" class="btn btn-primary">{{ t("BOOKING_DIALOG.CONFIRM") }}</button>
</div>
</form>
</div>
</div>
|
预订窗口。它使用 [Bootstrap] 模态窗口的真实类([modal]、[modal-backdrop]……),以“硬编码”方式使其可见([show d-block]),而不是通过 [Bootstrap] 的 [JavaScript]:由服务器决定是否显示它(URL 的 [book] 参数),而关闭它就相当于点击一个指向同一页面但不带该参数的链接([model.back_url])。
- 第 29–31 行:隐藏字段:除所选患者之外,服务器还需要知道的信息;
- 第 35–48 行:患者为自己预订:显示其姓名,没有可供选择的列表(而且服务器无论如何都会忽略 [clientId] 字段)。对于管理员,则显示患者列表,其第一个选项的值为空,用于提示进行选择。
11.17.2. 页面
11.17.2.1. templates/login.html
| {# =========================================================================
templates/login.html:登录表单(参见 controllers/auth.py)。
一个普通的 HTML <form>:浏览器自己在 POST /login 中发送登录名、
密码和验证码答案,无需 JavaScript。失败时,
服务器会返回此页面,其中保留已输入的登录名、一个
新的验证码,以及错误,由布局显示在页面底部。
========================================================================= #}
{% extends "layout.html" %}
{# with context:宏可以看到此页面的变量(t、path) #}
{% from "fragments/captcha.html" import captcha with context %}
{% block content %}
{% set login_typed = model.login != "" %}
<div class="row justify-content-center">
<div class="col-sm-8 col-md-6 col-lg-5">
<div class="card p-4">
<h5 class="card-title mb-3">{{ t("LOGIN.TITLE") }}</h5>
<form method="post" action="/login">
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
<div class="mb-3">
<label class="form-label" for="login">{{ t("LOGIN.LOGIN_LABEL") }}</label>
{# autofocus:布尔属性,条件为真时写出,否则省略 #}
<input id="login" name="login" type="text" class="form-control" autocomplete="username"
value="{{ model.login }}" required{{ " autofocus" if not login_typed }}>
</div>
<div class="mb-3">
<label class="form-label" for="password">{{ t("LOGIN.PASSWORD_LABEL") }}</label>
<input id="password" name="password" type="password" class="form-control"
autocomplete="current-password" required{{ " autofocus" if login_typed }}>
</div>
{{ captcha(model.captcha) }}
<button type="submit" class="btn btn-primary w-100">{{ t("LOGIN.SUBMIT") }}</button>
{# 还没有账户:患者可以自己创建一个。
它不是简单的链接:它是此表单的
第二个提交按钮,指向另一个地址(formaction)。
服务器在打开账户创建页面之前,
会在那里检查上面的验证码(参见 controllers/registration.py)。
formnovalidate:浏览器不要求填写登录名和密码
(创建账户时没有必要);由服务器检查
验证码。在字段中按回车键总是触发表单的第一个
按钮,即 "Log in"。 #}
<button type="submit" class="btn btn-outline-primary w-100 mt-3"
formaction="/register/access" formnovalidate>{{ t("LOGIN.CREATE_ACCOUNT") }}</button>
<div class="form-text text-center">{{ t("LOGIN.CREATE_ACCOUNT_HELP") }}</div>
</form>
<div class="text-muted small mt-3">
<span>{{ t("LOGIN.DEMO_ACCOUNTS") }}</span>
<ul class="mb-0 mt-1">
<li><code>admin</code> - <span>{{ t("LOGIN.DEMO_ADMIN") }}</span></li>
<li><code>pelissier</code>, <code>tatou</code>, <code>dupont</code> - <span>{{ t("LOGIN.DEMO_DOCTOR") }}</span></li>
<li><code>martin</code>, <code>durand</code>, <code>bistrou</code>, <code>german</code> - <span>{{ t("LOGIN.DEMO_USER") }}</span></li>
</ul>
</div>
</div>
</div>
</div>
{% endblock %}
|
- 第 10 行:导入宏,同时带上页面上下文;
- 第 13 行:如果登录名字段为空,光标就放在登录名字段中,否则(登录尝试失败之后或创建账户之后)放在密码字段中:布尔属性 [autofocus] 被设置在其中一个字段上;
- 第 24–30 行:[autocomplete] 属性的值帮助浏览器的密码管理器填写表单;
- 第 46–47 行:“创建患者账户”按钮不是链接,而是用来提交同一个表单的第二个按钮,它把表单发送到另一个地址([formaction],示例 20)。服务器在那里先验证验证码,然后才打开账户创建页面。[formnovalidate]:浏览器不要求填写标记为 [required] 的用户名和密码,因为创建账户并不需要它们。在字段中按 Enter 键始终会触发表单上的第一个按钮,即“登录”。
11.17.2.2. templates/schedule.html
| {# =========================================================================
templates/schedule.html:主页面(参见 controllers/schedule.py)。
三个块:
1. 选择医生和日期;
2. 日程;
3. 预订对话框(fragments/booking.html)。
可能出现的错误(日期无效、医生未知)由布局显示在
页面底部(参见 fragments/errors.html)。
========================================================================= #}
{% extends "layout.html" %}
{% block content %}
{# 1. 选择医生和日期:一个 GET 表单,只是用 URL 中的 ?doctorId=...&day=...
重新加载此页面 #}
<form method="get" action="/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">{{ t("DOCTOR_DAY_PICKER.DOCTOR_LABEL") }}</label>
<select id="doctorId" name="doctorId" class="form-select" required>
<option value="">{{ t("DOCTOR_DAY_PICKER.CHOOSE_DOCTOR") }}</option>
{% for doctor in model.doctors %}
<option value="{{ doctor.id }}"{{ " selected" if doctor.selected }}>{{ doctor.label }}</option>
{% endfor %}
</select>
</div>
<div class="col-sm-4">
<label class="form-label" for="day">{{ t("DOCTOR_DAY_PICKER.DAY_LABEL") }}</label>
<input id="day" name="day" type="date" class="form-control" value="{{ model.day }}" required>
</div>
<div class="col-sm-3">
<button type="submit" class="btn btn-primary w-100">{{ t("DOCTOR_DAY_PICKER.VIEW_SCHEDULE") }}</button>
</div>
</div>
</form>
{# 已有即将到来的预约的患者:为何没有"Book"按钮 #}
{% if model.info %}
<div class="alert alert-info">
<span>{{ t(model.info) }}</span>
<a href="/my-area" class="alert-link">{{ t("APP.MENU_MY_AREA") }}</a>
</div>
{% endif %}
{# 2. 日程 #}
{% set schedule = model.schedule %}
{% if schedule %}
<div class="card p-3">
<h5>{{ t("SCHEDULE.TITLE_PREFIX") }} {{ schedule.day }} - {{ schedule.doctor }}</h5>
{% if schedule.rows %}
<table class="table table-hover align-middle">
<thead>
<tr>
<th>{{ t("SCHEDULE.COLUMN_SLOT") }}</th>
<th>{{ t("SCHEDULE.COLUMN_STATUS") }}</th>
<th></th>
</tr>
</thead>
<tbody>
{% for row in schedule.rows %}
<tr class="{{ 'free-slot' if row.bookable }}">
<td>{{ row.time }}</td>
<td>
{# [patient] 只有在用户被允许
查看此姓名时才会填写(ADMIN、DOCTOR,或患者查看
自己的预约);否则就是简单的 "Booked" #}
{% if row.free %}
<span class="badge text-bg-success">{{ t("SCHEDULE.FREE") }}</span>
{% elif row.patient %}
<span class="badge {{ 'text-bg-primary' if row.mine else 'text-bg-secondary' }}">{{ row.patient }}</span>
{% else %}
<span class="badge text-bg-secondary">{{ t("SCHEDULE.BOOKED_BY_OTHER") }}</span>
{% endif %}
</td>
<td>
{# 所显示的按钮由控制器
(bookable、appointment_id)根据用户的角色决定。
"Book" 是一个简单的链接:它重新打开此页面,
并带上该时段的预订对话框 #}
{% if row.bookable %}
<a class="btn btn-sm btn-outline-success" href="{{ row.book_url }}">{{ t("SCHEDULE.BOOK") }}</a>
{% endif %}
{# "Cancel" 会修改数据:因此它是一个 POST #}
{% if row.appointment_id %}
<form method="post" action="/schedule/cancel" class="m-0"
data-confirmation="{{ t('SCHEDULE.CANCEL_CONFIRM') }}">
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
<input type="hidden" name="appointmentId" value="{{ row.appointment_id }}">
<input type="hidden" name="doctorId" value="{{ model.doctor_id }}">
<input type="hidden" name="day" value="{{ model.day }}">
<button type="submit" class="btn btn-sm btn-outline-danger">{{ t("SCHEDULE.CANCEL_APPOINTMENT") }}</button>
</form>
{% endif %}
</td>
</tr>
{% endfor %}
</tbody>
</table>
{% else %}
<p class="text-muted mb-0">{{ t("SCHEDULE.NO_SLOTS") }}</p>
{% endif %}
</div>
{% else %}
<p class="text-muted">{{ t("SCHEDULE.EMPTY_STATE") }}</p>
{% endif %}
{# 3. 预订对话框,仅当 URL 包含 &book=... 时才显示 #}
{% if model.booking %}
{% include "fragments/booking.html" %}
{% endif %}
{% endblock %}
|
- 第 15–34 行:选择医生和日期:一个 GET 表单(示例 17),它只是用参数 [doctorId] and [day] 在 URL 中重新加载页面。[<input type="date">] 字段以 [yyyy-mm-dd] 格式显示其值,而不管浏览器以何种语言显示它;
- 第 37–42 行:针对已有未来预约的患者的提示消息;
- 第 61–95 行:日程中的一个条目。有三种可能的状态:可预订、带患者姓名的已预订(如果是已登录患者自己的预约,则以蓝色显示)、不带姓名的已预订(“已预订”)。显示哪些按钮由操作决定。“预订”是一个简单的链接:它会重新打开本页面,并带上该时间段的预订窗口。“取消”会修改数据:它是一个 POST 表单,带有确认请求(示例 21);
- 第 108–110 行:预订窗口,仅当操作已准备好它时才显示。
11.17.2.3. templates/persons/list.html
| {# =========================================================================
templates/persons/list.html:医生或客户端的列表(ADMIN)。
两者共用一个视图:各自特有的标签通过
model.keys 传入(参见 controllers/doctors.py / controllers/clients.py)。
========================================================================= #}
{% extends "layout.html" %}
{% block content %}
<div class="d-flex justify-content-between align-items-center mb-3">
<h4 class="mb-0">{{ t(model.keys.title) }}</h4>
<a class="btn btn-primary" href="{{ model.add_url }}">{{ t(model.keys.add) }}</a>
</div>
<div class="card p-3">
{% if model.persons %}
<table class="table table-hover align-middle mb-0">
<thead>
<tr>
<th>{{ t("PERSONS.COLUMN_TITLE") }}</th>
<th>{{ t("PERSONS.COLUMN_FIRSTNAME") }}</th>
<th>{{ t("PERSONS.COLUMN_LASTNAME") }}</th>
<th>{{ t("PERSONS.COLUMN_LOGIN") }}</th>
<th></th>
</tr>
</thead>
<tbody>
{% for person in model.persons %}
<tr>
<td>{{ person.title }}</td>
<td>{{ person.first_name }}</td>
<td>{{ person.last_name }}</td>
<td><code>{{ person.login }}</code></td>
<td class="text-end">
<div class="d-inline-flex gap-2">
<a class="btn btn-sm btn-outline-primary" href="{{ person.edit_url }}">{{ t("PERSONS.EDIT") }}</a>
{# data-confirmation:在发送表单之前
会打开一个确认对话框(参见 static/js/app.js) #}
<form method="post" action="{{ person.delete_url }}" class="m-0"
data-confirmation="{{ t(model.keys.confirm_delete) }}">
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
<button type="submit" class="btn btn-sm btn-outline-danger">{{ t("PERSONS.DELETE") }}</button>
</form>
</div>
</td>
</tr>
{% endfor %}
</tbody>
</table>
{% else %}
<p class="text-muted mb-0">{{ t(model.keys.empty) }}</p>
{% endif %}
</div>
{% endblock %}
|
一个视图同时用于两个列表,即医生和客户:各自特有的标签出现在 [model.keys] 中;[t(model.keys.title)] 渲染一个本身就是变量的键。每一行都有一个“编辑”链接和一个需要确认的“删除”表单。
| {# =========================================================================
templates/persons/form.html:医生或客户端的创建或编辑
(ADMIN)。model.creating 用于区分这两种情况。
当输入被拒绝时(字段为空、登录名已被占用……),操作
会返回此视图,其中包含:
- 已输入的值(model.values);
- 用红色轮廓标出的有问题的字段(Bootstrap 类 "is-invalid");
- 被验证拒绝的字段下方的消息;
- 页面的错误消息,由布局显示在页面底部
(参见 fragments/errors.html)。
========================================================================= #}
{% extends "layout.html" %}
{% block content %}
{% set state = model.state %}
<div class="row justify-content-center">
<div class="col-md-8 col-lg-6">
<div class="card p-4">
<h5 class="card-title mb-3">{{ t(model.page_title) }}</h5>
{# novalidate:我们让服务器来验证(它才是权威);
浏览器的检查(required……)只是一种便利,
用户总是可以绕过 #}
<form method="post" action="{{ model.action }}" novalidate>
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
{% if not model.creating %}
<input type="hidden" name="version" value="{{ model.values.version }}">
{% endif %}
{# 称谓、名、姓:三个表单共用的片段 #}
{% include "fragments/person_fields.html" %}
<h6 class="mt-4 text-muted">{{ t("PERSONS.ACCOUNT_SECTION") }}</h6>
<div class="mb-3">
<label class="form-label" for="login">{{ t("PERSONS.LOGIN_LABEL") }}</label>
<input id="login" name="login" type="text" maxlength="30" autocomplete="off"
class="form-control {{ state.invalid_class('login') }}" value="{{ model.values.login }}">
{% if state.error_of("login") %}
<div class="invalid-feedback">{{ t(state.error_of("login")) }}</div>
{% else %}
<div class="form-text">{{ t("PERSONS.LOGIN_HELP_CREATE" if model.creating else "PERSONS.LOGIN_HELP_EDIT") }}</div>
{% endif %}
</div>
<div class="mb-4">
<label class="form-label" for="password">{{ t("PERSONS.PASSWORD_LABEL") }}</label>
{# 绝不预填:密码绝不会回传给浏览器 #}
<input id="password" name="password" type="password" maxlength="72" autocomplete="new-password"
class="form-control {{ state.invalid_class('password') }}">
{% if state.error_of("password") %}
<div class="invalid-feedback">{{ t(state.error_of("password")) }}</div>
{% else %}
<div class="form-text">{{ t("PERSONS.PASSWORD_HELP_CREATE" if model.creating else "PERSONS.PASSWORD_HELP_EDIT") }}</div>
{% endif %}
</div>
<div class="d-flex gap-2">
<button type="submit" class="btn btn-primary">{{ t("PERSONS.SAVE") }}</button>
<a class="btn btn-secondary" href="{{ model.list_url }}">{{ t("PERSONS.BACK") }}</a>
</div>
</form>
</div>
</div>
</div>
{% endblock %}
|
- 第 25 行:表单提交的地址由操作提供:[/doctors/add], [/clients/3/edit]……;
- 第 27–29 行:更新时,记录的版本存放在隐藏字段中(乐观锁);
- 第 32 行:身份字段;
- 第 38–44 行:登录名,可选,带有一个工具提示,其内容取决于记录是在创建还是在编辑([t("..." if model.creating else "...")]);
- 第 50-50 行:密码从不预先填入;它绝不会被发回浏览器。[autocomplete="new-password"] 可防止浏览器在此处建议管理员的密码。
11.17.2.5. templates/registration.html
| {# =========================================================================
templates/registration.html:"Create a patient account"(公开页面,
参见 controllers/registration.py)。身份字段与 ADMIN 的表单
相同(person_fields.html 片段),但登录名和
密码是必填的,并需确认。
这里没有验证码:只有在输入了
身份验证页面的验证码("Create a patient account" 按钮)之后,才能到达此页面。
t(key, min=...):键为 [key] 的值的消息,带有
{min} 参数(参见 web/translator.py)。
========================================================================= #}
{% extends "layout.html" %}
{% block content %}
{% set state = model.state %}
<div class="row justify-content-center">
<div class="col-md-8 col-lg-6">
<div class="card p-4">
<h5 class="card-title mb-1">{{ t("REGISTRATION.TITLE") }}</h5>
<p class="text-muted small mb-3">{{ t("REGISTRATION.INTRO") }}</p>
<form method="post" action="/register" novalidate>
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
{% include "fragments/person_fields.html" %}
<h6 class="mt-4 text-muted">{{ t("PERSONS.ACCOUNT_SECTION") }}</h6>
<div class="mb-3">
<label class="form-label" for="login">{{ t("PERSONS.LOGIN_LABEL") }}</label>
<input id="login" name="login" type="text" maxlength="30" autocomplete="username" required
class="form-control {{ state.invalid_class('login') }}" value="{{ model.values.login }}">
{% if state.error_of("login") %}
<div class="invalid-feedback">{{ t(state.error_of("login")) }}</div>
{% else %}
<div class="form-text">{{ t("REGISTRATION.LOGIN_HELP") }}</div>
{% endif %}
</div>
<div class="row g-3 mb-3">
<div class="col-sm-6">
<label class="form-label" for="password">{{ t("PERSONS.PASSWORD_LABEL") }}</label>
<input id="password" name="password" type="password" maxlength="72" autocomplete="new-password" required
class="form-control {{ state.invalid_class('password') }}">
{% if state.error_of("password") %}
<div class="invalid-feedback">{{ t(state.error_of("password"), min=model.password_min) }}</div>
{% else %}
<div class="form-text">{{ t("REGISTRATION.PASSWORD_HELP", min=model.password_min) }}</div>
{% endif %}
</div>
<div class="col-sm-6">
<label class="form-label" for="confirmation">{{ t("ACCOUNT.CONFIRMATION_LABEL") }}</label>
<input id="confirmation" name="confirmation" type="password" maxlength="72" autocomplete="new-password" required
class="form-control {{ state.invalid_class('confirmation') }}">
{% if state.error_of("confirmation") %}
<div class="invalid-feedback">{{ t(state.error_of("confirmation")) }}</div>
{% endif %}
</div>
</div>
<div class="d-flex gap-2">
<button type="submit" class="btn btn-primary">{{ t("REGISTRATION.SUBMIT") }}</button>
<a class="btn btn-secondary" href="/login">{{ t("REGISTRATION.BACK_TO_LOGIN") }}</a>
</div>
</form>
</div>
</div>
</div>
{% endblock %}
|
患者账户创建表单:个人信息字段,其后是用户名、密码和确认密码,都是必填的。表示密码太短的消息带有一个指定最小长度的参数:[t(state.error_of("password"), min=model.password_min)]。这里没有验证码:只有在登录页面输入验证码之后才能访问此页面。
11.17.2.6. templates/area.html
| {# =========================================================================
templates/area.html:"My area":患者的主页
(USER 角色),在其登录后立即显示。
- 两个选项:[Manage my account] 和 [View a schedule];
- 其即将到来的预约(如果有),以及取消它的方式。
========================================================================= #}
{% extends "layout.html" %}
{% block content %}
<h4 class="mb-3">{{ t("AREA.HELLO", name=model.patient) }}</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="/my-account">
<h5 class="mb-1">{{ t("AREA.MANAGE_ACCOUNT") }}</h5>
<span class="text-muted">{{ t("AREA.MANAGE_ACCOUNT_HELP") }}</span>
</a>
</div>
<div class="col-sm-6">
<a class="card p-4 h-100 text-decoration-none option-card" href="/schedule">
<h5 class="mb-1">{{ t("AREA.VIEW_SCHEDULE") }}</h5>
<span class="text-muted">{{ t("AREA.VIEW_SCHEDULE_HELP") }}</span>
</a>
</div>
</div>
<div class="card p-3">
<h5>{{ t("AREA.MY_APPOINTMENT") }}</h5>
{# 通常只有一个(规则"一次只能有一个即将到来的预约"),
但页面可以显示多个。loop.last:是否为最后一个元素?
for 循环的 else 块:列表为空 #}
{% for appointment in model.appointments %}
<div class="d-flex flex-wrap justify-content-between align-items-center gap-2 py-2{{ '' if loop.last else ' border-bottom' }}">
<div>
<div class="fw-semibold">{{ appointment.day }}, {{ appointment.time }}</div>
<div class="text-muted">
<span>{{ appointment.doctor }}</span> -
<a href="{{ appointment.schedule_url }}">{{ t("AREA.SEE_IN_SCHEDULE") }}</a>
</div>
</div>
<form method="post" action="/my-area/cancel" class="m-0"
data-confirmation="{{ t('SCHEDULE.CANCEL_CONFIRM') }}">
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
<input type="hidden" name="appointmentId" value="{{ appointment.id }}">
<button type="submit" class="btn btn-outline-danger">{{ t("AREA.CANCEL_APPOINTMENT") }}</button>
</form>
</div>
{% else %}
<p class="text-muted mb-0">{{ t("AREA.NO_APPOINTMENT") }}</p>
{% endfor %}
</div>
{% endblock %}
|
患者的仪表板:两个大标签页(“管理我的账户”、“查看日程”)及其未来的预约。[for ... else] 循环(示例 14)在列表为空时显示一条消息;[loop.last] 去掉最后一个预约下方的边框。该页面可以显示多个预约,即使管理规则只允许一个。
11.17.2.7. templates/account.html
| {# =========================================================================
templates/account.html:"Manage my account"(USER 角色)。
同一页面上有两个相互独立的表单:
1. 编辑(身份、登录名、可选的新密码);
2. 删除账户,同时也会取消其预约。
两者都需要当前密码。
========================================================================= #}
{% extends "layout.html" %}
{% block content %}
{% set state = model.state %}
<div class="row justify-content-center">
<div class="col-md-8 col-lg-6">
{# 1. 编辑 #}
<div class="card p-4 mb-4">
<h5 class="card-title mb-3">{{ t("MY_ACCOUNT.TITLE") }}</h5>
<form method="post" action="/my-account" novalidate>
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
<input type="hidden" name="version" value="{{ model.values.version }}">
{% include "fragments/person_fields.html" %}
<h6 class="mt-4 text-muted">{{ t("PERSONS.ACCOUNT_SECTION") }}</h6>
<div class="mb-3">
<label class="form-label" for="login">{{ t("PERSONS.LOGIN_LABEL") }}</label>
<input id="login" name="login" type="text" maxlength="30" autocomplete="username" required
class="form-control {{ state.invalid_class('login') }}" value="{{ model.values.login }}">
{% if state.error_of("login") %}
<div class="invalid-feedback">{{ t(state.error_of("login")) }}</div>
{% endif %}
</div>
<div class="row g-3 mb-3">
<div class="col-sm-6">
<label class="form-label" for="password">{{ t("MY_ACCOUNT.NEW_PASSWORD_LABEL") }}</label>
<input id="password" name="password" type="password" maxlength="72" autocomplete="new-password"
class="form-control {{ state.invalid_class('password') }}">
{% if state.error_of("password") %}
<div class="invalid-feedback">{{ t(state.error_of("password"), min=model.password_min) }}</div>
{% else %}
<div class="form-text">{{ t("PERSONS.PASSWORD_HELP_EDIT") }}</div>
{% endif %}
</div>
<div class="col-sm-6">
<label class="form-label" for="confirmation">{{ t("ACCOUNT.CONFIRMATION_LABEL") }}</label>
<input id="confirmation" name="confirmation" type="password" maxlength="72" autocomplete="new-password"
class="form-control {{ state.invalid_class('confirmation') }}">
{% if state.error_of("confirmation") %}
<div class="invalid-feedback">{{ t(state.error_of("confirmation")) }}</div>
{% endif %}
</div>
</div>
<div class="mb-4">
<label class="form-label" for="current_password">{{ t("MY_ACCOUNT.CURRENT_PASSWORD_LABEL") }}</label>
<input id="current_password" name="current_password" type="password" maxlength="72"
autocomplete="current-password" required
class="form-control {{ state.invalid_class('current_password') }}">
{% if state.error_of("current_password") %}
<div class="invalid-feedback">{{ t(state.error_of("current_password")) }}</div>
{% else %}
<div class="form-text">{{ t("MY_ACCOUNT.CURRENT_PASSWORD_HELP") }}</div>
{% endif %}
</div>
<div class="d-flex gap-2">
<button type="submit" class="btn btn-primary">{{ t("PERSONS.SAVE") }}</button>
<a class="btn btn-secondary" href="/my-area">{{ t("MY_ACCOUNT.BACK") }}</a>
</div>
</form>
</div>
{# 2. 删除 #}
<div class="card p-4 border-danger">
<h5 class="card-title text-danger mb-1">{{ t("MY_ACCOUNT.DELETE_TITLE") }}</h5>
<p class="text-muted small">{{ t("MY_ACCOUNT.DELETE_HELP") }}</p>
<form method="post" action="/my-account/delete" class="d-flex flex-wrap gap-2 align-items-end"
data-confirmation="{{ t('MY_ACCOUNT.DELETE_CONFIRM') }}">
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
<div class="flex-grow-1">
<label class="form-label" for="delete_password">{{ t("MY_ACCOUNT.CURRENT_PASSWORD_LABEL") }}</label>
<input id="delete_password" name="delete_password" type="password" maxlength="72"
autocomplete="current-password" required class="form-control">
</div>
<button type="submit" class="btn btn-danger">{{ t("MY_ACCOUNT.DELETE_SUBMIT") }}</button>
</form>
</div>
</div>
</div>
{% endblock %}
|
同一页面上有两个相互独立的表单:账户修改(第 19–73 行)和账户删除(第 80–89 行),由确认窗口确认。两者都需要当前密码,分别在两个单独的字段中输入(一个表单只提交它自己的字段)。
11.17.2.8. templates/error.html
| {# =========================================================================
templates/error.html:错误页面(400、403、404、500……),
由 web/errors.py 构建。
========================================================================= #}
{% extends "layout.html" %}
{% 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">{{ model.code }}</h1>
<p class="lead">{{ t(model.message) }}</p>
<div><a class="btn btn-primary" href="/">{{ t("ERROR_PAGE.BACK") }}</a></div>
</div>
</div>
</div>
{% endblock %}
|
错误页面:醒目显示的错误代码,以及已翻译的消息。它扩展了该模板:即使发生错误,用户仍保留导航栏,并且可以切换语言。
11.18. 字典
界面文本包含在两个 JSON 字典中,即 [i18n/fr.json] 和 [i18n/en.json],翻译器在启动时读取它们。它们与应用程序以下版本中的文件相同:[NestJS]、[ASP.NET Core MVC]、和 [Spring MVC] 。
11.18.1. i18n/fr.json
| {
"APP": {
"TITLE": "RdvMedecins",
"LOGOUT": "Se déconnecter",
"MENU_SCHEDULE": "Agenda",
"MENU_DOCTORS": "Médecins",
"MENU_PATIENTS": "Clients",
"MENU_MY_AREA": "Mon espace"
},
"LOGIN": {
"TITLE": "Connexion",
"LOGIN_LABEL": "Login",
"PASSWORD_LABEL": "Mot de passe",
"SUBMIT": "Se connecter",
"ERROR": "Login ou mot de passe incorrect.",
"DEMO_ACCOUNTS": "Comptes de démonstration (mot de passe = login) :",
"DEMO_ADMIN": "rôle ADMIN : rendez-vous + gestion des médecins et des clients",
"DEMO_DOCTOR": "rôle DOCTOR : prise et annulation de rendez-vous",
"DEMO_USER": "rôle USER (patients) : réservation pour eux-mêmes, gestion de leur compte",
"CREATE_ACCOUNT": "Créer un compte client",
"CREATE_ACCOUNT_HELP": "Pour créer un compte, recopiez d'abord les caractères de l'image."
},
"DOCTOR_DAY_PICKER": {
"DOCTOR_LABEL": "Médecin",
"CHOOSE_DOCTOR": "-- choisir un médecin --",
"DAY_LABEL": "Jour",
"VIEW_SCHEDULE": "Voir l'agenda"
},
"SCHEDULE": {
"PAGE_TITLE": "Agenda",
"TITLE_PREFIX": "Agenda du",
"COLUMN_SLOT": "Créneau",
"COLUMN_STATUS": "Statut",
"FREE": "Libre",
"BOOK": "Réserver",
"CANCEL_APPOINTMENT": "Annuler",
"CANCEL_CONFIRM": "Annuler ce rendez-vous ?",
"EMPTY_STATE": "Choisissez un médecin et un jour, puis cliquez sur « Voir l'agenda ».",
"NO_SLOTS": "Ce médecin n'a aucun créneau horaire.",
"BOOKED": "Rendez-vous enregistré.",
"CANCELLED": "Rendez-vous annulé.",
"BOOKED_BY_OTHER": "Réservé",
"ALREADY_BOOKED_INFO": "Vous avez déjà un rendez-vous à venir : annulez-le pour en prendre un autre."
},
"BOOKING_DIALOG": {
"TITLE": "Réserver ce créneau",
"CLOSE_ARIA": "Fermer",
"SLOT": "Créneau de {time}",
"PATIENT_LABEL": "Patient",
"CHOOSE_PATIENT": "-- choisir un patient --",
"CANCEL": "Annuler",
"CONFIRM": "Confirmer"
},
"PERSONS": {
"COLUMN_TITLE": "Titre",
"COLUMN_FIRSTNAME": "Prénom",
"COLUMN_LASTNAME": "Nom",
"COLUMN_LOGIN": "Login",
"EDIT": "Modifier",
"DELETE": "Supprimer",
"SAVE": "Enregistrer",
"BACK": "Retour à la liste",
"TITLE_LABEL": "Titre",
"FIRSTNAME_LABEL": "Prénom",
"LASTNAME_LABEL": "Nom",
"LOGIN_LABEL": "Login",
"PASSWORD_LABEL": "Mot de passe",
"LOGIN_HELP_CREATE": "Facultatif : par défaut, le nom en minuscules.",
"LOGIN_HELP_EDIT": "Laisser vide pour ne pas le changer.",
"PASSWORD_HELP_CREATE": "Facultatif : par défaut, identique au login.",
"PASSWORD_HELP_EDIT": "Laisser vide pour ne pas le changer.",
"ACCOUNT_SECTION": "Compte utilisateur"
},
"DOCTORS": {
"TITLE": "Médecins",
"ADD": "Ajouter un médecin",
"EDIT": "Modifier un médecin",
"EMPTY": "Aucun médecin.",
"DELETE_CONFIRM": "Supprimer ce médecin, ses créneaux horaires et son compte utilisateur ?",
"ADDED": "Le médecin {name} a été ajouté (login : {login}).",
"UPDATED": "Le médecin {name} a été modifié.",
"DELETED": "Le médecin {name} a été supprimé."
},
"CLIENTS": {
"TITLE": "Clients",
"ADD": "Ajouter un client",
"EDIT": "Modifier un client",
"EMPTY": "Aucun client.",
"DELETE_CONFIRM": "Supprimer ce client, son compte utilisateur et tous ses rendez-vous ?",
"ADDED": "Le client {name} a été ajouté (login : {login}).",
"UPDATED": "Le client {name} a été modifié.",
"DELETED": "Le client {name} a été supprimé."
},
"ERROR_PAGE": {
"TITLE": "Erreur",
"BACK": "Retour à l'accueil"
},
"ERRORS": {
"LOGIN_TAKEN": "Ce login est déjà utilisé par un autre compte.",
"DOCTOR_ALREADY_EXISTS": "Un médecin portant ce prénom et ce nom existe déjà.",
"PATIENT_ALREADY_EXISTS": "Un client portant ce prénom et ce nom existe déjà.",
"DOCTOR_HAS_APPOINTMENTS": "Ce médecin a des rendez-vous : annulez-les avant de le supprimer.",
"SLOT_ALREADY_BOOKED": "Ce créneau vient d'être réservé par quelqu'un d'autre.",
"CONCURRENT_UPDATE": "Cette fiche a été modifiée entre-temps par un autre utilisateur. Revenez à la liste et rouvrez-la avant de recommencer.",
"DOCTOR_NOT_FOUND": "Ce médecin n'existe pas (ou plus).",
"PATIENT_NOT_FOUND": "Ce client n'existe pas (ou plus).",
"SLOT_NOT_FOUND": "Ce créneau n'existe pas (ou plus).",
"APPOINTMENT_NOT_FOUND": "Ce rendez-vous n'existe pas (ou plus).",
"INVALID_DATE": "La date demandée n'est pas valide.",
"CHOOSE_PATIENT": "Choisissez un patient.",
"INVALID_FORM": "Le formulaire contient des erreurs.",
"INVALID_TITLE": "Choisissez un titre dans la liste.",
"FIRSTNAME_REQUIRED": "Le prénom est obligatoire.",
"FIRSTNAME_TOO_LONG": "Le prénom ne doit pas dépasser 20 caractères.",
"LASTNAME_REQUIRED": "Le nom est obligatoire.",
"LASTNAME_TOO_LONG": "Le nom ne doit pas dépasser 20 caractères.",
"INVALID_LOGIN": "30 caractères au plus : lettres minuscules non accentuées, chiffres, point, tiret, souligné.",
"PASSWORD_TOO_LONG": "Le mot de passe ne doit pas dépasser 72 caractères.",
"SESSION_EXPIRED": "Votre session a expiré : reconnectez-vous.",
"BAD_REQUEST": "La requête est invalide.",
"FORBIDDEN": "Votre rôle ne vous permet pas d'accéder à cette page.",
"NOT_FOUND": "Cette page n'existe pas.",
"SERVER_ERROR": "Une erreur inattendue s'est produite. Réessayez plus tard.",
"TOO_MANY_ATTEMPTS": "Trop de tentatives infructueuses. Réessayez dans {minutes} minute(s).",
"WRONG_CAPTCHA": "Les caractères recopiés ne correspondent pas à l'image. Une nouvelle image vous est proposée.",
"TOO_MANY_ACCOUNTS": "Trop de comptes ont été créés depuis votre connexion. Réessayez dans {minutes} minute(s).",
"LOGIN_REQUIRED": "Le login est obligatoire.",
"PASSWORD_REQUIRED": "Le mot de passe est obligatoire.",
"PASSWORD_TOO_SHORT": "Le mot de passe doit comporter au moins {min} caractères.",
"CONFIRMATION_REQUIRED": "Confirmez le mot de passe.",
"PASSWORDS_DIFFER": "La confirmation ne correspond pas au mot de passe.",
"CURRENT_PASSWORD_REQUIRED": "Saisissez votre mot de passe actuel.",
"WRONG_CURRENT_PASSWORD": "Mot de passe actuel incorrect.",
"PAST_DATE": "On ne peut pas prendre de rendez-vous à une date passée.",
"PATIENT_HAS_UPCOMING_APPOINTMENT": "Ce patient a déjà un rendez-vous à venir : il faut l'annuler avant d'en prendre un autre.",
"CAPTCHA_BEFORE_ACCOUNT": "Pour créer un compte, recopiez d'abord correctement les caractères de l'image, puis cliquez sur « Créer un compte client »."
},
"CAPTCHA": {
"LABEL": "Recopiez les caractères de l'image",
"IMAGE_ALT": "Image de vérification anti-robots",
"NEW_IMAGE": "Autre image",
"HELP": "Majuscules ou minuscules, peu importe."
},
"REGISTRATION": {
"TITLE": "Créer un compte client",
"INTRO": "Ce compte vous permettra de prendre vous-même vos rendez-vous.",
"LOGIN_HELP": "Lettres minuscules non accentuées, chiffres, point, tiret, souligné.",
"PASSWORD_HELP": "Au moins {min} caractères.",
"SUBMIT": "Créer mon compte",
"BACK_TO_LOGIN": "Retour à la connexion",
"DONE": "Votre compte a été créé. Vous pouvez vous connecter avec le login {login}."
},
"ACCOUNT": {
"CONFIRMATION_LABEL": "Confirmation du mot de passe"
},
"AREA": {
"TITLE": "Mon espace",
"HELLO": "Bonjour {name}",
"MANAGE_ACCOUNT": "Gérer mon compte",
"MANAGE_ACCOUNT_HELP": "Modifier mes informations, mon mot de passe, ou supprimer mon compte.",
"VIEW_SCHEDULE": "Voir un agenda",
"VIEW_SCHEDULE_HELP": "Consulter l'agenda d'un médecin et réserver un créneau.",
"MY_APPOINTMENT": "Mon rendez-vous",
"SEE_IN_SCHEDULE": "voir dans l'agenda",
"CANCEL_APPOINTMENT": "Annuler ce rendez-vous",
"NO_APPOINTMENT": "Vous n'avez aucun rendez-vous à venir."
},
"MY_ACCOUNT": {
"TITLE": "Gérer mon compte",
"NEW_PASSWORD_LABEL": "Nouveau mot de passe",
"CURRENT_PASSWORD_LABEL": "Mot de passe actuel",
"CURRENT_PASSWORD_HELP": "Obligatoire pour enregistrer une modification.",
"BACK": "Retour à mon espace",
"DELETE_TITLE": "Supprimer mon compte",
"DELETE_HELP": "Votre compte sera définitivement supprimé, ainsi que tous vos rendez-vous.",
"DELETE_CONFIRM": "Supprimer définitivement votre compte ? Votre rendez-vous éventuel sera annulé.",
"DELETE_SUBMIT": "Supprimer mon compte",
"UPDATED": "Votre compte a été modifié.",
"DELETED": "Votre compte a été supprimé."
},
"CONFIRMATION": {
"TITLE": "Confirmation",
"NO": "Non, revenir",
"YES": "Oui, confirmer"
}
}
|
键按页面或主题分组:[APP] (导航栏)、[LOGIN]、[SCHEDULE]、[BOOKING_DIALOG] (预订窗口)、[PERSONS], [DOCTORS]、[CLIENTS]、[ERRORS] (所有错误消息,包括来自表单验证器和业务层的消息)等。消息参数写作 [{name}]、[{login}]、[{minutes}]、[{min}]、[{time}]。
11.18.2. i18n/en.json
英文字典拥有完全相同的键。下面是几行用于对照:
| {
"APP": {
"TITLE": "RdvMedecins",
"LOGOUT": "Log out",
"MENU_SCHEDULE": "Schedule",
"MENU_DOCTORS": "Doctors",
"MENU_PATIENTS": "Patients",
"MENU_MY_AREA": "My area"
},
"LOGIN": {
"TITLE": "Login",
"LOGIN_LABEL": "Login",
"PASSWORD_LABEL": "Password",
"SUBMIT": "Log in",
"ERROR": "Incorrect login or password.",
"DEMO_ACCOUNTS": "Demo accounts (password = login):",
"DEMO_ADMIN": "ADMIN role: appointments + doctor and patient management",
"DEMO_DOCTOR": "DOCTOR role: booking and cancelling appointments",
"DEMO_USER": "USER role (patients): booking for themselves, managing their account",
"CREATE_ACCOUNT": "Create a patient account",
"CREATE_ACCOUNT_HELP": "To create an account, first type the characters shown in the image."
|
再增加一种语言只需再多一个字典:需要把它添加到翻译器的列表([LANGUAGES])中,并在导航栏中增加一个按钮。
11.19. 静态文件
[static] 文件夹包含应用程序的样式表、脚本,以及 [Bootstrap] ([lib/bootstrap] 文件夹:官方发行版中的 [bootstrap.min.css] 样式表及其许可证;应用程序不使用 [Bootstrap] 中的 [JavaScript])。
11.19.1. static/css/styles.css
| /* =========================================================================
static/css/styles.css - a few settings on top of Bootstrap
(the same as in the ASP.NET Core MVC and Spring MVC 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] 添加的几条额外规则,与应用程序之前的版本相同。错误区域(第 23–32 行)是粘性的 ([position: sticky]、[bottom: 1rem]):如果页面比窗口高(有十二个时间段的日程),它会一直显示在窗口底部,而不是消失在折叠线以下。[z-index: 1060] 使它位于模态窗口的灰色背景之上。
11.19.2. static/js/app.js
| // =========================================================================
// static/js/app.js:应用唯一的 JavaScript。
// -------------------------------------------------------------------------
// 整个应用无需 JavaScript 也能运行。此脚本增加了一项
// 便利功能:在发送带有属性
// data-confirmation="..." 的表单之前,弹出模态对话框询问 "Are you sure?"
// (对话框本身在页面中: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');
// 焦点落在 "No" 上:不小心按下回车键不会删除任何东西
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. 对话框的按钮(Yes / No / 关闭叉号)
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();
}
}
});
})();
|
示例 21 中的脚本,已补充完整:
- 第 16–18 行:如果页面没有确认窗口,脚本什么也不做;
- 第 26–34 行:打开时,消息通过 [textContent] 放入,而不是 [innerHTML]:它被显示为文本 ,绝不会被解释为 HTML。焦点移到“否”按钮上:不小心按下 Enter 键不会删除任何内容;
- 第 37–41 行:关闭时,焦点会回到之前拥有它的元素(“删除”按钮),这对键盘导航很重要;
- 第 54–65 行:窗口内的点击。[closest('[data-action]')] 从被点击的元素开始,沿其父元素逐级向上,查找带有属性 [data-action] 的元素:因此,对按钮内图标的点击会归属于该按钮。如果没有找到元素,运算符 [?.] 会返回 [undefined] 而不是引发错误。点击变灰的背景会关闭窗口;
- 第 71–83 行:键盘行为:Esc 键关闭窗口;Tab 和 Shift-Tab 在窗口中的按钮之间循环切换焦点,而不会移到后面变灰的页面上。