speckle-server/docs/blazor-ui-module-spec.md

Blazor UI Module Spec

1. Mục tiêu UI

Blazor WebAssembly là giao diện chính cho nền tảng mới. UI cần phục vụ công việc hằng ngày của nhóm BIM/CAD/AEC:

• Quản lý project/model/version.
• Xem mô hình 3D bằng Speckle Viewer.
• Upload file và theo dõi import.
• Tạo issue/comment/review trên model.
• Theo dõi dashboard và hoạt động dự án.
• Quản trị user, quota, job, integration.

UI không phải landing page. Màn hình đầu tiên sau login phải là workspace làm việc.

2. Kiến trúc frontend

Thành phần	Trách nhiệm
Blazor WASM App	Routing, layout, state UI, form, table, panel.
API Client	Typed client gọi REST/GraphQL.
Auth State	Token/session, current user, permission.
Viewer JS Bridge	Wrapper cho @speckle/viewer.
Design System	Component button, table, tabs, dialog, toolbar, status badge.
Realtime Client	SignalR/WebSocket hoặc polling cho job/import/review.

3. Layout tổng thể

3.1 App shell

Thành phần:

• Top bar: project switcher, search, notification, user menu.
• Left navigation: Dashboard, Projects, Issues, Reviews, Files, Admin.
• Main content: route content.
• Right panel: context panel trong viewer hoặc detail pages.

Nguyên tắc:

• Giao diện làm việc dày thông tin, rõ phân cấp.
• Không dùng hero marketing.
• Table/list phải scan nhanh.
• Viewer page ưu tiên không gian model, panel có thể collapse.

4. Route đề xuất

Route	Màn hình
/login	Đăng nhập.
/auth/approve	Approve connector/app.
/	Dashboard cá nhân.
/projects	Danh sách project.
/projects/{projectId}	Project overview.
/projects/{projectId}/models	Model list/tree.
/projects/{projectId}/models/{modelId}	Model detail + versions.
/projects/{projectId}/versions/{versionId}	Version detail.
/projects/{projectId}/viewer/{resourceId}	Viewer page.
/projects/{projectId}/issues	Issue board/list.
/projects/{projectId}/reviews	Review sessions.
/projects/{projectId}/files	File uploads/import jobs.
/projects/{projectId}/settings	Project settings/team/webhook.
/admin	Admin dashboard.
/admin/users	User management.
/admin/jobs	Job monitor.
/admin/audit	Audit logs.

5. Module Login/Auth

5.1 Login page

Chức năng:

• Email/password hoặc SSO nếu có.
• Remember session.
• Error state rõ.
• Redirect về URL trước đó.

5.2 Connector approve page

Chức năng:

• Hiển thị app name, scopes, redirect URL.
• Nút Approve/Deny.
• Nếu app trustByDefault, có thể auto approve theo policy.
• Sau approve redirect về connector callback.

6. Module Dashboard

Mục tiêu: người dùng thấy nhanh việc cần làm.

Widget:

• Recent projects.
• Recent versions.
• My open issues.
• Pending reviews.
• Failed imports.
• Storage usage nếu có quyền.

Filters:

• Project.
• Date range.
• Assigned to me.

7. Module Projects

7.1 Project list

Hiển thị:

• Name, visibility, role, latest activity, model count, issue count.
• Search.
• Filter by role/visibility.
• Create project button.

Actions:

• Open.
• Favorite/pin nếu triển khai.
• Archive/delete nếu owner.

7.2 Project overview

Sections:

• Project summary.
• Latest models.
• Latest versions.
• Open issues.
• Pending reviews.
• File import status.
• Activity feed.

8. Module Models

8.1 Model tree/list

Chức năng:

• Hiển thị model theo cây Architecture/Walls, Structure/Beams.
• Search/filter source app/contributor.
• Create model.
• Rename/update description.
• Delete/archive model.

8.2 Model detail

Tabs:

• Versions.
• Files.
• Issues.
• Reviews.
• Settings.

Version table columns:

• Version id.
• Message.
• Author.
• Source app.
• Created at.
• Total children.
• Status derivative/import.
• Open in viewer.

9. Module Version

Version detail hiển thị:

• Metadata: id, root object, source app, author, created time.
• Parent versions.
• Object count.
• Preview/viewer entry.
• Import/derivative status.
• Related issues/comments/reviews.

Actions:

• Open viewer.
• Mark received nếu cần compatibility.
• Move to model.
• Delete version nếu có quyền.
• Create review.

10. Module Viewer

10.1 Viewer layout

Màn hình:

• Full-height viewer canvas.
• Top toolbar: model/version selector, view mode, section, measure, isolate, fit, saved views.
• Left panel: model/resource tree, filters.
• Right panel: properties, issue/comment/review.
• Bottom status: loading progress, selected count, derivative status.

10.2 Speckle Viewer JS bridge

Blazor gọi JS bridge thay vì gọi trực tiếp viewer internals.

API JS bridge đề xuất:

createViewer(containerId, options)
loadResources(viewerId, resources)
disposeViewer(viewerId)
fitToView(viewerId)
setSectionBox(viewerId, section)
getViewerState(viewerId)
setViewerState(viewerId, state)
getSelection(viewerId)
isolateObjects(viewerId, objectIds)
clearIsolation(viewerId)

Events gửi về Blazor:

• viewerLoaded
• loadProgress
• selectionChanged
• cameraChanged
• objectDoubleClicked
• error

10.3 Viewer states

State cần lưu cho issue/saved view:

• Camera position/target.
• Section box.
• Selected object ids.
• Isolated/hidden object ids.
• Filters.
• Resource ids.
• Screenshot/thumbnail optional.

11. Module File Uploads

Màn hình:

• Upload dropzone.
• File list.
• Import queue.
• Import detail/log.

States:

• Uploading.
• Queued.
• Converting.
• Creating version.
• Completed.
• Failed.
• Cancelled.

Actions:

• Upload file.
• Start import.
• Retry failed.
• Cancel queued/running nếu worker support.
• Open created version.

12. Module Issues

Views:

• List view.
• Board by status.
• Viewer side panel.

Issue fields:

• Title.
• Description.
• Status.
• Priority.
• Assignee.
• Due date.
• Related model/version/object ids.
• Viewer state.
• Comments.

Actions:

• Create issue from viewer selection.
• Update status/assignee/priority.
• Add comment.
• Open issue in viewer.
• Resolve/close.

13. Module Reviews

Review list:

• Name.
• Status.
• Due date.
• Progress.
• Reviewer.

Review detail:

• Items: model/version.
• Viewer open button.
• Decision: approve, reject, approve with comments.
• Related issues.
• Activity.

Workflow:

1. Project manager creates review session.
2. Adds versions and reviewers.
3. Reviewers inspect model in viewer.
4. Reviewers create issues or decision.
5. Manager closes review.

14. Module Search/Properties

Search scopes:

• Projects.
• Models.
• Versions.
• Issues.
• Object properties within current version.

Property panel:

• Object id.
• Speckle type.
• Application id if present.
• Category/level/family/type if indexed.
• Raw JSON expandable for technical users.

15. Module Notifications

Notification types:

• Version created.
• Issue assigned.
• Issue commented.
• Review requested.
• Import failed/completed.
• Approval decision.

Delivery:

• In-app notification.
• Email later.
• Webhook for integrations.

16. Module Admin

Screens:

• System overview.
• Users.
• Apps/connectors.
• Tokens.
• Jobs.
• Storage/quota.
• Audit logs.
• Server settings.

Admin actions:

• Disable user.
• Revoke token.
• Retry/cancel job.
• Configure allowed file types.
• Configure storage limits.
• View audit.

17. Permission behavior in UI

UI phải ẩn hoặc disable action theo quyền:

Permission	UI behavior
No project read	Không hiện project hoặc hiện 403.
Viewer only	Không hiện upload/create/delete.
Reviewer	Hiện issue/review action, không hiện project settings.
Contributor	Hiện upload/model/version action.
Owner	Hiện team/settings/delete.
Admin	Hiện admin global.

Quan trọng: UI chỉ hỗ trợ trải nghiệm; backend vẫn là nơi enforce quyền.

18. Loading/error/empty states

Mọi màn hình chính cần:

• Loading skeleton hoặc progress.
• Empty state có action phù hợp.
• Error state có retry.
• Permission denied state.
• Offline/token expired handling.

Viewer riêng cần:

• Load progress.
• Object stream error.
• Derivative not ready fallback.
• WebGL unsupported message.
• Large model warning nếu browser yếu.

19. MVP UI scope

MVP nên gồm:

• Login/connector approve.
• Project list/create/detail.
• Model list/create/detail.
• Version list/create via connector.
• Viewer page load model.
• File upload/import status.
• Issue create/list/detail.
• Basic review decision.
• Admin jobs basic.

Không cần MVP:

• Full custom dashboard analytics.
• Complex BIM rule builder.
• Advanced saved view groups.
• Real-time collaborative cursor.