RomanNum3ral
/
MicroFish
mirror of https://github.com/666ghj/MiroFish.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

translation comment code - backend - models folder

This commit is contained in:
ththu0205 2026-03-24 16:51:40 +00:00 committed by TQuynh109
parent 985f89f49a
commit 950e8a80cb
2 changed files with 88 additions and 87 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

101
backend/app/models/project.py
View File

@ -1,6 +1,7 @@
""" """
项目上下文管理 Quản lý context (ngữ cảnh) của dự án
用于在服务端持久化项目状态，避免前端在接口间传递大量数据 Được sử dụng để lưu trữ trạng thái dự án trên server (persistence),
giúp tránh việc frontend phải gửi đi một lượng lớn dữ liệu mỗi lần gọi API.
""" """
import os import os
@ -15,45 +16,45 @@ from ..config import Config
class ProjectStatus(str, Enum): class ProjectStatus(str, Enum):
"""项目状态""" """Trạng thái hiện tại của dự án"""
CREATED = "created" # 刚创建，文件已上传 CREATED = "created" # Dự án vừa được tạo, các file đã được tải lên thành công
ONTOLOGY_GENERATED = "ontology_generated" # 本体已生成 ONTOLOGY_GENERATED = "ontology_generated" # Đã hoàn tất khởi tạo Ontology
GRAPH_BUILDING = "graph_building" # 图谱构建中 GRAPH_BUILDING = "graph_building" # Tri thức đồ thị (Knowledge Graph) đang được xây dựng
GRAPH_COMPLETED = "graph_completed" # 图谱构建完成 GRAPH_COMPLETED = "graph_completed" # Đã hoàn thành quá trình Graph
FAILED = "failed" # 失败 FAILED = "failed" # Thiết lập / Xử lý gặp lỗi
@dataclass @dataclass
class Project: class Project:
"""项目数据模型""" """Mô hình dữ liệu (Data model) của dự án"""
project_id: str project_id: str
name: str name: str
status: ProjectStatus status: ProjectStatus
created_at: str created_at: str
updated_at: str updated_at: str
# 文件信息 # File information
files: List[Dict[str, str]] = field(default_factory=list) # [{filename, path, size}] files: List[Dict[str, str]] = field(default_factory=list) # [{filename, path, size}]
total_text_length: int = 0 total_text_length: int = 0
# 本体信息（接口1生成后填充） # Thông tin ontology (được điền sau khi API 1 xử lý xong)
ontology: Optional[Dict[str, Any]] = None ontology: Optional[Dict[str, Any]] = None
analysis_summary: Optional[str] = None analysis_summary: Optional[str] = None
# 图谱信息（接口2完成后填充） # Thông tin graph (được điền sau khi API 2 hoàn thành)
graph_id: Optional[str] = None graph_id: Optional[str] = None
graph_build_task_id: Optional[str] = None graph_build_task_id: Optional[str] = None
# 配置 # Cấu hình
simulation_requirement: Optional[str] = None simulation_requirement: Optional[str] = None
chunk_size: int = 500 chunk_size: int = 500
chunk_overlap: int = 50 chunk_overlap: int = 50
# 错误信息 # Thông tin lỗi
error: Optional[str] = None error: Optional[str] = None
def to_dict(self) -> Dict[str, Any]: def to_dict(self) -> Dict[str, Any]:
"""转换为字典""" """Biến đổi đối tượng (Object) thành Dictionary (để dễ dàng chuyển thành JSON và lưu trữ)"""
return { return {
"project_id": self.project_id, "project_id": self.project_id,
"name": self.name, "name": self.name,
@ -74,7 +75,7 @@ class Project:
@classmethod @classmethod
def from_dict(cls, data: Dict[str, Any]) -> 'Project': def from_dict(cls, data: Dict[str, Any]) -> 'Project':
"""从字典创建""" """Khởi tạo một instance Project từ dữ liệu kiểu Dictionary (khi load lên từ hệ thống lưu trữ)"""
status = data.get('status', 'created') status = data.get('status', 'created')
if isinstance(status, str): if isinstance(status, str):
status = ProjectStatus(status) status = ProjectStatus(status)
@ -99,46 +100,46 @@ class Project:
class ProjectManager: class ProjectManager:
"""项目管理器 - 负责项目的持久化存储和检索""" """Quản lý các dự án (ProjectManager) - Chịu trách nhiệm lưu trữ và truy xuất thông tin dự án"""
# 项目存储根目录 # Thư mục gốc để lưu trữ toàn bộ dữ liệu dự án trên máy chủ
PROJECTS_DIR = os.path.join(Config.UPLOAD_FOLDER, 'projects') PROJECTS_DIR = os.path.join(Config.UPLOAD_FOLDER, 'projects')
@classmethod @classmethod
def _ensure_projects_dir(cls): def _ensure_projects_dir(cls):
"""确保项目目录存在""" """Đảm bảo thư mục lưu trữ dự án đã được tạo, nếu không có thì self tạo mới"""
os.makedirs(cls.PROJECTS_DIR, exist_ok=True) os.makedirs(cls.PROJECTS_DIR, exist_ok=True)
@classmethod @classmethod
def _get_project_dir(cls, project_id: str) -> str: def _get_project_dir(cls, project_id: str) -> str:
"""获取项目目录路径""" """Đường dẫn tới thư mục lưu trữ tương ứng với project_id"""
return os.path.join(cls.PROJECTS_DIR, project_id) return os.path.join(cls.PROJECTS_DIR, project_id)
@classmethod @classmethod
def _get_project_meta_path(cls, project_id: str) -> str: def _get_project_meta_path(cls, project_id: str) -> str:
"""获取项目元数据文件路径""" """Đường dẫn lấy file cài đặt metadata (thường là project.json)"""
return os.path.join(cls._get_project_dir(project_id), 'project.json') return os.path.join(cls._get_project_dir(project_id), 'project.json')
@classmethod @classmethod
def _get_project_files_dir(cls, project_id: str) -> str: def _get_project_files_dir(cls, project_id: str) -> str:
"""获取项目文件存储目录""" """Đường dẫn đến thư mục chứa các file nguyên thuỷ do người dùng kéo thả tải lên cho dự án"""
return os.path.join(cls._get_project_dir(project_id), 'files') return os.path.join(cls._get_project_dir(project_id), 'files')
@classmethod @classmethod
def _get_project_text_path(cls, project_id: str) -> str: def _get_project_text_path(cls, project_id: str) -> str:
"""获取项目提取文本存储路径""" """Lấy vị trí của tệp văn bản (txt) đã được hệ thống trích xuất nội dung"""
return os.path.join(cls._get_project_dir(project_id), 'extracted_text.txt') return os.path.join(cls._get_project_dir(project_id), 'extracted_text.txt')
@classmethod @classmethod
def create_project(cls, name: str = "Unnamed Project") -> Project: def create_project(cls, name: str = "Unnamed Project") -> Project:
""" """
创建新项目 Khởi tạo và tạo mới cấu trúc dự án trên server
Args: Args:
name: 项目名称 name: Tên của dự án
Returns: Returns:
新创建的Project对象 Project object vừa được tạo
""" """
cls._ensure_projects_dir() cls._ensure_projects_dir()
@ -153,20 +154,20 @@ class ProjectManager:
updated_at=now updated_at=now
) )
# 创建项目目录结构 # Thiết lập các thư mục con trong không gian thư mục của project
project_dir = cls._get_project_dir(project_id) project_dir = cls._get_project_dir(project_id)
files_dir = cls._get_project_files_dir(project_id) files_dir = cls._get_project_files_dir(project_id)
os.makedirs(project_dir, exist_ok=True) os.makedirs(project_dir, exist_ok=True)
os.makedirs(files_dir, exist_ok=True) os.makedirs(files_dir, exist_ok=True)
# 保存项目元数据 # Ghi các trường thông tin (metadata) của project vào file cứng
cls.save_project(project) cls.save_project(project)
return project return project
@classmethod @classmethod
def save_project(cls, project: Project) -> None: def save_project(cls, project: Project) -> None:
"""保存项目元数据""" """Ghi chồng cấu hình cập nhật (metadata mới) đối của project vào file (Mặc định: project.json) """
project.updated_at = datetime.now().isoformat() project.updated_at = datetime.now().isoformat()
meta_path = cls._get_project_meta_path(project.project_id) meta_path = cls._get_project_meta_path(project.project_id)
@ -176,10 +177,10 @@ class ProjectManager:
@classmethod @classmethod
def get_project(cls, project_id: str) -> Optional[Project]: def get_project(cls, project_id: str) -> Optional[Project]:
""" """
获取项目 Get Project
Args: Args:
project_id: 项目ID project_id: Project ID
Returns: Returns:
Project对象，如果不存在返回None Project对象，如果不存在返回None
@ -197,13 +198,13 @@ class ProjectManager:
@classmethod @classmethod
def list_projects(cls, limit: int = 50) -> List[Project]: def list_projects(cls, limit: int = 50) -> List[Project]:
""" """
列出所有项目 Lấy danh sách tất cả các dự án (projects) đang có trên system
Args: Args:
limit: 返回数量限制 limit: Giới hạn số lượng hiển thị (mặc định lấy 50 project)
Returns: Returns:
项目列表，按创建时间倒序 Danh sách gồm các Object Project, xếp theo ngày/giờ giảm dần (từ mới tạo -> cũ nhất)
""" """
cls._ensure_projects_dir() cls._ensure_projects_dir()
@ -213,7 +214,7 @@ class ProjectManager:
if project: if project:
projects.append(project) projects.append(project)
# 按创建时间倒序排序 # Sắp xếp lại lịch sử project theo thứ tự giảm dần thời gian
projects.sort(key=lambda p: p.created_at, reverse=True) projects.sort(key=lambda p: p.created_at, reverse=True)
return projects[:limit] return projects[:limit]
@ -221,47 +222,47 @@ class ProjectManager:
@classmethod @classmethod
def delete_project(cls, project_id: str) -> bool: def delete_project(cls, project_id: str) -> bool:
""" """
删除项目及其所有文件 Xoá vĩnh viễn dữ liệu về project và mọi file liên quan của nó khỏi server
Args: Args:
project_id: 项目ID project_id: Mã ID của Project
Returns: Returns:
是否删除成功 Boolean đại diện cờ Thành công / Thất bại của việc xoá
""" """
project_dir = cls._get_project_dir(project_id) project_dir = cls._get_project_dir(project_id)
if not os.path.exists(project_dir): if not os.path.exists(project_dir):
return False return False
shutil.rmtree(project_dir) shutil.rmtree(project_dir) # Xoá toàn bộ thư mục dữ liệu project_id
return True return True
@classmethod @classmethod
def save_file_to_project(cls, project_id: str, file_storage, original_filename: str) -> Dict[str, str]: def save_file_to_project(cls, project_id: str, file_storage, original_filename: str) -> Dict[str, str]:
""" """
保存上传的文件到项目目录 Ghi dữ liệu file đính kèm mà người dùng upload lên vào kho dự án
Args: Args:
project_id: 项目ID project_id: Mã định danh của Project
file_storage: Flask的FileStorage对象 file_storage: Đối tượng Request File (từ framework, VD: của thư viện Flask/FastAPI) chứa nội dung file byte
original_filename: 原始文件名 original_filename: Tên ban đầu từ máy tính người dùng
Returns: Returns:
文件信息字典 {filename, path, size} Object chứa kết quả lưu file mới gồm {tên ban đầu, tên hash được lưu, đường dẫn đầy đủ, dung lượng}
""" """
files_dir = cls._get_project_files_dir(project_id) files_dir = cls._get_project_files_dir(project_id)
os.makedirs(files_dir, exist_ok=True) os.makedirs(files_dir, exist_ok=True)
# 生成安全的文件名 # Biến đổi tên file thành chuỗi an toàn độc nhất (UUID) để giữ các phiên bản không bị ghi đè, với phần mở rộng ban đầu
ext = os.path.splitext(original_filename)[1].lower() ext = os.path.splitext(original_filename)[1].lower()
safe_filename = f"{uuid.uuid4().hex[:8]}{ext}" safe_filename = f"{uuid.uuid4().hex[:8]}{ext}"
file_path = os.path.join(files_dir, safe_filename) file_path = os.path.join(files_dir, safe_filename)
# 保存文件 # Uỷ quyền lưu vào đường dẫn đích
file_storage.save(file_path) file_storage.save(file_path)
# 获取文件大小 # Đếm kích thước dung lượng (byte) của tập tin tĩnh tại ổ cứng
file_size = os.path.getsize(file_path) file_size = os.path.getsize(file_path)
return { return {
@ -273,14 +274,14 @@ class ProjectManager:
@classmethod @classmethod
def save_extracted_text(cls, project_id: str, text: str) -> None: def save_extracted_text(cls, project_id: str, text: str) -> None:
"""保存提取的文本""" """Tạo/ghi văn bản trích xuất (từ nội dung phân tích File upload) cho dự án vào folder dữ liệu"""
text_path = cls._get_project_text_path(project_id) text_path = cls._get_project_text_path(project_id)
with open(text_path, 'w', encoding='utf-8') as f: with open(text_path, 'w', encoding='utf-8') as f:
f.write(text) f.write(text)
@classmethod @classmethod
def get_extracted_text(cls, project_id: str) -> Optional[str]: def get_extracted_text(cls, project_id: str) -> Optional[str]:
"""获取提取的文本""" """Đọc và lấy nội dung File văn bản được trích xuất nếu có trước đó"""
text_path = cls._get_project_text_path(project_id) text_path = cls._get_project_text_path(project_id)
if not os.path.exists(text_path): if not os.path.exists(text_path):
@ -291,7 +292,7 @@ class ProjectManager:
@classmethod @classmethod
def get_project_files(cls, project_id: str) -> List[str]: def get_project_files(cls, project_id: str) -> List[str]:
"""获取项目的所有文件路径""" """Lấy danh sách link đường dẫn gốc (absolute path) của các files (Tài liệu upload) thuộc dự án này"""
files_dir = cls._get_project_files_dir(project_id) files_dir = cls._get_project_files_dir(project_id)
if not os.path.exists(files_dir): if not os.path.exists(files_dir):

74
backend/app/models/task.py
View File

@ -1,6 +1,6 @@
""" """
任务状态管理 Quản lý trạng thái Task (tác vụ)
用于跟踪长时间运行的任务（如图谱构建） Được sử dụng để theo dõi các tác vụ chạy ngầm mất nhiều thời gian (ví dụ: xây dựng Knowledge Graph)
""" """
import uuid import uuid
@ -12,30 +12,30 @@ from dataclasses import dataclass, field
class TaskStatus(str, Enum): class TaskStatus(str, Enum):
"""任务状态枚举""" """Định nghĩa các trạng thái (Enum) mà một Task có thể có"""
PENDING = "pending" # 等待中 PENDING = "pending" # Đang chờ (Task mới được tạo, chưa được xử lý)
PROCESSING = "processing" # 处理中 PROCESSING = "processing" # Đang xử lý (Hệ thống đang chạy ngầm Task này)
COMPLETED = "completed" # 已完成 COMPLETED = "completed" # Đã hoàn thành thành công
FAILED = "failed" # 失败 FAILED = "failed" # Xảy ra lỗi và thất bại
@dataclass @dataclass
class Task: class Task:
"""任务数据类""" """Lớp dữ liệu lưu trữ thông tin của một Task cụ thể"""
task_id: str task_id: str
task_type: str task_type: str
status: TaskStatus status: TaskStatus
created_at: datetime created_at: datetime
updated_at: datetime updated_at: datetime
progress: int = 0 # 总进度百分比 0-100 progress: int = 0 # Phần trăm tiến độ quá trình chạy (0-100)
message: str = "" # 状态消息 message: str = "" # Thông báo trạng thái hiện tại để hiển thị cho người dùng
result: Optional[Dict] = None # 任务结果 result: Optional[Dict] = None # Kết quả trả về sau khi Task chạy xong
error: Optional[str] = None # 错误信息 error: Optional[str] = None # Thông tin chi tiết mỗi khi Task bị lỗi
metadata: Dict = field(default_factory=dict) # 额外元数据 metadata: Dict = field(default_factory=dict) # Siêu dữ liệu bổ sung kèm theo (ví dụ: project_id)
progress_detail: Dict = field(default_factory=dict) # 详细进度信息 progress_detail: Dict = field(default_factory=dict) # Nội dung thông tin chi tiết về các bước trong tiến trình
def to_dict(self) -> Dict[str, Any]: def to_dict(self) -> Dict[str, Any]:
"""转换为字典""" """Chuyển đổi Class thành Dictionary để map vào JSON API Response"""
return { return {
"task_id": self.task_id, "task_id": self.task_id,
"task_type": self.task_type, "task_type": self.task_type,
@ -53,15 +53,15 @@ class Task:
class TaskManager: class TaskManager:
""" """
任务管理器 Trình quản lý Task
线程安全的任务状态管理 Đảm bảo quản lý trạng thái của các tác vụ được đồng bộ tốt trên nhiều luồng chạy (Thread-safe)
""" """
_instance = None _instance = None
_lock = threading.Lock() _lock = threading.Lock()
def __new__(cls): def __new__(cls):
"""单例模式""" """Kế thừa Singleton Pattern (Chỉ khởi tạo 1 instance duy nhất trên toàn ứng dụng)"""
if cls._instance is None: if cls._instance is None:
with cls._lock: with cls._lock:
if cls._instance is None: if cls._instance is None:
@ -72,14 +72,14 @@ class TaskManager:
def create_task(self, task_type: str, metadata: Optional[Dict] = None) -> str: def create_task(self, task_type: str, metadata: Optional[Dict] = None) -> str:
""" """
创建新任务 Tạo mới một Task và cho vào hàng đợi (quản lý state)
Args: Args:
task_type: 任务类型 task_type: Loại tác vụ (vd: 'build_graph', 'generate_report', ...)
metadata: 额外元数据 metadata: Dữ liệu đính kèm (vd: project_id liên quan để cập nhật dữ liệu sau này)
Returns: Returns:
任务ID Chuỗi Mã định danh ngẫu nhiên (UUID) của Task
""" """
task_id = str(uuid.uuid4()) task_id = str(uuid.uuid4())
now = datetime.now() now = datetime.now()
@ -99,7 +99,7 @@ class TaskManager:
return task_id return task_id
def get_task(self, task_id: str) -> Optional[Task]: def get_task(self, task_id: str) -> Optional[Task]:
"""获取任务""" """Lấy thông tin một Task đang chạy/kết thúc dựa theo Task UUID"""
with self._task_lock: with self._task_lock:
return self._tasks.get(task_id) return self._tasks.get(task_id)
@ -114,16 +114,16 @@ class TaskManager:
progress_detail: Optional[Dict] = None progress_detail: Optional[Dict] = None
): ):
""" """
更新任务状态 Cập nhật tiến trình của Task
Args: Args:
task_id: 任务ID task_id: Mã ID của Task đang chạy
status: 新状态 status: Trạng thái cập nhật (Pending, Processing, Completed, Failed)
progress: 进度 progress: % Tiến độ hiện tại
message: 消息 message: Tin nhắn mô tả ngắn gọn hiện trạng làm gì
result: 结果 result: Trả về kết quả đầu ra khi thành công
error: 错误信息 error: Lời nhắn/Exception khi thất bại
progress_detail: 详细进度信息 progress_detail: Các sub-tiến trình chi tiết
""" """
with self._task_lock: with self._task_lock:
task = self._tasks.get(task_id) task = self._tasks.get(task_id)
@ -143,26 +143,26 @@ class TaskManager:
task.progress_detail = progress_detail task.progress_detail = progress_detail
def complete_task(self, task_id: str, result: Dict): def complete_task(self, task_id: str, result: Dict):
"""标记任务完成""" """Hành động đánh dấu tác vụ đã kết thúc Thành Công và gán 100% cho progress"""
self.update_task( self.update_task(
task_id, task_id,
status=TaskStatus.COMPLETED, status=TaskStatus.COMPLETED,
progress=100, progress=100,
message="任务完成", message="The task has been completed!",
result=result result=result
) )
def fail_task(self, task_id: str, error: str): def fail_task(self, task_id: str, error: str):
"""标记任务失败""" """Hành động đánh dấu tác vụ đã Thất Bại do lỗi"""
self.update_task( self.update_task(
task_id, task_id,
status=TaskStatus.FAILED, status=TaskStatus.FAILED,
message="任务失败", message="The task has an error!?",
error=error error=error
) )
def list_tasks(self, task_type: Optional[str] = None) -> list: def list_tasks(self, task_type: Optional[str] = None) -> list:
"""列出任务""" """Liệt kê danh sách tất cả các Task (Hoặc filter theo type của task)"""
with self._task_lock: with self._task_lock:
tasks = list(self._tasks.values()) tasks = list(self._tasks.values())
if task_type: if task_type:
@ -170,7 +170,7 @@ class TaskManager:
return [t.to_dict() for t in sorted(tasks, key=lambda x: x.created_at, reverse=True)] return [t.to_dict() for t in sorted(tasks, key=lambda x: x.created_at, reverse=True)]
def cleanup_old_tasks(self, max_age_hours: int = 24): def cleanup_old_tasks(self, max_age_hours: int = 24):
"""清理旧任务""" """Dọn dẹp/xoá khỏi bộ nhớ các Task đã cũ (Đã hoàn thành hoặc lỗi sau N giờ) để tránh rò rỉ hoặc xài tốn RAM"""
from datetime import timedelta from datetime import timedelta
cutoff = datetime.now() - timedelta(hours=max_age_hours) cutoff = datetime.now() - timedelta(hours=max_age_hours)