speckle-server/docs/mvp-implementation-plan.md

MVP Implementation Plan

1. Mục tiêu MVP

MVP phải chứng minh hệ thống mới có thể thay thế core Speckle Server cho các luồng quan trọng:

• Speckle Connector đăng nhập được.
• Connector tạo project/model/version được.
• Connector upload và pull object được.
• Blazor web xem được model bằng Speckle Viewer.
• User upload file IFC/STL/OBJ cơ bản và convert thành version.
• Có issue/review cơ bản để thể hiện giá trị nghiệp vụ mở rộng.

2. Nguyên tắc triển khai

• Làm compatibility contract trước UI nâng cao.
• Test bằng connector thật sớm.
• Không viết lại Speckle Viewer.
• Không tối ưu C++ quá sâu trước khi contract object ổn định.
• Mỗi milestone phải có demo chạy được.

3. Milestone 0 - Foundation

Thời lượng gợi ý: 1-2 tuần.

Deliverables:

• Repo solution ASP.NET/Blazor.
• Docker compose local: API, PostgreSQL, Redis/Queue, MinIO.
• Migration framework.
• Logging, health check, config.
• CI build/test basic.

Tasks:

• Tạo solution structure.
• Chọn GraphQL library.
• Chọn queue.
• Tạo base entities và DbContext/migrations.
• Tạo OpenAPI/Swagger.
• Tạo seed default apps.

Done khi:

• docker compose up chạy local.
• API health check OK.
• Blazor gọi được /api/me mock hoặc real.

4. Milestone 1 - Auth và connector login

Thời lượng gợi ý: 2-3 tuần.

Deliverables:

• User login.
• Token storage.
• Default Speckle apps.
• /auth/accesscode.
• /auth/token.
• Scope/role authorization.

Tasks:

• Implement user/password hoặc SSO stub.
• Implement app registry.
• Implement access code flow.
• Implement bearer token validation.
• Implement token scope checks.
• Tạo connector approve UI.
• Viết contract tests cho auth flow.

Done khi:

• Speckle Desktop/Connector có thể add account tới server mới.
• Token dùng được để gọi /graphql.
• Token revoke/logout hoạt động.

5. Milestone 2 - Project/Model/Version GraphQL compatibility

Thời lượng gợi ý: 3-4 tuần.

Deliverables:

• Project CRUD.
• Model CRUD.
• Version CRUD.
• GraphQL schema mới và legacy.
• Mapping Stream/Branch/Commit sang Project/Model/Version.

Tasks:

• Implement tables: projects, project_members, models, versions.
• Implement GraphQL project, stream, streams.
• Implement projectMutations, modelMutations, versionMutations.
• Implement legacy streamCreate, branchCreate, commitCreate.
• Implement permission rules.
• Write GraphQL contract tests from real connector queries.

Done khi:

• Connector tạo project/model/version metadata được.
• Blazor project/model/version list hiển thị dữ liệu thật.

6. Milestone 3 - Object upload/pull core

Thời lượng gợi ý: 4-6 tuần.

Deliverables:

• Object table and repository.
• POST /objects/{projectId}.
• GET /objects/{projectId}/{objectId}.
• GET /objects/{projectId}/{objectId}/single.
• POST /api/diff/{projectId}.
• POST /api/getobjects/{projectId}.
• POST /api/v2/projects/{projectId}/object-stream.

Tasks:

• Implement object id validation/hash compatibility.
• Implement multipart/gzip parsing.
• Implement batch upsert.
• Implement object diff.
• Implement object stream gzip.
• Implement DB cursor/backpressure.
• Implement rate limits and upload size limits.
• Add integration tests with real Speckle object payload.

Done khi:

• Connector push model nhỏ thành công.
• Connector pull model vừa push thành công.
• Upload lại không duplicate object.
• Viewer hoặc test client stream object được.

7. Milestone 4 - Blazor viewer MVP

Thời lượng gợi ý: 3-4 tuần.

Deliverables:

• Blazor app shell.
• Project/model/version pages basic.
• Viewer page.
• JS bridge cho @speckle/viewer.
• Selection/property panel cơ bản.

Tasks:

• Add viewer package/build pipeline.
• Implement JS bridge lifecycle.
• Implement viewer load resources.
• Implement load progress/error states.
• Implement selection callback.
• Implement property panel from selected object.
• Playwright smoke test viewer page.

Done khi:

• User mở version từ Blazor và thấy model 3D.
• Fit/selection/properties hoạt động cơ bản.
• Viewer dispose không leak khi đổi route.

8. Milestone 5 - File upload/import C++ MVP

Thời lượng gợi ý: 4-6 tuần.

Deliverables:

• Blob storage.
• File upload API.
• File upload status UI.
• C++ file import worker MVP.
• Convert ít nhất một định dạng ưu tiên, nên là IFC hoặc OBJ/STL.

Tasks:

• Implement blob metadata and storage.
• Implement presigned upload URL.
• Implement legacy /api/file/{fileType}/{projectId}/{branchName?}.
• Implement file_uploads table and job queue.
• Implement C++ worker job polling/claim.
• Implement conversion output to Speckle-compatible object graph.
• Implement complete/fail callback.
• Create version after conversion.

Done khi:

• User upload file từ Blazor.
• Job chạy và tạo version.
• Version mở được trong viewer.
• File lỗi hiển thị failed và message.

9. Milestone 6 - Viewer derivative MVP

Thời lượng gợi ý: 4-6 tuần, có thể song song sau Milestone 4.

Deliverables:

• viewer_derivatives table.
• Derivative queue.
• C++ derivative worker.
• Manifest/artifact endpoints.
• Viewer fallback logic.

Tasks:

• Implement derivative status.
• Enqueue derivative on version created.
• Implement worker pull object stream.
• Generate manifest/artifacts MVP.
• Upload artifacts.
• Publish/fail endpoints.
• Viewer checks manifest and loads derivative if ready.

Done khi:

• Model lớn có derivative ready.
• Viewer load derivative artifact.
• Nếu derivative chưa ready, viewer fallback object stream.

10. Milestone 7 - Issue/Review MVP

Thời lượng gợi ý: 3-4 tuần.

Deliverables:

• Issue CRUD.
• Comment thread basic.
• Review session and decision.
• Viewer create issue from selection.

Tasks:

• Implement issues/comments/review tables.
• Implement issue API.
• Implement review API.
• Implement issue list and side panel.
• Store viewer state in issue.
• Open issue in viewer restores camera/selection.

Done khi:

• Reviewer tạo issue từ model.
• PM tạo review và reviewer approve/reject version.
• Issue/review hiện trên project dashboard.

11. Milestone 8 - Admin/Operations MVP

Thời lượng gợi ý: 2-3 tuần.

Deliverables:

• Admin users basic.
• Job dashboard.
• Audit log.
• Storage usage.
• Retry failed job.

Tasks:

• Implement audit logging.
• Implement admin APIs.
• Implement job list/retry/cancel.
• Implement metrics dashboards or endpoint.
• Add health checks for DB/storage/queue/worker.

Done khi:

• Admin thấy failed jobs và retry được.
• Admin revoke token/disable user được.
• Audit log ghi hành động quan trọng.

12. Workstream song song

Workstream	Có thể chạy song song với
Blazor UI shell	Auth/backend foundation.
C++ file importer prototype	Object API design.
Viewer JS bridge prototype	Project/model/version API.
Contract test harness	Tất cả milestone.
Data migration research	Sau khi data model draft ổn định.

13. Backlog ưu tiên P0

P0 bắt buộc cho MVP:

• Auth connector.
• GraphQL legacy project/model/version.
• Object upload/pull REST.
• Blazor viewer.
• File upload/import một định dạng.
• Permission core.
• Contract tests.

14. Backlog ưu tiên P1

P1 sau MVP:

• Large model derivative.
• Issue/review đầy đủ.
• Search property.
• Webhook.
• Admin quota.
• Migration tool từ Speckle Server.
• Notifications.

15. Backlog ưu tiên P2

P2:

• BIM rule engine.
• Advanced dashboard/report.
• Saved view groups.
• Multi-tenant organization/workspace.
• SSO enterprise.
• CDN/multi-region.

16. Test strategy

16.1 Unit tests

• Token creation/validation.
• Permission engine.
• Object hash/id validation.
• Project/model/version mapping.
• Job state transitions.

16.2 Integration tests

• GraphQL streamCreate -> branchCreate -> commitCreate.
• Object diff -> upload -> getobjects.
• File upload/import job callbacks.
• Viewer derivative publish/fail.

16.3 Contract tests

• Capture real connector requests.
• Replay against new server.
• Assert status, shape, required fields.

16.4 E2E tests

• Login.
• Create project.
• Upload/push model.
• Open viewer.
• Create issue.
• Create review decision.

17. Test/Audit gates theo milestone

Mỗi milestone phải có một điểm dừng kiểm chứng trước khi chuyển sang milestone tiếp theo. Không đóng milestone chỉ vì code đã merge; phải có bằng chứng test, audit và khả năng rollback/debug.

Milestone	Test gate bắt buộc	Audit/observability gate bắt buộc	Bằng chứng nghiệm thu
M0 - Foundation	Build CI, migration dry-run, health check API.	Log có correlationId, health check DB/storage/queue.	Link pipeline xanh, ảnh/chụp log health check.
M1 - Auth	Unit test token, integration test /auth/accesscode và /auth/token.	Audit login, token create, token revoke.	Connector add account thành công bằng server local/staging.
M2 - Project/Model/Version	GraphQL contract test cho streamCreate, branchCreate, commitCreate, query project/stream.	Audit project create/update, model create, version create.	Replay query thật từ connector pass.
M3 - Object upload/pull	Integration test diff -> upload -> getobjects, test upload lại không duplicate.	Metrics object count, upload bytes, duration, error rate.	Connector push/pull model thật thành công.
M4 - Blazor Viewer	Playwright smoke test viewer page, JS bridge dispose/load test.	Viewer load progress, object stream errors, selected object logs.	Mở được model từ Blazor và chọn object xem property.
M5 - File Import	Job state transition test, import success/fail integration test.	Audit file upload/import, job logs có jobId, fileUploadId.	Upload file mẫu tạo version xem được, file lỗi hiện failed.
M6 - Viewer Derivative	Test manifest/artifact publish/fail, fallback object stream.	Metrics derivative queue time, tile count, artifact bytes.	Model lớn load bằng derivative hoặc fallback rõ ràng.
M7 - Issue/Review	API/E2E test tạo issue từ viewer, review approve/reject.	Audit issue create/update, review decision.	Reviewer mở issue trong viewer khôi phục camera/selection.
M8 - Admin/Ops	Test retry job, revoke token, permission admin.	Audit admin action, dashboard job/error metrics.	Admin nhìn thấy job lỗi và retry được.

Quy tắc bắt buộc:

• Mỗi milestone phải có checklist "pass/fail" trong PR hoặc release note nội bộ.
• Mỗi API compatibility thay đổi phải có contract test trước hoặc cùng PR.
• Mỗi luồng nền như import/derivative phải có job idempotency test.
• Mỗi endpoint ghi dữ liệu phải có audit event hoặc lý do rõ nếu không audit.
• Mỗi endpoint xử lý file/object lớn phải có log kích thước, thời gian, user/project và error code.
• Không triển khai milestone sau nếu gate của milestone trước chưa đạt, trừ khi có waiver được ghi trong task.

18. Definition of Done MVP

MVP hoàn thành khi:

• Connector thật login và push/pull được model.
• Blazor viewer mở được model push từ connector.
• File import tạo version xem được.
• Object API pass contract tests.
• User roles ngăn hành động sai quyền.
• Admin xem được job/import lỗi.
• Logs/metrics đủ để debug upload/import/viewer.
• Tài liệu API, data model, pipeline được cập nhật theo implementation thực tế.

19. Rủi ro và phương án giảm

Rủi ro	Giảm thiểu
Connector dùng GraphQL field chưa liệt kê	Dùng proxy/log capture query thật, bổ sung contract tests.
Object hash không tương thích	Chấp nhận id client gửi, test bằng payload thật, port thuật toán hash cẩn thận.
Viewer khó bundle trong Blazor	Tách JS bridge/build riêng, prototype sớm.
C++ importer mất nhiều thời gian	Bắt đầu với OBJ/STL hoặc IFC subset, giữ IFC đầy đủ sang phase sau nếu cần.
Object stream chậm	Dùng DB cursor/gzip, benchmark sớm, derivative cho model lớn.
Scope MVP phình to	P0/P1/P2 rõ, không đưa dashboard nâng cao vào P0.