中文 | English

一个基于 Vue 3 + Flask 的智能多维表格系统，类似于 Airtable 或飞书多维表格。支持多种视图（表格视图、分组视图、看板视图、日历视图、甘特视图、表单视图、仪表盘等），拥有丰富的字段类型；支持markdown编写富文本文档。

• 多维表格管理 - 创建、编辑、删除、收藏多维表格，支持成员管理和分享协作
• 数据表管理 - 支持多个数据表，拖拽排序、重命名、删除、复制
• 字段管理 - 支持 26 种字段类型，包含字段配置、排序、显示隐藏、默认值设置
• 记录管理 - 增删改查、批量操作、记录详情抽屉、变更历史追踪
• 视图管理 - 6 种视图类型，支持筛选、排序、分组、视图切换、列冻结
• 文档管理 - 文档创建编辑、富文本编辑（Quill）、Markdown 支持、PDF 导出、版本历史管理

• 数据筛选 - 多条件组合筛选，支持 AND/OR 逻辑，20+ 种操作符
• 数据排序 - 多字段排序，支持升序/降序，拖拽调整优先级
• 数据分组 - 按字段分组展示，支持多级分组（最多 3 级）、分组统计
• 公式引擎 - 43 个内置函数，支持数学、文本、日期、逻辑、统计计算
• 流式数据加载 - 万级数据首屏秒级渲染，异步加载剩余页，非阻塞式操作
• 数据导入 - 支持 Excel、CSV、JSON 格式，支持多 Sheet，可导入创建新表
• 数据导出 - 支持 Excel、CSV、JSON 格式，自定义导出字段

• Base 分享 - 多维表级别分享，支持链接分享和权限控制
• 表单分享 - 表单视图公开分享，支持配置提交选项
• 仪表盘分享 - 仪表盘公开分享，支持实时数据展示
• 成员管理 - Base 级别成员列表、添加成员、角色分配
• 实时协作 - 基于 WebSocket 的多人实时协作（可选启用）
  • 在线状态显示
  • 视图同步（滚动位置、视图切换）
  • 单元格锁定（防止冲突编辑）
  • 冲突检测与解决（基于乐观锁）
  • 离线队列（断线自动缓存，重连自动重放）
  • 优雅降级（实时不可用时自动切换为普通模式）
• 请求追踪系统 - 请求 ID 全链路追踪、统一错误处理、标准化 API 响应格式
• 本地缓存体系 - 协作状态缓存、用户认证缓存、系统配置缓存，配置请求减少 90%+

• 用户认证 - JWT Token 认证，支持刷新 Token、邮箱验证、密码重置
• 角色权限 - 基于角色的访问控制（RBAC）
  • 所有者（Owner）- 完全控制权限
  • 管理员（Admin）- 管理权限（除删除外）
  • 编辑者（Editor）- 编辑权限
  • 评论者（Commenter）- 评论和查看权限
  • 查看者（Viewer）- 只读权限
• 安全配置管理 - 动态密码强度规则、注册开关、会话超时配置、公开配置接口
• 敏感信息保护 - 30+ 修复点的日志脱敏，密码/Token/手机号/邮箱自动遮蔽
• 安全防护 - XSS 防护、CSRF 保护、安全响应头、API 速率限制、文件上传安全验证
• 操作日志 - 完整的操作审计日志

• 拖拽排序 - 表格、字段、视图、看板卡片拖拽排序
• 收藏功能 - 快速访问常用的表格和仪表盘
• 搜索功能 - 快速搜索表格名称和记录内容
• Element Plus 图标 - 统一的图标系统，提升视觉一致性
• 快捷键支持 - 常用操作的键盘快捷键

• 多种图表组件 - 数字卡片、时钟组件、日期组件、KPI 卡片、跑马灯、实时图表等
• 仪表盘模板 - 支持保存和复用仪表盘配置模板
• 网格布局 - 灵活的网格布局系统，支持自定义行列配置
• 实时数据 - 支持实时数据更新和动态图表
• 分享功能 - 仪表盘公开分享，支持嵌入外部网站

• SMTP 配置 - 支持自定义 SMTP 服务器
• 邮件模板 - 可自定义邮件模板（注册验证、密码重置等）
• 邮件队列 - 异步邮件发送队列，支持重试机制
• 邮件日志 - 完整的邮件发送日志和统计
• 管理员面板 - 邮件配置管理和监控界面

• 文档 CRUD - 支持文档创建、编辑、删除、查询，与 Base 关联权限控制
• 富文本编辑器 - 基于 Quill，支持加粗/斜体/列表/链接/表格等格式化功能
• Markdown 编写 - 支持 Markdown 语法实时渲染
• 版本历史 - 版本记录与回溯，版本对比查看，创建者追踪
• PDF 导出 - 文档内容导出为 PDF，DOM 直接解析确保样式准确

功能	预览图	功能	预览图
登录		注册
首页		全部首页
表格视图		分组表格
表格字段		看板视图
日历视图		甘特图视图
表单视图		仪表盘
分享功能		文档管理

下载最新release版本下的一键启动包，解压之后一键启动：

# Windows PowerShell
.\start.bat

# Linux/macOS
./start.sh

该一键启动包无需依赖任何外部环境，双击即可启动。

无需安装任何依赖，无需手工创建账号。

启动后会自动打开浏览器，然后试用控制台打印的账号邮箱和密码登录即可试用。

使用官方docker镜像启动（自动适配架构）：

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

• 或者使用 docker compose ，只需创建以下 docker-compose.yml ：：

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:

• Node.js >= 18
• npm >= 9
• Python >= 3.11 （仅后端模式需要）

cd smart-table
npm install

npm run dev

访问 http://localhost:5173

npm run build

npm run preview

# 运行所有测试
npm run test

# 监听模式运行测试（开发时使用）
npm run test:watch

# 生成测试覆盖率报告
npm run test:coverage

cd smarttable-backend

# 复制环境变量配置文件
cp .env.example .env
# 编辑 .env 文件配置数据库连接等（默认使用 SQLite）

# 启动所有服务（SQLite 模式）
docker-compose up -d

# 或使用 PostgreSQL + Redis（适合生产环境）
# v1.4.0 优化：Docker 部署内嵌 Redis，无需额外启动 Redis 容器
docker-compose -f docker-compose.dev.yml up -d

# 执行数据库迁移
docker-compose exec backend flask db upgrade

# 查看日志
docker-compose logs -f backend

# 访问 API 文档
# http://localhost:5000/api/docs  (Swagger UI)
# http://localhost:5000/api/apidoc  (ReDoc)

cd smarttable-backend

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# Windows:
venv\Scripts\activate
# Linux/macOS:
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt

# 复制环境变量配置文件
cp .env.example .env
# 默认使用 SQLite，无需修改 DATABASE_URL

# 初始化数据库
flask db upgrade

# 启动开发服务器（默认不启用实时协作）
flask run --reload

# 或使用 run.py 启动（支持更多选项）
python run.py

# 启用实时协作功能
python run.py --enable-realtime
> 或者通过修改 .env 的 `ENABLE_REALTIME=True` 来配置协同编辑功能

✅ 默认数据库: SQLite（轻量级，无需额外安装）
✅ 可选数据库: PostgreSQL（通过环境变量 DATABASE_URL 配置）
✅ 认证系统: JWT Token 认证，支持刷新 Token、邮箱验证
✅ 权限管理: 基于角色的权限控制（RBAC）
✅ 数据迁移: Alembic 数据库迁移工具
✅ API 文档: 完整的 Swagger/OpenAPI 文档（Flasgger）
✅ 实时协作: 可选的 WebSocket 实时协作功能（通过 --enable-realtime 启用）
✅ 邮件系统: 可选的 SMTP 邮件发送功能
✅ 对象存储: 可选的 MinIO 文件存储
✅ 安全防护: XSS 防护、速率限制、安全响应头

User (用户)
  ├── owns many Base (多维表格)
  ├── is member of many Base (通过 BaseMember)
  └── has many OperationLog (操作日志)

Base (多维表格)
  ├── has many Table (数据表)
  ├── has many Dashboard (仪表盘)
  ├── has many BaseShare (分享链接)
  ├── has many BaseMember (成员)
  └── has many CollaborationSession (协作会话)

Table (数据表)
  ├── has many Field (字段)
  ├── has many Record (记录)
  ├── has many View (视图)
  ├── has many LinkRelation (关联关系)
  └── belongs to Base

Field (字段)
  ├── has options (字段配置)
  └── belongs to Table

Record (记录)
  ├── has many RecordHistory (变更历史)
  ├── has values for each Field
  └── belongs to Table

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

• 用户认证信息（用户名、邮箱、密码哈希）
• 邮箱验证状态
• 角色权限（普通用户/管理员）
• 头像和个人资料

• 多维表格基础单元
• 支持收藏、自定义图标和颜色
• 成员管理和权限控制
• 分享设置（公开/私有/密码保护）

• 包含字段定义和记录数据
• 支持拖拽排序、收藏
• 关联关系配置

• 定义数据列的类型和属性
• 支持 26 种字段类型
• 丰富的字段选项（验证规则、默认值、格式化等）

• 数据行，存储各字段的值
• 支持增删改查、批量操作
• 完整的变更历史追踪

• 数据展示方式（6 种视图类型）
• 独立的筛选、排序、分组配置
• 视图级别字段控制（隐藏、冻结、宽度）

• 文档存储与管理，关联到 Base
• 支持富文本和 Markdown 内容
• 权限继承自所属 Base

• 文档版本历史追踪
• 记录每次保存的快照和创建者
• 支持版本回溯和对比

• 实时协作会话追踪
• 记录用户加入/离开、活跃状态
• 仅在启用实时协作功能时使用

// 数学计算
{单价} * {数量}

// 折扣计算
{原价} * (1 - {折扣})

// 条件判断（嵌套 IF）
IF({成绩} >= 90, "优秀", IF({成绩} >= 60, "及格", "不及格"))

// 文本拼接
CONCAT({姓}, {名})

// 日期计算
DATEDIF({开始日期}, {结束日期}, "D")

// 统计计算
SUMIF({部门}, "销售部", {销售额})

// 查找引用
LOOKUP({关联表.相关记录}, {目标字段})

• Base URL: http://localhost:5000/api
• 认证方式: Bearer Token (JWT)
• 数据格式: JSON
• API 文档:
  • Swagger UI: http://localhost:5000/apidocs

实时协作功能基于 WebSocket (Socket.IO) 实现，支持多人同时编辑同一表格。

# 启用实时协作
python run.py --enable-realtime
# 或使用短参数
python run.py -r
> 或通过修改 .env 的 `ENABLE_REALTIME=True` 来配置协同编辑功能

# 不启用实时协作（默认行为）
python run.py

# 启用实时协作
ENABLE_REALTIME=true

# SocketIO 消息队列（使用 Redis 时推荐，用于多进程部署）
SOCKETIO_MESSAGE_QUEUE=redis://localhost:6379/1

# SocketIO 心跳配置
SOCKETIO_PING_TIMEOUT=60
SOCKETIO_PING_INTERVAL=25

在 docker-compose.yml 或 .env 文件中添加：

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

直接启动：

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

• 或者使用 docker compose ，只需创建以下 docker-compose.yml ：：

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:

# 克隆项目
git clone https://github.com/ldbinac/smart_table.git
cd smart-table-spec

# 复制环境变量配置
cp .env.example .env
# 编辑 .env 文件，根据实际情况修改配置

# 一键启动所有服务（前端 + 后端 + 数据库）
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f

访问地址：

• 前端应用: http://localhost
• 后端 API: http://localhost:5000/api
• API 文档: http://localhost:5000/apidocs

# 使用生产环境配置
docker-compose -f docker-compose.full.yml up -d

# 或分别启动
docker-compose -f docker-compose.dev.yml up -d

smart-table-spec/
├── docker-compose.yml              # 开发环境（SQLite）
├── docker-compose.full.yml         # 生产环境（PostgreSQL + Redis + MinIO）
├── docker-compose.dev.yml          # 开发环境（PostgreSQL + Redis）
├── Dockerfile                      # 前端构建 + Nginx
├── smarttable-backend/
│   ├── Dockerfile                  # 后端应用
│   └── docker-compose.yml          # 后端独立编排
└── docker/
    ├── nginx/
    │   └── nginx.conf              # Nginx 配置
    └── supervisor/
        └── supervisord.conf        # 进程管理配置

详见 .env.example 和 smarttable-backend/.env.example

关键配置项：

💡 提示: 推荐使用最新版本的 Chrome 或 Edge 以获得最佳体验

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 进行开发和测试
4. 提交更改 (git commit -m 'feat: Add some AmazingFeature')
5. 推送到分支 (git push origin feature/AmazingFeature)
6. 创建 Pull Request 并填写详细的描述

我们使用 Conventional Commits 规范：

• feat: 新功能
• fix: Bug 修复
• docs: 文档更新
• style: 代码格式调整（不影响功能）
• refactor: 代码重构（既不是新功能也不是修复）
• perf: 性能优化
• test: 测试相关
• chore: 构建/工具/辅助工具的变动

• 前端遵循 ESLint + Prettier 配置
• 后端遵循 PEP 8 规范
• 提交前确保通过所有测试：npm run test (前端) / pytest (后端)
• 确保 TypeScript 类型检查通过：vue-tsc --noEmit

本项目采用 MIT License 开源协议。

感谢所有为本项目做出贡献的开发者和用户！

特别感谢：

• Vue.js 团队提供优秀的前端框架
• Element Plus 团队提供完善的 UI 组件库
• Flask 社区提供灵活的后端框架
• TinyEditor 团队提供功能强大的文本编辑器组件
• Vxe-Table 团队提供高性能的虚拟滚动表格组件
• Vtable 团队提供高性能的 canvas 表格组件
• 所有 Issue 提交者和 Pull Request 贡献者

• 📧 Email: ldengbin@126.com
• 💬 Issues: GitHub Issues
• 📖 Documentation: User-Manual
• 关注作者：

⭐ 如果这个项目对你有帮助，请给我们一个 Star！⭐

Made with ❤️ by Smart Table Team