chore: 初始化文档站仓库

2026-09-21 13:38:20 +08:00
commit a4ae7ac979
58 changed files with 4622 additions and 0 deletions
@@ -0,0 +1,74 @@
+# 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/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` | 查询 / 更新按账单来源的「计入统计」默认值 |
+
+## 统一响应结构
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {}
+}
+```
+
+- `code` 非 200 表示业务失败，`message` 为错误信息。
+- 分页接口的 `data` 为 `PageResult`（`records` / `total` 等）。
+- 数据库未配置时返回业务码 `5031`，前端据此跳转初始化引导页。
+
+## 相关文档
+
+- [整体架构](/dev/architecture)
+- [项目结构](/dev/project-structure)