支持 Markdown 语法，拖拽或粘贴图片可自动上传

# Markdown Note System 设计文档 ## 1. 项目概述 Markdown Note System 是一个基于 Flask 框架实现的轻量级笔记管理系统，主要特点包括： - **文件存储模式**：不依赖传统数据库，所有项目数据都存储在文件系统中，以 JSON 文件保存项目元数据和 Markdown 文件存储笔记内容。 - **Markdown 编辑与展示**：笔记内容采用 Markdown 格式存储与展示，并使用 Bootstrap 卡片组件进行美化。 - **图片管理**：支持图片的上传、删除、复制链接与图库展示，图片数据统一存储在 `data/images.json` 文件中。 - **数据完整性校验**：通过 SHA256 为笔记生成哈希，在保存笔记时进行校验，防止数据被篡改。 - **前后端分离**：前端通过 Jinja2 模板渲染页面，并利用 RESTful API 与后端交互，支持项目创建、笔记管理、项目导入和下载压缩包等功能。 - **自动备份**：前端使用 localStorage 自动备份编辑中的笔记，减少意外丢失。 --- ## 2. 系统架构 ### 2.1 后端架构 - **Flask 应用** 使用 Flask 作为 Web 框架，并定义了全局配置（如数据存储根目录 `DATA_DIR`），通过 `app.py` 中的各个路由处理不同的 URL 请求。 - **数据存储模式** - 每个项目在 `data` 目录下拥有一个单独的子目录，其中包含 `metadata.json` 和对应的各个笔记 Markdown 文件。 - 图片相关数据统一存储于 `data/images.json` 文件中。 - 存储和数据读取均使用 JSON 文件和标准文件 IO 操作，简单高效。 ### 2.2 前端交互 - **模板与布局** 使用 Jinja2 作为模板引擎，各页面通过继承 `base.html` 模板实现统一布局，集成了 Bootstrap 5 实现响应式设计。 - **编辑与预览** - 编辑页面（`note_edit.html`）集成了 SimpleMDE Markdown 编辑器，实现拖拽、粘贴图片上传功能以及自动备份、字符统计等功能。 - 预览页面（`note_preview.html`）将 Markdown 内容通过 `markdown.markdown` 转换成 HTML，并封装在 Bootstrap 卡片中，同时支持导出为图片或 PDF 格式。 - **用户交互** 使用 SweetAlert2 弹窗实现提示、确认、错误信息展示，使操作更加直观和友好。 - **图形效果** 集成了 Fancybox 用于图库展示，并且 MathJax 用于公式的动态渲染。 --- ## 3. 数据模型与模块设计 ### 3.1 项目与笔记存储（Storage 类） - **目录结构** 每个项目对应一个子目录，目录中包含： - `metadata.json`：记录项目 ID、名称、创建和更新时间、笔记信息和图片数据。 - 多个 Markdown 文件，文件名即为笔记 ID，保存笔记内容。 - **主要方法** - `get_projects()` 遍历数据目录，加载每个项目的元数据并将相关时间字段格式化为 datetime 对象。 - `create_project(name)` 根据项目名称生成唯一的项目 ID，创建对应目录，并写入基础元数据。 - `get_project(project_id)` 读取指定项目的 `metadata.json`，同时对笔记列表中的时间字段进行转换排序。 - `create_note(project_id, title)` 在项目中创建新笔记，初始内容为 “# New Note\nStart writing here...”，并计算内容哈希，更新项目元数据。 - `update_note(project_id, note_id, title, content)` 更新对应笔记文件的内容，重设标题、更新时间和内容哈希，然后保存变更到 `metadata.json`。 - `_save_project_meta(project_id, metadata)` 辅助方法，用于保存项目的元数据。 ### 3.2 图片管理（ImageStorage 类与 Image 类） - **图片数据封装** `Image` 类封装了图片的 ID、文件名、访问 URL 及上传时间，提供 `to_dict()` 方法便于序列化。 - **图片存储** `ImageStorage` 类处理图片数据的读取和写入，默认将数据保存到 `data/images.json` 文件中： - `get_all_images()`：读取所有图片记录。 - `add_image(image_dict)`：将新图片记录追加到现有列表后保存到文件中。 --- ## 4. RESTful API 接口 后端提供了一系列 API 接口，方便前端进行项目、笔记、图片等操作，其主要分类如下： ### 4.1 Project 接口 - **创建项目** `POST /api/projects` 前端传入项目名称；后端生成项目目录与元数据，并返回 JSON 格式的项目数据。 - **删除项目** `DELETE /api/projects/<project_id>` 删除项目目录及其所有内容，返回操作结果。 - **导入项目** `POST /api/projects/import` 支持上传项目压缩包，后端解压后重写元数据（重置项目 ID 和时间），完成项目导入。 - **项目下载** `GET /api/projects/<project_id>/download_zip` 将项目目录打包成 ZIP 文件，供用户下载项目数据。 ### 4.2 Note 接口 - **创建笔记** `POST /api/projects/<project_id>/notes` 根据传入标题创建新笔记，写入磁盘，并更新项目的 `metadata.json`。 - **更新笔记** `PUT /api/projects/<project_id>/notes/<note_id>` 保存笔记内容和标题，重新计算内容哈希，更新笔记对应的元数据。 - **删除笔记** `DELETE /api/projects/<project_id>/notes/<note_id>` 删除笔记 Markdown 文件，并从项目元数据中移除记录。 - **移动笔记** `PUT /api/projects/<project_id>/notes/<note_id>/move` 支持笔记在项目之间的转移，通过文件重命名和更新各自项目的元数据实现。 - **验证笔记完整性** `GET /api/projects/<project_id>/notes/<note_id>/verify` 对比当前笔记内容的 SHA256 哈希和存储时的哈希，判断数据是否被篡改。 - **笔记下载** `GET /api/projects/<project_id>/notes/<note_id>/download` 使用 Flask 的 `send_file` 接口发送指定笔记的 Markdown 文件。 ### 4.3 Image 接口 - **上传图片** `POST /api/upload_image` 处理图片上传请求，读取文件内容计算哈希值确保唯一性，然后存储图片到 `static/uploads` 目录下，返回图片 URL 及 Markdown 嵌入格式。 - **删除图片** `DELETE /api/images/<image_id>` 根据图片 ID 删除服务器中的图片文件，并更新 `images.json` 文件中的记录。 ### 4.4 Gallery 页面 - **展示图库** `GET /gallery` 获取所有图片数据并渲染图库页面，前端支持图片预览、复制链接和删除操作。 --- ## 5. 安全性与扩展性 ### 5.1 数据完整性与安全性 - **哈希校验** 每次笔记更新时使用 SHA256 算法计算内容哈希，后续通过 `/verify` 接口校验，防止笔记内容被恶意篡改。 - **文件操作安全** 对文件读写操作进行了异常捕获，保证数据的稳定性和完整性。 ### 5.2 自动备份机制 - 前端在笔记编辑页面中集成了基于 localStorage 的自动备份，每隔一定时间自动保存当前编辑内容，出现意外关闭时可提示用户恢复备份内容。 ### 5.3 前后端分离与模块化设计 - **RESTful API** 前后端分离的设计使得各模块功能独立，利于后续扩展与维护。 - **模块化开发** 项目、笔记、图片等各个功能模块均有独立的实现，通过面向对象设计解耦业务逻辑，便于新增功能和修改现有功能。 --- ## 6. 总结 Markdown Note System 以轻量级架构和文件系统数据管理方式，实现了简洁高效的笔记管理、图片上传与展示、数据完整性校验和自动备份功能。前后端采用 RESTful 模式配合 Jinja2 模板进行页面渲染，同时集成 SimpleMDE、SweetAlert2、Fancybox、MathJax 等前端组件，提供直观友好的用户体验。系统设计充分体现了“简洁、自由、扩展性高”的开发理念，便于后续二次开发和功能拓展。

笔记ID：7dcb8f8f-3dcb-40e3-8553-dcc6280f8893

上次保存哈希：a17b2c1d49f185459f58050df8305e1643f79fded95e9783ce518c7d88f35f5e

检测是否篡改