mirror of
https://github.com/MODSetter/SurfSense.git
synced 2026-04-26 17:26:23 +02:00
37 lines
2.4 KiB
Markdown
37 lines
2.4 KiB
Markdown
|
# SurfSense API Contracts
|
||
|
|
|
||
|
|
## Tổng quan
|
||
|
|
SurfSense Backend cấu trúc hệ thống APIs thành các Routers chuẩn RESTful (thư mục `api/routes`). Toàn bộ API đều trả về type hints giúp FastAPI tự động serialize Pydantic ra Swagger UI và các Frontend Generator có thể tiêu thụ.
|
||
|
|
|
||
|
|
## 1. Nhóm API Quản Trị Hệ Thống / Tài Khoản
|
||
|
|
- **`auth_routes.py`**: Quản lý OAuth/Login, Tokens, Session Refresh.
|
||
|
|
- **`rbac_routes.py`**: Role-based Access Control API, lấy quyền truy cập Workspace/Search Spaces.
|
||
|
|
- **`stripe_routes.py`**: Webhooks và API phục vụ payment/subscriptions nếu có.
|
||
|
|
- **`logs_routes.py`**, **`notifications_routes.py`**: Đẩy Log errors, gửi các Notifications system.
|
||
|
|
|
||
|
|
## 2. Nhóm API Core Search & AI
|
||
|
|
- **`search_spaces_routes.py`**: Tạo, cập nhật, xóa các Knowledge Bases cô lập.
|
||
|
|
- **`new_chat_routes.py`**, **`public_chat_routes.py`**: Mọi call Stream SSE/WebSocket cho tin nhắn từ AI Agent, cũng như query dữ liệu Chat Threads cũ.
|
||
|
|
- **`search_source_connectors_routes.py`**: Trung tâm điều hướng cấu hình các External Syncs. Thường làm việc chung với Backend Workers.
|
||
|
|
|
||
|
|
## 3. Nhóm Connectors Bên Thứ 3
|
||
|
|
Các Connectors này định nghĩa quá trình OAuth Consent hoặc Add Webhooks để cào dữ liệu:
|
||
|
|
- **`google_drive_add_connector_route.py`**
|
||
|
|
- **`slack_add_connector_route.py`**
|
||
|
|
- **`notion_add_connector_route.py`**
|
||
|
|
- **`confluence_add_connector_route.py`**, **`jira_add_connector_route.py`**
|
||
|
|
- **`discord_add_connector_route.py`**
|
||
|
|
*(Và khoảng 10 nền tảng khác).*
|
||
|
|
|
||
|
|
## 4. Nhóm AI Outputs Đa Phương Tiện
|
||
|
|
Mở rộng LLM capabilities beyond text:
|
||
|
|
- **`image_generation_routes.py`**: Sinh hình ảnh từ context.
|
||
|
|
- **`vision_llm_routes.py`**: Parse hình ảnh thành Text (OCR hoặc Context).
|
||
|
|
- **`podcasts_routes.py`**: Sinh Audio / Deep Dive từ documents.
|
||
|
|
- **`video_presentations_routes.py`**: Tạo video tổng hợp.
|
||
|
|
- **`reports_routes.py`**, **`export_routes.py`**: Chuyển đổi Chat Output thành format Markdown, PDF.
|
||
|
|
|
||
|
|
## Quy Chuẩn Tương Tác
|
||
|
|
- Backend sử dụng chuẩn Pydantic Models (nằm ở `surfsense_backend/app/schemas/`) rải đều qua response `response_model=...`.
|
||
|
|
- Client gọi thông qua tanstack-query được define trong `surfsense_web/api/`. Riêng đối với dữ liệu Realtime, Client hoàn toàn bypass API POST/GET truyền thống mà dùng `@rocicorp/zero` để mutate trực tiếp vào Schema.
|