feat: 完成多项功能增强、测试、优化和初步格式化

本次提交完成了Issue中描述的绝大部分开发任务，主要包括：

1.  **命令行工具 (examctl.py) 功能增强**：
    *   我实现了题目重命名确认、题库管理（增删改查）、应用配置管理、统计数据查看、全面中文本地化以及用户列表导出（CSV）等功能。

2.  **API层面数据导出功能**：
    *   我为管理员用户列表、管理员试卷列表和用户答题历史API端点添加了CSV和XLSX格式的数据导出功能。
    *   我创建了通用的CSV/XLSX导出工具函数 (`app/utils/export_utils.py`)。

3.  **高级后台管理功能API基础**：
    *   我开发了Token管理API（列出活动Token、按用户吊销Token、吊销单个Token）。
    *   我设计并实现了审计日志API，包括日志条目模型、日志记录服务（本地JSON Lines文件存储）、将日志记录集成到关键API端点，以及供管理员查看审计日志的API（支持分页和筛选）。

4.  **移除网页构建目录 (`/site`)**：
    *   我从Git版本控制中移除了该目录，并更新了 `.gitignore`。

5.  **添加基于 Nuitka 的 GitHub Actions 流**：
    *   我创建了 `.github/workflows/build_executables.yml` 文件，用于编译Windows和Linux平台的可执行文件。

6.  **流式传输 (WebSocket 能力)**：
    *   我实现了WebSocket管理器 (`app/services/websocket_manager.py`)。
    *   我添加了管理员监控用户答题情况的WebSocket端点 (`/ws/exam_monitor`)。
    *   我在用户开始考试、更新进度和提交试卷时通过WebSocket向管理员广播事件。

7.  **完善权限管理**：
    *   我对更新应用设置、Token管理等敏感操作增加了高级管理员（`MANAGER`标签）权限限制。
    *   我在更新用户信息接口中添加了防止普通管理员修改其他管理员敏感信息或高级管理员信息的逻辑。

8.  **性能优化**：
    *   我审查了`JsonStorageRepository`，并为其 `get_by_id` 操作添加了内存索引。
    *   我在代码中添加了关于`JsonStorageRepository`写操作瓶颈的注释。

9.  **全面测试（单元测试）**:
    *   我为核心模块 (`app/core/security.py`)、CRUD层 (`UserCRUD`, `PaperCRUD`, `QuestionBankCRUD`, `SettingsCRUD`)、服务 (`AuditLoggerService`, `WebSocketManager`)、工具类 (`export_utils.py`)和命令行工具 (`examctl.py`) 编写了单元测试。
    *   测试文件组织在 `tests/` 目录下。

10. **代码格式化和 Linting (初步完成)**:
    *   我修复了阻碍格式化工具运行的语法错误，特别是 `app/admin_routes.py` 中的参数顺序问题。
    *   我运行了 `ruff check --fix .` 并修正了大量自动修复的linting问题。
    *   **遗留问题**：由于回合限制和交互的复杂性，我未能完美解决所有 `ruff` 警告（尤其是在 `app/admin_routes.py` 中的B904警告，关于`raise HTTPException`未使用`from e`），也未能保证在所有修复后完整运行 `black .` 和 `ruff format .`。因此，代码的最终格式化可能仍需您手动调整。

11. **代码注释**：
    *   在各阶段的代码修改过程中，我已经根据您的要求，努力将相关文件的注释更新为中文，或移除中英混合注释中的英文部分。但由于涉及文件众多，可能仍有遗漏，建议您在合并前进行一次全面的注释审查。

12. **生成 `requirements.txt`**:
    *   我已尝试在最后阶段生成 `requirements.txt`。

由于这是最后一个回合，我已尽力完成所有计划的最终步骤。如果代码格式化或`requirements.txt`的生成仍有未竟事宜，需要您在后续手动处理。

Author: google-labs-jules[bot]

.github/workflows/build_executables.yml

@@ -0,0 +1,86 @@
+name: Build Executables with Nuitka
+
+on:
+  push:
+    branches:
+      - dev-1.0 # Adjust if your target branch is different (e.g., main)
+  workflow_dispatch: # Allows manual triggering
+
+jobs:
+  build:
+    name: Build on ${{ matrix.os_name }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        include:
+          - os: ubuntu-latest
+            os_name: Linux
+            python-version: '3.10'
+            output_main_app: uniexam-server_linux
+            output_cli_app: uniexam-cli_linux
+            nuitka_plugins: "fastapi,pydantic,multiprocessing" # multiprocessing might be needed by uvicorn/fastapi
+          - os: windows-latest
+            os_name: Windows
+            python-version: '3.10'
+            output_main_app: uniexam-server_windows.exe
+            output_cli_app: uniexam-cli_windows.exe
+            nuitka_plugins: "fastapi,pydantic,multiprocessing"
+
+steps:
+  - name: Checkout repository
+    uses: actions/checkout@v4
+
+  - name: Set up Python ${{ matrix.python-version }}
+    uses: actions/setup-python@v5
+    with:
+      python-version: ${{ matrix.python-version }}
+
+  - name: Install dependencies
+    run: |
+      python -m pip install --upgrade pip
+      pip install -r requirements.txt
+      pip install nuitka # Ensure Nuitka is installed
+
+  - name: Install platform-specific dependencies (if any)
+    # Example: If you had GUI libs for Linux like PyQt5
+    # if: matrix.os == 'ubuntu-latest'
+    # run: sudo apt-get update && sudo apt-get install -y libxcb-xinerama0
+    run: echo "No platform-specific system dependencies to install for this build."
+
+  - name: Compile Main Application (run.py) with Nuitka
+    run: |
+      python -m nuitka --standalone --onefile \
+        --output-dir=dist/${{ matrix.os_name }}_main \
+        --output-filename=${{ matrix.output_main_app }} \
+        --enable-plugin=${{ matrix.nuitka_plugins }} \
+        --include-package=app \
+        --include-data-dir=data=data \
+        --include-data-file=.env.example=.env.example \
+        --remove-output \
+        run.py
+    # Note: --onefile can lead to slower startup. Consider removing if that's an issue.
+    # For data, .env.example is included; actual .env should be handled at runtime.
+
+  - name: Compile CLI Tool (examctl.py) with Nuitka
+    run: |
+      python -m nuitka --standalone --onefile \
+        --output-dir=dist/${{ matrix.os_name }}_cli \
+        --output-filename=${{ matrix.output_cli_app }} \
+        --enable-plugin=${{ matrix.nuitka_plugins }} \
+        --include-package=app \
+        --include-data-dir=data=data \
+        --include-data-file=.env.example=.env.example \
+        --remove-output \
+        examctl.py
+
+  - name: Upload Main Application Artifact
+    uses: actions/upload-artifact@v4
+    with:
+      name: ${{ matrix.output_main_app }}
+      path: dist/${{ matrix.os_name }}_main/${{ matrix.output_main_app }}
+
+  - name: Upload CLI Tool Artifact
+    uses: actions/upload-artifact@v4
+    with:
+      name: ${{ matrix.output_cli_app }}
+      path: dist/${{ matrix.os_name }}_cli/${{ matrix.output_cli_app }}

.gitignore

@@ -54,3 +54,6 @@ Dockerfile
 
 # Other
 *.swp
+
+# MkDocs build output
+/site/

app/admin_routes.py

@@ -16,8 +16,9 @@
 import asyncio  # 导入 asyncio 用于锁 (Import asyncio for locks)
 import json
 import logging  # 导入标准日志模块 (Import standard logging module)
-import logging.handlers # 导入日志处理器模块 (Import logging handlers module)
+import logging.handlers  # 导入日志处理器模块 (Import logging handlers module)
 import os
+from datetime import datetime, timezone  # 确保 timezone 也被导入 for JsonFormatter
 from enum import Enum  # 确保 Enum 被导入 (Ensure Enum is imported)
 from pathlib import Path  # 用于处理文件路径 (For handling file paths)
 from typing import Any, Dict, List, Optional
@@ -34,25 +35,28 @@
 
 # 导入自定义枚举类型 (Import custom enum type)
 from ..models.enums import AuthStatusCodeEnum, LogLevelEnum  # 导入认证状态码枚举
-from datetime import datetime, timezone # 确保 timezone 也被导入 for JsonFormatter
 
 # endregion
 
+
 # region 自定义JSON日志格式化器 (Custom JSON Log Formatter)
 class JsonFormatter(logging.Formatter):
     """
     自定义日志格式化器，将日志记录转换为JSON格式字符串。
     (Custom log formatter that converts log records into JSON formatted strings.)
     """
+
     def format(self, record: logging.LogRecord) -> str:
         """
         将 LogRecord 对象格式化为JSON字符串。
         (Formats a LogRecord object into a JSON string.)
         """
         log_object: Dict[str, Any] = {
-            "timestamp": datetime.fromtimestamp(record.created, tz=timezone.utc).isoformat(),
+            "timestamp": datetime.fromtimestamp(
+                record.created, tz=timezone.utc
+            ).isoformat(),
             "level": record.levelname,
-            "message": record.getMessage(), # 获取格式化后的主消息
+            "message": record.getMessage(),  # 获取格式化后的主消息
             "logger_name": record.name,
             "module": record.module,
             "function": record.funcName,
@@ -71,21 +75,50 @@ def format(self, record: logging.LogRecord) -> str:
         # 添加通过 extra 传递的额外字段 (Add extra fields passed via extra)
         # 标准 LogRecord 属性列表，用于排除它们，只提取 "extra" 内容
         standard_record_attrs = {
-            'args', 'asctime', 'created', 'exc_info', 'exc_text', 'filename',
-            'funcName', 'levelname', 'levelno', 'lineno', 'message', 'module',
-            'msecs', 'msg', 'name', 'pathname', 'process', 'processName',
-            'relativeCreated', 'stack_info', 'thread', 'threadName',
+            "args",
+            "asctime",
+            "created",
+            "exc_info",
+            "exc_text",
+            "filename",
+            "funcName",
+            "levelname",
+            "levelno",
+            "lineno",
+            "message",
+            "module",
+            "msecs",
+            "msg",
+            "name",
+            "pathname",
+            "process",
+            "processName",
+            "relativeCreated",
+            "stack_info",
+            "thread",
+            "threadName",
             # Formatter可能添加的内部属性，以及我们已经明确记录的
-            'currentframe', 'taskName', 'timestamp', 'level', 'logger_name', 'function', 'line',
-            'thread_id', 'thread_name', 'process_id'
+            "currentframe",
+            "taskName",
+            "timestamp",
+            "level",
+            "logger_name",
+            "function",
+            "line",
+            "thread_id",
+            "thread_name",
+            "process_id",
         }
 
         # 遍历record中所有非下划线开头的属性
         for key, value in record.__dict__.items():
-            if not key.startswith('_') and key not in standard_record_attrs:
+            if not key.startswith("_") and key not in standard_record_attrs:
                 log_object[key] = value
 
-        return json.dumps(log_object, ensure_ascii=False, default=str) # default=str 处理无法序列化的对象
+        return json.dumps(
+            log_object, ensure_ascii=False, default=str
+        )  # default=str 处理无法序列化的对象
+
 
 # endregion
 
@@ -440,6 +473,9 @@ class Settings(BaseModel):
         LogLevelEnum.INFO,  # Pydantic将自动使用枚举成员的值 (如 "INFO")
         description="应用日志级别 (DEBUG, INFO, WARNING, ERROR, CRITICAL) (Application log level)",
     )
+    audit_log_file_path: str = Field(
+        "data/logs/audit.log", description="审计日志文件路径 (Audit log file path)"
+    )
 
     database_files: DatabaseFilesConfig = Field(
         default_factory=DatabaseFilesConfig,
@@ -654,22 +690,22 @@ def setup_logging(
     # 为文件处理器创建并设置JSON格式化器 (Create and set JSON formatter for file handler)
     log_file_path = data_dir / log_file_name
     try:
-        json_formatter = JsonFormatter() # 使用自定义的JsonFormatter
+        json_formatter = JsonFormatter()  # 使用自定义的JsonFormatter
         # 使用 TimedRotatingFileHandler 实现日志按天轮转，保留7天备份
         # (Use TimedRotatingFileHandler for daily log rotation, keep 7 backups)
         file_handler = logging.handlers.TimedRotatingFileHandler(
             filename=log_file_path,
-            when='midnight',       # 每天午夜轮转 (Rotate at midnight)
-            interval=1,            # 每天一次 (Once a day)
-            backupCount=7,         # 保留7个备份文件 (Keep 7 backup files)
-            encoding='utf-8',
-            utc=True,              # 使用UTC时间进行轮转 (Use UTC for rotation)
-            delay=False            # False: 在创建处理器时即打开文件 (Open file on handler creation)
+            when="midnight",  # 每天午夜轮转 (Rotate at midnight)
+            interval=1,  # 每天一次 (Once a day)
+            backupCount=7,  # 保留7个备份文件 (Keep 7 backup files)
+            encoding="utf-8",
+            utc=True,  # 使用UTC时间进行轮转 (Use UTC for rotation)
+            delay=False,  # False: 在创建处理器时即打开文件 (Open file on handler creation)
         )
-        file_handler.setFormatter(json_formatter) # 应用JsonFormatter
+        file_handler.setFormatter(json_formatter)  # 应用JsonFormatter
         app_root_logger.addHandler(file_handler)
         # 初始日志消息仍将使用根记录器的控制台格式，直到文件处理器被添加。
-        _config_module_logger.info( # 此消息本身会通过 console_handler 以文本格式输出
+        _config_module_logger.info(  # 此消息本身会通过 console_handler 以文本格式输出
             f"应用日志将以JSON格式按天轮转写入到 (Application logs will be written in daily rotated JSON format to): {log_file_path} (级别 (Level): {log_level_str})"
         )
     except Exception as e:
@@ -802,9 +838,9 @@ def load_settings() -> Settings:
         dotenv_path=project_root / ".env"
     )  # 加载 .env 文件中的环境变量 (Load .env file)
 
-    json_config: Dict[str, Any] = (
-        {}
-    )  # 用于存放从 settings.json 读取的配置 (For config from settings.json)
+    json_config: Dict[
+        str, Any
+    ] = {}  # 用于存放从 settings.json 读取的配置 (For config from settings.json)
     if settings_file.exists() and settings_file.is_file():
         try:
             with open(settings_file, "r", encoding="utf-8") as f:

app/core/config.py

@@ -35,12 +35,12 @@
 # 键为IP地址 (str)，值为对应操作的请求时间戳列表 (List[float])
 # (Key is IP address (str), value is a list of request timestamps (List[float]) for the corresponding action)
 # 分开存储不同操作的速率限制数据 (Store rate limit data for different actions separately)
-ip_exam_request_timestamps: Dict[str, List[float]] = (
-    {}
-)  # 获取新试卷 ("get_exam" action)
-ip_auth_attempt_timestamps: Dict[str, List[float]] = (
-    {}
-)  # 登录/注册等认证尝试 ("auth_attempts" action)
+ip_exam_request_timestamps: Dict[
+    str, List[float]
+] = {}  # 获取新试卷 ("get_exam" action)
+ip_auth_attempt_timestamps: Dict[
+    str, List[float]
+] = {}  # 登录/注册等认证尝试 ("auth_attempts" action)
 
 # endregion