Workspace Board / 临时工作区

一个轻量、可分享、可加密、可自动过期的临时工作区系统。

它适合用来快速整理并分享：

• Markdown 文本草稿
• 图片与附件
• 带访问控制的临时资料页

核心特性

• 文本块支持所见即所得 Markdown 编辑、渲染/源码切换、代码高亮和自动保存
• 文件块支持图片网格、文件列表、批量选择和 ZIP 打包下载
• 图片预览支持缩放、旋转、翻转、拖拽、取色和链接复制
• 工作区支持访问密码、管理密码、过期自动清理
• 前后端单仓库，支持本地运行和 Docker 部署

技术栈

• 前端：React 19、TypeScript、Vite、React Router、dnd-kit、Milkdown、react-markdown
• 后端：Express 5、TypeScript、Multer
• 数据与存储：SQLite + 本地磁盘目录
• 工程护栏：ESLint、TypeScript typecheck、Vite build

快速开始

1. 安装依赖

npm install

2. 准备环境变量

复制 .env.example 为 .env，至少确认以下变量：

• PORT
• APP_BASE_URL
• DATA_DIR
• JWT_SECRET
• EDIT_SESSION_TTL_HOURS
• MAX_FILE_SIZE_MB

3. 本地开发

npm run dev

默认情况下：

• 前端开发服务运行在 http://localhost:5173
• 后端服务运行在 http://localhost:3000
• 工作区页面路径为 http://localhost:5173/s/:slug

4. 构建与启动生产版本

npm run build
npm run start

质量检查

提交前建议至少执行：

npm run typecheck
npm run lint
npm run build

目录结构

client/
  public/
  src/
    components/
      file-block/
      image-preview/
      text-block/
    hooks/
    pages/
    styles/

server/
  src/
    db/
    http/
    routes/
    services/
    auth.ts
    config.ts
    db.ts
    dto.ts
    index.ts
    utils.ts

docs/
  architecture.md
  development-guide.md
  deployment.md

当前结构要点

• client/src/App.tsx 负责路由注册与页面级懒加载
• client/src/pages/WorkspacePage.tsx 负责工作区级状态编排、权限流、toast 和预览弹层调度
• client/src/components/BlockList.tsx 负责内容块列表和拖拽排序
• client/src/components/TextBlock.tsx 负责文本块的渲染/源码双模式、自动保存和工具栏编排
• client/src/components/ImagePreviewModal.tsx 负责图片预览状态编排，工具栏等细节已下沉到 image-preview/
• server/src/index.ts 现在只负责启动、挂载中间件和注册路由
• server/src/routes 按工作区、内容块、媒体访问拆分路由
• server/src/db 拆成共享连接、迁移和不同仓储模块

分包与性能优化

当前前端已做两层按需加载：

• 路由级分包：HomePage、WorkspacePage
• 重功能分包：BlockList、ImagePreviewModal、FilePreviewModal

同时，Vite 构建中对 dnd-kit 和 Markdown 编辑器依赖分别做了独立 vendor chunk，避免拖拽与富编辑器依赖直接挤进主业务包。

文档导航

• README.md 项目总览、启动方式和目录入口
• docs/architecture.md 当前架构、模块边界、数据流和重构后的分层说明
• docs/development-guide.md 开发维护约定、常见修改入口和回归检查建议
• docs/deployment.md 环境变量、Docker 与生产部署说明
• 产品说明文档.md 产品定位、功能说明与边界

仓库约定

• 新增和重构代码默认补充中文注释
• 用户可见文案默认使用简体中文
• 样式遵循“共享骨架在 blocks.css，业务细节在模块样式文件”的原则
• 临时日志、截图、浏览器调试产物不进入仓库