From 81f7e205e1ab163f5a34a42e2ee7df616d93af79 Mon Sep 17 00:00:00 2001
From: wangqifan <wangqifan@zhiyun.com>
Date: Sun, 10 Aug 2025 11:24:02 +0800
Subject: [PATCH] first commit

---
 README.md | 107 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 107 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a78f8c9
--- /dev/null
+++ b/README.md
@@ -0,0 +1,107 @@
+# Selenium 模块化项目架构
+
+这是一个使用 Python 和 Selenium 的模块化项目架构，支持通过命令行参数调用不同的业务逻辑，并支持两种方式启动和控制 Google Chrome 浏览器。
+
+## 文件结构
+
+```
+.
+├── browser_manager.py          # 管理浏览器启动和 WebDriver 实例
+├── config.py                   # 存放项目配置，如调试端口和用户目录
+├── main.py                     # 项目主入口，负责解析参数和调用模块
+├── requirements.txt            # 项目依赖库
+├── modules/                    # 存放所有独立的业务逻辑模块
+│   └── or_address_handler.py   # 处理 o-address.csv 的业务模块
+├── data/                       # 存放数据文件
+│   └── o-address.csv           # 示例数据文件
+└── chrome_user_data/           # (自动生成) Chrome 用户数据目录
+```
+
+## 安装依赖
+
+在开始之前，请确保你已经安装了 Python。然后通过以下命令安装所需的库：
+
+```bash
+pip install -r requirements.txt
+```
+
+## 如何运行
+
+现在，所有操作都通过命令行来执行，使用 `main.py` 作为入口。
+
+### 基本命令格式
+
+```bash
+python main.py --module <模块名称> [--debug]
+```
+
+-   `--module <模块名称>`: **必需参数**。指定要运行的业务模块。当前可用的模块是 `or-address`。
+-   `--debug`: **可选参数**。如果带上这个参数，脚本会尝试连接到一个已存在的 Chrome 浏览器，而不是启动一个新浏览器。
+
+### 示例 1: 启动新浏览器执行任务
+
+这是最常见的用法。下面的命令会启动一个全新的浏览器，并执行 `or-address` 模块定义的任务。
+
+```bash
+python main.py --module or-address
+```
+
+### 示例 2: 连接到现有浏览器执行任务
+
+如果你需要保持登录状态或利用已打开的浏览器会话，可以使用 `--debug` 模式。
+
+1.  **手动启动 Chrome 浏览器**：
+    打开你的命令行工具 (CMD 或 PowerShell)，然后运行以下命令。这会启动一个特殊的 Chrome 实例，并开启一个调试端口。
+
+    ```bash
+    chrome.exe --remote-debugging-port=9222 --user-data-dir="d:/project/zhiyun-scripy/chrome_user_data"
+    ```
+    > **注意**: 
+    > - `--remote-debugging-port` 的值必须与 `config.py` 中的 `CHROME_DEBUGGER_PORT` 一致。
+    > - `--user-data-dir` 指定了一个用户配置文件的目录，请确保路径是绝对路径。
+    > - 如果 `chrome.exe` 不在你的系统 PATH 中，你可能需要提供它的完整路径。
+
+2.  **运行脚本并连接**：
+    在另一个终端中，运行以下命令。`--debug` 参数会告诉脚本去连接你刚才手动打开的浏览器。
+
+    ```bash
+    python main.py --module or-address --debug
+    ```
+
+## 如何添加新的业务模块？
+
+1.  在 `modules/` 目录下创建一个新的 Python 文件，例如 `new_task_handler.py`。
+2.  在这个新文件中，定义一个函数，该函数接收 `driver` 作为参数。例如：
+
+    ```python
+    # modules/new_task_handler.py
+    def process_new_task(driver):
+        print("正在执行新任务...")
+        driver.get("https://www.example.com")
+        # ... 在这里编写你的新业务逻辑 ...
+    ```
+
+3.  打开 `main.py` 文件，将你的新模块和处理函数添加到 `MODULES` 字典中：
+
+    ```python
+    # main.py
+    from modules.or_address_handler import process_addresses
+    from modules.new_task_handler import process_new_task # 导入新函数
+
+    MODULES = {
+        "or-address": process_addresses,
+        "new-task": process_new_task, # 添加新模块的映射
+    }
+    ```
+
+4.  现在你就可以通过命令行调用你的新模块了：
+
+    ```bash
+    python main.py --module new-task
+    ```
+
+## 其他说明
+
+-   **`browser_manager.py`**: 一般情况下你不需要修改这个文件。
+-   **`config.py`**: 如果你需要更改调试端口或用户数据目录的名称，可以修改这个文件。
+-   **`data/`**: 所有需要被脚本读取的数据文件（如 CSV, Excel, TXT）都建议放在这个目录下。