Confluence¶

Ứng dụng Code To UML trên Confluence dành cho người muốn tạo sơ đồ bằng macro hoặc chuyển code block có sẵn thành sơ đồ khi publish trang.

Trước khi bắt đầu¶

Quản trị viên phải cài ứng dụng Code To UML cho Confluence site. Người dùng không cần nhập token trong macro editor.

Tạo diagram bằng macro editor¶

Chỉnh sửa Confluence page.
Mở menu macro và chọn Code To UML.
Chọn mẫu hoặc dán fenced diagram.
Nếu cần, nhập tên để nhận diện diagram.
Chờ live preview hiển thị.
Chọn Save diagram.
Publish page và kiểm tra diagram.

Ví dụ:

```mermaid {theme=default}
flowchart LR
  Draft --> Review
  Review --> Publish
```

Kết quả mong đợi: macro được lưu ở vị trí đã chèn và diagram hiển thị sau khi publish.

Mở lại macro editor để sửa mã sơ đồ. Nếu live preview báo lỗi, sửa mã trước khi lưu.

Chuyển code block thành macro khi publish¶

Thêm code block vào page.
Chọn language của loại sơ đồ, ví dụ plantuml hoặc mermaid.
Nhập mã sơ đồ và tùy chọn.
Publish page.
Reload page nếu cần và xác nhận code block đã trở thành Code To UML macro.

Ứng dụng chỉ chuyển code block có ngôn ngữ được hỗ trợ và mã sơ đồ hợp lệ. Đoạn văn, heading và code block thông thường được giữ nguyên. Nếu mã quá lớn hoặc loại sơ đồ không được phép, code block vẫn được giữ để bạn không mất nội dung.

Chỉnh sửa và đọc diagram đã publish¶

Trên page đã publish, viewer hỗ trợ:

Pan và zoom.
Fullscreen.
Reset góc nhìn.
Tải sơ đồ dưới dạng SVG.
Sao chép mã sơ đồ.
Ẩn hoặc hiện mã sơ đồ.

Các thao tác này chỉ thay đổi cách xem trong trình duyệt, không sửa mã đã lưu. Muốn thay đổi diagram, mở macro editor rồi publish lại page.

Để tải file, mở toolbar của sơ đồ và chọn Download SVG. File dùng title của sơ đồ làm tên; nếu chưa đặt title, ứng dụng dùng tên loại sơ đồ hoặc diagram. Nút này có trong cả viewer của trang đã publish và live preview của macro editor.

Tùy chỉnh diagram¶

Đặt tùy chọn trong fence hoặc dùng directive %%krokup. Khi code block được chuyển thành macro, các tùy chọn hợp lệ được giữ cùng mã sơ đồ.

Xem Diagram Customization để thay theme, scale, background hoặc direction.

Khi dùng Pydia¶

Pydia chạy Python và có thể bị tắt theo site hoặc Confluence space. Nếu Pydia bị từ chối, hãy dùng loại sơ đồ khác hoặc gửi tên space cho quản trị viên kiểm tra.

Xử lý sự cố¶

Hiện tượng	Cách xử lý
Không tìm thấy macro	Xác nhận app đã được cài cho đúng Confluence site
Live preview lỗi	Kiểm tra ngôn ngữ, mã sơ đồ và dấu đóng fence
Không thể lưu macro	Sửa mã sơ đồ tới khi preview thành công
Code block không được chuyển	Chọn ngôn ngữ được hỗ trợ rồi publish lại
Pydia bị từ chối	Liên hệ quản trị viên và cung cấp tên Confluence space
Sơ đồ bị chặn sau khi render	Loại bỏ liên kết hoặc nội dung nhúng bên ngoài khỏi mã sơ đồ
Không kết nối được Code To UML	Báo quản trị viên kèm thời điểm và trang gặp lỗi

Hướng dẫn cài đặt ứng dụng, cấu hình token, quyền kết nối và chính sách Pydia dành cho quản trị viên nằm trong Operations.