SparksFly
/
learning-rust
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
learning-rust/tauri-app/开发迭代计划.md

18 KiB
Raw Blame History

WriteFlow 开发提示词（迭代式开发指南）

本指南基于 README.md 与 产品策划开发手册 制定，采用增量迭代方式推进。每个阶段均有明确的交付物、技术要点、验收标准，确保代码质量、功能完整性和用户体验一致性。
UI 开发必须遵循 /ui-ux-pro-max 规范（即符合产品设计原则、使用 Naive UI 组件库、响应式布局、暗色/亮色主题无缝切换）。

总体开发原则

  1. 本地优先，数据安全：所有笔记以 .md 文件存储于本地，同步仅作为附加能力，不得破坏本地数据。
  2. 所见即所得为核心体验：编辑器必须达到 Typora 级别的流畅度和渲染效果。
  3. 渐进增强：先保证核心编辑与文件管理可用，再叠加同步、高级功能。
  4. 跨平台一致性：在 Windows/macOS/Linux 上行为一致，UI 适配各平台习惯（如菜单栏、快捷键）。
  5. 代码规范：
    • 前端：TypeScript + ESLint + Prettier（Vue 官方风格指南）
    • 后端：Rust 1.70+，遵循 Rustfmt + Clippy，模块化设计，错误处理清晰。
  6. 测试覆盖：关键路径（文件读写、同步、冲突处理）必须有单元测试和集成测试。
  7. 性能目标：冷启动 < 2s，打开 1000 行文件 < 500ms，空闲内存 < 100MB。

Phase 1 – MVP 基础编辑器（8 周）

目标：提供可用的本地 Markdown 所见即所得编辑器，包含文件管理、基础主题、导出 HTML/PDF。
UI/UX 依据：设计规范第 6 章（沉浸优先、无干扰、反馈及时），使用 Naive UI 组件（布局、按钮、弹窗、消息提示）。

迭代 1.1 – 项目骨架与编辑器内核（W1）

任务清单

  • 初始化 Tauri + Vue 3 + TypeScript 项目
    • 使用 create-tauri-app 选择 Vue 3 + TypeScript。
    • 配置 vite.config.ts，启用别名 @ 指向 src。
    • 安装依赖：naive-ui、milkdown（含 @milkdown/vue）、@milkdown/theme-nord（或其他主题）、@milkdown/preset-commonmark。
  • 集成 Milkdown 编辑器组件
    • 在 App.vue 或独立 Editor.vue 中挂载 Milkdown 编辑器。
    • 配置基本 CommonMark 预设，实现标题、加粗、斜体、列表、引用、代码块、链接、图片、表格（基础）的实时渲染。
    • 关闭 Milkdown 的工具栏，实现纯键盘驱动的所见即所得（光标所在行自动隐藏标记符号）。
  • 实现自定义标题栏（无系统边框）
    • 修改 tauri.conf.json："windows" 配置 "decorations": false。
    • 在 Vue 中绘制标题栏，包含应用 Logo、标题（当前文件名）、窗口控制按钮（最小化、最大化、关闭）。
    • 实现窗口拖拽区域：使用 Tauri data-tauri-drag-region 属性。
  • 基础的亮色/暗色主题
    • 定义 CSS 变量（色值参考设计规范 6.4）。
    • 提供顶部菜单或设置项切换主题，利用 Naive UI 的 n-config-provider 配合自定义类。

关键技术点

  • Milkdown 编辑器的 editor 实例管理（通过 ref 获取，用于后续内容读写）。
  • Tauri 的 window API 控制窗口大小和位置。
  • 使用 @tauri-apps/api/event 监听系统主题变更（可选）。

验收标准

  • 启动后编辑器可输入，Markdown 语法正确渲染。
  • 标题栏可拖拽移动窗口，控制按钮功能正常。
  • 主题切换后编辑器背景、文字、边框颜色同步变化。
  • 无控制台报错，内存占用 < 50MB（空文档）。

迭代 1.2 – 文件系统集成（W2–W3）

任务清单

  • 实现文件树侧边栏
    • 使用 Naive UI 的 n-tree 组件，绑定目录结构数据。
    • 通过 Tauri fs 模块（read_dir）递归读取工作区目录。
    • 支持展开/折叠文件夹，点击 .md 文件在编辑器中打开。
  • 新建/打开/保存文件
    • 新建：生成 untitled.md，弹窗让用户重命名（或自动生成时间戳文件名）。
    • 打开：使用 dialog.open() 选择 .md 文件，读取内容并渲染。
    • 保存：使用 fs.writeFile()，支持 Ctrl+S 快捷键，同时自动保存到当前文件。
  • 最近打开文件列表
    • 使用 localStorage 或 Tauri store 插件存储最近 10 个文件路径。
    • 在菜单或侧边栏显示快速入口。
  • 工作区管理（单工作区 MVP）
    • 首次启动引导用户选择笔记目录（dialog.open({ directory: true })）。
    • 将路径持久化（store 或配置文件），后续启动自动加载该目录。

技术要点

  • 文件读写使用 Tauri 的 tauri::fs 和 tauri::dialog 模块，注意权限配置（capabilities）。
  • 文件树数据使用 ref 响应式，结合 watch 监听目录变更（后续可升级为 notify 后端监听）。
  • 编辑器内容与文件路径双向绑定：打开文件 → 设置 editor 内容，保存时读取 editor 内容写入文件。

验收标准

  • 文件树正确显示目录及 .md 文件，点击文件立即在编辑器中打开。
  • 新建文件后保存，文件出现在文件树中。
  • 最近文件列表正确记录，重启后依然存在。
  • 打开非文本文件或非 MD 文件时，给出友好提示。

迭代 1.3 – 编辑体验增强（W4）

任务清单

  • 自动保存与手动保存状态
    • 每隔 30 秒自动保存当前文件（若有更改）。
    • 状态栏显示“已保存”或“正在保存...”图标（Naive UI n-icon）。
  • 快捷键体系（核心）
    • Ctrl+N 新建，Ctrl+O 打开，Ctrl+S 保存，Ctrl+Shift+S 另存为。
    • Ctrl+Z/Ctrl+Y 撤销/重做（Milkdown 内置）。
    • Ctrl+F 查找（后续迭代）。
    • 使用 Tauri globalShortcut 或前端 @vueuse/core 的 useMagicKeys。
  • 字数统计与文档信息
    • 状态栏显示当前文档字数（中英文混合计数）、行数、光标位置。
    • 使用 @milkdown/utils 的 prose 或自行解析 AST 统计。
  • 焦点模式（可选）
    • 快捷键 F11 或菜单切换：隐藏侧边栏，编辑器全屏。
    • 使用 CSS 动画过渡，保持平滑。

UI/UX 规范检查

  • 状态栏位于底部，信息左对齐，同步状态（尚无）预留位置。
  • 快捷键提示可悬浮显示（使用 n-tooltip）。

验收标准

  • 自动保存生效，关闭窗口或切换文件时不丢失编辑内容。
  • 核心快捷键全平台（Win/Cmd 适配）正常。
  • 字数统计准确（英文单词、中文字符、总字符）。
  • 焦点模式切换流畅，无闪烁。

迭代 1.4 – 主题与导出（W5–W6）

任务清单

  • 完整的亮色/暗色主题切换
    • 提供至少三种配色：默认亮色、默认暗色、Sepia（暖色）。
    • 使用 Naive UI 的 n-config-provider 全局管理主题，同时自定义编辑器样式（Milkdown 的样式覆盖）。
  • 导出 HTML
    • 将当前 Markdown 内容转换为 HTML（可借助 Milkdown 的 getMarkdown + markdown-it 或直接使用 Milkdown 渲染结果）。
    • 打包为一个自包含的 .html 文件（含样式），通过 Tauri dialog.save() 选择保存位置。
  • 导出 PDF
    • 方案一：使用 window.print() 配合 @media print 样式实现打印为 PDF（跨平台简单）。
    • 方案二：使用 Rust 后端（printpdf）生成 PDF，更专业但复杂度高。MVP 采用方案一，后续替换。
    • 导出前确保样式一致（保留主题）。
  • 设置存储
    • 使用 Tauri store 插件（或 confy crate）保存用户偏好：主题、最近工作区、自动保存间隔等。

技术要点

  • 导出 HTML 时，需内联主题 CSS 和 Milkdown 渲染样式，确保外部打开显示正常。
  • PDF 导出使用 Tauri 的 WebviewWindow 的 print 方法或调用系统打印对话框。

验收标准

  • 三种主题切换后，编辑器、侧边栏、状态栏颜色同步。
  • 导出 HTML 文件，在浏览器中打开与编辑器内显示一致。
  • 导出 PDF 内容完整，中文不乱码，图片（若有）正常显示。
  • 用户设置（主题、最近工作区）在重启后保留。

迭代 1.5 – 错误处理与基础测试（W7–W8）

任务清单

  • 全局错误处理
    • 前端：Vue 全局错误处理器（app.config.errorHandler）捕获并显示友好提示（n-notification）。
    • Rust：使用 anyhow 或自定义错误类型，Tauri Command 返回 Result，错误信息通过 invoke 传递到前端。
  • 文件操作异常场景
    • 文件被外部修改（只读、删除）时的提示。
    • 磁盘空间不足、权限错误等提示。
  • 单元测试（Rust）
    • 文件读写函数、Hash 计算、路径处理等工具函数。
    • 使用 cargo test，覆盖率 > 70%。
  • 前端单元测试（Vitest）
    • 测试文件树组件、编辑器组件（通过 Mock 编辑器 API）。
  • E2E 测试（Playwright）
    • 核心路径：启动 → 新建文件 → 输入内容 → 保存 → 重新打开 → 内容一致。
    • 导出 HTML 和 PDF 可验证文件生成。

验收标准

  • 所有错误场景有对应的用户提示，不崩溃。
  • 单元测试全部通过。
  • E2E 测试通过。
  • 打包后的应用在 Windows/macOS/Linux 上可运行（基础功能）。

Phase 1 交付物

  • 可安装的桌面应用（.msi/.dmg/.AppImage）。
  • 源码仓库，包含完整的开发文档（README、CONTRIBUTING）。
  • 项目网站（VitePress）上线，包含下载链接和用户手册。

Phase 2 – S3 同步引擎（6 周）

目标：实现基于 S3 协议的云端同步，支持手动/自动同步、冲突检测、图片上传。

迭代 2.1 – S3 连接层（W9–W10）

任务清单

  • 添加 Rust S3 客户端
    • 依赖 aws-sdk-s3 或 rust-s3，实现 SyncProtocol trait（参考设计文档 8.4）。
    • 实现 connect、list_files、upload、download、delete、get_metadata 方法。
  • 凭据安全存储
    • 使用 keyring crate（macOS/Windows/Linux 统一）或 Tauri 的 store 加密存储 AccessKey/SecretKey。
    • 前端提供配置表单（Endpoint、Bucket、Region、AccessKey、SecretKey），通过 Tauri Command 保存。
  • 连接测试
    • 提供“测试连接”按钮，验证凭据是否正确，Bucket 是否可访问。

技术要点

  • 使用 async/await，超时控制（tokio::time::timeout）。
  • 处理 S3 的路径前缀（prefix）作为远程目录。

验收标准

  • 配置正确的 S3 信息后，测试连接成功。
  • 凭据加密存储，无法在明文配置文件中读取。
  • 列出远程文件（含前缀）正常。

迭代 2.2 – 同步核心（W11）

任务清单

  • 计算文件 Hash
    • 使用 sha2 或 blake3 计算文件内容的哈希值。
    • 存储本地元数据：last_modified、hash、sync_status。
  • Diff 引擎
    • 对比本地文件、远程文件、上次同步基线（存储在本地 .writeflow/sync_meta.json）。
    • 分类：local_newer、remote_newer、both_changed（冲突）、identical。
  • 上传/下载执行
    • 实现批量上传（并发控制，避免过多连接）。
    • 实现增量下载（仅下载变更文件）。
    • 进度反馈：通过 Tauri 事件向前端发送进度信息（emit）。

技术要点

  • 使用 tokio 并发，控制并发数（如 5 个）。
  • 前端显示同步进度条（n-progress）。

验收标准

  • 本地新增文件 → 同步后出现在远程。
  • 远程新增文件 → 同步后下载到本地。
  • 本地文件修改 → 同步后远程更新。
  • 远程文件修改 → 同步后本地更新。

迭代 2.3 – 冲突处理与状态 UI（W12）

任务清单

  • 冲突检测与策略
    • 实现三种策略：keep_local、keep_remote、keep_both（默认）。
    • keep_both 生成 filename_conflict_YYYYMMDDHHMMSS.md。
  • 同步状态 UI
    • 状态栏显示同步状态（空闲、同步中、冲突、错误）。
    • 文件树中每个文件显示同步图标（绿勾、橙色感叹号、红色叉）。
    • 点击状态可查看详细信息（使用 n-drawer 或 n-modal）。
  • 手动/自动同步
    • 提供“立即同步”按钮。
    • 定时同步（可配置间隔，默认 5 分钟）。

验收标准

  • 两台设备修改同一文件，同步后生成冲突副本，原文件保留不丢失。
  • 状态指示器实时更新，冲突有明确提示。
  • 自动同步按设定间隔执行。

迭代 2.4 – 图片同步与首次配置向导（W13–W14）

任务清单

  • 图片自动上传
    • 监听编辑器中的图片插入（拖拽或粘贴），使用 Tauri fs 读取图片文件并上传至 S3。
    • 替换 Markdown 中的图片路径为相对路径（如 images/xxx.png），同时上传到远程对应路径。
  • 图片引用管理
    • 确保本地和远程图片目录结构一致。
  • 首次配置向导
    • 启动时检测是否已配置同步，若无则弹出向导（n-steps）。
    • 引导选择工作区、配置 S3 信息、测试连接。
  • 同步日志
    • 提供查看同步日志的界面（n-log 或 n-textarea），便于调试。

验收标准

  • 粘贴图片到编辑器，自动上传到 S3，并在本地生成相对路径引用。
  • 在另一设备同步后，图片正常显示。
  • 向导流程完整，可跳过或稍后配置。
  • 同步日志记录关键操作。

Phase 2 交付物

  • 完整的 S3 同步功能，支持公开云（AWS、阿里云等）和私有部署（MinIO）。
  • 冲突处理机制完善，数据安全有保障。

Phase 3 – 高级编辑功能（8 周）

目标：补齐 Typora 的高级能力，包括代码高亮、数学公式、图表、目录大纲、多种导出格式。

由于篇幅，此处仅列出关键迭代，细节可参考产品手册 4.3。

迭代 3.1 – 代码高亮与数学公式

  • 引入 Shiki（Rust 端可预高亮）或前端 prism.js 实现语法高亮。
  • 使用 KaTeX 渲染行内和块级公式。
  • 配置 Milkdown 插件：@milkdown/plugin-math（需等待适配）或自定义。

迭代 3.2 – Mermaid 图表与表格编辑器

  • 集成 Mermaid.js，在渲染阶段将代码块 mermaid 转换为 SVG。
  • 使用 Naive UI 的 n-table 构建可视化表格编辑器（弹窗形式），支持增删行列、对齐。

迭代 3.3 – 文档大纲与导航

  • 解析 Markdown 标题，在侧边栏或独立面板生成大纲树，点击跳转。
  • 使用 @milkdown/plugin-toc 或自行解析。

迭代 3.4 – 导出增强（PDF、Word、图片）

  • 替换 window.print() 为 Rust genpdf 或 html-to-pdf 引擎，提升 PDF 质量。
  • 集成 docx crate 或调用 Pandoc（需用户安装）导出 Word。
  • 导出为 PNG（截图）。

Phase 4 – 多协议同步（6 周）

目标：支持 WebDAV、Git、WebRTC 等协议，扩展同步场景。

每个协议作为一个独立迭代，实现相同的 SyncProtocol trait，复用核心引擎。

迭代 4.1 – WebDAV

  • 使用 reqwest 实现 PROPFIND、PUT、GET、DELETE。
  • 支持摘要认证和 OAuth2（如坚果云）。

迭代 4.2 – Git

  • 集成 git2-rs，实现 clone、pull、push、commit。
  • 提供版本历史查看（类似 Git 日志）。

迭代 4.3 – WebRTC

  • 使用 webrtc-rs 或通过 Tauri 调用前端 WebRTC，实现 P2P 直连同步。
  • 需要信令服务器（简单实现）。

Phase 5 – 体验打磨与生态（持续）

目标：多标签页、全文搜索、快捷键自定义、主题市场、插件系统。

迭代 5.1 – 多标签页

  • 使用 n-tabs 管理多个打开的文件，支持拖拽排序。
  • 每个标签页独立编辑器实例（或共享实例切换内容）。

迭代 5.2 – 全文搜索

  • 使用 tauri 后端遍历文件内容，结合 tantivy 或 ripgrep 实现高速搜索。
  • 前端结果列表，点击跳转并高亮匹配项。

迭代 5.3 – 快捷键自定义

  • 提供设置界面，使用 n-dynamic-tags 编辑快捷键映射。
  • 存储为 JSON，动态注册/注销。

迭代 5.4 – 插件系统

  • 基于 deno 或 quickjs 嵌入 JavaScript 引擎，允许用户编写插件扩展。
  • 提供插件 API（如 onSave、onRender）。

开发流程与质量保障

代码审查

  • 每次 PR 必须通过 CI（检查 lint、test、build）。
  • 至少一名 Reviewer 批准。

持续集成

  • GitHub Actions：
    • 前端 lint + test
    • Rust clippy + test
    • 构建 Tauri 应用（仅 PR 检查，不发布）

文档同步

  • 所有 API 变更更新 TSDoc/Rustdoc。
  • 用户手册同步更新（VitePress）。

附录：UI 开发规范（/ui-ux-pro-max）

  1. 使用 Naive UI 组件：优先使用 n-* 组件，避免自定义基础组件（除非必要）。
  2. 响应式适配：窗口缩放时编辑器宽度自适应，侧边栏可折叠。
  3. 暗色/亮色完全支持：所有颜色使用 CSS 变量，随主题切换。
  4. 交互反馈：操作成功/失败使用 n-message 或 n-notification，加载状态使用 n-spin。
  5. 可访问性：使用语义化标签，键盘导航（Tab 顺序合理）。
  6. 布局：遵循设计规范第 6 章，标题栏高度 32px，状态栏 28px，编辑器填充适当留白。

开始开发：请从 Phase 1 – 迭代 1.1 入手，完成后再推进后续。每个迭代完成后进行自测，并更新 CHANGELOG。祝开发顺利！