# 10-医院管理系统 - 功能说明

# 项目概述

本项目是基于 Django 3.2 + Django REST Framework + Vue 3 + Element Plus 的前后端分离「医院管理系统」工程项目，目前处于基础框架搭建阶段：已经完成通用的多角色后台框架、账号体系（注册、登录、找回密码、个人信息与密码修改、管理员重置密码）、JWT 认证与中间件拦截、文件上传、统一响应格式，并集成了 Java 版代码生成器（CodeGenerator），可在建表后批量生成 Django 与 Vue3 的 CRUD 代码；但医院业务模块（科室、医生、挂号预约、就诊记录等）尚未生成，代码中不存在任何医院业务表与业务接口，现有的 pet（宠物）模块是脚手架自带的示例模块，用于演示代码生成与 CRUD 页面效果。

# 项目概览

# ✨ 创新点

# 1. 模块化独立 App 架构

要点：后端按职能拆分为独立 Django App——apps/admin（管理员接口）、apps/user（用户接口）、apps/pet（示例模块）、apps/common（登录注册、文件上传等公共接口）。
要点：每个 App 自带 models.py、XxxSerializer.py、views.py、urls.py，由 project/urls.py 统一挂载（/admin/、/user/、/pet/、/common/）。
要点：apps/admin/apps.py 通过 label = 'custom_admin' 设置唯一应用标签，避免与 django.contrib.admin 冲突而导致的 App label 重复报错。

# 2. 自定义 JWT 认证与中间件统一拦截

要点：utils/jwt_auth.py 使用 PyJWT 生成 / 解析 Token，算法 HS256，密钥直接复用 Django 的 SECRET_KEY，默认有效期 60*24*30 分钟（30 天）。
要点：Token 载荷中携带 id、username、type（ADMIN / USER）三项信息，前端把 Token 放在请求头 token 字段中传递（非标准 Authorization）。
要点：middleware/TokenInterceptorMiddleware.py 全局校验 Token，白名单外的一律要求登录，校验失败统一返回 {"code": 401} 由前端跳转登录页。

# 3. Java 代码生成器一键生成 CRUD

要点：CodeGenerator 基于 Spring Boot 2.5.6 + MyBatis-Plus Generator 3.5.2 + Velocity 2.3，读取数据库表结构后批量生成代码。
要点：一次生成 Django 侧 models.py、序列化器、views.py（分页/新增/更新/批量删除/详情/列表）、urls.py，以及 Vue3 侧带搜索、表格、分页、弹窗表单的后台管理页面。
要点：生成内容会自动注册到 settings.py 的 INSTALLED_APPS、project/urls.py、frontend/src/router/index.js 与 AdminLayout.vue 菜单，并带重复检测。

# 4. 统一响应格式与全局异常处理体系

要点：apps/common/ResponseMessage.py 提供 success / failed / other / jump 四个静态方法，所有接口统一返回 code、msg、data 三段结构。
要点：utils/custom_exception.py 定义了 CustomException、NotFoundException、PermissionDeniedException、UnauthorizedException、ValidationException、BusinessException 六类业务异常。
要点：utils/exception_handler.py 提供全局异常处理器（优先级：自定义异常 → Django 内置异常 → DRF 异常 → 未知异常），统一转换为 code / msg / data 格式并记录日志。

# ✨ 项目亮点

# 一、业务功能亮点

双角色账号体系：系统按 ADMIN（管理员）与 USER（普通用户）两种角色划分，角色只存在于 JWT Token 的 type 字段中，登录时由前端选择、后端写入 Token，不落库。
完整的账号全流程：提供注册（PUT /common/register）、登录（POST /common/login）、找回密码（POST /common/retrievePassword）、查询当前用户（GET /common/currentUser）、修改个人信息（POST /common/updateCurrentUser）、修改密码（POST /common/updatePassword）、管理员重置密码（POST /common/resetPassword）。
后台账号与用户管理：后台提供「管理员管理」（/admin/admin）与「用户管理」（/admin/user）两个页面，支持分页查询、按用户名与手机号搜索、新增、编辑、单条/批量删除，并支持管理员一键「重置密码」。
示例业务模块：pet 模块提供「宠物分类管理」菜单（/admin/pet）与宠物信息完整 CRUD 接口（分页、列表、新增、更新、删除、详情），作为代码生成器与页面模板的落地示例。

# 二、技术实现亮点

现代化前端技术栈：采用 Vue ^3.4.29（Composition API + <script setup>）、Element Plus ^2.8.4、Vite ^5.3.1、Vue Router ^4.4.3、Pinia ^2.2.2、Axios ^1.7.5；另在 package.json 中预置了 ECharts ^5.5.1、wangEditor ^5.1.14、@element-plus/icons-vue ^2.3.1、dayjs ^1.11.13、lodash ^4.17.21 等常用依赖。
稳定可靠的后端架构：Django ~=3.2（settings.py 由 Django 3.2.20 生成）+ Django REST Framework ~=3.14.0，配套 PyJWT ~=2.7.0、PyMySQL 1.1.0 / mysqlclient 2.1.1、django-cors-headers 4.2.0、drf-yasg 1.21.7；接口均基于 DRF 的 APIView / GenericAPIView 实现。
完善的数据库设计：sql/sql.sql 建表脚本包含 2 张基础表（admin、user），Django 模型层共定义 3 张表（admin、user、pet）；表之间采用逻辑外键关联（如 pet.category_id、pet.user_id 均为整型字段，不建物理外键），表的字符集为 utf8mb4 / utf8mb4_unicode_ci，主键统一为 bigint 自增且注释为「ID」。
代码生成器支持：集成 Java 版代码生成器 CodeGenerator，可在 CodeGeneratorMain.java 中配置数据库连接与「表名 + 中文名 + App 名」列表，一键生成 Django 后端与 Vue3 前端 CRUD 代码，并自动注册 App、路由与后台菜单。
安全性设计：
- Token 认证与拦截：TokenInterceptorMiddleware 对非白名单请求强制校验 Token，并将解析出的 id、username、type 注入 request，供视图做身份判断。
- 越权校验：UpdateCurrentUserAPIView、UpdatePasswordAPIView 均校验 id 必须等于当前登录用户 request.id，否则返回「无权修改其他用户信息 / 密码」；ResetPasswordAPIView 校验 request.type 必须为 ADMIN，否则返回「无权执行此操作」。
- 接口白名单：仅放行 /common/login、/common/register、/common/retrievePassword 等少量接口，/uploads/、/static/、/swagger/、/django-admin/ 按前缀放行。
- 跨域控制：通过 django-cors-headers 配置 CORS_ORIGIN_ALLOW_ALL = True，并在 CORS_ALLOW_HEADERS 中显式允许 token 请求头。
- 密码存储：按框架约定，admin.password、user.password 字段长度均为 varchar(25)，登录时进行明文比对（apps/user/views.py 中保留了 MD5 校验的注释代码，未启用）。

# 三、用户体验亮点

双界面设计：前台为顶部横向导航 + 内容区的简洁展示界面（FrontLayout.vue，菜单「首页 / 个人中心」）；后台为左侧深色侧边导航 + 顶栏用户下拉的管理界面（AdminLayout.vue，菜单「首页 / 管理员管理 / 用户管理 / 宠物分类管理」）。
响应式布局：FrontLayout.vue 使用 @media (max-width: 768px) 在小屏下隐藏用户名文字与菜单文字；个人中心页面通过 el-col 的 :xs="24" :sm="6/18" :md="5/19" 实现响应式分栏；登录、注册、找回密码页使用全屏背景图居中卡片布局。
交互优化：
- 友好的加载提示和错误提示。
- 重要操作的确认弹窗。
- 及时的全局消息提示。
- 严谨的前后端表单验证。
文件上传体验：封装通用上传组件 components/MyUpload.vue——支持 imageCard / image / video / audio / file 五种类型自动切换上传样式与 accept 限制；上传请求自动携带 Token；单文件模式（limit=1）下再次选择文件即自动替换；超出数量限制时给出「最多只允许上传 N 张图片」提示；支持图片/视频/音频预览弹窗与文件下载；头像栏同时用 el-image + :preview-teleported="true" 支持表格内点击预览。

# 管理员

# 系统管理

管理员管理：在「管理员管理」页面（/admin/admin）分页查看账号列表（ID、用户名称、昵称、用户头像、电话、邮箱），支持按用户名、手机号搜索与重置，支持新增账号（未填写密码时后端默认写入 123456）、编辑账号、单条删除与勾选批量删除，并可对任意账号执行「重置密码」——调用 POST /common/resetPassword?type=ADMIN&id=xx 将密码重置为 123456。

普通用户管理：在「用户管理」页面（/admin/user）分页查看用户列表，操作能力与管理员管理一致（搜索、新增、编辑、删除、批量删除、重置密码）；对应接口为 /user/page、/user/list、/user/save、/user/delete（批量删除使用 POST + ID 数组）。

个人账号：后台顶栏用户下拉菜单提供「个人信息」（跳转 /admin/editCurrentUser，可修改头像、邮箱、电话）、「修改密码」（跳转 /admin/editPassword，校验旧密码后修改）与「退出登录」（清空 localStorage 并跳回登录页）。

# 示例模块

宠物类型：「宠物分类管理」菜单（/admin/pet）对应的页面提供分类名称搜索、新增、编辑、删除、批量删除与分页功能，接口复用 /pet/page、/pet/add、/pet/update、/pet/delBatch。

宠物信息：提供完整的宠物信息 CRUD 接口——分页查询（GET /pet/page，支持按宠物名称模糊搜索、pageNum 分页、页大小 10 条）、全部列表（GET /pet/list）、新增（POST /pet/add）、更新（PUT /pet/update，局部更新）、批量删除（DELETE /pet/delete）、详情（GET /pet/detail）；字段包含宠物名称、分类 ID、年龄（月）、性别、品种、毛色、健康状况、宠物照片、详细描述、来源类型、发布用户 ID、创建时间。对应的完整管理页面为 frontend/src/views/admin/Pet.vue。

# 普通用户

# 账号功能

注册/登录：前台注册页（/register）填写头像、用户类型、用户名、密码、昵称后提交 PUT /common/register，后端先校验用户名是否重复，再写入 user 表；登录页（/login）选择用户类型（管理员 / 用户）并提交 POST /common/login，后端根据 type 分别查询 admin 表或 user 表并比对密码，成功后返回用户信息与 Token，前端将 token、currentUser 写入 localStorage，并按角色跳转——USER 进入前台 /，ADMIN 进入后台 /admin。

找回密码：找回密码页（/retrievePassword）填写手机号、验证码与新密码后提交 POST /common/retrievePassword，后端按 contact（联系方式）匹配用户并更新密码（代码中保留了验证码校验的 TODO 注释，当前未实际校验验证码）。

# 个人中心

个人信息：前台「个人中心 → 个人信息」（/personalCenter/profile）展示用户名、昵称、邮箱、联系方式（数据取自本地登录信息）；点击「编辑信息」进入 /editCurrentUser，可修改头像、邮箱、电话，提交 POST /common/updateCurrentUser 成功后重新拉取 GET /common/currentUser 并刷新本地用户信息。

修改密码：/editPassword 页面填写旧密码与新密码，提交 POST /common/updatePassword，后端校验身份与旧密码一致后更新，成功后前端清空本地登录信息并跳转登录页重新登录。

# 功能权限对照表

功能模块	管理员	普通用户
注册	✓	✓
登录（含角色选择）	✓	✓
找回密码	✓	✓
查看当前用户信息	✓	✓
修改个人信息	✓ 仅本人	✓ 仅本人
修改密码	✓ 仅本人	✓ 仅本人
文件上传	✓	✓
后台首页	✓	-
管理员管理（增删改查、批删）	✓	-
普通用户管理（增删改查、批删）	✓	-
重置他人密码	✓	-
宠物分类管理	✓	-
前台首页	-	✓
个人中心	-	✓

说明：后台与前台的角色隔离由前端布局实现——AdminLayout.vue 检测到 currentUser.type === 'USER' 时跳回 /，FrontLayout.vue 检测到 type !== 'USER' 时跳转 /admin；后端 /admin/* 系列接口当前仅要求登录（Token 校验），未做额外的角色判断，仅「重置密码」接口在后端校验了 ADMIN 角色。

# 默认账号

# 管理员

用户名: admin
密码: 123456

1
2

来源：sql/sql.sql 中 admin 表初始化数据（nickname 为「系统管理员」，contact 为 13800000000）。

# 测试账号（普通用户）

用户名: user
密码: 123456

1
2

来源：sql/sql.sql 中 user 表初始化数据（nickname 为「管理员」，contact 为 13800000000）。

# 核心业务流程

# 用户注册流程

1. 打开 /register 注册页，填写头像、用户类型、用户名、密码、昵称（前端校验必填项）。
2. 前端提交 PUT /common/register。
3. 后端按 username 查询 user 表，若已存在则返回「用户名重复」。
4. 后端移除前端传入的 type 字段（角色不落库），使用 UserSerializer 校验并写入 user 表。
5. 返回用户信息，前端提示「注册成功，正在跳转」并跳转 /login。

1
2
3
4
5

# 登录与 Token 认证流程

1. 在 /login 选择用户类型（ADMIN / USER），输入账号密码，提交 POST /common/login。
2. 后端校验 type 是否为 ADMIN / USER，无效则返回「无效的用户类型」。
3. 按 type 查询 admin 表或 user 表，用户不存在或密码不一致时统一返回「用户名或者是密码错误」。
4. 校验通过后生成 JWT（HS256，密钥为 Django SECRET_KEY，有效期 30 天），载荷为 {id, username, type}。
5. 返回用户信息 + token + type，前端写入 localStorage（token、currentUser），按角色跳转 / 或 /admin。
6. 后续请求由 axios 请求拦截器自动在请求头写入 token；TokenInterceptorMiddleware 校验非白名单接口，
   校验通过则把 id / username / type 注入 request，校验失败返回 code 401，前端清除 token 并跳转登录页。

1
2
3
4
5
6
7

# 账号管理与重置密码流程

1. 管理员在 /admin/admin 或 /admin/user 页面点击「新增」，填写头像、用户名、昵称、电话、邮箱并提交。
2. 新增接口（POST /admin/add 或 POST /user/save）中若未传密码，后端默认写入 123456。
3. 管理员点击列表中的「重置密码」，前端请求 POST /common/resetPassword?type=ADMIN&id=xx。
4. 后端校验当前登录用户 type 必须为 ADMIN，否则返回「无权执行此操作」。
5. 校验通过后把目标账号密码更新为 123456，返回「密码重置成功，新密码为：123456」。

1
2
3
4
5

# 代码生成器生成业务模块流程

1. 在目标数据库中按规范建表（主键 id 为 bigint 自增且注释「ID」，状态类字段用中文描述，关联字段用 xx_id 逻辑关联）。
2. 修改 CodeGenerator/src/main/java/com/project/platform/utils/generator/DjangoProjectPathConfig.java 的 PROJECT_ROOT，
   指向本项目的 project 目录（当前文件中的路径为模板示例路径，需按实际项目修改）。
3. 在 CodeGeneratorMain.java 中配置数据库连接（地址、端口、用户名、密码、库名）与待生成的表列表
   （参数格式：表名、中文显示名称、Django app 名称），运行 main 方法。
4. 生成 Django 侧 models.py、序列化器、views.py、urls.py 与 Vue3 侧管理页面，并自动注册 INSTALLED_APPS、路由与后台菜单。
5. 启动后端与前端验证生成结果（python manage.py runserver / npm run dev）。

1
2
3
4
5
6
7

# 技术说明

# 系统架构

前端：Vue 3.4.29 + Element Plus 2.8.4 + Vite 5.3.1
后端：Django 3.2（由 3.2.20 生成）+ Django REST Framework 3.14.0
数据库：MySQL（当前配置库名 django_template，字符集 utf8mb4）
认证：自定义 JWT Token（HS256，请求头字段 token）

# 访问地址

后端API：http://127.0.0.1:8000（frontend/.env.development 的 VITE_APP_API_URL 与 settings.py 的 HTTP_PICTURE 均指向该地址，Django 开发服务器默认端口为 8000）
前端页面：http://localhost:5173（开发环境，Vite 默认端口；vite.config.js 中未显式配置 server.port）
接口文档：http://127.0.0.1:8000/swagger/（drf-yasg）

# 数据库

数据库名：django_template（沿用模板默认值，尚未按本项目重命名）
字符集：utf8mb4（sql/sql.sql 中表的排序规则为 utf8mb4_unicode_ci）
总表数：sql/sql.sql 建表脚本包含 2 张表（admin、user）；Django 模型层共定义 3 张表（admin、user、pet）

表名	模型类	所在 App	说明
admin	Admin	apps/admin	管理员表（username、password、nickname、email、contact、avatar）
user	User	apps/user	用户表（username、password、nickname、email、contact、avatar）
pet	Pet	apps/pet	宠物信息示例表（name、category_id、age、gender、breed、color、health_status、image、description、source_type、user_id、create_time）

说明：apps/common/models.py 中还保留了 Test、A、B、C 四个教学示例模型类（未指定 db_table，且 apps.common 未注册到 INSTALLED_APPS），不属于业务表；pet 表在 sql/sql.sql 中暂无对应建表语句。

# API接口规范

RESTful风格：
GET    /module/page          # 分页查询（pageNum 页码，默认每页 10 条）
GET    /module/list          # 查询全部（不分页）
POST   /module/add           # 新增
PUT    /module/update        # 更新（局部更新）
DELETE /module/delete        # 批量删除（请求体为 ID 数组）

响应格式：
{
    "code": 200,
    "msg": "操作成功",
    "data": {...}
}

1
2
3
4
5
6
7
8
9
10
11
12
13

实际接口前缀：/common/*（登录注册等）、/admin/*（管理员管理）、/user/*（用户管理）、/pet/*（示例模块）、/file/upload（文件上传）。分页接口统一返回 {"total": 总数, "list": 列表}；失败时 code 为 500 并携带 msg；未登录时 code 为 401。

# 系统特色

# 文件上传

接口：POST /file/upload（apps/common/views.py 的 FileUploadAPIView，参数名为 file）。
文件命名：使用 uuid4 生成唯一文件名并保留原扩展名，避免同名覆盖。
存储位置：settings.UPLOAD_PATH = "uploads\\"（相对项目根目录，目录不存在时自动创建）；媒体访问配置为 MEDIA_URL = "/uploads/"、MEDIA_ROOT = BASE_DIR/uploads。
访问地址：settings.HTTP_PICTURE = "http://127.0.0.1:8000/uploads/"，接口返回 {"name": 原文件名, "url": 访问地址}。
限制说明：后端接口与 settings.py 中未配置文件大小或文件类型限制；前端 MyUpload.vue 依据 type 设置 accept（image/*、video/*、audio/*），默认最多 100 个文件，富文本组件中视频上传限制为 100 * 1024 * 1024。
上传方式：所有上传请求都会自动携带登录 Token（MyUpload.vue 与 MyEditor.vue 均设置请求头 token）。

# 统一响应格式

apps/common/ResponseMessage.py 统一封装返回结构：success(data) 返回 code 200 / msg「操作成功」；failed() 返回 code 500 / msg「操作失败」；other(data) 返回 code 500 且把提示信息同时放入 data 与 msg；jump(code, data) 用于返回 401 等需要前端跳转的状态。

# 全局异常处理

utils/exception_handler.py 提供 custom_exception_handler，按「自定义异常 → Django 内置异常（ObjectDoesNotExist、Http404、PermissionDenied）→ DRF 异常 → 未知异常」的顺序统一处理，输出 code / msg / data 结构并写入日志（需在 settings.py 的 REST_FRAMEWORK 中配置 EXCEPTION_HANDLER 后生效，当前配置尚未启用该项）。

# 工具函数库

utils/jwt_auth.py：create_token 生成 Token、get_payload 解析并区分「认证失败 / 已失效 / 非法 Token」三种错误，另提供 JwtQueryParamAuthentication、JwtHeaderAuthentication 两个 DRF 认证类。
utils/DateUtil.py：get_last_seven_days() 取最近 7 天日期、get_date() 返回格式化为 %Y-%m-%d 的日期列表。
utils/current_user.py + middleware/CurrentUserMiddleware.py：基于 ThreadLocal 保存当前登录用户，便于在任意位置通过 get_current_user() 等方法获取用户信息（中间件当前未登记到 MIDDLEWARE）。
apps/common/signals.py：pre_save_timestamp_handler 在保存时自动写入 create_time（为空时）与 update_time，已挂载到 Admin、User、Pet 模型。
前端 utils/tools.js：封装 isLogin()、getCurrentUser()、getToken()、formatDateToYYYYMMDD()；utils/http.js 统一 axios 实例（超时 5000ms、请求头自动携带 token、按 code 200/401/409/500 统一处理并弹出全局消息）。

# 前端通用组件

components/MyUpload.vue：五种类型的通用文件上传组件，被登录注册页头像、个人信息与后台新增/编辑表单复用。
components/MyEditor.vue：基于 wangEditor（@wangeditor/editor ^5.1.14、@wangeditor/editor-for-vue ^5.1.12）封装的可复用富文本编辑器组件，支持工具栏、图片与视频上传（上传地址与 Token 已配置）；该组件当前已在 admin/Admin.vue、admin/User.vue 中引入，但尚未在页面模板中实际渲染使用。

# 代码生成器

CodeGenerator 为独立的 Java 工具工程（Spring Boot 2.5.6 + MyBatis-Plus Generator 3.5.2 + Velocity 2.3 + mysql-connector-j 8.1.0），支持按表批量生成 Django 后端 CRUD 与 Vue3 管理页面，并自动注册 App、路由与后台菜单；模板文件位于 src/main/resources/templates/page.vue.vm。

# 项目当前状态说明

重要提示：本项目目前为基础框架版本，医院管理相关的业务模块（如科室、医生、挂号预约、就诊记录等）尚未在代码中实现。框架已具备：账号体系、管理员与用户管理、示例模块（宠物类型、宠物信息）、JWT 认证、文件上传、代码生成器。后续可基于 CodeGenerator 依据医院业务数据表批量生成对应模块的 Django + Vue3 代码。

补充说明（均为当前代码的真实状态，便于后续开发对接）：

菜单与页面：后台菜单只有「首页 / 管理员管理 / 用户管理 / 宠物分类管理」四项，前台只有「首页 / 个人中心」两项；后台首页（admin/Home.vue）与前台首页（front/Index.vue）目前仅显示「首页」文字，未接入统计图表（echarts 已在 package.json 中声明但源码中尚无任何引用）。
路由现状：frontend/src/router/index.js 中将 /admin/pet 指向 views/admin/PetCategory.vue；views/admin/Pet.vue 已存在但未在路由中注册。
分类模块现状：apps/pet/PetCategorySerializer.py 引用的 PetCategory 模型在 apps/pet/models.py 中不存在；「宠物分类管理」页面实际调用的是 /pet/page 接口。
管理员接口现状：apps/admin/views.py 中的增删改查统一操作 User 模型（即 /admin/* 与 /user/* 系列接口读写同一张 user 表）。
test 模块现状：settings.py 与 project/urls.py 中仍注册了 apps.test 与 /test/ 路由，但该 App 目录下已无源码文件。
注册与改密的实现细节：apps/user/views.py 的 RegisterAPIView 会向前端数据中写入 role_type 字段（该字段在 User 模型中不存在），前台注册实际走的是 PUT /common/register；EditPassword.vue 提交的 id 为空字符串，而后端 /common/updatePassword 要求 id 等于当前登录用户 ID，前端页面后续需补充从本地登录信息中回填 id。
数据库与配置：settings.py 中数据库名仍为 django_template，数据库连接指向 118.89.93.2:3306；sql/sql.sql 只包含 admin、user 两张表的建表与初始化数据，pet 表的建表语句尚未纳入该脚本。

# 10-医院管理系统 - 功能说明

# 项目概述

# 项目概览

# ✨ 创新点

# 1. 模块化独立 App 架构

# 2. 自定义 JWT 认证与中间件统一拦截

# 3. Java 代码生成器一键生成 CRUD

# 4. 统一响应格式与全局异常处理体系

# ✨ 项目亮点

# 一、 业务功能亮点

# 二、 技术实现亮点

# 三、 用户体验亮点

# 管理员

# 系统管理

# 示例模块

# 普通用户

# 账号功能

# 个人中心

# 功能权限对照表

# 默认账号

# 管理员

# 测试账号（普通用户）

# 核心业务流程

# 用户注册流程

# 登录与 Token 认证流程

# 账号管理与重置密码流程

# 代码生成器生成业务模块流程

# 技术说明

# 系统架构

# 访问地址

# 数据库

# API接口规范

# 系统特色

# 文件上传

# 统一响应格式

# 全局异常处理

# 工具函数库

# 前端通用组件

# 代码生成器

# 项目当前状态说明

# 一、业务功能亮点

# 二、技术实现亮点

# 三、用户体验亮点