lanyuanxiaoyao
124ef0e5ce
将 README.md 拆分为多个专题文档，减少认知负荷： - 用户文档迁移到 docs/ (用户指南、元素、模板、参考等) - 开发文档迁移到 docs/development/ (架构、模块、规范) - README.md 精简至 ~290 行，仅保留概览和导航 - 删除 README_DEV.md，内容已迁移 - 归档 OpenSpec 变更 refactor-docs-progressive-disclosure
2.4 KiB
2.4 KiB
Validators 模块
validators/ 目录包含所有验证相关的代码。
模块组成
validators/result.py
验证结果数据结构：
@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
几何验证器，检查元素边界：
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
资源验证器，检查文件存在性：
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
主验证器，协调所有子验证器：
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 英寸的容忍度：
TOLERANCE = 0.1 # 英寸
if right > slide_width + TOLERANCE:
# 报告 WARNING
分级错误报告
- ERROR：阻止转换的严重问题
- WARNING：影响视觉效果的问题
- INFO：优化建议
相关文档
- Elements 模块 - 元素级验证
- 开发规范 - 验证职责