architect/arh/standards/structure-old/SUBPROJECTS.md

Подпроекты (Subprojects)

Версия: 1.0.0
Дата: 2026-01-25

Концепция

Проект может содержать подпроекты — самостоятельные приложения на разных технических стеках, объединённые общей бизнес-целью.

Проект (бизнес)
└── Подпроекты (технические стеки)
    ├── app/django/      — Django приложение
    ├── app/nextjs/      — Next.js сайт
    ├── app/cscart/      — CS-Cart магазин
    └── app/mobile/      — React Native приложение

Когда использовать подпроекты

ДА (разные стеки)

НЕТ (один стек)

Правило: Подпроект = отдельный runtime, deployment, зависимости.

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

projects/org/example/
└── app/
    └── platform-name/        ← Подпроект
        ├── PROJECT.md        ← Описание подпроекта
        ├── DEPLOYMENT.md     ← Инструкция развёртывания
        │
        ├── modules/          ← Код (специфично для платформы)
        ├── dist/             ← Дистрибутивы, архивы
        ├── scripts/          ← Утилиты
        ├── backups/          ← Бэкапы (если нужны)
        └── docs/             ← Документация подпроекта

Обязательные файлы

Файл Назначение
PROJECT.md Описание подпроекта, стека, зависимостей
DEPLOYMENT.md Пошаговая инструкция развёртывания

Рекомендуемые папки

Папка Назначение
modules/ Код (модули, библиотеки, компоненты)
dist/ Готовые артефакты (архивы, wheel, npm пакеты)
scripts/ Утилиты (установка, миграция, проверка)
backups/ Важные бэкапы БД/конфигов
docs/ Документация (API, troubleshooting)

Именование подпроектов

app/{platform}/

Примеры:
- app/django/ — Django backend
- app/nextjs/ — Next.js фронтенд
- app/cscart/ — CS-Cart магазин
- app/mobile/ — React Native приложение
- app/wordpress/ — WordPress сайт
- app/laravel/ — Laravel API

Правило: Имя платформы/фреймворка, не функция (app/shop/ → app/cscart/).

PROJECT.md подпроекта

Описывает технический стек, зависимости, структуру.

# Platform Name: Project Subproject

**Тип:** Backend / Frontend / Mobile / CMS
**Платформа:** Django 4.2 / Next.js 14 / CS-Cart 4.19 / ...
**Версия:** 1.0.0

## Описание

Краткое описание подпроекта и его роли.

## Домены

| Домен | Статус | Назначение |
|-------|--------|------------|
| api.example.com | production | REST API |
| app.example.com | staging | Frontend staging |

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

\`\`\`
app/platform/
├── PROJECT.md
├── DEPLOYMENT.md
├── modules/
├── dist/
└── scripts/
\`\`\`

## Компоненты

### 1. Core

**Версия:** X.Y.Z
**Требования:** ...

### 2. Модули

| Модуль | Версия | Статус |
|--------|--------|--------|
| module_a | 1.0.0 | Active |

## Быстрый старт

\`\`\`bash
# Развёртывание
cat DEPLOYMENT.md
\`\`\`

## Документация

| Документ | Описание |
|----------|----------|
| [DEPLOYMENT.md](DEPLOYMENT.md) | Развёртывание |

DEPLOYMENT.md подпроекта

Пошаговая инструкция развёртывания от нуля до production.

Содержание:
1. Требования (OS, runtime, БД)
2. Установка зависимостей
3. Конфигурация
4. База данных (создание, миграции)
5. Первый запуск
6. Проверка работоспособности
7. Журнал изменений (changelog)

Формат:
- Каждый шаг — исполняемая команда
- Чеклисты для проверки
- Решения типичных проблем
- Скриншоты (если UI)

Скрипты подпроекта

Утилиты для обслуживания подпроекта.

Типичные скрипты:
- scripts/install.sh — автоматическая установка
- scripts/check_installation.php — проверка корректности
- scripts/migrate.sh — миграция данных
- scripts/backup.sh — создание бэкапа
- scripts/deploy.sh — деплой на сервер

Правила:
- Исполняемые (chmod +x)
- С комментариями
- README.md в папке scripts/

Дистрибутивы

Готовые к установке артефакты.

Примеры:
- dist/module_v1.2.4.tgz — архив модуля
- dist/app_v2.0.0.whl — Python wheel
- dist/package-1.5.0.zip — npm пакет
- dist/wordpress-plugin.zip — плагин

Правила:
- Семантическое версионирование (semver)
- Изменения в PROJECT.md при новой версии

Связь с родительским проектом

projects/org/example/
├── CLAUDE.md              ← Упоминает подпроекты
├── PROJECT.md             ← Бизнес-описание
│
└── app/
    └── platform/
        ├── PROJECT.md     ← Ссылка на родителя
        └── ...

В родительском CLAUDE.md:

## Подпроекты (технические стеки)

- `app/django/` — Django 4.2 (Python, PostgreSQL)
- `app/nextjs/` — Next.js 14 (TypeScript, React)

В подпроекте PROJECT.md:

**Родительский проект:** [projects/org/example/](../../)

Примеры

Пример 1: CS-Cart подпроект

projects/org/{PROJECT_NAME}/
└── app/
    └── cscart/
        ├── PROJECT.md          — Описание CS-Cart подпроекта
        ├── DEPLOYMENT.md       — Развёртывание CS-Cart
        ├── modules/
        │   └── lider_import/   — Модуль импорта
        ├── dist/
        │   └── lider_import_v1.2.4.tgz
        ├── scripts/
        │   ├── check_installation.php
        │   └── change_timestamp.sh
        ├── backups/
        └── docs/

Пример 2: Full-stack проект

projects/company/saas/
└── app/
    ├── backend/         — Django REST API
    │   ├── PROJECT.md
    │   ├── requirements.txt
    │   └── ...
    │
    ├── frontend/        — Next.js фронтенд
    │   ├── PROJECT.md
    │   ├── package.json
    │   └── ...
    │
    └── mobile/          — React Native приложение
        ├── PROJECT.md
        ├── package.json
        └── ...

Чеклист создания подпроекта

Правила разработки

1. Автономность

Каждый подпроект должен быть самодостаточным:
- Собственный PROJECT.md и DEPLOYMENT.md
- Собственные скрипты
- Можно развернуть независимо

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

Каждый подпроект версионируется отдельно:
- Версия в PROJECT.md
- Changelog в DEPLOYMENT.md

3. Документация

Вся специфичная для стека документация — внутри подпроекта:
- API → app/platform/docs/API.md
- Troubleshooting → app/platform/docs/TROUBLESHOOTING.md

4. Дистрибутивы

Готовые артефакты → dist/:
- Архивы модулей
- Compiled binaries
- Docker images (ссылки)

Связанные стандарты

Версия: 1.0.0