390 lines
18 KiB
Markdown
390 lines
18 KiB
Markdown
# WriteFlow 开发提示词（迭代式开发指南）
|
||
|
||
> 本指南基于 [README.md](./README.md) 与 [产品策划开发手册](./产品策划开发手册.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。祝开发顺利！ |