# AppointSystem
**Repository Path**: musexuanran/appoint-system
## Basic Information
- **Project Name**: AppointSystem
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-21
- **Last Updated**: 2026-11-21
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# AppointSystem — 预约管理系统
基于 **Spring Boot 3.5 + MyBatis + MySQL** 的医疗预约后端服务,附带一套**免构建的单页前端**(原生 JS,由 Spring Boot 直接托管)。
覆盖:**三角色登录鉴权(客户 / 医生 / 管理员,JWT + PBKDF2)**、号源发布与防重叠(按号源上限 `capacity`)、可用号源的多条件检索(分页/排序/严格排除不可用)、预约(客户归属与资格校验、防超卖)、取消(原子释放号源 + 审计记录)、管理员代删预约记录、全局异常处理与统一错误响应。
---
## 1. 技术栈
| 层次 | 选型 |
| --- | --- |
| 运行时 | Java 17 |
| 框架 | Spring Boot 3.5.6(Web / Validation / JDBC) |
| 持久层 | **MyBatis 3(mybatis-spring-boot-starter 3.0.4)**,SQL 全量显式化 |
| 鉴权 | 手写 **JWT(HS256,JDK 内置加密,零新增依赖)** + **PBKDF2 密码哈希** + 注解式 `@RequireRole` / `@PublicAccess` |
| 数据库 | MySQL 5.7+(生产);H2(`demo` / `test` profile,MySQL 兼容模式) |
| 事务 | Spring `@Transactional` + JDBC 事务管理器 |
| 文档 | springdoc-openapi(Swagger UI,公开可访问) |
| 前端 | 原生 HTML/CSS/JS,零构建,`src/main/resources/static` |
| 测试 | JUnit 5 + MockMvc + 并发多线程测试(71 个用例) |
---
## 2. 角色模型
| 角色 | 能力 |
| --- | --- |
| **客户 CUSTOMER** | 注册/登录;浏览可预约号源;选择医生与时间段挂号;取消自己的预约。**看不到后台控制台** |
| **医生 PROVIDER** | 注册/登录;发布/删除**自己的**号源;设置每个号源的号源上限(`capacity`);维护自己的科室与每日默认号源上限 |
| **管理员 ADMIN** | 管理**所有**医生(增删改查、调整号源上限);为任意医生发布号源;改期/删除号源;**代客户删除预约记录**;访问客户目录 |
> 客户、医生通过注册接口自建账号;管理员账号由服务端种子数据 / `AuthService.registerAdmin` 创建(无对外注册接口)。
---
## 3. 目录结构
```
src/main/java/musexuanran/appoint/
├── AppointSystemApplication.java 入口(@EnableScheduling)
├── api/ REST 控制器
│ ├── AuthController.java 登录 / 注册 / 当前身份
│ └── dto/ 请求/响应 DTO(record)+ 分页信封
├── config/ Clock、OpenAPI、CORS、拦截器注册
├── domain/ POJO 领域对象 + 枚举(Role/CustomerStatus/ServiceCategory…)
├── demo/DemoDataInitializer.java demo profile 种子数据(各角色账号)
├── exception/ ApiException / ErrorCode / GlobalExceptionHandler
├── mapper/ MyBatis Mapper 接口
│ └── model/ 读模型(SlotView / AppointmentView,单条 SQL 联表)
├── security/ JWT 签发校验、PBKDF2、AuthInterceptor、@RequireRole/@PublicAccess/@CurrentPrincipal
└── service/ 业务编排(认证、时间段、预约、客户、医生、过期扫描)
└── support/PageQuery.java 分页/排序白名单 → 安全 SQL 片段
src/main/resources/
├── mapper/*.xml MyBatis SQL
├── db/schema-mysql.sql MySQL 建表脚本(生产)
├── db/schema-h2.sql H2 建表脚本(demo/test)
├── static/ 前端 SPA(index.html + assets/)
└── application*.yml 配置(默认 MySQL / demo / test)
docs/ 设计文档、AI 提示词记录、实施简报、Postman 集合
```
---
## 4. 快速开始
### 方式一:零依赖演示(H2 内存库,推荐先跑这个)
```bash
mvn spring-boot:run -Dspring-boot.run.profiles=demo
```
打开 即为前端界面。种子数据已内置三种角色账号:
| 角色 | 用户名 / 密码 |
| --- | --- |
| 管理员 | `admin / admin123` |
| 医生 | `dentist.chen / provider123`(另 `smith.legal`、`tutor.qiming`) |
| 客户 | `zhang.wei / customer123`(另 `li.na`、`wang.qiang`、`suspended`) |
也可以用打包好的 jar:
```bash
mvn -DskipTests package
java -jar target/AppointSystem.jar --spring.profiles.active=demo
```
Swagger UI(公开):
### 方式二:连接 MySQL
```bash
# 1) 建库建表(只需一次)
mysql -uroot -p < src/main/resources/db/schema-mysql.sql
# 2) 启动(默认 root/123456,可用环境变量覆盖)
set DB_USER=root
set DB_PASSWORD=你的密码
set DB_NAME=appoint_system
mvn spring-boot:run
```
或让它自动建表(空库场景):`set DB_INIT=always`。
可用环境变量:`DB_HOST`、`DB_PORT`、`DB_NAME`、`DB_USER`、`DB_PASSWORD`、`SERVER_PORT`、`APP_TIME_ZONE`、`DB_INIT`。
### 运行测试
```bash
mvn test
```
71 个用例全部基于 H2(`test` profile)运行,覆盖鉴权矩阵、号源容量语义、角色越权、**16 线程抢订**等。
---
## 5. API 一览
基址:`/api/v1`。除标注「公开」外,所有接口需要 `Authorization: Bearer `。
### 5.1 认证(Auth)
| 方法 | 路径 | 说明 | 角色 | 状态码 |
| --- | --- | --- | --- | --- |
| POST | `/auth/login` | 登录,返回 JWT | 公开 | 200 / 401 |
| POST | `/auth/register/customer` | 注册客户(username/password/fullName/email) | 公开 | 201 / 400 / 409 |
| POST | `/auth/register/provider` | 注册医生(username/password/name/serviceCategory/dailyCapacity) | 公开 | 201 / 400 / 409 |
| GET | `/auth/me` | 当前登录身份(来自 token) | 任意登录 | 200 |
### 5.2 医生(Providers)
| 方法 | 路径 | 说明 | 角色 | 状态码 |
| --- | --- | --- | --- | --- |
| GET | `/providers?category=&page=&size=&sort=` | 医生分页列表(可按科室过滤) | 公开 | 200 |
| GET | `/providers/{providerId}` | 医生详情 | 公开 | 200 / 404 |
| GET | `/providers/{providerId}/slots?from=&to=` | 某医生的可预约号源 | 公开 | 200 / 404 |
| POST | `/providers/{providerId}/slots` | 发布号源(body: date/startTime/endTime/capacity?) | 医生本人 / 管理员 | 201 / 400 / 403 / 404 / 409 |
| PATCH | `/providers/{providerId}` | 更新医生(科室/名称/每日默认号源上限,PATCH 语义) | 医生本人 / 管理员 | 200 / 403 / 404 |
| DELETE | `/providers/{providerId}` | 删除医生(有号源时 409,级联删除登录账号) | 管理员 | 204 / 403 / 404 / 409 |
### 5.3 号源(Slots)
| 方法 | 路径 | 说明 | 角色 | 状态码 |
| --- | --- | --- | --- | --- |
| GET | `/slots?providerId=&category=&from=&to=&page=&size=&sort=` | **可预约号源检索**(严格排除满/锁定/过期) | 公开 | 200 / 400 |
| GET | `/slots/{slotId}` | 号源详情(含 `capacity`/`bookedCount`/`remaining`) | 公开 | 200 / 404 |
| PUT | `/slots/{slotId}` | 重新排班(改期/改号源上限,仅 AVAILABLE) | 管理员 | 200 / 400 / 404 / 409 |
| DELETE | `/slots/{slotId}` | 删除号源(仅 AVAILABLE) | 医生本人 / 管理员 | 204 / 403 / 404 / 409 |
### 5.4 预约(Appointments)
| 方法 | 路径 | 说明 | 角色 | 状态码 |
| --- | --- | --- | --- | --- |
| POST | `/appointments` | 挂号(body 仅 `slotId`,客户身份来自 token) | 客户 | 201 / 403 / 404 / 409 |
| GET | `/appointments?customerId=&slotId=&status=&page=&size=&sort=` | 预约列表(**按角色自动限定**:客户看自己 / 医生看自己号源 / 管理员看全部) | 任意登录 | 200 |
| GET | `/appointments/{appointmentId}` | 预约详情(越权返回 403) | 任意登录 | 200 / 403 / 404 |
| POST | `/appointments/{appointmentId}/cancel` | 取消(body 仅 `reason`,原子释放号源) | 客户本人 | 200 / 403 / 404 / 409 |
| DELETE | `/appointments/{appointmentId}` | **删除预约记录**(已确认的释放号源,已取消的仅删历史) | 管理员 | 204 / 403 / 404 |
### 5.5 客户(Customers)
| 方法 | 路径 | 说明 | 角色 | 状态码 |
| --- | --- | --- | --- | --- |
| GET | `/customers?page=&size=&sort=` | 客户分页列表 | 管理员 | 200 |
| GET | `/customers/{customerId}` | 客户详情(含 `eligibleToBook`) | 管理员 | 200 / 404 |
分页参数:`page` 从 0 开始,`size` 最大 100,`sort` 形如 `slotDate,asc`(多个字段用 `;` 分隔)。排序字段走**白名单**,非法字段直接 400。
### 统一错误响应
```json
{
"timestamp": "2026-11-21T02:20:56.932Z",
"status": 409,
"code": "DOUBLE_BOOKING",
"message": "Slot 10 has already been booked by another customer",
"path": "/api/v1/appointments",
"violations": [{ "field": "date", "message": "date is required (ISO-8601, e.g. 2026-12-01)" }]
}
```
| HTTP | 错误码 | 触发场景 |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` / `MALFORMED_REQUEST` / `INVALID_PARAMETER` | 字段校验失败、JSON 无法解析、参数类型/排序字段非法 |
| 400 | `INVALID_TIME_RANGE` | 结束时间早于开始时间、零长度、号源已过期 |
| 401 | `UNAUTHORIZED` / `TOKEN_INVALID` / `TOKEN_EXPIRED` / `INVALID_CREDENTIALS` | 未登录 / 签名伪造 / 过期 / 用户名或密码错误(不区分二者,防枚举) |
| 403 | `FORBIDDEN_ROLE` / `PROVIDER_OWNERSHIP_VIOLATION` / `APPOINTMENT_OWNERSHIP_VIOLATION` / `CUSTOMER_NOT_ELIGIBLE` | 角色越权 / 医生操作他人号源 / 取消他人预约 / 客户被停用 |
| 404 | `SLOT_NOT_FOUND` / `PROVIDER_NOT_FOUND` / `CUSTOMER_NOT_FOUND` / `APPOINTMENT_NOT_FOUND` / `ENDPOINT_NOT_FOUND` | 资源不存在 |
| 409 | `USERNAME_TAKEN` / `DUPLICATE_RESOURCE` | 用户名 / 邮箱等唯一约束冲突 |
| 409 | `SLOT_OVERLAP` | 同一医生同日号源重叠 |
| 409 | `SLOT_FULL` / `DOUBLE_BOOKING` / `SLOT_NOT_AVAILABLE` | 号源已约满 / 已预约 / 被锁定 / 已过期 |
| 409 | `CUSTOMER_SCHEDULE_CONFLICT` | 同一客户已有时间重叠的预约 |
| 409 | `APPOINTMENT_ALREADY_CANCELLED` / `APPOINTMENT_NOT_CANCELLABLE` | 重复取消 / 号源已结束 |
| 409 | `PROVIDER_HAS_SLOTS` | 删除仍持有号源的医生 |
| 409 | `CONCURRENT_MODIFICATION` | 行锁等待超时、并发冲突 |
| 500 | `INTERNAL_ERROR` | 未预期异常(服务端记录堆栈,响应不泄露细节) |
---
## 6. 前端功能
`/` 下的单页应用直接调用上面的 API,登录后按角色展示不同导航:
- **登录/注册**:登录、注册客户、注册医生三个入口,登录态存 `localStorage`,所有请求自动注入 Bearer Token,Token 失效自动回到登录页。
- **客户**:`预约大厅`(医生/科室/日期筛选,号源卡片显示「剩余 N / 容量」)+ `我的预约`(取消 + 展示取消时间与原因)。
- **医生**:`医生工作台`(维护科室与每日默认号源上限、发布自己号源、删除自己可预约号源)+ 查看自己号源上的预约。
- **管理员**:`管理后台`(注册/编辑/删除医生、为任意医生发布号源、号源改期/删除、代客户删除预约记录、客户目录、**并发抢订演示**、API 文档入口)。
- 右上角显示当前角色与用户名,可退出登录。
---
## 7. 文档
- [docs/DESIGN.md](docs/DESIGN.md) — 解决方案与设计文档(鉴权、号源容量模型、重叠算法、并发与事务、异常体系、取舍)
- [docs/BRIEFING.md](docs/BRIEFING.md) — 10 分钟实施简报提纲与演示脚本
- [docs/AI_PROMPTS.md](docs/AI_PROMPTS.md) — AI 辅助开发的提示词记录与踩坑复盘
- [docs/AppointSystem.postman_collection.json](docs/AppointSystem.postman_collection.json) — Postman 集合
## 8. 已知限制与后续演进
- **数据库结构管理**:`db/schema-*.sql` 手工维护;生产建议接入 Flyway/Liquibase。
- **号源锁定(LOCKED)**:状态与检索排除逻辑已就绪,暂未提供"短时占位"接口。
- **令牌吊销**:JWT 无状态,登出后令牌在 TTL 内仍有效;如需强制下线需引入黑名单/刷新令牌。
- **可观测性**:可接入 Actuator + Micrometer,对 409 比例与行锁等待打点告警。
- **分页性能**:当前 `COUNT(*)` + `LIMIT/OFFSET`;超大表可改为键集分页(keyset pagination)。