立项原因： 传统房屋租赁依赖人工记录和线下对接，房源状态、租金账期、合同续租与退租、报修维修等环节信息分散、易遗漏，房东与租客之间缺乏统一的信息化协作平台。
行业场景 / 业务背景： 项目面向房屋出租（整租 + 合租）业务场景，覆盖房东、租客、平台管理员三类角色的日常需求：房东需要集中管理房源、租客、合同与租金收缴；租客需要在线找房、签约、缴费、报修；管理员负责系统用户与权限治理。系统通过自动化账单、到期提醒、逾期强制退租等机制，解决租赁过程中"账目算不清、到期记不住、纠纷难追溯"等核心痛点。
核心功能模块（13 个后台接口 + 15 个前端页面）：
认证与权限（RBAC）：登录/注册、JWT 鉴权、三级角色（管理员/房东/租客）、注解式 @LoginRequired + @RequirePermission 权限码校验、动态菜单、可视化权限配置页。
房源管理：整租/合租双模式，房源编号自动生成，图片批量上传（MD5 去重、封面管理），合租名额（单间价 × 名额）计算。
租客管理：租客档案（含身份证正反面）、自动创建登录账号（用户名=手机号）、租房历史记录。
合同管理：签订/终止/续租，合同编号生成，终止自动结算退还资金（押金 + 未用租金），到期提醒。
租金管理：按支付方式（月/季/年付）自动拆分账单、缴费自动计算滞纳金、2 小时支付窗口、收入汇总、CSV 报表导出。
报修管理：工单全流程状态机（待处理→已派单→处理中→已完成/取消）、进度时间轴、租客评价、维修人员管理。
数据统计（仪表盘）：房源总数/空置率/在租合同/逾期租金卡片 + ECharts 图表（月度收入柱状图、房源状态环形图、报修分布饼图、收缴率环形图）。
系统管理：用户管理、操作日志（AOP 自动记录）、权限配置、文件上传。
主要功能描述： 系统实现了房屋租赁全生命周期的数字化管理——从房源发布、租客找房签约，到账单自动生成与收缴、合同到期/逾期自动提醒与强制退租，再到报修工单闭环处理，覆盖了租赁业务的完整链路。
具体任务与实现亮点
RBAC 三级权限体系：注解式鉴权由 LoginInterceptor 统一处理，权限码分 MENU/API/BUTTON 三类，PermissionService 用 ConcurrentHashMap 内存缓存并支持热加载，前端路由 meta.roles + 后端动态菜单 + 页面内按钮级判断三层联动。
多角色行级数据隔离：ADMIN 全量、LANDLORD 只看自己房源、TENANT 只看自己合同/报修，在 Controller/Service 层贯穿实现。
合租复杂计费：单间价 × 名额 × 月数联动计算，支持部分续租、部分退租、同租客名额合并。
账单自动化与逾期机制：按支付周期自动拆单，缴费自动算滞纳金，2 小时超时作废，定时任务自动标记逾期、强制退租并按 overdueRefundRate 扣押金。
AOP 操作日志：切面拦截所有写操作，记录用户、模块、参数、IP（含 X-Forwarded-For 代理穿透）、耗时。
文件 MD5 去重：相同内容只存一份，按月分目录。
前端纯手写 CSV 导出（BOM 头防中文乱码）、ECharts 实例 dispose 防内存泄漏、Promise.allSettled 并发拉取账单。
难点
状态机联动：合同、账单、房源状态跨模块联动（签约→房源转已租、缴费→激活合同、逾期→强制退租并恢复房源）涉及多事务一致性与定时任务协同。
合租名额的增删与退还计算：续租/退租时名额增减与金额、日期的联动计算。
权限与数据隔离的边界控制：需在拦截器、Service 查询条件、前端按钮三层同时保证，避免越权。
定时任务与业务幂等：避免重复作废/重复扣款。
评论