architect/standards/PROJECT_STANDARD_IT.md

PROJECT_STANDARD_IT — Стандарт IT-проекта

Версия: 1.0.0
Дата: 2026-03-07

1. Зачем этот документ

PROJECT_STANDARD.md — универсальный стандарт для любого проекта (biz, ops, it, org...).
Этот файл — IT-расширение: правила специфичные для разработки, которых нет в базовом.

Читать вместе с:
- PROJECT_STANDARD.md — файловая структура, именование
- PROJECT_TYPOLOGY.md — типы IT-проектов (site/app/api/bot/...)
- PROJECT_DOCUMENTS.md — обязательные документы для it

2. Два способа начать IT-проект

PATH A — С нуля

НИЧЕГО → Vanilla (v0.0.0) → Working (v0.x.x) → Production (v1.0.0+)

Vanilla = голый дистрибутив без нашего кода. Это контрольная точка:
- CMS установлена, но не настроена
- Наш код ещё не написан
- Зафиксировано тегом v0.0.0

Когда PATH A:
- Новый проект с нуля
- Переход на новую CMS/фреймворк (Drupal 10 → 11)
- Смена технологии (PHP → Python)

# Точка ванилы фиксируется тегом
git tag v0.0.0 -m "Vanilla: Drupal 11.3.3 installed"
git push --tags

PATH B — Онбординг существующего

Получение → Анализ → Развёртывание → Working (v1.0.0)

Нет ванилы. Это уже рабочий проект — принимаем как есть.

Когда PATH B:
- Переезд с другого сервера
- Принятие проекта от другой команды
- Клонирование боевого проекта для доработки

Результат онбординга: v1.0.0 — момент когда проект поднят и понят.

Новая версия vs Новый проект

Ситуация Решение
Добавили фичу Новая версия: v1.0.0 → v1.1.0
Переход Drupal 10 → 11 Новый проект (PATH A), архивируем старый
Смена PHP → Python Новый проект (PATH A)
Баг-фикс v1.0.0 → v1.0.1
Рефакторинг (тот же стек) Новая версия

Правило: если смена CMS или ключевого фреймворка — новый проект.

3. Версионирование

Формат: MAJOR.MINOR.PATCH

Компонент Когда Пример
MAJOR Breaking changes — API изменился, несовместимо 1.0.0 → 2.0.0
MINOR Новая фича, добавлен модуль, обратно совместимо 1.0.0 → 1.1.0
PATCH Баг-фикс, hotfix 1.0.0 → 1.0.1

PATH A — нумерация

v0.0.0   ← Vanilla (дистрибутив без нашего кода)
v0.1.0   ← Первая фича / модуль
v0.2.0   ← Вторая фича
...
v1.0.0   ← Первый релиз в production
v1.1.0   ← Новая фича в проде
v1.1.1   ← Баг-фикс

PATH B — нумерация

Если проект уже версионирован:
  → Продолжить нумерацию (v2.3.1 → v2.3.2)

Если версии нет:
  → v1.0.0 (онбординг завершён, проект понят и задокументирован)

Теги в git

# При деплое на production
git tag v1.0.0 -m "Release: first production deploy"
git tag v1.1.0-catalog -m "Release: catalog module"  # модульный тег
git push --tags

4. Структура папок IT-проекта

Базовая структура

@it-{name}/
├── AI.md              ← контекст проекта (что, зачем, стек)
├── INDEX.md           ← навигация
├── STATUS.md          ← текущая стадия
├── LOG.md             ← история решений
├── DESIGN.md          ← архитектура
├── README.md          ← как запустить
├── LAUNCH.md          ← как задеплоить
├── GUIDE.md           ← как делать (рабочие процессы)
│
├── src/               ← наш код
├── tests/             ← тесты
├── deploy/            ← скрипты деплоя
│   ├── push.sh        ← деплой на сервер
│   └── servers.conf   ← конфигурация окружений
│
└── arh/               ← архив

Третья сторона (не наш код)

Зависимости и дистрибутивы — не в git, в .gitignore:

Стек Третья сторона Где лежит
Python venv, site-packages venv/ (gitignore)
Node.js npm пакеты node_modules/ (gitignore)
PHP/Composer зависимости vendor/ (gitignore)
Drupal ядро + контриб web/core/, web/modules/contrib/ (gitignore)

Правило: в git — только наш код и конфиги. Дистрибутивы восстанавливаются через pip install / npm install / composer install.

Расширенная структура (крупный проект)

@it-{name}/
├── ...базовые файлы...
│
├── src/
│   ├── modules/       ← Drupal кастомные модули
│   ├── themes/        ← Drupal темы
│   ├── components/    ← React/Vue компоненты
│   └── api/           ← API-слой
│
├── DESIGN-api.md      ← Расширение DESIGN (API-схема)
├── DESIGN-db.md       ← Расширение DESIGN (схема БД)
│
├── deploy/
│   ├── push.sh
│   ├── servers.conf
│   └── docker-compose.yml
│
└── data/              ← Схема данных, миграции (если есть)
    └── migrations/

5. Git-workflow

Ветки

Масштаб Ветки Когда
Маленький проект (1 разработчик) master Простые скрипты, боты
Средний проект master + develop CRM, сайт, API
Большой проект Gitflow полный Платформа, enterprise

Gitflow полный:

master      ← production (только релизы через PR)
develop     ← основная разработка
staging     ← тестирование перед релизом
feature/*   ← новые фичи (feature/catalog-filters)
hotfix/*    ← срочные фиксы production (hotfix/broken-price)

Формат коммитов

type(scope): subject

body (опционально — зачем, не что)

Типы:

Тип Когда
feat Новая функциональность
fix Исправление бага
docs Только документация
refactor Рефакторинг без изменения поведения
test Добавление / исправление тестов
chore Рутина: зависимости, конфиги, CI
deploy Деплой, инфраструктура

Примеры:

git commit -m "feat(catalog): add OEM search by article"
git commit -m "fix(import): handle empty prices in BAZON feed"
git commit -m "docs: update deployment guide for Drupal 11"
git commit -m "chore: upgrade dependencies to latest"

Правила:
- subject — на русском или английском, но консистентно в проекте
- Не больше 72 символов в первой строке
- Imperative: "add", "fix", "update" — не "added", "fixed"

6. Окружения

Окружение Назначение Ветка
local Разработка на ноутбуке develop / feature/*
staging Тестирование, демо заказчику staging
production Боевой сервер master

Конфиг окружений в deploy/servers.conf:

[local]
host=localhost
path=/var/www/project

[staging]
host=staging.example.ru
user=deploy
path=/var/www/project-staging

[production]
host=91.218.142.168
user=deploy
path=/var/www/project

7. Процесс создания нового IT-проекта

1. Определить PATH (A или B)
2. Создать папку @it-{name}/ по PROJECT_STANDARD.md
3. Заполнить AI.md — стек, хостинг, цель
4. Инициализировать git:
   git init
   git add .
   git commit -m "chore: init project structure"
5. PATH A: установить дистрибутив → зафиксировать v0.0.0
6. PATH B: развернуть существующий → зафиксировать v1.0.0
7. Заполнить README.md — как запустить
8. Заполнить LAUNCH.md — как задеплоить

8. Связи

Обновлено: 2026-03-07