🏠 На главную | 🧭 Руководство (RU) | 🛡️ Core API

🛡️ Core: PII и DTO (Архитектура)

Этот раздел описывает, как структурируются и защищаются данные в экосистеме codex-core.

Цель домена

Основная цель домена core — гарантировать, что персональные данные (PII) никогда случайно не утекут в логи, при этом сохраняя неизменяемое и стандартизированное представление данных для внутренней логики.

1. Автоматическое маскирование PII

BaseDTO автоматически маскирует конфиденциальную информацию в своих методах repr и str.

Как это работает:

1. Сопоставление по ключевым словам: Если имя поля содержит любое из предопределенных ключевых слов (phone, email, name, address, note, comment), его значение в логах будет заменено на ***.
2. Рекурсивное маскирование: Если поле не является напрямую PII, но содержит словарь или список словарей (например, metadata), библиотека будет рекурсивно сканировать их на наличие ключевых слов PII.

Пример:

from codex_core.core import BaseDTO

class OrderDTO(BaseDTO):
    order_id: int
    customer_email: str  # Будет замаскировано
    notes: str           # Будет замаскировано
    meta: dict           # Сканируется рекурсивно

2. Неизменяемость

Все DTO по умолчанию заморожены (используется pydantic.ConfigDict(frozen=True)). Это гарантирует, что данные не могут быть изменены после создания, что важно для многопоточных и параллельных сред.

Рекомендации

• Не логируйте DTO в "горячих" путях: Хотя логика маскирования PII оптимизирована, она всё равно вносит определенные накладные расходы. Избегайте логирования DTO внутри плотных циклов или высокочастотных алгоритмов с бэктрекингом.
• Используйте осмысленные имена полей: Всегда называйте свои поля в соответствии с их содержанием. Если вы назовете поле номера телефона p, оно не будет замаскировано автоматически. Используйте phone, user_phone и т. д.
• Явное маскирование: Если у вас есть конфиденциальное поле, которое не соответствует нашим ключевым словам, вы всё равно можете замаскировать его, назвав соответствующим образом (например, secret_note).