Network Volume

Quy ước chung

• Base URL: BASE_API_URL
• Path: /bff/v1/networkvolume/{orgIdentifier}/workspaces/{workspaceIdentifier}/{action}
• Method: Tất cả đều POST.
• Header riêng của service: X-Region: <region>
• Header chung (apiClient): X-Org-Id, X-Workspace-Id, X-User-Id
• Response envelope: { "code": "", "message": "", "data": ..., "total": 0 }
• Tham số: Query action truyền qua query string (body {}); các action còn lại truyền qua JSON body.

Danh sách endpoint

Volume

#	Action	Query param	Body	Mục đích
1	network-volume.list	status, sort_by, sort_type (asc | desc)	{}	Danh sách volume
2	network-volume.create	—	{ name, capacity_gb }	Tạo volume
3	network-volume.update	—	{ volume_id, capacity_gb }	Mở rộng dung lượng
4	network-volume.delete	—	{ volume_id }	Xoá volume
5	network-volume.calculateprice	—	{}	Lấy đơn giá
6	network-volume.checkname	name	{}	Kiểm tra trùng tên

S3 adapter key

#	Action	Query param	Body	Mục đích
7	network-volume.lists3keys	—	{}	Danh sách S3 key + trạng thái S3
8	network-volume.creates3key	—	{ name }	Tạo S3 key (timeout 90s)
9	network-volume.gets3key	—	{ key_id }	Chi tiết S3 key
10	network-volume.deletes3key	—	{ key_id }	Xoá S3 key

Ràng buộc

Field	Quy tắc
name	Tối đa 16 ký tự, regex ^[a-zA-Z][a-zA-Z0-9-]*$ (bắt đầu bằng chữ; chữ, số, -)
capacity_gb	Từ 50 đến 3000 GB (mặc định 50)
Mount point mặc định	/mnt/hps

Request body

2. network-volume.create

{ "name": "my-volume", "capacity_gb": 100 }

3. network-volume.update — chỉ cho tăng dung lượng

{ "volume_id": "...", "capacity_gb": 200 }

8. network-volume.creates3key

{ "name": "my-key" }

Response chính

Action	Response (data)
network-volume.list	[{ id, name, vast_config_id, region_code, capacity_gb, endpoint, status, last_error, created_at, created_by, updated_at, updated_by }] (kèm total ở envelope)
network-volume.create / update / delete	Volume: các field như list + vast_resources{ quota, view_policy, view }
network-volume.calculateprice	{ capacity_gb, price, price_per_gb_hour, hourly_cost, monthly_cost, total, currency_code, price_info{ currency, value, unit } } — FE ưu tiên price_per_gb_hour, rồi price, rồi price_info.value; currency mặc định USD
network-volume.checkname	{ is_duplicate: boolean } (FE cũng chấp nhận isDuplicate, duplicated, exists, bọc trong data, hoặc một boolean)

Enum

• status volume: ACTIVE, CREATING, PROCESSING, DELETING, DELETED, ERROR (khi ERROR, xem last_error)
• Region hiển thị: Ha Noi, Tokyo

Mã lỗi

Định dạng lỗi

Khi lỗi, HTTP status ≠ 2xx và body có dạng:

{ "code": "EQ-RESOURCE-00001", "message": "...", "params": { "quotaLevel": "Workspace" }, "role_based": true }

• role_based: true — thông báo phụ thuộc vai trò (MANAGEMENT / WS_ADMIN / MEMBER) và params.quotaLevel.
• HTTP 401 — tự đăng xuất.

Mã lỗi chung (billing / quota / gateway)

Code	Ý nghĩa
INSUFFICIENT_BALANCE	Không đủ credit (role-based). Role MANAGEMENT tự mở modal top-up.
INSUFFICIENT_PERMISSIONS	Không có quyền thực hiện thao tác.
EQ-RESOURCE-00001	Đã đạt quota (role-based, theo params.quotaLevel).
EQ-RESOURCE-SYSTEM-LIMIT	Đã đạt quota của resource (params.name).
BFF-CREATING-CONCURRENCY	Đang có resource khác được tạo trong workspace/service này.
route_not_found	Endpoint không tồn tại.
method_not_allowed	Sai method (chỉ dùng POST).
request_too_large	Body vượt 64 KB.
invalid_token	Token không hợp lệ hoặc hết hạn.
gateway_internal_error	Lỗi nội bộ gateway.
upstream_unavailable	Service phía sau tạm thời không khả dụng.
gateway_timeout	Service phía sau timeout.