文档
模块和扩展
交互式美人鱼图集成指南
＃＃ 介绍
在现代技术文档和网络出版中，一张图片胜过一千行文字。可视化复杂的工作流程、系统架构和生命周期状态有助于读者快速消化技术细节。
PolyCMS 集成了本机 自托管 Mermaid.js 渲染管道，而不是依赖繁重、不可搜索的静态图像文件或缓慢的第三方 CDN（这些文件会增加页面延迟并降低隐私性）。本指南介绍了如何动态编译图表，介绍了交互式可视化 TipTap 编辑器元素，并演示了从简单流程到 PolyCMS 整体架构的四个图表示例。
技术架构&自托管策略
PolyCMS 专为速度和绝对主权而构建。核心渲染器动态解析原始块元素。当一个块被标记为图表时：
解析器检测 ：PHP 动态引擎 (helpers.php) 扫描以 <pre><code class="language-mermaid"> 开头的标准 Markdown 块。
安全实体解码 ：它安全地解码 HTML 实体（e.g。将 --> 转换回原始解析器就绪的 --> 语法）。
离线资产 ：PolyCMS 不是请求 jsDelivr 或 cdnjs，而是通过 Laravel asset('assets/vendor/mermaid-10.x/mermaid.min.js') 帮助程序在本地解析脚本。
Vercel 启发的主题变量 ：管理可视化编辑器和公共前端都使用自定义的类似 Vercel 的基本变量渲染图表，在浅色和深色模式下提供高对比度、干净的简约美感。
图表预设和示例
以下是在 PolyCMS 中本地运行的四个经典图表实现。
1. 简单流程图：用户身份验证生命周期（水平 - LR）
一个简单的从左到右的流程图，显示会话防护如何解析和验证标准客户端输入。
graph LR
A[输入凭据] --> B{字段是否为空？}
B -->|是| C[显示验证错误]
B -->|否| D[通过 Sanctum 进行身份验证]
D --> E{成功？}
E -->|是| F[重定向到管理面板]
E -->|否| G[显示凭据错误]
2.状态图：电子商务交易生命周期（StateDiagram-v2）
状态图描述了通过 PayPal 或 SePay 支付网关进行的在线购买交易可能的状态转换。
stateDiagram-v2
[*] --> 新建
新建 --> 待处理 : 客户结账
待处理 --> 已完成 : 付款已确认
待处理 --> 已失败 : 付款超时 / 失败
已失败 --> 待处理 : 客户重试
已完成 --> [*]
3. 中间序列图：安全 REST API 请求流
序列图展示了客户、Web 客户端、API 网关和数据库之间的安全来回交互，以提供经过令牌验证的内容。
sequenceDiagram
participant User as 开发者或用户
participant App as API 客户端
participant Auth as API 网关
participant DB as 核心数据库
User->>App: 发送带有 Bearer Token 的 API 请求
App->>Auth: GET /api/v1/posts (Auth Header)
Auth->>Auth: 验证令牌签名和作用域
Auth->>DB: 查询文章（按分类过滤）
DB-->>Auth: Eloquent collection retrieved
Auth-->>App: JSON Response (200 OK + Data)
App-->>User: 呈现格式化的数据数组
PolyCMS 核心架构工作流程（复杂 - TD）
为了演示复杂的垂直布局，这里是 PolyCMS 的完整技术架构管道。它概述了帖子如何从数据库传输，通过动态块编译器，解析短代码/Mermaid 标签，应用受 WordPress 启发的钩子/过滤器钩子，最后输出高级 Vercel 风格的 HTML 视图。
graph TD
%% Define Node Shapes
DB[(MySQL or PostgreSQL Database)]
Engine[ContentRenderer Core Engine]
JsonParser{Parse block JSON content_raw?}
HtmlFallback[Fallback to content_html]
TiptapParse[TipTap NodeView Reconstitution]
Helper[app/helpers.php Processing Pipeline]
HookAction[Phase 1: Filter content.render.html]
ModalOverlay[Phase 2: Extract Modal Links & YT Sliders]
MermaidParse[Phase 3: Decode Mermaid Graph syntax]
AssetLoader[Inject Dynamic Self-Hosted Assets]
VercelTheme[Apply Premium Vercel CSS themeVariables]
FinalView[最终网页视图渲染的 HTML]
%% Flow lines
DB -->|获取文章数据负载| Engine
Engine --> JsonParser
JsonParser -->|是 - 非空| TiptapParse
JsonParser -->|否 - 空| HtmlFallback
TiptapParse --> Helper
HtmlFallback --> Helper
Helper --> HookAction
HookAction --> ModalOverlay
ModalOverlay --> MermaidParse
MermaidParse --> AssetLoader
AssetLoader --> VercelTheme
VercelTheme --> FinalView
%% Style highlights
style DB fill:#0a0a0a,stroke:#333333,stroke-width:2px,color:#ffffff
style Engine fill:#000000,stroke:#333333,stroke-width:2px,color:#ffffff
style Helper fill:#000000,stroke:#10b981,stroke-width:2px,color:#ffffff
style FinalView fill:#111111,stroke:#10b981,stroke-width:3px,color:#ffffff
交互式 TipTap 图块编辑器
作为 PolyCMS 管理面板的作者，您无需记住 Mermaid 语法即可创建这些漂亮的图形。在块编辑器中：
单击编辑器工具栏上的 美人鱼图 按钮。
优雅的视觉容器将立即内联渲染。
切换到 编辑代码 选项卡，使用帮助按钮（--> Arrow、[Node]、{Decision}）编写语法。
使用模板 下拉列表立即加载标准预设（流程图、序列、状态）并即时修改它们。
如果您的语法不正确，内置编译器会突出显示该行并显示有用的错误横幅，而不会中断您的起草过程！