进行中网页应用
Furui Bookkeeping
福瑞记账（Campus Ledger）—— 面向大学生的个人记账系统
面向在校大学生的记账系统：手动记账、微信 / 支付宝账单文件导入（自动解析、去重、分类推荐）、收支统计、预算管理，以及 8 项基于本地规则的智能分析。
角色 独立开发（需求 / 设计文档 / 后端 / 前端 / 测试 / 部署）
- Java 17
- Spring Boot 3.2.5（Web / 参数校验 / 文件上传 / 统一异常处理）
- MyBatis-Plus 3.5.5
- jjwt 0.12.5 + BCrypt
- Apache Commons CSV 1.11 + Apache POI 5.2.5
- Maven
- Flutter 3.47（Dart 3.13）· Flutter Web
- fl_chart 图表
- 还有 11 项技术
概览
面向在校大学生的个人记账系统：支持手动记账、微信 / 支付宝官方账单文件导入（自动解析、去重、分类推荐）、收支统计、预算管理，以及 Android 通知栏常驻看板（今日支出 / 本月预算 / 结余）。
技术栈为 Spring Boot 3.2.5 + MyBatis-Plus + MySQL 8 + Flutter（Web / Android），已用 Docker Compose 部署上线。所有智能能力均为本地规则 + 统计实现，不接入大模型、不产生调用费用。
问题
大学生的生活费来源固定（家庭转账、奖助学金、兼职），支出集中在餐饮、交通、购物、娱乐、学习几类，特点是单笔金额小、笔数多，且几乎全部通过微信 / 支付宝支付。
手工记账难坚持；而移动支付账单虽然记录完整，却看不出「钱花在哪了」，也没有预算执行的概念。
第三方记账 App 需要上传账号或导入数据，隐私与合规风险高。
目标
记账省事：把用户自己导出的官方账单文件导入系统，自动解析成记账记录（自动判断收支、识别金额与交易号、推荐分类、过滤重复）。
看清去向：月度收支结余、分类占比、每日趋势、支付来源构成，以及月度总预算与分类预算的执行情况。
合规与自主：不登录用户微信 / 支付宝账号，不使用私有接口、Hook、逆向或模拟登录，只解析用户自己导出的账单文件；智能分析全部本地实现，不依赖外部服务。
方案
导入环节做成可容错的解析器：先探测文件编码（UTF-8 与 GBK / GB18030），再按表头列名映射字段而不是依赖固定列号，脏数据与异常文件返回中文提示而不是 500。
去重做三层：优先使用原始交易号，无交易号时用组合指纹，最后用数据库唯一键 (user_id, dedup_key) 兜底；预览页默认不勾选重复记录。
智能分析全部用本地规则 + 用户历史 + 统计阈值实现，每条结论都带依据与置信度；数据不足时返回明确状态（NO_DATA / INSUFFICIENT_DATA / NOT_APPLICABLE），不编造结论。
架构
Flutter Web 客户端（登录 / 注册 · 首页 · 账单 · 导入 · 统计 · 预算 · 我的）→ HTTP + JSON（金额为字符串）与 multipart/form-data（账单文件）→ Spring Boot 后端（单模块，Controller → Service → Mapper 分层，MyBatis-Plus 数据访问）；鉴权由 AuthInterceptor 解析 JWT 得到 CurrentUser，所有查询按当前用户隔离；导入由 BillImportService + 文件解析器 + 分类匹配器组成；MySQL 8.0 共 4 张表（user · bill · budget · import_batch）。
只解析用户导出的官方账单文件，不登录支付账号
- 背景
- 第三方记账工具常见的做法是让用户提供账号或用私有接口抓取账单，存在合规与封号风险。
- 选择
- 只解析用户自己导出的 CSV / xlsx 账单文件
- 原因
- 不接触账号凭据、不使用私有接口 / Hook / 逆向，合规风险最低。
- 考虑过的方案
- 登录用户微信 / 支付宝账号抓取
- 解析用户自己导出的官方账单文件
- 代价
- 用户需要自己先导出账单文件，多了一步操作。
智能分析用本地规则实现，不接入大模型
- 背景
- 记账数据属于隐私数据，且分析请求频率较高。
- 选择
- 8 项智能能力全部本地规则实现，每条结论附带依据与置信度
- 原因
- 结论可解释、零调用成本、无隐私外发。
- 考虑过的方案
- 调用大模型做消费分析
- 用本地规则 + 统计阈值实现
- 代价
- 分析能力上限受规则覆盖范围限制，无法处理规则之外的复杂语义场景。
数据不足时返回状态，而不是给结论
- 背景
- 记账初期样本很少，强行分析会得出误导性结论。
- 选择
- 每个智能能力都有明确状态（OK / NO_DATA / INSUFFICIENT_DATA / NOT_APPLICABLE）
- 原因
- 样本或覆盖率不足时如实返回，避免用户被假结论误导。
Android 常驻看板用 AlarmManager 而不是前台服务
- 背景
- Android 15 起对 dataSync 类型的前台服务有「每天最多 6 小时」的限制，长期常驻通知会失效。
- 选择
- AlarmManager 每 30 分钟触发一次刷新，并用 BOOT_COMPLETED 接收器在重启后重新安排
- 原因
- 不需要前台服务权限，也不受前台服务时长限制。
- 考虑过的方案
- 前台服务持续刷新
- AlarmManager + BroadcastReceiver 定时刷新
- 代价
- 闹钟在重启后会丢失，需要额外处理开机恢复。
技术栈
后端
- Java 17
- Spring Boot 3.2.5（Web / 参数校验 / 文件上传 / 统一异常处理）
- MyBatis-Plus 3.5.5
- jjwt 0.12.5 + BCrypt
- Apache Commons CSV 1.11 + Apache POI 5.2.5
- Maven
前端
- Flutter 3.47（Dart 3.13）· Flutter Web
- fl_chart 图表
- file_picker
- shared_preferences
- intl
数据库
- MySQL 8.0（金额 DECIMAL(10,2)、唯一约束保证去重与预算不重复）
- 4 张表：user · bill · budget · import_batch
测试
- JUnit（后端 397 个用例）
- flutter test（前端 302 通过 / 88 跳过）
- flutter analyze
- PowerShell 接口验证脚本
DevOps 与基础设施
- Docker Compose（MySQL + Spring Boot 后端 + Nginx 前端）
- 云服务器部署（Ubuntu 24.04）
基础设施
- Docker Compose 三容器编排（MySQL / 后端 / Nginx）
- 云服务器部署并完成外网验收
- Android 通知栏看板走 Flutter ↔ Kotlin MethodChannel
技术亮点
账单导入工程化
编码自动探测、按表头列名映射（不依赖固定列号）、脏数据容错；异常文件（空文件 / 错误表头 / 损坏 / 商户版账单）全部返回中文提示而不是 500。
三重去重
优先原始交易号，无交易号时用组合指纹，数据库唯一键 (user_id, dedup_key) 兜底，重复导入不会产生重复账单。
「本地智能」而非大模型
全部基于规则 + 用户历史 + 统计阈值，结论可解释、零调用成本、无隐私外发；每条结论都带依据与置信度。
数据不足时不给假结论
每个智能能力都有明确状态（OK / NO_DATA / INSUFFICIENT_DATA / NOT_APPLICABLE），样本不足或覆盖率不足时如实返回。
查询次数约束
用测试断言「整个预测 / 分析只执行一次聚合查询」（verify(times(1))）并校验取数窗口，主动防止 N+1 与全表扫描。
统计口径统一
type=3（转账 / 提现 / 还款等不计收支）在所有统计、预算与智能分析中统一排除，避免口径不一致导致的结论矛盾。
合规设计
明确不登录用户支付账号、不用私有接口 / Hook / 逆向，只解析用户自己导出的官方账单文件。
移动端原生能力桥接
通知栏看板用 Flutter ↔ Kotlin MethodChannel 打通，刷新由原生侧独立完成（自己持有 token 与接口地址），不依赖 Flutter 引擎存活；登录后自动恢复、退出登录自动收起、记账后立即刷新。
难点与取舍
账单文件格式差异大
- 问题
- 微信为 UTF-8、支付宝为 GBK / GB18030，列名与顺序都不同，还夹杂脏数据。
- 做法
- 编码自动探测 + 表头定位 + 列名映射 + 容错解析，解析失败给中文错误提示。
- 结果
- 两种来源的账单文件都能导入，异常文件不会以 500 结束。
重复导入去重
- 问题
- 同一笔交易可能被多次导入。
- 做法
- 交易号优先、组合指纹兜底、数据库唯一键最终保障，并在预览页默认不勾选重复记录。
- 结果
- 重复导入不会产生重复账单。
智能分析的边界条件
- 问题
- 周期性支出识别容易误报高频日常消费（例如每天校车）。
- 做法
- 引入周 / 双周 / 月周期 + 金额波动 / 间隔稳定性四信号，信号不足直接丢弃并降级置信度。
- 结果
- 减少误报，结论附置信度。
性能与 N+1
- 问题
- 随着智能能力增多，多次查询会导致接口变慢。
- 做法
- 用 Mapper 调用次数断言约束（部分能力要求 1 次聚合查询完成），并限定取数窗口。
- 结果
- 查询次数受测试约束，避免 N+1 与全表扫描。
测试稳定性
- 问题
- 前端联调用例依赖后端，后端没起时容易「测试变红」。
- 做法
- 联调用例先探测 /api/health，后端不可用自动 skip。
- 结果
- 本地无后端也能跑通其余用例。
真实部署与验收
- 问题
- 需要验证容器化部署后的真实可用性与越权防护。
- 做法
- Docker Compose 三容器 + 服务器安全组放行端口，执行外网验收。
- 结果
- 外网登录、账单 / 统计 / 预算 / 导入历史读取、multipart 上传导入、越权访问返回 404 均通过。
Android 后台刷新限制
- 问题
- 常驻通知需要定时更新，但 Android 15 起对 dataSync 类型前台服务有「每天最多 6 小时」限制。
- 做法
- 改用 AlarmManager + BroadcastReceiver 定时刷新（30 分钟一次），并用 BOOT_COMPLETED 接收器在重启后重新安排。
- 结果
- 不需要前台服务权限即可长期刷新。
权限与生命周期边界
- 问题
- Android 13+ 通知需要运行时授权；登录 / 退出 / 记账三个时机都需要更新通知，否则会显示过期数据。
- 做法
- 用户拒绝授权时开关自动回退并给出系统设置引导；登录 / 退出 / 记账分别触发通知的挂载、收起与即时刷新；Web / Windows 走空实现保证跨平台构建。
- 结果
- 通知状态与账号状态一致，跨平台构建不受影响。
权衡取舍
智能分析实现方式
选了 本地规则 + 统计阈值，而不是 调用大模型分析消费数据 —— 结论可解释、零调用成本、无隐私外发。
代价：分析能力受规则覆盖范围限制，复杂语义场景无法处理。
账单获取方式
选了 解析用户导出的官方账单文件，而不是 登录支付账号或用私有接口抓取 —— 不接触账号凭据、不使用逆向手段，合规风险最低。
代价：用户需要自己先导出一份账单文件。
Android 后台刷新机制
选了 AlarmManager 定时触发，而不是 前台服务常驻刷新 —— 前台服务在较新系统上有每日时长限制，长期常驻不可靠。
代价：重启后闹钟会丢失，需要额外处理开机恢复。
结果
后端测试：mvn clean test 397 个用例，Failures 0 / Errors 0 / Skipped 0（本次直接解析 surefire-reports 下 22 个测试类报告核对一致）。
前端测试：flutter analyze → No issues found（本次实测）；flutter test → 302 passed / 88 skipped / 0 failed（后端未启动时联调用例自动跳过，属正常降级）。
构建产物：后端 jar 45.2 MB、Flutter Web 构建产物、Android release APK。
代码规模：后端 128 个 Java 文件（含 22 个测试类）、前端 65 个 Dart 文件（含 31 个测试文件）+ 8 个 Kotlin 原生文件（通知栏看板）、数据库 4 张表。
线上部署（本次实测）：https://ledger.myiskg.com/ 的 /api/health 返回 200、首页 200（自 2026-09-24 起启用 HTTPS）；Docker Compose 编排 MySQL + 后端 + Nginx 三个容器。部署沿革：原阿里云实例 8.138.161.154:8090 已于 2026-09-20 停用，现全部指向腾讯云实例。
验收记录：外网登录、账单 / 统计 / 预算 / 导入历史读取、multipart 上传导入、越权 404 均通过。
收获
合规要求应该当成设计约束写进需求：只解析用户导出的官方文件，让整个导入方案在实现前就避开了账号与私有接口的风险。
数据不足时给状态比给结论更专业：把 NO_DATA / INSUFFICIENT_DATA 做成明确返回值，比强行给出分析结果更可信。
平台限制会推动更好的技术选择：因为前台服务有时长限制而改用系统闹钟，反而减少了一项敏感权限。
截图
首页：本月概览与快捷入口 
账单列表：按日期分组与多维筛选 
导入预览：重复记录默认不勾选、可改分类 
统计分析：分类占比、来源构成与每日趋势 
预算管理：总预算与分类预算执行情况 
线上部署实例的登录页（本次实测截图）