Чек-лист передачи исходного кода для клиентов и агентств

Что должна обеспечивать передача исходного кода

Передача исходного кода — это момент, когда проект перестаёт быть «то, чем может управлять агентство», и становится «тем, чем клиент может владеть». Без чёткой передачи быстро проявляются стандартные проблемы: приложение собирается только на одном ноутбуке, в production используется секрет, которого никто не может найти, или небольшое обновление превращается в дни гаданий.

Цель любого чек-листа передачи проста: после передачи клиент должен уметь собрать, запустить и развернуть продукт без постоянного вмешательства агентства. Это не значит «никогда не нужна поддержка». Это значит, что базовые операции повторяемы и задокументированы, чтобы следующий человек мог подхватить работу с уверенностью.

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

• Полный репозиторий (включая файлы развёртывания и скрипты миграций)
• Документы по настройке, которые работают на чистой машине
• Передача доступа (учётные записи, права и где система размещается)
• Руководство по рутинным задачам (развёртывание, откат, бэкапы, логи)
• Финальная помеченная версия или снимок, на который клиент может ссылаться

Объём имеет такое же значение, как и содержание. Некоторые передачи охватывают только одно окружение (например, production). Другие включают dev, staging и production с отдельными настройками и процессами. Если вы не укажете, какие окружения включены, люди будут понимать по-разному, и именно это вызывает простои.

Практичный критерий успеха — проверочный тест: человек, который не собирал приложение, может экспортировать код (например, с платформы вроде Koder.ai), следовать документации, настроить переменные окружения, запустить миграции, собрать и развернуть в согласованном окружении.

Этот чек-лист фокусируется на технической готовности: переменные окружения, вращение секретов, миграции базы данных, скрипты развёртывания и проверка сборки. Он не охватывает юридические условия, контракты, пункты об ИС или споры по оплате. Это важно, но относится к отдельным соглашениям.

До экспорта: договоритесь о владельце и сроках

Чистая передача начинается до самого экспорта. Если договориться, кто за что отвечает и когда, вы избежите сюрпризов в последний момент: сломанных развёртываний, неоплаченного хостинга или отсутствующих доступов.

Назначьте дату передачи и короткое окно заморозки

Выберите дату передачи и определите окно заморозки (обычно 24–72 часа), когда вносите только срочные исправления. Это удерживает экспортируемый код и работающую систему в синхронизации. Если во время заморозки нужен хотфикс, запишите точно, что изменилось, и убедитесь, что это включено в финальный экспорт.

Уточните владение аккаунтами и оплатой

Решите, кто будет владельцем DNS, облачного хостинга и платных сервисов после передачи. Это не просто бумажная формальность. Если оплата остаётся на карте агентства, сервисы могут быть приостановлены без предупреждения.

Быстрый способ это зафиксировать:

• Назвать владельца аккаунта для DNS, хостинга и почты
• Подтвердить, кто платит по каждому счёту с даты передачи
• Решить, будут ли аккаунты переданы или воссозданы под клиентом
• Записать контакт поддержки для каждого провайдера

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

Перечислите окружения и где они работают

Согласуйте, какие окружения существуют (local, staging, production) и где каждое из них размещается. Укажите, является ли staging отдельным сервером, отдельной базой данных или просто флагом функциональности. Если вы использовали платформу вроде Koder.ai, также подтвердите, что хостится там, а что ожидается запустить в инфраструктуре клиента после экспорта.

Соберите доступ заранее

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

Также согласуйте финальный приёмочный тест и процесс подписания. Например: «Клиент может собрать с чистой машины, запустить миграции, развернуть в staging и пройти smoke-тест. Затем обе стороны подписывают акт приёма в письменной форме.»

Основы репозитория и документации

Хороший чек-лист передачи начинается с репозитория, который новая команда может открыть и понять за несколько минут. Подтвердите, что включено (код приложения, шаблоны конфигурации, скрипты) и что умышленно исключено (реальные секреты, приватные ключи, большие сгенерированные файлы). Если что-то исключено, укажите, где это хранится и кто этим владеет.

Сохраняйте предсказуемую структуру. Стремитесь к понятным верхнеуровневым папкам, например frontend/, backend/, mobile/, infra/, scripts/ и docs/. Если проект — монорепозиторий, объясните, как части связаны и как запускать каждую из них.

README должен быть пригоден для человека, который не писал проект. В нём должны быть перечислены предпосылки и быстрый путь к рабочему дев-руну без догадок.

Что задокументировать (минимум)

Включите короткий раздел README, который отвечает на вопросы:

• Что содержит этот репозиторий и для чего он служит (один абзац)
• Предпосылки с точными версиями (runtime, пакетный менеджер, Docker при необходимости)
• Однокомандные шаги для локального запуска (и как понять, что всё успешно)
• Как запускать тесты и собирать production-артефакт
• Где искать ключевые документы: заметки по архитектуре, миграции, заметки по развёртыванию

Добавьте простые заметки по архитектуре на понятном языке: что с чем взаимодействует и почему. Небольшой рисунок опционален, но несколько предложений обычно достаточно. Пример: «React-фронтенд обращается к Go API. API читает и пишет в PostgreSQL. Фоновые задачи выполняются отдельным воркер-процессом.»

Наконец, включите версионированный changelog или заметки релиза для сборки, передаваемой на хендовёрд. Это может быть CHANGELOG.md или короткий файл «handoff release notes», где указан точный коммит/тег, что было доставлено и известные проблемы.

Если код экспортирован из платформы вроде Koder.ai, укажите тип сгенерированного проекта (web, server, mobile), ожидаемый тулчейн (например React, Go, PostgreSQL, Flutter) и поддерживаемые версии ОС/инструментов, которые клиент должен использовать для воспроизведения сборки.

Переменные окружения: инвентарь и документация

Переменные окружения часто являются причиной того, что «рабочее приложение» ломается сразу после передачи. Хороший чек-лист рассматривает их как часть продукта, а не как послефактное добавление.

Начните с инвентаря, по которому новая команда может действовать без догадок. Держите его простым и указывайте пример формата значения (не реальные секреты). Если переменная необязательна, опишите, что случится при её отсутствии и какое поведение по умолчанию.

Простой способ представить инвентарь:

• Имя переменной, что она контролирует и пример формата
• Обязательная или нет, и поведение по умолчанию
• Где она задаётся (CI, панель хостинга, локальный .env файл)
• В каких окружениях нужны разные значения (dev, staging, production)
• Кто отвечает за изменение (клиент, агентство или совместно)

Явно указывайте различия по окружениям. Например, staging может указывать на тестовую базу и песочницу платежного провайдера, в то время как production использует боевые сервисы. Также отметьте значения, которые должны совпадать между системами, такие как callback-URL, allowed origins или bundle-идентификаторы мобильного приложения.

Документируйте, где сейчас хранится каждое значение. Многие команды распределяют значения по локальным .env файлам для разработки, CI-переменным для сборок и настройкам хостинга для runtime. Если вы использовали Koder.ai для экспорта, включите файл .env.example и короткую заметку о том, какие переменные нужно заполнить до первой сборки.

Наконец, докажите, что в репозитории нет скрытых секретов. Не ограничивайтесь проверкой текущих файлов. Просмотрите историю коммитов на предмет случайных ключей, старых .env файлов или вставленных учётных данных в пример конфига.

Конкретный пример: React-фронтенд и Go API могут нуждаться в API_BASE_URL для веба, а бэкенду — в DATABASE_URL и JWT_SIGNING_KEY. Если staging использует другой домен, укажите оба значения и где их менять, чтобы новая команда не отправила настройки staging в production.

Вращение секретов: передайте безопасно и проверьте

Передача не считается завершённой, пока клиент не контролирует все учётные данные, которые нужны приложению. Это значит — вращать секреты, а не просто делиться ими. Если у агентства (или у бывшего подрядчика) остаются рабочие ключи, это — незакрытая дверь, которой вы не можете аудировать.

Начните с полного инвентаря. Не ограничивайтесь паролями базы данных. Включите ключи сторонних API, OAuth client secrets, секреты подписей webhook, ключи подписи JWT, SMTP-учётные данные, ключи доступа к хранилищу и любые «временные» токены в CI.

Вот простой чек-лист для дня вращения секретов:

• Перечислите каждый секрет, что он открывает и где сейчас установлен (локальные env, CI, панель хостинга, vault)
• Создайте новые учётные данные в аккаунтах клиента и назначьте владельца для каждого (человек и общий почтовый ящик команды)
• Обновите конфиг приложения, чтобы использовать новые значения, затем разверните сначала в staging или тестовом окружении
• Отозвите старые учётные данные сразу после подтверждения работоспособности новых
• Запишите точные шаги вращения, чтобы следующая ротация была скучной и быстрой

После вращения подтвердите, что ничего не сломалось. Прогоняйте быстрые тесты «как реальный пользователь», а не только смотрите логи.

Сосредоточьтесь на потоках, зависящих от секретов:

• Вход, регистрация, сброс пароля и обновление токенов
• Платежи, отправка писем и загрузка файлов
• Webhook-и (проверка подписи и обработка повторных попыток)
• Фоновые задания или планировщики, обращающиеся к внешним API
• Админские действия, попадающие на привилегированные эндпоинты

Пример: если вы экспортировали проект из Koder.ai и приложение использует платёжный провайдер и доставку почты, поверните оба ключа, разверните, затем сделайте небольшой тестовый платёж и отправку тестового письма. Только после успешных тестов отзывайте ключи агентства.

Наконец, задокументируйте, где секреты будут храниться дальше (vault, CI-переменные или настройки хостинга), кто может их менять и как безопасно откатить изменения, если вращение вызвало ошибки.

Миграции базы данных и работа с данными

Передача может выглядеть «завершённой», хотя именно база данных первая даёт сбой. Рассматривайте миграции и данные как отдельный продукт: версионированные, повторяемые и протестированные.

Начните с записи текущей версии базы данных и места, где лежат миграции в репозитории. Будьте конкретны: путь к папке, шаблон именования и идентификатор последней миграции (или метка времени). Если используется PostgreSQL (часто с Go-бэкендом), также укажите требуемые расширения.

Что задокументировать (чтобы другой мог запустить)

Включите короткий runbook, который отвечает на вопросы:

• Какая команда запускает миграции и в каком порядке всё выполнять (создать базу, применить миграции, затем сиды)
• Как это отличается по окружениям (local, staging, production), включая любые флаги «безопасного режима»
• Автоматические ли миграции при развёртывании или их нужно запускать вручную, и кто имеет право их запускать
• Стратегия сидов: нет, только демо или минимальные обязательные записи (admin, настройки по умолчанию)
• План отката: что можно вернуть, а что нет (например, разрушительные удаления колонок)

Откаты требуют честности. Некоторые изменения обратимы только восстановлением бэкапа. Укажите это простым языком и сопроводите шагом по бэкапу (снимок перед релизом, проверка процесса восстановления).

Перед завершением передачи прогоните миграции на копии production-данных, если возможно. Это выявит медленные запросы, отсутствующие индексы и проблемы «работает на пустых данных». Реалистичный тест — экспорт кода, настройка env, восстановление анонимизированной дампы, затем применение миграций с нуля. Это упражнение проверяет большую часть чек-листа передачи.

Если приложение было создано на платформе вроде Koder.ai и затем экспортировано, дважды проверьте, что файлы миграций и любые сид-скрипты включены в экспорт и корректно вызываются при старте бэкенда.

Сборка и CI: сделайте процесс повторяемым

Передача завершена только тогда, когда кто-то другой может пересобрать приложение с нуля на чистой машине. Ваш чек-лист должен включать точные команды сборки, необходимые версии и ожидаемый результат (например: «веб-бандл в /dist», «имя бинарника API», «место APK Flutter»).

Запишите инструменты и пакетные менеджеры, которые вы реально используете, а не те, которые считаете используемыми. Для типичного стека это может быть Node.js (npm или pnpm) для React, тулчейн Go для сервера, инструменты клиента PostgreSQL для локальной настройки и Flutter SDK для мобильной части.

Сделайте установку зависимостей предсказуемой. Убедитесь, что lock-файлы закоммичены (package-lock.json, pnpm-lock.yaml, go.sum, pubspec.lock) и выполните чистую установку на новой машине или контейнере, чтобы доказать работоспособность.

Зафиксируйте, что делает CI, шаг за шагом, чтобы его можно было скопировать на другой CI-провайдер, если потребуется:

• Установка зависимостей (с lock-файлами)
• Запуск тестов и линтеров
• Сборка артефактов (веб-бандл, бинарь сервера, мобильная сборка)
• Формирование артефактов (zip, Docker-образ, релиз-бандл)
• Хранение логов и метаданных сборки (версия, коммит, дата)

Отделите конфигурацию времени сборки от конфигурации времени выполнения. Конфигурация сборки влияет на то, что компилируется (например, BASE_URL, вшитый в веб-бандл). Конфигурация времени выполнения инжектируется при старте (DATABASE_URL, API-ключи, флаги). Их смешивание — распространённая причина «работает в CI», но ломается в проде.

Предоставьте простую локальную проверку. Даже короткий набор команд подойдет:

# Web
pnpm install
pnpm test
pnpm build

# API
go test ./...
go build ./cmd/server

# Mobile
flutter pub get
flutter test
flutter build apk

Если вы экспортируете из платформы вроде Koder.ai, включите сгенерированные CI-файлы или пресеты сборки, использовавшиеся при развёртывании, чтобы клиент мог воспроизвести ту же сборку вне платформы.

Скрипты развёртывания и процесс релиза

Хороший чек-лист не ограничивается «вот репозиторий». Он объясняет, как код превращается в запущенный сервис и кто нажимает кнопку.

Начните с описания текущего процесса развёртывания: полностью вручную (команды на сервере), через CI (пайплайн собирает и деплоит) или через хостинг-платформу. Укажите, где хранятся конфиги и какие окружения существуют (dev, staging, production).

Сделайте шаги релиза повторяемыми. Если процесс зависит от человека, запоминающего 12 команд, превратите их в скрипты и укажите необходимые права.

Что включить в пакет развёртывания

Дайте клиенту всё, чтобы развернуть на первый день:

• Команды сборки и запуска (и точные версии Node, Go, Flutter и т.д.)
• Скрипты развёртывания (shell-скрипты, цели Makefile или конфиги пайплайнов)
• Необходимые права доступа: роли в облаке, реестр образов, DNS, админ базы данных
• Заметки по настройке окружения: где задаются env и как они отличаются по окружениям
• Именование релизов: теги/релизы и как идентифицировать то, что сейчас работает

Согласуйте ожидания по недоступности. Если требуется «нулевой даунтайм», опишите, что это значит на практике (blue-green, rolling deploy, окно только для чтения при миграциях). Если даунтайм допустим, определите чёткое окно.

Статические ресурсы и кэши — частые точки отказа. Укажите, как собираются и обслуживаются ассеты, когда нужно сбрасывать кэш и используется ли CDN.

Откат, который можно выполнить

Откат должен быть коротким, протестированным рецептом, привязанным к тегу или ID релиза. Например: развернуть предыдущий тег, восстановить снимок базы и инвалидировать кэши.

Если приложение было создано в Koder.ai и затем экспортировано, укажите последний работоспособный снимок и точную версию экспорта, чтобы клиент мог быстро сопоставить код с рабочим релизом.

Пошагово: проверка сборки после экспорта

Проверка — момент, когда вы узнаёте, настоящая ли передача. Цель проста: новый человек берёт экспортированный код, настраивает его и получает то же приложение без догадок.

Перед началом зафиксируйте, как выглядит «правильно»: версия работающего приложения, текущий коммит/тег и один–два ключевых экрана или API-ответа для сравнения. Если экспорт был из Koder.ai, отметьте снимок или время экспорта, чтобы доказать, что вы тестировали актуальное состояние.

1. Подтвердите, что экспорт совпадает с production: проверьте историю коммитов, заметки релиза или метаданные сборки. Сравните видимую строку версии или небольшое поведение (специфическая настройка или текст UI) с работающим приложением.
2. Настройте переменные окружения и секреты: создайте конфиг для целевого окружения (локально и для staging). Используйте инвентарь env и убедитесь, что в репозитории ничего не захардкожено.
3. Установите зависимости и запустите тесты: сделайте чистую установку (без кэшированных node_modules/vendor). Запустите юнит-тесты и линтеры точно так, как описано.
4. Примените миграции и запустите локально: поднимите базу данных, выполните миграции в порядке и стартуйте приложение. Убедитесь, что приложение читает/пишет базу и нет ожидаемых миграций.
5. Разверните в staging, выполните smoke-тесты, затем продвигайте: деплойте через те же скрипты/пайплайн, что планируете использовать в production. Продвигайте только когда staging соответствует ожиданиям.

Для smoke-тестов держите их короткими и привязанными к рискам:

• Вход/выход (или создание тестового пользователя)
• Один ключевой end-to-end сценарий (создать–изменить–сохранить)
• Один callback: email/webhook/платёж, если применимо
• Базовая обработка ошибок (плохой ввод, отсутствующая запись)
• Логи не показывают повторяющихся падений или ошибок, связанных с секретами

Если что-то ломается, зафиксируйте точную команду, вывод ошибки и используемые env. Эти детали экономят часы при смене владельца.

Распрострённые ошибки при передаче и как их избежать

Самый быстрый путь превратить передачу в пожар — предполагать, что «код достаточно». Хороший чек-лист фокусируется на мелочах, которые решают, сможет ли клиент действительно запускать и менять приложение без вас.

Ошибки, вызывающие большинство проблем

Большинство проблем укладывается в несколько шаблонов:

• Секреты не вращаются, поэтому старые пароли агентства, API-ключи или облачные токены продолжают работать после передачи.
• Переменные окружения неполные, потому что некоторые значения живут только в CI или панели хостинга, а не в репозитории.
• Разовые правки в production забываются: хотфикс, ручная правка БД или переключатель конфигурации, выставленный прямо на сервере.
• Миграции работают локально, но падают в проде из‑за отсутствия прав, расширений или владельцев схемы.
• Нет плана отката и нет помеченного релиза, к которому можно вернуться при первой неудачной сборке.

Как предотвратить их (без добавления недель работы)

Сделайте вращение и очистку доступа запланированной задачей, а не пунктом «когда найдём время». Назначьте дату, когда аккаунты агентства удаляются, сервисные ключи регенерируются и клиент подтверждает возможность деплоя только со своими кредами.

Для env выполните инвентарь из трёх мест: репозиторий, CI и UI хостинга. Затем проверьте это, сделав чистую сборку на новой машине или контейнере.

Для миграций тестируйте с той же ролью базы данных, которую будет использовать production-деплой. Если в production нужны привилегированные шаги (включение расширения), пропишите их и определите владельца.

Реалистичный пример: после экспорта проекта из Koder.ai клиент успешно деплоит, но фоновые задачи падают, потому что URL очереди был задан только в панели хостинга. Простой аудит env бы это выявил. Сопроводите тегированный релиз и документированный откат (например, «развернуть тег v1.8.2 и восстановить последний снимок»), и команда избежит простоя.

Финальный чек-лист, простой пример и дальнейшие шаги

Если оставить одну страницу из этого чек-листа, оставьте эту. Цель проста: чистый клон должен запускаться на новой машине, с новыми секретами и базой, которая может безопасно двигаться вперёд.

Быстрые проверки (выполнять из свежего клона)

Запускайте эти проверки на ноутбуке, который никогда не видел проект (или в чистом контейнере/VM). Это самый быстрый способ поймать недостающие файлы, скрытые предположения и старые креды.

• Сборка с нуля: установить зависимости, запустить тесты (если есть) и получить релизную сборку без ручных правок.
• Конфигурация работает: установить задокументированные переменные окружения и подтвердить, что приложение стартует с чистым конфигом или env.
• Секреты вращены: убедиться, что приложение работает с новыми ключами, затем отозвать старые и проверить, что ничего не сломалось.
• Миграции выполняются чисто: начать с пустой базы, применить миграции, затем запустить приложение и пройти базовый сценарий.
• Путь развёртывания реален: один раз выполнить скрипт развёртывания или CI-рабочий процесс и подтвердить, что он даёт тот же результат.

Простой пример передачи

Агентство передаёт React-фронтенд, Go API и PostgreSQL. Команда клиента клонирует репозиторий, копирует предоставленный .env.example в реальные env, создаёт новые учётные данные для базы, почты и сторонних API. Они запускают go test (или согласованную команду тестов), собирают React-приложение, применяют миграции к чистой Postgres-инстанции и запускают оба сервиса. Наконец, они деплоят с использованием документированного скрипта и подтверждают, что этот же коммит можно пересобрать позже.

Дальнейшие шаги

Сделайте передачу краткой и управляемой. 30–60 минутный walkthrough обычно эффективнее длинного документа.

• Запланируйте walkthrough и запишите решения (кто владеет деплоем, секретами и изменениями БД).
• Назначьте одного владельца production-доступа и одного резервного.
• Согласуйте финальный «acceptance build» коммит-хеш и пометьте его тегом.
• Если вы работали в Koder.ai, экспортируйте исходники, затем используйте снимки и откат при первом запуске клиентом, чтобы снизить риски.