Дебаты 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 нужно обосновать
по инвентаризации. Дополнительные механизмы проекта расширяют таблицу.
Извлечение бизнес-логики по потокам
Модель начинает с бизнес-результата: оформить заказ, назначить доступ, пересчитать баланс, импортировать данные. Для каждого потока она:
- Находит всех инициаторов и точки входа, включая admin, команды и workers.
- Выделяет участников, предусловия, источники данных и проверки прав.
- Строит состояния и переходы: допустимо/запрещено, инициатор, причина отказа.
- Выписывает правила расчёта, порядок операций и исключения.
- Отмечает транзакционные границы и внешние эффекты.
- Разбирает повторный вызов, конкурентный вызов и сбой между шагами.
- Сопоставляет чтение кода, тесты, документацию, историю и намерения.
- Создаёт наблюдения отдельно от нормы и предлагает проверяемые примеры.
Карточка правила содержит не только счастливый путь: границы времени, пустые значения, отрицательные/предельные суммы, округление и единицы, повтор, конфликт состояний, недоступность зависимости. Не относящиеся к правилу измерения отмечаются как неприменимые.
Пример decision table
Условная норма: отменять заказ может оператор своего пространства, пока передача исполнителю не зафиксирована.
| Роль/объект | Состояние | Событие | Требуемый результат |
|---|---|---|---|
| Оператор своего пространства | created | cancel | cancelled, один согласованный внешний эффект |
| Оператор чужого пространства | created | cancel | отказ без изменения данных |
| Оператор своего пространства | dispatched | cancel | отказ по бизнес-правилу |
| Оператор своего пространства | cancelled | cancel повторно | прежний результат, без нового эффекта |
| Разрешённый оператор | гонка cancel/dispatch | оба запроса | результат определяется утверждённой семантикой конкуренции |
Последняя строка не дополняется выдумкой модели. Если порядок приоритета ещё не решён, она становится предметом подготовленного выбора человека.
Три вида несогласованности
- Норма и код расходятся. Зафиксировать разницу, защитить нужное существующее поведение и выполнить ранбук приведения реализации к решению.
- Источники фактов расходятся. Сравнить снимки, настройки, входные данные и маршруты; провести воспроизводимый эксперимент.
- Намерение неоднозначно. Подготовить варианты с конкретными примерами. Человек выбирает смысл, после чего модель обновляет связанные записи.
Не каждый вопрос требует человека. Название файла, исправление ссылки, сбор отчёта и выбор команды по уже утверждённому ранбуку решает исполнитель. Неизвестные вопросы приоритизируются по влиянию на текущую задачу и риску; ненужные для решения пробелы сохраняются в backlog с владельцем.
Django-ловушки, которые должны попасть в гайд проекта
Справочник не заменяет обследование, но задаёт обязательные вопросы.
save()не вызываетfull_clean()автоматически; наличиеclean()не доказывает проверку всех writers. Django instancesQuerySet.update()обходитsave()и сигналы сохранения. Массовое удаление отличается по вызову методов и сигналов. QuerySeton_commit()не делает запись в БД и внешний вызов одной атомарной операцией. Для надёжной доставки может потребоваться outbox или иной согласованный протокол, с собственной проверкой. Transactions- Объектные права DRF требуют отдельного внимания к list/create и кастомным путям получения объекта. DRF permissions
- Миграции данных работают с историческим состоянием моделей; прямой импорт текущего класса может ломать повторное применение истории. Migrations
- Повтор задачи и подтверждение сообщения — часть контракта Celery, а не гарантия «ровно один раз». Celery tasks
Алгоритмы, циклы и практики
Карточка алгоритма: назначение; вход/выход; предусловия; шаги; инварианты; условие завершения; сложность и пределы; детерминированность; обработка ошибок; связи с данными, кодом и тестами.
Для цикла фиксируются начало, повтор, выход, лимиты, тайм-ауты и побочные эффекты. Ищите не только циклы импортов, но и сигнал → запись → сигнал, task → retry → task и webhook → API → webhook. Неразрешённое динамическое ребро остаётся явным пробелом, а не исчезает из красивой диаграммы.
Повторяющаяся практика в коде — кандидат на анализ, а не автоматически правило для будущего. Документируйте отдельно фактическую практику, рекомендованный путь, исключение и план устранения наследия.
Приёмка извлечённого знания
Независимый проверяющий получает утверждение, источники и контекст, ищет контрпример и обходные пути. Значимые утверждения переводятся в исполняемые проверки с отдельно установленным оракулом. Проверка текста другой моделью не доказывает бизнес-смысл и не заменяет эксперимент.
Готовность пилотной области означает, что для выбранных классов задач видны правила, основные пути и риски, есть основания приёмки и понятны непроверенные области. Это не заявление о полном документировании всего кода.