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= 查询参数鉴权。

接口分组

控制器	路径前缀	说明
UserController	/api/user	登录、注册、用户信息、注册开关
TransactionController	/api/transaction	收支记录增删改查、批量创建与操作、导出、交易渠道选项
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	数据库状态、测试与配置
AppConfigController	/api/app	应用配置（通知链接、日志保留）
UserSettingController	/api/setting	用户偏好（账单来源统计默认值、不计入统计展示样式）

关键接口

方法	路径	说明
GET	/api/transaction/channels	获取交易渠道选项（内置 + 当前用户自定义，含 code/name/builtin）
POST	/api/transaction/batch	批量创建交易记录（逐条可带 imageId/rawData），导入时按「类型+金额+时间」跳过重复
GET / POST / PUT / DELETE	/api/channel、/api/channel/{id}	自定义渠道列表（含使用账单数）、新建、改名、删除
POST	/api/ai/record/image	上传一至多张账单/支付截图（字段 files），调用视觉模型识别为多条交易记录
POST	/api/ai/record/image/stream	图片记账（SSE）：实时推送识别进度，结束返回完整结果
GET	/api/ai/image/{id}	查看本人上传的图片记账图片，?thumbnail=true 返回缩略图
POST	/api/ai/channel	由自然语言描述生成交易渠道名称
GET	/api/rule/page	分页查询规则（keyword / enabled / type）
POST	/api/ai/rule/suggest	依据所选已打标签记录生成规则建议（含 duplicate 标记）
POST	/api/ai/rule/apply	批量创建规则（自动去重、按需新建分类/标签）
POST	/api/ai/statistics	自然语言解析为统计面板参数
GET / PUT	/api/app/bill-source-include-in-stats	查询 / 更新按账单来源的「计入统计」默认值

统一响应结构

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

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

相关文档

• 整体架构
• 项目结构