Дебаты Astra × Fable03-extracting-the-project

3. Как извлекать бизнес-логику и устройство Django-проекта

Сначала воспроизводимый объект исследования

При переходе к живому репозиторию модель собирает паспорт: repo/revision, Python/Django и библиотеки, БД и расширения, broker/cache/storage, способы запуска, тестов и выпуска, настройки окружений, владельцев интеграций, источники бизнес-намерений. Укажите, какие сведения доступны только в runtime, какие конфигурации ещё не исследованы и какие системы не охвачены.

До исполнения неизвестного кода изучите команды запуска и инициализацию. Импорт Django-приложения, AppConfig.ready() или management command могут иметь побочные эффекты. Для динамической инвентаризации используйте изолированную среду с синтетическими данными и без production-credentials. Статический разбор также не безошибочен: у анализатора есть версия, поддерживаемые конструкции и перечень неразрешённых связей.

Входы, работа, выходы

Вход Работа модели/инструментов Выход
Исходники и конфигурации Инвентаризация приложений, точек входа, способов записи Реестры с координатами в конкретном снимке
История PR и инцидентов Найти часто меняемые/опасные процессы и повторяемые задания Кандидаты пилота и ранбуков
Тесты и инструкции запуска Воспроизвести существующие проверки и ограничения Baseline: passed/failed/not_run/flaky
Разрешённые примеры данных и интеграций Проверить сценарии в изоляции Наблюдения и границы эксперимента
Намерения человека Выделить спорные бизнес-решения и уже данные ответы Решения, неизвестное, порядок уточнений

Критерий выхода: другой исполнитель может повторить получение карты и baseline; каждый существенный вывод имеет источник либо пометку неизвестности. Неполная карта с явными пробелами лучше вымышленной полной карты.

Минимальная карта входов, способов записи и обратных зависимостей пилота нужна уже на старте. Это может быть воспроизводимый поиск и небольшой реестр; дорогая платформа полного графа не обязательна. Анализ каждого изменения имеет независимый вход из кода, даже если все ссылки документации валидны. Импорты и статические вызовы дают кандидатов, но не гарантируют полноту динамических путей.

Инвентаризация технических аспектов

Область Что искать и документировать Чем проверять
Запуск и конфигурация WSGI/ASGI, middleware, settings variants, init, flags Чистый запуск, реестр конфигураций, порядок инициализации
HTTP и интерфейсы URL, views/viewsets, формы, сериализация, шаблоны, OpenAPI при наличии Разрешение маршрутов, контракты запросов/ответов, негативные примеры
Бизнес-операции Сервисы, методы моделей, managers, handlers, вычисления Трассировка сценариев, decision tables, примеры и инварианты
Запись данных ORM, raw SQL, bulk operations, admin actions, импорты Реестр всех writers и обходов обычной валидации
Схема и совместимость Ограничения, индексы, routers, multi-DB, миграции, исторические модели Schema diff, прогон миграций, план совместимости версий
Конкурентность Транзакции, locks, optimistic versions, unique constraints Конкурентные тесты на существенных свойствах реальной БД
Неявные эффекты Signals, save/delete overrides, callbacks, middleware Статические кандидаты плюс динамическая проверка маршрутов
Фоновые циклы Tasks, schedules, retries, deadlines, queues, deduplication Тесты повторов, падения worker и доставки
Интеграции API, webhooks, auth, timeouts, quotas, idempotency Версии контрактов, sandbox/contract tests, отказ внешней стороны
Данные вне БД Cache, files, search, exports, email Инвалидация, восстановление и рассогласование копий
Доступ Authentication, role/object/tenant filtering, admin и task access Матрица actor × operation × object × tenant
Эксплуатация Deploy, logs, metrics, traces, backups, restore, alerts Rehearsal и evidence на каждой операции
Нефункциональные свойства Latency, query budget, throughput, locale/time/money Измерения и согласованные допустимые границы

Не все строки применимы ко всем проектам. not_applicable нужно обосновать по инвентаризации. Дополнительные механизмы проекта расширяют таблицу.

Извлечение бизнес-логики по потокам

Модель начинает с бизнес-результата: оформить заказ, назначить доступ, пересчитать баланс, импортировать данные. Для каждого потока она:

  1. Находит всех инициаторов и точки входа, включая admin, команды и workers.
  2. Выделяет участников, предусловия, источники данных и проверки прав.
  3. Строит состояния и переходы: допустимо/запрещено, инициатор, причина отказа.
  4. Выписывает правила расчёта, порядок операций и исключения.
  5. Отмечает транзакционные границы и внешние эффекты.
  6. Разбирает повторный вызов, конкурентный вызов и сбой между шагами.
  7. Сопоставляет чтение кода, тесты, документацию, историю и намерения.
  8. Создаёт наблюдения отдельно от нормы и предлагает проверяемые примеры.

Карточка правила содержит не только счастливый путь: границы времени, пустые значения, отрицательные/предельные суммы, округление и единицы, повтор, конфликт состояний, недоступность зависимости. Не относящиеся к правилу измерения отмечаются как неприменимые.

Пример decision table

Условная норма: отменять заказ может оператор своего пространства, пока передача исполнителю не зафиксирована.

Роль/объект Состояние Событие Требуемый результат
Оператор своего пространства created cancel cancelled, один согласованный внешний эффект
Оператор чужого пространства created cancel отказ без изменения данных
Оператор своего пространства dispatched cancel отказ по бизнес-правилу
Оператор своего пространства cancelled cancel повторно прежний результат, без нового эффекта
Разрешённый оператор гонка cancel/dispatch оба запроса результат определяется утверждённой семантикой конкуренции

Последняя строка не дополняется выдумкой модели. Если порядок приоритета ещё не решён, она становится предметом подготовленного выбора человека.

Три вида несогласованности

  • Норма и код расходятся. Зафиксировать разницу, защитить нужное существующее поведение и выполнить ранбук приведения реализации к решению.
  • Источники фактов расходятся. Сравнить снимки, настройки, входные данные и маршруты; провести воспроизводимый эксперимент.
  • Намерение неоднозначно. Подготовить варианты с конкретными примерами. Человек выбирает смысл, после чего модель обновляет связанные записи.

Не каждый вопрос требует человека. Название файла, исправление ссылки, сбор отчёта и выбор команды по уже утверждённому ранбуку решает исполнитель. Неизвестные вопросы приоритизируются по влиянию на текущую задачу и риску; ненужные для решения пробелы сохраняются в backlog с владельцем.

Django-ловушки, которые должны попасть в гайд проекта

Справочник не заменяет обследование, но задаёт обязательные вопросы.

  • save() не вызывает full_clean() автоматически; наличие clean() не доказывает проверку всех writers. Django instances
  • QuerySet.update() обходит save() и сигналы сохранения. Массовое удаление отличается по вызову методов и сигналов. QuerySet
  • on_commit() не делает запись в БД и внешний вызов одной атомарной операцией. Для надёжной доставки может потребоваться outbox или иной согласованный протокол, с собственной проверкой. Transactions
  • Объектные права DRF требуют отдельного внимания к list/create и кастомным путям получения объекта. DRF permissions
  • Миграции данных работают с историческим состоянием моделей; прямой импорт текущего класса может ломать повторное применение истории. Migrations
  • Повтор задачи и подтверждение сообщения — часть контракта Celery, а не гарантия «ровно один раз». Celery tasks

Алгоритмы, циклы и практики

Карточка алгоритма: назначение; вход/выход; предусловия; шаги; инварианты; условие завершения; сложность и пределы; детерминированность; обработка ошибок; связи с данными, кодом и тестами.

Для цикла фиксируются начало, повтор, выход, лимиты, тайм-ауты и побочные эффекты. Ищите не только циклы импортов, но и сигнал → запись → сигнал, task → retry → task и webhook → API → webhook. Неразрешённое динамическое ребро остаётся явным пробелом, а не исчезает из красивой диаграммы.

Повторяющаяся практика в коде — кандидат на анализ, а не автоматически правило для будущего. Документируйте отдельно фактическую практику, рекомендованный путь, исключение и план устранения наследия.

Приёмка извлечённого знания

Независимый проверяющий получает утверждение, источники и контекст, ищет контрпример и обходные пути. Значимые утверждения переводятся в исполняемые проверки с отдельно установленным оракулом. Проверка текста другой моделью не доказывает бизнес-смысл и не заменяет эксперимент.

Готовность пилотной области означает, что для выбранных классов задач видны правила, основные пути и риски, есть основания приёмки и понятны непроверенные области. Это не заявление о полном документировании всего кода.