docs: update project structure and add database documentation

- Add tests/ directory to .gitignore - Document database connectivity with pyodbc and config - Add project structure and file organization guidelines - Update installation steps to use requirements.txt - Document new dependencies: pandas, openpyxl, pyodbc
2026-01-23 15:00:55 +08:00
parent 4b0a882b69
commit bbf84b7f8c
9 changed files with 456 additions and 322 deletions
--- a/docs/DEPENDENCIES.md
+++ b/docs/DEPENDENCIES.md
@@ -0,0 +1,169 @@
+# 项目依赖说明
+
+## Python 版本要求
+
+- Python >= 3.8
+
+## 依赖安装
+
+```bash
+# 激活虚拟环境 (Windows)
+.venv\Scripts\activate
+
+# 安装所有依赖
+pip install -r requirements.txt
+
+# 安装 Playwright 浏览器
+playwright install chromium
+```
+
+## 核心依赖
+
+### 1. playwright==1.57.0
+
+**用途**: 浏览器自动化框架
+
+**功能模块**:
+- `playwright.sync_api` - 同步 API
+- 浏览器启动与页面操作
+- 元素定位器 (Locator)
+- 弹窗处理 (expect_popup)
+- 嵌套 iframe 处理
+
+**使用文件**:
+- `test_playwright.py` - 主要自动化脚本
+- `record.py` - 录制脚本
+
+**重要**: 安装后需运行 `playwright install chromium` 下载浏览器
+
+---
+
+### 2. pyodbc>=5.0.0
+
+**用途**: SQL Server 数据库连接
+
+**功能模块**:
+- 数据库连接管理
+- SQL 查询执行
+- 事务处理
+
+**使用文件**:
+- `db/connection.py` - 数据库连接组件
+- `test_db_query.py` - 数据库查询测试脚本
+
+**注意**: Windows 系统通常已预装 ODBC 驱动，如遇连接问题请安装 [ODBC Driver 18 for SQL Server](https://learn.microsoft.com/zh-cn/sql/connect/odbc/download-odbc-driver-for-sql-server)
+
+---
+
+### 3. pandas>=2.0.0
+
+**用途**: 数据处理与分析
+
+**功能模块**:
+- DataFrame 数据结构
+- Excel 文件读写
+- 数据清洗与转换
+
+**使用文件**:
+- `excel_to_markdown.py` - Excel 转 Markdown
+- `analyze_excel.py` - Excel 数据分析
+
+---
+
+### 4. openpyxl>=3.1.0
+
+**用途**: Excel 文件操作
+
+**功能模块**:
+- 读取 `.xlsx` 文件
+- 工作表操作
+- 单元格读取
+
+**使用文件**:
+- `excel_to_markdown.py`
+- `analyze_excel.py`
+
+---
+
+### 5. numpy>=1.24.0
+
+**用途**: 数值计算
+
+**说明**: pandas 的依赖包，自动安装
+
+---
+
+### 6. python-dateutil>=2.8.0
+
+**用途**: 日期时间处理
+
+**说明**: pandas 的依赖包，自动安装
+
+---
+
+### 7. pytz>=2023.0
+
+**用途**: 时区处理
+
+**说明**: pandas 的依赖包，自动安装
+
+---
+
+## 传递依赖
+
+以下包由核心依赖自动安装，无需手动指定：
+
+| 包名 | 版本 | 被依赖包 |
+|------|------|----------|
+| greenlet | 3.3.0 | playwright |
+| pyee | 13.0.0 | playwright |
+| typing_extensions | 4.15.0 | 多个包 |
+| et_xmlfile | 2.0.0 | openpyxl |
+| six | 1.17.0 | python-dateutil |
+| tzdata | 2025.3 | pandas |
+
+---
+
+## 按功能分类
+
+### 浏览器自动化
+```
+playwright==1.57.0
+```
+
+### 数据库
+```
+pyodbc>=5.0.0
+```
+
+### Excel/数据处理
+```
+pandas>=2.0.0
+openpyxl>=3.1.0
+numpy>=1.24.0
+```
+
+---
+
+## 当前环境已安装包
+
+```
+Package           Version
+----------------- -----------
+et_xmlfile        2.0.0
+greenlet          3.3.0
+numpy             2.2.6
+openpyxl          3.1.5
+pandas            2.3.3
+pip               25.3
+playwright        1.57.0
+pyee              13.0.0
+python-dateutil   2.9.0.post0
+pytz              2025.2
+setuptools        65.5.0
+six               1.17.0
+typing_extensions 4.15.0
+tzdata            2025.3
+```
+
+**注意**: `pyodbc` 尚未安装，运行数据库相关脚本前请先安装。