speckle-server/docs/aspnet-blazor-speckle-platform-business-requirements.md

Tài liệu nghiệp vụ nền tảng quản lý mô hình Speckle-compatible

1. Mục tiêu sản phẩm

Xây dựng một nền tảng quản lý, chia sẻ, versioning và xem mô hình 3D/BIM/CAD tương tự Speckle Server, nhưng phát triển mới theo hướng:

• Frontend dùng Blazor WebAssembly.
• Backend dùng ASP.NET Core.
• Database chính dùng PostgreSQL.
• Service xử lý nặng dùng C++ native cho upload object, file import, convert và viewer derivative.
• Viewer 3D dùng lại Speckle Viewer thông qua JavaScript interop thay vì viết lại engine 3D.
• Tương thích Speckle connector ở mức API contract cần thiết để connector hiện tại có thể đăng nhập, upload, pull và tạo version/model.

Mục tiêu nghiệp vụ không phải clone toàn bộ Speckle Server, mà xây một "Speckle-compatible model platform" có core upload/view/version ổn định, sau đó mở rộng thêm các tính năng nghiệp vụ riêng như issue, approval, review, dashboard, kiểm tra BIM, báo cáo và tích hợp nội bộ.

2. Phạm vi tổng thể

2.1 Trong phạm vi

• Quản lý người dùng, đăng nhập, token, app/connector access.
• Quản lý project.
• Quản lý model trong project.
• Quản lý version của model.
• Upload/pull object graph theo contract tương thích Speckle.
• File upload và file import IFC/STL/OBJ.
• View model 3D trên web.
• Large model streaming bằng viewer derivative/tile.
• Comment, issue, markup, review.
• Phân quyền theo project/model/action.
• Dashboard, báo cáo, hoạt động gần đây.
• Webhook/API cho tích hợp.
• Admin configuration, quota, audit log.

2.2 Ngoài phạm vi MVP

• Billing/subscription thương mại đầy đủ.
• Marketplace plugin.
• Full clone workspace/automation/gendo/ACC của Speckle.
• Viết lại Speckle Viewer bằng C# hoặc WebGL thuần.
• Desktop connector mới nếu connector Speckle hiện tại đã đáp ứng.

3. Vai trò người dùng

Vai trò	Mô tả	Quyền chính
System Admin	Quản trị toàn hệ thống	Cấu hình server, user, quota, storage, audit
Organization Admin	Quản trị tổ chức/công ty	Quản lý thành viên, workspace, policy
Project Owner	Chủ dự án	Quản lý project, phân quyền, xóa/sửa project
Project Manager	Quản lý dự án	Theo dõi model, review, issue, approval
Model Author	Người upload/cập nhật model	Upload model, tạo version, sửa metadata
Reviewer	Người kiểm tra/phản hồi	Xem model, comment, issue, approval
Viewer	Người xem	Xem model được cấp quyền
Connector App	Ứng dụng desktop/plugin	Auth, upload object, pull object, tạo version
Conversion Worker	Worker hệ thống	Lấy job import, convert file, publish kết quả

4. Khái niệm nghiệp vụ lõi

Khái niệm	Ý nghĩa trong nền tảng mới	Tương đương Speckle
Project	Không gian chứa model, version, team, issue	Stream/Project
Model	Một nhánh dữ liệu trong project, ví dụ Architecture, Structure	Branch/Model
Version	Một bản phát hành/snapshot của model	Commit/Version
Object	Đơn vị dữ liệu bất biến, lưu JSON object graph	Object
Root Object	Object gốc mà version trỏ tới	referencedObject
Blob	File thô/attachment được upload	Blob storage item
File Import	Quy trình convert file thô thành model/version	File upload/import
Viewer Resource	Thông tin để viewer biết cần load model/version/object nào	Viewer resource
Viewer Derivative	Dữ liệu render tối ưu cho model lớn	Large model derivative
Issue	Vấn đề gắn với model/version/view/camera	Comment/issue mở rộng
Review	Phiên kiểm tra/phê duyệt model/version	Custom

5. Feature 01 - Đăng nhập, tài khoản và token

Mục tiêu

Cho phép người dùng và connector đăng nhập an toàn, nhận token, refresh token và sử dụng API theo scope.

Tác nhân

• Người dùng web.
• Speckle connector.
• Admin.
• Ứng dụng tích hợp bên thứ ba.

Chức năng

• Đăng nhập bằng email/password.
• Đăng nhập SSO/OIDC ở phase sau.
• Tạo token cá nhân.
• Tạo app token cho connector.
• Refresh token.
• Logout/revoke token.
• Quản lý session web bằng cookie hoặc bearer token.
• Hỗ trợ OAuth-like flow tương thích Speckle connector:
  • /auth/accesscode
  • /auth/token

Quy tắc nghiệp vụ

• Token gồm token id và secret, secret chỉ hiển thị một lần khi tạo.
• Token phải có scope rõ ràng: streams:read, streams:write, profile:read, tokens:write, users:read.
• Token có thể giới hạn theo project/workspace.
• Token hết hạn phải tự động invalid.
• Connector chỉ được upload/pull project mà user có quyền.
• Admin có thể revoke token khi cần.

Luồng chính

1. User đăng nhập web.
2. Connector mở browser để xin quyền.
3. Server trả access code về redirect URL của connector.
4. Connector đổi access code lấy token và refresh token.
5. Connector dùng token gọi object/GraphQL API.

Tiêu chí chấp nhận

• Connector hiện tại đăng nhập được mà không cần sửa code connector.
• Token bị revoke không thể gọi API.
• Token thiếu scope bị từ chối đúng lỗi 403.
• Token hết hạn không còn hợp lệ.

6. Feature 02 - Quản lý ứng dụng/connector

Mục tiêu

Cho phép hệ thống nhận diện các ứng dụng như web app, desktop manager, connector, Excel, PowerBI hoặc app nội bộ.

Chức năng

• Seed sẵn default apps tương thích Speckle connector.
• Admin tạo app mới.
• App có id, secret, redirect URL, scope mặc định.
• User xem danh sách app đã cấp quyền.
• User revoke quyền app.

Quy tắc nghiệp vụ

• Default connector app ID phải ổn định để connector cũ dùng được.
• App trusted có thể bỏ qua màn hình consent nếu policy cho phép.
• Khi app scope thay đổi, token cũ phải được xem xét revoke hoặc yêu cầu re-consent.

Tiêu chí chấp nhận

• Connector Desktop/Auth Service đăng nhập bằng app id tương thích.
• App bị xóa không thể tạo token mới.
• User revoke app thì token app hết hiệu lực.

7. Feature 03 - Quản lý Project

Mục tiêu

Project là container chính cho mô hình, team, issue, file, version, dashboard và quyền truy cập.

Chức năng

• Tạo project.
• Cập nhật tên, mô tả, visibility.
• Xóa project.
• Archive project.
• Clone/copy project ở phase sau.
• Danh sách project của user.
• Tìm kiếm project theo tên/mô tả/mã dự án.

Thuộc tính chính

• Project ID.
• Name.
• Description.
• Visibility: Private, Public, Organization, Workspace.
• Owner.
• CreatedAt, UpdatedAt.
• Region/storage location nếu triển khai multi-region.
• Project code/client/job number.

Quy tắc nghiệp vụ

• Project Private chỉ người được mời mới xem được.
• Project Public có thể xem không cần đăng nhập nếu policy cho phép.
• Chỉ Owner/Admin được xóa project.
• Xóa project phải trigger cleanup object/blob/derivative theo job nền.
• Project có model/version thì không hard delete ngay, nên chuyển sang archived hoặc soft delete trước.

Tiêu chí chấp nhận

• User chỉ thấy project mình có quyền.
• Project mới có model mặc định main hoặc cho phép tạo model đầu tiên khi upload.
• Xóa/Archive project không làm connector nhìn thấy project trong danh sách.

8. Feature 04 - Thành viên và phân quyền project

Mục tiêu

Quản lý ai được xem, upload, review, approve và quản trị dữ liệu trong project.

Vai trò project

Role	Quyền
Owner	Toàn quyền, phân quyền, xóa project
Manager	Quản lý model/version/issue/review
Contributor	Upload model, tạo version, comment
Reviewer	Xem, comment, tạo issue, approve nếu được cấp
Viewer	Chỉ xem

Chức năng

• Mời user bằng email.
• Cập nhật role.
• Thu hồi quyền.
• Rời project.
• Danh sách thành viên.
• Pending invitation.
• Public access toggle.

Quy tắc nghiệp vụ

• Project phải luôn có ít nhất một Owner.
• User không thể tự hạ quyền nếu là Owner cuối cùng.
• Role cao hơn kế thừa quyền role thấp hơn.
• Connector dùng quyền của user sở hữu token.
• Public project vẫn có thể giới hạn comment/upload.

Tiêu chí chấp nhận

• Viewer không upload được.
• Contributor upload được nhưng không đổi quyền người khác.
• Reviewer tạo issue/comment nhưng không xóa version nếu không có quyền.

9. Feature 05 - Quản lý Model

Mục tiêu

Model là đơn vị dữ liệu có version riêng trong project, ví dụ Architecture, Structure, MEP, Site, hoặc A/B/C.

Chức năng

• Tạo model.
• Đổi tên model.
• Xóa/archive model.
• Hiển thị tree model theo dấu /.
• Lọc model theo source app, contributor, trạng thái import.
• Pending imported model khi file import chưa xong.

Thuộc tính chính

• Model ID.
• Project ID.
• Name/fullName.
• Display name.
• Description.
• Author.
• CreatedAt, UpdatedAt.
• Preview image.
• Source app gần nhất.

Quy tắc nghiệp vụ

• Trong cùng project, tên model phải unique theo case-insensitive.
• Tên model có thể dùng / để tạo cây thư mục ảo.
• Xóa model phải xử lý version liên quan.
• Model do connector tạo phải map được với branch/model name cũ.

Tiêu chí chấp nhận

• Connector upload vào branch/model main tự tạo nếu chưa có.
• UI hiển thị model tree đúng với tên có /.
• Không cho tạo hai model trùng tên.

10. Feature 06 - Quản lý Version

Mục tiêu

Version là snapshot bất biến của model tại một thời điểm, trỏ tới root object đã upload.

Chức năng

• Tạo version từ connector hoặc web.
• Cập nhật message của version.
• Xóa/archive version.
• Move version sang model khác.
• Danh sách version theo model.
• So sánh version.
• Mark version received khi connector pull.

Thuộc tính chính

• Version ID.
• Project ID.
• Model ID.
• Root object ID.
• Message.
• Source application.
• Author.
• Parents.
• Total children count.
• CreatedAt.
• Preview URL.

Quy tắc nghiệp vụ

• Version immutable về root object; chỉ metadata như message có thể sửa.
• Root object phải tồn tại trong project trước khi tạo version.
• Version có parent dùng để dựng lịch sử/diff.
• Xóa version không xóa ngay object vì object có thể được version khác dùng.

Tiêu chí chấp nhận

• Connector tạo commit/version thành công sau khi upload object.
• Pull latest version lấy đúng root object.
• Version list phân trang và sắp xếp theo thời gian mới nhất.

11. Feature 07 - Object Upload/Pull Core

Mục tiêu

Đây là lõi quan trọng nhất. Hệ thống phải lưu object graph bất biến, dedup theo object id/hash và stream object hiệu quả cho connector/viewer.

Chức năng

• Diff object IDs: client hỏi object nào server đã có.
• Upload batch object.
• Download single object.
• Download root object cùng closure.
• Download batch object theo danh sách ID.
• Stream object dạng gzip.
• Stream object dạng id<TAB>json.
• Hỗ trợ attribute mask cho object stream.

Quy tắc nghiệp vụ

• Object ID phải dài 32 ký tự nếu theo Speckle hash.
• Object là immutable: object cùng ID không được update nội dung.
• Nếu object đã tồn tại thì bỏ qua insert.
• Object thuộc project nào thì chỉ user có quyền project đó đọc/ghi.
• Batch upload phải reject object quá lớn theo cấu hình.
• Không dùng GraphQL cho object payload lớn.

Tiêu chí chấp nhận

• Upload lại cùng model không duplicate object.
• Connector có thể diff -> upload missing -> create version.
• Viewer có thể stream model mà không tải toàn bộ vào memory backend.
• Response format tương thích objectloader Speckle.

12. Feature 08 - File Upload và Blob Storage

Mục tiêu

Cho phép upload file thô như IFC, STL, OBJ, PDF, ảnh attachment, comment attachment.

Chức năng

• Upload blob qua REST multipart.
• Generate presigned upload URL.
• Download blob.
• List blob theo project.
• Delete blob.
• Blob diff để kiểm tra file đã tồn tại.
• Attachment cho comment/issue.

Thuộc tính chính

• Blob ID.
• Project ID.
• User ID.
• File name.
• File type.
• File size.
• File hash.
• Upload status.
• Object storage key.

Quy tắc nghiệp vụ

• Blob upload phải kiểm tra quyền ghi project.
• File import blob không nên hiện lẫn với derivative artifacts.
• Attachment nhỏ có thể hiển thị trong comment/issue.
• Blob bị xóa phải xóa metadata và object storage theo job nền nếu cần.

Tiêu chí chấp nhận

• User upload IFC qua web thành công.
• Worker tải được file từ blob storage bằng token nội bộ hoặc app token.
• User không có quyền không tải được blob private.

13. Feature 09 - File Import và Conversion

Mục tiêu

Chuyển file thô thành model/version có thể xem trên web và pull qua connector nếu cần.

File type ưu tiên

• IFC.
• STL.
• OBJ.
• GLTF/GLB ở phase sau.
• RVT/DWG không xử lý trực tiếp nếu không có license/SDK hợp lệ.

Chức năng

• Start file import sau khi upload.
• Queue job import.
• Worker nhận job.
• Convert file thành Speckle object graph hoặc viewer derivative.
• Tạo model nếu chưa có.
• Tạo version mới.
• Update trạng thái import.
• Trả warning/error cho UI.

Trạng thái import

• Queued.
• Processing.
• Succeeded.
• Failed.
• TimedOut.
• Cancelled.

Quy tắc nghiệp vụ

• File nhỏ/trung bình: convert thành object graph đầy đủ.
• File lớn: tạo root object tối thiểu và viewer derivative/tile.
• Import thất bại không được tạo version lỗi.
• Retry có giới hạn số lần và compute budget.
• User phải thấy tiến độ/trạng thái rõ ràng.

Tiêu chí chấp nhận

• Upload IFC tạo version xem được.
• File lỗi có thông báo dễ hiểu.
• Worker restart không làm mất job.
• Một job không bị hai worker xử lý đồng thời.

14. Feature 10 - Viewer Web bằng Speckle Viewer

Mục tiêu

Người dùng xem, kiểm tra, đo đạc, lọc, comment và review model trong Blazor WebAssembly.

Chức năng

• Load một hoặc nhiều model/version.
• Orbit/pan/zoom.
• Select object.
• Isolate/hide/show object.
• Color by property.
• Section box.
• Measurements: point, distance, perpendicular, area.
• Object snap cho đo đạc.
• Explode.
• View modes.
• Screenshot.
• Saved views.
• Comment bubble/issue marker.
• Compare version/diff.

Quy tắc nghiệp vụ

• Viewer engine dùng @speckle/viewer, Blazor chỉ điều khiển qua JS interop.
• Viewer không tự quyết quyền; backend phải xác thực resource trước.
• Private model cần token hợp lệ để tải object/derivative.
• Saved view phải lưu camera, filter, section box, resource ID.
• Comment/issue phải gắn với resource/version/object/viewer state.

Tiêu chí chấp nhận

• Model upload từ connector mở được trong Blazor viewer.
• Selection trả về object id và property.
• Section/measurement hoạt động trên model bình thường.
• Large model không làm browser full-load object graph nếu derivative có sẵn.

15. Feature 11 - Large Model Viewer Derivative

Mục tiêu

Cho phép mở IFC/model lớn hàng trăm MB bằng tiled binary streaming, tránh browser OOM.

Chức năng

• Detect large model.
• Generate manifest.
• Generate binary tiles.
• Publish derivative artifacts.
• Load manifest.
• Stream tiles theo nhu cầu viewer.
• LOD theo camera/frustum.
• Evict tile theo memory budget.
• Metadata on-demand khi select.

Trạng thái derivative

• Missing.
• Queued.
• Processing.
• Ready.
• Failed.

Quy tắc nghiệp vụ

• Large model không fallback sang full object graph nếu rủi ro OOM.
• Manifest chỉ public khi status Ready.
• Tile/artifact phải immutable theo version.
• Derivative artifacts không tính như user blob thường.
• Selection trên derivative phải map được về element/global ID.

Tiêu chí chấp nhận

• Model lớn hiển thị first render nhanh.
• Browser không tải toàn bộ geometry.
• User thấy thông báo nếu derivative đang processing/failed.
• Tile private không tải được nếu thiếu quyền project.

16. Feature 12 - Comment, Issue và Markup

Mục tiêu

Cho phép trao đổi, phản hồi, tạo vấn đề và lưu ngữ cảnh viewer trên model/version.

Chức năng

• Tạo comment thread.
• Reply comment.
• Edit comment.
• Archive/resolve comment.
• Tạo issue từ viewer.
• Gắn screenshot.
• Gắn camera/viewer state.
• Gắn selected object IDs.
• Mention user.
• Attachment blob.
• Lọc issue theo trạng thái, người phụ trách, model/version.

Issue status

• Open.
• In Review.
• Resolved.
• Closed.
• Reopened.

Issue fields

• Title.
• Description.
• Status.
• Priority.
• Assignee.
• Due date.
• Project/model/version/resource.
• Viewer state.
• Selected object IDs.
• Screenshot.

Quy tắc nghiệp vụ

• Comment thường dùng cho trao đổi nhẹ.
• Issue dùng cho việc cần theo dõi trạng thái.
• Issue phải giữ được viewer context để mở lại đúng vị trí.
• User chỉ thấy issue trong project mình có quyền.
• Archive không hard delete.

Tiêu chí chấp nhận

• Click issue mở viewer đúng camera/section/selection.
• Người được mention nhận notification.
• Reviewer không có quyền edit issue người khác nếu policy không cho phép.

17. Feature 13 - Review và Approval Workflow

Mục tiêu

Cho phép kiểm tra và phê duyệt version/model theo quy trình dự án.

Chức năng

• Tạo review session cho version.
• Chọn reviewer.
• Reviewer approve/reject/request changes.
• Ghi nhận quyết định, ghi chú và thời gian.
• Khóa version khi đã approved nếu policy yêu cầu.
• Dashboard pending reviews.

Trạng thái review

• Draft.
• Submitted.
• In Review.
• Approved.
• Rejected.
• Changes Requested.
• Cancelled.

Quy tắc nghiệp vụ

• Một version có thể có nhiều review session, nhưng chỉ một session active theo loại review.
• Người tạo version không nên tự approve nếu policy yêu cầu separation of duties.
• Approval phải được audit log.
• Reject/Changes Requested nên yêu cầu comment.

Tiêu chí chấp nhận

• Project Manager tạo review cho version.
• Reviewer nhận notification và approve/reject.
• Version hiển thị badge approval status.
• Audit log lưu đầy đủ người quyết định và thời điểm.

18. Feature 14 - Metadata, Property và Search

Mục tiêu

Cho phép tìm kiếm, lọc, thống kê và khai thác property của object/model.

Chức năng

• Xem property object khi select.
• Search object theo name/type/category/property.
• Filter object theo property.
• Group/count theo property.
• Export property table.
• Index metadata sau khi upload/import.

Quy tắc nghiệp vụ

• Metadata object graph có thể rất lớn, cần indexing async.
• Search phải giới hạn theo quyền project.
• Với large derivative, metadata tải on-demand.
• Property key cần normalize để tránh trùng do casing/source app.

Tiêu chí chấp nhận

• User chọn object thấy property.
• User lọc được object theo category/type.
• Search không trả object thuộc project không có quyền.

19. Feature 15 - Dashboard và báo cáo

Mục tiêu

Cung cấp tổng quan dự án, tiến độ model, vấn đề, review và hoạt động.

Chức năng

• Project dashboard.
• Model/version statistics.
• Recent activity.
• Open issue count.
• Review pending count.
• Upload/import status.
• Storage usage.
• Contributor activity.
• Export report PDF/Excel ở phase sau.

Quy tắc nghiệp vụ

• Dashboard phải tôn trọng quyền user.
• Số liệu nặng nên tính async/cache.
• Admin dashboard thấy toàn hệ thống, user dashboard chỉ thấy project liên quan.

Tiêu chí chấp nhận

• Project Manager thấy model mới nhất, issue mở, review pending.
• Admin thấy storage/quota/user activity.

20. Feature 16 - Notification

Mục tiêu

Thông báo cho người dùng khi có hoạt động quan trọng trong project.

Kênh

• In-app notification.
• Email.
• Webhook.
• Slack/Teams ở phase sau.

Sự kiện thông báo

• Được mời vào project.
• Có version mới.
• File import hoàn tất/lỗi.
• Comment reply/mention.
• Issue assigned.
• Review requested.
• Review approved/rejected.

Quy tắc nghiệp vụ

• User có thể cấu hình notification preference.
• Không gửi notification cho hành động do chính user tạo nếu policy không yêu cầu.
• Notification phải có deep link đến project/model/version/issue.

Tiêu chí chấp nhận

• Mention user tạo notification.
• File import fail gửi notification cho uploader.
• User tắt email thì không nhận email nhưng vẫn có in-app.

21. Feature 17 - Activity Stream và Audit Log

Mục tiêu

Ghi nhận hoạt động để truy vết, báo cáo và kiểm tra bảo mật.

Activity cho user/project

• Project created/updated/deleted.
• Model created/updated/deleted.
• Version created/deleted.
• File uploaded/imported.
• Comment/issue/review changes.

Audit bảo mật

• Login/logout.
• Token created/revoked.
• Permission changed.
• Admin configuration changed.
• Failed auth attempts.

Quy tắc nghiệp vụ

• Audit log không cho user thường sửa/xóa.
• Activity có thể public theo project, audit chỉ admin xem.
• Dữ liệu nhạy cảm trong audit phải mask.

Tiêu chí chấp nhận

• Admin xem được ai đổi quyền project.
• Project timeline hiển thị version/comment/issue mới.

22. Feature 18 - Webhook và tích hợp

Mục tiêu

Cho hệ thống khác nhận sự kiện từ nền tảng.

Chức năng

• Tạo webhook endpoint theo project.
• Chọn event types.
• Gửi payload ký chữ ký HMAC.
• Retry khi lỗi.
• Xem delivery history.
• Disable webhook lỗi liên tục.

Event types

• Project updated.
• Model created/updated/deleted.
• Version created/deleted.
• File import completed/failed.
• Issue created/updated.
• Review completed.

Quy tắc nghiệp vụ

• Webhook phải retry có backoff.
• Timeout không được ảnh hưởng request chính.
• Secret chỉ hiển thị khi tạo/rotate.

Tiêu chí chấp nhận

• Tạo webhook và nhận event version created.
• Delivery lỗi được retry.
• Payload có signature để bên nhận verify.

23. Feature 19 - Admin, cấu hình và quota

Mục tiêu

Cho admin vận hành hệ thống an toàn, kiểm soát tài nguyên và policy.

Chức năng

• Quản lý user.
• Quản lý role server.
• Cấu hình đăng ký/mời.
• Cấu hình file size limit.
• Cấu hình object size limit.
• Cấu hình storage provider.
• Quota theo user/project/org.
• Feature flags.
• Health/status page.

Quy tắc nghiệp vụ

• Chỉ System Admin được đổi global config.
• Config quan trọng phải ghi audit.
• Quota vượt giới hạn thì chặn upload/import mới nhưng vẫn cho đọc dữ liệu.

Tiêu chí chấp nhận

• Admin khóa user thì token user không còn dùng được.
• Project vượt quota không upload file mới được.
• Feature flag large model có thể bật/tắt.

24. Feature 20 - API, SDK và Developer Experience

Mục tiêu

Cho developer nội bộ hoặc bên thứ ba tích hợp với nền tảng.

Chức năng

• GraphQL endpoint.
• REST object/blob endpoints.
• OpenAPI cho REST API mới.
• C# SDK chính thức cho backend mới.
• API token management.
• API explorer.
• Rate limit.

Quy tắc nghiệp vụ

• Speckle-compatible endpoints phải ổn định.
• API mới có thể REST/gRPC nhưng không làm connector cũ gãy.
• Breaking change phải versioned.

Tiêu chí chấp nhận

• C# SDK có thể tạo project, upload object, tạo version, load object.
• Connector Speckle gọi endpoint cũ vẫn chạy.

25. Feature 21 - Migration từ Speckle Server hiện tại

Mục tiêu

Chuyển dữ liệu từ Speckle Server hiện tại sang nền tảng mới hoặc chạy song song trong giai đoạn chuyển đổi.

Chức năng

• Import users.
• Import projects/streams.
• Import models/branches.
• Import versions/commits.
• Import objects.
• Import blobs/file uploads.
• Import comments.
• Validate object counts/hash.
• Report migration errors.

Quy tắc nghiệp vụ

• Không đổi object ID khi migrate.
• Version phải trỏ đúng root object cũ.
• Quyền user/project phải giữ tương đương.
• Migration nên chạy repeatable/idempotent.

Tiêu chí chấp nhận

• Project migrated mở được trong viewer mới.
• Connector pull version migrated được.
• Object count và root object match server cũ.

26. Feature 22 - Vận hành, monitoring và reliability

Mục tiêu

Đảm bảo hệ thống ổn định khi upload model lớn, nhiều connector và nhiều worker.

Chức năng

• Health checks.
• Metrics.
• Structured logs.
• Queue monitoring.
• Worker heartbeat.
• Dead-letter jobs.
• Retry policy.
• Backup/restore.
• Storage cleanup jobs.

Quy tắc nghiệp vụ

• Request upload lớn không được làm backend OOM.
• Worker lỗi phải mark job failed hoặc retry được.
• Cleanup không được xóa object/blob còn version tham chiếu.
• Monitoring phải phân biệt lỗi user input và lỗi hệ thống.

Tiêu chí chấp nhận

• Admin thấy worker nào đang offline.
• Job import timeout được retry hoặc failed rõ ràng.
• Backup restore được project mẫu.

27. Roadmap đề xuất

Phase 1 - Core Speckle-compatible MVP

• Auth/token connector.
• Project/model/version.
• Object diff/upload/download.
• Blazor viewer shell nhúng Speckle Viewer.
• Basic permission.
• Upload model từ connector và xem trên web.

Phase 2 - File import và viewer hoàn chỉnh

• Blob upload.
• IFC/STL/OBJ import.
• Comment/issue cơ bản.
• Saved views.
• Preview image.
• Activity stream.

Phase 3 - Large model và C++ native optimization

• C++ conversion worker.
• Viewer derivative manifest/tile.
• Large model loader.
• Metadata on-demand.
• Memory budget/eviction.

Phase 4 - Nghiệp vụ mở rộng

• Review/approval workflow.
• Dashboard/report.
• Webhook/integration.
• BIM checking.
• Advanced permissions/quota.

Phase 5 - Production hardening

• Migration tools.
• Monitoring/alerting.
• HA deployment.
• Backup/restore.
• API/SDK documentation.

28. MVP definition of done

MVP chỉ được xem là đạt nếu:

• Connector đăng nhập được.
• Connector tạo project/model/version hoặc dùng project/model có sẵn.
• Connector upload object qua diff/upload đúng contract.
• Web Blazor mở version và nhúng Speckle Viewer xem được model.
• User có quyền mới xem/upload được.
• Object lưu trong PostgreSQL có hash/dedup đúng.
• File import cơ bản tạo được version mới.
• Không cần clone toàn bộ frontend Speckle hiện tại.

29. Nguyên tắc thiết kế sản phẩm

• Giữ core data contract ổn định trước khi mở rộng UI.
• Không đưa geometry nặng qua GraphQL.
• Không viết lại Speckle Viewer ở giai đoạn đầu.
• Không trộn derivative artifacts với user-visible blob listing.
• Mọi tính năng mới phải gắn được với Project/Model/Version.
• API tương thích connector phải được test bằng golden tests.
• Tính năng nghiệp vụ mới nên xây quanh viewer context: resource, camera, object selection, version.