PROJECT_STRUCTURE_STANDARD.md

Версия: 1.0.0
Дата: 2026-02-13
Статус: Обязательный для всех новых проектов

Основной принцип

ПРОЕКТ (бизнес-задача)
  │
  └── РЕШЕНИЯ (множество IT компонентов)
       │
       ├── СТЕК (технологии решения)
       │
       └── СРЕДЫ (dev/tst/prd)
            │
            └── ХРАНЕНИЕ (app/arh/dev/tst/prd)

Каждый уровень имеет чёткое назначение и структуру.

1. ПРОЕКТ (Project)

Что: Бизнес-задача, инициатива
Примеры: "Интернет-магазин", "CRM система", "Аналитическая платформа"

Структура проекта

project-name/
│
├── PROJECT.md                    ← Описание проекта (обязательно)
├── REQUIREMENTS.md               ← Бизнес-требования
├── ROADMAP.md                    ← Дорожная карта
│
├── it/                           ← IT РЕШЕНИЯ (обязательно)
│   ├── solution-1/
│   ├── solution-2/
│   └── ...
│
├── data/                         ← ДАННЫЕ проекта (опционально)
│   ├── inbox/                    Входящие файлы
│   ├── exports/                  Экспорты
│   └── images/                   Изображения
│
└── docs/                         ← ДОКУМЕНТАЦИЯ (рекомендуется)
    ├── ARCHITECTURE.md           Архитектура
    ├── INTEGRATION.md            Интеграции между решениями
    └── API.md                    API документация

PROJECT.md (обязательный файл)

# Название проекта

**Тип:** e-commerce | crm | analytics | platform | ...
**Статус:** planning | development | testing | production
**Владелец:** ФИО / Компания
**Дата создания:** YYYY-MM-DD

## Описание

Краткое описание бизнес-задачи (2-3 предложения).

## Цели

- Цель 1
- Цель 2
- Цель 3

## IT Решения

- `it/website/` - Веб-сайт (Drupal 11)
- `it/api/` - REST API (Python FastAPI)
- `it/database/` - База данных (MySQL 8.0)

## Команда

- Product Owner: ФИО
- Tech Lead: ФИО
- Developers: ...

## Ссылки

- Prod: https://example.com
- Test: https://test.example.com
- Документация: `/docs/`

2. РЕШЕНИЕ (Solution)

Что: IT компонент проекта
Примеры: Сайт, Мобильное приложение, API, База данных, Бот, Интеграция

Типы решений

Особое решение: database/

Тип	Назначение	Примеры стека
website	Веб-сайт	Drupal, WordPress, Laravel, Next.js
mobile-app	Мобильное приложение	React Native, Flutter, Swift
api	REST/GraphQL API	FastAPI, Express, Laravel
database	База данных (общая для всех решений)	MySQL, PostgreSQL, MongoDB
bot	Чат-бот	Python aiogram, Node.js telegraf
integration	Интеграция/синхронизация	Python, Node.js
analytics	Аналитика/дашборды	Grafana, Metabase, Superset
service	Фоновый сервис	Celery, Queue workers

База данных — это отдельное решение, которое используют другие решения.

Структура database/

database/
├── STACK.yaml                    Описание БД
├── README.md                     Как подключиться
│
├── schema/                       Схема БД (DDL)
│   ├── 01_tables.sql             Таблицы
│   ├── 02_relations.sql          Связи
│   └── 03_indexes.sql            Индексы
│
├── migrations/                   Миграции (версии схемы)
│   ├── 2026-02-01_001_create_products.sql
│   └── 2026-02-05_002_add_categories.sql
│
├── seeds/                        Начальные данные
│   ├── brands.sql
│   └── test_data.sql
│
├── dev/                          dev БД
│   ├── dump.sql                  Дамп
│   └── .env                      Credentials
│
├── tst/                          test БД
│   └── .env
│
└── prd/                          prod БД
    └── .env

Как другие решения подключаются

# В website/
ln -s ../database/dev/.env .env.database

# В api/
from configparser import ConfigParser
config = ConfigParser()
config.read('../database/dev/.env')
db = connect(config['DB_HOST'], config['DB_NAME'])

Структура решения

solution-name/
│
├── STACK.yaml                    ← Описание стека (обязательно)
├── README.md                     ← Как запустить (обязательно)
├── CHANGELOG.md                  ← История изменений
│
├── app/                          ← ШТАТНОЕ (обязательно)
│   ├── core/                     Фреймворк/CMS/дистрибутив
│   ├── vendor/                   Зависимости (composer/npm/pip)
│   └── contrib/                  Сторонние модули/плагины
│
├── arh/                          ← АРХИВ (обязательно)
│   ├── YYYY-MM-DD_название/      Бэкапы по датам
│   └── backups/                  Автоматические бэкапы
│
├── dev/                          ← РАЗРАБОТКА (обязательно)
│   └── custom/                   Наш код
│
├── tst/                          ← ТЕСТ (опционально)
│   └── custom/                   Копия из dev/
│
├── prd/                          ← ПРОДАКШН (обязательно)
│   └── custom/                   Копия из tst/ или dev/
│
└── deploy/                       ← ДЕПЛОЙ (обязательно)
    ├── servers.conf              Конфигурация серверов
    ├── push.sh                   Деплой на серверы
    ├── pull.sh                   Скачать с серверов
    └── status.sh                 Статус деплоев

3. СТЕК (Stack)

Что: Набор технологий для реализации решения

STACK.yaml (обязательный файл)

# Метаданные решения
solution: solution-name
type: website|api|database|mobile-app|bot|integration|analytics|service
description: Краткое описание решения

# Технологический стек
stack:
  # Основной язык программирования
  language:
    - php: 8.1
    - python: 3.11
    - nodejs: 20.x

  # Фреймворк/CMS
  framework:
    - drupal: 11.3.3
    - commerce: 3.x
    - laravel: 10.x

  # База данных
  database:
    primary: mysql:8.0
    alternative: mariadb:10.6

  # Веб-сервер (для web решений)
  webserver:
    - nginx: 1.21

  # Кэширование (опционально)
  cache:
    - redis: 6.x

  # Инструменты
  tools:
    - composer: 2.x
    - npm: 9.x
    - drush: 12.x

# Зависимости
dependencies:
  # Системные пакеты
  system:
    - php-fpm
    - php-mysql
    - php-gd

  # Другие решения проекта
  internal:
    - it/database
    - it/api

  # Библиотеки workspace
  external:
    - library/connectors/api/ozon
    - library/services/session

# Среды разработки
environments:
  # Разработка
  dev:
    location: local
    path: $WORKSPACE/projects/org/PROJECT/it/SOLUTION/

  # Тестирование
  tst:
    location: remote
    host: example.com
    user: username
    path: ~/staging/
    url: https://test.example.com

  # Продакшн
  prd:
    location: remote
    host: example.com
    user: username
    path: ~/production/
    url: https://example.com

# Метаданные
created: 2026-02-13
version: 1.0.0
maintainer: ФИО

4. СРЕДЫ (Environments)

dev/ - РАЗРАБОТКА

Назначение: Активная разработка
Где: Локально на компьютере разработчика
Содержимое: Наш код в процессе разработки

dev/
└── custom/                       Наш код
    ├── modules/                  Модули (для Drupal)
    ├── plugins/                  Плагины (для WP)
    ├── components/               Компоненты (для React)
    ├── scripts/                  Скрипты (для Python)
    └── ...

tst/ - ТЕСТИРОВАНИЕ

Назначение: Снапшот для тестирования
Где: Test сервер (staging)
Содержимое: Копия из dev/ после готовности

tst/
└── custom/                       Копия dev/custom/

Когда создавать:
- ✅ Тестирование занимает >1 дня
- ✅ Нужна параллельная разработка
- ✅ Требуется история тестов

Когда НЕ создавать:
- ❌ Быстрое тестирование (<1 часа)
- ❌ Маленький проект (1 разработчик)
- ❌ Можно сразу dev → prd

prd/ - ПРОДАКШН

Назначение: Боевая версия
Где: Production сервер
Содержимое: Копия из tst/ или dev/ после тестов

prd/
└── custom/                       Копия tst/custom/ или dev/custom/

Правило: Только через деплой! Никогда не редактировать напрямую.

5. ХРАНЕНИЕ (Storage)

app/ - ШТАТНОЕ

Website (Drupal/WordPress/Laravel)

app/
├── drupal-11.3.3/                Drupal core
├── vendor/                       Composer зависимости
└── contrib/                      Contrib модули
    ├── commerce/
    └── views/

API (Python/Node.js)

app/
├── venv/                         Python virtual environment
└── requirements.txt              Зависимости

Mobile App (React Native)

app/
└── node_modules/                 NPM зависимости

Правило: Регенерируется (composer install, npm install), не коммитим в git.

arh/ - АРХИВ

arh/
├── 2026-02-01_pre-catalog/       Бэкап перед большим изменением
├── 2026-02-10_prd-backup/        Бэкап prod перед деплоем
└── backups/
    ├── prd-2026-02-13.tar.gz     Автоматический бэкап
    └── db-2026-02-13.sql         Бэкап БД

Когда создавать:
- Перед большим рефакторингом
- Перед деплоем на prod (обязательно!)
- Автоматически раз в день/неделю

WORKFLOW

Процесс разработки

1. РАЗРАБОТКА (dev/)
   ↓
   - Пишем код
   - Тестируем локально
   - git commit
   ↓

2. ГОТОВО К ТЕСТАМ
   ↓
   cp dev/ → tst/
   rsync tst/ → test сервер
   ↓

3. ТЕСТИРОВАНИЕ
   ↓
   - Проверяем на test сервере
   - Находим баги → фиксим в dev/ → повторяем
   ↓

4. ТЕСТЫ ПРОЙДЕНЫ
   ↓
   cp tst/ → arh/YYYY-MM-DD_backup/  (бэкап текущей prd)
   cp tst/ → prd/
   rsync prd/ → prod сервер
   ↓

5. ПРОДАКШН
   ↓
   - Проверяем на prod
   - Мониторим 15 минут
   - git tag v1.0.0

Параллельная работа

ДЕНЬ 1:
dev/  v1.1.0  ← разрабатываем новое
tst/  v1.0.0  ← отправили на тесты
prd/  v0.9.0  ← работает на prod

ДЕНЬ 3:
dev/  v1.2.0  ← продолжаем разработку
tst/  v1.0.0  ← всё ещё тестируется
prd/  v0.9.0  ← стабильно работает

ДЕНЬ 5:
dev/  v1.3.0  ← новые фичи
tst/  v1.1.0  ← v1.0.0 протестирован, отправили v1.1.0
prd/  v1.0.0  ← задеплоили протестированную

КОМАНДЫ

Инициализация нового проекта

# Создать проект
mkdir -p projects/org/project-name
cd projects/org/project-name

# Структура
mkdir -p it data docs

# PROJECT.md
cat > PROJECT.md << 'EOF'
# project-name

**Тип:** ...
**Статус:** development

## Описание

...

## IT Решения

- `it/website/` - ...
EOF

# Git
git init
git add .
git commit -m "init: project structure"

Создание нового решения

cd it/
mkdir new-solution
cd new-solution

# Структура
mkdir -p app arh dev tst prd deploy docs

# STACK.yaml
cat > STACK.yaml << 'EOF'
solution: new-solution
type: website
stack:
  language:
    - php: 8.1
  framework:
    - drupal: 11.x
EOF

# README.md
cat > README.md << 'EOF'
# new-solution

## Стек

См. STACK.yaml

## Запуск

...
EOF

Деплой

# dev → tst
cp -r dev/custom tst/
./deploy/push.sh tst

# tst → prd (после тестов)
cp -r prd/ arh/$(date +%Y-%m-%d)_backup/  # бэкап
cp -r tst/custom prd/
./deploy/push.sh prd

ПРИМЕРЫ

Простой проект (1 решение)

simple-project/
├── PROJECT.md
└── it/
    └── website/                  Одно решение
        ├── STACK.yaml
        ├── app/
        ├── dev/
        ├── tst/
        └── prd/

Средний проект (3-5 решений)

medium-project/
├── PROJECT.md
└── it/
    ├── website/                  Сайт
    ├── api/                      API
    ├── database/                 БД
    └── bot/                      Бот

Большой проект (6+ решений)

large-project/
├── PROJECT.md
├── it/
│   ├── website/                  Сайт (Drupal)
│   ├── mobile-app/               Приложение (React Native)
│   ├── api/                      API (FastAPI)
│   ├── database/                 БД (MySQL)
│   ├── telegram-bot/             Telegram бот
│   ├── analytics/                Аналитика (Grafana)
│   ├── 1c-sync/                  Интеграция с 1С
│   └── admin-panel/              Админка (React)
├── data/
└── docs/
    └── ARCHITECTURE.md           Как всё связано

ПРОВЕРКИ

При создании проекта

✓ Создан PROJECT.md
✓ Создана папка it/
✓ Git инициализирован
✓ .gitignore создан

При создании решения

✓ Создан STACK.yaml
✓ Создан README.md
✓ Создана структура app/arh/dev/tst/prd/deploy/
✓ Тип решения определён

Перед деплоем на tst

✓ Код в dev/ протестирован локально
✓ Git коммит создан
✓ README обновлён

Перед деплоем на prd

✓ Тесты на tst пройдены
✓ Бэкап текущей prd создан
✓ Команда уведомлена
✓ План отката готов

ЧАСТЫЕ ВОПРОСЫ

Обязательна ли папка tst/?

Нет. Создавать только если:
- Тестирование >1 дня
- Нужна параллельная разработка
- Требуется история тестов

Можно ли несколько решений в одном git репозитории?

Да. Все решения проекта обычно в одном репозитории:

project/.git/
├── it/solution-1/
└── it/solution-2/

Или каждое решение в своём репозитории (для больших команд).

Где хранить данные (изображения, файлы)?

Каскадный метод: Общее → наверх, специфичное → внутрь

Уровень 1: data/ (файлы, общие для всех решений)

project/
├── data/                 ← Общие данные
│   ├── images/           Изображения
│   ├── documents/        Документы
│   ├── exports/          Экспорты
│   └── inbox/            Входящие файлы
└── it/website/

cd it/website/
ln -s ../../data data

Уровень 2: it/database/ (БД, общая для всех решений)

project/
├── it/
│   ├── database/         ← База данных как решение
│   │   ├── STACK.yaml    MySQL/PostgreSQL
│   │   ├── schema/       Схема БД
│   │   ├── dev/          dev БД
│   │   ├── tst/          test БД
│   │   └── prd/          prod БД
│   │
│   ├── website/          Подключается к database/
│   └── api/              Подключается к database/

cd it/website/
ln -s ../database/dev/.env .env.database

Уровень 3: it/solution/data/ (специфичные данные решения)

it/website/
└── dev/
    └── modules/
        └── custom_module/
            └── data/     ← Только для этого модуля

Как решения взаимодействуют?

Через:
- REST API (решение api/ предоставляет)
- Общую БД (решение database/)
- Очереди (Redis, RabbitMQ)
- Файлы (общая папка data/)

ЧЕК-ЛИСТЫ

Новый проект

✓ mkdir project-name
✓ mkdir it data docs
✓ Создать PROJECT.md
✓ git init
✓ Создать первое решение

Новое решение

✓ mkdir it/solution-name
✓ mkdir app arh dev tst prd deploy
✓ Создать STACK.yaml
✓ Создать README.md
✓ Определить тип (website/api/...)

Первый деплой

✓ Разработка в dev/
✓ Тесты локально пройдены
✓ Создать tst/ (если нужно)
✓ Деплой на test сервер
✓ Тесты на test OK
✓ Создать prd/
✓ Деплой на prod

СТАНДАРТНЫЕ ФАЙЛЫ

.gitignore (для решения)

# Штатное (регенерируется)
/app/vendor/
/app/node_modules/
/app/core/
/app/venv/

# Архив (большие файлы)
/arh/

# Среды (копии)
/tst/
/prd/

# Временное
*.log
*.tmp
.DS_Store
.env.local

deploy/servers.conf

# Test сервер
TEST_HOST=test.example.com
TEST_USER=username
TEST_PATH=~/staging/

# Prod сервер
PROD_HOST=example.com
PROD_USER=username
PROD_PATH=~/production/

deploy/push.sh

#!/bin/bash
TARGET=$1  # tst или prd

source servers.conf

if [ "$TARGET" == "tst" ]; then
  rsync -av --delete tst/custom/ $TEST_USER@$TEST_HOST:$TEST_PATH/custom/
  echo "✅ Deployed to TEST"

elif [ "$TARGET" == "prd" ]; then
  read -p "Deploy to PROD? (yes): " confirm
  if [ "$confirm" != "yes" ]; then
    echo "❌ Cancelled"
    exit 1
  fi

  rsync -av --delete prd/custom/ $PROD_USER@$PROD_HOST:$PROD_PATH/custom/
  echo "✅ Deployed to PROD"
fi

ПРИМЕНЕНИЕ

✅ Новым проектам (обязательно)
✅ Существующим проектам (при рефакторинге)
✅ Любым типам решений (web, mobile, api, bot, ...)
✅ Любым технологиям (Drupal, Laravel, Python, Node.js, ...)

Стандарт структуры IT проекта