轻量级家庭资产管理与记账系统 V1
财迹用于管理一个家庭中不同成员的账户、资产、负债、收入、支出与转账,并回答四个问题:
- 家庭的钱在哪里?(Account)
- 这些钱属于哪个成员?(Member)
- 这些钱是什么类型的资产?(Asset)
- 这些钱为什么发生变化?(Transaction)
业务模型、数据库字段、转账规则与统计规则以设计文档为准:
| 层 | 技术 |
|---|---|
| 后端语言 | C++23 |
| 构建系统 | Meson(cpp_std=c++23,warning_level=3) |
| Web 框架 | Crow(header-only RESTful JSON API) |
| JSON | nlohmann/json |
| 数据库 | SQLite3(WAL、外键、Prepared Statement) |
| 测试 | GoogleTest + meson test |
| 前端 | Vue 3 + TypeScript + Vite + Vue Router + Pinia + Axios + Element Plus |
主项目使用 Meson 构建,未使用 CMake。
为了让项目在没有 sudo、没有系统 -dev 包、甚至无法访问 GitHub 的环境中也能直接构建,依赖已放入 subprojects/:
subprojects/
├── asio/ # standalone asio 1.30.2(Crow 的网络层)
├── crow/ # Crow 1.2.1(header-only)
├── nlohmann_json/ # nlohmann/json 3.11.3 单头文件
├── sqlite3/ # SQLite amalgamation 3.46.1(编译为静态库)
└── googletest/ # GoogleTest 1.14.0
无需 pkg-config,也无需系统安装这些库。
wealth-trace/
├── meson.build # 顶层构建定义
├── meson_options.txt # enable_tests 选项
├── config.json # 运行配置
│
├── backend/
│ ├── meson.build
│ ├── include/ # 头文件(common/config/utils/database/model/repository/service/dto/controller)
│ ├── src/ # 实现
│ │ ├── main.cpp
│ │ ├── common/ # 日志、统一响应、错误
│ │ ├── config/ # 配置加载
│ │ ├── utils/ # 金额、利率、时间、字符串
│ │ ├── database/ # Database / Statement / TransactionGuard / Migration
│ │ ├── model/ # 枚举与实体
│ │ ├── repository/ # SQL 访问
│ │ ├── service/ # 业务逻辑与事务
│ │ ├── dto/ # JSON 解析与序列化
│ │ └── controller/ # HTTP 路由
│ └── test/ # GoogleTest 测试
│
├── frontend/ # Vue 3 + TS + Vite
│ ├── src/{api,components,views,router,stores,types,utils}/
│ └── vite.config.ts # /api 代理到后端
│
├── migrations/ # SQL migration(001–013,含交易 Entry 模型)
├── mcp/ # stdio MCP 服务(TypeScript,发布包含编译产物和生产依赖)
├── data/ # SQLite 数据库文件(运行时生成)
├── docs/ # API、MCP 与设计问题说明
└── scripts/ # 冒烟测试脚本
网页左侧“数据备份”可下载完整 SQLite 数据库,或导入备份并整体恢复。导入会先验证完整性和外键,自动迁移旧版备份,并在数据库目录的 backups/ 保存覆盖前快照。上传文件上限为 100 MiB。
后端:
- C++ 编译器:GCC ≥ 11(需要支持
-std=c++23;已在 GCC 11.4 验证) - Meson ≥ 1.3(
cpp_std=c++23支持),Ninja - 第三方库已内置,无需额外安装
如果系统 Meson 过旧(例如 Ubuntu 22.04 自带 0.61),用 pip 升级:
pip3 install --user -U meson前端:
- Node.js ≥ 20(已在 Node 24 验证)、npm
在项目根目录执行:
# 开发:构建后端,启动后端 :8080 和 Vite :5173(支持热更新)
bash scripts/run.sh dev
# 生产:构建前后端;后端在 :8080 托管 frontend/dist
bash scripts/run.sh prod也可以在模式后传入自定义配置文件:bash scripts/run.sh prod /path/to/config.json。
首次运行时,脚本会在缺少 frontend/node_modules 的情况下自动安装前端依赖。开发模式访问 http://127.0.0.1:5173;生产模式访问 http://127.0.0.1:8080。按 Ctrl-C 停止服务。
启动前脚本会自动检测并停止仍占用后端/Vite 端口的旧进程,避免新服务因端口被占而启动失败。
推荐使用 x86_64 Ubuntu 22.04 开发机。先准备 Node.js ≥ 20、npm、Ninja、rsync 和 Meson ≥ 1.3(Ubuntu 22.04 自带的 Meson 0.61 不够新):
sudo apt-get install ninja-build python3-pip nodejs npm rsync
python3 -m pip install --user 'meson>=1.3'若系统没有 ARM64 交叉编译器,首次执行构建脚本会用 apt download 将 Ubuntu 22.04 工具链装入仓库内的 .toolchains/arm64/,不需要 sudo;后续构建复用它。也可以提前用系统包安装 gcc-aarch64-linux-gnu g++-aarch64-linux-gnu libc6-dev-arm64-cross。首次构建缺少前端依赖时,脚本会运行 npm ci。
目标服务器需要 ARM64 Linux、systemd、Python 3、curl、tar、rsync,以及可免密登录的 root(或可执行 sudo -n 的账号)。前后端和 MCP 都在本机构建,目标机不需要 npm、Meson 或 C++ 编译器;运行 MCP 时仍需 Node.js ≥ 20。交叉编译器使用 Ubuntu 22.04 的 ARM64 运行库;目标机应使用兼容的 Linux/运行库版本。
# 只构建:生成 dist/wealth-trace-linux-arm64.tar.gz
bash scripts/build-arm64.sh
# 一键构建并部署:将示例 IP 换成自己的服务器地址
bash scripts/deploy-arm64.sh --host 192.0.2.10 --user root --port 8081
# 使用已有构建包部署到指定目标
bash scripts/deploy-arm64.sh --skip-build --host 192.0.2.10 --user root --port 8081--host 必填,是 SSH 连接地址;当它是 IPv4 地址时,应用默认监听该地址。用 --user 修改 SSH 用户,用 --port 修改应用端口(不影响 SSH 的 22 端口)。若通过域名连接服务器,另用 --bind 指定服务器上的 IPv4 监听地址,例如 --host my-server.example --bind 192.0.2.10。示例中的 192.0.2.10 是文档专用地址,执行前必须替换。
脚本在目标机的 /opt/wealth-trace/releases/ 保存每次发布的后端程序、前端静态文件、数据库迁移、MCP 编译产物及生产依赖、README.md 和 docs/;/opt/wealth-trace/current 指向当前版本。MCP 文件位于 /opt/wealth-trace/current/mcp/,接入文档位于 /opt/wealth-trace/current/docs/MCP.md,目标机无需从 GitHub 或 npm 获取这些文件。systemd 服务使用专用 wealthtrace 账号,数据库保存在 /var/lib/wealth-trace/caiji.db,服务器配置保存在 /etc/wealth-trace/config.json。每次发布前会将现有 SQLite 数据库备份到 /var/lib/wealth-trace/backups/,启动后检查健康接口;启动失败会自动恢复之前的程序、服务配置,并连同部署前的数据库备份一起还原(新版本重启时可能已执行了迁移,不还原数据库会让旧程序读到不兼容的新结构);/var/lib/wealth-trace/backups/ 同时保留历次备份,需要时也可手动恢复。
部署后可用 ssh <SSH用户>@<服务器地址> systemctl status wealth-trace.service 查看状态,并通过 http://<监听地址>:<应用端口>/ 访问。服务器实际监听地址和端口保存在 /etc/wealth-trace/config.json 的 server.host、server.port 中;修改部署目标时,重新运行脚本并传入相应的 --host、--bind、--port。部署脚本会强制启用登录鉴权(auth.mode=required):首次访问时浏览器会引导创建管理员账号。
部署包已包含 MCP 运行文件和文档。可将下面的提示词发给运行在目标服务器上的 Agent:
请为你所在的 MCP 客户端配置 wealth-trace MCP。先阅读本机
/opt/wealth-trace/current/docs/MCP.md,检查/opt/wealth-trace/current/mcp/dist/index.js和mcp/node_modules/是否存在,并确认 Node.js 版本至少为 20。发布包已包含运行文件和生产依赖,无需下载源码或运行 npm。根据你使用的 MCP 客户端,将它配置为通过node启动/opt/wealth-trace/current/mcp/dist/index.js。读取/etc/wealth-trace/config.json中的server.host和server.port,将 MCP 进程的WEALTH_TRACE_API_URL设置为对应的http://<可访问的主机地址>:<端口>/api;若监听地址为0.0.0.0,且 MCP 与后端在同一台机器上,可用127.0.0.1。后端已启用登录鉴权:还需向用户询问财迹的管理员用户名与密码(即首次浏览器访问时创建的账号),把WEALTH_TRACE_API_USER与WEALTH_TRACE_API_PASSWORD一并写入 MCP 配置的环境变量;MCP 会用它们自动登录并维护会话,请勿把密码写入其他文件或回显到日志。若管理员密码日后修改,需同步更新这两个变量。重启或重载 MCP 客户端后,调用只读工具check_backend验证连接,报告配置位置、使用的 API 地址和验证结果。验证期间不要修改财迹业务数据;如果缺少 Node.js 20,请报告并说明需要安装的运行环境。
# 1. 配置
meson setup build
# 2. 编译
meson compile -C build
# 3. 运行(首次启动会自动创建数据库并执行 migration)
./build/backend/wealth-trace config.json默认监听 http://127.0.0.1:8080。
工作目录应为项目根目录,因为
config.json中的database.migrations_dir默认为相对路径migrations。
main.cpp 启动流程:
- 读取
config.json; - 打开 SQLite 数据库并设置
PRAGMA foreign_keys=ON、journal_mode=WAL、busy_timeout; - 检查并执行尚未执行的 migration;
- 若不存在家庭,创建默认家庭「我的家庭」;
- 执行每日资产维护补跑(
system_state.daily_maintenance_last_run不是当天时); - 注册 REST 路由并启动 Crow,同时启动每日维护调度线程(等到下一个业务时区 0 点执行);
- 若
frontend.enabled=true且已构建前端,则同时托管frontend/dist(SPA 回退到index.html)。
- 数据库文件默认
data/caiji.db,可通过配置修改; - 表结构全部由
migrations/*.sql管理,不在业务代码中散落建表 SQL; - 迁移记录表:
schema_migration(version, name, applied_at); - 013 将旧流水迁移为业务交易与资产 Entry。执行前会检查转账成对关系、定投执行关联和资产购买目标;发现无法可靠转换的记录时会列出记录 ID 并中止,修复数据后再启动。迁移失败不会应用 013。
- 迁移文件命名:
<版本号>_<描述>.sql,按版本升序执行; - 每个迁移在独立事务中执行,失败即整体回滚并停止启动。
开发模式(Vite dev server,自动把 /api 代理到 127.0.0.1:8080):
cd frontend
npm install
npm run dev # http://127.0.0.1:5173生产构建(构建产物由后端静态托管):
cd frontend
npm run build # 生成 frontend/dist
# 然后启动后端,访问 http://127.0.0.1:8080若 npm 被配置了不可用的代理(例如
~/.npmrc中的proxy),npm install会失败。 可临时使用:npm_config_proxy= npm_config_https_proxy= npm install。
meson test -C build测试覆盖金额/利率换算、时间格式、数据库与 migration、外键、事务回滚,以及核心财务流程:
- 收入/支出对余额的影响
- 转账作为一个
TRANSFER交易保存,包含一条OUT和一条INEntry - 投资买入的中性展示、Entry 余额变化、编辑转账时替换 Entries
- 全局及单资产流水 DTO 的方向、无效多 Entry 交易不产生部分写入
- int64 金额边界、删除有流水资产限制
- 旧交易/定投迁移及异常历史数据的迁移预检
- 跨家庭转账被拒绝
- 余额调整可正可负
- 关闭资产后禁止交易
- 负债支出使余额变负
- 统计(总资产/总负债/净资产/本月收支)
- 账户存在资产时禁止变更属主
- 有交易后禁止修改初始金额
- 明细类型必须与资产类型一致
冒烟脚本(需要先构建后端):
bash scripts/run_api_smoke.sh # 使用临时数据库及独立端口,跑 API 收支/转账/统计流程
bash scripts/dev_smoke.sh # 后端 + Vite 开发服务器联调
bash scripts/static_smoke.sh # 验证后端静态托管前端| 字段 | 说明 | 默认 |
|---|---|---|
server.host |
监听地址 | 127.0.0.1 |
server.port |
监听端口 | 8080 |
server.threads |
工作线程数(Crow concurrency,最小 2) | 4 |
auth.mode |
鉴权模式:required(登录后访问)或 disabled(仅限回环地址本地开发) |
required |
auth.allow_unauthenticated_lan |
在非回环地址上关闭鉴权的显式确认(强烈不建议) | false |
database.path |
SQLite 文件路径 | data/caiji.db |
database.migrations_dir |
migration 目录 | migrations |
database.busy_timeout_ms |
忙等待超时 | 5000 |
database.wal |
是否启用 WAL | true |
log.level |
日志级别 trace/debug/info/warn/error/critical | info |
frontend.enabled |
是否托管前端构建产物 | true |
frontend.dir |
前端构建目录 | frontend/dist |
business_timezone |
业务时区(IANA 名称),影响业务日期与每日维护调度 | Asia/Shanghai |
categories.expense |
新家庭的初始支出分类 | 餐饮/交通/... |
categories.income |
新家庭的初始收入分类 | 工资/奖金/... |
分类保存于数据库,可在应用的“分类管理”页面新增、改名、停用和删除未被交易使用的分类。配置文件分类仅作为初始模板。
后端默认启用登录鉴权(auth.mode=required):除 /api/health 与 /api/auth/* 公开端点外,所有 API 都要求 Authorization: Bearer <令牌>。首次访问时浏览器会引导创建管理员账号;密码以 PBKDF2-HMAC-SHA256(200k 迭代)哈希存储,登录会话为 90 天滑动有效期(每次请求自动续期,90 天内使用过一次即无需重新登录,多设备各自独立,修改密码会吊销全部会话)。登录连续失败会触发按用户名的递增退避。
仓库根目录的 config.json 为本地开发设置了 "auth": {"mode": "disabled"},仅允许配合 127.0.0.1 回环绑定;绑定非回环地址且关闭鉴权时,后端会拒绝启动(除非显式设置 auth.allow_unauthenticated_lan=true)。deploy-arm64.sh 部署时会强制写入 auth.mode=required。
注意:HTTP 为明文传输,令牌与密码在同网段内可被窃听;如需跨不可信网络访问,请在前面架设 TLS 反向代理(如 caddy/nginx)。MCP 接入需配置 WEALTH_TRACE_API_USER / WEALTH_TRACE_API_PASSWORD 环境变量(详见 docs/MCP.md)。
配置文件路径可通过命令行参数或环境变量 WEALTH_TRACE_CONFIG 指定:
./build/backend/wealth-trace /path/to/config.json
WEALTH_TRACE_CONFIG=/path/to/config.json ./build/backend/wealth-trace全项目统一,不允许混用:
- 币种:V1 仅支持人民币(CNY),数据库中不保存币种字段,不做汇率换算。
- 金额:最小货币单位整数(人民币 1 元 = 100 分),C++
std::int64_t,SQLiteINTEGER,API 也使用整数分。 - 利率:定点整数,
RATE_SCALE = 1000000。例如 1.85% 存为18500。 - 时间:审计时间戳以 UTC 存储,
YYYY-MM-DD HH:MM:SS;日期YYYY-MM-DD。 - 业务时区:
business_timezone(默认Asia/Shanghai)决定「业务日期」口径, 用于债券基金赎回日推进、可赎回状态判定与统计的「自然月」;查询区间按业务时区边界 换算成 UTC 后匹配transaction_time。前端不自行推算,统一使用后端返回的结果。 - 负债的
current_balance为负数;净资产 =SUM(asset.current_balance)。
前端在展示时把「分」换算成「元」,金额输入换算成「分」后提交。
统一响应结构:
{ "code": 0, "message": "success", "data": {} }失败:
{ "code": 40001, "message": "invalid request", "data": null }主要接口(完整列表见 docs/API.md):
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/health |
健康检查 |
| GET | /api/meta |
枚举与默认分类 |
| GET | /api/database/export |
下载完整 SQLite 数据库备份 |
| POST | /api/database/import |
校验并整体导入数据库备份(最大 100 MiB) |
| GET/POST | /api/households |
家庭列表/创建 |
| GET/PUT | /api/households/{id} |
家庭详情/更新 |
| DELETE | /api/households/{household_id}/categories/{id} |
删除未被交易使用的分类 |
| GET/POST | /api/households/{id}/members |
成员列表/创建 |
| GET/PUT | /api/members/{id} |
成员详情/更新 |
| GET/POST | /api/households/{id}/accounts |
账户列表(含余额)/创建 |
| GET/PUT/DELETE | /api/accounts/{id} |
账户详情(含余额)/更新/删除 |
| GET/POST | /api/households/{id}/assets |
资产列表/创建(可带明细) |
| POST | /api/households/{id}/assets/maintenance-preview |
创建资产时的「添加时维护」预览 |
| GET/PUT | /api/assets/{id} |
资产详情/更新 |
| DELETE | /api/assets/{id} |
删除无交易 Entry 的资产;有历史时需关闭 |
| PUT | /api/assets/{id}/status |
启用/关闭资产 |
| PUT | /api/assets/{id}/detail |
更新资产专有明细 |
| GET | /api/households/{id}/transactions |
流水查询(成员/资产/类型/时间) |
| GET | /api/assets/{id}/transactions |
单资产视角流水 |
| POST | /api/households/{id}/transactions |
创建通用交易 |
| POST | /api/households/{id}/transactions/income |
记账收入 |
| POST | /api/households/{id}/transactions/expense |
记账支出 |
| POST | /api/households/{id}/transactions/adjustment |
余额调整 |
| POST | /api/households/{id}/transfers |
转账(单笔交易、两条 Entry) |
| POST | /api/households/{id}/investments/buy |
投资买入 |
| GET/POST | /api/households/{id}/investment-plans |
定投计划列表 / 创建 |
| PUT/DELETE | /api/investment-plans/{id} |
更新 / 删除定投计划 |
| PUT | /api/investment-plans/{id}/status |
暂停 / 恢复定投计划 |
| POST | /api/investment-plans/{id}/execute |
立即执行一次定投 |
| GET | /api/investment-plans/{id}/executions |
定投执行历史 |
| POST | /api/investment-executions/{id}/retry |
重试失败定投期次 |
| GET | /api/transactions/{id} |
单笔交易详情 |
| PUT | /api/transactions/{id} |
更新交易及其 Entries |
| PUT | /api/transactions/{id}/category |
修改收入或支出流水的分类 |
| DELETE | /api/transactions/{id} |
删除流水(可选回滚余额,转账成对处理) |
| GET | /api/households/{id}/statistics/overview |
家庭总览 |
| GET | /api/households/{id}/statistics/period |
区间收支统计 |
| GET | /api/households/{id}/statistics/monthly |
近 N 个月收支趋势 |
| GET | /api/households/{id}/statistics/trend |
近一周/近一月/近一年的收支趋势 |
| GET | /api/households/{id}/statistics/transaction-days |
每日交易笔数 |
| GET | /api/maintenance/preview |
每日维护变更预览(不落库) |
| POST | /api/maintenance/run |
手动执行每日维护(幂等) |
- MCP 接入:
docs/MCP.md - 需求与总体设计:
家庭资产管理系统-需求分析与总体设计-V1.md - 实现中发现的设计问题与处理:
docs/设计问题说明.md - API 明细:
docs/API.md
债券基金(BOND_FUND):通过 holding_mode 区分持有期(MIN_HOLDING)与滚动持有(ROLLING)。
first_redeem_date / next_redeem_date 由服务端按「购买日期 + 持有周期」计算并允许手工修正;
滚动型的下一赎回日由每日维护推进(today > next_redeem_date 才滚动,当天仍是有效赎回日)。
持有状态不落库,由后端按业务时区(默认 Asia/Shanghai)实时推导并随资产 JSON 返回
(status / days_until_redeem)。详见 docs/设计问题说明.md 第 14–16 节。
维护时机共有四处,规则统一(见 docs/设计问题说明.md 第 19 节):
启动补跑、每天 0 点调度、新增资产时的「添加时维护」(maintain_on_create,前端预览并确认后传入)、
以及资产页的「手动维护」按钮(/api/maintenance/preview + /api/maintenance/run)。
定期存款(TERM_DEPOSIT):start_date / term_value / term_unit 必填,maturity_date
由后端按自然月 / 自然年计算(目标月无对应日取月末),也可手工修正。开启自动续存的存款,
每日维护在到期当天(today >= maturity_date,与滚动债基的 > 不同)推进到下一存期并同步
start_date;到期状态同样不落库,实时推导并返回 status / days_until_maturity。
详见 docs/设计问题说明.md 第 17 节。
定活理财(FLEXIBLE_TERM):选择 180 或 360 天持有期。申购确认满 30 个自然日后,
每月 5 日开放转出;持有期满后每天可转出。资产页显示下一次可转出日期,转账接口校验开放日。
商业养老金(COMMERCIAL_PENSION):填写买入时间及持有周期(天、月、年),默认到期续期。
可设置预约赎回的日期时间提醒范围;它不限制修改到期处理方式。用户可选择到期赎回,
届时停止续期并允许转出。
V1 范围说明:不包含复杂权限、私人账单、复式记账、股票基金份额/净值、行情同步、AI 记账等。