speckle-server/docs/aspnet-blazor-speckle-platform-data-model.md

Data Model nền tảng Speckle-compatible ASP.NET/Blazor

1. Mục tiêu

Tài liệu này mô tả mô hình dữ liệu mục tiêu cho PostgreSQL. Thiết kế ưu tiên:

• Tương thích Speckle concepts: Stream/Branch/Commit/Object.
• API mới dùng thuật ngữ Project/Model/Version.
• Object graph immutable và deduplicate.
• Hỗ trợ upload/pull/viewer hiệu năng cao.
• Mở rộng được cho issue, review, dashboard, audit và integration.

2. Quy ước chung

• Primary key dùng text hoặc uuid tuỳ compatibility. Với Project/Model/Version nên dùng text/base62 nếu cần giống Speckle.
• Tất cả bảng nghiệp vụ có created_at, updated_at.
• Soft delete dùng deleted_at khi dữ liệu cần audit.
• JSON linh hoạt dùng jsonb.
• Dữ liệu lớn không nhét vào row nếu có thể đưa sang object storage.
• Các bảng object/version cần index kỹ vì là điểm nóng.

3. Nhóm identity/auth

3.1 users

Cột	Kiểu	Ghi chú
id	text/uuid	User id.
email	citext	Unique.
name	text	Display name.
company	text	Optional.
avatar_url	text	Optional.
server_role	text	admin, user, guest.
status	text	active, invited, disabled.
created_at	timestamptz
updated_at	timestamptz

Index:

• Unique email.
• Index status.

3.2 server_apps

Cột	Kiểu	Ghi chú
id	text	Ví dụ sdm, sca, connectrV3.
secret_digest	text	Hash nếu app confidential.
name	text
redirect_url	text
is_public	boolean	Public app không giữ secret thật.
trust_by_default	boolean	Auto approve hay không.
scopes	text[]	Scope app được xin.
created_at	timestamptz

3.3 api_tokens

Cột	Kiểu	Ghi chú
id	text	10 ký tự token id nếu giữ format Speckle.
owner_user_id	text	FK users.
app_id	text	FK server_apps, nullable cho PAT.
token_digest	text	Hash secret.
last_chars	text	6 ký tự cuối để hiển thị.
name	text
expires_at	timestamptz	Nullable.
revoked_at	timestamptz	Nullable.
created_at	timestamptz

3.4 api_token_scopes

Cột	Kiểu	Ghi chú
token_id	text	FK api_tokens.
scope	text	Ví dụ streams:read.

Primary key: (token_id, scope).

3.5 auth_access_codes

Cột	Kiểu	Ghi chú
code	text	Short lived.
user_id	text
app_id	text
redirect_url	text
challenge	text	Optional PKCE/challenge.
expires_at	timestamptz
used_at	timestamptz	Nullable.
created_at	timestamptz

4. Nhóm project/model/version

4.1 projects

Tương đương Speckle Stream.

Cột	Kiểu	Ghi chú
id	text	Dùng làm streamId legacy.
name	text
description	text
visibility	text	private, public, workspace.
allow_public_comments	boolean
owner_user_id	text	FK users.
workspace_id	text	Nullable nếu chưa làm workspace.
source_apps	text[]	Cache app sources, có thể tính lại.
created_at	timestamptz
updated_at	timestamptz
deleted_at	timestamptz

Index:

• owner_user_id.
• visibility.
• Full text index cho name, description.

4.2 project_members

Cột	Kiểu	Ghi chú
project_id	text	FK projects.
user_id	text	FK users.
role	text	owner, contributor, reviewer, viewer.
created_at	timestamptz
updated_at	timestamptz

Primary key: (project_id, user_id).

4.3 project_invites

Cột	Kiểu	Ghi chú
id	text/uuid
project_id	text
email	citext
user_id	text	Nullable.
role	text
token_digest	text
status	text	pending, accepted, declined, cancelled.
invited_by_user_id	text
expires_at	timestamptz
created_at	timestamptz

4.4 models

Tương đương Speckle Branch.

Cột	Kiểu	Ghi chú
id	text	Dùng làm model id.
project_id	text	FK projects.
name	text	Full name, ví dụ Architecture/Walls.
display_name	text	Segment cuối.
description	text
author_user_id	text
created_at	timestamptz
updated_at	timestamptz
deleted_at	timestamptz

Index:

• Unique (project_id, name) where deleted_at is null.
• Index (project_id, updated_at desc).

4.5 versions

Tương đương Speckle Commit.

Cột	Kiểu	Ghi chú
id	text	Dùng làm commit/version id.
project_id	text	FK projects.
model_id	text	FK models.
referenced_object	text	Root object id.
message	text	Commit message.
source_application	text	Revit/Rhino/IFC importer...
author_user_id	text
total_children_count	integer
parents	text[]	Parent version ids.
preview_url	text	Optional.
created_at	timestamptz
updated_at	timestamptz
deleted_at	timestamptz

Index:

• (project_id, model_id, created_at desc).
• (project_id, referenced_object).
• GIN parents.

5. Nhóm object graph

5.1 objects

Cột	Kiểu	Ghi chú
project_id	text	Partition/shard key.
id	text	Speckle object id/hash.
speckle_type	text	Từ speckle_type hoặc speckleType.
data	jsonb	Object JSON nguyên gốc.
total_children_count	integer	Optional.
created_at	timestamptz

Primary key: (project_id, id).

Index:

• (project_id, speckle_type).
• GIN data jsonb_path_ops nếu cần query property.
• BRIN/partition theo project_id hoặc hash partition khi rất lớn.

Ghi chú:

• Đây là bảng điểm nóng nhất.
• Insert phải dùng upsert/ignore conflict.
• Không update data sau khi insert trừ migration có kiểm soát.

5.2 object_children

Tuỳ chọn. Nếu cần traversal nhanh thay vì parse JSON mỗi lần.

Cột	Kiểu	Ghi chú
project_id	text
object_id	text	Parent object.
child_object_id	text	Child reference.
path	text	Property path nếu cần.
depth_hint	integer	Optional.

Primary key: (project_id, object_id, child_object_id, path).

5.3 object_properties_index

Tuỳ chọn cho search/filter BIM.

Cột	Kiểu	Ghi chú
project_id	text
version_id	text
object_id	text
property_key	text	Ví dụ category, level, family.
property_value_text	text
property_value_number	numeric	Nullable.
property_value_bool	boolean	Nullable.

Index:

• (project_id, property_key, property_value_text).
• (project_id, version_id, property_key).

6. Nhóm blob/file/import

6.1 blobs

Cột	Kiểu	Ghi chú
id	text	Blob id.
project_id	text
file_name	text
content_type	text
size_bytes	bigint
storage_key	text	Key trong object storage.
hash	text	Optional checksum.
created_by_user_id	text
created_at	timestamptz
deleted_at	timestamptz

6.2 file_uploads

Cột	Kiểu	Ghi chú
id	text	File upload id.
project_id	text
model_id	text	Nullable cho pending model.
model_name	text	Dùng khi model chưa có.
blob_id	text	FK blobs.
file_name	text
file_type	text	ifc, stl, obj, ...
file_size	bigint
status	text	queued, converting, completed, error, cancelled.
converted_version_id	text	Nullable.
converted_root_object_id	text	Nullable.
error_code	text	Nullable.
error_message	text	Nullable.
metadata	jsonb
performance_data	jsonb
created_by_user_id	text
created_at	timestamptz
updated_at	timestamptz

Index:

• (project_id, status).
• (project_id, model_id, created_at desc).

6.3 jobs

Generic background job state.

Cột	Kiểu	Ghi chú
id	uuid/text
type	text	file-import, viewer-derivative, preview, bim-check.
status	text	queued, running, succeeded, failed, cancelled.
project_id	text	Nullable.
resource_type	text	file_upload, version, ...
resource_id	text
payload	jsonb
attempt_count	integer
max_attempts	integer
run_after	timestamptz
locked_by	text	Worker id.
locked_at	timestamptz
error_code	text
error_message	text
created_at	timestamptz
updated_at	timestamptz

7. Nhóm viewer

7.1 viewer_derivatives

Cột	Kiểu	Ghi chú
id	uuid/text
project_id	text
model_id	text
version_id	text
derivative_type	text	large-model.
schema_version	integer	Version format derivative.
status	text	queued, processing, ready, failed.
stage	text	extracting, tiling, uploading-artifacts, ...
progress	numeric	0..1.
manifest_key	text	Object storage key.
manifest_hash	text
tile_count	integer
tile_bytes	bigint
metadata_bytes	bigint
stats	jsonb
error_code	text
error_message	text
published_at	timestamptz
created_at	timestamptz
updated_at	timestamptz

Unique: (project_id, version_id, derivative_type, schema_version).

7.2 saved_views

Cột	Kiểu	Ghi chú
id	text/uuid
project_id	text
name	text
description	text
resource_ids	text	Viewer resource string.
viewer_state	jsonb	Camera, section, filters, selection.
is_home_view	boolean
created_by_user_id	text
created_at	timestamptz
updated_at	timestamptz

8. Nhóm comment/issue/review

8.1 comments

Cột	Kiểu	Ghi chú
id	text/uuid
project_id	text
parent_comment_id	text	Thread reply.
target_type	text	project, model, version, object, issue.
target_id	text
body	jsonb/text	Rich text hoặc markdown.
viewer_state	jsonb	Camera/selection tại lúc comment.
created_by_user_id	text
created_at	timestamptz
updated_at	timestamptz
deleted_at	timestamptz

8.2 issues

Cột	Kiểu	Ghi chú
id	text/uuid
project_id	text
model_id	text	Nullable.
version_id	text	Nullable.
title	text
description	text/jsonb
status	text	open, in_progress, resolved, closed.
priority	text	low, medium, high, critical.
assignee_user_id	text	Nullable.
created_by_user_id	text
due_date	date	Nullable.
viewer_state	jsonb	Camera/selection/markup.
object_ids	text[]	Related objects.
created_at	timestamptz
updated_at	timestamptz
closed_at	timestamptz

8.3 review_sessions

Cột	Kiểu	Ghi chú
id	text/uuid
project_id	text
name	text
status	text	draft, active, completed, cancelled.
created_by_user_id	text
starts_at	timestamptz	Nullable.
due_at	timestamptz	Nullable.
created_at	timestamptz
updated_at	timestamptz

8.4 review_items

Cột	Kiểu	Ghi chú
id	text/uuid
review_session_id	text
project_id	text
model_id	text
version_id	text
status	text	pending, approved, rejected, approved_with_comments.
reviewer_user_id	text
decision_note	text
decided_at	timestamptz

9. Nhóm audit/integration

9.1 activity_events

Cột	Kiểu	Ghi chú
id	uuid
project_id	text	Nullable.
actor_user_id	text	Nullable cho system.
event_type	text	project.created, version.created, ...
resource_type	text
resource_id	text
payload	jsonb
created_at	timestamptz

9.2 audit_logs

Cột	Kiểu	Ghi chú
id	uuid
actor_user_id	text
action	text
target_type	text
target_id	text
ip_address	inet
user_agent	text
before	jsonb	Nullable.
after	jsonb	Nullable.
created_at	timestamptz

9.3 webhooks

Cột	Kiểu	Ghi chú
id	text/uuid
project_id	text	Nullable.
url	text
secret_digest	text
events	text[]
is_active	boolean
created_by_user_id	text
created_at	timestamptz

9.4 webhook_deliveries

Cột	Kiểu	Ghi chú
id	uuid
webhook_id	text
event_id	uuid
status	text	pending, succeeded, failed.
attempt_count	integer
response_status	integer
response_body	text	Cắt ngắn.
created_at	timestamptz
delivered_at	timestamptz

10. View/report đề xuất

• project_latest_versions: latest version per model.
• project_storage_usage: object bytes, blob bytes, derivative bytes.
• user_recent_projects: project activity per user.
• issue_summary_by_project: open/resolved/overdue issues.
• conversion_job_summary: conversion status and duration.

11. Migration mapping từ Speckle Server

Speckle table/concept	Bảng mới
streams	projects
stream_acl/collaborators	project_members
branches	models
commits	versions
objects	objects
blobs	blobs
file_uploads	file_uploads
api_tokens/token scopes	api_tokens/api_token_scopes
comments	comments/issues tuỳ loại

Migration cần:

• Preserve IDs nếu muốn URL/connector reference cũ tiếp tục hoạt động.
• Preserve object data nguyên gốc.
• Validate count: project, model, version, object, blob.
• Checksum object id/data trước và sau migration.