Hướng dẫn tích hợp sơ đồ nàng tiên cá tương tác

Last updated on Jun 24, 2026 01:49

Giới thiệu

Trong tài liệu kỹ thuật hiện đại và xuất bản trên web, một bức tranh có giá trị bằng hàng nghìn dòng văn bản. Trực quan hóa các quy trình công việc phức tạp, kiến trúc hệ thống và trạng thái vòng đời giúp người đọc hiểu được các chi tiết kỹ thuật một cách nhanh chóng.

Thay vì dựa vào các tệp hình ảnh tĩnh nặng, không thể tìm kiếm hoặc CDN của bên thứ ba làm chậm làm tăng độ trễ của trang và làm suy giảm quyền riêng tư, PolyCMS tích hợp quy trình hiển thị Self-Hosted Mermaid.js gốc. Hướng dẫn này bao gồm cách các sơ đồ được biên dịch linh hoạt, giới thiệu phần tử soạn thảo TipTap trực quan tương tác và trình bày bốn ví dụ về biểu đồ, từ các luồng đơn giản đến kiến trúc tổng thể của PolyCMS.

Kiến trúc kỹ thuật & Chiến lược tự lưu trữ

PolyCMS được xây dựng cho tốc độ và chủ quyền tuyệt đối. Trình kết xuất lõi phân tích các phần tử khối thô một cách linh hoạt. Khi một khối được đánh dấu là sơ đồ:

Phát hiện trình phân tích cú pháp: Công cụ động PHP (helpers.php) quét các khối Markdown tiêu chuẩn bắt đầu bằng <pre><code class="lingu-mermaid">.
Giải mã thực thể an toàn: Nó giải mã các thực thể HTML một cách an toàn (e.g. chuyển đổi --> trở lại cú pháp --> sẵn sàng cho trình phân tích cú pháp thô).
Tài sản ngoại tuyến: Thay vì yêu cầu jsDelivr hoặc cdnjs, PolyCMS phân giải tập lệnh cục bộ thông qua trình trợ giúp Laravel asset('assets/vendor/mermaid-10.x/mermaid.min.js').
Biến chủ đề lấy cảm hứng từ Vercel: Cả trình chỉnh sửa trực quan của quản trị viên và giao diện người dùng công khai đều hiển thị sơ đồ với các biến cơ sở giống như Vercel tùy chỉnh, mang lại tính thẩm mỹ tối giản rõ ràng, có độ tương phản cao ở cả chế độ Sáng và Tối.

Các cài đặt trước và ví dụ về sơ đồ

Dưới đây là bốn triển khai sơ đồ cổ điển chạy nguyên bản trong PolyCMS.

1. Sơ đồ đơn giản: Vòng đời xác thực người dùng (Ngang - LR)

Biểu đồ luồng đơn giản từ trái sang phải hiển thị cách các đầu vào tiêu chuẩn phía máy khách được phân tích cú pháp và xác thực bởi bộ bảo vệ phiên.

graph LR A[Nhập thông tin đăng nhập] --> B{Các trường có trống không?} B -->|Có| C[Hiển thị lỗi xác thực] B -->|Không| D[Xác thực qua Sanctum] D --> E{Thành công?} E -->|Có| F[Chuyển hướng đến Bảng quản trị] E -->|Không| G[Hiển thị lỗi sai thông tin đăng nhập]

2. Sơ đồ trạng thái: Vòng đời giao dịch thương mại điện tử (StateDiagram-v2)

Sơ đồ trạng thái mô tả các chuyển đổi trạng thái có thể có của giao dịch mua hàng trực tuyến thông qua cổng thanh toán PayPal hoặc SePay.

stateDiagram-v2 [*] --> Mới Mới --> Chờ_xử_lý : Khách hàng thanh toán Chờ_xử_lý --> Hoàn_thành : Thanh toán được xác nhận Chờ_xử_lý --> Thất_bại : Thanh toán hết hạn / Thất bại Thất_bại --> Chờ_xử_lý : Khách hàng thử lại Hoàn_thành --> [*]

3. Sơ đồ trình tự trung gian: Luồng yêu cầu API REST an toàn

Sơ đồ trình tự thể hiện các tương tác qua lại an toàn giữa Khách hàng, Máy khách web, Cổng API và Cơ sở dữ liệu để phân phát nội dung được xác thực bằng mã thông báo.

sequenceDiagram participant User as Nhà phát triển hoặc Người dùng participant App as Ứng dụng khách API participant Auth as Cổng API participant DB as Cơ sở dữ liệu cốt lõi User->>App: Gửi yêu cầu API kèm Bearer Token App->>Auth: GET /api/v1/posts (Auth Header) Auth->>Auth: Xác thực chữ ký & phạm vi của token Auth->>DB: Truy vấn các bài viết (lọc theo taxonomy) DB-->>Auth: Eloquent collection retrieved Auth-->>App: JSON Response (200 OK + Data) App-->>User: Hiển thị mảng dữ liệu đã định dạng

Quy trình làm việc kiến trúc cốt lõi của PolyCMS (Phức tạp - TD)

Để minh họa bố cục dọc phức tạp, đây là quy trình kiến trúc kỹ thuật hoàn chỉnh của PolyCMS. Nó phác thảo cách một bài đăng di chuyển từ Cơ sở dữ liệu, đi qua trình biên dịch khối động, phân tích các thẻ shortcode/Nàng tiên cá, áp dụng móc móc/bộ lọc lấy cảm hứng từ WordPress và cuối cùng xuất ra các chế độ xem HTML theo kiểu Vercel cao cấp.

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 xem web cuối cùng được hiển thị] %% Flow lines DB -->|Lấy dữ liệu bài đăng| Engine Engine --> JsonParser JsonParser -->|Có - Không rỗng| TiptapParse JsonParser -->|Không - Rỗng| 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

Trình chỉnh sửa khối sơ đồ TipTap tương tác

Là tác giả trong Bảng quản trị PolyCMS, bạn không cần phải ghi nhớ cú pháp Nàng tiên cá để tạo ra những đồ họa đẹp mắt này. Trong trình chỉnh sửa khối:

Nhấp vào nút Sơ đồ nàng tiên cá trên thanh công cụ soạn thảo.
Một vùng chứa hình ảnh trang nhã sẽ ngay lập tức hiển thị nội tuyến.
Chuyển sang tab Edit Code để viết cú pháp bằng các nút trợ giúp (--> Arrow, [Node], {Decision}).
Sử dụng trình đơn thả xuống Mẫu để tải ngay các cài đặt trước tiêu chuẩn (Sơ đồ quy trình, Trình tự, Trạng thái) và sửa đổi chúng nhanh chóng.
Nếu cú pháp của bạn không chính xác, trình biên dịch tích hợp sẽ đánh dấu dòng đó và hiển thị biểu ngữ lỗi hữu ích mà không làm gián đoạn quá trình soạn thảo của bạn!