fix tạm lỗi cài đặt AI prompt
This commit is contained in:
@@ -0,0 +1,182 @@
|
||||
Dưới đây là toàn bộ nội dung tài liệu đặc tả kỹ thuật đã được chuyển đổi sang định dạng Markdown chuẩn, tối ưu hóa các khối mã nguồn (`python`, `text`), căn chỉnh bảng biểu, sơ đồ luồng ASCII và các công thức toán học dạng LaTeX:
|
||||
|
||||
# Technical Specification: Sub-Tab Audio Clip Editor & DSP Operations
|
||||
|
||||
This document outlines the software engineering specification for the temporary isolated Sub-Tab Audio Clip Editor. It defines internal clipboard mechanics, DSP algorithms for selection-based operations, Context Menu structures, and main application menu shortcuts.
|
||||
|
||||
---
|
||||
|
||||
## 1. Clipboard & Cursor-Aligned Insertion Mechanics
|
||||
|
||||
The Sub-Tab workspace features an isolated, low-latency stereo/mono audio buffer. The editor tracks a local virtual playhead position $t_{\text{cursor}}$ and handles clipboard buffers using non-destructive splicing techniques.
|
||||
|
||||
```text
|
||||
Local Timeline Buffer
|
||||
+-------------------------------------------------------+
|
||||
| Track Waveform Segment │ |
|
||||
+-------------------------------┼-----------------------+
|
||||
▲
|
||||
t_cursor (Insertion Point)
|
||||
│
|
||||
▼ [ PASTE TRIGGERED ]
|
||||
+-------------------------------------------------------+
|
||||
| Track Waveform Segment │ CLIPBOARD DATA │ |
|
||||
+-------------------------------------------------------+
|
||||
◄──────────────►
|
||||
clip_duration
|
||||
|
||||
```
|
||||
|
||||
### 1.1. Cursor Paste Action
|
||||
|
||||
When a paste command is issued (either via Context Menu, Application Menu, or Hotkey):
|
||||
|
||||
* **Payload Extraction:** Retrieve the copied `AudioBufferSegment` from the system/application clipboard.
|
||||
* **Splicing Boundary Calculations:** Slice the current active timeline buffer at $t_{\text{cursor}}$.
|
||||
* **Re-allocation & Stitching:**
|
||||
* Compute the new duration: $T_{\text{new}} = T_{\text{original}} + T_{\text{clipboard}}$.
|
||||
* Allocate a new virtual audio array $Y_{\text{new}}$:
|
||||
|
||||
|
||||
|
||||
$$Y_{\text{new}}(t) = \begin{cases} Y_{\text{original}}(t) & 0 \le t < t_{\text{cursor}} \\ Y_{\text{clipboard}}(t - t_{\text{cursor}}) & t_{\text{cursor}} \le t < t_{\text{cursor}} + T_{\text{clipboard}} \\ Y_{\text{original}}(t - T_{\text{clipboard}}) & t_{\text{cursor}} + T_{\text{clipboard}} \le t \le T_{\text{new}} \end{cases}$$
|
||||
|
||||
* **Playhead Update:** Advance the active playhead $t_{\text{cursor}}$ immediately to $t_{\text{cursor}} + T_{\text{clipboard}}$.
|
||||
|
||||
---
|
||||
|
||||
## 2. Selection Context Menu & DSP Engine
|
||||
|
||||
Right-clicking inside a highlighted region $[T_{\text{start}}, T_{\text{end}}]$ of the Waveform Canvas triggers an overlay context menu containing the following DSP and editing commands.
|
||||
|
||||
```text
|
||||
+---------------------------------------------+
|
||||
| Selection: [ 01:02.100 - 01:05.400 ] |
|
||||
+---------------------------------------------+
|
||||
| Normalize Selection To Peak |
|
||||
| Adjust Gain/Volume... |
|
||||
| Adjust Panning (Stereo Balance)... |
|
||||
| Fade In (Linear/Exponential) |
|
||||
| Fade Out (Linear/Exponential) |
|
||||
|---------------------------------------------|
|
||||
| Cut Ctrl+X |
|
||||
| Copy Ctrl+C |
|
||||
| Paste Ctrl+V |
|
||||
| Delete Selected Segment Del |
|
||||
|---------------------------------------------|
|
||||
| Loop Selection: [ ▲ ] [ 4 ] [ ▼ ] times |
|
||||
+---------------------------------------------+
|
||||
|
||||
```
|
||||
|
||||
### 2.1. Normalize Selection
|
||||
|
||||
Scales the peak amplitude of the selected segment to a target ceiling $A_{\text{target}}$ (defaulting to $1.0$ or $0\text{ dBFS}$):
|
||||
|
||||
$$Y_{\text{norm}}(t) = Y(t) \cdot \frac{A_{\text{target}}}{\max_{u \in [T_{\text{start}}, T_{\text{end}}]} \vert{}Y(u)\vert{}} \quad \text{for } t \in [T_{\text{start}}, T_{\text{end}}]$$
|
||||
|
||||
### 2.2. Volume (Gain dB) Adjustment
|
||||
|
||||
Applies a static linear gain multiplier derived from user-specified decibel scaling values ($\Delta\text{dB}$):
|
||||
|
||||
$$G = 10^{\frac{\Delta\text{dB}}{20}}$$
|
||||
|
||||
$$Y_{\text{gained}}(t) = Y(t) \cdot G \quad \text{for } t \in [T_{\text{start}}, T_{\text{end}}]$$
|
||||
|
||||
### 2.3. Panning (Stereo Balance)
|
||||
|
||||
Applies a constant-power panning law across Left ($L$) and Right ($R$) channels based on the panning angle $\theta \in [0, \pi/2]$, where $\theta = \pi/4$ represents absolute center:
|
||||
|
||||
$$Y_L(t) = Y_{\text{mono}}(t) \cdot \cos(\theta), \quad Y_R(t) = Y_{\text{mono}}(t) \cdot \sin(\theta)$$
|
||||
|
||||
### 2.4. Fade-In and Fade-Out (Linear / Exponential)
|
||||
|
||||
* **Linear Fade-In Curve:**
|
||||
|
||||
$$f_{\text{in}}(t) = \frac{t - T_{\text{start}}}{T_{\text{end}} - T_{\text{start}}} \quad \text{for } t \in [T_{\text{start}}, T_{\text{end}}]$$
|
||||
|
||||
* **Linear Fade-Out Curve:**
|
||||
|
||||
$$f_{\text{out}}(t) = 1.0 - \frac{t - T_{\text{start}}}{T_{\text{end}} - T_{\text{start}}} \quad \text{for } t \in [T_{\text{start}}, T_{\text{end}}]$$
|
||||
|
||||
### 2.5. Delete, Cut, and Copy
|
||||
|
||||
* **Delete:** Erases the selected segment $[T_{\text{start}}, T_{\text{end}}]$ and shifts all subsequent samples leftward.
|
||||
* **Cut:** Copies the selected samples to the clipboard, then executes the *Delete* routine.
|
||||
* **Copy:** Writes the targeted buffer segment to the clip memory without modifying the timeline.
|
||||
|
||||
### 2.6. Segment Looping with Step Multiplier
|
||||
|
||||
Repeats the selected segment $[T_{\text{start}}, T_{\text{end}}]$ consecutively $N$ times. The menu provides a numeric spinner (Up/Down buttons) to adjust $N$:
|
||||
|
||||
1. Extract segment: $Y_{\text{segment}} = Y(t)$ for $t \in [T_{\text{start}}, T_{\text{end}}]$.
|
||||
2. Compute new duration adjustment: $\Delta L = (N - 1) \cdot (T_{\text{end}} - T_{\text{start}})$.
|
||||
3. Duplicate and insert $Y_{\text{segment}}$ array $N-1$ times directly after $T_{\text{end}}$.
|
||||
|
||||
---
|
||||
|
||||
## 3. Global Menu Bar & Keyboard Shortcut Matrix
|
||||
|
||||
All context-dependent sub-tab actions are mapped directly to the global Menu Bar at the top of the DAW window, as specified in `image_e0e462.png`.
|
||||
|
||||
```text
|
||||
File Edit View Insert Track Options Actions Extensions Help
|
||||
│
|
||||
├── Normalize Selection [Ctrl+Alt+N]
|
||||
├── Adjust Volume... [V]
|
||||
├── Adjust Panning... [P]
|
||||
├── Fade In [F]
|
||||
├── Fade Out [G]
|
||||
├── Cut [Ctrl+X]
|
||||
├── Copy [Ctrl+C]
|
||||
├── Paste [Ctrl+V]
|
||||
├── Delete [Del]
|
||||
└── Loop Clip... [Ctrl+L]
|
||||
|
||||
```
|
||||
|
||||
### 3.1. Keyboard Mapping Table
|
||||
|
||||
To maximize speed and accessibility, the system listens for global key event hooks within the Sub-Tab window focus:
|
||||
|
||||
| Action Command | Main Menu Category | Recommended Keyboard Shortcut | Python Event Trigger (`QKeyEvent`) |
|
||||
| --- | --- | --- | --- |
|
||||
| **Cut** | Edit -> Cut | `Ctrl + X` | `Qt.Key.Key_X` + `ControlModifier` |
|
||||
| **Copy** | Edit -> Copy | `Ctrl + C` | `Qt.Key.Key_C` + `ControlModifier` |
|
||||
| **Paste** | Edit -> Paste | `Ctrl + V` | `Qt.Key.Key_V` + `ControlModifier` |
|
||||
| **Delete** | Edit -> Delete | `Del` / `Backspace` | `Qt.Key.Key_Delete` / `Key_Backspace` |
|
||||
| **Normalize** | Actions -> Normalize | `Ctrl + Alt + N` | `Qt.Key.Key_N` + `ControlModifier` + `AltModifier` |
|
||||
| **Fade In** | Actions -> Fade In | `F` | `Qt.Key.Key_F` |
|
||||
| **Fade Out** | Actions -> Fade Out | `G` | `Qt.Key.Key_G` |
|
||||
| **Loop Segment** | Actions -> Loop... | `Ctrl + L` | `Qt.Key.Key_L` + `ControlModifier` |
|
||||
| **Adjust Volume** | Actions -> Gain... | `V` | `Qt.Key.Key_V` |
|
||||
| **Adjust Panning** | Actions -> Panning... | `P` | `Qt.Key.Key_P` |
|
||||
|
||||
---
|
||||
|
||||
## 4. Python Implementation Notes for Docker Server Porting
|
||||
|
||||
When porting these sub-tab operations to your Python DSP engine (`core/audio_editor.py`), use NumPy slice vectors to perform non-destructive edits on waveforms:
|
||||
|
||||
```python
|
||||
# Prototype helper for non-destructive volume adjustment in Python
|
||||
import numpy as np
|
||||
|
||||
def apply_gain_on_segment(y: np.ndarray, sr: int, start_sec: float, end_sec: float, gain_db: float) -> np.ndarray:
|
||||
"""
|
||||
Applies gain in dB to a selected segment of a mono numpy audio array.
|
||||
"""
|
||||
# 1. Translate time coordinates securely with boundary checking
|
||||
start_sample = max(0, int(start_sec * sr))
|
||||
end_sample = min(len(y), int(end_sec * sr))
|
||||
|
||||
# 2. Convert dB value to linear multiplier
|
||||
multiplier = 10.0 ** (gain_db / 20.0)
|
||||
|
||||
# 3. Create a deep copy and modify segment in-place
|
||||
y_edited = np.copy(y)
|
||||
y_edited[start_sample:end_sample] *= multiplier
|
||||
|
||||
return y_edited
|
||||
|
||||
```
|
||||
@@ -0,0 +1,173 @@
|
||||
|
||||
# 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`).
|
||||
|
||||
```text
|
||||
[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.
|
||||
|
||||
```sql
|
||||
-- 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.
|
||||
|
||||
```python
|
||||
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:
|
||||
|
||||
```python
|
||||
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:
|
||||
|
||||
```text
|
||||
+-----------------------------------------------------------------------------+
|
||||
| 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 |
|
||||
+-----------------------------------------------------------------------------+
|
||||
|
||||
```
|
||||
Reference in New Issue
Block a user