# Code-map: от пользовательской функции к реализации

Карта предназначена для навигации по изменениям. Она не подменяет исходники: при расхождении сначала проверяется конкретная версия кода, затем обновляется документация.

| Функция | UI / интерфейс | Основные модули | Данные | Проверка |
|---|---|---|---|---|
| Авторизация | accounts | services/auth.py, vk_user_token.py | auth_accounts, account_communities | browser/API состояния рассматриваются раздельно |
| Создание и исполнение заданий | schedules, processing | services/admin_control.py, cli/admin_worker.py | admin_jobs, admin_job_step_logs | claim, heartbeat, retry, stale cleanup |
| Планирование API | schedules, group-pool | services/api_posts_schedule.py | api_schedule_steps, api_group_pool_items | поколение расписания, очередь, cooldown |
| Сбор | groups, posts | services/crawler.py, vk_parsers.py | communities, posts, post_media | источник, повторное чтение, нормализация |
| Профиль и маркет | groups tabs, market | community_profile.py, community_market.py, community_services.py | профиль, товары, услуги | фильтры и привязка к группе |
| Быстрый отбор | group-pool | fast_screen_pool.py, fast_wall_probe.py | fast_screen_pool_states, fast_screen_pool_checks | lease, due rows, retention |
| Pipeline | pipeline | services/content_pipeline.py | content_pipeline_runs/posts/items | этапы и сохранённые результаты |
| OCR | processing, post details | ocr.py, ocr_jobs.py, cli/ocr_worker.py, cli/ocr_sidecar.py | ocr_jobs, post_media | completed/failed, attempts, timeout |
| Канонические материалы | results | publication_materials.py, publication-intelligence | publication_decisions/materials/media | связь решения с исходником и версия |
| Разметка и teacher | labels, processing | publication_teacher.py | teacher runs/results/applications | разметка, расхождения, применение |
| Логи | logs, file-logs | web/app.py, helpers file logs | admin_job_logs, step logs, files | событийные и файловые следы |
| Выдача | Telegram / MAX | отдельные bot repositories | canonical output + bot tables | downstream использует подготовленные данные |

Все пути Python выше относятся к src/wtg/. Историческая подробная карта и перечень CLI находятся в source-reference/CODE_MAP.md.

## Как проводить изменение

1. Зафиксировать сценарий и SHA: какое действие оператора меняется и какой результат ожидается.
2. Найти маршрут в карте и проследить цепочку до обработчика, очереди и таблиц. Проверить вызывающие модули и связанные интерфейсы.
3. Разделить изменения контракта, миграции данных и поведения. Проверить, читают ли эти таблицы боты и старый review-слой.
4. Изменить код в пределах сценария. Тяжёлую работу оставлять в заданиях; сохранять явные статусы и причины отказа.
5. Выполнить соответствующие unit/integration проверки. В браузере пройти целевой сценарий и ошибку, проверить фактическую версию.
6. Обновить карту, затронутые схемы, описание API и сценарий проверки в том же изменении.
7. В отчёте указать результат проверки, версии и ограничения. Планируемые возможности не переносить в схему текущего состояния.

## Пример анализа OCR-изменения

processing → OCR status API → ocr_jobs → claim/lease в worker → HTTP sidecar → сохранение результата → publication_materials → results. Изменение таймаута затрагивает повтор и освобождение lease; изменение формата результата затрагивает parser, storage и классификатор. Проверять только /health sidecar недостаточно.

## Работа со схемами

architecture.mmd показывает границы компонентов; data-model.mmd — отношения сущностей; processing-sequence.mmd — порядок взаимодействий; deployment.mmd — наблюдавшееся размещение. Mermaid является редактируемым исходником, SVG — экспортом для сайта. Направления стрелок и названия сверяются с кодом; изменение layout не должно менять смысл связей.
