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 后，在请求头携带：
text
```
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`	账单解析与确认导入
`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/config`	应用配置（注册开关、通知链接等）

统一响应结构

json

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

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

相关文档