# MoKeeText Web 记事本 — 设计文档

**日期**: 2026-06-23
**状态**: 已确认

---

## 项目概述

一个 Web 记事本工具，包含两个核心模块：
1. **Markdown 笔记** — 增强型编辑器，类似飞书文档体验
2. **网站账号管理** — 网站密码本，智能导入功能

数据存储到 MySQL。

---

## 技术选型

| 层级 | 技术 | 理由 |
|------|------|------|
| 后端框架 | Python FastAPI | 高性能异步，Python 操作 MySQL 成熟 |
| 模板引擎 | Jinja2 | FastAPI 内置支持，服务端渲染 |
| ORM | SQLAlchemy | 最成熟的 Python ORM，MySQL 支持好 |
| 数据库 | MySQL | 用户指定 |
| 编辑器 | Tiptap | 增强型富文本编辑器，支持颜色/图片/表情/表格 |
| 前端交互 | 原生 JS + CDN 库 | 无构建步骤，快速迭代 |
| 样式 | 手写 CSS（飞书风格）| 简洁现代，大量留白 |

---

## 数据库设计

### 文件夹表 (folders)
| 字段 | 类型 | 说明 |
|------|------|------|
| id | INT PK | 主键 |
| name | VARCHAR(100) | 文件夹名 |
| type | ENUM('note','website') | 文件夹类型 |
| parent_id | INT FK | 父文件夹（NULL为根） |
| sort_order | INT | 排序 |
| created_at | DATETIME | 创建时间 |

### 笔记表 (notes)
| 字段 | 类型 | 说明 |
|------|------|------|
| id | INT PK | 主键 |
| title | VARCHAR(500) | 标题 |
| content | LONGTEXT | Tiptap JSON/HTML |
| folder_id | INT FK | 所属文件夹 |
| created_at | DATETIME | 创建时间 |
| updated_at | DATETIME | 更新时间 |

### 标签表 (tags)
| 字段 | 类型 | 说明 |
|------|------|------|
| id | INT PK | 主键 |
| name | VARCHAR(50) | 标签名 |
| color | VARCHAR(20) | 颜色 |

### 笔记-标签关联 (note_tags)
| 字段 | 类型 | 说明 |
|------|------|------|
| note_id | INT FK | 笔记ID |
| tag_id | INT FK | 标签ID |

### 网站表 (websites)
| 字段 | 类型 | 说明 |
|------|------|------|
| id | INT PK | 主键 |
| name | VARCHAR(200) | 网站名 |
| url | VARCHAR(500) | 网址 |
| folder_id | INT FK | 所属文件夹 |
| created_at | DATETIME | 创建时间 |

### 账号表 (accounts)
| 字段 | 类型 | 说明 |
|------|------|------|
| id | INT PK | 主键 |
| website_id | INT FK | 所属网站 |
| username | VARCHAR(500) | 账号 |
| password | VARCHAR(500) | 密码（明文，后续加密） |
| remark | TEXT | 登录说明/备注 |
| created_at | DATETIME | 创建时间 |

---

## 页面路由

| 路由 | 页面 |
|------|------|
| `/` | 重定向到 /notes |
| `/notes` | 笔记主页 |
| `/websites` | 网站管理主页 |
| `/api/notes/*` | 笔记 CRUD API |
| `/api/websites/*` | 网站 CRUD API |
| `/api/accounts/*` | 账号 CRUD API |
| `/api/folders/*` | 文件夹 CRUD API |
| `/api/tags/*` | 标签 CRUD API |
| `/api/import/parse` | 智能导入解析 |
| `/api/import/save` | 智能导入保存 |

---

## 智能导入解析逻辑

输入格式：
```
https://github.com 代码网站
zhangsan_new@qq.com
Xyz789!@#
新注册的开发账号
```

解析规则：
- 第1行：按第一个空格分割 → 前半为URL，后半为网站名
- 第2行：账号
- 第3行：密码
- 第4行：备注（可选）
- 根据URL匹配已有网站 → 存在则返回匹配信息，不存在则标记新建

---

## UI 布局

```
┌──────────────────────────────────────────────┐
│  📝 MoKeeText     [笔记] [网站管理]   个人版 │
├────────────┬─────────────────────────────────┤
│ 搜索...    │  标题        编辑/预览/分屏  标签│
│ + 新建     │  ─────────────────────────────  │
│            │                                 │
│ 📁 文件夹  │   Tiptap 增强编辑器             │
│  ├ 工作    │   (支持颜色/图片/表情/表格)     │
│  ├ 个人    │                                 │
│  └ 学习    │                                 │
│            │                                 │
│ 🏷️ 标签   │                                 │
│ python     │                                 │
│ mysql      │                                 │
└────────────┴─────────────────────────────────┘
```

---

## 项目结构

```
mokeeText/
├── app.py              # FastAPI 入口
├── config.py           # 数据库配置
├── models.py           # SQLAlchemy 模型
├── routes/
│   ├── notes.py        # 笔记相关路由
│   ├── websites.py     # 网站相关路由
│   └── import_api.py   # 智能导入 API
├── templates/
│   ├── base.html       # 基础布局
│   ├── notes.html      # 笔记页
│   └── websites.html   # 网站管理页
├── static/
│   ├── css/
│   │   └── style.css   # 飞书风格样式
│   └── js/
│       ├── editor.js   # Tiptap 初始化
│       ├── notes.js    # 笔记交互
│       └── websites.js # 网站管理交互
├── requirements.txt
└── docs/
    └── superpowers/
        └── specs/
            └── 2026-06-23-mokeetext-design.md
```