lanyuanxiaoyao
124ef0e5ce
将 README.md 拆分为多个专题文档，减少认知负荷： - 用户文档迁移到 docs/ (用户指南、元素、模板、参考等) - 开发文档迁移到 docs/development/ (架构、模块、规范) - README.md 精简至 ~290 行，仅保留概览和导航 - 删除 README_DEV.md，内容已迁移 - 归档 OpenSpec 变更 refactor-docs-progressive-disclosure
113 lines
2.4 KiB
Markdown
113 lines
2.4 KiB
Markdown
# Validators 模块
|
|
|
|
`validators/` 目录包含所有验证相关的代码。
|
|
|
|
## 模块组成
|
|
|
|
### validators/result.py
|
|
|
|
验证结果数据结构：
|
|
|
|
```python
|
|
@dataclass
|
|
class ValidationIssue:
|
|
level: str # ERROR/WARNING/INFO
|
|
message: str
|
|
location: str = ""
|
|
code: str = ""
|
|
|
|
@dataclass
|
|
class ValidationResult:
|
|
errors: List[ValidationIssue]
|
|
warnings: List[ValidationIssue]
|
|
infos: List[ValidationIssue]
|
|
```
|
|
|
|
### validators/geometry.py
|
|
|
|
几何验证器，检查元素边界：
|
|
|
|
```python
|
|
class GeometryValidator:
|
|
def __init__(self, slide_width, slide_height):
|
|
self.slide_width = slide_width
|
|
self.slide_height = slide_height
|
|
self.tolerance = 0.1 # 英寸
|
|
|
|
def validate_element(self, element, slide_index, elem_index):
|
|
"""检查元素是否在页面范围内"""
|
|
# 检查边界
|
|
# 支持容忍度
|
|
```
|
|
|
|
### validators/resource.py
|
|
|
|
资源验证器，检查文件存在性：
|
|
|
|
```python
|
|
class ResourceValidator:
|
|
def __init__(self, base_dir):
|
|
self.base_dir = Path(base_dir)
|
|
|
|
def validate_image(self, src, slide_index, elem_index):
|
|
"""检查图片文件是否存在"""
|
|
# 检查文件路径
|
|
# 验证文件存在
|
|
```
|
|
|
|
### validators/validator.py
|
|
|
|
主验证器，协调所有子验证器：
|
|
|
|
```python
|
|
class Validator:
|
|
def __init__(self, slide_width, slide_height, base_dir):
|
|
self.geometry_validator = GeometryValidator(slide_width, slide_height)
|
|
self.resource_validator = ResourceValidator(base_dir)
|
|
|
|
def validate_presentation(self, presentation):
|
|
"""验证整个演示文稿"""
|
|
# 遍历所有幻灯片和元素
|
|
# 调用子验证器
|
|
```
|
|
|
|
## 验证职责分层
|
|
|
|
### 元素级验证
|
|
|
|
在元素类中完成：
|
|
- 必需字段检查
|
|
- 数据类型检查
|
|
- 值的有效性检查
|
|
|
|
### 系统级验证
|
|
|
|
在验证器中完成：
|
|
- 几何验证（需要页面尺寸）
|
|
- 资源验证（需要文件路径）
|
|
- 跨元素验证
|
|
|
|
## 验证容忍度
|
|
|
|
几何验证时，允许 0.1 英寸的容忍度：
|
|
|
|
```python
|
|
TOLERANCE = 0.1 # 英寸
|
|
|
|
if right > slide_width + TOLERANCE:
|
|
# 报告 WARNING
|
|
```
|
|
|
|
## 分级错误报告
|
|
|
|
- **ERROR**：阻止转换的严重问题
|
|
- **WARNING**：影响视觉效果的问题
|
|
- **INFO**：优化建议
|
|
|
|
## 相关文档
|
|
|
|
- [Elements 模块](elements.md) - 元素级验证
|
|
- [开发规范](../development-guide.md) - 验证职责
|
|
|
|
[返回开发文档索引](../README.md)
|