Notes App — 设计方案

状态：✅ 设计已确认 | 2026-05-22

1. 项目概述

定位：轻量知识管理 Web 应用
MVP 范围：笔记 CRUD + 分类/标签管理 + 全文搜索
编辑体验：Markdown 编辑 + 实时预览
技术栈：Vue 3 + Vite 前端 / Spring Boot 3.4.5 + Java 21 后端 / SQLite 持久化 / Docker 单容器部署

2. 整体架构

┌─────────────────────────────────────┐
│           Docker Container          │
│  ┌─────────────┐  ┌──────────────┐  │
│  │  Vue 3 SPA  │  │ Spring Boot  │  │
│  │  (Nginx)    │──│  REST API    │  │
│  │  :80        │  │  :8080       │  │
│  └─────────────┘  └──────┬───────┘  │
│                          │          │
│                   ┌──────▼───────┐  │
│                   │   SQLite     │  │
│                   │ (bind mount) │  │
│                   └──────────────┘  │
└─────────────────────────────────────┘
  • 前端：Vue 3 SPA，Nginx 反代 /api 到后端，本地开发用 Vite proxy
  • 后端：Spring Boot REST API，SQLite（FTS5 全文搜索）
  • 部署：Docker 单容器，前端静态文件打入镜像，数据库 bind mount ./data/
  • Markdown：前端 marked + highlight.js 实时渲染

3. 数据模型

三张表：

  • category：id, name, color
  • note：id, title, content, category_id (FK), created_at, updated_at
  • tag：id, name, color
  • note_tag：note_id (FK), tag_id (FK)

全文搜索：SQLite FTS5 虚拟表，索引 title + content。

4. API 设计

统一返回格式：{ "code": 0, "data": {...}, "message": "ok" }

笔记

  • GET /api/notes — 列表（支持 ?category=&tag=&q=）
  • GET /api/notes/{id} — 详情
  • POST /api/notes — 新建
  • PUT /api/notes/{id} — 编辑
  • DELETE /api/notes/{id} — 删除

分类

  • GET /api/categories — 列表
  • POST /api/categories — 新建
  • PUT /api/categories/{id} — 编辑
  • DELETE /api/categories/{id} — 删除

标签

  • GET /api/tags — 列表
  • POST /api/tags — 新建
  • PUT /api/tags/{id} — 编辑
  • DELETE /api/tags/{id} — 删除

搜索

  • GET /api/search?q=xxx — FTS5 全文搜索

5. 前端组件树

App
├── Sidebar                    # 左侧导航
│   ├── CategoryList           # 分类列表
│   │   └── CategoryItem
│   ├── TagCloud               # 标签云
│   │   └── TagChip
│   └── SearchBar              # 搜索框
│
├── NoteList                   # 中间笔记列表
│   ├── NoteCard
│   └── NewNoteButton
│
└── NoteEditor                 # 右侧编辑区
    ├── EditorToolbar
    ├── MarkdownInput
    └── MarkdownPreview

交互流：分类/标签筛选 → 列表更新 → 编辑器加载；编辑区 debounce 2s 自动保存。
响应式：< 768px 三栏→单栏，编辑器全屏 + 返回按钮。

6. 部署方案

  • Dockerfile 三阶段构建：Node 前端 → Maven 后端（含前端静态）→ JRE 运行
  • docker-compose.yml：单容器 + bind mount ./data/
  • 端口映射：8080:8080（Spring Boot 直接服务前端静态文件 + API）

7. 风险

风险 等级 缓解
SQLite FTS5 中文分词效果不佳 🟡 P2 先用 FTS5 默认分词，如不满足后续可换 Lucene
Markdown 编辑器性能 🟢 P3 纯 textarea + 渲染预览，非富文本编辑器，性能无瓶颈