# ATProto Data 和 Lexicon 模块架构总览

## 项目概述

本项目为 ATProto (Authenticated Transfer Protocol) 提供 Python 实现，专注于数据模型和 Lexicon 定义的处理。基于现有的 URI 模块架构模式，提供类型安全的数据验证、序列化和 Lexicon 解析功能。

## 整体架构设计

### 1. 系统架构图

```mermaid
graph TB
    subgraph "ATProto 核心模块"
        URI[URI 模块]
        Data[Data 模块]
        Lexicon[Lexicon 模块]
    end
    
    subgraph "外部依赖"
        Pydantic[Pydantic]
        CBOR[cbor2]
        CID[py-cid]
    end
    
    subgraph "数据流"
        LexiconJSON[Lexicon JSON 文件]
        RawData[原始数据]
    end
    
    LexiconJSON --> Lexicon
    Lexicon --> Data
    RawData --> Data
    Data --> Serialized[序列化数据]
    
    URI --> Data
    URI --> Lexicon
    
    Pydantic --> Data
    Pydantic --> Lexicon
    CBOR --> Data
    CID --> Data
```

### 2. 模块职责划分

#### 2.1 Data 模块 (`src/atpasser/data`)
- **数据序列化**: JSON 和 DAG-CBOR 格式的序列化/反序列化
- **数据验证**: 类型验证、格式验证、约束验证
- **特殊类型处理**: CID 链接、Blob 引用、日期时间格式等
- **错误处理**: 详细的验证错误和序列化错误

#### 2.2 Lexicon 模块 (`src/atpasser/lexicon`)
- **定义解析**: 解析 Lexicon JSON 定义文件
- **模型生成**: 动态生成 Pydantic 模型类
- **引用解析**: 处理跨定义引用和联合类型
- **注册管理**: 模型注册表和缓存管理
- **兼容性验证**: 前向和后向兼容性检查

### 3. 核心功能特性

#### 3.1 类型安全
- 基于 Pydantic 的强类型系统
- 运行时类型验证
- 自动类型转换和规范化

#### 3.2 格式支持
- **JSON**: 符合 ATProto JSON 编码规范
- **DAG-CBOR**: 支持规范的 DAG-CBOR 编码
- **混合格式**: 支持两种格式间的转换

#### 3.3 验证系统
- 语法验证 (基础数据类型)
- 语义验证 (业务规则和约束)
- 格式验证 (字符串格式如 datetime、uri、did 等)
- 引用验证 (CID、blob、跨定义引用)

### 4. 集成架构

#### 4.1 与现有 URI 模块的集成

```python
# 示例：URI 与 Data 模块的集成
from atpasser.uri import URI, NSID
from atpasser.data import ATProtoSerializer
from atpasser.lexicon import LexiconRegistry

# 解析 URI
uri = URI("at://example.com/com.example.blog.post/123")

# 根据 NSID 获取对应的数据模型
model_class = LexiconRegistry.get_model(uri.collection.nsid)

# 使用 Data 模块处理数据
serializer = ATProtoSerializer()
data = serializer.from_json(raw_data, model_class)
```

#### 4.2 数据流架构

```
原始数据 → Data 模块验证 → Lexicon 模型转换 → 序列化输出
Lexicon JSON → Lexicon 模块解析 → 生成 Pydantic 模型 → 注册到注册表
```

### 5. 错误处理架构

#### 5.1 统一的错误体系

```python
class ATProtoError(Exception):
    """基础错误类"""
    pass

class DataError(ATProtoError):
    """数据相关错误"""
    pass

class LexiconError(ATProtoError):
    """Lexicon 相关错误"""
    pass

class URIError(ATProtoError):
    """URI 相关错误"""
    pass
```

#### 5.2 错误诊断
- **字段级错误定位**: 精确到具体字段的路径信息
- **上下文信息**: 包含验证时的输入数据和期望格式
- **建议修复**: 提供具体的修复建议

### 6. 性能优化策略

#### 6.1 缓存机制
- **模型缓存**: 缓存已解析的 Lexicon 模型
- **序列化缓存**: 缓存序列化结果
- **引用解析缓存**: 缓存跨定义引用解析结果

#### 6.2 懒加载
- 按需解析 Lexicon 定义
- 延迟模型生成直到实际使用
- 动态导入依赖模块

### 7. 扩展性设计

#### 7.1 插件系统
- 支持自定义类型处理器
- 支持自定义验证规则
- 支持自定义序列化格式

#### 7.2 中间件支持
- 预处理钩子 (数据清洗、转换)
- 后处理钩子 (日志记录、监控)
- 验证钩子 (自定义验证逻辑)

### 8. 实施路线图

#### 阶段 1: 基础实现 (2-3 周)
- 实现 Data 模块基础类型和 JSON 序列化
- 实现 Lexicon 模块基础解析器
- 建立基本的错误处理系统

#### 阶段 2: 完整功能 (3-4 周)
- 添加 CBOR 序列化支持
- 实现完整的验证系统
- 添加引用解析和联合类型支持

#### 阶段 3: 优化增强 (2 周)
- 实现缓存和性能优化
- 添加高级格式验证
- 完善错误处理和诊断信息

#### 阶段 4: 测试部署 (1-2 周)
- 编写完整的测试套件
- 性能测试和优化
- 文档编写和示例代码

### 9. 依赖管理

#### 9.1 核心依赖
- `pydantic >=2.11.9`: 数据验证和模型定义
- `cbor2 >=5.7.0`: CBOR 序列化支持
- `py-cid >=0.3.0`: CID 处理支持

#### 9.2 可选依赖
- `jsonpath-ng >=1.7.0`: JSONPath 支持
- `langcodes >=3.5.0`: 语言代码验证

### 10. 质量保证

#### 10.1 测试策略
- **单元测试**: 覆盖所有核心功能
- **集成测试**: 测试模块间集成
- **兼容性测试**: 确保与规范兼容
- **性能测试**: 验证性能指标

#### 10.2 代码质量
- 类型注解覆盖率达到 100%
- 测试覆盖率超过 90%
- 遵循 PEP 8 编码规范
- 详细的文档和示例

## 总结

本架构设计提供了一个完整、可扩展的 ATProto 数据处理解决方案，充分利用了 Python 的类型系统和现有生态，同时保持了与 ATProto 规范的完全兼容性。模块化的设计使得各个组件可以独立开发和测试，同时也便于未来的扩展和维护。