modify: 代码注释

src/chongming/scripts/build.py

@@ -1,21 +1,31 @@
-import platform
-
-from module_bank import PythonToSQLite
-from module_bank.encryption import Encryption
 import os
-from pathlib import Path
+import platform
 import shutil
 import subprocess
 import sys
 import asyncio
+from pathlib import Path
+
+from module_bank import PythonToSQLite
+from module_bank.encryption import Encryption
 from sqlite_vfs.core import SQLiteVFS
 from sqlite_vfs.folder_packer import FolderPacker
 
 
 is_windows = platform.system() == "Windows"
 
+
 def build_vue_web():
-    """打包 Vue Web"""
+    """
+    打包 Vue Web 前端项目
+
+    该函数执行以下操作:
+    1. 运行 npm build 命令构建 Vue 项目
+    2. 将构建产物打包到 SQLite VFS 虚拟文件系统中
+
+    Returns:
+        None: 无返回值,通过打印信息反馈执行结果
+    """
     # 构建 Vue Web 命令
     dist_dir = "./src/chongming-web/dist"
     output_db = "./build/static.svfs"
@@ -43,12 +53,12 @@ def build_vue_web():
         print("Vue Web 打包成功")
         if result.stdout:
             print(result.stdout)
-    
+
     # 检查 dist 目录是否存在
     if not os.path.exists(dist_dir):
         print(f"错误: dist 目录不存在: {dist_dir}")
         return
-    
+
     vfs = SQLiteVFS(output_db, compress=False)
     packer = FolderPacker(
         sqlite_vfs=vfs,
@@ -58,12 +68,27 @@ def build_vue_web():
 
     try:
         packer.pack_folder(dist_dir)
-        print(f"✅ 打包完成，文件保存为 {output_db}")
+        print(f"✅ 打包完成,文件保存为 {output_db}")
     finally:
         vfs.close()
 
 
 def run_pyarmor_obfuscate():
+    """
+    使用 PyArmor 对关键 Python 文件进行代码混淆
+
+    该函数遍历预定义的文件列表,对每个文件执行 pyarmor gen 命令进行混淆处理,
+    以保护源代码不被轻易反编译。
+
+    处理的文件包括:
+    - main.py (主入口文件)
+    - server.py (服务器文件)
+    - utils/launch.py (启动工具)
+    - utils/config.py (配置工具)
+
+    Returns:
+        None: 无返回值,遇到错误时提前返回
+    """
     # pyarmor obfuscate --output=obfuscated_script.py original_script.py
     obfuscate_files = [
         ("main.py", "./"),
@@ -89,7 +114,18 @@ def run_pyarmor_obfuscate():
 
 
 def run_pyinstaller():
-    """运行 PyInstaller 打包成可执行文件"""
+    """
+    使用 PyInstaller 将应用打包成单文件可执行程序
+
+    该函数根据操作系统平台(Windows/非Windows)构建不同的 PyInstaller 命令,
+    包含所有必要的隐藏导入以确保依赖库被正确打包。
+
+    Windows 和非 Windows 平台的主要区别:
+    - 非 Windows 平台额外包含 gunicorn 相关模块
+
+    Returns:
+        None: 无返回值,通过打印信息反馈执行结果
+    """
     try:
         # 构建 PyInstaller 命令
         if is_windows:
@@ -230,19 +266,36 @@ def run_pyinstaller():
         result = subprocess.run(cmd, cwd="./build", capture_output=True, text=True)
 
         if result.returncode == 0:
-            print("PyInstaller 打包成功！")
+            print("PyInstaller 打包成功!")
             print(result.stdout)
         else:
-            print("PyInstaller 打包失败！")
+            print("PyInstaller 打包失败!")
             print("错误信息:", result.stderr)
 
     except FileNotFoundError:
-        print("错误：未找到 PyInstaller，请先安装 PyInstaller：pip install pyinstaller")
+        print("错误:未找到 PyInstaller,请先安装 PyInstaller:pip install pyinstaller")
     except Exception as e:
         print(f"PyInstaller 执行出错: {e}")
 
 
 async def init_database():
+    """
+    异步初始化数据库
+
+    该函数执行以下操作:
+    1. 从配置中读取数据库连接信息
+    2. 创建异步数据库引擎和会话工厂
+    3. 设置 SQLite 优化参数(WAL 模式和同步策略)
+    4. 创建所有 SQLModel 定义的数据库表
+    5. 初始化权限系统和默认管理员账户
+
+    Raises:
+        ValueError: 当数据库配置不存在时抛出
+        OperationalError: 当数据库操作出现异常时抛出(已存在表的情况除外)
+
+    Returns:
+        None: 无返回值
+    """
     from sqlalchemy.ext.asyncio import create_async_engine
     from sqlmodel import SQLModel, text
     from sqlalchemy.exc import OperationalError
@@ -284,6 +337,23 @@ async def init_database():
 
 
 async def main():
+    """
+    主构建流程函数
+
+    该函数协调整个应用的构建过程,按顺序执行以下步骤:
+    1. 加密打包 Python 模块(app 和 plugins)到 SQLite 数据库文件
+    2. 创建并准备 build 目录结构
+    3. 复制必要的源文件和配置文件到 build 目录
+    4. 注入动态生成的加密密钥到配置文件
+    5. 对关键文件进行代码混淆
+    6. 使用 PyInstaller 打包成可执行文件
+    7. 清理临时构建文件
+    8. 初始化数据库
+    9. 构建 Vue 前端项目
+
+    Returns:
+        None: 无返回值
+    """
     # 打包模块
     key = Encryption.generate_key()
     resources_path = Path("resources")
@@ -367,4 +437,12 @@ async def main():
 
 
 def build():
+    """
+    构建入口函数
+
+    该函数作为整个构建流程的入口点,通过 asyncio.run() 启动异步主构建流程。
+
+    Returns:
+        None: 无返回值
+    """
     asyncio.run(main())