SmartisanNote.Remake/IFLOW.md

SmartisanNote.vue 项目概览

项目简介

这是一个基于 Vue 3 和 Vite 构建的单页 Web 应用（SPA），旨在模仿锤子科技（Smartisan）的便签应用。该项目使用 localStorage 进行本地数据持久化，支持便签的增删改查、文件夹管理、便签置顶、星标标记、基础设置（如云同步、深色模式）以及丰富的交互功能。

技术栈

• 核心框架: Vue 3 (Composition API)
• 构建工具: Vite
• 路由管理: vue-router
• 状态管理: Pinia (Vue 3 状态管理库)
• UI 库: 原生 CSS，使用了锤子便签的经典配色方案（定义在 index.html 的 CSS 变量中）
• 移动端支持: Capacitor (用于构建 Android/iOS 应用)
• 样式预处理器: Less
• 代码语言: JavaScript (ES6+)
• UI 组件库: Ionic Framework
• 日期处理: moment.js

项目结构

.
├── android/                 # Capacitor Android 项目文件
├── dist/                    # 构建后的生产文件
├── node_modules/            # 项目依赖
├── public/                  # 静态资源目录
├── src/
│   ├── common/              # 全局样式和通用工具
│   ├── components/          # 可复用的 Vue 组件 (Header, NoteItem, FolderItem)
│   ├── pages/               # 页面级别的 Vue 组件 (NoteList, NoteEditor, Folder, Settings)
│   ├── stores/              # Pinia 状态管理 stores
│   │   └── useAppStore.js   # 全局状态管理 store
│   ├── utils/               # 工具函数
│   │   ├── dateUtils.js     # 日期处理工具，基于 moment.js
│   │   └── storage.js       # localStorage 封装，负责数据的读写
│   ├── App.vue              # 根组件
│   └── main.js              # 应用入口，初始化路由、Pinia 和挂载
├── index.html               # HTML 模板，包含 CSS 变量定义
├── package.json             # 项目元数据和脚本命令
├── vite.config.js           # Vite 构建配置
└── capacitor.config.json    # Capacitor 配置文件

开发与构建命令

• 安装依赖: npm install
• 启动开发服务器: npm run dev
  • 默认端口: 3000
  • 基于 Vite，支持热更新。
• 构建生产版本: npm run build
  • 使用 Vite 构建，并同步到 Capacitor 项目 (npx cap sync)。
• 构建所有版本: npm run build:all
  • 构建标准版本和 PWA 版本
• 部署PWA版本: npm run deploy:pwa
  • 构建并部署PWA版本到FTP服务器
• 在 Android 设备上运行: npm run android
  • 需要预先配置好 Android 开发环境。

核心功能

便签管理

• 增删改查: 支持创建、查看、编辑和删除便签
• 星标标记: 可以将重要便签标记为星标便签
• 置顶功能: 支持将便签置顶显示在列表顶部
• 图片标记: 可以标记便签中是否包含图片
• 滑动删除: 支持右滑显示删除按钮，带有阻尼效果的交互体验
• 富文本编辑: 支持加粗、居中、待办事项、列表、标题、引用等格式

文件夹管理

• 分类组织: 支持创建文件夹对便签进行分类管理
• 默认文件夹: 提供"全部便签"、"加星便签"、"回收站"等默认文件夹

搜索功能

• 全文搜索: 支持按标题和内容搜索便签
• 实时过滤: 搜索结果实时更新

设置功能

• 云同步: 支持云同步设置（待实现）
• 深色模式: 支持深色模式切换（待完善）

日期时间处理

• 智能格式化: 根据时间范围自动格式化日期显示
• 多场景适配: 不同页面使用不同的日期格式化规则
• 本地化支持: 支持中文日期格式显示

代码规范与开发约定

• 状态管理: 使用 Pinia 进行全局状态管理，通过 useAppStore composable 函数访问状态。
• 数据持久化: 所有数据（便签、文件夹、设置）均通过 src/utils/storage.js 与 localStorage 进行交互。
• 路由: 使用 vue-router 和 createWebHashHistory 进行前端路由管理。
• UI 风格: 颜色方案严格遵循 index.html 中定义的 CSS 变量，以保持锤子便签的视觉风格。
• 组件组织: 页面组件 (pages/) 和可复用组件 (components/) 分离，结构清晰。
• 代码风格: 采用标准的 Vue 3 Composition API 写法，使用 ES6 模块系统 (import/export)。
• 日期处理: 使用 moment.js 进行日期处理，通过 src/utils/dateUtils.js 统一管理日期格式化逻辑。

样式

• 全局样式文件是位于 common/ 目录下的 base.css。
• 使用 Codefun 原子类样式，用于快速布局。
• 样式规范应遵循项目中已有的风格。
• 使用 Less 作为 CSS 预处理器。

JavaScript

• 严格遵循ES6规范。
• 遵循JavaScript函数式编程范式。
• 方法类函数应该使用 function 进行定义。
• 避免出现超过4个以上的 ref，超过4个则使用 reactive。
• 全局变量都集中放置于代码顶部。
• 变量名使用小驼峰命名法。
• 常量名使用全大写。
• 状态类变量命名参考 isLogin、isOpen。
• 事件类方法命名参考 onClick、onSelect。
• 变量都应该写有注释说明、类型说明。
• Promise 方法使用 async await 写法，并进行容错处理。
• 字符串拼接使用ES6的模板语法。
• JavaScript规范应遵循项目中已有的风格。

组件

• 全局组件放在 components/ 目录下。
• 页面独立组件放在页面根目录下的 components/。
• 每个组件应该附带 README.MD 文档。
• 组件编写应遵循项目中已有的风格。

Header 组件

• 动态按钮: 根据页面状态显示不同的操作按钮（新建、保存、插入图片）
• 文件夹管理: 支持文件夹展开/收起功能

NoteItem 组件

• 滑动交互: 支持右滑显示删除按钮，带有阻尼效果
• 状态切换: 支持星标和置顶状态的切换
• 视觉反馈: 滑动时便签夹会切换状态，提供直观的交互反馈
• 日期显示: 显示格式化后的便签更新时间

RichTextEditor 组件

• 富文本编辑: 支持多种文本格式（加粗、居中、待办事项、列表、标题、引用）
• 图片插入: 支持插入图片功能
• 工具栏: 提供浮动工具栏，支持格式化操作

页面

• 页面使用 Composition API (setup语法糖) 编写。
• 注释、结构规范应遵循项目中已有的风格。

NoteListPage

• 便签列表: 显示所有便签，支持置顶便签优先显示
• 文件夹管理: 支持文件夹的展开和切换
• 搜索功能: 提供便签搜索功能
• 交互反馈: 显示便签总数和置顶便签数量
• 智能日期显示: 根据时间范围显示不同的日期格式
  • 今天：显示为 "今天 下午 4:00"
  • 昨天：显示为 "昨天 下午 4:00"
  • 超过两天但小于一周：显示为 "星期一 10/8 上午 3:00"
  • 超过一周但小于一年：显示为 "10天前 9/20 下午 2:00"
  • 超过一年：显示为 "635天前 2024/8/10 上午 9:00"

NoteEditorPage

• 编辑模式: 支持新建和编辑便签
• 富文本编辑: 集成RichTextEditor组件，支持丰富的文本格式
• 图片插入: 支持通过工具栏插入图片
• 状态管理: 根据路由参数判断是新建还是编辑模式
• 智能日期显示: 根据时间范围显示不同的日期格式
  • 今天：显示为 "今天 下午 4:00"
  • 昨天：显示为 "昨天 下午 4:00"
  • 超过两天但小于一个月：显示为 "10/8 上午 3:00"
  • 超过一个月：显示为 "2024/8/10 上午 9:00"

状态管理 (Pinia)

项目现在使用 Pinia 作为状态管理解决方案，主要特点包括：

• Store 定义: 在 src/stores/useAppStore.js 中定义了全局状态 store
• 状态结构: 包含 notes、folders 和 settings 三个主要状态
• Getters: 提供了计算属性如 starredNotesCount 和 allNotesCount
• Actions: 包含所有状态变更操作，如 addNote、updateNote、deleteNote 等
• 数据持久化: 通过 storage.js 工具函数与 localStorage 进行数据交互
• Mock 数据: 支持加载预设的 mock 数据用于开发和演示
• 使用方式: 在组件中通过 const store = useAppStore() 来访问状态和方法

新增功能特性

滑动交互

• 阻尼效果: 右滑超过阈值后提供阻尼效果，增强交互体验
• 状态切换: 滑动时便签夹会切换到展开状态，松开后根据位置决定是否保持展开
• 视觉反馈: 滑动过程中提供实时视觉反馈

Mock 数据

• 自动加载: 当检测到无数据时自动加载预设的 mock 数据
• 手动加载: 可通过 URL 参数 ?mock=true 强制加载 mock 数据
• 丰富内容: 包含多种类型的便签、文件夹和设置示例
• 固定日期: 使用固定的日期值确保数据一致性

增强的便签功能

• 置顶支持: 便签可以置顶显示在列表顶部
• 图片标记: 可以标记便签是否包含图片
• 排序优化: 置顶便签优先显示，按更新时间排序

PWA 支持

• 离线使用: 支持构建PWA版本，可离线使用
• 自动部署: 支持一键构建并部署到FTP服务器

智能日期处理

• 统一管理: 通过 dateUtils.js 统一管理所有日期处理逻辑
• 多格式支持: 支持多种日期格式化方式以适应不同场景
• 本地化显示: 支持中文友好的日期时间显示
• 场景适配: 不同页面使用最适合的日期格式化规则