# 基于 Flask 的个人博客系统设计文档

## 1. 概述

本系统是一个轻量级的个人博客内容管理方案，支持通过 Web 界面上传 Markdown 博文及关联图片。后端基于 Flask 完成 Markdown 到 HTML 的渲染（含 LaTeX 支持），生成静态页面并保存。不需要数据库，所有数据以文件系统方式组织。前端采用瀑布流布局展示文章列表，风格简洁美观，仿照朋友圈的卡片式设计。

## 2. 技术架构

- **后端框架**：Flask  
- **Markdown 渲染**：`markdown` + 扩展（codehilite, fenced_code, tables 等）  
- **LaTeX 渲染**：前端 MathJax 3（服务端保留 `$...$` / `$$...$$` 标记）  
- **文件存储**：按文章 ID 分目录存储原始 Markdown、图片，另生成独立静态 HTML 文件  
- **元数据管理**：单一 `posts_index.json` 文件存储所有文章索引（无数据库）  
- **前端布局**：CSS Grid 实现瀑布流卡片，深色/浅色干净主题，响应式设计  

## 3. 目录结构

```
.
├── app.py                     # Flask 主程序，路由与核心逻辑
├── config.py                  # 配置文件（上传限制、路径等）
├── requirements.txt           # Python 依赖列表
├── templates/                 # Jinja2 模板
│   ├── base.html              # 全局基础模板（含 meta、MathJax、导航栏）
│   ├── index.html             # 博客首页（瀑布流文章列表）
│   ├── upload.html            # 上传表单页面
│   └── admin.html             # 管理页面（展示所有文章，提供删除操作）
├── static/                    # 静态资源（Flask 自动提供）
│   ├── css/
│   │   └── style.css          # 主样式表（瀑布流、卡片、暗色/亮色风格）
│   ├── js/
│   │   └── main.js            # 可选前端交互（如瀑布流优化、懒加载）
│   └── uploads/               # 用户上传的图片存储目录
│       └── posts/             # 每篇文章的图片子目录（详见下文）
├── generated/                 # 生成的静态 HTML 文件
│   └── <post_id>.html         # 每篇文章对应的独立页面
├── posts_data/                # 原始数据存储
│   └── <post_id>/             # 以文章 ID 命名的目录
│       ├── content.md         # 原始 Markdown 文件
│       └── images/            # 该文章用到的图片（软链接或实际存储）
│           └── 图片文件...
└── posts_index.json           # 全局索引文件，存储所有文章元数据
```

> **说明**：  
> - 图片实际保存到 `static/uploads/posts/<post_id>/` 下，以便通过 `/static/uploads/posts/<post_id>/image.png` 直接访问。  
> - `posts_data/<post_id>/images/` 可以是一个目录软链接，也可以在主程序中统一按 ID 查找图片路径。为简化，可以在上传时直接将图片保存到 `static/uploads/posts/<post_id>/`，而 `posts_data` 中只保留 Markdown 副本。两种方案均可，本设计采用统一保存到 `static/uploads/posts/<post_id>/`，在 `posts_data` 中不再重复存储图片。

## 4. 需要创建的文件清单

| 文件路径 | 作用 |
|---------|------|
| `app.py` | Flask 应用入口，定义所有路由（首页、上传、文章详情、管理、删除） |
| `config.py` | 配置项：`UPLOAD_FOLDER`, `GENERATED_FOLDER`, `INDEX_FILE`, `ALLOWED_EXTENSIONS`, `MAX_CONTENT_LENGTH` 等 |
| `requirements.txt` | 依赖列表（Flask, markdown, Pygments 等） |
| `templates/base.html` | 全局模板，包含 HTML 骨架、导航栏、MathJax 脚本、基础 CSS/JS 引用 |
| `templates/index.html` | 首页，继承 base.html，使用瀑布流卡片渲染文章列表 |
| `templates/upload.html` | 上传表单，支持 Markdown 文件 + 多图片选择 |
| `templates/admin.html` | 后台管理，以表格形式列出所有文章，提供删除按钮 |
| `static/css/style.css` | 完整样式定义（瀑布流栅格、卡片样式、按钮、代码高亮等） |
| `static/js/main.js` | 可选前端增强（如卡片悬停效果、动态瀑布流重排） |
| `posts_index.json` | 运行时自动生成/更新，存储结构见下文 |

## 5. 核心功能设计

### 5.1 文章上传与处理流程

1. **接收请求**：POST `/upload`，接收 `title`（字符串），`markdown_file`（文件），`images`（多文件列表）。  
2. **创建文章 ID**：使用时间戳（如 `int(time.time()*1000)`）或 `uuid4` 生成唯一 `post_id`。  
3. **创建目录**：  
   - 图片保存目录：`static/uploads/posts/<post_id>/`  
   - 原始 Markdown 保存目录：`posts_data/<post_id>/`
4. **保存文件**：  
   - 将 Markdown 文件保存为 `posts_data/<post_id>/content.md`。  
   - 将每个图片保存到 `static/uploads/posts/<post_id>/` 下，保留原文件名（需过滤危险字符）。  
5. **解析 Markdown**：  
   - 读取 `content.md` 内容，提取 Front Matter（若存在，使用 `frontmatter` 库或正则），获得 `title`, `date`, `summary` 等。若 Front Matter 缺失，则使用表单中的 `title`，当前时间作为发布日期，摘要从正文前 200 字生成。  
   - 处理图片 URL：扫描 Markdown 中所有 `![](filename)` 式的本地图片引用，将 `filename` 替换为 `/static/uploads/posts/<post_id>/filename`。若图片未上传，记录警告但继续渲染。  
6. **渲染 HTML**：  
   - 使用 `markdown.markdown()` 并将扩展启用：`extra`, `codehilite`, `tables`, `fenced_code`。  
   - 若需 LaTeX 支持，在渲染结果中保留 `$...$` 和 `$$...$$`（不进行转义）。  
7. **生成静态页面**：  
   - 使用 Jinja2 模板（如 `post_template.html`，可从 `base.html` 继承）渲染完整 HTML，内容区为上述生成的 HTML，标题为文章标题。  
   - 保存到 `generated/<post_id>.html`。  
8. **更新索引**：  
   - 读取 `posts_index.json`，新增一条记录：`{ "id": post_id, "title": title, "date": iso_date, "summary": summary, "thumbnail": 首张图片路径或空 }`。  
   - 按日期倒序排序后写回文件。

### 5.2 列表页渲染（瀑布流）

- 路由 `/` 读取 `posts_index.json`，将文章列表按日期倒序传入模板。  
- 前端使用 CSS Grid 布局实现瀑布流：  
  ```css
  .waterfall {
    display: grid;
    grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
    gap: 1.5rem;
  }
  .card {
    background: white;
    border-radius: 20px;
    box-shadow: 0 4px 12px rgba(0,0,0,0.05);
    overflow: hidden;
    transition: transform 0.2s;
  }
  .card:hover { transform: translateY(-4px); }
  ```  
- 每个卡片包含：文章标题、日期、摘要、若存在缩略图则显示在卡片顶部。缩略图可从索引的 `thumbnail` 字段获取。

### 5.3 文章详情页

- 路由 `/post/<post_id>` 使用 `send_from_directory` 返回 `generated` 目录下的 `<post_id>.html`。  
- 若文件不存在，返回 404 页面（可自定义模板）。  
- 生成的静态页面中已包含 MathJax 脚本，正文中的 LaTeX 会被自动渲染。

### 5.4 管理功能

- **管理页面**：`GET /admin`，读取索引展示所有文章，提供删除按钮（需注意 CSRF，可简单用 POST 表单）。  
- **删除文章**：`POST /admin/delete/<post_id>`，执行以下操作：  
  - 删除 `generated/<post_id>.html`  
  - 删除 `posts_data/<post_id>/` 整个目录  
  - 删除 `static/uploads/posts/<post_id>/` 整个目录  
  - 从 `posts_index.json` 中移除该条目并保存  
  - 重定向回 `/admin`

## 6. 数据格式设计

### 6.1 `posts_index.json` 结构

```json
[
  {
    "id": "1703123456789",
    "title": "Python 中的装饰器",
    "date": "2023-12-21T10:30:00",
    "summary": "装饰器是 Python 一个强大的功能...",
    "thumbnail": "/static/uploads/posts/1703123456789/code.png"
  },
  ...
]
```

### 6.2 Markdown Front Matter 建议（可选）

若用户希望在 Markdown 文件头部定义元数据，支持以下格式：

```yaml
---
title: 文章标题
date: 2024-01-01
summary: 自定义摘要
---
```

可使用 `python-frontmatter` 库解析，若未安装则回退到正则或忽略。在本设计中推荐使用，但非强制。

## 7. 关键实现细节

### 7.1 图片路径修正函数

在渲染 Markdown 之前，预处理文本：

```python
def fix_image_paths(md_content: str, post_id: str) -> str:
    pattern = r'!\[([^\]]*)\]\(([^)]+)\)'
    def repl(match):
        alt, src = match.groups()
        # 仅当 src 不含 '/' 或 'http' 且扩展名为图片时视为本地文件
        if not src.startswith(('http://', 'https://', '/', '#')) and '.' in src:
            new_src = f"/static/uploads/posts/{post_id}/{src}"
            return f'![{alt}]({new_src})'
        return match.group(0)
    return re.sub(pattern, repl, md_content)
```

### 7.2 Markdown 渲染配置

```python
import markdown
md = markdown.Markdown(extensions=[
    'extra',
    'codehilite',
    'tables',
    'fenced_code'
])
html_body = md.convert(fixed_md)
```

### 7.3 摘要提取（无 Front Matter 时）

```python
from bs4 import BeautifulSoup
soup = BeautifulSoup(html_body, 'html.parser')
text = soup.get_text()
summary = text[:200] + ('...' if len(text) > 200 else '')
```

### 7.4 缩略图提取

优先使用 Front Matter 中指定的 `thumbnail`，否则取正文中第一张图片的 URL。

## 8. 前端样式设计要点

### 8.1 整体风格

- 背景色：`#f8fafc`（浅灰色），卡片纯白 `#ffffff`，圆角大半径（20px）。  
- 字体：系统默认无衬线（-apple-system, BlinkMacSystemFont, "Segoe UI"）。  
- 导航栏：半透明白色毛玻璃效果，包含 “博客”、“上传”、“管理” 链接。  
- 响应式：移动端禁用悬停效果，栅格 `minmax(250px,1fr)`。

### 8.2 卡片内容

- 若缩略图存在：`<img>` 宽度 100%，高度 180px，object-fit: cover。  
- 标题：粗体，大小 1.25rem，上下边距。  
- 日期：小字，灰色。  
- 摘要：浅灰色文字，行高 1.5。  
- 底部可加 “阅读全文 →” 链接，指向 `/post/<id>`。

### 8.3 代码高亮

使用 Pygments 生成 CSS 类，在 `style.css` 中引入一个默认高亮主题（如 `monokai` 或 `friendly`）。需在 Markdown 渲染时启用 `codehilite` 扩展并生成对应 HTML。

### 8.4 MathJax 配置

在 `base.html` 中添加：

```html
<script src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml.js" id="MathJax-script" async></script>
```

并设置 `tex: { inlineMath: [['$', '$'], ['\\(', '\\)']] }`。

## 9. 路由概览

| 路径 | 方法 | 说明 |
|------|------|------|
| `/` | GET | 首页，瀑布流文章列表 |
| `/upload` | GET | 显示上传表单 |
| `/upload` | POST | 处理上传，保存文章并生成静态页 |
| `/post/<post_id>` | GET | 查看静态文章详情 |
| `/admin` | GET | 管理页面，列出所有文章 |
| `/admin/delete/<post_id>` | POST | 删除文章及相关文件 |
| `/static/<path:filename>` | GET | Flask 默认静态文件路由（用于 CSS、JS、图片） |

## 10. 部署与运行说明

1. 安装依赖：`pip install -r requirements.txt`  
2. 运行：`python app.py`（默认监听 `0.0.0.0:5000`）  
3. 使用生产服务器时，可将 `generated/` 目录通过 Nginx 直接托管提升性能，但 Flask 本身也可完成。

## 11. 扩展建议

- 支持 RSS 订阅：从索引生成 XML。  
- 添加文章标签系统：在索引中增加 `tags` 列表，前端做筛选。  
- 缓存优化：列表页可定期重新生成静态文件。  
- 图片压缩/缩略图生成：使用 Pillow 在上传时生成不同尺寸。

---

> 本设计文档已覆盖完整架构、目录结构、核心代码逻辑及样式取向。请后续根据本设计实现具体代码。