File Upload
Resource Management
Health Check
Metrics
Cache Management
Online User Management
Server Monitoring
Authentication System
Plugin Market
Scheduled Tasks
AI Chat
User Management
Role Management
Department Management
Menu Management
Dictionary Management
Log Management
Notice Management
Parameter Configuration
Position Management
Tenant Management
Ticket Management

File Upload

Overview

FastapiAdmin uses a unified upload architecture. All file uploads are handled through a single interface, supporting classified storage for different file types.

Upload Types

Type	Path Parameter	Storage Directory	Usage
`file`	`upload_type=file`	`upload/file/YYYY/MM/DD/`	General file upload (default)
`avatar`	`upload_type=avatar`	`upload/avatar/YYYY/MM/DD/`	User avatar upload
`param`	`upload_type=param`	`upload/param/YYYY/MM/DD/`	Parameter config file upload
`resource`	`upload_type=resource`	`upload/resource/[target_path]/YYYY/MM/DD/`	Monitor resource files, supports custom directory

Unified Upload Interface

Endpoint: /api/v1/common/file/upload

Method: POST

Content-Type: multipart/form-data

Permission: module_common:file:upload

Request Parameters:

Parameter	Type	Location	Required	Description
`file`	`UploadFile`	Body	Yes	File to upload
`upload_type`	`string`	Query	No	Upload type, default `file`
`target_path`	`string`	Form	No	Target directory path, only for `resource` type

Response Example:

json

{
  "code": 0,
  "msg": "File uploaded successfully",
  "data": {
    "file_path": "/app/uploads/resource/images/2024/01/15/abc123.png",
    "file_name": "abc123.png",
    "origin_name": "original-file.png",
    "file_url": "http://localhost:8000/app/uploads/resource/images/2024/01/15/abc123.png"
  }
}

Resource Upload Interface

Endpoint: /api/v1/monitor/resource/upload

Method: POST

Content-Type: multipart/form-data

Permission: module_monitor:resource:upload

Request Parameters:

Parameter	Type	Location	Required	Description
`file`	`UploadFile`	Body	Yes	File to upload
`target_path`	`string`	Form	No	Target directory path

Note: This interface is a shortcut to the unified upload interface, internally calls the unified upload with resource type.

Frontend Examples

General File Upload

typescript

import { request } from "@utils";

async function uploadFile(file: File) {
  const formData = new FormData();
  formData.append("file", file);

  const response = await request<ApiResponse<UploadFilePath>>({
    url: "/common/file/upload",
    method: "post",
    data: formData,
    headers: { "Content-Type": "multipart/form-data" },
  });

  return response.data.data;
}

Avatar Upload

typescript

import { UserAPI } from "@api/module_system/user";

async function uploadAvatar(file: File) {
  const formData = new FormData();
  formData.append("file", file);

  const response = await UserAPI.uploadCurrentUserAvatar(formData);
  return response.data.data;
}

Parameter Config Upload

typescript

import { uploadFile } from "@api/module_system/params";

async function uploadParamConfig(file: File) {
  const formData = new FormData();
  formData.append("file", file);

  const response = await uploadFile(formData);
  return response.data.data;
}

Resource File Upload (with Directory)

typescript

import { ResourceAPI } from "@api/module_monitor/resource";

async function uploadResource(file: File, targetPath: string) {
  const formData = new FormData();
  formData.append("file", file);
  formData.append("target_path", targetPath);

  const response = await ResourceAPI.uploadFile(formData);
  return response.data.data;
}

// Example: Upload to images directory
await uploadResource(file, "images");

// Example: Upload to nested/path directory
await uploadResource(file, "nested/path");

Security Features

Filename Sanitization: Automatically sanitizes dangerous characters from filenames
Path Traversal Protection: Detects and blocks path traversal attacks like ../
File Type Validation: Dual validation based on MIME type and extension
File Size Limit: Configurable single file size limit
Content Detection: Validates file authenticity through file header bytes

Directory Structure

upload/
├── file/           # General files
│   └── YYYY/MM/DD/
├── avatar/         # Avatars
│   └── YYYY/MM/DD/
├── param/          # Parameter configs
│   └── YYYY/MM/DD/
└── resource/       # Monitor resources
    ├── images/
    ├── documents/
    └── YYYY/MM/DD/

Resource Management

Overview

The resource management module provides complete management capabilities for the upload/resource directory, including file browsing, upload, download, delete, move, copy, rename, and directory creation.

Function List

Function	Method	Endpoint	Description
Browse Directory	`listResource`	`GET /api/v1/monitor/resource/list`	Browse specified directory
Upload File	`uploadFile`	`POST /api/v1/monitor/resource/upload`	Upload to specified directory
Download File	`downloadFile`	`GET /api/v1/monitor/resource/download`	Download file
Delete Resource	`deleteResource`	`DELETE /api/v1/monitor/resource/delete`	Delete file or directory
Move Resource	`moveResource`	`POST /api/v1/monitor/resource/move`	Move file or directory
Copy Resource	`copyResource`	`POST /api/v1/monitor/resource/copy`	Copy file or directory
Rename Resource	`renameResource`	`POST /api/v1/monitor/resource/rename`	Rename file or directory
Create Directory	`createDirectory`	`POST /api/v1/monitor/resource/create-dir`	Create new directory
Export List	`exportResource`	`POST /api/v1/monitor/resource/export`	Export resource list

Directory Browsing

Endpoint: GET /api/v1/monitor/resource/list

Permission: module_monitor:resource:list

Query Parameters:

Parameter	Type	Required	Description
`path`	`string`	No	Directory path, default root
`include_hidden`	`boolean`	No	Include hidden files, default `false`
`page_no`	`integer`	No	Page number, default 1
`page_size`	`integer`	No	Page size, default 20

Response Example:

json

{
  "code": 0,
  "msg": "Directory listed successfully",
  "data": {
    "path": "/upload/resource",
    "name": "resource",
    "items": [
      {
        "name": "images",
        "is_file": false,
        "is_dir": true,
        "size": null,
        "created_time": "2024-01-15T10:30:00",
        "modified_time": "2024-01-15T10:30:00",
        "is_hidden": false
      },
      {
        "name": "logo.svg",
        "is_file": true,
        "is_dir": false,
        "size": 12345,
        "created_time": "2024-01-15T10:30:00",
        "modified_time": "2024-01-15T10:30:00",
        "is_hidden": false,
        "file_url": "http://localhost:8000/app/uploads/resource/logo.svg"
      }
    ],
    "total_files": 10,
    "total_dirs": 5,
    "total_size": 1024000
  }
}

Delete Resource

Endpoint: DELETE /api/v1/monitor/resource/delete

Permission: module_monitor:resource:delete

Request Body: string[] - File path array

Example:

json

["upload/resource/images/logo.svg", "upload/resource/documents"]

Move Resource

Endpoint: POST /api/v1/monitor/resource/move

Permission: module_monitor:resource:move

Request Body:

json

{
  "source_path": "upload/resource/images/logo.svg",
  "target_path": "upload/resource/backup/logo.svg",
  "overwrite": false
}

Copy Resource

Endpoint: POST /api/v1/monitor/resource/copy

Permission: module_monitor:resource:copy

Request Body:

json

{
  "source_path": "upload/resource/images/logo.svg",
  "target_path": "upload/resource/images/logo_copy.svg",
  "overwrite": false
}

Rename Resource

Endpoint: POST /api/v1/monitor/resource/rename

Permission: module_monitor:resource:rename

Request Body:

json

{
  "old_path": "upload/resource/images/logo.svg",
  "new_name": "logo_new.svg"
}

Create Directory

Endpoint: POST /api/v1/monitor/resource/create-dir

Permission: module_monitor:resource:create-dir

Request Body:

json

{
  "parent_path": "upload/resource/images",
  "dir_name": "screenshots"
}

Health Check

Overview

Health check endpoints provide real-time monitoring of application status, supporting three-level health checks.

Check Types

Type	Endpoint	Usage	Dependencies
Basic Check	`GET /health`	Load balancer probe	None
Readiness Check	`GET /health/ready`	K8s readinessProbe	Database, Redis
Liveness Check	`GET /health/live`	K8s livenessProbe	None

Basic Health Check

Endpoint: GET /api/v1/common/health

Permission: None

Response Example:

json

{
  "code": 0,
  "msg": "Healthy",
  "data": {
    "status": "ok",
    "timestamp": "2024-01-15T10:30:00",
    "version": "1.0.0"
  }
}

Readiness Check

Endpoint: GET /api/v1/common/health/ready

Permission: None

Description: Checks if all dependencies (database, Redis) are ready, used to determine if the application can receive traffic.

Response Example:

json

{
  "code": 0,
  "msg": "Dependencies ready",
  "data": {
    "status": "ready",
    "timestamp": "2024-01-15T10:30:00",
    "version": "1.0.0",
    "uptime_seconds": 3600.5,
    "dependencies": {
      "database": {
        "status": "up",
        "latency_ms": 5.23
      },
      "redis": {
        "status": "up",
        "latency_ms": 1.12
      }
    },
    "disk_usage": {
      "total": 500000000000,
      "used": 250000000000,
      "free": 250000000000,
      "percent": 50.0
    }
  }
}

Failure Response (HTTP 503):

json

{
  "code": 503,
  "msg": "Dependencies not ready",
  "data": {
    "status": "not_ready",
    "timestamp": "2024-01-15T10:30:00",
    "version": "1.0.0",
    "uptime_seconds": 3600.5,
    "dependencies": {
      "database": {
        "status": "down",
        "latency_ms": null
      },
      "redis": {
        "status": "up",
        "latency_ms": 1.12
      }
    },
    "disk_usage": {
      "total": 500000000000,
      "used": 250000000000,
      "free": 250000000000,
      "percent": 50.0
    }
  }
}

Liveness Check

Endpoint: GET /api/v1/common/health/live

Permission: None

Response Example:

json

{
  "code": 0,
  "msg": "Alive",
  "data": {
    "status": "alive",
    "timestamp": "2024-01-15T10:30:00",
    "uptime_seconds": 3600.5
  }
}

Metrics

Overview

FastapiAdmin integrates Prometheus metrics collection, exposing HTTP request metrics through the /metrics endpoint.

Metrics Endpoint

Endpoint: GET /api/v1/common/metrics

Format: Prometheus text format

Available Metrics

Metric Name	Type	Description
`http_requests_total`	Counter	Total HTTP requests
`http_request_duration_seconds`	Histogram	HTTP request latency (seconds)
`http_request_size_bytes`	Histogram	HTTP request size (bytes)
`http_response_size_bytes`	Histogram	HTTP response size (bytes)
`http_requests_in_progress`	Gauge	Number of in-progress HTTP requests

Configuration

Metrics collection is automatically configured in app/scripts/init_app.py, no manual configuration required.

Default Excluded Endpoints:

/metrics - Metrics endpoint itself
/health - Health check
/health/live - Liveness check
/health/ready - Readiness check
/docs - API docs
/redoc - ReDoc
/openapi.json - OpenAPI spec
/static/* - Static files
/favicon.ico - Favicon

Grafana Configuration Example

yaml

# Prometheus datasource config
apiVersion: 1
datasources:
  - name: Prometheus
    type: prometheus
    url: http://prometheus:9090
    access: proxy

# HTTP request rate panel
- title: HTTP Request Rate
  type: graph
  targets:
    - expr: rate(http_requests_total[5m])
      legendFormat: "{{handler}} - {{method}}"

# Request latency panel
- title: HTTP Request Latency
  type: graph
  targets:
    - expr: histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m]))
      legendFormat: "p95 - {{handler}}"

Cache Management

Overview

Cache management module provides Redis cache monitoring and management, including cache information query, cache key management, and cache clearing.

Core Endpoints

Function	Method	Endpoint	Permission
Get Cache Monitor Info	`getCacheInfo`	`GET /api/v1/monitor/cache/info`	`module_monitor:cache:query`
Get Cache Name List	`getCacheNames`	`GET /api/v1/monitor/cache/get/names`	`module_monitor:cache:query`
Get Cache Key List	`getCacheKeys`	`GET /api/v1/monitor/cache/get/keys/{cache_name}`	`module_monitor:cache:query`
Get Cache Value	`getCacheValue`	`GET /api/v1/monitor/cache/get/value/{cache_name}/{cache_key}`	`module_monitor:cache:query`
Clear Cache By Name	`clearCacheByName`	`DELETE /api/v1/monitor/cache/delete/name/{cache_name}`	`module_monitor:cache:delete`
Clear Cache By Key	`clearCacheByKey`	`DELETE /api/v1/monitor/cache/delete/key/{cache_key}`	`module_monitor:cache:delete`
Clear All Cache	`clearAllCache`	`DELETE /api/v1/monitor/cache/delete/all`	`module_monitor:cache:delete`

Response Data Structure

typescript

interface CacheMonitorSchema {
  command_stats: Array<{
    name: string;    // Command name
    value: string;   // Call count
  }>;
  db_size: number;   // Total keys in Redis
  info: object;      // Redis server info
}

interface CacheInfoSchema {
  cache_key: string;      // Cache key
  cache_name: string;     // Cache name
  cache_value: any;       // Cache value
  remark: string | null; // Remark
}

Frontend Examples

typescript

// Get cache monitor info
const cacheInfo = await CacheAPI.getCacheInfo();

// Get cache name list
const cacheNames = await CacheAPI.getCacheNames();

// Get keys for specified cache name
const keys = await CacheAPI.getCacheKeys('captcha');

// Clear all cache
await CacheAPI.clearAllCache();

Online User Management

Overview

Online user management module provides monitoring and management of currently online users, supporting viewing online user list, forced logout, and clearing all online users.

Core Endpoints

Function	Method	Endpoint	Permission
Get Online User List	`getOnlineList`	`GET /api/v1/monitor/online/list`	`module_monitor:online:query`
Force Offline	`forceOffline`	`DELETE /api/v1/monitor/online/delete`	`module_monitor:online:delete`
Clear All Online	`clearAllOnline`	`DELETE /api/v1/monitor/online/clear`	`module_monitor:online:delete`

Frontend Examples

typescript

// Get online user list
const onlineUsers = await OnlineAPI.getOnlineList({ page_no: 1, page_size: 10 });

// Force offline specified user
await OnlineAPI.forceOffline('session-id-xxx');

// Clear all online users (use with caution)
await OnlineAPI.clearAllOnline();

Server Monitoring

Overview

Server monitoring module provides real-time monitoring of server system resources, including CPU, memory, disk, network usage.

Core Endpoints

Function	Method	Endpoint	Permission
Get Server Info	`getServerInfo`	`GET /api/v1/monitor/server/info`	`module_monitor:server:query`

Response Data Structure

typescript

interface ServerMonitorSchema {
  cpu: {
    percent: number;      // CPU usage (%)
    cores: number;       // CPU cores
  };
  memory: {
    total: number;       // Total memory (bytes)
    used: number;        // Used memory (bytes)
    free: number;        // Free memory (bytes)
    percent: number;     // Memory usage (%)
  };
  disk: {
    total: number;        // Total disk (bytes)
    used: number;         // Used (bytes)
    free: number;         // Free (bytes)
    percent: number;      // Usage (%)
  };
  network: {
    bytes_sent: number;   // Bytes sent
    bytes_recv: number;   // Bytes received
  };
  uptime: number;          // Server uptime (seconds)
}

Authentication System

Overview

FastapiAdmin provides a complete user authentication system, including user login, token management, captcha, and tenant switching.

Get Captcha (optional): Call /captcha to get captcha image
User Login: Call /login with username, password, and captcha
Get Tenant List: After successful login, return user's associated tenants
Select Tenant: Call /select-tenant to select working tenant
Get User Info: Call /current/info to get current user details

Core Endpoints

Function	Method	Endpoint	Description
Get Captcha	`getCaptcha`	`GET /api/v1/system/auth/captcha`	Get captcha image
User Login	`login`	`POST /api/v1/system/auth/login`	User authentication
Logout	`logout`	`POST /api/v1/system/auth/logout`	Clear token
Refresh Token	`refresh`	`POST /api/v1/system/auth/refresh`	Refresh access token
Get Tenant List	`getTenants`	`GET /api/v1/system/auth/tenants`	Get user's associated tenants
Select Tenant	`selectTenant`	`POST /api/v1/system/auth/select-tenant`	Switch tenant context
Get User Info	`getCurrentUserInfo`	`GET /api/v1/system/user/current/info`	Get current user details

Frontend Examples

typescript

import { AuthAPI } from "@api/module_system/auth";
import { UserAPI } from "@api/module_system/user";

// 1. Get captcha
async function getCaptcha() {
  const response = await AuthAPI.getCaptcha();
  return response.data.data;
}

// 2. User login
async function login(username: string, password: string, captchaKey: string, captcha: string) {
  const response = await AuthAPI.login({
    username,
    password,
    captcha_key: captchaKey,
    captcha: captcha,
    login_type: "password",
  });
  return response.data.data;
}

// 3. Select tenant
async function selectTenant(tenantId: number) {
  const response = await AuthAPI.selectTenant({ tenant_id: tenantId });
  return response.data.data;
}

// 4. Get user info
async function getUserInfo() {
  const response = await UserAPI.getCurrentUserInfo();
  return response.data.data;
}

Token Management

Access Token: Validity configured by ACCESS_TOKEN_EXPIRE_MINUTES, used for API authentication
Refresh Token: Longer validity, used to refresh access token
Session ID: Uniquely identifies user session, stored in Redis

Plugin Market

Overview

FastapiAdmin provides a plugin market feature, supporting plugin installation, uninstallation, enable/disable operations.

Core Endpoints

Function	Method	Endpoint	Permission	Description
Plugin Marketplace	`marketplace`	`GET /api/v1/system/plugin/marketplace`	Tenant User	Get available plugins
My Plugins	`myPlugins`	`GET /api/v1/system/plugin/my`	Tenant User	Get installed plugins
Install Plugin	`install`	`POST /api/v1/system/plugin/install`	Tenant User	Install plugin
Uninstall Plugin	`uninstall`	`POST /api/v1/system/plugin/uninstall`	Tenant User	Uninstall plugin
Toggle Status	`toggle`	`POST /api/v1/system/plugin/toggle`	Tenant User	Enable/disable plugin

Plugin Status

Status Code	Marketplace Meaning	My Plugins Meaning
`0`	Plugin available	Enabled
`1`	Plugin unavailable	Disabled

Frontend Examples

typescript

import PluginAPI, { type PluginTable } from "@api/module_application/plugin";

// Get marketplace list
async function getMarketplace(category?: string) {
  const response = await PluginAPI.marketplace(
    { page_no: 1, page_size: 10 },
    category
  );
  return response.data.data;
}

// Install plugin
async function installPlugin(pluginId: number) {
  await PluginAPI.install(pluginId);
}

// Toggle plugin status
async function togglePlugin(pluginId: number) {
  await PluginAPI.toggle(pluginId);
}

Scheduled Tasks

Overview

FastapiAdmin provides APScheduler-based scheduled task management, supporting task creation, modification, deletion, pause, resume, and immediate execution.

Core Endpoints

Function	Method	Endpoint	Description
Get Scheduler Status	`getSchedulerStatus`	`GET /api/v1/task/cronjob/job/scheduler/status`	Get scheduler running status
Get Task List	`getSchedulerJobs`	`GET /api/v1/task/cronjob/job/scheduler/jobs`	Get all tasks
Start Scheduler	`startScheduler`	`POST /api/v1/task/cronjob/job/scheduler/start`	Start scheduler
Pause Scheduler	`pauseScheduler`	`POST /api/v1/task/cronjob/job/scheduler/pause`	Pause scheduler
Resume Scheduler	`resumeScheduler`	`POST /api/v1/task/cronjob/job/scheduler/resume`	Resume scheduler
Shutdown Scheduler	`shutdownScheduler`	`POST /api/v1/task/cronjob/job/scheduler/shutdown`	Shutdown scheduler
Pause Task	`pauseJob`	`POST /api/v1/task/cronjob/job/task/pause/{jobId}`	Pause specified task
Resume Task	`resumeJob`	`POST /api/v1/task/cronjob/job/task/resume/{jobId}`	Resume specified task
Run Now	`runJobNow`	`POST /api/v1/task/cronjob/job/task/run/{jobId}`	Execute task immediately
Remove Task	`removeJob`	`DELETE /api/v1/task/cronjob/job/task/remove/{jobId}`	Remove task
Get Logs	`getJobLogList`	`GET /api/v1/task/cronjob/job/log/list`	Get task execution logs
Sync Jobs	`syncJobsToDb`	`POST /api/v1/task/cronjob/job/scheduler/sync`	Sync tasks to database

Scheduler Status

typescript

interface SchedulerStatus {
  status: string;        // running, paused, shutdown
  is_running: boolean;   // Is running
  job_count: number;     // Task count
}

Frontend Examples

typescript

import JobAPI from "@api/module_task/cronjob/job";

// Get scheduler status
async function getStatus() {
  const response = await JobAPI.getSchedulerStatus();
  return response.data.data;
}

// Start scheduler
async function startScheduler() {
  await JobAPI.startScheduler();
}

// Pause task
async function pauseTask(jobId: string) {
  await JobAPI.pauseJob(jobId);
}

// Run task immediately
async function runNow(jobId: string) {
  await JobAPI.runJobNow(jobId);
}

AI Chat

Overview

FastapiAdmin integrates AI chat functionality, supporting session creation, message sending, and history retrieval.

Core Endpoints

Function	Method	Endpoint	Description
Session List	`getSessionList`	`GET /api/v1/ai/chat/list`	Get paginated session list
Create Session	`createSession`	`POST /api/v1/ai/chat/create`	Create new session
Update Session	`updateSession`	`PUT /api/v1/ai/chat/update/{id}`	Update session title
Delete Session	`deleteSession`	`DELETE /api/v1/ai/chat/delete`	Delete session
AI Chat	`chat`	`POST /api/v1/ai/chat/ai-chat`	Send message and get AI reply
Session Detail	`getSessionDetail`	`GET /api/v1/ai/chat/detail/{sessionId}`	Get session details and messages

Data Structure

typescript

interface ChatSession {
  session_id: string;
  id: string;
  title: string | null;
  agent_id: string | null;
  team_id: string | null;
  workflow_id: string | null;
  created_time: string | null;
  updated_time: string | null;
}

interface ChatMessage {
  id: string;
  session_id: string;
  role: string;           // user, assistant
  content: string;
  created_time: string;
}

Frontend Examples

typescript

import ChatAPI from "@api/module_ai/chat";

// Get session list
async function getSessions() {
  const response = await ChatAPI.getSessionList({ page_no: 1, page_size: 10 });
  return response.data.data;
}

// Create session
async function createSession() {
  const response = await ChatAPI.createSession({ title: "New Chat" });
  return response.data.data;
}

// Send message
async function sendMessage(sessionId: string, content: string) {
  const response = await ChatAPI.chat({
    session_id: sessionId,
    message: content,
  });
  return response.data.data;
}

User Management

Overview

User management module provides complete user CRUD operations, including user creation, query, update, deletion, password reset, status management, role assignment, and avatar upload.

Core Endpoints

Function	Method	Endpoint	Permission	Description
User List	`listUser`	`GET /api/v1/system/user/list`	`module_system:user:query`	Get paginated user list
User Detail	`detailUser`	`GET /api/v1/system/user/detail/{id}`	`module_system:user:detail`	Get user details
Create User	`createUser`	`POST /api/v1/system/user/create`	`module_system:user:create`	Create new user
Update User	`updateUser`	`PUT /api/v1/system/user/update/{id}`	`module_system:user:update`	Update user
Delete User	`deleteUser`	`DELETE /api/v1/system/user/delete`	`module_system:user:delete`	Delete users
Reset Password	`resetPassword`	`PUT /api/v1/system/user/password/reset/{id}`	`module_system:user:update`	Reset user password
Toggle Status	`toggleStatus`	`PUT /api/v1/system/user/status/{id}`	`module_system:user:update`	Enable/disable user
Assign Roles	`assignRoles`	`PUT /api/v1/system/user/roles/{id}`	`module_system:user:update`	Assign roles to user
Upload Avatar	`uploadAvatar`	`POST /api/v1/system/user/avatar/upload`	Login User	Upload user avatar
Get Current User	`getCurrentUserInfo`	`GET /api/v1/system/user/current/info`	Login User	Get current user info
Update Current User	`updateCurrentUserInfo`	`PUT /api/v1/system/user/current/update`	Login User	Update current user info
Change Password	`changePassword`	`PUT /api/v1/system/user/current/password`	Login User	Change own password

Frontend Examples

typescript

import UserAPI from "@api/module_system/user";

// Get user list
async function getUsers() {
  const response = await UserAPI.listUser({
    page_no: 1,
    page_size: 10,
    username: "admin",
  });
  return response.data.data;
}

// Create user
async function createUser() {
  const response = await UserAPI.createUser({
    username: "newuser",
    nickname: "New User",
    email: "newuser@example.com",
    phone: "13800138000",
    dept_id: 1,
    position_ids: [1, 2],
    role_ids: [1],
    password: "password123",
  });
  return response.data.data;
}

// Upload avatar
async function uploadAvatar(file: File) {
  const formData = new FormData();
  formData.append("file", file);
  const response = await UserAPI.uploadCurrentUserAvatar(formData);
  return response.data.data;
}

Role Management

Overview

Role management module provides role CRUD operations, supporting role creation, permission configuration, status management.

Core Endpoints

Function	Method	Endpoint	Permission	Description
Role List	`listRole`	`GET /api/v1/system/role/list`	`module_system:role:query`	Get paginated role list
Role Detail	`detailRole`	`GET /api/v1/system/role/detail/{id}`	`module_system:role:detail`	Get role details
Create Role	`createRole`	`POST /api/v1/system/role/create`	`module_system:role:create`	Create new role
Update Role	`updateRole`	`PUT /api/v1/system/role/update/{id}`	`module_system:role:update`	Update role
Delete Role	`deleteRole`	`DELETE /api/v1/system/role/delete`	`module_system:role:delete`	Delete roles
Toggle Status	`toggleStatus`	`PUT /api/v1/system/role/status/{id}`	`module_system:role:update`	Enable/disable role
Get Role Menu	`getRoleMenu`	`GET /api/v1/system/role/{id}/menu`	`module_system:role:query`	Get role's menu permissions
Set Role Menu	`setRoleMenu`	`PUT /api/v1/system/role/{id}/menu`	`module_system:role:update`	Set role's menu permissions
Get Role Data Scope	`getDataScope`	`GET /api/v1/system/role/{id}/data_scope`	`module_system:role:query`	Get role's data scope
Set Role Data Scope	`setDataScope`	`PUT /api/v1/system/role/{id}/data_scope`	`module_system:role:update`	Set role's data scope

Frontend Examples

typescript

import RoleAPI from "@api/module_system/role";

// Get role list
async function getRoles() {
  const response = await RoleAPI.listRole({ page_no: 1, page_size: 10 });
  return response.data.data;
}

// Create role
async function createRole() {
  const response = await RoleAPI.createRole({
    name: "Admin",
    code: "admin",
    sort: 1,
    data_scope: "custom",
    dept_ids: [1, 2, 3],
    remark: "Administrator role",
  });
  return response.data.data;
}

// Set role menu permissions
async function setMenus(roleId: number, menuIds: number[]) {
  await RoleAPI.setRoleMenu(roleId, { menu_ids: menuIds });
}

Department Management

Overview

Department management module provides department tree operations, supporting department creation, query, update, deletion, and status management.

Core Endpoints

Function	Method	Endpoint	Permission	Description
Department Tree	`treeDepartment`	`GET /api/v1/system/dept/tree`	`module_system:dept:query`	Get department tree
Department List	`listDepartment`	`GET /api/v1/system/dept/list`	`module_system:dept:query`	Get department list
Department Detail	`detailDepartment`	`GET /api/v1/system/dept/detail/{id}`	`module_system:dept:detail`	Get department details
Create Department	`createDepartment`	`POST /api/v1/system/dept/create`	`module_system:dept:create`	Create new department
Update Department	`updateDepartment`	`PUT /api/v1/system/dept/update/{id}`	`module_system:dept:update`	Update department
Delete Department	`deleteDepartment`	`DELETE /api/v1/system/dept/delete`	`module_system:dept:delete`	Delete departments
Toggle Status	`toggleStatus`	`PUT /api/v1/system/dept/status/{id}`	`module_system:dept:update`	Enable/disable department

Department Tree Response Example

json

{
  "code": 0,
  "msg": "success",
  "data": [
    {
      "id": 1,
      "name": "Headquarters",
      "parent_id": 0,
      "sort": 1,
      "leader": "John Doe",
      "phone": "13800138000",
      "email": "john@company.com",
      "status": "0",
      "children": [
        {
          "id": 2,
          "name": "Technology Department",
          "parent_id": 1,
          "sort": 1,
          "children": []
        }
      ]
    }
  ]
}

Frontend Examples

typescript

import DeptAPI from "@api/module_system/dept";

// Get department tree
async function getDeptTree() {
  const response = await DeptAPI.treeDepartment({});
  return response.data.data;
}

// Create department
async function createDept() {
  const response = await DeptAPI.createDepartment({
    name: "New Department",
    parent_id: 1,
    sort: 1,
    leader: "Jane Doe",
    phone: "13900139000",
    email: "jane@company.com",
  });
  return response.data.data;
}

Overview

Menu management module provides menu CRUD operations, supporting menu creation, permission configuration, and status management.

Type	Value	Description
1	Directory	Directory
2	Menu	Menu
3	Button	Button
4	External Link	External Link

Core Endpoints

Function	Method	Endpoint	Permission	Description
Menu Tree	`getMenuTree`	`GET /api/v1/system/menu/tree`	`module_system:menu:query`	Get menu tree
Menu List	`listMenu`	`GET /api/v1/system/menu/list`	`module_system:menu:query`	Get menu list
Menu Detail	`detailMenu`	`GET /api/v1/system/menu/detail/{id}`	`module_system:menu:detail`	Get menu details
Create Menu	`createMenu`	`POST /api/v1/system/menu/create`	`module_system:menu:create`	Create new menu
Update Menu	`updateMenu`	`PUT /api/v1/system/menu/update/{id}`	`module_system:menu:update`	Update menu
Delete Menu	`deleteMenu`	`DELETE /api/v1/system/menu/delete`	`module_system:menu:delete`	Delete menus
Toggle Status	`toggleStatus`	`PUT /api/v1/system/menu/status/{id}`	`module_system:menu:update`	Enable/disable menu

Frontend Examples

typescript

import MenuAPI from "@api/module_system/menu";

// Get menu tree
const menuTree = await MenuAPI.getMenuTree({});

// Create menu
await MenuAPI.createMenu({
  name: 'System Management',
  path: '/system',
  component: 'Layout',
  type: 1,
  parent_id: 0,
  order: 1,
  status: '0',
  icon: 'system'
});

Dictionary Management

Overview

Dictionary management module provides system dictionary type and data management, supporting dictionary CRUD and cache synchronization.

Core Endpoints

Dictionary Type

Function	Method	Endpoint	Permission
Get Dictionary Type List	`listDictType`	`GET /api/v1/system/dict/type/list`	`module_system:dict_type:query`
Get Dictionary Type Detail	`detailDictType`	`GET /api/v1/system/dict/type/detail/{id}`	`module_system:dict_type:detail`
Create Dictionary Type	`createDictType`	`POST /api/v1/system/dict/type/create`	`module_system:dict_type:create`
Update Dictionary Type	`updateDictType`	`PUT /api/v1/system/dict/type/update/{id}`	`module_system:dict_type:update`
Delete Dictionary Type	`deleteDictType`	`DELETE /api/v1/system/dict/type/delete`	`module_system:dict_type:delete`

Dictionary Data

Function	Method	Endpoint	Permission
Get Dictionary Data List	`listDictData`	`GET /api/v1/system/dict/data/list`	`module_system:dict_data:query`
Get Dictionary Data Detail	`detailDictData`	`GET /api/v1/system/dict/data/detail/{id}`	`module_system:dict_data:detail`
Create Dictionary Data	`createDictData`	`POST /api/v1/system/dict/data/create`	`module_system:dict_data:create`
Update Dictionary Data	`updateDictData`	`PUT /api/v1/system/dict/data/update/{id}`	`module_system:dict_data:update`
Delete Dictionary Data	`deleteDictData`	`DELETE /api/v1/system/dict/data/delete`	`module_system:dict_data:delete`
Get Dictionary Data By Type	`getDictDataByType`	`GET /api/v1/system/dict/data/info/{dict_type}`	Public

Frontend Examples

typescript

// Get dictionary type list
const dictTypes = await DictAPI.listDictType({ page_no: 1, page_size: 10 });

// Get dictionary data by type (for dropdown selections)
const statusOptions = await DictAPI.getDictDataByType('sys_user_status');

Log Management

Overview

Log management module provides operation log query, detail viewing, and export functionality.

Core Endpoints

Function	Method	Endpoint	Permission
Get Log List	`listLog`	`GET /api/v1/system/log/list`	`module_system:log:query`
Get Log Detail	`detailLog`	`GET /api/v1/system/log/detail/{id}`	`module_system:log:detail`
Delete Log	`deleteLog`	`DELETE /api/v1/system/log/delete`	`module_system:log:delete`
Export Log	`exportLog`	`POST /api/v1/system/log/export`	`module_system:log:export`

Frontend Examples

typescript

// Query logs
const logs = await LogAPI.listLog({
  page_no: 1,
  page_size: 20,
  start_time: '2024-01-01',
  end_time: '2024-01-31'
});

// Export logs
const response = await LogAPI.exportLog({
  start_time: '2024-01-01',
  end_time: '2024-01-31'
});

Notice Management

Overview

Notice management module provides announcement management, supporting announcement creation, query, update, deletion, and status management.

Core Endpoints

Function	Method	Endpoint	Permission
Get Notice List	`listNotice`	`GET /api/v1/system/notice/list`	`module_system:notice:query`
Get Notice Detail	`detailNotice`	`GET /api/v1/system/notice/detail/{id}`	`module_system:notice:detail`
Create Notice	`createNotice`	`POST /api/v1/system/notice/create`	`module_system:notice:create`
Update Notice	`updateNotice`	`PUT /api/v1/system/notice/update/{id}`	`module_system:notice:update`
Delete Notice	`deleteNotice`	`DELETE /api/v1/system/notice/delete`	`module_system:notice:delete`
Get Available Notices	`getAvailableNotice`	`GET /api/v1/system/notice/available`	Login User
Get Notification Panel	`getNotificationPanel`	`GET /api/v1/system/notice/panel`	Login User

Frontend Examples

typescript

// Get available notices (for homepage display)
const notices = await NoticeAPI.getAvailableNotice();

// Get notification panel data (for bell icon)
const panelData = await NoticeAPI.getNotificationPanel();

Parameter Configuration

Overview

Parameter configuration module provides system parameter management, supporting parameter CRUD and cache synchronization.

Core Endpoints

Function	Method	Endpoint	Permission
Get Parameter List	`listParams`	`GET /api/v1/system/param/list`	`module_system:param:query`
Get Parameter Detail	`detailParams`	`GET /api/v1/system/param/detail/{id}`	`module_system:param:detail`
Get Parameter By Key	`getParamsByKey`	`GET /api/v1/system/param/key/{config_key}`	`module_system:param:query`
Get Parameter Value	`getParamsValue`	`GET /api/v1/system/param/value/{config_key}`	`module_system:param:query`
Create Parameter	`createParams`	`POST /api/v1/system/param/create`	`module_system:param:create`
Update Parameter	`updateParams`	`PUT /api/v1/system/param/update/{id}`	`module_system:param:update`
Delete Parameter	`deleteParams`	`DELETE /api/v1/system/param/delete`	`module_system:param:delete`
Get Init Parameters	`getInitParams`	`GET /api/v1/system/param/info`	Public

Frontend Examples

typescript

// Get init parameters (for system startup)
const configParams = await ParamsAPI.getInitParams();

// Get parameter value by key
const maxUploadSize = await ParamsAPI.getParamsValue('sys.max_upload_size');

Position Management

Overview

Position management module provides position management, supporting position CRUD and status management.

Core Endpoints

Function	Method	Endpoint	Permission
Get Position List	`listPosition`	`GET /api/v1/system/position/list`	`module_system:position:query`
Get Position Detail	`detailPosition`	`GET /api/v1/system/position/detail/{id}`	`module_system:position:detail`
Create Position	`createPosition`	`POST /api/v1/system/position/create`	`module_system:position:create`
Update Position	`updatePosition`	`PUT /api/v1/system/position/update/{id}`	`module_system:position:update`
Delete Position	`deletePosition`	`DELETE /api/v1/system/position/delete`	`module_system:position:delete`

Frontend Examples

typescript

// Get position list
const positions = await PositionAPI.listPosition({ page_no: 1, page_size: 10 });

// Create position
await PositionAPI.createPosition({
  name: 'Senior Developer',
  code: 'senior_dev',
  order: 1,
  status: '0'
});

Tenant Management

Overview

Tenant management module provides multi-tenant architecture support, including tenant CRUD, user management, quota management, config management, and menu permissions.

Core Endpoints

Basic Tenant Operations

Function	Method	Endpoint	Permission
Get Tenant List	`listTenant`	`GET /api/v1/system/tenant/list`	`module_system:tenant:query`
Get Tenant Detail	`detailTenant`	`GET /api/v1/system/tenant/detail/{id}`	`module_system:tenant:query`
Create Tenant	`createTenant`	`POST /api/v1/system/tenant/create`	`module_system:tenant:create`
Update Tenant	`updateTenant`	`PUT /api/v1/system/tenant/update/{id}`	`module_system:tenant:update`
Delete Tenant	`deleteTenant`	`DELETE /api/v1/system/tenant/delete`	`module_system:tenant:delete`
Toggle Tenant Status	`toggleTenantStatus`	`PUT /api/v1/system/tenant/status/{id}`	`module_system:tenant:patch`

Tenant User Management

Function	Method	Endpoint	Permission
Get Tenant Users	`getTenantUsers`	`GET /api/v1/system/tenant/{id}/users`	`module_system:tenant:query`
Add Tenant User	`addTenantUser`	`POST /api/v1/system/tenant/{id}/users`	`module_system:tenant:create`
Remove Tenant User	`removeTenantUser`	`DELETE /api/v1/system/tenant/{id}/users/{uid}`	`module_system:tenant:delete`

Tenant Quota Management

Function	Method	Endpoint	Permission
Get Tenant Quota	`getTenantQuota`	`GET /api/v1/system/tenant/{id}/quota`	`module_system:tenant:query`
Update Tenant Quota	`updateTenantQuota`	`PUT /api/v1/system/tenant/{id}/quota`	`module_system:tenant:update`

Tenant Config Management

Function	Method	Endpoint	Permission
Get Tenant Config	`getTenantConfig`	`GET /api/v1/system/tenant/{id}/config`	`module_system:tenant:query`
Update Tenant Config	`updateTenantConfig`	`PUT /api/v1/system/tenant/{id}/config`	`module_system:tenant:update`

Function	Method	Endpoint	Permission
Get Tenant Menus	`getTenantMenus`	`GET /api/v1/system/tenant/{id}/menus`	`module_system:tenant:query`
Set Tenant Menus	`setTenantMenus`	`PUT /api/v1/system/tenant/{id}/menus`	`module_system:tenant:update`

Frontend Examples

typescript

// Create tenant
const tenant = await TenantAPI.createTenant({
  name: 'Example Tenant',
  code: 'example_tenant',
  admin_name: 'Administrator',
  admin_account: 'admin',
  admin_password: 'password'
});

// Add user to tenant
await TenantAPI.addTenantUser(tenant.id, { user_id: 123 });

// Set tenant quota
await TenantAPI.updateTenantQuota(tenant.id, {
  user_limit: 100,
  storage_limit: 1024 * 1024 * 1024 // 1GB
});

Ticket Management

Overview

Ticket management module provides ticket creation, query, update, and deletion, supporting ticket workflow management.

Core Endpoints

Function	Method	Endpoint	Permission
Get Ticket List	`listTicket`	`GET /api/v1/system/ticket/list`	`module_ticket:ticket:query`
Get Ticket Detail	`detailTicket`	`GET /api/v1/system/ticket/detail/{id}`	`module_ticket:ticket:query`
Create Ticket	`createTicket`	`POST /api/v1/system/ticket/create`	`module_ticket:ticket:create`
Update Ticket	`updateTicket`	`PUT /api/v1/system/ticket/update/{id}`	`module_ticket:ticket:update`
Delete Ticket	`deleteTicket`	`DELETE /api/v1/system/ticket/delete`	`module_ticket:ticket:delete`

Frontend Examples

typescript

// Create ticket
await TicketAPI.createTicket({
  title: 'System Bug Report',
  content: 'Login page not loading properly',
  priority: 'high',
  type: 'bug'
});

// Get ticket list
const tickets = await TicketAPI.listTicket({ page_no: 1, page_size: 10 });

Best Practices

1. File Upload

✅ Use unified upload interface for all file uploads
✅ Validate file type and size on client before uploading
✅ Use target_path parameter to organize file structure
✅ Avoid special characters and Chinese in filenames

2. Resource Management

✅ Regularly clean up unused files
✅ Use directory structure to organize different types of resources
✅ Confirm files are not referenced by other resources before deletion

3. Monitoring & Operations

✅ Configure K8s probes to use /health/ready and /health/live
✅ Use Prometheus to collect /metrics data
✅ Set reasonable alert thresholds

Table of Contents ​

File Upload ​

Overview ​

Upload Types ​

Unified Upload Interface ​

Resource Upload Interface ​

Frontend Examples ​

General File Upload ​

Avatar Upload ​

Parameter Config Upload ​

Resource File Upload (with Directory) ​

Security Features ​

Directory Structure ​

Resource Management ​

Overview ​

Function List ​

Directory Browsing ​

Delete Resource ​

Move Resource ​

Copy Resource ​

Rename Resource ​

Create Directory ​

Health Check ​

Overview ​

Check Types ​

Basic Health Check ​

Readiness Check ​

Liveness Check ​

Metrics ​

Overview ​

Metrics Endpoint ​

Available Metrics ​

Configuration ​

Grafana Configuration Example ​

Cache Management ​

Overview ​

Core Endpoints ​

Response Data Structure ​

Frontend Examples ​

Online User Management ​

Overview ​

Core Endpoints ​

Frontend Examples ​

Server Monitoring ​

Overview ​

Core Endpoints ​

Response Data Structure ​

Authentication System ​

Overview ​

Login Flow ​

Core Endpoints ​

Frontend Examples ​

Token Management ​

Plugin Market ​

Overview ​

Core Endpoints ​

Plugin Status ​

Frontend Examples ​

Scheduled Tasks ​

Overview ​

Core Endpoints ​

Scheduler Status ​

Frontend Examples ​

AI Chat ​

Overview ​

Core Endpoints ​

Data Structure ​

Frontend Examples ​

User Management ​

Overview ​

Core Endpoints ​

Frontend Examples ​

Role Management ​

Overview ​

Core Endpoints ​

Frontend Examples ​

Department Management ​

Overview ​

Core Endpoints ​

Department Tree Response Example ​

Table of Contents

File Upload

Overview

Upload Types

Unified Upload Interface

Resource Upload Interface

Frontend Examples

General File Upload

Avatar Upload

Parameter Config Upload

Resource File Upload (with Directory)

Security Features

Directory Structure

Resource Management

Overview

Function List

Directory Browsing

Delete Resource

Move Resource

Copy Resource

Rename Resource

Create Directory

Health Check

Overview

Check Types

Basic Health Check

Readiness Check

Liveness Check

Metrics

Overview

Metrics Endpoint

Available Metrics

Configuration

Grafana Configuration Example

Cache Management

Overview

Core Endpoints

Response Data Structure

Frontend Examples

Online User Management

Overview

Core Endpoints

Frontend Examples

Server Monitoring

Overview

Core Endpoints

Response Data Structure

Authentication System

Overview

Login Flow

Core Endpoints

Frontend Examples

Token Management

Plugin Market

Overview

Core Endpoints

Plugin Status

Frontend Examples

Scheduled Tasks

Overview

Core Endpoints

Scheduler Status

Frontend Examples

AI Chat

Overview

Core Endpoints

Data Structure

Frontend Examples

User Management

Overview

Core Endpoints

Frontend Examples

Role Management

Overview

Core Endpoints

Frontend Examples

Department Management

Overview

Core Endpoints

Department Tree Response Example