feat(biji-qianduan): 优化移动端适配并添加相关功能
- 新增移动端样式文件，优化小屏幕布局和交互- 在 HomePage 组件中添加移动端导航栏和搜索功能 - 修改 App.vue 以适应移动端布局- 更新 package.json 中的依赖版本 - 新增移动优先设计文档
This commit is contained in:
@@ -1,88 +1,241 @@
|
||||
# 项目分析报告
|
||||
# 项目分析与发展规划
|
||||
|
||||
本文档基于对现有代码库文件摘要的分析，对 "biji" 项目进行全面的评估，涵盖功能、技术栈、架构、代码质量和潜在风险。
|
||||
## 1. 项目概述
|
||||
|
||||
本项目是一个功能完善的全栈笔记应用，旨在为用户提供一个简洁、高效、安全的笔记管理平台。
|
||||
|
||||
- **核心功能**: 支持Markdown笔记的创建、编辑、分组管理，并包含图片上传、回收站、用户认证和系统管理等功能。
|
||||
- **技术架构**: 采用主流的前后端分离架构。
|
||||
- **前端**: 基于 Vue 3、Vite、Element Plus 和 Pinia 构建，实现了响应式和组件化的UI。
|
||||
- **后端**: 基于 Java 17、Spring Boot 3 和 MyBatis-Plus 构建，提供稳定、高效的API服务，并使用 SQLite 作为数据存储，简化了部署。
|
||||
|
||||
## 2. 系统架构
|
||||
|
||||
```mermaid
|
||||
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生态的最佳实践。
|
||||
|
||||
```mermaid
|
||||
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三层架构，逻辑清晰，易于维护。
|
||||
|
||||
```mermaid
|
||||
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. 核心业务逻辑
|
||||
|
||||
### 用户认证流程
|
||||
|
||||
```mermaid
|
||||
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
|
||||
```
|
||||
|
||||
### 笔记与图片管理
|
||||
|
||||
```mermaid
|
||||
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** 结构图来输出高保真原型，清晰地展示页面布局、组件样式和交互流程。
|
||||
|
||||
---
|
||||
|
||||
## 1. 功能概述
|
||||
## 7. 确认与下一步
|
||||
|
||||
根据实体类（Entity）、视图对象（VO）和工具类，可以推断出项目是一个笔记类应用（"biji" 在中文里是“笔记”的意思），其核心功能如下：
|
||||
以上是我对项目的完整分析和后续规划。
|
||||
|
||||
- **用户管理**：
|
||||
- **用户注册**：系统包含一个 `RegistrationCode` 实体，表明用户注册可能需要邀请码或注册码，这是一种控制用户增长的有效方式。
|
||||
- **用户实体**：标准的 `User` 实体，用于存储用户信息。
|
||||
- **安全认证**：`PasswordUtils` 使用 BCrypt 进行密码加密，这是业界推荐的安全实践。
|
||||
请您审阅这份计划。如果符合您的预期，我将请求切换到 **代码模式**，并开始以下工作：
|
||||
1. 根据设计方案，创建新的移动端适配样式文件。
|
||||
2. 调整现有Vue组件，使其在移动端具有良好的响应式表现。
|
||||
3. 实现新的交互效果和视觉元素。
|
||||
|
||||
- **核心笔记功能**：
|
||||
- **Markdown 编辑**：`MarkdownImageExtractor` 工具类的存在强烈暗示，应用的核心编辑器支持 Markdown 格式。
|
||||
- **图片管理**：用户可以在笔记中插入图片。系统会自动提取 Markdown 内容中的图片文件名（似乎是 UUID 格式），并可能将其与笔记关联。`Image` 和 `ImageName` 实体也证明了这一点。
|
||||
|
||||
- **数据管理**：
|
||||
- **回收站功能**：`TrashItemVo` 的存在表明项目实现了“回收站”或“软删除”功能。用户删除的内容可以先进入回收站，后续可以进行恢复或永久删除，提升了用户体验。
|
||||
|
||||
---
|
||||
|
||||
## 2. 技术栈分析
|
||||
|
||||
项目采用了现代化的前后端分离架构。
|
||||
|
||||
- **后端 (`biji-houdaun`)**
|
||||
- **语言**: Java
|
||||
- **框架**: 很可能是 **Spring Boot**。
|
||||
- **数据库 ORM**: **MyBatis-Plus** (根据 `@TableName` 注解推断)。
|
||||
- **API 文档**: **Swagger / OpenAPI** (根据 `@Schema` 注解推断)。
|
||||
- **安全**: **Spring Security** (结合 `BCryptPasswordEncoder` 的使用推断)。
|
||||
|
||||
- **前端 (`biji-qianduan`)**
|
||||
- **框架**: **Vue.js** (根据 `vite.config.js` 中的 `plugins: [vue()]` 推断)。
|
||||
- **构建工具**: **Vite**，一个现代、高效的前端构建工具。
|
||||
- **代码风格**: 使用了路径别名 `@` 指向 `src` 目录，这是良好的开发实践。
|
||||
|
||||
---
|
||||
|
||||
## 3. 架构分析
|
||||
|
||||
- **前后端分离架构**：这是本项目最核心的架构模式。
|
||||
- **前端**：作为单页应用 (SPA)，负责用户界面和交互逻辑。
|
||||
- **后端**：通过 RESTful API 向前端提供数据和业务逻辑服务。
|
||||
|
||||
- **API 通信**：
|
||||
- 前端通过 Vite 的开发服务器代理 (`/api` 代理到 `http://localhost:8084`) 与后端进行通信。这解决了开发环境下的跨域问题 (CORS)，是标准的开发配置。
|
||||
|
||||
- **数据流**：
|
||||
1. 用户在 Vue.js 构建的前端界面进行操作。
|
||||
2. 前端向后端发起 API 请求 (例如，保存一篇包含图片的笔记)。
|
||||
3. 后端 Spring Boot 应用接收请求，Controller 层调用 Service 层处理业务逻辑。
|
||||
4. Service 层可能会调用 `MarkdownImageExtractor` 来解析内容、处理图片，并使用 MyBatis-Plus 将 `User`, `Image` 等实体持久化到数据库。
|
||||
5. 后端将处理结果（如成功信息或数据）以 JSON 格式返回给前端。
|
||||
|
||||
---
|
||||
|
||||
## 4. 代码改进建议
|
||||
|
||||
虽然无法看到完整的业务逻辑代码，但从现有文件摘要中可以提出以下建议：
|
||||
|
||||
- **实体类冗余代码**：在 `RegistrationCode.java` 中，如果使用了 Lombok 的 `@Data` 注解，那么 `getCreatedBy()` 和 `getCreatedAt()` 这类标准的 getter 方法是自动生成的，无需手动编写。如果方法内没有特殊逻辑，建议移除以保持代码整洁。
|
||||
|
||||
- **正则表达式的健壮性**：`MarkdownImageExtractor` 中用于提取图片文件名的正则表达式似乎非常具体（匹配 UUID 格式）。这是一个优点（命名规范），但也可能成为一个限制。如果未来需要支持其他格式的文件名，该正则表达式需要更新。
|
||||
|
||||
- **遵循 VO 模式**：项目已经定义了 `TrashItemVo`，这是一个很好的实践，做到了持久化对象（Entity）和视图对象（VO）的分离。建议在所有需要向前端返回复杂数据的地方都遵循此模式，避免直接暴露数据库实体。
|
||||
|
||||
---
|
||||
|
||||
## 5. 潜在问题与风险分析
|
||||
|
||||
基于当前分析，项目在未来发展中可能面临以下挑战：
|
||||
|
||||
- **存储管理 - 孤立图片问题**：
|
||||
- 当用户在笔记中移除一张图片的链接时，对应的图片文件是否会从服务器上删除？如果处理不当，会产生大量不再被任何笔记引用的“孤立图片”，浪费存储空间。
|
||||
- **建议**：可以设计一个定期的垃圾回收任务，扫描并清理未被引用的图片文件。
|
||||
|
||||
- **存储扩展性**：
|
||||
- 图片是存储在服务器本地文件系统还是云存储（如 AWS S3, 阿里云 OSS）？如果存储在本地，当应用部署到多台服务器（集群）时，会出现图片访问不到的问题。
|
||||
- **建议**：对于有一定规模的应用，早期就应考虑使用云存储服务。
|
||||
|
||||
- **安全性**：
|
||||
- 项目已使用 BCrypt 加密密码，这是很好的起点。
|
||||
- 但仍需关注其他安全风险，如：XSS（跨站脚本攻击）、CSRF（跨站请求伪造）、SQL 注入等。虽然 Spring Security 和 MyBatis-Plus 提供了防护，但仍需正确配置和使用。
|
||||
- **建议**：对所有用户输入进行严格的校验和过滤。
|
||||
期待您的反馈！
|
||||
Reference in New Issue
Block a user