← 返回账本

架构文档

book.dreamanual.com · 在线记账应用 · 当前实现版本 v0.1.0

整体架构

技术栈

  • 前端：原生 HTML + CSS（Arco Design 风格 token 体系）+ 原生 JS，无框架依赖
  • 后端：Node.js + Express，分层为 server.js（入口）/ api/routes.js（路由）/ api/db.js（数据层）
  • 存储：SQLite（Node 内置 node:sqlite 模块，零原生依赖）
  • 部署：腾讯云 82.156.112.18，nginx 反代 HTTPS + 1Panel 管理

前端（public/）

  • index.html — 单页应用结构（5 个页面 Tab）
  • js/store.js — 数据层：内存缓存 + fetch，读同步 / 写异步
  • js/app.js — 页面渲染与交互逻辑
  • js/icons.js — 内联 SVG 图标库
  • css/tokens.css — Arco 风格设计 token

后端（api/）

  • server.js — Express 入口、静态托管、安全头
  • api/routes.js — REST 路由（账户/分类/流水/报表/导出）
  • api/db.js — SQLite 数据层（迁移、CRUD、聚合报表）
  • data/book.db — SQLite 数据文件

数据模型

表关键字段说明
accountsname, kind, currency, opening_balance, archived账户：现金 / 借记卡 / 信用卡 / 钱包 / 投资 / 虚拟
categoriesname, kind, icon, color, parent_id分类：支出 / 收入 / 转账
transactionsaccount_id, category_id, amount, payee, note, occurred_at, source流水：金额支出为负 / 收入为正；软删除

API 一览

方法路径说明
GET/api/accounts账户列表
POST/api/accounts新增账户（支持币种）
POST/api/accounts/:id/reconcile余额校准（生成差额流水）
GET/api/transactions流水列表（支持筛选）
POST/api/transactions记一笔
GET/api/reports/period周期报表（日/周/月/年 + 环比）
GET/api/reports/accounts账户净变动分布
GET/api/exports/csv按筛选导出 CSV（带 BOM）

关键设计

金额方向约定

支出为负、收入为正，转账单独分类。聚合时按符号分组统计，界面展示绝对值 + 方向标识。

余额校准

输入账户真实余额后，后端计算与账面差额，自动生成一条「余额校准」转账分类流水，保证账实相符且可追溯。

软删除

流水与账户均采用软删除（archived / deleted_at），数据可追溯、可恢复。

报表聚合

日/周/月/年周期由后端 SQL 聚合，返回当期与上期（环比），前端负责可视化（占比条 / 趋势 / 分布）。