Skip to content

数据模型 ​

系统共 24 张表,覆盖用户、记账、账单关系、渠道、标签、规则、AI、通知、邮箱账单与日志审计。所有表主键为自增 id,表间关系均为逻辑外键(通过 user_id、category_id 等字段在应用层维护,未声明物理外键)。

表清单 ​

业务域表名说明
用户t_user用户表(用户名、BCrypt 密码、昵称)
用户t_user_preference每用户多条的用户偏好(键值)
记账t_category收支分类(收入/支出,含图标与排序)
记账t_transaction收支记录(核心表)
记账t_channel用户自定义交易渠道(内置渠道由枚举维护)
标签t_tag标签
标签t_transaction_tag交易-标签关联(多对多)
账单关系t_transaction_group账单关系组(父子/同级)
账单关系t_transaction_group_item关系组成员(角色与顺序)
规则t_rule自定义归类规则
规则t_rule_tag规则-标签关联(多对多)
AIt_ai_config每用户一条的 AI 配置(含视觉模型)
AIt_ai_usageAI 调用用量记录
AIt_ai_image图片记账上传的截图及其解析摘要
AIt_ai_image_transaction图片与解析生成交易的关联
AIt_ai_sql_history智能查数提问历史(每用户多条)
通知t_notification_config每用户一条的提醒配置
通知t_notification_channel通知渠道
通知t_notification_log通知发送日志
邮箱账单t_email_bill_configIMAP 邮箱配置
邮箱账单t_email_bill_sender_rule发件人规则
邮箱账单t_email_bill_message拉取到的账单消息
日志t_http_log接口访问日志
日志t_login_log登录日志

关系概览 ​

以用户为中心(一对多) ​

主体关系对象关联字段
t_user1 : Nt_categoryuser_id
t_user1 : Nt_transactionuser_id
t_user1 : Nt_taguser_id
t_user1 : Nt_channeluser_id
t_user1 : Nt_transaction_groupuser_id
t_user1 : Nt_ruleuser_id
t_user1 : Nt_ai_imageuser_id
t_user1 : Nt_notification_channeluser_id
t_user1 : Nt_email_bill_configuser_id
t_user1 : Nt_email_bill_sender_ruleuser_id
t_user1 : Nt_email_bill_messageuser_id
t_user1 : Nt_user_preferenceuser_id
t_user1 : Nt_ai_usage / t_http_log / t_login_log / t_notification_loguser_id

一对一(每用户一条) ​

主体关系对象关联字段
t_user1 : 1t_ai_configuser_id(唯一)
t_user1 : 1t_notification_configuser_id(唯一)

记账与标签 ​

主体关系对象关联字段 / 中间表
t_category1 : Nt_transactiontransaction.category_id(可空=未分类)
t_transactionN : Mt_tag中间表 t_transaction_tag(联合唯一)
t_category1 : Nt_rulerule.category_id(命中目标分类)
t_ruleN : Mt_tag中间表 t_rule_tag(联合唯一)
t_ai_image1 : Nt_ai_image_transactionimage_id
t_transaction1 : Nt_ai_image_transactiontransaction_id
t_transaction_group1 : Nt_transaction_group_itemgroup_id(联合唯一 group_id + transaction_id)
t_transaction1 : Nt_transaction_group_itemtransaction_id

交易记录通过 channel 编码关联渠道:内置渠道编码取自 ChannelType 枚举,自定义渠道编码取自 t_channel.code(用户内唯一),因此渠道改名不影响历史记录。

通知与邮箱账单 ​

主体关系对象关联字段
t_notification_channel1 : Nt_notification_logchannel_id(可空)
t_email_bill_config1 : Nt_email_bill_messageconfig_id
t_email_bill_sender_rule1 : Nt_email_bill_messagesender_rule_id(可空)

邮箱配置与发件人规则的默认分类通过 expense_category_id / income_category_id 逻辑引用 t_category;默认标签以 JSON 数组字符串保存(未用关联表)。

核心表字段 ​

t_transaction(收支记录) ​

字段说明
user_id所属用户
category_id分类(可空,未分类)
typeINCOME / EXPENSE
amount金额(DECIMAL(12,2))
channel交易渠道(如 ALIPAY / WECHAT / CASH / BANK)
remark备注
remark_hidden备注是否隐藏
external_no外部账单交易号,导入去重
transaction_time交易发生时间
include_in_stats是否计入统计(默认 1)
raw_data原始字段 JSON(账单导入的原始账单行,或图片记账由模型提取的原始字段;手动记录为空)

关键索引:唯一索引 uk_user_external (user_id, external_no) 实现导入去重;idx_user_time (user_id, transaction_time) 支撑按时间查询与统计。

t_category / t_tag ​

  • 分类:name、type、icon(Emoji)、sort_order。
  • 标签:name、color、sort_order,唯一索引 uk_user_name (user_id, name) 保证用户内标签名唯一。
  • 删除标签时会一并清理 t_transaction_tag 与 t_rule_tag 中的关联记录(单条与批量删除行为一致);删除分类仅移除分类本身,账单与规则上的 category_id 作为逻辑外键保留(账单会显示为「未分类」)。

t_rule ​

name、enabled、sort_order(优先级)、type、keyword、min_amount、max_amount、category_id。

t_transaction_group / t_transaction_group_item(账单关系) ​

  • t_transaction_group:user_id、type(PARENT_CHILD 父子 / SIBLING 同级)、name、remark;索引 user_id。
  • t_transaction_group_item:group_id、transaction_id、role(PARENT / CHILD / MEMBER)、sort_order(同级链路的顺序);唯一索引 (group_id, transaction_id) 防止同一账单在同一组内重复,另有 transaction_id 索引。
  • 约束:一个关系组至少两条成员、上限 50 条;父子关系必须且只能有一条 PARENT;一笔账单不能同时加入两个同类型的关系组。删除账单时会自动清理其成员记录,成员不足两条或父子组缺父时整组删除(仅解除关联,不删除账单)。详见账单关系(使用说明)。

t_channel(自定义交易渠道) ​

字段说明
user_id所属用户
code渠道编码,后端生成(CUSTOM_ + 随机串),稳定不变,交易记录按此关联
name渠道名称,用户可修改
sort_order排序序号,数值越小越靠前

唯一索引 uk_channel_user_code (user_id, code)、uk_channel_user_name (user_id, name) 分别保证用户内编码与名称唯一。仅存放用户自建渠道,内置渠道由 ChannelType 枚举维护。

t_ai_config / t_ai_image ​

  • t_ai_config:每用户一条,含 enabled、api_key、base_url、model 与 vision_model(图片记账使用的视觉模型,默认 deepseek-flash)。
  • t_ai_image:图片记账上传的截图,一次上传可产生多条(最多 5 张),含 user_id、file_path(相对应用运行目录,落盘于 data/ai-images/)、mime_type、file_size、width、height、model(解析所用视觉模型)、summary(识别摘要)、record_count(该图识别出的记录数)。
  • t_ai_image_transaction:图片与交易记录的关联,含 image_id、transaction_id,唯一索引 uk_ai_image_transaction (image_id, transaction_id);每笔记录按模型标注的来源图分别建立关联。
  • t_ai_sql_history:智能查数(自然语言转 SQL)的提问历史,含 user_id、query_text(截断 500 字符)、created_at;索引 (user_id, created_at)。

去重键:图片记账与批量导入使用「收支类型 + 金额 + 交易时间(到秒)」作为业务去重键(TransactionDedupUtils),用于标记疑似重复并在导入时跳过,弥补这类记录没有外部交易号的不足。

t_user_preference ​

按用户存储的键值偏好:pref_key 为偏好键,pref_value 为标量字符串或 JSON。已使用的偏好键包括:billSourceIncludeInStats(各来源计入统计默认值)、excludedDisplayStyle(不计入记录展示样式)、showHiddenData(是否显示已隐藏备注的记录)、chartClickNavigation(统计面板图表点击是否跳转明细)、paginationPrefs(表格分页候选与默认值)、navMenu(左侧导航顺序与显隐)。唯一索引 uk_user_pref (user_id, pref_key) 保证每个用户每个偏好仅一条。未配置时由应用回退系统默认值。

t_email_bill_config ​

IMAP 连接信息(host/port/use_ssl/username/password/folder)、状态(status/last_error/last_connected_at/last_uid)、默认归类(expense_category_id/income_category_id/tag_ids)与拉取范围(fetch_scope/fetch_limit)。

t_email_bill_message ​

config_id、uid、message_id、subject、from_address、received_at、附件信息、命中的 sender_rule_id 与 bill_type、状态(PULLED/CONFIRMED/IGNORED)、error。唯一索引 uk_email_bill_message (config_id, uid, attachment_index) 防止重复拉取。

MySQL 与 SQLite 双脚本 ​

系统同时维护 sql/init.sql(MySQL)与 sql/schema-sqlite.sql(SQLite),表结构与语义保持一致,主要差异:

维度MySQLSQLite
主键自增BIGINT AUTO_INCREMENTINTEGER PRIMARY KEY AUTOINCREMENT
布尔TINYINT(1)INTEGER
金额DECIMAL(12,2)NUMERIC(12,2)
JSONJSONTEXT
时间默认值DEFAULT CURRENT_TIMESTAMPstrftime(...,'localtime')
updated_at 自动更新ON UPDATE CURRENT_TIMESTAMPAFTER UPDATE 触发器
语句分隔符;;;(兼容触发器内部的分号)
列注释支持不支持

统计模块会依据当前数据源类型,切换 MySQL 与 SQLite 的时间分组函数(DATE_FORMAT/QUARTER 与 strftime)。

初始化与迁移 ​

  • 应用启动时由 SchemaInitializer 执行对应建表脚本(幂等)。
  • 建表脚本只做 CREATE TABLE IF NOT EXISTS,无法修改已有库的列;需要就地变更列名或新增列时由 SchemaMigrator 在启动/切换数据源时幂等迁移(如 t_transaction.payment_method → channel 改名、t_ai_config.vision_model 加列;MySQL 用 information_schema、SQLite 用 PRAGMA table_info 检测列是否存在)。
  • 新用户注册时由 DefaultDataInitializer 初始化默认分类、标签与邮箱发件人规则。

基于 Spring Boot 3 + Vue 3 的个人汇账