lanyuanxiaoyao
833018d451
## 功能特性 - 建立统一的项目结构，包含 core/、readers/、utils/、tests/ 模块 - 迁移 lyxy-reader-office 的所有解析器（docx、xlsx、pptx、pdf） - 迁移 lyxy-reader-html 的所有解析器（html、url 下载） - 统一 CLI 入口为 lyxy_document_reader.py - 统一 Markdown 后处理逻辑 - 按文件类型组织 readers，每个解析器独立文件 - 依赖分组按文件类型细分（docx、xlsx、pptx、pdf、html、http） - PDF OCR 解析器优先，无参数控制 - 使用 logging 模块替代简单 print - 设计完整的单元测试结构 - 重写项目文档 ## 新增目录/文件 - core/ - 核心模块（异常体系、Markdown 工具、解析调度器） - readers/ - 格式阅读器（base.py + docx/xlsx/pptx/pdf/html） - utils/ - 工具函数（文件类型检测） - tests/ - 测试（conftest.py + test_core/ + test_readers/ + test_utils/） - lyxy_document_reader.py - 统一 CLI 入口 ## 依赖分组 - docx - DOCX 文档解析支持 - xlsx - XLSX 文档解析支持 - pptx - PPTX 文档解析支持 - pdf - PDF 文档解析支持（含 OCR） - html - HTML/URL 解析支持 - http - HTTP/URL 下载支持 - office - Office 格式组合（docx/xlsx/pptx/pdf） - web - Web 格式组合（html/http） - full - 完整功能 - dev - 开发依赖
138 lines
5.2 KiB
Markdown
138 lines
5.2 KiB
Markdown
## ADDED Requirements
|
||
|
||
### Requirement: 统一 CLI 入口
|
||
系统 SHALL 提供 lyxy_document_reader.py 作为统一的命令行入口，支持处理所有文档类型。
|
||
|
||
#### Scenario: 调用 CLI 帮助信息
|
||
- **WHEN** 用户执行 `uv run python lyxy_document_reader.py --help`
|
||
- **THEN** 系统显示完整的命令行参数帮助信息
|
||
|
||
#### Scenario: CLI 接受输入路径
|
||
- **WHEN** 用户执行 `uv run python lyxy_document_reader.py <input_path>`
|
||
- **THEN** 系统识别输入类型并解析文档
|
||
|
||
### Requirement: 输入类型自动识别
|
||
系统 SHALL 自动识别输入类型，包括 URL 和本地文件。
|
||
|
||
#### Scenario: 识别 HTTP URL
|
||
- **WHEN** 输入以 `http://` 或 `https://` 开头
|
||
- **THEN** 系统识别为 URL，使用 html-reader 处理
|
||
|
||
#### Scenario: 识别 DOCX 文件
|
||
- **WHEN** 输入文件扩展名为 .docx 或 .doc，或文件内容为 OOXML Word 格式
|
||
- **THEN** 系统识别为 DOCX，使用 docx-reader 处理
|
||
|
||
#### Scenario: 识别 XLSX 文件
|
||
- **WHEN** 输入文件扩展名为 .xlsx、.xls 或 .xlsm，或文件内容为 OOXML Excel 格式
|
||
- **THEN** 系统识别为 XLSX，使用 xlsx-reader 处理
|
||
|
||
#### Scenario: 识别 PPTX 文件
|
||
- **WHEN** 输入文件扩展名为 .pptx 或 .ppt，或文件内容为 OOXML PowerPoint 格式
|
||
- **THEN** 系统识别为 PPTX，使用 pptx-reader 处理
|
||
|
||
#### Scenario: 识别 PDF 文件
|
||
- **WHEN** 输入文件扩展名为 .pdf，或文件头为 %PDF
|
||
- **THEN** 系统识别为 PDF，使用 pdf-reader 处理
|
||
|
||
#### Scenario: 识别 HTML 文件
|
||
- **WHEN** 输入文件扩展名为 .html、.htm 或 .xhtml
|
||
- **THEN** 系统识别为 HTML，使用 html-reader 处理
|
||
|
||
### Requirement: 输出完整 Markdown
|
||
系统 SHALL 能够输出解析后的完整 Markdown 内容。
|
||
|
||
#### Scenario: 无查询参数时输出完整内容
|
||
- **WHEN** 用户不使用任何查询参数（-c/-l/-t/-tc/-s）
|
||
- **THEN** 系统输出完整的 Markdown 文档内容
|
||
|
||
### Requirement: 字数统计
|
||
系统 SHALL 支持统计解析后文档的总字数。
|
||
|
||
#### Scenario: 使用 -c 参数统计字数
|
||
- **WHEN** 用户使用 `-c` 或 `--count` 参数
|
||
- **THEN** 系统输出解析后文档的总字数（不含换行符）
|
||
|
||
### Requirement: 行数统计
|
||
系统 SHALL 支持统计解析后文档的总行数。
|
||
|
||
#### Scenario: 使用 -l 参数统计行数
|
||
- **WHEN** 用户使用 `-l` 或 `--lines` 参数
|
||
- **THEN** 系统输出解析后文档的总行数
|
||
|
||
### Requirement: 标题提取
|
||
系统 SHALL 支持提取文档中的所有标题行。
|
||
|
||
#### Scenario: 使用 -t 参数提取标题
|
||
- **WHEN** 用户使用 `-t` 或 `--titles` 参数
|
||
- **THEN** 系统输出解析后文档的所有 1-6 级标题行
|
||
|
||
### Requirement: 指定标题内容提取
|
||
系统 SHALL 支持提取指定标题及其下级内容。
|
||
|
||
#### Scenario: 使用 -tc 参数提取标题内容
|
||
- **WHEN** 用户使用 `-tc <name>` 或 `--title-content <name>` 参数
|
||
- **THEN** 系统输出所有匹配标题名称的标题及其下级内容，包含上级标题上下文，多个匹配用 --- 分隔
|
||
|
||
#### Scenario: 标题未找到时提示错误
|
||
- **WHEN** 指定的标题名称未找到
|
||
- **THEN** 系统输出错误信息并退出非零状态码
|
||
|
||
### Requirement: 正则搜索
|
||
系统 SHALL 支持使用正则表达式搜索文档内容。
|
||
|
||
#### Scenario: 使用 -s 参数搜索
|
||
- **WHEN** 用户使用 `-s <pattern>` 或 `--search <pattern>` 参数
|
||
- **THEN** 系统输出所有匹配结果及其上下文，多个匹配用 --- 分隔
|
||
|
||
#### Scenario: 使用 -n 参数指定上下文行数
|
||
- **WHEN** 用户同时使用 `-s <pattern>` 和 `-n <num>` 或 `--context <num>` 参数
|
||
- **THEN** 系统输出匹配结果及其前后指定行数的上下文（不含空行）
|
||
|
||
#### Scenario: 无效正则表达式提示错误
|
||
- **WHEN** 提供的正则表达式无效
|
||
- **THEN** 系统输出错误信息并退出非零状态码
|
||
|
||
#### Scenario: 无匹配结果提示错误
|
||
- **WHEN** 未找到任何匹配
|
||
- **THEN** 系统输出错误信息并退出非零状态码
|
||
|
||
### Requirement: Markdown 图片移除
|
||
系统 SHALL 自动移除解析结果中的 Markdown 图片标记。
|
||
|
||
#### Scenario: 移除图片标记
|
||
- **WHEN** 解析结果包含 `` 格式的图片标记
|
||
- **THEN** 系统移除这些图片标记
|
||
|
||
### Requirement: Markdown 空白规范化
|
||
系统 SHALL 规范化解析结果中的空白字符，保留单行空行。
|
||
|
||
#### Scenario: 规范化连续空行
|
||
- **WHEN** 解析结果包含连续 3 个或更多换行符
|
||
- **THEN** 系统将其替换为 2 个换行符（保留单行空行）
|
||
|
||
### Requirement: 使用 logging 模块
|
||
系统 SHALL 使用 Python logging 模块进行日志输出，而非简单 print。
|
||
|
||
#### Scenario: 日志输出
|
||
- **WHEN** 系统运行时
|
||
- **THEN** 所有日志信息通过 logging 模块输出
|
||
|
||
### Requirement: 自定义异常
|
||
系统 SHALL 使用自定义异常类处理错误，提供清晰的错误信息和位置上下文。
|
||
|
||
#### Scenario: 抛出 FileDetectionError
|
||
- **WHEN** 文件类型检测失败
|
||
- **THEN** 系统抛出 FileDetectionError 异常
|
||
|
||
#### Scenario: 抛出 ReaderNotFoundError
|
||
- **WHEN** 未找到适配的阅读器
|
||
- **THEN** 系统抛出 ReaderNotFoundError 异常
|
||
|
||
#### Scenario: 抛出 ParseError
|
||
- **WHEN** 文档解析失败
|
||
- **THEN** 系统抛出 ParseError 异常
|
||
|
||
#### Scenario: 抛出 DownloadError
|
||
- **WHEN** URL 下载失败
|
||
- **THEN** 系统抛出 DownloadError 异常
|