mokee/mokeeText
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

初始化

Browse Source
This commit is contained in:
zg
2026-07-15 16:08:17 +08:00
parent f0d70aded4
commit 4e0057ece5
89 changed files with 13512 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

310
docs/DEPLOY.md Normal file
View File

@@ -0,0 +1,310 @@
# MoKeeText 部署文档
## 部署架构
```
Internet
│
┌───────┴───────┐
│ 反向代理/Nginx │ (运维侧管理，SSL 终端)
└───────┬───────┘
│
┌─────────────┼─────────────┐
│ │ │
:3006 (前端) :4006 (后端) :3306 (MySQL)
│ │ │
┌─────────┴──┐ ┌──────┴──────┐ ┌──┴──────────┐
│ Nginx │ │ FastAPI │ │ MySQL 8.0 │
│ (Alpine) │ │ (Python3.12)│ │ (远程) │
│ │ │ │ │ │
│ 静态文件 │ │ API + ORM │ │ 10.20.1.122 │
└────────────┘ └─────────────┘ └──────────────┘
容器: frontend 容器: backend 外部服务
```
**两个容器**：
- **frontend** — Nginx Alpine，挂载 Vue 构建产物，端口 3006
- **backend** — Python 3.12-slim，Uvicorn 运行 FastAPI，端口 4006
**跨域通信**：前端直接跨域请求后端 API，Nginx **不代理** `/api/`。CORS 在后端 FastAPI 中配置。
---
## 环境信息
| 项目 | 值 |
|------|-----|
| 服务器 IP | `101.132.183.138` |
| SSH 用户 | `root` |
| SSH 认证 | 密钥（~/.ssh/id_rsa） |
| 项目路径 | `/data/mokee/mokeetext` |
| 前端域名 | `https://mokeetext.zgitm.com` → 端口 `3006` |
| 后端域名 | `https://mokeetext.server.zgitm.com` → 端口 `4006` |
| 数据库 | MySQL `10.20.1.122:3306` / 库 `mokeetext` |
| 数据库用户 | `mokeetext` |
---
## 服务器目录结构
```
/data/mokee/mokeetext/
├── docker-compose.yml # 容器编排（由 deploy.py 上传）
├── backend/
│ ├── Dockerfile
│ ├── app.py
│ ├── models.py
│ ├── config.py
│ ├── logger.py
│ ├── init_db.py
│ ├── requirements.txt
│ ├── routes/
│ │ ├── notes.py
│ │ ├── websites.py
│ │ ├── import_api.py
│ │ ├── upload.py
│ │ └── share.py
│ └── middleware/
│ └── user_context.py
├── frontend/
│ ├── Dockerfile.frontend
│ ├── nginx.conf
│ └── static/
│ └── dist/ # Vue 构建产物（Nginx 托管）
└── logs/ # 应用日志（挂载到宿主机）
├── mokeetext.log # 按天轮转
└── current.log
```
---
## 日常部署流程
### 前置条件
1. SSH 密钥已配置到服务器
2. 本地已安装 Python 3.12 + paramiko
### 快速部署（仅前端改动）
大多数改动只需要重新构建前端并重建 frontend 容器：
```bash
# 1. 构建前端
cd frontend
npx vite build
# 2. 部署
cd ..
python deploy/deploy.py
```
`deploy.py` 会自动：
1. SSH 连接到服务器
2. 清理旧的 JS/CSS 文件
3. SFTP 上传新的 `static/dist/` 文件
4. 执行 `docker compose up -d --build frontend`
### 后端改动部署
如果修改了后端代码：
```bash
# 1. 上传后端文件
scp backend/*.py root@101.132.183.138:/data/mokee/mokeetext/backend/
scp backend/routes/*.py root@101.132.183.138:/data/mokee/mokeetext/backend/routes/
scp backend/middleware/*.py root@101.132.183.138:/data/mokee/mokeetext/backend/middleware/
# 2. 重建后端容器
ssh root@101.132.183.138 'cd /data/mokee/mokeetext && docker compose up -d --build backend'
```
### Docker Compose 配置变更
如果修改了 `docker-compose.yml`：
```bash
scp deploy/docker-compose.yml root@101.132.183.138:/data/mokee/mokeetext/docker-compose.yml
ssh root@101.132.183.138 'cd /data/mokee/mokeetext && docker compose up -d --build'
```
---
## 首次部署（从零搭建）
### 1. 服务器准备
```bash
# SSH 到服务器
ssh root@101.132.183.138
# 安装 Docker（如果尚未安装）
curl -fsSL https://get.docker.com | sh
# 创建项目目录
mkdir -p /data/mokee/mokeetext/{backend/routes,backend/middleware,frontend/static/dist,logs}
```
### 2. 上传文件
```bash
# 在本地上传所有文件
scp deploy/docker-compose.yml root@101.132.183.138:/data/mokee/mokeetext/
scp backend/*.py backend/*.txt backend/Dockerfile backend/.dockerignore \
root@101.132.183.138:/data/mokee/mokeetext/backend/
scp backend/routes/*.py root@101.132.183.138:/data/mokee/mokeetext/backend/routes/
scp backend/middleware/*.py root@101.132.183.138:/data/mokee/mokeetext/backend/middleware/
scp frontend/Dockerfile.frontend frontend/nginx.conf frontend/.dockerignore \
root@101.132.183.138:/data/mokee/mokeetext/frontend/
# 构建前端并上传
cd frontend && npx vite build && cd ..
scp -r frontend/static/dist/* root@101.132.183.138:/data/mokee/mokeetext/frontend/static/dist/
```
### 3. 启动服务
```bash
ssh root@101.132.183.138 'cd /data/mokee/mokeetext && docker compose up -d --build'
```
### 4. 验证
```bash
# 检查容器状态
ssh root@101.132.183.138 'cd /data/mokee/mokeetext && docker compose ps'
# 检查后端健康
curl https://mokeetext.server.zgitm.com/api/notes
# 检查前端
curl https://mokeetext.zgitm.com
```
---
## 常用运维命令
### 容器管理
```bash
# 查看运行状态
ssh root@101.132.183.138 'cd /data/mokee/mokeetext && docker compose ps'
# 查看日志
ssh root@101.132.183.138 'cd /data/mokee/mokeetext && docker compose logs --tail=50 backend'
ssh root@101.132.183.138 'cd /data/mokee/mokeetext && docker compose logs --tail=50 frontend'
# 重启单个服务
ssh root@101.132.183.138 'cd /data/mokee/mokeetext && docker compose restart backend'
# 停止所有服务
ssh root@101.132.183.138 'cd /data/mokee/mokeetext && docker compose down'
# 完全重建（清除缓存）
ssh root@101.132.183.138 'cd /data/mokee/mokeetext && docker compose build --no-cache && docker compose up -d'
```
### 日志查看
```bash
# 应用日志（按天拆分）
ssh root@101.132.183.138 'ls -la /data/mokee/mokeetext/logs/'
ssh root@101.132.183.138 'tail -100 /data/mokee/mokeetext/logs/current.log'
# 实时跟踪
ssh root@101.132.183.138 'tail -f /data/mokee/mokeetext/logs/current.log'
```
### 数据库操作
```bash
# 进入 MySQL
ssh root@101.132.183.138 'docker exec -it mokeetext-backend-1 python -c "
import pymysql
conn = pymysql.connect(host=\"10.20.1.122\", user=\"mokeetext\", password=\"mokee.\", database=\"mokeetext\")
print(\"connected\")
conn.close()
"'
```
---
## 环境变量
### Backend 容器
| 变量 | 默认值 | 说明 |
|------|--------|------|
| `MYSQL_HOST` | `10.20.1.122` | 数据库主机 |
| `MYSQL_PORT` | `3306` | 数据库端口 |
| `MYSQL_USER` | `mokeetext` | 数据库用户 |
| `MYSQL_PASSWORD` | `mokee.` | 数据库密码 |
| `MYSQL_DATABASE` | `mokeetext` | 数据库名 |
| `LOG_DIR` | `/data/mokee/mokeetext/logs` | 日志目录 |
这些在 `docker-compose.yml` 中定义，可通过 `.env` 文件覆盖。
### Frontend 构建
| 变量 | 说明 |
|------|------|
| `VITE_API_BASE` | 生产环境 API 地址 |
| `VITE_LOGIN_URL` | 统一登录页地址 |
| `VITE_SYSTEM_CODE` | 系统编码 |
定义在 `frontend/.env.production` 中。
---
## 回滚
如果部署出现问题：
```bash
# 1. 回到上一个前端镜像
ssh root@101.132.183.138 'cd /data/mokee/mokeetext && docker compose up -d frontend'
# Docker 会使用缓存的镜像层
# 2. 如果有备份的 dist 文件
scp backup-dist/* root@101.132.183.138:/data/mokee/mokeetext/frontend/static/dist/
ssh root@101.132.183.138 'cd /data/mokee/mokeetext && docker compose restart frontend'
# 3. 极端情况：重建所有容器
ssh root@101.132.183.138 'cd /data/mokee/mokeetext && docker compose down && docker compose up -d --build'
```
---
## 故障排查
### 前端页面空白
1. 检查 Nginx 容器是否运行：`docker compose ps frontend`
2. 检查 dist 文件是否存在：`ls /data/mokee/mokeetext/frontend/static/dist/`
3. 检查 Nginx 日志：`docker compose logs frontend`
### API 返回 500
1. 检查后端容器日志：`docker compose logs backend --tail=100`
2. 检查数据库连接：确认 MySQL 可访问
3. 检查应用日志：`tail -100 /data/mokee/mokeetext/logs/current.log`
### CORS 错误
1. 确认前端请求的 API 地址正确
2. 确认 `app.py` 中 `allow_origins` 包含当前域名
3. 确认请求未经过 Nginx 代理（前端直接调后端）
### 容器无法启动
```bash
# 查看构建日志
ssh root@101.132.183.138 'cd /data/mokee/mokeetext && docker compose build --progress=plain'
# 检查端口占用
ssh root@101.132.183.138 'netstat -tlnp | grep -E "3006|4006"'
```

345
docs/README.md Normal file
View File

@@ -0,0 +1,345 @@
# MoKeeText 项目文档
## 概述
**MoKeeText** 是一个 Web 端富文本笔记管理应用，同时具备网站账号密码管理功能，集成 Mokee Gateway 统一登录网关。
### 核心功能
| 模块 | 功能 |
|------|------|
| 📝 **笔记编辑** | 基于 Tiptap 的增强型富文本编辑器，支持文字颜色、图片粘贴/拖拽上传、表格、代码高亮、任务列表 |
| 🔐 **网站管理** | 按文件夹分类管理网站及其登录账号密码 |
| 🔗 **分享链接** | 笔记可生成分享链接，支持 7天/30天/1年/永久 四种有效期 |
| 📥 **智能导入** | 自动解析粘贴的网站账号信息，一键导入 |
| 🖼️ **图片上传** | 粘贴/拖拽图片自动上传，存数据库 LONGBLOB，点击全屏预览 |
| 👤 **统一登录** | 接入 Mokee Gateway，通过网关转发用户身份，支持 API 级数据隔离 |
---
## 技术栈
| 层 | 技术 | 版本 |
|----|------|------|
| 后端框架 | FastAPI (Python) | ≥0.115 |
| 服务器 | Uvicorn | ≥0.30 |
| ORM | SQLAlchemy | ≥2.0 |
| 数据库 | MySQL | 8.0 |
| 前端框架 | Vue 3 + Vite | 3.5 / 8.x |
| 路由 | Vue Router | 4.6 |
| 编辑器 | Tiptap | 3.27 |
| 代码高亮 | highlight.js (lowlight) | - |
| HTTP 客户端 | Axios（生产）/ fetch（本地开发） | 1.18 |
| 容器化 | Docker + Docker Compose | - |
| Web 服务器 | Nginx (Alpine) | - |
---
## 项目结构
```
mokeeText/
├── backend/ # 后端 — FastAPI 应用
│ ├── app.py # 入口：CORS、中间件、路由注册
│ ├── models.py # SQLAlchemy 数据模型（6 张表）
│ ├── config.py # 数据库连接配置（环境变量）
│ ├── logger.py # 日志系统（按天轮转，保留 30 天）
│ ├── init_db.py # 建表脚本
│ ├── requirements.txt # Python 依赖
│ ├── Dockerfile # 后端 Docker 镜像
│ ├── .dockerignore
│ ├── routes/ # API 路由
│ │ ├── notes.py # 笔记 CRUD + 分享 + 移动
│ │ ├── websites.py # 网站/账号/文件夹 CRUD + 排序
│ │ ├── import_api.py # 智能导入解析
│ │ ├── upload.py # 图片上传/读取
│ │ └── share.py # 公开分享查看页
│ └── middleware/
│ └── user_context.py # 网关用户上下文中间件
│
├── frontend/ # 前端 — Vue 3 SPA
│ ├── index.html # Vite 入口 HTML
│ ├── package.json # 前端依赖
│ ├── vite.config.js # Vite 构建配置
│ ├── nginx.conf # Nginx 配置
│ ├── Dockerfile.frontend # 前端 Nginx Docker 镜像
│ ├── .dockerignore
│ ├── .env / .env.production # 环境变量
│ ├── src/
│ │ ├── main.js # Vue 入口 → 挂载 Router + v-permission
│ │ ├── App.vue # 根组件：左导航 + 顶栏 + UserChip + 底栏
│ │ ├── router.js # Vue Router 配置 + 路由守卫
│ │ ├── utils/request.js # Axios 实例 + 拦截器
│ │ ├── composables/useApi.js # 双模式 API（dev fetch / prod axios）
│ │ ├── directives/permission.js # v-permission 按钮权限指令
│ │ ├── views/
│ │ │ ├── NotesView.vue # 笔记：文件夹侧边栏 + 列表 + 编辑器
│ │ │ ├── WebsitesView.vue # 网站管理：列表 + CRUD 弹窗
│ │ │ └── SharesView.vue # 分享管理
│ │ └── components/
│ │ ├── NoteEditor.vue # Tiptap 增强编辑器
│ │ ├── Modal.vue # 通用弹窗组件
│ │ ├── ConfirmModal.vue
│ │ └── PromptModal.vue
│ └── static/
│ ├── dist/ # Vite 构建产物（Nginx 托管）
│ ├── js/vendor/ # Tiptap UMD 扩展文件
│ ├── css/
│ └── uploads/
│
├── deploy/ # 部署
│ ├── docker-compose.yml # 双容器编排
│ ├── deploy.py # 日常部署脚本
│ └── migrate_server.py # 服务器迁移脚本（一次性）
│
├── docs/ # 文档
│ ├── README.md # 本文档
│ ├── DEPLOY.md # 部署文档
│ └── superpowers/ # 设计规范 + 实施计划
│
└── memory/ # 会话记忆
```
---
## 数据库设计
### ER 图
```
folders ──┬── notes ──┬── note_tags ── tags
│
└── websites ── accounts
uploads（独立，图片存 DB）
```
### 表结构
#### folders — 文件夹（笔记和网站共用）
| 字段 | 类型 | 说明 |
|------|------|------|
| id | INT PK | 自增主键 |
| name | VARCHAR(100) | 文件夹名称 |
| type | ENUM('note','website') | 类型 |
| parent_id | INT FK→folders.id | 父文件夹（树形结构） |
| sort_order | INT | 排序 |
| created_by | VARCHAR(100) | 创建者账号 |
| created_at | DATETIME | 创建时间 |
#### notes — 笔记
| 字段 | 类型 | 说明 |
|------|------|------|
| id | INT PK | 自增主键 |
| title | VARCHAR(500) | 标题 |
| content | TEXT | Tiptap 输出的 HTML |
| folder_id | INT FK→folders.id | 所属文件夹 |
| created_by | VARCHAR(100) | 创建者 |
| updated_by | VARCHAR(100) | 最后修改者 |
| share_token | VARCHAR(64) UNIQUE | 分享令牌 |
| share_expires_at | DATETIME | 分享过期时间 |
| created_at / updated_at | DATETIME | 时间戳 |
#### tags — 标签
| 字段 | 类型 | 说明 |
|------|------|------|
| id | INT PK | 自增主键 |
| name | VARCHAR(50) UNIQUE | 标签名 |
| 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_by / updated_by | VARCHAR(100) | 操作者 |
| created_at / updated_at | DATETIME | 时间戳 |
#### accounts — 账号
| 字段 | 类型 | 说明 |
|------|------|------|
| id | INT PK | 自增主键 |
| website_id | INT FK | 所属网站 |
| username | VARCHAR(500) | 用户名 |
| password | VARCHAR(500) | 密码（明文，待加密） |
| remark | TEXT | 备注 |
| sort_order | INT | 排序 |
| created_by / updated_by | VARCHAR(100) | 操作者 |
#### uploads — 上传文件
| 字段 | 类型 | 说明 |
|------|------|------|
| id | INT PK | 自增主键 |
| filename | VARCHAR(255) | 原始文件名 |
| content_type | VARCHAR(100) | MIME 类型 |
| data | LONGBLOB | 二进制数据（最大 4GB） |
| size | INT | 文件大小（字节） |
| created_by | VARCHAR(100) | 上传者 |
| created_at | DATETIME | 上传时间 |
---
## API 接口
所有接口均以 `/api/` 为前缀。除分享页和图片读取外，所有操作需要网关注入用户身份。
### 笔记
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/notes` | 获取笔记列表（支持 `?folder_id=` 筛选） |
| POST | `/api/notes` | 创建笔记 |
| GET | `/api/notes/{id}` | 获取笔记详情 |
| PUT | `/api/notes/{id}` | 修改笔记 |
| DELETE | `/api/notes/{id}` | 删除笔记 |
| PUT | `/api/notes/{id}/move` | 移动笔记到文件夹 |
| POST | `/api/notes/{id}/share` | 生成分享链接 |
### 文件夹
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/folders` | 获取文件夹列表（支持 `?type=note\|website`） |
| POST | `/api/folders` | 创建文件夹 |
| PUT | `/api/folders/{id}` | 重命名文件夹 |
| DELETE | `/api/folders/{id}` | 删除文件夹 |
### 网站与账号
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/websites` | 获取网站列表（支持 `?folder_id=`） |
| POST | `/api/websites` | 创建网站 |
| PUT | `/api/websites/{id}` | 修改网站 |
| DELETE | `/api/websites/{id}` | 删除网站 |
| GET | `/api/websites/{id}/accounts` | 获取账号列表 |
| POST | `/api/websites/{id}/accounts` | 创建账号 |
| PUT | `/api/accounts/{id}` | 修改账号 |
| DELETE | `/api/accounts/{id}` | 删除账号 |
| PUT | `/api/accounts/sort` | 账号排序 |
### 文件
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/upload/image` | 上传图片（网关鉴权） |
| GET | `/api/file/{id}` | 读取图片（公开，无需鉴权） |
### 分享
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/share/{token}` | 公开查看分享的笔记（不走网关） |
| GET | `/api/shares` | 获取我的分享列表 |
| DELETE | `/api/shares/{note_id}` | 取消分享 |
### 智能导入
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/import/parse` | 解析粘贴的文本，提取网站+账号信息 |
---
## 认证架构
```
┌─────────┐ ┌──────────────┐ ┌─────────────┐ ┌──────────┐
│ 浏览器 │ ──→ │ 统一登录页 │ ──→ │ Mokee │ ──→ │ FastAPI │
│ │ │ login.user. │ │ Gateway │ │ 后端 │
│ │ │ zgitm.com │ │ gw.server. │ │ :4006 │
│ │ │ │ │ zgitm.com │ │ │
└─────────┘ └──────────────┘ └──────┬───────┘ └──────────┘
│
注入 X-User-* 头
X-User-Id, X-User-Account,
X-User-Roles, X-System-Code ...
```
### 请求流程
1. **用户访问** → 前端路由守卫检查 Cookie 中是否有 `token`
2. **无 Token** → 重定向到 `login.user.zgitm.com` 统一登录
3. **登录成功** → 网关设置 Cookie，用户回到应用
4. **API 请求** → Axios 拦截器从 Cookie 取 Token 放入 Authorization 头
5. **网关转发** → 验证 Token 后注入 `X-User-*` 系列请求头
6. **后端中间件** → `UserContextMiddleware` 提取请求头存入 `request.state.user`
7. **业务路由** → 通过 `UserContext.get_user_id()` 获取当前用户，按 `created_by` 过滤数据
### 本地开发模式
设置环境变量 `DEV_MODE=true` 或添加请求头 `X-Dev-Mock-User`，后端绕过网关认证，使用默认 admin 用户。
```bash
# 启动后端
cd backend
DEV_MODE=true uvicorn app:app --port 4006
# 启动前端（另一个终端）
cd frontend
npx vite
```
---
## 前端架构
### 路由
| 路径 | 组件 | 说明 |
|------|------|------|
| `/` | → 重定向 | 默认到 /notes |
| `/notes` | NotesView | 笔记编辑器（文件夹 + 列表 + 编辑器） |
| `/websites` | WebsitesView | 网站账号管理 |
| `/shares` | SharesView | 分享链接管理 |
### API 调用模式
前端通过 `useApi()` 组合式函数发起请求，自动适配环境：
- **生产环境**：使用 Axios 实例，拦截器自动携带 Token → 请求走网关
- **本地开发**：使用 fetch，添加 `X-Dev-Mock-User` 头模拟用户
```js
// composables/useApi.js
import { useApi } from '@/composables/useApi'
const { get, post, put, del } = useApi()
const notes = await get('/api/notes')
```
### 图片处理
- **上传**：粘贴/拖拽 → `POST /api/upload/image`（走网关，带 Token）
- **显示**：`<img src="https://mokeetext.server.zgitm.com/api/file/{id}">`（走后端直连，公开读取）
- **预览**：点击图片 → 全屏灯箱，带关闭按钮
### UI 特性
- 左侧可收起导航栏（展开 "mokee编辑器"，收起 "M"）
- 文件夹侧边栏可收起
- 笔记列表 + 编辑器双栏布局
- Ctrl+S 保存，顶部 toast 提示
- 弹窗全部为 Vue 组件（非浏览器 alert/confirm）
- 移动端响应式适配（768px 断点）
- 顶栏右侧「切换系统」按钮 → 跳转网关系统选择页
---
## 生产环境
| 项目 | 值 |
|------|-----|
| 服务器 | 101.132.183.138 (腾讯云) |
| 前端地址 | https://mokeetext.zgitm.com |
| 后端地址 | https://mokeetext.server.zgitm.com |
| 数据库 | MySQL 10.20.1.122:3306/mokeetext |
| 日志路径 | /data/mokee/mokeetext/logs（按天轮转，保留 30 天） |
| ICP 备案 | 湘ICP备19021539号 |

1216
docs/superpowers/plans/2026-06-23-mokeetext-gateway-integration.md Normal file
View File

File diff suppressed because it is too large Load Diff

2115
docs/superpowers/plans/2026-06-23-mokeetext-implementation.md Normal file
View File

File diff suppressed because it is too large Load Diff

173
docs/superpowers/specs/2026-06-23-mokeetext-design.md Normal file
View File

@@ -0,0 +1,173 @@
# 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
```