Skip to content

API 文档 ​

系统使用 Knife4j(OpenAPI 3) 生成接口文档,后端启动后可直接访问。

访问入口 ​

入口地址说明
Knife4j UIhttp://<host>:<port>/doc.html增强版接口文档界面
OpenAPI JSONhttp://<host>:<port>/v3/api-docs标准 OpenAPI 描述
Swagger UIhttp://<host>:<port>/swagger-ui/index.html原生界面

开发模式下默认端口为 8080,例如 http://localhost:8080/doc.html。

认证 ​

  • 接口统一使用 JWT Bearer 鉴权,登录接口返回 token 后,在请求头携带:

    text
    Authorization: Bearer <token>
  • Knife4j 配置中已声明全局 Bearer 安全方案,可在文档界面直接填入 token 调试。

  • 无需鉴权的接口:/api/user/login、/api/user/register、/api/user/registration-status、/api/database/status。

  • 日志实时推送等 SSE 接口因 EventSource 无法自定义请求头,兼容通过 ?token= 查询参数鉴权。

接口数据加密 ​

后端支持对 /api/** 的请求体与响应体做端到端加密(RSA + AES-GCM),浏览器登录后自动完成握手,对使用者透明。该能力为机会式:未携带加密会话头的请求按明文处理,因此 Knife4j 等工具仍可直接明文调试接口。

  • 握手:前端先 GET /api/crypto/public-key 获取 RSA 公钥(返回 {enabled, keyId, algorithm, publicKey}),本地生成 32 字节 AES 密钥并用 RSA-OAEP(SHA-256) 加密,再 POST /api/crypto/handshake(body {keyId, key})换取 sessionId;此后请求统一携带 X-Crypto-Session: <sessionId> 头。
  • 算法:AES-256-GCM(IV 12 字节、认证标签 128 位),GCM 的 AAD 绑定 sessionId 以防跨会话重放;AES 会话密钥仅存后端内存,RSA 密钥对在首次启动时自动生成并持久化到运行目录 config/crypto-keys.json。
  • 信封格式:加解密对象为 JSON 信封 {"enc":"A256GCM","iv":"<Base64>","data":"<Base64 密文+标签>"}。
  • 会话:有效期 2 小时、上限 2000 个;失效返回业务码 4201,前端自动重新握手并重试一次。
  • 豁免范围:SSE 流式接口、multipart 文件上传、二进制下载/图片(导出、/api/ai/image/**)与握手接口本身不做加解密;/api/crypto/** 无需鉴权。
  • 开关:由编译期常量 CryptoConstants.API_ENCRYPTION_ENABLED 控制;关闭后 public-key 返回 enabled:false,前端自动回退明文。

接口分组 ​

控制器路径前缀说明
UserController/api/user登录、注册、用户信息、注册开关、修改密码
TransactionController/api/transaction收支记录增删改查、批量创建与操作、备注隐藏、导出、交易渠道选项
TransactionGroupController/api/transaction/group账单关系组的查询、创建、更新、删除与名称历史
BillImportController/api/transaction/import账单解析与确认导入
ChannelController/api/channel用户自定义交易渠道的增删改查
CategoryController/api/category分类管理
TagController/api/tag标签管理
RuleController/api/rule自定义规则(列表、分页查询、增删改、启停、批量删除、命中账单预览与一键应用)
StatisticsController/api/statistics统计汇总、分类、趋势、分组
AiController/api/aiAI 建议、查询、智能查数、文字/图片记账、渠道/关系/规则生成、统计搜索、用量
NotificationController/api/notification通知配置、渠道、发送日志
EmailBillController/api/email-bill邮箱配置、发件人规则、待处理账单
LogController/api/log访问日志、登录日志、运行日志与 SSE
DatabaseController/api/database数据库状态、测试与配置(含 SSE 进度)
AppConfigController/api/app应用配置(通知链接、日志保留)
UserSettingController/api/setting用户偏好(账单来源统计默认值、展示样式、隐藏备注显示、分页、导航)

关键接口 ​

方法路径说明
GET/api/transaction/channels获取交易渠道选项(内置 + 当前用户自定义,含 code/name/builtin)
POST/api/transaction/batch批量创建交易记录(逐条可带 imageId/rawData),导入时按「类型+金额+时间」跳过重复
PUT/api/transaction/{id}/remark-hidden隐藏 / 取消隐藏某条记录的备注
GET / POST / PUT / DELETE/api/channel、/api/channel/{id}自定义渠道列表(含使用账单数)、新建、改名、删除
GET/api/transaction/group/by-transaction/{id}查询某笔账单所属的全部关系组(含成员快照)
GET/api/transaction/group/names关系名称历史(可按 type 过滤,去重、倒序)
POST / PUT / DELETE/api/transaction/group、/api/transaction/group/{id}创建 / 更新 / 删除账单关系组(删除仅解除关联,不删除账单)
PUT/api/user/password修改当前登录用户的密码(校验原密码,新旧需不同)
POST/api/ai/record/image上传一至多张账单/支付截图(字段 files),调用视觉模型识别为多条交易记录
POST/api/ai/record/image/stream图片记账(SSE):实时推送识别进度,结束返回完整结果
GET/api/ai/image/{id}查看本人上传的图片记账图片,?thumbnail=true 返回缩略图
POST/api/ai/channel由自然语言描述生成交易渠道名称
POST/api/ai/relation由关联账单生成关系名称与备注
POST/api/ai/sql智能查数:自然语言生成只读 SQL 并执行
GET / DELETE/api/ai/sql/history查询 / 清空智能查数提问历史(limit 上限 200)
GET/api/rule/page分页查询规则(keyword / enabled / type)
DELETE/api/rule/batch批量删除规则(body { ids },返回实际删除数)
DELETE/api/tag/batch批量删除标签(body { ids },先清理交易-标签与规则-标签关联再删除,返回实际删除数)
DELETE/api/category/batch批量删除分类(body { ids },返回实际删除数)
POST/api/rule/apply-preview预览所选规则命中的历史账单及将应用的目标分类/标签(body { ruleIds },返回 RuleApplyPreviewVO,明细上限 500 条,纯本地匹配)
POST/api/rule/apply一键将所选规则的分类与标签应用到其命中的历史账单(分类覆盖、标签追加,返回 RuleApplyResultVO;纯本地匹配,不外发数据)
POST/api/ai/rule/suggest依据所选已打标签记录生成规则建议(含 duplicate 标记)
POST/api/ai/rule/apply批量创建规则(自动去重、按需新建分类/标签)
POST/api/ai/rule/apply-transactions按传入规则对指定交易做本地匹配并应用(命中则覆盖分类、追加标签,必要时新建;纯本地匹配,不外发数据)
POST/api/ai/rule/check-duplicates校验编辑后的规则是否与已有规则或批内其它规则重复(body { rules },返回逐条布尔标记;纯本地,不调用大模型)
POST/api/ai/statistics自然语言解析为统计面板参数
GET / PUT/api/setting/excluded-display-style查询 / 更新「不计入统计」记录展示样式
GET / PUT/api/setting/show-hidden-data查询 / 更新是否显示已隐藏备注的记录
GET / PUT/api/setting/chart-click-navigation查询 / 更新统计面板图表点击是否跳转明细
GET / PUT/api/setting/pagination-prefs查询 / 更新表格分页候选列表与默认每页条数
GET / PUT/api/setting/nav-menu查询 / 更新左侧导航顺序与显隐
GET / PUT/api/setting/bill-source-include-in-stats查询 / 更新按账单来源的「计入统计」默认值
POST/api/database/config/stream应用数据库配置并通过 SSE 推送进度(另有 /api/database/test/stream)

统一响应结构 ​

json
{
  "code": 200,
  "message": "success",
  "data": {}
}
  • code 非 200 表示业务失败,message 为错误信息。
  • 分页接口的 data 为 PageResult(records / total 等)。
  • 数据库未配置时返回业务码 5031,前端据此跳转初始化引导页。

相关文档 ​

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