基于Flask的图书借阅管理系统

登录表单含用户名+密码字段；前端校验非空；POST /api/auth/login 验证凭据，成功返回JWT token并跳转角色对应首页，失败返回401及"用户名或密码错误"提示。含三态：loading按钮、空字段提示、网络异常toast。

注册表单含用户名、密码、确认密码、姓名、联系方式；前端校验两次密码一致且非空；POST /api/auth/register 校验用户名唯一性，成功自动分配读者角色入库，默认读者类型为"学生"（由FR-SET-001全局参数控制默认类型，管理员可后续在读者管理中修改），失败返回409（用户名已存在）。

修改密码表单含旧密码、新密码、确认新密码；PUT /api/auth/password 校验旧密码正确性、新密码长度≥6位，成功返回200，失败返回对应错误码（旧密码错误403、格式不符422）。

登录后前端根据JWT中role字段跳转：role=admin进入管理后台首页（含所有管理模块入口），role=reader进入读者首页（仅借阅查询、个人信息、图书检索）。未登录访问任何受保护路由统一跳转登录页。

JWT token有效期24小时，前端存储于localStorage；每次请求在Authorization header带Bearer token；后端中间件校验token有效性，过期返回401；前端Axios拦截器统一拦截401并跳转登录页。无refresh token机制，token过期需重新登录。退出登录清除本地token并跳转登录页。

系统首次部署时通过数据库种子脚本自动创建默认管理员账号（用户名admin，初始密码通过环境变量ADMIN_PASSWORD或配置文件设置，未配置则使用默认密码并强制首次登录修改）。管理员账号写入users表，role=admin。后续如需新增管理员，由现有管理员在后台通过类似读者新增的界面创建（或直接操作数据库）。种子脚本幂等：检测到已有管理员则跳过。

表格分页展示图书列表，每页默认20条；支持按书名、ISBN、作者、分类关键字搜索；支持按分类、出版社下拉筛选；列含ISBN、书名、作者、分类、库存、可借数量。GET /api/books?page=&size=20&keyword=&category=&publisher= 返回分页数据。三态：loading骨架屏、空数据提示"暂无图书"、接口异常toast。

管理员操作；表单含ISBN、书名、作者、出版社、分类、出版日期、总册数、馆藏位置；POST /api/books 后端校验ISBN唯一性（重复返回409）、必填字段非空；成功后图书自动加入库存，返回201。

管理员操作；点击列表行"编辑"按钮弹出编辑表单，回填当前图书信息；PUT /api/books/:id 更新图书字段（ISBN不可修改），校验规则同新增；成功返回200并刷新列表。

管理员操作；DELETE /api/books/:id 将图书标记为已下架（is_deleted=1），不物理删除数据；若该图书有在借记录则拒绝删除并返回409"存在未归还借阅，无法下架"。

点击列表行或"详情"按钮，侧滑面板展示图书完整信息（含ISBN、书名、作者、出版社、分类、出版日期、总册数、当前在馆数、创建时间）；GET /api/books/:id 返回图书全量字段。

表格分页展示读者列表，每页默认20条；支持按读者编号、姓名、联系电话、读者类型搜索；支持按读者类型（学生/教师/社会）下拉筛选；列含编号、姓名、类型、联系电话、注册日期、当前借阅数。GET /api/readers?page=&size=20&keyword=&type= 返回分页数据。三态：loading骨架屏、空数据提示、异常toast。

管理员操作；表单含读者编号、姓名、读者类型、联系电话、邮箱、最大借阅册数（选填，不填则使用读者类型默认值）；POST /api/readers 后端校验读者编号唯一性（重复返回409），必填字段非空；创建成功返回201。

管理员操作；点击列表行"编辑"弹出编辑表单回填信息；PUT /api/readers/:id 更新读者字段（编号不可修改），校验规则同新增；成功返回200并刷新列表。

管理员操作；DELETE /api/readers/:id 标记读者为已注销（is_deleted=1）；若读者存在未归还借阅记录则拒绝删除并返回409"该读者尚有未归还图书，无法注销"。

点击列表行或"详情"按钮，侧滑面板展示读者完整信息（含编号、姓名、类型、联系方式、注册日期、借阅历史数量、当前在借册数、超期未还数）；GET /api/readers/:id 返回全量字段。

读者状态分为"正常"和"已注销"（is_deleted）。注册即默认为正常，可立即借书；已注销读者不可登录、不可借书。若读者存在超期未还图书，借书时 FR-BORROW-002 校验拦截（而非修改读者状态）。还清所有超期书并缴清罚款后借阅资格自动恢复，无需管理员手动解禁。

管理员操作；表单选择读者（搜索/下拉选）和图书（ISBN扫码或搜索选），自动填入当天为借书日期；POST /api/borrows 创建借阅记录，预计归还日期=借书日期+借阅天数。借阅天数取值优先级：读者类型配置的借阅天数 > 全局默认借阅天数（FR-SET-001）。成功返回201及借阅编号。

借书登记提交时后端校验：(1)读者是否存在且状态正常→否则409"读者不存在或已注销"；(2)当前在借数是否达到最大借阅上限→上限取值：读者个人设置的最大借阅册数（若已设置），否则取读者类型配置的最大借阅册数，超限返回409"已达借阅上限"；(3)读者是否有超期未还图书记录→否则409"存在超期未还，请先归还"；(4)图书库存可借数>0→否则409"该图书暂无库存"；(5)读者是否有未缴罚款→否则409"存在未缴罚款，请先缴纳"。

表格分页展示在借及超期借阅记录（未归还）；支持按读者姓名、图书书名、借阅状态（在借/超期）筛选；列含借阅编号、读者、图书、借书日期、预计归还日期、状态、已超期天数。GET /api/borrows?page=&size=20&reader=&book=&status= 返回分页数据（默认不含已归还记录）。三态：loading、空数据、异常toast。已归还记录在 FR-RETURN-003 中独立展示。

点击借阅记录行，侧滑面板展示完整借阅信息：借阅编号、读者信息（姓名+类型+联系方式）、图书信息（书名+ISBN+作者）、借书日期、预计归还日期、实际归还日期、状态、关联罚款记录（如有）。GET /api/borrows/:id。

管理员操作；通过借阅编号直接检索，或扫描图书ISBN检索在借记录。若通过ISBN检索且该ISBN存在多条在借记录（多册被不同读者借出），弹出列表供管理员选择具体读者和借阅记录。确认归还后 PUT /api/borrows/:id/return 更新实际归还日期=当天、状态改为"已还"、图书库存+1。若超期则自动触发罚款计算并生成罚款记录。成功返回200。

还书时后端自动比较实际归还日期与预计归还日期：若实际>预计，超期天数=实际-预计，自动生成罚款记录（金额=超期天数×每日罚款单价，默认0.5元/天）；若未超期则不生成罚款。计算结果在还书成功响应中返回。

表格分页展示已完成归还的记录；支持按读者姓名、图书书名、归还日期范围筛选；列含借阅编号、读者、图书、借书日期、预计归还日期、实际归还日期、是否超期、关联罚款金额。GET /api/borrows/returned?page=&size=20&reader=&book=&dateFrom=&dateTo= 返回已归还分页数据。三态同借阅列表。

罚款单价由系统配置（默认0.5元/天，管理员可在系统设置中修改）；还书超期时自动按"金额=超期天数×单价"生成罚款记录；同一条借阅记录最多生成一条罚款（不重复计费）。罚款状态初始为"未缴纳"。

管理员操作；在罚款记录列表中点击"缴纳"按钮；PUT /api/fines/:id/pay 将罚款状态改为"已缴纳"，记录缴纳时间；若已缴纳则返回409"该罚款已缴纳，不可重复操作"。

表格分页展示罚款记录；支持按读者姓名、缴纳状态（未缴纳/已缴纳）、罚款日期范围筛选；列含罚款编号、读者、关联图书、超期天数、罚款金额、状态、缴纳时间。GET /api/fines?page=&size=20&reader=&status=&dateFrom=&dateTo= 返回分页数据。三态：loading、空数据、异常toast。

管理员仪表盘展示：总图书册数、在馆册数、借出册数、下架册数；按分类统计饼图展示各类图书占比。GET /api/stats/books 返回聚合数据。

按图书借阅次数降序排列，展示Top20热门图书（书名+作者+借阅次数+当前库存）；支持按时间范围（本月/本季/本年/自定义）筛选。GET /api/stats/popular-books?period=month。

按读者统计借阅数据：读者姓名+类型+总借阅次数+当前在借数+超期次数+未缴罚款总额；支持按读者类型分组汇总。GET /api/stats/reader-borrows。

列出所有当前超期且未归还的借阅记录：读者姓名+联系方式+图书书名+借书日期+预计归还日期+已超期天数。管理员可一键导出或逐条催还。GET /api/borrows/overdue 支持分页。

管理员在超期未还列表（FR-QUERY-004）、借阅排行榜（FR-QUERY-002）、读者借阅统计（FR-QUERY-003）页面可点击"导出"按钮；GET /api/export/overdue-books、/api/export/popular-books?period=、/api/export/reader-borrows 返回CSV文件（Content-Type: text/csv，含BOM头兼容Excel中文），列与对应页面表格一致。三态：导出中loading、成功下载、失败toast。

设计核心表：users(用户+角色)、books(图书)、readers(读者)、borrows(借阅记录)、fines(罚款记录)、settings(系统配置)、reader_types(读者类型)、book_categories(图书分类)。所有表含id主键自增、created_at、updated_at时间戳；软删除字段为is_deleted TINYINT(1)默认0；外键约束保证数据完整性。

所有API统一前缀/api/；使用Blueprint模块化路由（auth、books、readers、borrows、fines、stats、settings）；请求/响应均为JSON格式；统一错误响应格式{"error": true, "code": "ERROR_CODE", "message": "描述"}；JWT中间件保护除登录注册外所有接口。

Vue 3 + Vue Router + Axios 单页应用；路由分管理员区(/admin/*)和读者区(/reader/*)；全局封装Axios拦截器处理JWT注入和401统一跳转；使用Element Plus或Naive UI组件库保证界面简洁实用。

前端所有请求Content-Type: application/json；Authorization: Bearer {token}；后端CORS配置允许前端开发端口(如5173)跨域；生产环境由Flask托管Vue构建产物，或Nginx反向代理统一域名。

读者登录后可见；搜索框按书名/作者/ISBN关键字检索，支持按分类下拉筛选；结果列表展示书名、作者、分类、出版社、可借数量（不含进价、编辑等管理字段）；点击行可查看图书详情（不含管理信息）。GET /api/books/search 仅返回未下架图书。三态：loading、空结果提示、接口异常toast。

读者登录后查看自己的借阅记录；表格分页展示，按状态（在借/已还/超期）Tab切换筛选；列含图书书名、借书日期、预计归还日期、实际归还日期、状态、是否超期、关联罚款金额。GET /api/borrows/mine 自动取当前登录用户，仅返回本人记录。三态同标准列表。

读者登录后查看自己的基本信息：姓名、读者编号、类型、联系电话、邮箱、注册日期、当前在借数、超期未还数、未缴罚款总额；可编辑联系电话和邮箱；PUT /api/readers/me 更新本人联系方式字段，编号和类型不可修改。成功返回200并刷新展示。

读者登录后查看自己的罚款记录；表格分页展示，按缴纳状态（未缴纳/已缴纳）Tab切换筛选；列含罚款编号、关联图书、超期天数、罚款金额、状态、生成日期、缴纳时间。GET /api/fines/mine 自动取当前登录用户，仅返回本人记录。缴纳需到管理员处线下处理（FR-FINE-002），读者端不提供在线缴纳入口。三态同标准列表。

管理员操作；表单修改全局参数：(1)超期罚款单价（元/天，默认0.5）；(2)默认借阅天数（默认30，作为读者类型未配置借阅天数时的兜底值）；(3)新注册读者默认类型（默认"学生"，从已有读者类型中选择）。PUT /api/settings/borrow-config 更新参数，立即生效；GET /api/settings/borrow-config 返回当前值。校验：罚款单价必须>0，借阅天数必须≥1整数，默认读者类型必须为已存在的读者类型。

管理员操作；表格列出所有读者类型（默认含学生/教师/社会）；每种类型可配置：类型名称、默认借阅天数、最大借阅册数；支持新增类型（POST /api/settings/reader-types）、编辑（PUT /api/settings/reader-types/:id）、删除（DELETE，若该类型下已有读者则提示"该类型下存在N名读者，请先迁移"返回409）。

管理员操作；表格列出所有图书分类；支持新增分类（POST /api/settings/book-categories，名称唯一，重复返回409）、编辑分类名称（PUT /api/settings/book-categories/:id）、删除分类（DELETE，若该分类下有未下架图书则提示"该分类下存在N本图书，请先迁移或下架"返回409）。图书新增/编辑时的分类下拉选项由此接口提供。