01
架构分层
五层单体全栈架构，前后端同仓、同进程，请求链路短、部署简单。
接入层Entry / Edge
自定义 Node HTTP Server 承载 Next.js 请求与 WebSocket 升级，同端口双协议（默认 3008）；生产由 Nginx 反向代理 + HTTPS 终结。
视图层Presentation
React 18 客户端组件为主，Radix UI 无障碍原语 + Tailwind 原子化样式，172 个业务组件按领域组织（表格 / 视图 / 大屏 / 编辑器 / 工作台 / 集成）。
状态层State / Domain
Zustand 多 Store 领域拆分（项目 / 团队 / 认证 / 集成），Immer 不可变更新，20 个自定义 Hooks 封装业务逻辑，组件保持轻薄。
服务层API / Service
Next.js App Router Route Handlers 提供 95 个 API 端点，统一鉴权中间件 + Zod 入参校验；业务逻辑下沉至 lib 层 90 个模块，API 层保持轻量的控制层职责。
数据层Persistence
PostgreSQL 单库 30 张业务表，node-postgres 连接池直连（无 ORM，SQL 可控），JSONB 存储表格 Schema 与记录，兼顾结构灵活与查询能力。
架构取舍：选择单体全栈而非微服务 —— 团队协作类应用的瓶颈在交互复杂度而非服务吞吐；单体降低运维成本，让私有化交付变成「一个 Node 进程 + 一个 PostgreSQL」，这是企业内网部署的关键优势。
02
核心技术栈
版本与用途逐项对应，均为项目实际依赖。
| 技术 | 版本 | 用途 |
|---|---|---|
| Next.js | 14.2.16 | App Router 全栈框架、SSR / 静态优化、API Route Handlers |
| React | 18.x | UI 渲染、并发特性、Suspense |
| TypeScript | 5.x | 全量类型约束，字段 / 视图 / 权限等领域模型集中定义 |
| Tailwind CSS | 3.4.17 | 原子化样式 + tailwindcss-animate 动效 |
| Radix UI | 30+ 原语 | 无障碍交互基座（Dialog / Select / Popover / Menu 等） |
| Zustand | latest | 轻量全局状态管理，领域 Store 拆分 |
| PostgreSQL / pg | 8.16.3 | 关系型持久化 + 连接池 |
| ws | 8.19.0 | WebSocket 实时协同服务 |
| Tiptap | 3.10+ | 富文本文档编辑器（ProseMirror 内核，14 个扩展） |
| Mind Elixir | 5.3.6 | 思维导图渲染与编辑内核 |
| Recharts | latest | 数据大屏图表渲染（7 种图表类型） |
| react-window | latest | 表格 / 看板虚拟滚动 |
| react-grid-layout | latest | 大屏拖拽网格布局 |
| dnd-kit / hello-pangea | 6.3 / latest | 字段排序、看板卡片、项目卡片拖拽 |
| SheetJS (xlsx) | 0.18.5 | Excel 解析与导出 |
| jsPDF + html2canvas | 3.0.4 / 1.4.1 | PDF 导出与画面栅格化 |
| Zod | 3.25.76 | API 入参与表单校验（配合 react-hook-form） |
| jsonwebtoken / bcryptjs | 9.0.2 / 2.4.3 | JWT 会话签发、密码哈希 |
| jsonpath-plus | 10.3.0 | 第三方 API 响应字段提取（集成同步） |
| date-fns | 4.1.0 | 日期计算（甘特图、日期字段、公式日期函数） |
03
状态管理与数据流
单向数据流 + 乐观更新，兼顾响应速度与一致性。
Store 领域拆分
project-store项目 / 文件树 / 当前表数据team-store团队与成员auth-store登录态与用户信息integrations/storeAPI 连接与同步任务workspace-context工作台上下文
写入链路
- 乐观更新：本地 Store 先改，UI 即时反馈
- 自动保存：
auto-save防抖批量提交 - 持久化 Hook：
use-data-persistence统一落库 - 本地兜底：
indexeddb-backup断网不丢数据 - 失败回滚：错误边界 + Toast 提示
// 单元格编辑到落库的完整链路 EditableCell onChange --> useTableStore.updateCell() // 乐观更新，UI 立即响应 --> formulaEngine.recalc() // 依赖公式字段级联重算 --> rowHighlight.evaluate() // 行高亮规则重新匹配 --> autoSave.schedule(debounce) // 防抖合并写请求 --> PATCH /api/tables/[id] // 服务端鉴权 + Zod 校验 --> pg.query(UPDATE ... JSONB) // PostgreSQL 持久化 --> ws.broadcast(roomId, patch) // 广播给同表其他协作者
04
性能工程
面向十万行级数据的四项关键优化。
虚拟滚动
基于 react-window 的窗口化渲染，只挂载可视区域行；表格与看板列均有虚拟化实现，DOM 节点数与数据量解耦。
Web Worker 解析
Excel 导入在独立 Worker 线程解析，主线程不阻塞，配合进度条实时反馈；万行文件导入期间界面保持可交互。
渲染与请求优化
- 组件级 memo / 稳定引用，规避大表整表重渲染
- 编辑写入防抖合并，减少请求数量
- 分页 Hook 支持服务端分页取数
- 重型编辑器（Tiptap / 导图 / 大屏）按需动态加载
数据层优化
- pg 连接池复用，避免连接风暴
- JSONB 整表存取，减少多表 JOIN 开销
lib/db/monitoring数据库监控埋点- 内置性能测试组件，可现场压测渲染表现
05
实时协同实现
WebSocket 房间模型 + 增量补丁持久化，自研而非依赖第三方协同服务。
房间模型
以资源 ID 作为 roomId，服务端维护 roomId → clientIds 映射，变更定向广播，避免全局广播开销。
在线状态
presenceMap 维护 roomId → userId → PresenceState，实时展示同表在线成员，进出房间自动同步。
增量补丁
协同变更以 Patch 写入 table_collab_patches 表，断线重连可补齐缺失变更，变更历史可追溯。
同端口部署：WebSocket 服务与 Next.js 共享同一 Node HTTP Server，通过
upgrade 事件挂载在 /ws/collab 路径，无需额外端口与独立进程，Nginx 只需一条 WebSocket 转发规则。
06
自研核心引擎
业务复杂度集中在 lib 层的若干独立引擎中，可单独测试与演进。
公式引擎
自研词法解析 + 求值器，内置 31 个函数（数学 / 文本 / 逻辑 / 日期），支持字段引用、依赖图拓扑排序与循环依赖检测。
行高亮引擎
规则条件求值引擎，按字段条件匹配自动着色行，规则可叠加、优先级可控。
统计引擎
聚合计算 + 条件筛选分离设计，支撑字段统计栏、指标卡与大屏数据聚合。
排序引擎
按字段类型智能比较（数字 / 日期 / 文本 / 多选），支持多字段级联排序。
关联 / Lookup
跨表关联解析与引用值计算，含 v2 版 Lookup 工具与子记录聚合逻辑。
AI 引擎
DeepSeek API 封装 + AI 字段引擎（提示词模板变量替换、批量执行、用量计数），及表格 / 文档生成服务。
同步引擎
第三方 API 拉取、字段映射转换（JSONPath）、全量 / 增量写入、冲突与错误策略处理，同步日志落库。
布局引擎
大屏网格布局计算与主题体系，画册视图布局映射，甘特图时间轴排布计算。
权限引擎
行级 / 列级 / 文件级权限判定与查询过滤器注入，权限变更全量日志记录。
07
数据模型
PostgreSQL 30 张业务表，按领域归组。
身份与组织
业务实体
权限与审计
协同 · 备份 · 集成 · 商业化
不用 ORM 的理由：表格类产品的核心数据是动态 Schema（字段可任意增删改类型），ORM 的静态模型映射反而是负担。直接用 SQL + JSONB，既保留结构灵活性，又能用 PostgreSQL 的 JSONB 索引与查询能力，性能与可维护性均可控。
08
安全体系
身份、鉴权、数据、传输四层防护。
身份与会话
- bcrypt 密码单向哈希，明文不落库
- JWT 无状态会话签发与校验
- OAuth 第三方登录接入
- 设备指纹（
fingerprint）辅助风险识别 - 路由守卫（
use-auth-guard）前端访问拦截
接口与数据
- 统一鉴权中间件：API 层集中身份校验
- Zod 入参校验：拒绝非法载荷
- 参数化 SQL：从根本上规避注入
- 公开访问隔离（
public-access）：分享链接只暴露必要数据 - 加密工具（
crypto）：敏感配置（如 API 凭据）加密存储
09
工程结构
按职责分目录，领域内聚。
app/ Next.js App Router 路由与 API api/ 95 个 Route Handler（tables/ai/teams/projects/pay/...） projects/ tables/ 工作台与表格页面 documents/ mindmaps/ 文档与导图页面 dashboards/ forms/ 大屏与表单页面 admin/ auth/ invite/ 后台、认证、邀请 scenarios/ sitemap.ts SEO 场景页与站点地图 components/ 172 个 React 组件 ui/ 50 个基础组件（Radix 封装） project-detail/ 项目侧栏、文件树、工具栏 workspace/ 工作台标签页与对话框 tiptap-editor/ 富文本编辑器与扩展 field-statistics/ 字段统计与条件构建器 integrations/ API 连接、字段映射、同步任务 lib/ 90 个模块：引擎、服务、Store、工具 db/ 连接配置、基础查询、监控 statistics/ row-highlight/ 统计与高亮引擎 integrations/ 同步引擎与数据映射 hooks/ 20 个业务 Hooks（协同、导入、权限、分页...） workers/ Web Worker（Excel 解析） scripts/ 构建、发布、部署、迁移脚本 server.js 自定义 Node Server（HTTP + WebSocket）
10
构建与部署
标准化脚本链路，支持云端与离线内网两种交付形态。
构建链路
pnpm dev自定义 Server 开发模式（含 WS）pnpm buildNext 构建 + 后处理脚本pnpm release预编译产物构建 + 打包- pnpm 统一包管理，依赖硬链接复用
部署形态
- SaaS 云端：Node 进程 + Nginx + HTTPS
- 私有化：客户自有服务器 + 自建 PostgreSQL
- 离线包：预编译产物 tar 分发，内网无需联网构建
- 环境隔离：
.env.local / .production / .offline多环境配置
# 运行时依赖（最小集） Node.js >= 18 Next.js 14 要求 PostgreSQL >= 13 JSONB 与索引特性 Nginx 可选 反向代理 / HTTPS / WebSocket 转发 内存 >= 2GB 单实例建议值 # 环境变量（关键项） DATABASE_URL PostgreSQL 连接串 JWT_SECRET 会话签名密钥 DEEPSEEK_API_KEY AI 能力密钥（不配置则 AI 功能不可用） DEEPSEEK_API_URL 模型服务地址，可指向私有部署模型 PORT 服务端口，默认 3008
数据主权：除 AI 能力需调用模型 API 外，全部数据留在自有 PostgreSQL 中，无任何第三方 BaaS / 云数据库依赖。AI 服务地址可配置，支持接入私有化部署的模型服务，实现完全内网闭环。