Упущенные Спецификации и Компоненты

# Упоминания в CIFRA_NAMING.md
cifra init
cifra generate
cifra run
cifra migrate

# Детальная спецификация
cifra init <project-name> [options]
  Options:
    --template, -t <name>     Шаблон (crm, erp, admin_panel)
    --database, -d <type>     БД (postgresql, mysql, sqlite)
    --auth                    Включить аутентификацию
    --no-git                  Не создавать git репозиторий
    --path <dir>              Путь для создания проекта

cifra generate <config.cifra> [options]
  Options:
    --output, -o <dir>        Папка для генерации
    --force, -f               Перезаписать существующие файлы
    --watch, -w               Watch mode (регенерация при изменении)
    --dry-run                 Показать что будет сгенерировано

cifra run <config.cifra> [options]
  Options:
    --port, -p <number>       Порт (default: 8000)
    --host <address>          Host (default: 0.0.0.0)
    --reload                  Auto-reload при изменении кода
    --workers <number>        Количество worker процессов

cifra migrate <command> [options]
  Commands:
    create <name>             Создать миграцию
    up                        Применить миграции
    down [number]             Откатить N миграций
    status                    Статус миграций
    reset                     Сбросить все миграции

cifra export <entity> [options]
  Options:
    --format <type>           Формат (json, csv, xlsx, sql)
    --filter <query>          Фильтр данных
    --output, -o <file>       Выходной файл

cifra import <file> [options]
  Options:
    --entity <name>           Entity для импорта
    --format <type>           Формат файла
    --update                  Обновлять существующие записи
    --skip-errors             Пропускать ошибки

cifra hub <command>
  Commands:
    search <query>            Поиск модулей в Hub
    install <module>          Установить модуль
    publish                   Опубликовать модуль
    update                    Обновить установленные модули

cifra deploy <environment> [options]
  Options:
    --provider <name>         Cloud provider (aws, gcp, azure, do)
    --region <name>           Регион
    --instances <number>      Количество инстансов

cifra doctor
  Проверка окружения и конфигурации

cifra version
  Показать версию CIFRA

cifra help [command]
  Помощь по команде

# plugin.yaml
plugin:
  id: social-media
  name: "Social Media Fields Plugin"
  version: "1.0.0"
  author: "John Doe"
  description: "Добавляет поля соц.сетей к Entity"

  requires:
    cifra: ">=1.0.0"
    plugins:
      - contacts: "^1.0.0"

  permissions:
    - entity:Contact:extend
    - api:read

  entities:
    Contact:
      fields:
        facebook: {type: string, icon: facebook}
        twitter: {type: string, icon: twitter}
        linkedin: {type: string, icon: linkedin}

      ui:
        form:
          sections:
            - name: "Социальные сети"
              fields: [facebook, twitter, linkedin]

  hooks:
    - event: "entity.Contact.before_save"
      handler: "handlers.validate_social_urls"

    - event: "entity.Contact.after_create"
      handler: "handlers.fetch_social_profiles"

# cifra/core/plugins.py
class PluginAPI:
    """API для разработки плагинов"""

    # Hooks
    @hook('entity.*.before_save')
    def validate_data(self, entity, data):
        """Вызывается перед сохранением любой Entity"""
        ...

    @hook('entity.Contact.after_create')
    def on_contact_created(self, contact):
        """Вызывается после создания Contact"""
        ...

    # Entity Extension
    @extend_entity('Contact')
    def add_fields(self, entity_class):
        """Добавляет поля к Contact"""
        entity_class.add_field('facebook', StringField())
        ...

    # API Extension
    @register_endpoint('/api/contacts/{id}/social')
    async def get_social_profiles(self, contact_id: UUID):
        """Добавляет кастомный endpoint"""
        ...

    # UI Extension
    @register_widget('SocialMediaCard')
    def social_media_widget(self):
        """Добавляет виджет в UI"""
        ...

# cifra/core/events.py
class EventSystem:
    """Централизованная система событий"""

    # Event naming: <domain>.<entity>.<action>
    # Examples:
    # - entity.Contact.created
    # - entity.Deal.stage_changed
    # - process.order_fulfillment.started
    # - user.login.success
    # - integration.stripe.payment_received

    def emit(self, event_name: str, payload: dict, priority: int = 0):
        """
        Отправить событие

        Args:
            event_name: entity.Contact.created
            payload: {id, email, name, ...}
            priority: 0-9 (0=lowest, 9=highest)
        """
        event = Event(
            name=event_name,
            payload=payload,
            priority=priority,
            timestamp=datetime.utcnow(),
            id=uuid4()
        )

        # Persist event
        await self.event_log.save(event)

        # Notify subscribers
        await self.notify_subscribers(event)

    def subscribe(self, pattern: str, handler: Callable, filter: dict = None):
        """
        Подписаться на события

        Args:
            pattern: entity.Contact.* (wildcard поддерживается)
            handler: async function(event)
            filter: {field: value} - дополнительная фильтрация payload
        """
        subscriber = Subscriber(
            pattern=pattern,
            handler=handler,
            filter=filter
        )
        self.subscribers.append(subscriber)

    async def replay(self, from_time: datetime, to_time: datetime):
        """Replay событий (для восстановления состояния)"""
        events = await self.event_log.get_range(from_time, to_time)
        for event in events:
            await self.notify_subscribers(event)

# Использование
@event.subscribe('entity.Contact.created')
async def send_welcome_email(event):
    contact = event.payload
    await email_service.send(
        to=contact['email'],
        template='welcome',
        data=contact
    )

@event.subscribe('entity.Deal.*', filter={'amount': {'$gt': 100000}})
async def notify_manager_large_deal(event):
    """Уведомить менеджера о крупной сделке"""
    ...

# CIFRA Query Language (CQL)

# Простой фильтр
GET /api/contacts?filter={"status": "active"}

# Операторы сравнения
filter:
  amount: {$gt: 1000}          # больше 1000
  stage: {$in: [won, lost]}    # в списке
  email: {$regex: ".*@gmail.*"} # regex
  created_at: {$between: [2025-01-01, 2025-12-31]}

# Логические операторы
filter:
  $and:
    - status: active
    - amount: {$gt: 1000}

filter:
  $or:
    - stage: won
    - stage: lost

filter:
  $not:
    status: archived

# Вложенные связи (JOIN)
filter:
  company.name: "ACME Corp"
  company.country: "USA"

# Full-text search
search: "john smith"
search_fields: [first_name, last_name, email]

# Сортировка
sort: "-created_at"           # DESC
sort: ["stage", "-amount"]    # stage ASC, amount DESC

# Пагинация
limit: 25
offset: 50

# OR cursor-based
cursor: "eyJpZCI6MTIzfQ=="
limit: 25

# Aggregations
aggregate:
  - group_by: stage
    metrics:
      - count: "*"
      - sum: amount
      - avg: amount
      - min: created_at
      - max: created_at

# Результат:
{
  "lead": {count: 45, sum: 125000, avg: 2777.78},
  "won": {count: 23, sum: 450000, avg: 19565.22}
}

# 3 уровня кеширования

LEVEL 1: In-Memory (Python dict)
  scope: Request
  ttl: Request lifecycle
  size: Unlimited
  use: Избежать повторных обращений к БД в одном запросе

LEVEL 2: Redis (Single Instance)
  scope: Application
  ttl: 5 minutes - 1 hour
  size: 2 GB
  use: Горячие данные (активные пользователи, частые запросы)

LEVEL 3: Redis (Cluster)
  scope: Global
  ttl: 1 hour - 24 hours
  size: 10 GB
  use: Редко меняющиеся данные (справочники, настройки)

# Naming Convention
cache_key = f"cifra:{tenant_id}:{entity}:{id}:{version}"

Examples:
  - cifra:acme:Contact:uuid-123:v1
  - cifra:acme:Deal:list:stage=won:page=1:v2
  - cifra:global:settings:theme:v1

# TTL Strategy
entity_cache_ttl = {
    'User': 300,        # 5 min (часто меняется)
    'Contact': 600,     # 10 min
    'Deal': 600,        # 10 min
    'Product': 3600,    # 1 hour (редко меняется)
    'Category': 86400,  # 24 hours (почти не меняется)
}

# Invalidation Strategy
1. Time-based (TTL expired)
2. Event-based (entity.updated → invalidate cache)
3. Manual (cache.clear())
4. Tag-based (cache tags: Contact.uuid-123 → все связанные)

# Cache Warming
# При старте приложения загрузить в кеш:
- Все категории
- Все настройки
- Топ-100 товаров

# Cache Stampede Prevention
# Используем "lock" для предотвращения множественных запросов к БД
async def get_with_lock(key):
    # Пытаемся получить из кеша
    value = await cache.get(key)
    if value:
        return value

    # Пытаемся получить lock
    lock_key = f"{key}:lock"
    acquired = await cache.set(lock_key, 1, nx=True, ex=10)

    if acquired:
        # Мы первые - идём в БД
        value = await db.query(...)
        await cache.set(key, value, ex=ttl)
        await cache.delete(lock_key)
        return value
    else:
        # Кто-то уже идёт в БД - ждём
        await asyncio.sleep(0.1)
        return await get_with_lock(key)

# cifra/modules/media/upload.py

class FileUploadService:
    """Сервис загрузки файлов"""

    # Лимиты
    MAX_FILE_SIZE = 100 * 1024 * 1024  # 100 MB
    ALLOWED_EXTENSIONS = {
        'image': ['jpg', 'jpeg', 'png', 'gif', 'webp'],
        'video': ['mp4', 'mov', 'avi'],
        'document': ['pdf', 'doc', 'docx', 'xls', 'xlsx'],
        'archive': ['zip', 'tar', 'gz']
    }

    async def upload(
        self,
        file: UploadFile,
        type: str = 'image',
        resize: dict = None,
        optimize: bool = True
    ):
        """
        Загрузка файла

        Args:
            file: Файл из FastAPI UploadFile
            type: Тип файла (image, video, document)
            resize: {width: 800, height: 600, mode: 'fit'}
            optimize: Оптимизировать изображение
        """
        # 1. Валидация
        self.validate_file(file, type)

        # 2. Virus scan (опционально)
        if settings.VIRUS_SCAN_ENABLED:
            await self.scan_virus(file)

        # 3. Генерация пути
        path = self.generate_path(file.filename)
        # /uploads/2025/11/10/uuid-abc123.jpg

        # 4. Обработка (для изображений)
        if type == 'image':
            file_data = await file.read()

            if resize:
                file_data = await self.resize_image(file_data, resize)

            if optimize:
                file_data = await self.optimize_image(file_data)
        else:
            file_data = await file.read()

        # 5. Загрузка в storage
        if settings.STORAGE == 's3':
            url = await self.s3.upload(path, file_data)
        else:
            # Local filesystem
            full_path = f"{settings.MEDIA_ROOT}/{path}"
            with open(full_path, 'wb') as f:
                f.write(file_data)
            url = f"{settings.MEDIA_URL}/{path}"

        # 6. Создание Media entity
        media = Media(
            filename=file.filename,
            path=path,
            url=url,
            mime_type=file.content_type,
            size=len(file_data),
            uploaded_by=current_user.id
        )
        await media.save()

        return media

    async def resize_image(self, data: bytes, options: dict):
        """Resize изображения"""
        from PIL import Image
        from io import BytesIO

        img = Image.open(BytesIO(data))

        mode = options.get('mode', 'fit')  # fit, fill, crop

        if mode == 'fit':
            img.thumbnail((options['width'], options['height']))
        elif mode == 'crop':
            img = img.crop((0, 0, options['width'], options['height']))

        output = BytesIO()
        img.save(output, format='JPEG', quality=85)
        return output.getvalue()

    async def optimize_image(self, data: bytes):
        """Оптимизация изображения"""
        # Используем pillow-simd или imagemagick
        # Снижаем качество без потери визуального восприятия
        ...
        return optimized_data

# Chunked Upload (для больших файлов)
class ChunkedUploadService:
    """Загрузка больших файлов частями"""

    async def init_upload(self, filename: str, total_size: int):
        """Инициализация загрузки"""
        upload_id = str(uuid4())
        await redis.set(
            f"upload:{upload_id}",
            json.dumps({
                'filename': filename,
                'total_size': total_size,
                'chunks_received': 0,
                'chunks_total': math.ceil(total_size / CHUNK_SIZE)
            }),
            ex=3600  # 1 hour
        )
        return upload_id

    async def upload_chunk(self, upload_id: str, chunk_number: int, data: bytes):
        """Загрузка части файла"""
        # Сохранить chunk
        chunk_path = f"/tmp/uploads/{upload_id}/chunk_{chunk_number}"
        with open(chunk_path, 'wb') as f:
            f.write(data)

        # Обновить прогресс
        upload_info = await redis.get(f"upload:{upload_id}")
        upload_info['chunks_received'] += 1
        await redis.set(f"upload:{upload_id}", json.dumps(upload_info))

        # Если все chunks получены - собрать файл
        if upload_info['chunks_received'] == upload_info['chunks_total']:
            await self.finalize_upload(upload_id)

    async def finalize_upload(self, upload_id: str):
        """Завершение загрузки - сборка файла"""
        upload_info = await redis.get(f"upload:{upload_id}")

        # Собрать все chunks в один файл
        output_path = f"/tmp/uploads/{upload_id}/complete"
        with open(output_path, 'wb') as outfile:
            for i in range(upload_info['chunks_total']):
                chunk_path = f"/tmp/uploads/{upload_id}/chunk_{i}"
                with open(chunk_path, 'rb') as chunk:
                    outfile.write(chunk.read())

        # Загрузить в S3
        await s3.upload_file(output_path, ...)

        # Очистить временные файлы
        shutil.rmtree(f"/tmp/uploads/{upload_id}")

# cifra/worker/tasks.py
from celery import Celery, Task
from celery.schedules import crontab

app = Celery('cifra')
app.config_from_object('cifra.settings')

# Простая задача
@app.task
def send_email(to: str, subject: str, body: str):
    """Отправка email"""
    email_service.send(to, subject, body)

# Задача с retry
@app.task(bind=True, max_retries=3, default_retry_delay=60)
def fetch_external_data(self, url: str):
    """Получение данных из внешнего API"""
    try:
        response = requests.get(url, timeout=30)
        response.raise_for_status()
        return response.json()
    except RequestException as exc:
        # Retry через 60 секунд
        raise self.retry(exc=exc)

# Периодическая задача (cron-like)
@app.task
def cleanup_old_sessions():
    """Очистка старых сессий (каждый день в 3:00)"""
    Session.objects.filter(
        expires_at__lt=datetime.now()
    ).delete()

# Регистрация периодических задач
app.conf.beat_schedule = {
    'cleanup-sessions': {
        'task': 'cifra.worker.tasks.cleanup_old_sessions',
        'schedule': crontab(hour=3, minute=0),
    },
    'generate-daily-report': {
        'task': 'cifra.worker.tasks.generate_daily_report',
        'schedule': crontab(hour=9, minute=0),
    },
}

# Task chaining (последовательное выполнение)
from celery import chain

workflow = chain(
    fetch_external_data.s('https://api.example.com/data'),
    process_data.s(),
    save_to_database.s()
)
workflow.apply_async()

# Task grouping (параллельное выполнение)
from celery import group

job = group(
    send_email.s('user1@example.com', 'Hello', 'Body'),
    send_email.s('user2@example.com', 'Hello', 'Body'),
    send_email.s('user3@example.com', 'Hello', 'Body'),
)
result = job.apply_async()

# Long-running task с progress
@app.task(bind=True)
def generate_large_report(self, filters):
    """Генерация большого отчёта"""
    total = 1000
    for i in range(total):
        # Обработка данных
        process_row(i)

        # Обновление прогресса
        self.update_state(
            state='PROGRESS',
            meta={'current': i, 'total': total, 'percent': i/total*100}
        )

    return {'status': 'completed', 'file': '/reports/report.pdf'}

# Приоритеты задач
@app.task(priority=9)  # Высокий приоритет
def critical_task():
    ...

@app.task(priority=0)  # Низкий приоритет
def low_priority_task():
    ...

Создать:
  1. DEPLOYMENT_GUIDE.md
  2. TESTING_STRATEGY.md
  3. PERFORMANCE_GUIDE.md
  4. CLI_REFERENCE.md
  5. PLUGIN_API.md
  6. EVENT_SYSTEM.md
  7. QUERY_LANGUAGE.md
  8. CACHING_STRATEGY.md

Создать:
  9. MONITORING_GUIDE.md
  10. API_DOCUMENTATION.md
  11. I18N_GUIDE.md
  12. MIGRATION_GUIDE.md
  13. FILE_UPLOAD.md
  14. BACKGROUND_JOBS.md
  15. REPORT_BUILDER.md
  16. ACTIVITY_LOG.md

Создать:
  17. CONTRIBUTING.md
  18. TROUBLESHOOTING.md
  19. BEST_PRACTICES.md
  20. REAL_TIME.md
  21. MOBILE_SDK.md
  22. SEARCH_FEATURES.md

Создать:
  23. LICENSE.md
  24. BUSINESS_MODEL.md
  25. RELEASE_PROCESS.md
  26. COMMUNITY.md
  27. CODE_OF_CONDUCT.md
  28. MARKETING_STRATEGY.md
  29. TRAINING.md