Объединенный План Рефакторинга tg_content_factory

[axisrow]

Объединенный План Рефакторинга tg_content_factory

Summary

• Аудит выявил основные зоны риска: tracked generated artifacts, монолитные agent tools, ручные web/form parsers, дубли retry/backoff, две разные сущности AgentProviderService, самописные provider adapters, повторяющийся datetime/JSON parsing и перегруженный migration layer.
• ruff check src/ tests/ conftest.py проходит; остается предупреждение о некорректном # noqa в tests/test_telegram_command_dispatcher.py:1729.
• По Context7: Pydantic v2, FastAPI Depends/form models и Tenacity покрывают часть текущего самописного кода и должны стать предпочтительным путем для refactor PRs.

Key Refactors

• Убрать tracked artifacts: coverage.json, output1, src/web/routes/dialogs.py,cover; добавить соответствующие правила в .gitignore.
• Разрезать крупные agent tool modules: src/agent/tools/messaging.py, src/agent/tools/pipelines.py, src/agent/tools/photo_loader.py; вынести схемы аргументов и operation handlers по доменам.
• Перевести ручные form/arg parsers на Pydantic v2 BaseModel, TypeAdapter, model_validate_strings, начиная с src/web/settings/forms.py, src/web/pipelines/forms.py, src/web/routes/dialogs.py.
• В web routes использовать FastAPI Depends и Pydantic form models для повторяемых зависимостей, request.form(), redirects, JSON responses и query encoding.
• Свести retry/backoff к Tenacity: заменить дубли в src/services/error_recovery_service.py и src/services/production_limits_service.py на AsyncRetrying, stop_after_attempt, wait_exponential_jitter и кастомный retry predicate.
• Развести две сущности AgentProviderService: runtime registry из src/services/provider_service.py переименовать в RuntimeProviderRegistry, DB/config service из src/services/agent_provider_service.py в ProviderConfigService.
• Сократить custom HTTP provider adapters: для LLM-провайдеров сначала использовать уже установленные LangChain integrations; custom aiohttp оставить только для неподдержанных API.
• Заменить src/search/numpy_semantic.py на sklearn.neighbors.NearestNeighbors(metric="cosine"), так как scikit-learn уже есть в зависимостях.
• Вынести общий datetime/JSON parsing в shared utilities: _dt, _parse_schedule_at, fromisoformat, UTC-normalization и JSON parsing сейчас повторяются в repositories, CLI, web и agent tools.

Migration Policy

• migrations.py оставить только как schema-repair layer, потому что SQLite не добавляет колонки в существующие таблицы через CREATE TABLE IF NOT EXISTS.
• Сохранить публичный контракт run_migrations(db) -> bool, чтобы не менять Database.initialize().
• Перенести canonical table definitions, которые сейчас есть только в migrations, в schema.py: generation_runs, notification_bots, agent_threads, agent_messages, message_embeddings_json, generated_images, pipeline_templates.
• Переписать migrations.py в маленький модуль с helpers table_columns(), ensure_columns(), ensure_indexes():
  • только ALTER TABLE ... ADD COLUMN для отсутствующих колонок;
  • только CREATE TABLE IF NOT EXISTS, CREATE INDEX IF NOT EXISTS, CREATE TRIGGER IF NOT EXISTS;
  • легкая проверка FTS5 availability без rebuild/backfill.
• Удалить все data migrations: vec_messages перенос, keywords перенос, backfill reactions, reset prompt template, normalize forward_from_channel_id, Z.AI URL rewrites, tool permission key rewrites, legacy task/status/channel rewrites.
• Не пересоздавать таблицы ради constraint changes. Несовместимые старые constraints считаются manual upgrade/fresh DB case.

Library Reuse

• Активнее использовать уже подключенные зависимости: Pydantic v2, FastAPI Depends/form models, pydantic-settings, scikit-learn, LangChain provider integrations.
• Добавить новую зависимость tenacity только в retry-refactor PR.
• Оставить кастомным доменный код: Telegram identifier parsing, Flood Wait handling, session encryption wrapper around Fernet.

Test Plan

• После artifact cleanup: ruff check src/ tests/ conftest.py.
• После migration refactor: обновить tests/test_migrations*.py под schema-only policy; удалить/переписать tests для legacy data rewrites; прогнать pytest tests/test_migrations*.py -v и pytest tests/test_database.py -v -m aiosqlite_serial.
• После parser/form refactor: focused route tests for dialogs/settings/pipelines plus existing CLI command tests.
• После provider/retry refactor: provider service tests, generation/translation tests, tests/test_error_recovery_service.py, dispatcher tests.
• Финальный прогон: parallel pytest lane + serial aiosqlite_serial lane.

Assumptions

• Это roadmap без изменения кода в текущем Plan Mode.
• Приоритет выполнения: artifacts cleanup, schema-only migrations, low-risk parser de-duplication, затем agent/provider/database architecture cuts.
• CLI/web/agent compatibility сохраняется; legacy facade methods удалять только после перевода callers на db.repos.*.
• Существующие пользовательские данные сохраняются, но больше не исправляются автоматически migration layer.