# smart_table

**Repository Path**: yangadong/smart_table

## Basic Information

- **Project Name**: smart_table
- **Description**: 智能多维表格系统，类似于 Airtable 或飞书多维表格。支持多种视图（表格视图、分组视图、看板视图、日历视图、甘特视图、表单视图、仪表盘等），拥有丰富的字段类型。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: https://github.com/ldbinac/smart_table
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 30
- **Created**: 2026-06-25
- **Last Updated**: 2026-06-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Smart Table

[中文](README.md) | English

A smart multi-dimensional table system based on Vue 3 + Flask, similar to Airtable or Lark Base. Supports multiple views (table view, grouped view, kanban view, calendar view, Gantt view, form view, dashboard, etc.), with rich field types; supports markdown for writing rich text documents.

## ✨ Features

### 🎯 Core Features

- **Base Management** - Create, edit, delete, star multi-dimensional tables with member management and sharing
- **Table Management** - Support multiple tables with drag-sort, rename, delete, and duplicate
- **Field Management** - Support **26 field types** with configuration, sorting, visibility control, and default values
- **Record Management** - CRUD operations, batch actions, detail drawer, and change history tracking
- **View Management** - **6 view types** with filtering, sorting, grouping, view switching, and column freezing
- **Document Management** - Document CRUD, rich text editing (Quill), Markdown support, PDF export, version history

### 📝 Supported Field Types (26 Types)

| Category            | Field Type       | Description                                                         | Status |
| ------------------- | ---------------- | ------------------------------------------------------------------- | ------ |
| **Text Types**      | Single Line Text | Short text input with validation rules                              | ✅      |
| **Text Types**      | Long Text        | Long text/paragraph input with multi-line editing                   | ✅      |
| **Text Types**      | Rich Text        | HTML rich text editor with formatting support                       | ✅      |
| **Numeric Types**   | Number           | Integer/decimal with formatting (number/currency/percent)           | ✅      |
| **Date Types**      | Date             | Date picker supporting multiple date formats                        | ✅      |
| **Date Types**      | Date Time        | DateTime picker accurate to seconds                                 | ✅      |
| **Selection Types** | Single Select    | Dropdown single select with custom options and colors               | ✅      |
| **Selection Types** | Multi Select     | Tag-style multi select with custom options                          | ✅      |
| **Selection Types** | Checkbox         | Boolean toggle                                                      | ✅      |
| **People Types**    | Member           | User selection with current user default value                      | ✅      |
| **Contact Types**   | Phone            | Phone number input and formatted display                            | ✅      |
| **Contact Types**   | Email            | Email address input and validation                                  | ✅      |
| **Contact Types**   | URL              | URL link with click-to-navigate                                     | ✅      |
| **Media Types**     | Attachment       | File upload/download with image preview and thumbnails              | ✅      |
| **Computed Types**  | Formula          | 43 built-in functions with field references and nested calculations | ✅      |
| **Relation Types**  | Link             | Table relationships supporting one-to-one/one-to-many/many-to-many  | ✅      |
| **Lookup Types**    | Lookup           | Cross-table queries with aggregation (sum/avg/count/etc.)           | ✅      |
| **System Types**    | Created By       | Auto-record record creator                                          | ✅      |
| **System Types**    | Created Time     | Auto-record creation timestamp                                      | ✅      |
| **System Types**    | Updated By       | Auto-record last modifier                                           | ✅      |
| **System Types**    | Updated Time     | Auto-record last modification time                                  | ✅      |
| **System Types**    | Auto Number      | Auto-increment with prefix/suffix/date format/padding               | ✅      |
| **Others**          | Rating           | Star rating component                                               | ✅      |
| **Others**          | Progress         | Progress bar/percentage display                                     | ✅      |

### 🎨 Supported View Types (6 Types)

| View Type         | Description                                                            | Status |
| ----------------- | ---------------------------------------------------------------------- | ------ |
| **Table View**    | Classic table display with virtual scroll, column freeze, field filter | ✅      |
| **Kanban View**   | Card-based display with drag-sort and grouping                         | ✅      |
| **Calendar View** | Time-based display grouped by date                                     | ✅      |
| **Gantt View**    | Project timeline display with task dependencies                        | ✅      |
| **Form View**     | Data collection form with public sharing and customization             | ✅      |
| **Gallery View**  | Image card grid display for media content                              | ✅      |

### 🚀 Advanced Features

#### Data Processing

- **Data Filtering** - Multi-condition combined filtering with AND/OR logic, 20+ operators
- **Data Sorting** - Multi-field sorting with ascending/descending order, drag to adjust priority
- **Data Grouping** - Group by field with multi-level grouping (up to 3 levels), group statistics
- **Formula Engine** - **43 built-in functions** for math, text, date, logic, and statistics
- **Streaming Data Loading** - First-screen rendering in seconds for 10k+ records, async background loading of remaining pages, non-blocking operations
- **Data Import** - Support Excel, CSV, JSON formats with multi-sheet, can import to create new tables
- **Data Export** - Support Excel, CSV, JSON formats with custom field selection

#### Collaboration & Sharing

- **Base Sharing** - Base-level sharing with link sharing and permission control
- **Form Sharing** - Form view public sharing with submission options configuration
- **Dashboard Sharing** - Dashboard public sharing with real-time data display
- **Member Management** - Base-level member list, add members, role assignment
- **Real-time Collaboration** - WebSocket-based multi-user real-time collaboration (optional)
  - Online presence display
  - View sync (scroll position, view switching)
  - Cell locking (prevent conflict editing)
  - Conflict detection & resolution (optimistic locking)
  - Offline queue (auto-cache on disconnect, auto-replay on reconnect)
  - Graceful degradation (auto-switch to normal mode when unavailable)
- **Request Tracking System** - Request ID full-chain tracing, unified error handling, standardized API response
- **Local Cache System** - Collaboration state, user auth, system config caching; config requests reduced by 90%+

#### Permissions & Security

- **User Authentication** - JWT Token authentication with refresh token, email verification, password reset
- **Role-Based Access Control (RBAC)**:
  - Owner - Full control permissions
  - Admin - Management permissions (except deletion)
  - Editor - Edit permissions
  - Commenter - Comment and view permissions
  - Viewer - Read-only permissions
- **Security Config Management** - Dynamic password rules, registration toggle, session timeout config, public config endpoint
- **Sensitive Info Protection** - 30+ log sanitization fix points auto-masking passwords/tokens/phones/emails
- **Security Protection** - XSS protection, CSRF protection, security headers, API rate limiting, file upload validation
- **Operation Logs** - Complete operation audit logs

#### User Experience

- **Drag Sorting** - Drag to sort tables, fields, views, Kanban cards
- **Star Feature** - Quick access to frequently used tables and dashboards
- **Search Feature** - Quick search for table names and record content
- **Element Plus Icons** - Unified icon system for visual consistency
- **Keyboard Shortcuts** - Common operation keyboard shortcuts

#### Dashboard System

- **Multiple Chart Components** - Number cards, clock, date, KPI cards, marquee, real-time charts, etc.
- **Dashboard Templates** - Save and reuse dashboard configurations as templates
- **Grid Layout** - Flexible grid layout system with customizable rows/columns
- **Real-time Data** - Real-time data updates and dynamic charts
- **Sharing Feature** - Dashboard public sharing with embed support for external websites

#### Email System (Optional)

- **SMTP Configuration** - Custom SMTP server support
- **Email Templates** - Customizable email templates (registration verification, password reset, etc.)
- **Email Queue** - Async email sending queue with retry mechanism
- **Email Logs** - Complete email sending logs and statistics
- **Admin Panel** - Email configuration management and monitoring interface

#### 📄 Document Management (v1.4.0)

- **Document CRUD** - Create, edit, delete, query documents with Base-associated permissions
- **Rich Text Editor** - Quill-based with bold/italic/lists/links/tables formatting
- **Markdown Support** - Markdown syntax with real-time rendering
- **Version History** - Version tracking and rollback, comparison view, creator tracking
- **PDF Export** - Export documents as PDF with DOM direct parsing for accurate styling

## 📸 Feature Preview

| Feature       | Preview                                         | Feature       | Preview                                         |
| ------------- | ----------------------------------------------- | ------------- | ----------------------------------------------- |
| Login         | ![](./doc/img/login.png)                        | Register      | ![](./doc/img/register.png)                     |
| Home          | ![Home](./doc/img/home.jpeg)                    | All Home      | ![Home2](./doc/img/home-all.jpeg)               |
| Table View    | ![Table View](./doc/img/TableView.jpeg)         | Grouped Table | ![Grouped Table](./doc/img/TableViewGroup.jpeg) |
| Table Fields  | ![Table Fields](./doc/img/TableViewFields.jpeg) | Kanban View   | ![Kanban View](./doc/img/KanbanView.jpeg)       |
| Calendar View | ![Calendar View](./doc/img/CalendarView.jpeg)   | Gantt View    | ![Gantt View](./doc/img/GanttView.jpeg)         |
| Form View     | ![Form View](./doc/img/FormView.jpeg)           | Dashboard     | ![Dashboard](./doc/img/Dashboard.jpeg)          |
| Sharing       | ![Sharing](./doc/img/sharing.png)               | Document Management     | ![Document Management](./doc/img/Document.png)               |

## 🛠️ Tech Stack

### Frontend Tech Stack

| Category             | Technology              | Version         | Description                           |
| -------------------- | ----------------------- | --------------- | ------------------------------------- |
| Frontend Framework   | Vue 3                   | ^3.5.30         | Composition API                       |
| Language             | TypeScript              | \~5.9.3         | Type safety                           |
| State Management     | Pinia                   | ^2.3.1          | Lightweight state management          |
| Router               | Vue Router              | ^4.6.4          | SPA routing                           |
| UI Component Library | Element Plus            | ^2.13.6         | Enterprise UI components              |
| Table Component      | vxe-table               | ^4.18.7         | High-performance virtual scroll table |
| Charts               | echarts + vue-echarts   | ^5.6.0 / ^6.7.3 | Data visualization                    |
| Date Processing      | dayjs                   | ^1.11.20        | Lightweight date library              |
| Drag Sorting         | sortablejs              | ^1.15.7         | Drag functionality                    |
| HTTP Client          | axios                   | ^1.14.0         | HTTP requests                         |
| Local Database       | Dexie                   | ^3.2.7          | IndexedDB wrapper                     |
| WebSocket            | socket.io-client        | ^4.8.3          | Real-time communication               |
| Utilities            | lodash-es, @vueuse/core | -               | Utility function sets                 |
| Rich Text            | tinyeditor              | ^4.0.0          | Rich text editor                      |
| Spreadsheet          | xlsx                    | ^0.18.5         | Excel parsing/generation              |
| Build Tool           | Vite                    | ^8.0.1          | Ultra-fast build tool                 |
| Testing              | Vitest                  | ^3.2.4          | Unit testing                          |

### Backend Tech Stack (Optional)

| Category            | Technology                       | Version               | Description                   |
| ------------------- | -------------------------------- | --------------------- | ----------------------------- |
| Framework           | Flask                            | 3.0.0                 | Python Web framework          |
| Database            | SQLite (Default) / PostgreSQL    | 3.x / 16+             | Relational database           |
| ORM                 | SQLAlchemy                       | 2.0.23                | Python ORM                    |
| Database Migration  | Alembic (Flask-Migrate)          | 4.0.5                 | Database version management   |
| Authentication      | JWT (Flask-JWT-Extended)         | 4.6.0                 | Token authentication          |
| Password Encryption | Flask-Bcrypt, bcrypt             | 1.0.1 / 4.1.2         | Password hashing              |
| Form Validation     | Flask-WTF                        | 1.2.1                 | CSRF protection               |
| CORS                | Flask-CORS                       | 4.0.0                 | Cross-origin support          |
| Caching             | Flask-Caching (+ Redis Optional) | 2.1.0                 | Caching acceleration          |
| WebSocket           | Flask-SocketIO                   | 5.3.6                 | Real-time communication       |
| Async Support       | eventlet                         | 0.36.1                | Async processing              |
| Data Serialization  | marshmallow                      | 3.20.1                | Data validation/serialization |
| Import/Export       | pandas, openpyxl, xlrd           | 2.1.4 / 3.1.2 / 2.0.1 | Data processing               |
| Image Processing    | Pillow                           | 10.4.0                | Image thumbnails              |
| Object Storage      | MinIO (Optional)                 | -                     | File object storage           |
| Encryption          | cryptography                     | 42.0.5                | Encryption algorithms         |
| API Documentation   | Flasgger                         | 0.9.7b2               | Swagger UI                    |
| WSGI Server         | Gunicorn                         | 21.2.0                | Production server             |
| Deployment          | Docker, Nginx                    | -                     | Containerized deployment      |

### Data Storage Options

| Mode                   | Technology         | Description                                                                                        |
| ---------------------- | ------------------ | -------------------------------------------------------------------------------------------------- |
| **Pure Frontend Mode** | Dexie (IndexedDB)  | Data stored locally in browser, no server required, suitable for personal use or offline scenarios |
| **Backend Mode**       | SQLite + Flask     | Default uses SQLite, lightweight without additional database installation                          |
| **Production Mode**    | PostgreSQL + Flask | Supports PostgreSQL, suitable for multi-user concurrent access and production environments         |

## 🚀 Quick Start

### One-click Start (Recommended)

Download the latest release package, extract it and start with one click:

```bash
# Windows PowerShell
.\start.bat

# Linux/macOS
./start.sh
```

<br />

> This one-click startup package requires no external dependencies, just double-click to run.
>
> **No need to install any dependencies, no need to manually create an account.**
>
> After startup, the browser will open automatically, then log in with the account email and password printed in the console to try it out.

### Docker Start

> For ARM architectures, please use the corresponding version image：`ygbinac/smarttable:1.4.1-arm64`

Start with the official Docker image:

```bash
docker run -d \
  --name smarttable \
  -p 80:80 \
  -v smarttable_data:/app/data \
  -v smarttable_uploads:/app/uploads \
  -v smarttable_redis:/data/redis \
  ygbinac/smarttable:latest
```

* Or use docker compose, just create the following docker-compose.yml:

```bash
services:
  smarttable:
    image: ygbinac/smarttable:latest
    container_name: smarttable
    ports:
      - "80:80"
    volumes:
      - smarttable_data:/app/data
      - smarttable_uploads:/app/uploads
      - smarttable_redis:/data/redis
    restart: unless-stopped

volumes:
  smarttable_data:
  smarttable_uploads:
  smarttable_redis:
```


## Development Environment

### Requirements

- Node.js >= 18
- npm >= 9
- Python >= 3.9 (Only for backend mode)

### Frontend Development

#### Install Dependencies

```bash
cd smart-table
npm install
```

#### Development Mode

```bash
npm run dev
```

Visit <http://localhost:5173>

#### Build for Production

```bash
npm run build
```

#### Preview Production Build

```bash
npm run preview
```

#### Run Tests

```bash
# Run all tests
npm run test

# Watch mode (for development)
npm run test:watch

# Generate test coverage report
npm run test:coverage
```

### Backend Service (Optional)

#### Using Docker Compose (Recommended)

```bash
cd smarttable-backend

# Copy environment variables configuration
cp .env.example .env
# Edit .env file to configure database connection (default uses SQLite)

# Start all services (SQLite mode)
docker-compose up -d

# Or use PostgreSQL + Redis (for production environment)
# v1.4.0 optimization: Docker deployment embeds Redis, no separate Redis container needed
docker-compose -f docker-compose.dev.yml up -d

# Run database migrations
docker-compose exec backend flask db upgrade

# View logs
docker-compose logs -f backend

# Access API documentation
# http://localhost:5000/api/docs  (Swagger UI)
# http://localhost:5000/api/apidoc  (ReDoc)
```

#### Local Development

```bash
cd smarttable-backend

# Create virtual environment
python -m venv venv

# Activate virtual environment
# Windows:
venv\Scripts\activate
# Linux/macOS:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Copy environment variables configuration
cp .env.example .env
# Default uses SQLite, no need to modify DATABASE_URL

# Initialize database
flask db upgrade

# Start development server (real-time collaboration disabled by default)
flask run --reload

# Or use run.py to start (supports more options)
python run.py

# Enable real-time collaboration
python run.py --enable-realtime
# Or use short flag
python run.py -r
```

#### Backend Features

✅ **Default Database**: SQLite (lightweight, no additional installation required)\
✅ **Optional Database**: PostgreSQL (configurable via `DATABASE_URL` environment variable)\
✅ **Authentication**: JWT Token authentication with refresh token, email verification\
✅ **Permission Management**: Role-based access control (RBAC)\
✅ **Database Migration**: Alembic migration tool\
✅ **API Documentation**: Complete Swagger/OpenAPI documentation (Flasgger)\
✅ **Real-time Collaboration**: Optional WebSocket real-time collaboration (enable via `--enable-realtime`)\
✅ **Email System**: Optional SMTP email sending\
✅ **Object Storage**: Optional MinIO file storage\
✅ **Security Protection**: XSS protection, rate limiting, security headers

## 🗄️ Data Models

### Core Entity Relationships

```
User (User)
  ├── owns many Base (Multi-dimensional Tables)
  ├── is member of many Base (via BaseMember)
  └── has many OperationLog (Operation Logs)

Base (Multi-dimensional Table)
  ├── has many Table (Data Tables)
  ├── has many Dashboard (Dashboards)
  ├── has many BaseShare (Share Links)
  ├── has many BaseMember (Members)
  └── has many CollaborationSession (Collaboration Sessions)

Table (Data Table)
  ├── has many Field (Fields)
  ├── has many Record (Records)
  ├── has many View (Views)
  ├── has many LinkRelation (Link Relations)
  └── belongs to Base

Field (Field)
  ├── has options (field options)
  └── belongs to Table

Record (Record)
  ├── has many RecordHistory (Change History)
  ├── has values for each Field
  └── belongs to Table

View (View)
  ├── has filter/sort/group configs
  └── belongs to Table
```

### Main Model Descriptions

#### User

- User authentication info (username, email, password hash)
- Email verification status
- Role permissions (regular user/admin)
- Avatar and profile info

#### Base (Multi-dimensional Table)

- Base unit for multi-dimensional tables
- Support starring, custom icon and color
- Member management and permission control
- Sharing settings (public/private/password protected)

#### Table (Data Table)

- Contains field definitions and record data
- Support drag-sort, starring
- Relationship configuration

#### Field (Field)

- Define column types and properties
- Support 26 field types
- Rich field options (validation rules, default values, formatting, etc.)

#### Record (Record)

- Data row storing values for each field
- Support CRUD, batch operations
- Complete change history tracking

#### View (View)

- Data display method (6 view types)
- Independent filter, sort, group configurations
- View-level field control (hidden, freeze, width)

#### Document (v1.4.0)

- Document storage and management, linked to Base
- Supports rich text and Markdown content
- Permissions inherited from parent Base

#### DocumentVersion (v1.4.0)

- Document version history tracking
- Snapshot and creator per save
- Supports version rollback and comparison

#### CollaborationSession

- Real-time collaboration session tracking
- Records user join/leave and active status
- Only used when real-time collaboration is enabled

## 🔢 Formula Engine

### Formula Usage Examples

```javascript
// Math calculation
{Unit Price} * {Quantity}

// Discount calculation
{Original Price} * (1 - {Discount})

// Conditional judgment (nested IF)
IF({Score} >= 90, "Excellent", IF({Score} >= 60, "Pass", "Fail"))

// Text concatenation
CONCAT({First Name}, {Last Name})

// Date calculation
DATEDIF({Start Date}, {End Date}, "D")

// Statistical calculation
SUMIF({Department}, "Sales", {Sales Amount})

// Lookup reference
LOOKUP({Related Table.Related Records}, {Target Field})
```

### Supported Functions (43 Total)

#### 📊 Math Functions (11)

| Function  | Description    | Example                   |
| --------- | -------------- | ------------------------- |
| `SUM`     | Sum            | `SUM({Field1}, {Field2})` |
| `AVG`     | Average        | `AVG({Score})`            |
| `MAX`     | Maximum        | `MAX({Age})`              |
| `MIN`     | Minimum        | `MIN({Price})`            |
| `ROUND`   | Round          | `ROUND({Value}, 2)`       |
| `CEILING` | Round up       | `CEILING({Value})`        |
| `FLOOR`   | Round down     | `FLOOR({Value})`          |
| `ABS`     | Absolute value | `ABS({Difference})`       |
| `MOD`     | Modulo         | `MOD({Value}, 2)`         |
| `POWER`   | Power          | `POWER({Base}, 2)`        |
| `SQRT`    | Square root    | `SQRT({Value})`           |

#### 📝 Text Functions (10)

| Function     | Description      | Example                            |
| ------------ | ---------------- | ---------------------------------- |
| `CONCAT`     | Concatenate text | `CONCAT({First}, {Last})`          |
| `LEFT`       | Left extract     | `LEFT({Text}, 3)`                  |
| `RIGHT`      | Right extract    | `RIGHT({Text}, 3)`                 |
| `LEN`        | Text length      | `LEN({Description})`               |
| `UPPER`      | To uppercase     | `UPPER({Text})`                    |
| `LOWER`      | To lowercase     | `LOWER({Text})`                    |
| `TRIM`       | Trim spaces      | `TRIM({Text})`                     |
| `SUBSTITUTE` | Replace text     | `SUBSTITUTE({Text}, "Old", "New")` |
| `REPLACE`    | Replace position | `REPLACE({Text}, 1, 3, "New")`     |
| `FIND`       | Find position    | `FIND("Substring", {Text})`        |

#### 📅 Date Functions (10)

| Function  | Description       | Example                        |
| --------- | ----------------- | ------------------------------ |
| `TODAY`   | Today's date      | `TODAY()`                      |
| `NOW`     | Current time      | `NOW()`                        |
| `YEAR`    | Extract year      | `YEAR({Date})`                 |
| `MONTH`   | Extract month     | `MONTH({Date})`                |
| `DAY`     | Extract day       | `DAY({Date})`                  |
| `HOUR`    | Extract hour      | `HOUR({Time})`                 |
| `MINUTE`  | Extract minute    | `MINUTE({Time})`               |
| `SECOND`  | Extract second    | `SECOND({Time})`               |
| `DATEDIF` | Date difference   | `DATEDIF({Start}, {End}, "D")` |
| `DATEADD` | Date add/subtract | `DATEADD({Date}, 7, "D")`      |

#### 🧠 Logic Functions (7)

| Function  | Description       | Example                            |
| --------- | ----------------- | ---------------------------------- |
| `IF`      | Conditional       | `IF({Condition}, "True", "False")` |
| `AND`     | Logical AND       | `AND({Cond1}, {Cond2})`            |
| `OR`      | Logical OR        | `OR({Cond1}, {Cond2})`             |
| `NOT`     | Logical NOT       | `NOT({Condition})`                 |
| `IFERROR` | Error handling    | `IFERROR({Formula}, "Default")`    |
| `IFS`     | Multi-condition   | `IFS({C1}, {V1}, {C2}, {V2})`      |
| `SWITCH`  | Multi-value match | `SWITCH({Field}, "A", 1, "B", 2)`  |

#### 📈 Statistical Functions (5)

| Function    | Description         | Example                                    |
| ----------- | ------------------- | ------------------------------------------ |
| `COUNT`     | Count               | `COUNT({Field})`                           |
| `COUNTA`    | Non-empty count     | `COUNTA({Field})`                          |
| `COUNTIF`   | Conditional count   | `COUNTIF({Field}, ">100")`                 |
| `SUMIF`     | Conditional sum     | `SUMIF({Category}, "A", {Amount})`         |
| `AVERAGEIF` | Conditional average | `AVERAGEIF({Department}, "R&D", {Salary})` |

## 🌐 RESTful API Endpoints

### API Basics

- **Base URL**: `http://localhost:5000/api`
- **Authentication**: Bearer Token (JWT)
- **Data Format**: JSON
- **API Documentation**:
  - Swagger UI: `http://localhost:5000/apidocs`

    <br />

## ⚡ Real-time Collaboration Configuration

Real-time collaboration is based on WebSocket (Socket.IO), supporting multiple users editing the same table simultaneously.

### Startup Parameters

```bash
# Enable real-time collaboration
python run.py --enable-realtime
# Or use short flag
python run.py -r

# Disable real-time collaboration (default behavior)
python run.py
```

### Environment Variables

```env
# Enable real-time collaboration
ENABLE_REALTIME=true

# SocketIO message queue (recommended when using Redis, for multi-process deployment)
SOCKETIO_MESSAGE_QUEUE=redis://localhost:6379/1

# SocketIO heartbeat configuration
SOCKETIO_PING_TIMEOUT=60
SOCKETIO_PING_INTERVAL=25
```

### Docker Deployment

Add to `docker-compose.yml` or `.env` file:

```yaml
environment:
  - ENABLE_REALTIME=true
  - SOCKETIO_MESSAGE_QUEUE=redis://redis:6379/1
```

### Feature Overview

| Feature                  | Description                                                                      |
| ------------------------ | -------------------------------------------------------------------------------- |
| **Online Presence**      | Display users currently editing the same table with cursor positions             |
| **View Sync**            | Real-time sync of other users' view switching and scroll positions               |
| **Cell Locking**         | Automatically lock cells being edited to prevent conflicts                       |
| **Conflict Detection**   | Optimistic locking-based conflict detection, returns 409 Conflict status code    |
| **Offline Queue**        | Operations auto-cached when disconnected, auto-replayed in order on reconnection |
| **Graceful Degradation** | Auto-degrade to normal HTTP polling when WebSocket unavailable                   |

### Socket.IO Events

| Event Category      | Event Name                        | Description                        |
| ------------------- | --------------------------------- | ---------------------------------- |
| **Room Management** | `room:join` / `room:leave`        | Join/leave collaboration room      |
| **Presence**        | `presence:view_changed`           | View switch notification           |
| <br />              | `presence:cell_selected`          | Cell selection notification        |
| <br />              | `presence:user_joined`            | User joined notification           |
| <br />              | `presence:user_left`              | User left notification             |
| **Cell Locking**    | `lock:acquire` / `lock:release`   | Acquire/release cell lock          |
| <br />              | `lock:acquired` / `lock:released` | Lock/unlock broadcast notification |
| **Data Sync**       | `data:record_updated`             | Record update push                 |
| <br />              | `data:record_created`             | Record creation push               |
| <br />              | `data:record_deleted`             | Record deletion push               |
| <br />              | `data:field_updated`              | Field update push                  |
| <br />              | `data:view_updated`               | View update push                   |
| <br />              | `data:table_updated`              | Table update push                  |
| <br />              | `data:table_created`              | Table creation push                |
| <br />              | `data:table_deleted`              | Table deletion push                |

## 🐳 Docker Deployment

### Quick Deploy (Official Image One-click Start)

> For ARM architectures, please use the corresponding version image：`ygbinac/smarttable:1.4.1-arm64`

Directly start:

```bash
docker run -d \
  --name smarttable \
  -p 80:80 \
  -v smarttable_data:/app/data \
  -v smarttable_uploads:/app/uploads \
  -v smarttable_redis:/data/redis \
  ygbinac/smarttable:latest
```

* Or use docker compose, just create the following docker-compose.yml:
```bash
services:
  smarttable:
    image: ygbinac/smarttable:latest
    container_name: smarttable
    ports:
      - "80:80"
    volumes:
      - smarttable_data:/app/data
      - smarttable_uploads:/app/uploads
      - smarttable_redis:/data/redis
    restart: unless-stopped

volumes:
  smarttable_data:
  smarttable_uploads:
  smarttable_redis:
```

### Source Deploy

```bash
# Clone repository
git clone https://github.com/ldbinac/smart_table.git
cd smart-table-spec

# Copy environment variables configuration
cp .env.example .env
# Edit .env file, modify configuration as needed

# Start all services (frontend + backend + database) with one command
docker-compose up -d

# Check service status
docker-compose ps

# View logs
docker-compose logs -f
```

Access URLs:

- Frontend: <http://localhost>
- Backend API: <http://localhost:5000/api>
- API Docs: <http://localhost:5000/apidocs>

### Production Deployment (PostgreSQL + Redis)

```bash
# Use production configuration
docker-compose -f docker-compose.full.yml up -d

# Or start separately
docker-compose -f docker-compose.dev.yml up -d
```

### Docker Compose Service Architecture

```
smart-table-spec/
├── docker-compose.yml              # Development (SQLite)
├── docker-compose.full.yml         # Production (PostgreSQL + Redis + MinIO)
├── docker-compose.dev.yml          # Development (PostgreSQL + Redis)
├── Dockerfile                      # Frontend build + Nginx
├── smarttable-backend/
│   ├── Dockerfile                  # Backend application
│   └── docker-compose.yml          # Backend standalone orchestration
└── docker/
    ├── nginx/
    │   └── nginx.conf              # Nginx configuration
    └── supervisor/
        └── supervisord.conf        # Process manager configuration
```

### Environment Variable Configuration

See [.env.example](.env.example) and [smarttable-backend/.env.example](smarttable-backend/.env.example)

Key configuration items:

| Variable               | Description                    | Default                   | Required                  |
| ---------------------- | ------------------------------ | ------------------------- | ------------------------- |
| `SECRET_KEY`           | Flask secret key               | -                         | ✅ Production              |
| `JWT_SECRET_KEY`       | JWT secret key                 | -                         | ✅ Production              |
| `DATABASE_URL`         | Database connection            | sqlite:///smarttable.db   | ❌                         |
| `REDIS_URL`            | Redis address                  | redis\://localhost:6379/0 | ❌                         |
| `ENABLE_REALTIME`      | Enable real-time collaboration | false                     | ❌                         |
| `MAIL_SERVER`          | SMTP server                    | -                         | ❌ (email feature needed)  |
| `MINIO_ENDPOINT`       | MinIO address                  | -                         | ❌ (object storage needed) |

## 🌍 Browser Support

| Browser | Minimum Version |
| ------- | --------------- |
| Chrome  | >= 90           |
| Firefox | >= 88           |
| Safari  | >= 14           |
| Edge    | >= 90           |

> 💡 **Tip**: Recommended to use the latest version of Chrome or Edge for best experience

## 🤝 Contributing

Welcome to submit Issues and Pull Requests!

### Development Workflow

1. Fork this repository
2. Create a feature branch (`git checkout -b feature/AmazingFeature`)
3. Develop and test
4. Commit your changes (`git commit -m 'feat: Add some AmazingFeature'`)
5. Push to the branch (`git push origin feature/AmazingFeature`)
6. Create a Pull Request with detailed description

### Commit Message Convention

We follow [Conventional Commits](https://www.conventionalcommits.org/) specification:

- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation update
- `style`: Code format changes (no functional impact)
- `refactor`: Code refactoring (neither new feature nor fix)
- `perf`: Performance optimization
- `test`: Test related
- `chore`: Build/tool/auxiliary tool changes

### Code Standards

- Frontend follows ESLint + Prettier configuration
- Backend follows PEP 8 standards
- Ensure all tests pass before committing: `npm run test` (frontend) / `pytest` (backend)
- Ensure TypeScript type checking passes: `vue-tsc --noEmit`

## 📄 License

This project is licensed under the [MIT License](LICENSE).

```
MIT License

Copyright (c) 2026 Smart Table Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```

***

## 🙏 Acknowledgments

Thanks to all developers and users who contributed to this project!

Special thanks to:

- Vue.js team for the excellent frontend framework
- Element Plus team for the comprehensive UI component library
- Flask community for the flexible backend framework
- TinyEditor team for the powerful text editor component
- All Issue submitters and PR contributors

***

## 📞 Contact Us

- 📧 Email: <ldengbin@126.com>
- 💬 Issues: [GitHub Issues](https://github.com/ldbinac/smart_table/issues)
- 📖 Documentation: [User-Manual](https://github.com/ldbinac/smart_table/blob/main/doc/Smart-Table-User-Manual.md)
- Follow the author on WeChat:
  ![](./doc/img/wechat_official_account.png)



***

**⭐ If this project helps you, please give us a Star! ⭐**

**Made with ❤️ by Smart Table Team**