Update README File

Author: Evil0ctal

README-ZH.md

@@ -194,6 +194,152 @@
 - `python3 start.py`
 - 随后你可以访问`http://localhost`来查看接口文档，并且在网页上测试。
 
+## 🧵 目录结构详解
+
+### 前言：
+
+> 如果你有意参与本项目的开发，建议先阅读本部分内容，以便快速了解项目的设计和各模块的职责。我非常推荐诸位通读本项目的代码，项目中的每个方法都包含详细的中英双语注释、内部说明和变量解释，并且广泛应用了 `Typing` 标注类型。虽未必做到完美无瑕，但我也力求代码清晰优雅、易于理解。此外，我也希望大家一起学习异步编程，提出优化建议，共同改进代码，使项目更加高效和健壮，并且共同进步！
+
+#### 📁 `app/api/` - API层
+
+* **技术栈** ：基于 FastAPI 框架构建，为 API 请求提供高性能、可扩展的路由系统。
+* **功能实现** ：
+  * **APIResponseModel.py** ：通过 Pydantic 定义数据模型，确保 API 响应数据结构的统一性。
+  * **routers/** ：各路由文件分别管理不同功能模块的 API 端点：
+    * `health_check.py` 💓：快速检查服务健康状态，及时了解系统状态。
+    * `whisper_tasks.py` 📝：Whisper 相关任务的路由管理，支持任务的创建、查询、删除等操作。
+    * `work_flows.py` 🔄：工作流的管理路由，提供对工作流的 CRUD 功能接口，未来计划实现事件驱动式的自动化工作流。
+
+#### 📁 `app/crawlers/` - 异步爬虫模块
+
+* **技术栈** ：`httpx` 进行异步 HTTP 请求，结合 `pydantic` 模型实现数据规范化。
+* **功能实现** ：
+  * **platforms/** 包含针对各平台的爬虫模块，支持 Douyin 和 TikTok：
+    * **douyin/** 🕸️：提供 Douyin 视频的抓取、数据提取和 API 接口，包含了自定义的模型和实用工具类。
+    * **tiktok/** 🕹️：支持 TikTok 数据的抓取和 API 数据展示功能，计划进一步扩展其他社交媒体平台。
+* **解决问题** ：提供自动化的数据抓取能力，结合 Whisper 模型实现媒体数据的全流程自动化处理。
+
+#### 📁 `app/database/` - 数据库管理模块
+
+* **技术栈** ：
+  * 使用 `SQLAlchemy` 异步支持与 `AsyncSession`，提供了多种数据库操作的 CRUD 功能。
+  * 支持 `MySQL` 和 `SQLite` 数据库连接，并实现自动重连、表检查与初始化等基础操作。
+  * 集成自定义日志记录和异常处理机制，确保数据库操作的可靠性。
+* **功能实现** ：
+  * **DatabaseManager** 🗄️：实现了数据库连接管理和任务的增删改查等操作，并支持复杂的查询和批量处理。
+    * **数据库连接与自动初始化** ：通过 `_connect` 方法实现数据库连接的自动重试和动态表检查，在首次连接时自动创建所需表格。
+    * **任务管理** ：包括 `add_task`、`get_task`、`update_task`、`delete_task` 等方法，以便灵活操作任务数据，支持异步批量操作。
+    * **查询与筛选** ：提供 `query_tasks` 方法，根据条件过滤任务，并包含分页和条件构建器 `_build_query_conditions`，实现灵活的查询和筛选。
+    * **回调状态更新** ：专门的 `update_task_callback_status` 方法用于更新任务的回调信息，包括状态码、消息和回调时间。
+    * **工作流管理** ：支持创建和管理工作流（`Workflow`），包括工作流任务和通知，适合自动化任务流程。
+* **解决问题** ：
+  * **可靠的数据库连接管理** ：采用自动重试和异步上下文管理器（`get_session`）来确保会话管理的稳定性，解决数据库断开或连接失败等问题。
+  * **高效的批量操作支持** ：提供批量更新和删除功能，适合大规模任务处理，减少数据库交互次数，提高效率。
+  * **灵活的任务查询** ：支持复杂条件查询并实现分页功能，使得数据库管理器能满足多样化的数据访问需求，便于大型项目的管理和查询优化。
+
+#### 📁 `app/http_client/` - 异步 HTTP 客户端模块
+
+* **技术栈** ：
+  * 采用 `httpx` 实现高效的异步 HTTP 客户端，支持代理配置、重试机制、并发限制等功能。
+  * 自定义异常处理模块，实现针对不同 HTTP 状态码的精细化错误管理。
+  * 实现了包括重试、退避、限流等网络请求优化策略。
+* **功能实现** ：
+  * **AsyncHttpClient** 🌐：为项目提供了一个健壮的异步 HTTP 客户端工具，集成了以下主要功能：
+    * **请求与数据获取** ：支持 `GET`、`POST`、`HEAD` 等常见 HTTP 请求，包含 `fetch_get_json` 和 `fetch_post_json` 方法，返回结构化 JSON 数据。
+    * **文件下载支持** ：`download_file` 方法可异步下载文件并支持大文件分块下载，具备完善的下载状态监控和异常处理机制。
+    * **自动重试与退避策略** ：针对特定 HTTP 状态码，`fetch_data` 方法提供了指数退避策略，支持自定义重试次数，增强了网络请求的鲁棒性。
+    * **错误处理与自定义异常** ：根据 HTTP 响应状态码自定义异常类型，实现自动化的错误类型识别和记录，简化错误的调试和追踪。
+    * **代理支持与并发管理** ：支持动态代理配置和并发控制，最大并发请求数可调，确保 HTTP 客户端在高负载下的稳定性和可控性。
+* **解决问题** ：
+  * **网络请求优化** ：通过自动重试与退避机制处理网络中断或服务不可用等异常情况，提供高可用性网络请求支持。
+  * **高并发请求场景** ：在高并发场景下，利用 `asyncio.Semaphore` 控制并发数量，防止请求过载，确保客户端服务的稳定性。
+  * **可调配置与灵活使用** ：支持上下文管理器，方便资源释放，动态请求头配置满足不同接口需求，通过自定义代理和超时设置增强了请求的适配性和灵活性。
+
+#### 📁 `app/model_pool/` - 异步模型池模块
+
+* **技术栈** ：
+  * 使用 `asyncio` 与 `concurrent.futures` 结合管理 GPU 与 CPU 模型实例。
+  * 利用线程安全单例模式确保 `AsyncModelPool` 的唯一实例，避免多线程环境下资源竞争。
+  * 设备自动分配和池大小优化逻辑：根据系统硬件资源（如 GPU 数量和 CPU 线程）动态调整池的配置参数。
+* **功能实现** ：
+  * **AsyncModelPool** 🧠：提供一个线程安全、动态可调的模型池管理系统，实现了以下主要功能：
+    * **设备分配和动态创建** ：根据 GPU 和 CPU 配置自动分配设备，支持多 GPU 并发，并限制每个 GPU 上的模型实例数量，确保高效利用硬件资源。
+    * **初始化与批量加载** ：支持异步批量加载模型实例，通过 `initialize_pool` 方法按需创建模型，减少并发加载冲突。
+    * **模型实例获取与归还** ：提供 `get_model` 和 `return_model` 方法，实现模型的并发获取与归还。支持“现有实例”与“动态创建”两种策略，实现灵活的资源分配。
+    * **健康检查与销毁** ：包含 `_is_model_healthy` 和 `_destroy_model` 方法，确保模型实例在使用前的健康状态并在销毁后执行资源清理，避免内存泄漏，由于Whisper属于静态模型，这两个方法目前没有使用的必要，暂时保留。
+    * **池大小调整** ：`resize_pool` 方法允许动态调整池大小，增加或移除模型实例以适应当前负载，当前未使用该方法，需要设计一个智能的大小调整逻辑。
+* **解决问题** ：
+  * **硬件资源优化** ：通过动态调整模型池大小，避免了资源浪费和过度分配，确保模型实例数量与硬件资源的实际配置匹配。
+  * **多任务并发支持** ：在多任务请求场景下提供高效的模型实例分配策略，支持每个 GPU 的并发使用，并限制最大实例数以避免资源竞争。
+  * **自动故障检测与处理** ：具备模型健康检查和错误处理机制，能够在发现损坏或不可用的模型实例后自动销毁并释放资源，保持池内实例健康稳定。
+
+#### 📁 `app/processors/` - 任务与工作流处理模块
+
+* **技术栈** ：
+  * 基于 `asyncio` 实现异步处理，结合线程池和队列机制，支持多任务并发管理。使用 `concurrent.futures` 提供线程池以提高任务处理效率。
+  * 支持与数据库和文件操作的协同处理，确保高并发情况下的数据一致性和资源高效利用。
+* **功能实现** ：
+  * **task_processor.py** 📋：实现了 Whisper 任务的后台处理逻辑，具备多队列设计、事件循环管理、任务优先级调度、并行任务处理、数据库更新和文件操作等功能。通过异步和线程池结合，支持大规模、高性能的语音转文本任务处理。
+    * **任务队列和优先级调度** ：包含多个任务队列，分离不同类型任务（如清理、回调等），支持任务优先级从数据库按需拉取，保证重要任务优先处理。
+    * **并行任务处理** ：结合线程池并行处理多个任务，通过异步方法 `_process_multiple_tasks` 提高处理吞吐量。
+    * **事件循环管理** ：通过 `run_loop` 方法启动后台事件循环，持续监控和处理任务队列，实现任务管理的自动化和实时性。
+  * **workflow_processor.py** 🔄：用于管理复杂工作流，支持自定义的任务依赖、条件判断和自动化调度。未来将增加事件触发的自动化工作流，进一步扩展处理逻辑。
+* **解决问题** ：
+  * **高并发处理** ：通过事件循环和多线程的结合，在大批量任务处理场景下提供高吞吐量和低延迟的任务处理能力。
+  * **任务分离和优先级支持** ：多队列和优先级调度机制确保不同类型任务独立处理，重要任务可以优先执行，增强了系统的响应速度和任务管理的灵活性。
+  * **资源优化** ：对 GPU、数据库、文件存储的有效管理，通过 `AsyncModelPool` 实现高效模型实例管理，确保大规模任务在资源紧张情况下的平稳处理。
+
+#### 📁 `app/services/` - 服务层模块
+
+* **技术栈** ：
+  * 使用 `FastAPI` 与 `asyncio` 提供高效异步服务，支持音频处理、转录、回调管理和工作流控制。
+  * 集成 `pydub` 和 `moviepy` 库用于音频和视频转换，使用 `ThreadPoolExecutor` 和 `BackgroundTasks` 实现并发文件处理和后台任务。
+  * 回调和工作流服务的设计为未来扩展和自定义任务提供支持。
+* **功能实现** ：
+  * **WhisperService** 🗣️：负责音频提取、转录任务的创建和字幕生成。
+    * **音频提取** ：`extract_audio_from_video` 方法提取视频中的音频（WAV 或 MP3 格式），并自动清理临时文件。
+    * **转录任务创建** ：`create_whisper_task` 方法接受文件或 URL，创建转录任务并保存到数据库，生成任务输出链接。
+    * **字幕生成** ：`generate_subtitle` 方法将转录结果转换为字幕文件（支持 SRT 和 VTT），并在完成后删除临时文件。
+  * **CallbackService** 📞：处理任务的回调通知，将结果传递给预定义的回调 URL，并记录回调状态。
+    * **回调通知** ：在任务完成后，通过 `task_callback_notification` 发送请求至回调 URL，通知任务结果并记录响应状态。
+    * **重试机制** ：支持失败重试，通过 `base_backoff` 设置指数回退，确保重要通知的可靠性。
+  * **WorkflowService** 🔄（待实现）：用于管理复杂的自动化任务工作流。
+    * **工作流控制** ：计划通过 `WorkflowService` 管理和执行一系列依赖任务，支持条件判断、任务依赖和回调管理，适用于自动化批量任务处理场景。
+    * **任务编排与状态跟踪** ：未来将支持工作流任务的状态跟踪和条件控制，提供灵活的工作流设计。
+    * **扩展能力** ：支持自定义的工作流步骤与组件配置，用户可以定义和配置不同的工作流来适应业务需求。
+* **解决问题** ：
+  * **高效任务处理与回调通知** ：利用 `TaskProcessor` 实现任务并发处理，并通过 `CallbackService` 确保任务完成后的回调通知机制的可靠性。
+  * **灵活工作流与扩展支持** ：`WorkflowService` 提供面向未来的工作流处理框架，使用户能更灵活地管理和监控一系列任务的执行顺序和依赖。
+  * **资源管理与文件清理** ：通过 `BackgroundTasks` 支持异步文件处理和清理，优化资源管理，确保高效和稳定的文件处理体验。
+
+#### 📁 `app/utils/` - 工具模块
+
+* **技术栈** ：Python 原生文件操作与日志模块，结合 `aiofiles` 实现高效异步文件操作，并使用 `ConcurrentRotatingFileHandler` 实现并发安全的日志轮转。
+* **功能实现** ：
+  * **file_utils.py** 📂：提供文件下载、保存、删除与清理操作，支持文件大小限制与类型检查，确保文件安全，适用于高并发的文件管理需求。
+  * **logging_utils.py** 📊：配置项目日志记录，支持文件和控制台输出，日志级别控制、文件自动轮转（10MB）和备份，便于调试与长期日志存储。
+* **解决问题** ：
+  * **资源管理** ：通过异步上下文管理器和自动删除机制清理临时文件，防止资源泄漏，确保系统稳定。
+  * **文件安全与权限管理** ：严格控制文件大小、类型和权限，防止未经授权的文件访问和资源滥用。
+  * **并发优化** ：利用信号量控制文件操作并发性，提升 I/O 性能。
+  * **日志轮转与安全** ：通过日志轮转与多进程支持，确保在高并发环境下日志输出的完整性与一致性，提供稳定的日志记录系统。
+
+#### 📁 `app/workflows/` - 工作流组件（待完善）
+
+* **技术栈** ：Python 自定义组件设计，未来可扩展支持基于 JSON 或自定义 Python 的任务流配置。
+* **功能实现** ：
+  * **components/** ：组件模块，用于扩展工作流的功能。
+    * `base_component.py` 🛠️：定义工作流组件的基类，支持通用方法和事件。
+    * `component_a.py`、`component_b.py`：自定义的工作流组件示例，支持扩展功能。
+* **解决问题** ：提供扩展性极高的组件设计，便于用户根据业务需求定义复杂的任务流程和自定义组件。
+
+#### 📄 `config/settings.py` - 配置文件
+
+* **技术栈** ：`dotenv` 解析环境变量，配置 FastAPI、数据库和模型池等参数。
+* **功能实现** ：
+  * 统一管理项目配置，方便进行数据库、模型池、服务地址等参数的集中配置。
+* **解决问题** ：提高配置灵活性，支持快速切换本地和生产环境配置。
+
 ## 🍱 接口使用示例
 
 - 添加一个TikTok任务（CURL格式）