Spring Boot+Vue实战：家庭债务管理系统的还款计划与逾期检测

做家庭理财系统的人不少但真正把“债务”当成一个独立模块来做、而不是塞在流水账里记一笔的其实不多。我自己家里前几年同时背着房贷、车贷和几笔亲友周转借款每个月还款日分散在不同时间额度还不一样用Excel记过一段时间很快就开始漏记、算错。后来我干脆自己用 Spring Boot Java Vue 做了一套家庭理财债务管理系统把三张报表、还款计划、逾期提醒全部收拢到一个界面里。这篇文章从需求拆解、技术选型、数据库建模到前后端核心实现把整套系统的设计思路和踩坑过程完整记录下来适合想自己搭一套家庭财务系统的开发者也适合准备做毕设或练手项目的朋友参考。1. 家庭理财场景里的债务管理到底要管什么很多人一听到“债务管理系统”第一反应是做一套贷款审批、风控评级那种信贷系统。但家庭场景完全是另一回事它的核心不是“风险管理”而是“现金流匹配”。你不需要评估某个人能不能还钱你需要的是搞清楚“每个月15号之前需要准备多少钱、这笔钱从哪里来、如果哪笔逾期了会有什么后果”。我梳理自己家的实际需求之后把债务管理拆成了四个层次。1.1 债务全貌的动态汇总负债得是一张总表第一件事是把所有债务记录到一张总表上。房贷是一笔车贷是一笔信用卡分期是一笔找亲戚借的几万块也是一笔。每笔债务的债权人、原始金额、剩余本金、利率类型、还款周期、剩余期数、下一个还款日都必须单独维护。动态汇总的意思是每次还完款、或者提前还款之后剩余本金要自动刷新不能再靠手改。我第一版就是这么干的结果还款日一到贷方余额不动还得自己动手改字段。后来我把“还款操作”做成了独立的事件流每发生一次还款系统自动生成一条还款流水同时反向更新债务的剩余本金和下一期还款日。这样无论你是按期还款、部分提前还还是结清总表永远是实时的。1.2 还款计划的自动生成别再自己算月供了债务管理最烦的一步是还款计划。等额本息和等额本金的计算逻辑完全不同亲友借款通常又是“约定一个总额、到期一次还清”的模式。每个月的还款额、利息占比、本金占比人工算太容易出错。系统里我内置了三套计算器分别对应这三类最典型的场景。等额本息每个月还款金额固定适合房贷、大部分车贷。核心公式是“本金×月利率×(1月利率)^期数÷((1月利率)^期数-1)”Java里直接按 BigDecimal 算避免 double 的精度问题。等额本金每月本金固定利息逐月递减适合部分银行贷款。首月月供最高之后逐月下降。到期一次还本付息适合亲友借款、短期周转。利息按约定利率和占用天数计算还款日一次性结清。1.3 还款提醒与逾期检测系统要主动说话债务最怕逾期但逾期往往不是“还不起”而是“忘了”。所以提醒功能不是锦上添花是刚需。我在系统里加了两个触发点一个是定时任务每天扫一次所有未结清债务如果“下一个还款日”在3天内就通过站内通知和邮件提醒另一个是逾期检测还款日过了还没流水就自动把债务状态切换成“逾期”并统计逾期天数和罚息估算。很多人觉得这几行逻辑很简单但加上“部分还款只还了利息本金还没动”“宽限期内还款不算逾期”这些真实规则之后状态流转就变得复杂了。我在这一块吃了不少亏后面专门讲。1.4 家庭多角色协作记账不是一个人的事我自己最早做的是单用户版后来发现不行。家里的收支和债务两个人都有参与总不能让一个人每天录入、另一个人靠口头传话。后来我加了家庭账户组支持一个家庭下挂多个成员每个人有独立的收支记录权限债务公开展示还款动作谁都可以操作但操作日志全部留痕。这个设计在真实使用中非常管用夫妻双方各自记自己的消费和收入债务表和还款情况对双方透明谁都不用来回问。2. 技术选型复盘为什么说 Spring Boot Vue 是这套系统的合理答案技术选型这一步说实话我没纠结太久。市面上做全栈家庭应用无外乎几个方案Java 后端配一套前端框架、Python 派系Flask/Django 模板或前端框架、Node.js 全家桶。我最终选了 Spring Boot 2.x Vue 3 Element Plus 的组合理由是具体的。2.1 为什么后端用了 Spring Boot 而不是 Flask家庭财务系统涉及大量金额计算和状态流转类型安全非常重要。Python 写起来快但动态类型很容易在算月供、算利息时翻车比如某个字段从 Decimal 变成了 float精度问题就出来了。Java 配合 BigDecimal 是账务系统最稳妥的选择。Spring Boot 本身带来的收益是省心。Spring Data JPA 帮我省掉了大部分 CRUD 样板代码Spring Security 提供了用户认证和角色控制的基础框架Spring Task 一句话就能启动定时任务。对于一个要长期维护的私人项目框架自带的能力越全我自己要维护的代码就越少。2.2 为什么前端选了 Vue 3 而不是直接配模版引擎做管理系统交互密度不低账单列表要筛选排序、还款日历要切换月份、图表要看趋势如果用 Thymeleaf 那种服务端渲染模板每次操作都要刷新页面体验很割裂。Vue 3 的组合式 API 让组件复用非常顺手比如还款计划表、逾期状态标签、金额格式化这些组件在仪表盘和明细页可以无缝复用。Element Plus 的选择就更实际了——进度条、日期选择器、表格、表单验证都现成我不需要为常见的后台交互自己造轮子。这套组合跑下来最直接的感受就是开发效率高后端专注业务规则前端专注交互展示边界非常清楚。2.3 但愿你别犯的选型错误别一上来就加微服务做这个项目时某位朋友听我说完想法建议我直接拆成用户服务、债务服务、账单服务多个微服务说这样架构先进。我当场拒绝了。一套家庭系统最多几个并发连接拆微服务除了增加运维成本没有任何收益。单体应用 模块化分包已经足够清晰。我把代码分成 controller、service、repository、domain 四层每个业务域用户、账户、流水、债务、还款计划一个 module 包谁也不会和谁纠缠。记住一个原则项目的复杂度决定架构的选择而不是架构图好不好看。3. 数据库建模与核心表设计先把账算明白数据库是这套系统的地基。很多项目做到一半开始改表结构就是因为最开始没想清楚业务关系。我重新设计了核心表结构你有心的话可以照着建。3.1 核心表结构概览我把主要表分成三组用户/家庭组、账户/流水、债务/还款计划。表格里是每张表的核心字段说明。表名职责核心字段说明users用户信息id, name, username, password_hash, rolerole 区分管理员与普通成员家庭共同维护人用普通成员角色只有本人能改自己的资料family_group家庭组id, name, member_count, created_by家庭组的归属信息一个家庭一份账本accounts账户id, family_id, name, balance, type类型分现金、借记卡、信用卡、虚拟账户信用卡余额是负数语义transactions收支流水id, account_id, category_id, amount, type, occur_time, notetype 是 income/expense每笔必须关联账户和分类debts债务主表id, family_id, name, creditor_name, principal, remaining_amount, annual_rate, repayment_type, start_date, end_date, next_due_date, status这是整张系统的核心status 表示未结清、已结清、逾期repayment_plans还款计划id, debt_id, period_no, due_date, principal_part, interest_part, total_amount, paid_status由后端根据还款方式自动批量生成repayment_records还款流水id, debt_id, amounts, paid_date, paid_by, note每还一笔钱就记一次流水适度支撑后台计算剩余本金设计时我给自己定了一条规矩所有金额字段一律用 DECIMAL(12,2)Java 侧对应 BigDecimal禁止用 double/float。利息计算对精度极其敏感早期用 double 算应对时产生的误差一度到几分钱账单看着就不对。3.2 债务表设计的三个容易忽略的细节第一利率字段我用 annual_rate 存年利率但计算时按还款周期折算。等额本息按月还就把年利率除以12亲友借款按天计息就除以360。这些逻辑集中在 DebtCalculator 一个类里其他地方不直接写利率公式。第二债务状态不能只有“存在”和“不存在”两个状态。我设计的 status 字段有七种取值ACTIVE、PARTIAL_PAID、PAID_OFF、OVERDUE、EXTENDED、SUSPENDED、CANCELLED。其中 PARTIAL_PAID 和 ACTIVE 的区别是是否有部分还款记录而 OVERDUE 不是直接改这个字段是由定时任务根据 next_due_date 和还款流水动态算出来并落库的。第三亲友借款这类债务没有标准还款计划系统生成一条“期末计划”最后一次性还本金和利息。在还款日之前它可能处于“不需要关注”的静默状态但到了最后一个月权重会突然拉满。在仪表盘上我特意给这类债务加了“临期提醒红点”免得因为平时不显示就彻底忘掉。3.3 账户和流水表之间的事务一致性记账系统最怕的就是账户余额和流水对不上。每个账户的 balance 字段是一个冗余字段不能直接信任它的更新必须和 transactions 表插入/删除在同一个数据库事务里。例如一笔支出发生transaction 表插入一条 expense同时 accounts.balance balance - 支出金额两个操作必须同时成功或同时失败。早期版本我没用事务测试时手动删了一条流水账户余额就永远对不上了。后来我改用这种强制关联方式在 TransactionService 里统一添加 Transactional 注解所有对 accounts.balance 的修改只能出现在这个事务里。真正常用之后你会发现事务这个 Spring 容器自带的机制才是这套系统不乱的定海神针。4. 后端实现要点还款计划、逾期计算与债务聚合这套系统后端的核心逻辑不在 CRUD而在三个地方还款计划生成、逾期自动检测、债务聚合统计。我把这三个部分的设计单独拎出来说因为它们藏着这个项目最关键的算法细节。4.1 还款计划生成算法算得对后面才能省心由于每笔债务的还款方式不同我把“计划生成”做成了策略模式。每种还款方式一个策略类统一通过 DebtCalculator.getRepaymentType() 取一个实例。核心代码如下保留了关键逻辑public class DebtCalculator { public static ListRepaymentPlan generatePlans(Debt debt) { switch (debt.getRepaymentType()) { case EQUAL_PRINCIPAL_AND_INTEREST: return equalPrincipalAndInterest(debt); case EQUAL_PRINCIPAL: return equalPrincipal(debt); case LUMP_SUM: return lumpSum(debt); default: throw new UnsupportedOperationException(不支持的还款方式: debt.getRepaymentType()); } } private static ListRepaymentPlan equalPrincipalAndInterest(Debt debt) { // 月利率 年利率 / 12 BigDecimal monthlyRate debt.getAnnualRate() .divide(BigDecimal.valueOf(12), 10, RoundingMode.HALF_UP); int totalPeriods debt.getTotalPeriods(); // 等额本息每期还款额 本金 * 月利率 * (1月利率)^期数 / ((1月利率)^期数 - 1) BigDecimal factor monthlyRate.add(BigDecimal.ONE).pow(totalPeriods); BigDecimal monthlyPayment debt.getRemainingAmount() .multiply(monthlyRate) .multiply(factor) .divide(factor.subtract(BigDecimal.ONE), 2, RoundingMode.HALF_UP); // 按每期扣减剩余本金生成计划明细 // ... 略每一条计划里保存应付本息、本金部分、利息部分 return plans; } private static ListRepaymentPlan lumpSum(Debt debt) { ListRepaymentPlan plans new ArrayList(); // 到期一次还本付息利息按实际天数计算 LocalDate dueDate debt.getEndDate(); long days ChronoUnit.DAYS.between(debt.getStartDate(), dueDate); BigDecimal interest debt.getRemainingAmount() .multiply(debt.getAnnualRate()) .divide(BigDecimal.valueOf(360), 2, RoundingMode.HALF_UP) .multiply(BigDecimal.valueOf(days)); // 最终计划一期包含本金利息 return plans; } }写这一段的时候我特意把所有除法都保留了10位小数到最后一步再四舍五入到分避免计算过程中精度损失累积。等额本息求幂运算在 Java 里用 BigDecimal.pow(int exponent) 就可以但注意参数只能是整数所以需要先把期数变量转成 int。等额本金就简单一些每期本金 剩余本金/总期数利息 剩余本金×月利率每还完一期把本金剩余重新计算。三种算法逻辑都写完后我拿银行的还款计划表核对了三笔真实贷款数字能完全对上当场放心了。4.2 逾期检测你以为是“过期置红”实际上是状态机最开始我设想得很简单每天跑一遍 SQL把 next_due_date 今天的债务标记为逾期。但真实跑起来立刻发现三个问题第一部分还款会把还款日后的债务本金减少但原计划里“已逾期”和“未还款”的界限就变得模糊第二有的银行有3天宽限期逾期当天还不算逾期第三亲友借款逾期了你不可能真的去计算罚息只是需要系统提醒你“该说一声了”。后来我把逾期处理重构成了基于事件的状态机。核心逻辑分三步// 1. 找出所有状态不为 PAID_OFF/CANCELLED 的债务 // 2. 检查最近一笔还款流水 OptionalRepaymentRecord latestRecord repaymentRecordRepository .findTopByDebtIdOrderByPaidDateDesc(debt.getId()); // 3. 设置宽限期 LocalDate overdueBaseDate latestRecord.map(r - r.getPaidDate()) .orElse(debt.getDueDate()); if (debt.getNextDueDate().plusDays(GRACE_DAYS).isBefore(today)) { debt.setStatus(Status.OVERDUE); } else { debt.setStatus(Status.ACTIVE); }这套逻辑运行一段时间后效果很好特别是处理那种“钱还了一半、本金还没平”的情况系统会根据最新一笔还款时间刷新状态基准日而不是简单看原定 next_due_date。另外我把“宽限期”做成配置项各家银行不一样改配置比改代码舒服多了。4.3 债务聚合报表把多笔债变成一张决策图光看债务列表你很难判断“下个月家庭资金紧不紧张”。我做了三个聚合报表每个都从不同角度回答问题。第一个是“月度现金流日历”把未来 12 个月内所有还款计划按月份聚合得到每月还款总额再叠加同期的预期收入和固定支出得出每个月的资金缺口预估。这个报表我用一个原生 SQL 按月份分组查出来后端再按月拼接成列表返回给前端。第二个是“负债结构分析”按债务类型房贷、车贷、消费贷、亲友借款汇总剩余本金和利息占比前端用饼图渲染。这样能一眼看出来家庭负债到底是被房贷占据大头还是短期消费贷款占比异常偏高。第三个是“还款进度曲线”对每笔已结清的债务记录本金从100%降到0%的曲线更准确地说是还款计划日期与剩余本金的关系。看这个曲线能判断“提前还款划算不划算”因为利息占比会随着期数变化而变化。这三个报表本身逻辑都不难难在数据要从 plans / debts / transactions 三张表去串。我的做法是先写一个 DebtAggregationQueryService把三次查询的结果封装成 DebtSnapshotView 对象后端一次性返回给前端避免前端多次调接口。快是次要的关键是数据结构对前端友好。5. 前端 Vue 部分的关键实现仪表盘与家庭协作后端逻辑再扎实前端体验不行这套系统就真的只能躺在自己电脑里。我在前端花了同样多的心力。下面讲几个我认为最值得借鉴的模块设计。5.1 仪表盘让负债情况一眼看穿首页仪表盘不能只是几张图堆在一起而是必须有信息层级。我的首页按照“总览—近期—明细”三级来布局。第一屏顶部是三张数字卡片总负债、月度应还、逾期笔数。总负债就是所有未结清债务的剩余本金之和月度应还是未来30天内所有到期计划的金额合计逾期笔数直接映射 statusOVERDUE 的债务数量。这三张卡片回答了家庭财务最核心的问题我们还欠多少、这个月要还多少、有没有忘了的。第二屏是“未来12个月还款日历热力图”。我用 Element Plus 的 Calendar 组件做底每个日期格子显示当天是否需要还款、应还多少。如果某天同时有两笔债券到期格子会标红点进去能看到具体明细。这个视图对家庭协作特别有用配偶打开系统第一眼就知道这几天有大额支出不用翻账本。第三屏是债务列表和“健康度评分”。健康度评分是我自己设计的一个指标综合了负债收入比、逾期记录、还款计划覆盖率三个维度满分为100分。低于60分会显示警示颜色我当初这样设计就是为了“每天打开系统的时候先被吓一跳”这样记住还款的概率反而更高。5.2 还款计划与流水录入的交互设计债务管理里最常见操作就两个新增债务、记录还款。新增债务的表单位于一个抽屉Drawer里关键是“还款方式”字段被选择后表单控件会动态变化。选择等额本息时只显示贷款金额、年利率、期数不要让你手工填月供选择到期一次还本付息时只显示起止日期和利率。这种联动依赖 Vue 3 的 watch 和 v-if 渲染控制实现起来不复杂但对使用体验的提升非常直接。还款录入表单则设计成“先选欠款再填金额”的两步走。由于还款操作会触发后端剩余本金重算前端在成功提示后会立即刷新两个视图一个是当前债务明细卡一个是仪表盘的月度应还。前端不自己计算任何金额字段所有结果都信后端返回避免两端逻辑不一致。5.3 权限与家庭协作的前端实现后端用 Spring Security 做了登录和角色鉴权前端则要配合做页面权限。我用的方案并不复杂登录接口成功后后端返回该用户的 roles 列表前端把它们存进 Pinia store。在路由守卫里通过 meta.roles 配置每个页面允许访问的角色没有权限就 redirect 到首页。家庭协作方面我设计了“家庭主页”页面。这个页面展示全家所有人的收支概览、债务操作日志以及一个简易的“任务看板”。家人可以在这上面互相创建“记得交电费”“这周末转账还X借款”这类提醒事项。操作日志是必须的家里两个人都在动钱每笔还款是谁操作的、什么时候操作的一目了然能省掉很多不必要的话。6. 部署、安全与打磨自用系统也不能裸奔做一个给自己或小家庭用的管理系统很容易在安全与运维上偷懒。我早期版本就是直接局域网访问密码明文存库结果一次忘记备份、系统重装数据全丢。吃了这个教训之后我把部署和安全这块完整补上了。6.1 后端部署与数据库备份生产环境我用了最稳妥的组合一台低配云主机或家里 NAS后端用 Java 17 跑 Spring Boot 的 fat JAR前端用 Nginx 托管打包后的 dist 目录数据库用独立的 MySQL 8.0 实例。这套部署的优点是结构简单、状态可查出了问题能顺着 Nginx 日志 → 应用日志 → SQL 日志一层层定位。数据备份我坚持“双备份”原则MySQL 每天凌晨自动执行 mysqldump 到本机磁盘另外写一个同步脚本把备份文件增量同步到另一块移动硬盘或云对象存储。家庭财务数据丢了找不回来那种痛苦不值得体验一次。我在服务器上挂了个 Crontab 任务0 2 * * * mysqldump -u family_finance_user -p你的密码 family_finance_db /backup/family_$(date \%Y\%m\%d).sql注意 cron 表达式里百分号要转义否则任务会直接不执行。这是我踩了两次坑才记住的。6.2 安全配置密码加密与访问控制密码存库必须用 BCrypt 加密Spring Security 自带的 BCryptPasswordEncoder 直接拿来用就行。登录接口要做好失败次数限制同一个 IP 5 次失败就锁定15分钟防止暴力破解。还有一个很多人忽略的小地方管理系统的 API 路径要加上随机盐比如 /api/v1/fam-xxxx/data而不是直接用 /debt/list 这种一眼能猜到的路径。即使系统只在内网跑多一层不可预期性也能挡掉大量随手扫描的流量。另外所有写操作接口我都加了审计字段操作人、操作时间、操作类型保存进一张 audit_log 表。6.3 打磨细节金额显示、时间精度、校验规则细节打磨是家庭系统能不能长期用下去的关键。金额显示统一保留两位小数并按照系统设置显示货币符号涉及利率输入前端用 Number 类型校验范围0~36%防止有人填入100%这种明显离谱的数值日期选择器限制了贷款起始日必须在当前日期之前还款日不能早于起始日。每个表单提交前前端会做一轮轻校验后端再做一轮业务校验双保险。另外在时间处理上我全程统一使用 LocalDate 与 LocalDateTime数据库对应 date 和 datetime 类型没有任何时区转换的困扰。谁在 UTC 和北京时间之间反复横跳过的应该明白这个选择有多幸福。7. 踩坑记录与实用建议我用三个真实事件换来的经验最后这部分必须写因为这套系统从零到真正上线用了大约三周其中至少五天在修下面这三个坑。如果提前有人告诉过我可能两天时间就能省出来。7.1 坑一等额本息计算精度问题导致系统里差了5分钱使用 BigDecimal.pow() 求高次幂后后续除法可能出现无限循环小数必须指定保留位数和舍入模式。如果保留位数不够累计下来会差几分钱如果舍入模式不对最后一期可能是负数或超额。我的处理方式是所有中间计算一律保留10位小数只在每期计划落库时四舍五入到2位。最后一期用总本金 总利息 减去 前N期已计金额总和算出最后一期的补差值。这样不管中间怎么算最后一期一定和“账目总额”吻合。这套处理写出来后我拿银行真实还款计划对账一分钱不差。7.2 坑二定时任务在同一时刻对同一债务跑了两次产生了重复逾期提醒当时我用 Spring 的 Scheduled 配了一个每天执行一次的任务用来检测逾期。但某次部署时不小心启动了两个实例体检任务在两边同时执行导致同一笔债务被更新了两次、提醒邮件发了两封。更隐蔽的是定时任务内部再次调用了债务服务和用户正常点击还款操作并发发生时可能出现剩余本金计算竞争。解决方案是两件事一是所有定时任务方法上加了分布式锁项目小就基于数据库的行锁或一张 lock 表实现二是债务更新方法统一使用乐观锁版本号字段。这样即使多实例运行也能保证同一时刻只有一个请求能更新同一条债务。7.3 坑三前端日历“还款日”与“实际还款日”混淆导致展示混乱我最早在还款日历上显示的是从 repayment_plans 表读取的 due_date应还日这是没问题的。但后来加了“宽限期”功能前端还继续用 due_date 渲染“是否逾期”的状态色导致一笔因银行宽限期而并未逾期的债务在日历上标成了脏红色用户一看就以为出大事了。修复方式是明确两个字段due_date 表示计划还款日overdue_date 表示真正算做逾期的日期等于 due_date 宽限期。前端把所有状态判断统一切换到 overdue_date 上宽限期内显示黄色加强提醒超过宽限期才显示红色。这个改动改起来不难但概念上必须理清楚否则不同页面的显示会出现矛盾。写在最后的个人体会整套系统从设计到落地我最深刻的感触是家庭财务管理不是会计系统它最核心的诉求是“让人心里有数”。Spring Boot、Vue 这些技术只是手段真正重要的是搞明白每一笔债务的结构、每一个还款日的含义、每一次还款对现金流的影响。把这个业务逻辑吃透了代码反而是水到渠成的事。最后分享一个我一直在用的小技巧系统每个月底会自动生成一份“下月还款预报表”PDF我把它放进家庭网盘和手机里各一份。这样哪怕哪天系统忘看了、邮件漏查了手机里那份 PDF 也能临时顶上。做工具就是这样自动化的终点不是代替人而是让人在极端场景下也有兜底。