# 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)。