argon-theme/.kiro/specs/mermaid-codeblock-magic/requirements.md

# Requirements Document: Mermaid 代码块渲染修复

## Introduction

本规范旨在修复 Argon WordPress 主题中 Mermaid 图表渲染的关键问题。当前实现存在以下严重问题：

**核心问题：**
1. **PJAX 加载后显示原始文本**：点击文章卡片后，Mermaid 图表显示为纯文本，没有任何样式
2. **语法解析错误**：日志显示 `flowchart`、`erDiagram`、`stateDiagram` 等语法解析失败
3. **图片导出功能缺失**：无法导出 PNG/SVG 格式的图表
4. **全屏查看体验差**：全屏查看应该复用图片查看组件，提供统一的交互体验

**优化目标：**
1. 修复 PJAX 页面切换后 Mermaid 图表不渲染的问题
2. 解决 Mermaid 语法解析错误
3. 实现图表导出功能（PNG/SVG）
4. 优化全屏查看体验，复用图片查看组件

## Glossary

- **PJAX**: 使用 Ajax 和 pushState 实现的页面无刷新跳转技术
- **Mermaid**: 基于文本的图表生成库，支持流程图、时序图、ER图等
- **Code Block**: 代码块，包含 Mermaid 图表定义的 HTML 元素
- **Syntax Error**: 语法错误，Mermaid 解析图表定义时遇到的错误
- **Render**: 渲染，将 Mermaid 文本定义转换为 SVG 图表
- **Export**: 导出，将渲染后的图表保存为图片文件
- **Lightbox**: 图片查看组件，用于全屏查看图片
- **Zoomify**: 图片缩放库，提供缩放和拖拽功能

## Requirements

### Requirement 1: PJAX 页面切换后 Mermaid 渲染

**User Story:** 作为用户，我希望通过 PJAX 跳转到文章页面后，Mermaid 图表能正常渲染，而不是显示原始文本。

#### Acceptance Criteria

1. WHEN 用户点击文章卡片 THEN THE System SHALL 通过 PJAX 加载新页面
2. WHEN PJAX 加载完成 THEN THE System SHALL 检测页面中的 Mermaid 代码块
3. WHEN 检测到 Mermaid 代码块 THEN THE System SHALL 渲染这些代码块为 SVG 图表
4. WHEN 渲染完成 THEN THE System SHALL 显示图表，而不是原始文本
5. WHEN 页面刷新后 THEN THE System SHALL 同样能正常渲染 Mermaid 图表

### Requirement 2: Mermaid 语法解析错误修复

**User Story:** 作为用户，我希望 Mermaid 图表能正确解析各种图表类型，不出现语法错误。

#### Acceptance Criteria

1. WHEN Mermaid 库加载时 THEN THE System SHALL 检查库版本和 API 兼容性
2. WHEN 解析 flowchart 语法 THEN THE System SHALL 正确识别并渲染流程图
3. WHEN 解析 erDiagram 语法 THEN THE System SHALL 正确识别并渲染 ER 图
4. WHEN 解析 stateDiagram 语法 THEN THE System SHALL 正确识别并渲染状态图
5. WHEN 遇到语法错误 THEN THE System SHALL 显示友好的错误提示，而不是抛出未捕获的异常
6. WHEN 清除缓存后首次加载 THEN THE System SHALL 等待 Mermaid 库完全加载后再渲染

### Requirement 3: Mermaid 代码块检测

**User Story:** 作为开发者，我希望系统能准确检测页面中的 Mermaid 代码块。

#### Acceptance Criteria

1. WHEN 页面加载完成 THEN THE System SHALL 扫描所有 `<pre><code>` 元素
2. WHEN 检测代码块 THEN THE System SHALL 识别 `language-mermaid` 类名
3. WHEN 检测代码块 THEN THE System SHALL 识别 `mermaid` 类名
4. WHEN 检测代码块 THEN THE System SHALL 提取代码块中的 Mermaid 定义文本
5. WHEN 代码块已渲染 THEN THE System SHALL 跳过该代码块，避免重复渲染

### Requirement 4: Mermaid 渲染流程优化

**User Story:** 作为开发者，我希望 Mermaid 渲染流程稳定可靠，能处理各种边缘情况。

#### Acceptance Criteria

1. WHEN 开始渲染 THEN THE System SHALL 检查 Mermaid 库是否已加载
2. WHEN Mermaid 库未加载 THEN THE System SHALL 等待库加载或显示错误提示
3. WHEN 渲染图表 THEN THE System SHALL 使用唯一的图表 ID，避免冲突
4. WHEN 渲染成功 THEN THE System SHALL 替换原始代码块为渲染后的容器
5. WHEN 渲染失败 THEN THE System SHALL 保留原始代码块并显示错误信息
6. WHEN 渲染多个图表 THEN THE System SHALL 按顺序渲染，避免并发冲突

### Requirement 5: 图表导出功能

**User Story:** 作为用户，我希望能将 Mermaid 图表导出为图片文件，方便保存和分享。

#### Acceptance Criteria

1. WHEN 鼠标悬停在图表上 THEN THE System SHALL 显示工具栏
2. WHEN 工具栏显示 THEN THE System SHALL 包含导出按钮
3. WHEN 点击导出按钮 THEN THE System SHALL 显示导出选项（PNG、SVG）
4. WHEN 选择 PNG 导出 THEN THE System SHALL 将 SVG 转换为 PNG 并下载
5. WHEN 选择 SVG 导出 THEN THE System SHALL 将 SVG 代码保存为文件并下载
6. WHEN 导出失败 THEN THE System SHALL 显示友好的错误提示

### Requirement 6: 全屏查看功能优化

**User Story:** 作为用户，我希望全屏查看 Mermaid 图表时，能获得与查看图片相同的体验。

#### Acceptance Criteria

1. WHEN 工具栏显示 THEN THE System SHALL 包含全屏按钮
2. WHEN 点击全屏按钮 THEN THE System SHALL 使用图片查看组件（Zoomify）打开图表
3. WHEN 全屏模式下 THEN THE System SHALL 支持缩放、拖拽、旋转等操作
4. WHEN 全屏模式下 THEN THE System SHALL 支持键盘快捷键（ESC 退出、方向键切换）
5. WHEN 退出全屏 THEN THE System SHALL 恢复原始页面状态

### Requirement 7: 错误处理和降级

**User Story:** 作为开发者，我希望系统能优雅地处理各种错误情况。

#### Acceptance Criteria

1. WHEN Mermaid 库加载失败 THEN THE System SHALL 显示错误提示并保留原始代码
2. WHEN 图表语法错误 THEN THE System SHALL 显示错误信息和错误位置
3. WHEN 渲染超时 THEN THE System SHALL 取消渲染并显示超时提示
4. WHEN 浏览器不支持 SVG THEN THE System SHALL 显示不支持提示
5. WHEN 导出功能不可用 THEN THE System SHALL 隐藏导出按钮

### Requirement 8: 性能优化

**User Story:** 作为用户，我希望 Mermaid 图表渲染快速流畅，不影响页面性能。

#### Acceptance Criteria

1. WHEN 页面包含多个图表 THEN THE System SHALL 使用批量渲染，避免阻塞
2. WHEN 图表不在视口内 THEN THE System SHALL 延迟渲染，优先渲染可见图表
3. WHEN 渲染图表 THEN THE System SHALL 显示加载动画，提供视觉反馈
4. WHEN 渲染完成 THEN THE System SHALL 使用淡入动画，提升视觉体验
5. WHEN PJAX 切换页面 THEN THE System SHALL 清理旧图表实例，避免内存泄漏

### Requirement 9: 主题同步

**User Story:** 作为用户，我希望 Mermaid 图表主题能自动跟随网站主题切换。

#### Acceptance Criteria

1. WHEN 网站使用日间模式 THEN THE System SHALL 使用 Mermaid 的 default 主题
2. WHEN 网站切换到夜间模式 THEN THE System SHALL 自动切换 Mermaid 到 dark 主题
3. WHEN 主题切换时 THEN THE System SHALL 重新渲染所有图表
4. WHEN 主题切换时 THEN THE System SHALL 保持图表的缩放级别和位置
5. WHEN 主题切换失败 THEN THE System SHALL 保留原主题，不影响图表显示

### Requirement 10: 响应式设计

**User Story:** 作为移动端用户，我希望 Mermaid 图表能自适应屏幕大小，操作便捷。

#### Acceptance Criteria

1. WHEN 屏幕宽度小于 768px THEN THE System SHALL 调整工具栏按钮大小
2. WHEN 移动端设备 THEN THE System SHALL 支持触摸操作（缩放、拖拽）
3. WHEN 图表宽度超过屏幕 THEN THE System SHALL 自动缩放图表以适应屏幕
4. WHEN 横屏模式 THEN THE System SHALL 自动调整图表布局
5. WHEN 移动端设备 THEN THE System SHALL 优化触摸事件响应速度

### Requirement 11: 交互体验优化

**User Story:** 作为用户，我希望与 Mermaid 图表交互时体验流畅，操作直观。

#### Acceptance Criteria

1. WHEN 鼠标悬停在图表上 THEN THE System SHALL 显示工具栏，提供操作按钮
2. WHEN 鼠标移出图表 THEN THE System SHALL 自动隐藏工具栏，避免遮挡内容
3. WHEN 工具栏显示 THEN THE System SHALL 使用半透明背景，不完全遮挡图表
4. WHEN 鼠标悬停在按钮上 THEN THE System SHALL 显示按钮功能提示（tooltip）
5. WHEN 点击按钮 THEN THE System SHALL 提供视觉反馈（按下效果、加载动画）
6. WHEN 操作失败 THEN THE System SHALL 显示友好的错误提示
7. WHEN 图表加载中 THEN THE System SHALL 显示加载动画，避免空白闪烁

### Requirement 12: 缩放和拖拽功能

**User Story:** 作为用户，我希望能缩放和拖拽 Mermaid 图表，查看细节。

#### Acceptance Criteria

1. WHEN 使用鼠标滚轮 THEN THE System SHALL 以鼠标位置为中心进行缩放
2. WHEN 缩放时 THEN THE System SHALL 使用 CSS transform 实现硬件加速
3. WHEN 缩放级别改变 THEN THE System SHALL 平滑过渡，避免突兀跳动
4. WHEN 缩放到最小或最大级别 THEN THE System SHALL 禁用对应的缩放按钮
5. WHEN 双击图表 THEN THE System SHALL 智能缩放到合适大小
6. WHEN 拖拽图表 THEN THE System SHALL 改变鼠标光标为抓手样式
7. WHEN 拖拽时 THEN THE System SHALL 禁用文本选择，避免误选
8. WHEN 图表未缩放且完全可见 THEN THE System SHALL 禁用拖拽功能

### Requirement 13: 代码质量保证

**User Story:** 作为开发者，我希望代码质量高，易于维护和扩展。

#### Acceptance Criteria

1. WHEN 编写代码 THEN THE System SHALL 遵循项目代码规范（Tab 缩进、单引号等）
2. WHEN 定义函数 THEN THE System SHALL 添加 JSDoc 注释，说明参数和返回值
3. WHEN 使用变量 THEN THE System SHALL 优先使用 let 和 const，避免 var
4. WHEN 处理异步操作 THEN THE System SHALL 使用 async/await 或 Promise
5. WHEN 添加事件监听器 THEN THE System SHALL 确保在清理时移除监听器
6. WHEN 操作 DOM THEN THE System SHALL 批量操作，避免频繁重排重绘
7. WHEN 使用第三方库 THEN THE System SHALL 检查库是否存在，提供降级方案

### Requirement 14: 错误日志和调试

**User Story:** 作为开发者，我希望能方便地调试和排查问题。

#### Acceptance Criteria

1. WHEN 启用调试模式 THEN THE System SHALL 在控制台输出详细的渲染日志
2. WHEN 渲染开始 THEN THE System SHALL 记录图表 ID、代码长度、渲染时间
3. WHEN 渲染成功 THEN THE System SHALL 记录成功信息和渲染耗时
4. WHEN 渲染失败 THEN THE System SHALL 记录错误类型、错误信息、错误堆栈
5. WHEN 发生异常 THEN THE System SHALL 记录上下文信息（图表代码、配置等）
6. WHEN 性能异常 THEN THE System SHALL 记录性能指标（渲染时间、内存占用）

### Requirement 15: 兼容性保证

**User Story:** 作为用户，我希望功能在不同浏览器和设备上都能正常工作。

#### Acceptance Criteria

1. WHEN 浏览器不支持 Promise THEN THE System SHALL 使用回调函数实现异步逻辑
2. WHEN 浏览器不支持 requestAnimationFrame THEN THE System SHALL 使用 setTimeout 降级
3. WHEN 浏览器不支持 SVG THEN THE System SHALL 显示不支持提示
4. WHEN 移动端浏览器 THEN THE System SHALL 优化触摸事件处理
5. WHEN 旧版浏览器 THEN THE System SHALL 提供 polyfill 或禁用高级功能

### Requirement 16: 内存管理

**User Story:** 作为开发者，我希望系统能正确管理内存，避免内存泄漏。

#### Acceptance Criteria

1. WHEN PJAX 切换页面 THEN THE System SHALL 清理所有 Mermaid 实例
2. WHEN 清理实例 THEN THE System SHALL 移除所有事件监听器
3. WHEN 清理实例 THEN THE System SHALL 移除所有 DOM 引用
4. WHEN 清理实例 THEN THE System SHALL 清空图表缓存
5. WHEN 重新渲染 THEN THE System SHALL 先清理旧实例，再创建新实例

### Requirement 17: 配置和扩展性

**User Story:** 作为开发者，我希望系统配置灵活，易于扩展。

#### Acceptance Criteria

1. WHEN 初始化 Mermaid THEN THE System SHALL 从全局配置读取主题设置
2. WHEN 配置改变 THEN THE System SHALL 支持动态更新配置
3. WHEN 添加新功能 THEN THE System SHALL 使用模块化设计，易于扩展
4. WHEN 自定义主题 THEN THE System SHALL 支持自定义 Mermaid 主题配置
5. WHEN 禁用功能 THEN THE System SHALL 支持通过配置禁用特定功能

### Requirement 18: 安全性

**User Story:** 作为开发者，我希望系统能防止 XSS 攻击和其他安全问题。

#### Acceptance Criteria

1. WHEN 渲染图表 THEN THE System SHALL 使用 Mermaid 的安全模式（securityLevel）
2. WHEN 处理用户输入 THEN THE System SHALL 转义特殊字符，防止 XSS
3. WHEN 导出图表 THEN THE System SHALL 验证文件名，防止路径遍历
4. WHEN 执行脚本 THEN THE System SHALL 使用沙箱环境，限制权限
5. WHEN 加载外部资源 THEN THE System SHALL 验证来源，防止 CSRF