Tài Liệu Thiết Kế: Hệ Thống Phân Quyền, Quản Lý Quota & Admin Control

Tài liệu này đặc tả kiến trúc bảo mật, quản lý người dùng, hạn mức tài nguyên (Quota), cờ tính năng (Feature Flags) và giao diện quản trị cho hệ thống SonicForge Studio.

1. Sơ Đồ Phân Cấp & Luồng Xác Thực (RBAC & Auth Flow)

Hệ thống sử dụng cơ chế kiểm soát truy cập dựa trên vai trò (Role-Based Access Control - RBAC) với 3 nhóm vai trò cơ bản:

Super Admin: Toàn quyền cấu hình hệ thống, quản lý người dùng, hạn mức (Quota), bật/tắt tính năng toàn cục và dọn dẹp tài nguyên vật lý.
Premium User: Người dùng trả phí, có hạn mức dung lượng lưu trữ lớn, không giới hạn số lượng track và được ưu tiên sử dụng AI Engine.
Standard User: Người dùng đăng ký miễn phí, có giới hạn dung lượng lưu trữ, số track tối đa và giới hạn số lượt gọi AI API hàng tháng.

1.1. Luồng Đăng Nhập Đầu Tiên với Mật Khẩu Mặc Định

Khi Admin khởi tạo một tài khoản mới hoặc tạo một dự án độc lập, hệ thống sẽ gán một mật khẩu mặc định (Default Password) được cấu hình từ môi trường Docker (DEFAULT_ADMIN_PASSWORD).

[Người dùng/Admin] ──► Đăng nhập bằng Mật khẩu Mặc định ──► [Server xác thực JWT]
                                                                  │
  ┌───────────────────────────────────────────────────────────────┘
  ▼
Kiểm tra trạng thái `must_change_password == True`
  ├── (Đúng) ──► Chặn mọi yêu cầu API thông thường ──► Trả về HTTP 403 (PASSWORD_CHANGE_REQUIRED)
  │                                                      yêu cầu đổi mật khẩu ngay lập tức.
  └── (Sai)  ──► Cho phép truy cập tài nguyên bình thường.

2. Thiết Kế Cơ Sở Dữ Liệu (Database Schema)

Để lưu trữ thông tin phân quyền, cấu hình mã hóa mật khẩu bằng thuật toán băm bảo mật Argon2id hoặc Bcrypt.

-- Bảng Người dùng (Users)
CREATE TABLE users (
    id VARCHAR(36) PRIMARY KEY,
    username VARCHAR(50) UNIQUE NOT NULL,
    email VARCHAR(100) UNIQUE NOT NULL,
    hashed_password VARCHAR(255) NOT NULL,
    role VARCHAR(20) DEFAULT 'standard', -- 'admin', 'premium', 'standard'
    must_change_password BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    is_active BOOLEAN DEFAULT TRUE
);

-- Bảng Hạn mức tài nguyên (User Quotas)
CREATE TABLE user_quotas (
    user_id VARCHAR(36) PRIMARY KEY,
    storage_limit_mb INTEGER DEFAULT 500,       -- Hạn mức ổ đĩa (Ví dụ: 500MB)
    max_tracks_per_project INTEGER DEFAULT 4,   -- Số track tối đa trong một project
    ai_calls_limit_monthly INTEGER DEFAULT 50,  -- Số lần gọi AI tối đa mỗi tháng
    ai_calls_used_this_month INTEGER DEFAULT 0,
    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
);

-- Bảng Cờ Tính Năng Hệ Thống (Feature Flags - Cho phép Admin bật/tắt nóng tính năng)
CREATE TABLE feature_flags (
    flag_key VARCHAR(50) PRIMARY KEY, -- Ví dụ: 'ai_cut_enabled', 'wav_export_24bit'
    description VARCHAR(255),
    is_enabled BOOLEAN DEFAULT TRUE,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Bảng Siêu dữ liệu Tập tin (Audio Files Meta)
CREATE TABLE audio_files (
    id VARCHAR(36) PRIMARY KEY,
    user_id VARCHAR(36) NOT NULL,
    file_name VARCHAR(255) NOT NULL,
    file_path VARCHAR(512) NOT NULL,
    file_size_bytes BIGINT NOT NULL,
    duration_seconds FLOAT NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
);

3. Thiết Kế Bảo Mật & Logic Python (Backend Implementation)

3.1. Hashing Mật Khẩu (Bcrypt)

Mật khẩu bắt buộc phải được mã hóa một chiều bằng salt ngẫu nhiên trước khi lưu vào DB.

from passlib.context import CryptContext

pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")

def hash_password(password: str) -> str:
    return pwd_context.hash(password)

def verify_password(plain_password: str, hashed_password: str) -> bool:
    return pwd_context.verify(plain_password, hashed_password)

3.2. Middleware Ép Đổi Mật Khẩu (Force Password Change Middleware)

Tất cả các API yêu cầu xác thực (ngoại trừ Endpoint đổi mật khẩu /api/v1/auth/change-password) đều phải đi qua bộ lọc kiểm tra trạng thái:

from fastapi import HTTPException, status, Depends
from app.models import User

def verify_user_not_flagged(current_user: User = Depends(get_current_active_user)):
    if current_user.must_change_password:
        raise HTTPException(
            status_code=status.HTTP_403_FORBIDDEN,
            detail={
                "error_code": "PASSWORD_CHANGE_REQUIRED",
                "message": "Bạn phải đổi mật khẩu mặc định trước khi sử dụng hệ thống."
            }
        )
    return current_user

3.3. Thuật Toán Kiểm Tra Hạn Mức Dung Lượng (Quota Validation)

Trước khi cho phép người dùng tải lên tệp tin mới, hệ thống tính toán tổng dung lượng tệp tin hiện tại:

S_{\text{used}} = \sum_{i=1}^{N} \text{file\_size\_bytes}_i

Nếu S_{\text{used}} + S_{\text{new\_file}} > \text{storage\_limit\_mb} \times 1024 \times 1024, chặn tải lên ngay tại API Gateway và trả về lỗi HTTP 400 Bad Request.

4. API Endpoints Quản Trị Hệ Thống (Admin APIs)

Admin sẽ được cung cấp bộ API riêng biệt để quản lý toàn cục:

Phương thức	Endpoint	Phân quyền	Mô tả
POST	`/api/v1/auth/register`	Toàn quyền (Public)	Đăng ký tài khoản người dùng mới (Mặc định `must_change_password = False`).
GET	`/api/v1/admin/users`	Admin	Lấy danh sách tất cả người dùng kèm thông tin Quotas hiện tại.
PUT	`/api/v1/admin/users/{user_id}`	Admin	Sửa đổi thông tin người dùng (Đổi vai trò, kích hoạt/vô hiệu hóa tài khoản).
DELETE	`/api/v1/admin/users/{user_id}`	Admin	Xóa tài khoản người dùng và tự động dọn dẹp tất cả tệp tin liên quan.
PUT	`/api/v1/admin/quotas/{user_id}`	Admin	Điều chỉnh giới hạn dung lượng (`storage_limit_mb`) và số lượt gọi AI.
GET	`/api/v1/admin/files`	Admin	Khám phá toàn bộ tệp tin đang lưu trên Server của mọi người dùng.
DELETE	`/api/v1/admin/files/{file_id}`	Admin	Buộc xóa tệp tin vật lý khỏi ổ đĩa và cập nhật lại quota cho người dùng.
PUT	`/api/v1/admin/features`	Admin	Thay đổi trạng thái True/False của các Feature Flags hệ thống.

5. UI Mockup: Admin Dashboard Sub-Panel

Khi người dùng đăng nhập với vai trò admin, một tab "Admin Dashboard" chuyên dụng sẽ xuất hiện trên thanh điều hướng góc trên cùng:

+-----------------------------------------------------------------------------+
| SONICFORGE STUDIO Pro  [Workspace]  [AI Settings]  [*Admin Dashboard*]      |
+-----------------------------------------------------------------------------+
| QUẢN LÝ NGƯỜI DÙNG & TÀI NGUYÊN HỆ THỐNG                                    |
| +-------------------------------------------------------------------------+ |
| | Tên người dùng | Vai trò    | Dung lượng (MB)  | Đã dùng (MB) | Thao tác | |
| |----------------|------------|------------------|--------------|----------| |
| | admin_01       | Admin      | Vô hạn           | 14.2 MB      | [Sửa]    | |
| | user_studio    | Premium    | 2048 MB          | 512.0 MB     | [Sửa][Xóa]| |
| | demo_member    | Standard   | 500 MB           | 498.5 MB     | [Sửa][Xóa]| |
| +-------------------------------------------------------------------------+ |
|                                                                             |
| CẤU HÌNH TÍNH NĂNG (FEATURE FLAGS)                                          |
| [X] Kích hoạt AI Cut Engine | [X] Cho phép xuất 24-bit WAV | [ ] Tách vocal |
+-----------------------------------------------------------------------------+

8.6 KiB Raw Blame History