markslide

1- Markslide 项目需求文档 (PRD)

1.1- 项目概述

1.1.1- 项目名称

Markslide

1.1.2- 项目目标

Markslide 是一个文档转换和预览工具，旨在帮助用户将文档转换为 HTML、Markdown 和 PPT 格式，同时提供高级的交互和用户体验。项目设计强调简洁优雅的用户界面、流畅的交互效果、快速响应性以及强大的文件管理和转换功能。

1.2- 预览功能重点部分

1.2.1- 预览功能说明

在文件列表中选择文件后，可以通过点击文件列表上方工具栏中的 " 预览 " 图标（图标为一个小眼睛）来选择不同的预览模式。点击 " 预览 " 图标将会展开一个下拉菜单，提供以下三种预览模式：

  1. Markdown 预览

    • 图标：[Markdown 图标]
    • Tooltip 提示：预览 Markdown 文件
    • 功能：选择此模式后，将打开一个新标签页，以 Markdown 渲染的方式展示文件内容。在这个标签页中，可以设置 Markdown 预览的样式，如字体大小、代码块样式等，这些设置是独立的，不会影响其他预览模式。

  2. HTML 预览

    • 图标：[HTML 图标]
    • Tooltip 提示：预览 HTML 文件
    • 功能：选择此模式后，将打开一个新标签页，以 HTML 渲染的方式展示文件内容。在这个标签页中，可以设置 HTML 预览的样式，如背景色、链接颜色等，这些设置是独立的，不会影响其他预览模式。

  3. PPT 预览

    • 图标：[PPT 图标]
    • Tooltip 提示：预览 PPT 文件
    • 功能：选择此模式后，将打开一个新标签页，以 PPT 渲染的方式展示文件内容。在这个标签页中，可以设置 PPT 预览的主题、样式、背景等，这些设置是独立的，不会影响其他预览模式。

1.2.2- 示例操作

  1. 选择文件：
    • 在文件列表中选择一个 Markdown 文件。
  2. 选择预览模式：
    • 点击文件列表上方的 " 预览 " 图标，展开下拉菜单。
    • 从下拉菜单中选择 "PPT 预览 "（或其他预览模式）。
  3. 打开新标签页：
    • 选择预览模式后，将自动打开一个新标签页，以所选模式展示文件内容。
    • 例如，选择 "PPT 预览 " 后，新标签页将以 PPT 的样式展示 Markdown 文件内容。
  4. 独立设置：
    • 在每个预览模式的新标签页中，可以独立设置样式和功能，互不影响。例如：
      • Markdown 预览：可以设置字体大小、代码块样式等。
      • HTML 预览：可以设置背景色、链接颜色等。
      • PPT 预览：可以设置主题、背景、幻灯片布局等。

1.2.3- 交互体验

  • 用户友好：每个预览模式的图标和 Tooltip 提示都清晰明了，方便用户快速选择。
  • 独立设置：每个预览模式的设置都是独立的，确保用户在不同的预览模式下可以自由定制，互不影响。
  • 新标签页：每次选择预览模式时，都会打开一个新标签页，确保预览内容不会干扰当前页面的操作。
  • 动画效果：所有交互带有平滑过渡动画，提升用户体验。
  • 提示和反馈：操作反馈如上传进度、成功提示、错误提示等。
  • 输入验证：提供严格输入验证和实时反馈，确保输入数据的正确性。

1.2.4- 预览内容的格式

  1. 在预览模式下忽略掉 Markdown 头部 YAML 和 YML 部分的内容，该部分内容不在三种预览模式中显示。
  2. PPT 预览模式中，以各级标题作为分页的标准。

1.3- 技术栈

1.3.1- 前端技术

  • 框架: Next.js 14.1.0
  • React: 18.2.0
  • UI 组件库: Chakra UI
  • CSS 框架: Tailwind CSS 3.4.x
  • 状态管理: Zustand
  • Markdown 处理: react-markdown + remark-gfm（支持扩展语法）
  • HTML 处理: react-html-parser + DOMPurify
  • PPT 处理: reveal.js + PptxGenJS
  • 文件处理: file-saver, react-dropzone
  • 编辑器: TipTap（可支持富文本编辑和 Markdown 扩展）
  • 开发工具: TypeScript, ESLint, Prettier
  • 图标库: FontAwesome 或 Material Icons
  • 国际化: i18next（多语言支持）

1.3.2- 其他技术

  • 代码分割和懒加载: Next.js 动态导入 + React Suspense
  • 性能优化: React useMemo 和 useCallback 钩子
  • 测试工具: Jest + Testing Library + Cypress (E2E 测试)
  • 环境变量: .env 文件
  • 部署: Vercel 或 Netlify
  • 安全工具: Helmet, Multer (文件上传中间件)
  • 文件类型检查: file-type
  • 错误监控: Sentry
  • 响应式设计: Tailwind CSS 响应式类
  • 版本控制: Git 和 GitHub
  • 后端对接: Supabase

1.4- 功能需求

1.4.1- 文件导入

  • 支持拖拽上传和点击选择文件
    • 用户可通过拖拽或点击按钮上传文件，提供动态效果提升用户体验。
  • 支持的文件格式
    • 支持 Markdown (.md)、HTML (.html)、PowerPoint (.ppt, .pptx) 文件。
  • 文件大小限制
    • 最大 10MB，系统提示不符合大小的文件。
  • 上传后自动解析并预览
    • 上传文件后，系统自动解析内容并显示在文件预览窗口。

1.4.2- 文件列表功能

  • 文件列表
    • 上传文件显示在文件列表中，支持排序和筛选。
  • 文件操作
    • 预览: 在新标签页中全屏预览文件。
    • 导入: 将文件内容导入编辑器。
    • 导出: 可导出为 Markdown、HTML 和 PPT 格式。
    • 编辑: 在编辑器中修改内容。
    • 重命名: 提供实时反馈和输入验证。
  • 预览模式选择
    • 用户选中文件列表中的文本时，可以选择 3 种预览模式：
      • Markdown 预览: 以 Markdown 格式预览文档。
      • HTML 预览: 以 HTML 格式预览文档。
      • PPT 预览: 以 PPT 格式预览文档。
  • 高级搜索和过滤功能
    • 支持按标签、文件类型和时间筛选文件，便于用户管理大量文件。

1.4.3- 文件预览

  • Markdown 预览
    • 使用 react-markdown 和 remark-gfm，支持代码高亮。
  • HTML 预览
    • 使用 react-html-parser + DOMPurify 确保安全性。
  • PPT 预览
    • 使用 reveal.js，支持全屏切换和幻灯片导航。
  • 全屏预览
    • 所有预览模式在新标签页全屏显示，带有过渡动画。
  • 独立主题系统
    • 每种预览模式独立主题，不受主页主题影响。

1.4.4- 编辑功能

  • 丰富的文本编辑器
    • 使用 TipTap 提供 Markdown 支持的富文本编辑功能。
  • 实时预览
    • 编辑内容实时更新预览区域。
  • 撤销和重做操作
    • 支持多步操作，提供撤销和重做功能。

1.4.5- 文件导出

  • 支持导出为 Markdown、HTML 和 PPT 格式
    • 文件导出时保留样式和格式。
  • 使用 PptxGenJS 生成 PPT 文件

1.4.6- 用户界面

  • 响应式设计
    • 确保应用在不同设备和屏幕尺寸上正常显示，优化移动端。
  • 主题切换
    • 支持深色、浅色模式和系统模式自动切换。
  • 图标系统
    • 配置应用图标，支持动画效果。
  • GitHub 仓库链接
    • 主页显示 GitHub 链接，支持动态效果。

1.4.7- 交互设计

  • 动画效果
    • 所有交互带有平滑过渡动画，提升用户体验。
  • 提示和反馈
    • 操作反馈如上传进度、成功提示、错误提示等。
  • 输入验证
    • 提供严格输入验证和实时反馈，确保输入数据的正确性。

1.4.8- 版本管理和历史记录

  • 版本管理
    • 允许用户查看和恢复到之前的文档版本。
  • 历史记录
    • 保存每个文档的版本历史，支持按时间或标签筛选。

1.4.9- 云存储集成

  • 云存储支持
    • 通过对接 Google Drive、Dropbox 等云存储服务，实现文件的云端同步和备份。
  • 自动同步
    • 支持自动同步功能，确保文件的最新版本始终可用。

1.4.10- 多格式支持扩展

  • 多格式支持
    • 未来可考虑支持 PDF、Word 等其他格式的转换和预览需求。
  • 插件和自定义模板支持
    • 允许用户创建和使用自定义模板或插件，实现更加个性化的文档转换需求。

1.4.11- 协同编辑

  • 多人协作
    • 支持多人实时协作编辑文档，适用于团队合作项目。
  • 协作提示
    • 显示当前在线协作的用户，提供实时更新和冲突解决机制。

1.4.12- 多语言支持

  • 多语言支持
    • 使用 i18next 实现多语言支持，默认提供中文和英文，其他语言可后期扩展。

1.4.13- 用户反馈

  • 错误报告：增加用户反馈机制，允许用户报告错误和提出建议。
  • 用户建议：提供用户建议收集渠道，帮助持续改进产品。

1.4.14- 用户引导

  • 新手引导：添加新手引导和帮助文档，帮助新用户快速上手。
  • 帮助文档：提供详细的使用手册和常见问题解答。

1.5- 技术实现细节

1.5.1- 文件导入

  • 拖拽上传：使用 react-dropzone 实现拖拽上传。
  • 点击选择文件：使用标准文件输入控件。
  • 文件解析
    • 使用 file-saver 和对应的解析库：
      • Markdown：react-markdown
      • HTML：react-html-parser + DOMPurify
      • PPT：reveal.js

1.5.2- 文件预览

  • Markdown 预览：支持代码高亮。
  • HTML 预览：结合 DOMPurify 确保安全性。
  • PPT 预览：支持全屏和幻灯片导航。
  • 全屏预览：在新标签页全屏显示内容。

1.5.3- 编辑功能

  • 文本编辑器：使用 TipTap 提供 Markdown 支持的富文本编辑。
  • 实时预览：使用 useState 和 useEffect 钩子实现编辑器与预览同步。
  • 撤销和重做：使用 Zustand 管理撤销和重做操作。

1.5.4- 文件导出

  • 导出功能：file-saver 实现文件导出，支持进度条和完成提示。

1.5.5- 用户界面

  • 响应式设计：使用 Tailwind CSS 确保适应各种设备。
  • 主题切换：使用 Zustand 管理深色、浅色和系统主题切换。
  • 图标系统：支持动画效果。

1.5.6- 版本控制与部署

  • Git 和 GitHub：使用 Git 进行版本控制。
  • 持续集成：使用 GitHub Actions 集成测试和自动部署。
  • 部署：使用 Vercel 或 Netlify 部署应用，确保自动化部署和预览环境。

1.5.7- 后端对接

  • Supabase：未来可通过 Supabase 实现用户认证和文档版本管理。

1.6- 安全性和性能优化

  • 内容安全策略 (CSP)：使用 Helmet 设置内容安全策略。
  • 文件类型检查：file-type 检查文件类型，防止恶意文件上传。
  • 文件上传中间件：结合 Multer 增强文件上传安全性。
  • 代码分割和懒加载：Next.js 动态导入和 React Suspense 实现代码懒加载。
  • 性能优化：使用 React 的 useMemo 和 useCallback 优化渲染性能。
  • 图片优化：如支持图片预览，使用 next/image 优化加载。
  • 错误监控：集成 Sentry 监控应用错误。

1.7- 测试和部署

  • 单元测试：使用 Jest 和 Testing Library 进行单元测试。
  • 端到端测试 (E2E)：使用 Cypress 进行端到端测试，覆盖文件上传、导出和预览等关键功能。
  • 环境变量：使用 .env 文件管理环境变量。
  • 自动化部署：使用 Vercel 或 Netlify 自动化部署和预览环境。

1.8- 未来可能的扩展

  • 用户认证系统：添加用户登录和注册功能。
  • 文档版本控制：实现文档的历史版本管理和回滚功能。
  • 多格式支持：支持 PDF、Word 等其他格式的转换和预览需求。
  • 协同编辑：支持多人实时协作编辑文档，适用于团队合作项目。
  • 插件和自定义模板支持：允许用户创建和使用自定义模板或插件，实现更加个性化的文档转换需求。
  • 多云支持：增加对更多云存储服务的支持，如 OneDrive、Box 等。
  • 自动备份：实现定期自动备份功能，确保数据安全。
  • 数据加密：对敏感数据进行加密处理，确保数据安全。
  • 权限管理：增加更细粒度的权限管理，确保不同用户有不同的操作权限。

1.9- 主页样式

image

1.10- 三种预览模式完全独立。目录结构

src/
├── app/                    # Next.js 应用路由
│   ├── markdown-preview/   # Markdown 预览路由
│   │   └── [id]/
│   │       └── page.tsx
│   ├── html-preview/      # HTML 预览路由
│   │   └── [id]/
│   │       └── page.tsx
│   └── ppt-preview/       # PPT 预览路由
│       └── [id]/
│           └── page.tsx
├── features/              # 功能模块
│   ├── markdown-preview/  # Markdown 预览功能
│   │   ├── components/    # 组件
│   │   │   ├── Preview.tsx
│   │   │   └── Toolbar.tsx
│   │   ├── store/        # 状态管理
│   │   │   └── store.ts
│   │   ├── styles/       # 样式
│   │   │   └── style.css
│   │   ├── themes/       # 主题
│   │   │   └── index.ts
│   │   └── utils/        # 工具函数
│   │       └── converter.ts
│   ├── html-preview/     # HTML 预览功能 (完全独立)
│   │   ├── components/
│   │   ├── store/
│   │   ├── styles/
│   │   ├── themes/
│   │   └── utils/
│   └── ppt-preview/      # PPT 预览功能 (完全独立)
│       ├── components/
│       ├── store/
│       ├── styles/
│       ├── themes/
│       └── utils/
└── shared/               # 共享工具/类型
    ├── types/           # 共享类型定义
    │   └── file.ts
    └── utils/           # 共享工具函数
        └── file.ts

1.10.1- 目录结构说明

  1. 每个预览模式都是完全独立的功能模块，确保预览模式之间没有相互依赖。
  2. 每个模块有自己的组件、状态管理、样式和工具函数，确保模块化和独立性。
  3. 没有任何跨模块的依赖，确保代码的清晰和可维护性。
  4. 只共享最基础的类型定义和工具函数，确保模块之间的解耦。

这样的结构确保每个预览模式都是完全独立的功能模块，每个模块有自己的组件、状态管理、样式和工具函数，没有任何跨模块的依赖，只共享最基础的类型定义和工具函数。