huanld/speckle-server
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
2b717aa2e21429e2433bafc35bf2e2595db9fdab
speckle-server/docs/mvp-implementation-plan.md
T

10 KiB
Raw Blame History

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. 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ế.

18. 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.
Reference in New Issue View Git Blame Copy Permalink