# Requirements Document

## Introduction

本文档定义了在 Argon WordPress 主题中实现 Mermaid 图表支持功能的需求。Mermaid 是一个基于 JavaScript 的图表和流程图生成工具，允许用户通过文本描述创建各种类型的可视化图表。

由于 WP-Markdown 编辑器的特殊渲染方式（将整个 Mermaid 代码块保存为单行，没有真正的换行符），直接集成 Mermaid 存在技术障碍。本需求文档采用插件集成方案，通过支持 Mermaid 的 WordPress 插件来实现功能。

## Glossary

- **Mermaid**: 基于 JavaScript 的图表生成库，支持流程图、时序图、类图等多种图表类型
- **WP-Markdown**: WordPress Markdown 编辑器，用于在 WordPress 中编辑 Markdown 格式的内容
- **Theme**: Argon WordPress 主题系统
- **Admin**: WordPress 后台管理员
- **CDN**: 内容分发网络，用于加载外部 JavaScript 库
- **Render_Engine**: Mermaid 图表渲染引擎
- **Code_Block**: Markdown 代码块，用于包含 Mermaid 图表定义
- **Theme_Mode**: 主题模式，包括日间模式和夜间模式
- **Settings_Page**: Argon 主题设置页面

## Requirements

### Requirement 1: Mermaid 库加载

**User Story:** 作为开发者，我希望主题能够正确加载 Mermaid 库，以便在文章中渲染图表。

#### Acceptance Criteria

1. WHEN Admin 在设置页启用 Mermaid 支持 THEN THE Theme SHALL 在前端页面加载 Mermaid JavaScript 库
2. WHERE CDN 模式被选择 WHEN 页面加载时 THEN THE Theme SHALL 从指定的 CDN 地址加载 Mermaid 库
3. WHERE 本地镜像模式被选择 WHEN 页面加载时 THEN THE Theme SHALL 从主题目录加载本地 Mermaid 库文件
4. WHEN Mermaid 库加载失败 THEN THE Theme SHALL 在控制台输出错误信息并降级到备用 CDN
5. THE Theme SHALL 仅在包含 Mermaid 代码块的页面加载 Mermaid 库

### Requirement 2: 图表渲染

**User Story:** 作为内容创作者，我希望在文章中使用 Mermaid 语法创建图表，并在前端正确显示。

#### Acceptance Criteria

1. WHEN 文章包含 Mermaid 代码块 THEN THE Render_Engine SHALL 将代码块渲染为可视化图表
2. THE Render_Engine SHALL 支持所有 Mermaid 官方图表类型（流程图、时序图、类图、状态图、甘特图、饼图、Git 图等）
3. WHEN Mermaid 代码语法错误 THEN THE Render_Engine SHALL 显示友好的错误提示信息
4. WHEN 图表渲染成功 THEN THE Theme SHALL 移除原始代码块文本并显示渲染后的 SVG 图表
5. THE Render_Engine SHALL 在 DOM 加载完成后初始化并渲染所有图表

### Requirement 3: 响应式设计

**User Story:** 作为用户，我希望图表能够在不同设备上正确显示，以便在移动端也能查看。

#### Acceptance Criteria

1. WHEN 图表宽度超过容器宽度 THEN THE Theme SHALL 启用横向滚动功能
2. WHEN 用户在移动设备上查看 THEN THE Theme SHALL 自动调整图表大小以适应屏幕宽度
3. THE Theme SHALL 为图表容器设置最大宽度为 100%
4. WHEN 图表高度超过视口高度 THEN THE Theme SHALL 保持图表完整性不进行裁剪
5. THE Theme SHALL 在图表容器上应用响应式 CSS 样式

### Requirement 4: 主题模式适配

**User Story:** 作为用户，我希望图表能够适配夜间模式，以便在不同主题下都有良好的视觉效果。

#### Acceptance Criteria

1. WHEN 用户切换到夜间模式 THEN THE Theme SHALL 自动切换 Mermaid 图表主题为深色主题
2. WHEN 用户切换到日间模式 THEN THE Theme SHALL 自动切换 Mermaid 图表主题为浅色主题
3. THE Theme SHALL 在主题切换时重新渲染所有 Mermaid 图表
4. THE Theme SHALL 确保图表颜色与页面背景色有足够的对比度
5. WHERE Admin 设置了自定义图表主题 THEN THE Theme SHALL 使用自定义主题而不是自动切换

### Requirement 5: 后台设置

**User Story:** 作为管理员，我希望能够在后台配置 Mermaid 功能，以便根据需求调整行为。

#### Acceptance Criteria

1. THE Settings_Page SHALL 提供启用或禁用 Mermaid 支持的开关选项
2. THE Settings_Page SHALL 提供 CDN 地址选择选项（jsDelivr、unpkg、自定义）
3. THE Settings_Page SHALL 提供图表主题选择选项（default、dark、forest、neutral）
4. THE Settings_Page SHALL 提供本地镜像开关选项
5. WHEN Admin 保存设置 THEN THE Theme SHALL 验证 CDN 地址格式的有效性
6. THE Settings_Page SHALL 提供 Mermaid 配置预览功能

### Requirement 6: 样式优化

**User Story:** 作为内容创作者，我希望图表有美观的样式，以便提升文章的视觉质量。

#### Acceptance Criteria

1. THE Theme SHALL 为图表容器添加背景色、圆角和阴影样式
2. THE Theme SHALL 确保图表容器样式与主题整体风格一致
3. WHEN 图表在卡片中显示 THEN THE Theme SHALL 添加适当的内边距
4. THE Theme SHALL 为图表添加淡入动画效果
5. THE Theme SHALL 在夜间模式下调整图表容器的背景色和边框色

### Requirement 7: 错误处理

**User Story:** 作为开发者，我希望系统能够优雅地处理错误，以便快速定位和解决问题。

#### Acceptance Criteria

1. WHEN Mermaid 代码解析失败 THEN THE Theme SHALL 在图表位置显示错误提示信息
2. WHEN Mermaid 库加载失败 THEN THE Theme SHALL 在控制台输出详细的错误日志
3. THE Theme SHALL 在错误提示中包含错误类型和行号信息
4. WHEN 发生错误 THEN THE Theme SHALL 保留原始代码块以便用户修正
5. THE Theme SHALL 提供调试模式选项以输出详细的渲染过程信息

### Requirement 8: 性能优化

**User Story:** 作为用户，我希望图表加载不影响页面性能，以便获得流畅的浏览体验。

#### Acceptance Criteria

1. THE Theme SHALL 仅在包含 Mermaid 代码块的页面加载 Mermaid 库
2. THE Theme SHALL 使用异步方式加载 Mermaid 库
3. THE Theme SHALL 缓存已渲染的图表以避免重复渲染
4. WHEN 页面包含多个图表 THEN THE Theme SHALL 批量渲染以提高性能
5. THE Theme SHALL 使用 CDN 加速 Mermaid 库的加载速度

### Requirement 9: 插件兼容性

**User Story:** 作为管理员，我希望 Mermaid 功能能够与常用的 WordPress 插件兼容，以便灵活选择编辑器。

#### Acceptance Criteria

1. THE Theme SHALL 支持通过 WP Githuber MD 插件创建的 Mermaid 图表
2. THE Theme SHALL 支持通过 Markdown Block 插件创建的 Mermaid 图表
3. THE Theme SHALL 支持通过 Code Syntax Block 插件创建的 Mermaid 图表
4. WHEN 检测到多个 Mermaid 插件 THEN THE Theme SHALL 避免重复加载 Mermaid 库
5. THE Theme SHALL 提供插件兼容性检测功能

### Requirement 10: 代码块识别

**User Story:** 作为开发者，我希望系统能够准确识别 Mermaid 代码块，以便正确渲染图表。

#### Acceptance Criteria

1. THE Theme SHALL 识别 class 属性为 "mermaid" 的 div 元素作为 Mermaid 代码块
2. THE Theme SHALL 识别 language 属性为 "mermaid" 的 pre 或 code 元素作为 Mermaid 代码块
3. THE Theme SHALL 识别 data-lang 属性为 "mermaid" 的元素作为 Mermaid 代码块
4. WHEN 代码块同时包含多个识别标记 THEN THE Theme SHALL 优先使用 class 属性
5. THE Theme SHALL 忽略被注释掉的 Mermaid 代码块