ledgerly-docs/dev/api.md

API 文档

系统使用 Knife4j（OpenAPI 3） 生成接口文档，后端启动后可直接访问。

访问入口

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

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

认证

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

  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/ai	AI 建议、查询、智能查数、文字/图片记账、渠道/关系/规则生成、统计搜索、用量
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 }，返回实际删除数）
POST	/api/ai/rule/suggest	依据所选已打标签记录生成规则建议（含 duplicate 标记）
POST	/api/ai/rule/apply	批量创建规则（自动去重、按需新建分类/标签）
POST	/api/ai/rule/apply-transactions	按传入规则对指定交易做本地匹配并应用（命中则覆盖分类、追加标签，必要时新建；纯本地匹配，不外发数据）
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）

统一响应结构

{
  "code": 200,
  "message": "success",
  "data": {}
}

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

相关文档

• 整体架构
• 项目结构