biji/doc/project_analysis.md

项目分析与发展规划

1. 项目概述

本项目是一个功能完善的全栈笔记应用，旨在为用户提供一个简洁、高效、安全的笔记管理平台。

• 核心功能: 支持Markdown笔记的创建、编辑、分组管理，并包含图片上传、回收站、用户认证和系统管理等功能。
• 技术架构: 采用主流的前后端分离架构。
  • 前端: 基于 Vue 3、Vite、Element Plus 和 Pinia 构建，实现了响应式和组件化的UI。
  • 后端: 基于 Java 17、Spring Boot 3 和 MyBatis-Plus 构建，提供稳定、高效的API服务，并使用 SQLite 作为数据存储，简化了部署。

2. 系统架构

graph TD
    subgraph 用户端
        A[浏览器]
    end

    subgraph 前端 (biji-qianduan)
        B[Vue 3 / Vite]
        C[Element Plus UI]
        D[Pinia 状态管理]
        E[Vue Router 路由]
        F[Axios API请求]
    end

    subgraph 后端 (biji-houdaun)
        G[Spring Boot 3]
        H[Spring Security]
        I[MyBatis-Plus]
        J[Knife4j API文档]
    end

    subgraph 数据层
        K[SQLite 数据库]
        L[文件存储 uploads]
    end

    A --> B
    B --> C
    B --> D
    B --> E
    B --> F
    F -- HTTP/S --> G
    G --> H
    G --> I
    G --> J
    I --> K
    G --> L

3. 前端架构分析

前端项目结构清晰，遵循了Vue生态的最佳实践。

graph TD
    subgraph 源码 (src)
        M[main.js] --> N[App.vue]
        M --> O[router/index.js]
        M --> P[stores/user.js]

        subgraph 页面与组件
            Q[components/HomePage.vue]
            R[components/LoginPage.vue]
            S[components/TrashPage.vue]
        end

        subgraph API
            T[api/CommonApi.js]
        end

        subgraph 工具
            U[utils/axios.js]
        end
    end

    N -- 路由视图 --> O
    O -- 定义路由 --> Q & R & S
    Q & R & S -- 使用 --> P
    Q & R & S -- 调用 --> T
    T -- 封装 --> U

• 核心页面:
  • HomePage.vue: 应用的主界面，集成了笔记列表、分类、预览、编辑和各种操作按钮，是功能最复杂的页面。
  • LoginPage.vue / RegisterPage.vue: 用户认证页面。
  • TrashPage.vue: 回收站页面，提供恢复和永久删除功能。
• 状态管理: stores/user.js 使用Pinia来管理用户的登录状态和信息，实现了全局共享。
• API请求: 所有后端请求都统一封装在 api/CommonApi.js 中，并通过 utils/axios.js 进行拦截和处理，便于统一管理。

4. 后端架构分析

后端采用经典的Spring Boot三层架构，逻辑清晰，易于维护。

graph TD
    subgraph API层
        V[UserController]
        W[MarkdownController]
        X[GroupingController]
        Y[ImageController]
        Z[TrashController]
    end

    subgraph 业务逻辑层
        AA[UserService]
        BB[MarkdownFileService]
        CC[GroupingService]
        DD[ImageService]
        EE[TrashService]
    end

    subgraph 数据访问层
        FF[UserMapper]
        GG[MarkdownFileMapper]
        HH[GroupingMapper]
        II[ImageMapper]
    end

    V --> AA
    W --> BB
    X --> CC
    Y --> DD
    Z --> EE

    AA --> FF
    BB --> GG
    CC --> HH
    DD --> II

• API接口: 通过分析Controller层，后端提供了以下几类核心接口：
  • 用户: 注册、登录、修改密码、删除用户。
  • 笔记: 创建、预览、更新、删除、按分组查询、搜索。
  • 分组: 创建、查询、更新、删除。
  • 图片: 上传、删除、预览。
  • 回收站: 查询、恢复、永久删除、清空。
  • 系统: 管理注册状态、生成注册码。

5. 核心业务逻辑

用户认证流程

sequenceDiagram
    participant User as 用户
    participant Frontend as 前端
    participant Backend as 后端
    participant JWT as JWT Util
    participant DB as 数据库

    User->>Frontend: 输入用户名和密码
    Frontend->>Backend: 发起登录请求 (/api/user/login)
    Backend->>DB: 查询用户信息
    DB-->>Backend: 返回用户信息
    Backend->>Backend: 验证密码
    alt 验证成功
        Backend->>JWT: 生成Token
        JWT-->>Backend: 返回Token
        Backend-->>Frontend: 返回Token
        Frontend-->>User: 登录成功，保存Token
    else 验证失败
        Backend-->>Frontend: 返回错误信息
        Frontend-->>User: 显示错误提示
    end

笔记与图片管理

flowchart TD
    A[用户在编辑器中操作] --> B{是新增/编辑笔记还是上传图片？}
    B -- 新增/编辑笔记 --> C[前端调用 /api/markdown/updateMarkdown]
    C --> D[MarkdownFileService 处理]
    D --> E[保存笔记内容到数据库]
    D -- 异步 --> F[提取图片链接，同步到ImageName表]

    B -- 上传图片 --> G[前端调用 /api/images 上传]
    G --> H[ImageService 处理]
    H --> I[图片保存到 uploads 目录]
    H --> J[图片信息存入数据库]
    J --> K[返回图片URL给前端]
    K --> A

回收站机制

• 软删除: 当用户删除笔记或分组时，后端服务（如 GroupingServiceImpl）并不会直接从数据库中物理删除记录，而是将 is_deleted 标志位置为 1，并记录删除时间 deleted_at。
• 恢复: TrashService 通过 restoreItem 方法，将对应记录的 is_deleted 标志位重置为 0。
• 永久删除: permanentlyDeleteItem 方法会从数据库中物理删除记录。

6. 后续规划：移动端适配与视觉美化

移动端页面布局 (手机端优先)

基于现有功能，移动端需要以下核心页面：

1. 主页 (Home):
   • 布局: 采用底部导航栏，包含“笔记”、“搜索”、“我的”三个Tab。
   • 笔记Tab: 以卡片流的形式展示笔记列表，支持下拉刷新和上拉加载。点击卡片进入笔记详情。
   • FAB (Floating Action Button): 用于快速创建新笔记。
2. 笔记详情/编辑页:
   • 布局: 顶部为标题和操作按钮（返回、保存、更多），下方为Markdown渲染区域或编辑器。
   • 交互: 编辑模式下，工具栏应悬浮或固定在键盘上方，方便操作。
3. 登录/注册页: 优化表单布局，使其在小屏幕上易于填写。
4. 侧边抽屉/“我的”页面:
   • 用于展示笔记分类、回收站入口、系统管理和用户设置（修改密码、退出登录）。

视觉美化 (现代感、色彩协调、交互流畅)

1. 设计语言: 采用简洁、扁平化的设计风格。
2. 色彩方案:
   • 主色调: 考虑使用柔和且具有科技感的蓝色或青色作为主色调。
   • 辅助色: 搭配中性的灰色和白色，以及用于提醒和危险操作的橙色/红色。
   • 暗黑模式: 提供一套完整的暗黑模式色彩方案。
3. 字体与排版: 选择清晰易读的无衬线字体（如 Inter, Lato），并优化移动端的字号和行间距。
4. 交互动效:
   • 加载动画: 使用骨架屏（Skeleton Screen）提升加载体验。
   • 转场动画: 页面切换时加入平滑的过渡效果。
   • 微交互: 为按钮点击、表单验证等操作添加精细的反馈动画。
5. 技术选型:
   • 我将使用 context7 服务查询 Tailwind CSS 和 Figma 的设计系统文档，以获取关于现代UI设计的最佳实践和灵感。

高保真原型图

我将使用 Figma 或提供详细的 Markdown + Mermaid 结构图来输出高保真原型，清晰地展示页面布局、组件样式和交互流程。

---

7. 确认与下一步

以上是我对项目的完整分析和后续规划。

请您审阅这份计划。如果符合您的预期，我将请求切换到 代码模式，并开始以下工作：

1. 根据设计方案，创建新的移动端适配样式文件。
2. 调整现有Vue组件，使其在移动端具有良好的响应式表现。
3. 实现新的交互效果和视觉元素。

期待您的反馈！