3.3 KiB
3.3 KiB
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 |
账单解析与确认导入 |
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 |
获取系统支持的交易渠道编码列表 |
| 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，前端据此跳转初始化引导页。