refactor: 重构文档结构,采用渐进式信息披露模式
将 README.md 拆分为多个专题文档,减少认知负荷: - 用户文档迁移到 docs/ (用户指南、元素、模板、参考等) - 开发文档迁移到 docs/development/ (架构、模块、规范) - README.md 精简至 ~290 行,仅保留概览和导航 - 删除 README_DEV.md,内容已迁移 - 归档 OpenSpec 变更 refactor-docs-progressive-disclosure
This commit is contained in:
112
docs/development/modules/validators.md
Normal file
112
docs/development/modules/validators.md
Normal file
@@ -0,0 +1,112 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user