SmartisanNote.Remake/IFLOW.md

SmartisanNote.Remake - IFLOW 上下文

项目概述

这是一个基于 Vue 3、Vite 和 Pinia 的移动端现代化 Web 应用，旨在重现并改进经典的锤子便签应用体验。该项目采用 PWA（渐进式 Web 应用）技术，支持离线使用和安装到主屏幕。

主要技术栈

• 框架: Vue 3 (Composition API)
• 构建工具: Vite
• 状态管理: Pinia
• 路由: Vue Router
• UI 组件库: Ionic Vue (部分使用)
• PWA 支持: vite-plugin-pwa
• 本地存储: IndexedDB (通过 src/utils/indexedDBStorage.js 封装)
• CSS 预处理器: Less
• 动画库: @oku-ui/motion
• 拖拽库: vue-draggable-plus

项目结构

.
├── android/         # Capacitor Android 项目文件
├── public/          # 静态资源目录 (图标等)
│   ├── assets/      # 应用资源文件
│   │   └── icons/   # 图标文件
│   │       ├── drawable-xxhdpi/  # Android 图标资源
│   │       └── drawable-xxxhdpi/ # Android 图标资源
│   └── icons/       # PWA 图标
│       ├── icon-192.png
│       └── icon-512.png
├── src/             # 源代码目录
│   ├── App.vue      # 根组件
│   ├── main.js      # 应用入口文件
│   ├── common/      # 通用样式
│   │   └── base.css # 基础样式文件
│   ├── components/  # 可复用的 UI 组件
│   │   ├── FolderItem.vue      # 文件夹项组件
│   │   ├── FolderManage.vue    # 文件夹管理组件
│   │   ├── Header.vue          # 头部组件
│   │   ├── Modal.vue           # 模态框组件
│   │   ├── NoteItem.vue        # 便签项组件
│   │   ├── RichTextEditor.vue  # 富文本编辑器组件
│   │   ├── Search.vue          # 搜索组件
│   │   ├── SettingGroup.vue    # 设置组组件
│   │   └── SwitchButton.vue    # 开关按钮组件
│   ├── pages/       # 页面组件
│   │   ├── FolderPage.vue      # 文件夹页面
│   │   ├── NoteEditorPage.vue  # 便签编辑页面
│   │   ├── NoteListPage.vue    # 便签列表页面
│   │   └── SettingsPage.vue    # 设置页面
│   ├── stores/      # Pinia 状态管理
│   │   ├── useAppStore.js      # 应用状态管理
│   │   └── useAppStore.test.js # 应用状态管理测试
│   └── utils/       # 工具函数
│       ├── dateUtils.js        # 日期工具函数
│       └── indexedDBStorage.js # IndexedDB 存储封装
├── index.html       # 应用入口 HTML 文件
├── .nvmdrc          # node.js 版本
├── package.json     # 项目依赖和脚本
├── vite.config.js   # Vite 配置文件
└── capacitor.config.json # Capacitor 配置文件

核心功能

• 便签管理: 创建、编辑、删除、置顶、加星便签。
• 文件夹管理: 将便签分类到不同的文件夹中。
• 搜索功能: 按标题或内容搜索便签。
• 回收站: 临时存储已删除的便签，支持彻底删除。
• 多种排序方式: 按更新时间、标题、星标状态排序。
• PWA 支持: 可安装为独立应用，支持离线使用。
• 本地存储: 所有数据存储在浏览器的 IndexedDB 中。
• 富文本编辑: 支持标题、待办事项、列表、加粗、引用、图片等多种格式。
• 动画效果: 使用 Oku Motion 实现流畅的动画效果。
• 拖拽排序: 支持图片拖拽排序。
• 深色模式: (计划中) 支持切换深色/浅色主题。
• 云同步: (计划中) 支持多设备间数据同步。

开发与构建

前置条件

确保已安装 Node.js (>=14) 和 npm。

安装依赖

npm install

开发

启动开发服务器:

npm run dev

这将在 http://localhost:3000 启动应用。

构建

构建标准 Web 应用:

npm run build

构建 PWA 应用:

npm run build:pwa

构建所有版本 (标准 + PWA):

npm run build:all

部署 PWA

构建 PWA 并上传到服务器:

npm run deploy:pwa

这将执行 vite build --mode pwa 并运行 upload-pwa.js 脚本。

Android 应用

运行 Android 应用:

npm run android

代码规范与约定

代码风格与结构

• 框架: Vue 3 (Composition API) 与 Pinia 状态管理
• 构建工具: Vite
• 路由: Vue Router
• UI 组件库: Ionic Vue (部分使用)
• PWA 支持: vite-plugin-pwa
• 本地存储: IndexedDB (通过 src/utils/indexedDBStorage.js 封装)
• CSS 预处理器: Less
• CSS 命名: 使用 BEM 命名规范，部分使用原子化 CSS 类名（以 code-fun- 开头）
• 响应式设计: 使用 viewport 单位 (vw/vh) 和 CSS 变量实现响应式布局
• 图标: 使用 PNG 图片作为图标，存储在 public/assets/icons/ 目录下
• 动画: 使用 Oku Motion 实现动画效果
• 拖拽: 使用 vue-draggable-plus 实现拖拽功能

命名规范

• 文件命名:
  • 组件文件使用 PascalCase 命名法，如 NoteItem.vue
  • 页面文件使用 PascalCase 命名法，如 NoteListPage.vue
  • 工具文件使用 camelCase 命名法，如 dateUtils.js
  • Store 文件使用 use 前缀 + PascalCase 命名法，如 useAppStore.js
• 组件命名: 使用 PascalCase 命名法，如 NoteItem
• 变量命名: 使用 camelCase 命名法，如 noteToDelete
• 常量命名: 使用 UPPER_SNAKE_CASE 命名法，如 NOTES_KEY
• 函数命名: 使用 camelCase 命名法，如 handleNotePress

代码组织

• 组件结构:
  • 使用 <template>, <script setup>, <style> 三段式结构
  • 计算属性 (computed) 置于响应式数据之后
  • 方法 (methods) 置于计算属性之后
  • 生命周期钩子 (onMounted, onUnmounted 等) 置于方法之前
  • 样式使用 Less 预处理器，并使用 scoped 属性避免样式污染
• 状态管理:
  • 使用 Pinia 进行全局状态管理
  • Store 文件中按照 state, getters, actions 的顺序组织代码
  • 异步操作使用 async/await 语法
• 工具函数:
  • 工具函数按功能模块划分文件，如 indexedDBStorage.js, dateUtils.js
  • 工具函数使用 export const 导出

注释规范

• 单行注释: 使用 // 进行单行注释，注释应位于代码上方或行尾
• 多行注释: 使用 /* */ 进行多行注释，用于解释复杂逻辑
• 函数注释: 使用 JSDoc 格式为函数添加注释，包含函数描述、参数类型和返回值类型

代码提交规范

• 提交信息应清晰描述变更内容，如 修复 搜索功能空值检查 或 新增 删除按钮功能。
• 对于功能性的新增或修改，使用 新增 前缀。
• 对于错误修复，使用 修复 前缀。
• 对于性能优化、代码重构（既不修复错误也不添加功能），使用 优化 前缀。
• 对于文档更新，使用 文档 前缀。
• 提交信息应使用中文。