Confluence

Confluence Code To UML là Forge app giúp người viết có thể soạn sơ đồ trong macro editor hoặc để app chuyển code block thành macro khi trang được publish. Cả hai cách đều render qua Code To UML Gateway mà không đưa token xuống browser.

1. Cách sử dụng

Để soạn trực tiếp bằng macro:

1. Chèn macro Code To UML từ menu của Confluence.
2. Nhập tên nếu cần, dán fenced diagram hoặc chọn một Code Template.
3. Kiểm tra live preview rồi chọn Save diagram.

Để chuyển code block đã có:

1. Thêm code block có language renderer, ví dụ mermaid hoặc plantuml.
2. Nhập diagram source và params nếu cần, sau đó publish trang.
3. Page event chuyển code block phù hợp thành macro.

Mở lại macro editor để sửa source đã lưu. Trên trang đã publish, viewer hỗ trợ pan và zoom, fullscreen, reset, copy code và ẩn hoặc hiện source.

2. Nội dung được chuyển đổi

Nội dung	Kết quả trên trang
Paragraph hoặc heading	Giữ đúng thứ tự đọc
Fence diagram	Macro Code To UML
Fence không phải diagram	Code block giữ nguyên
Native diagram block	Macro Code To UML

Fence params được chuyển thành một dòng %%krokup trước khi resolver gọi Gateway. Diagram bị bỏ qua vì renderer không hỗ trợ hoặc source quá lớn vẫn được giữ dưới dạng code block.

3. Cấu hình Forge

Biến	Bắt buộc	Ý nghĩa
RENDER_API_TOKEN	Có	Bearer token, lưu dạng encrypted Forge variable
RENDER_BASE_URL	Không	HTTPS base URL của Gateway
ALLOW_PYDIA	Không	Opt-in Pydia ở tầng Confluence
PYDIA_ALLOWED_SPACE_IDS	Không	Danh sách numeric space ID được phép dùng Pydia

Token chỉ tồn tại ở backend resolver. Page ADF, macro config và Custom UI không chứa token.

4. Deploy và install

Chạy trong confluence-code-to-uml-poc/:

npm install
npm --prefix static/code-to-uml install
npm test
npm run build
forge variables set -e production RENDER_API_TOKEN <token> --encrypt
forge deploy -e production
forge install --environment production --product Confluence --site <site>.atlassian.net

Thay đổi scope hoặc permission trong manifest.yml cần forge install --upgrade. Đổi Gateway host cần cập nhật cả RENDER_BASE_URL và backend fetch allow-list trong manifest.yml, sau đó deploy lại app.

5. Bảo mật SVG và Pydia

Resolver giới hạn source 200 KiB, timeout 25 giây và SVG 4 MiB. Response phải có image/svg+xml; script, event handler, active embed và URI nguy hiểm bị chặn. SVG được hiển thị qua Blob URL trong <img> của Forge sandbox.

Pydia chỉ hoạt động khi ALLOW_PYDIA=true và space ID nằm trong PYDIA_ALLOWED_SPACE_IDS. Tránh wildcard * vì mọi page editor trong mọi space có thể gửi Python source tới sandbox.

6. Xử lý lỗi

Hiện tượng	Cách xử lý
Rendering token is not configured	Đặt encrypted RENDER_API_TOKEN đúng environment
Pydia bị từ chối	Bật opt-in và thêm numeric space ID
SVG bị policy chặn	Kiểm tra active content hoặc external resource trong output
HTTP 400	Kiểm tra diagram source và fence đóng đúng
Không thể lưu macro	Sửa source cho tới khi live preview thành công