DOCUMENT SEQUENCE — Последовательность создания документов

type: organization
name: ЛидерАвто
industry: retail
domains:
  - biz
  - fin
  - it

type: module
name: catalog
purpose: Каталог товаров
dependencies:
  - import
  - search
version: 1.0.0

1. index.yaml          ← МАСТЕР-ФАЙЛ (обязательно)

type: module
name: catalog
status: planning

2. .biz.md             ← ЗАЧЕМ (бизнес-ценность)

# Назначение

Краткое описание зачем.

## Бизнес-задача

Какую проблему решаем.

## Ценность

- Что получим
- Метрики успеха

## Требования

- Требование 1
- Требование 2

Ситуация: Начинаем модуль catalog
Создаём: catalog/purpose.biz.md
Содержимое: "Каталог товаров с фильтрами. Ценность: конверсия +30%"

3a. .arc.md            ← КАК устроена система (архитектура)

# Архитектура

## Технологии

- Backend: PHP
- Frontend: JS
- БД: MySQL

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

1. Модуль A
2. Модуль B

## Интеграции

- Система X через API

3b. .dsg.md            ← КАК устроен модуль (дизайн)

# Дизайн: Название

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

1. Products — управление товарами
2. Filters — фильтрация

## Данные

| Компонент | Таблица | API |
|-----------|---------|-----|
| Products | products | fn_get_products() |

## Алгоритм

1. Получить фильтры
2. Построить SQL
3. Вернуть результат

4. .spc.md             ← ЧТО ДЕЛАЕТ (детально)

catalog/
├── catalog-products.spc.md     ← спека товаров
├── catalog-filters.spc.md      ← спека фильтров
└── catalog-search.spc.md       ← спека поиска

# Спецификация: Products

## Функция

### fn_get_products($params)

**Параметры:**
- `$params` (array) — фильтры

**Возвращает:**
- array — список товаров

**SQL:**
```sql
SELECT * FROM products
WHERE category_id = ?

**Правило:** .spc = обязательный документ для модуля

---

### Этап 4: API документация (30-60 минут)

**Триггер:** Спеки готовы, нужно задокументировать интерфейс

**Создаём:**

**Зачем .api:**
- Публичные функции модуля
- Примеры использования
- Параметры и возвраты (короткая форма)
- Шаблоны (если есть)

**Когда создавать:**
- ✅ Module с публичным API
- ✅ Module используется другими модулями
- ❌ Component (API на уровне модуля)
- ❌ Project (нет кода)

**Содержимое:**
```markdown
# API: Catalog

## Функции

### fn_get_products($params)
Получить товары с фильтрацией

### fn_get_categories()
Получить категории

## Использование

```php
$products = fn_get_products([
    'category_id' => 5,
    'brand' => 'MAN'
]);

**Отличие от .spc:**
- `.spc` — КАК работает ВНУТРИ (алгоритм, SQL)
- `.api` — КАК использовать СНАРУЖИ (примеры)

---

### Этап 5: Промпты для AI (20-40 минут)

**Триггер:** Спеки готовы, нужно СГЕНЕРИРОВАТЬ код

**Создаём:**

**Зачем .pmt:**
- Инструкции для AI
- Требования к коду
- Что использовать
- Что НЕ использовать

**Когда создавать:**
- ✅ Генерируем код AI
- ✅ Сложная логика (нужны детали)
- ❌ Пишем код вручную
- ❌ Тривиальный код

**Дробление:**
Один промпт = одна задача для AI:

**Содержимое:**
```markdown
# Промпт: Создать Products

Создай класс Products в `src/Products.php`

## Требования

1. По спеке catalog-products.spc.md
2. PDO prepared statements
3. Типизация

## Использовать

- db_get_array()
- fn_paginate()

## НЕ использовать

- Прямой SQL
- eval()

7. .tst.md             ← ТЕСТ-ПЛАН

# Тесты: Catalog

## Unit-тесты

- [ ] fn_get_products() возвращает массив
- [ ] Фильтр по категории работает

## Интеграционные

- [ ] Товары из БД отображаются
- [ ] Фильтры применяются

## Ручные

1. Открыть /catalog
2. Выбрать категорию
3. Проверить: товары показаны

## Критерии

- Все unit пройдены
- Все ручные пройдены

8. src/                ← КОД

src/
├── Products.php
├── Filters.php
└── Search.php

.ops.md                ← ПРОЦЕССЫ

.str.md                ← СТРУКТУРА

.prj.md                ← ПЛАН

НАЧИНАЕМ НОВЫЙ УРОВЕНЬ
    ↓
1. Создать index.yaml          ← ВСЕГДА первым
    ↓
2. Нужно объяснить ЗАЧЕМ?
    ├─→ ДА → .biz.md
    └─→ НЕТ → пропустить
    ↓
3. Какой уровень?
    ├─→ project/domain → .arc.md (архитектура)
    ├─→ module → .dsg.md (дизайн)
    └─→ component → пропустить
    ↓
4. Нужны детали?
    ├─→ ДА → .spc.md (спецификации)
    └─→ НЕТ → пропустить
    ↓
5. Есть публичный API?
    ├─→ ДА → .api.md
    └─→ НЕТ → пропустить
    ↓
6. Генерируем AI?
    ├─→ ДА → .pmt.md (промпты)
    └─→ НЕТ → пропустить
    ↓
7. Нужны тесты?
    ├─→ ДА → .tst.md
    └─→ НЕТ → пропустить
    ↓
8. Есть код?
    ├─→ ДА → src/
    └─→ НЕТ → готово
    ↓
ПАРАЛЛЕЛЬНО (когда нужно):
    ├─→ Деплой? → .ops.md
    ├─→ Оргструктура? → .str.md
    └─→ План проекта? → .prj.md

День 1 (10 мин):
1. catalog/index.yaml          ← мастер-файл
2. catalog/purpose.biz.md      ← зачем
3. catalog/catalog.spc.md      ← что делает

День 2 (2 часа):
4. catalog/src/Catalog.php     ← код

ИТОГО: 4 файла

День 1 (30 мин):
1. catalog/index.yaml          ← мастер-файл
2. catalog/purpose.biz.md      ← зачем

День 2 (1 час):
3. catalog/design.dsg.md       ← как устроен

День 3 (3 часа):
4. catalog/catalog-products.spc.md
5. catalog/catalog-filters.spc.md
6. catalog/catalog-search.spc.md

День 4 (1 час):
7. catalog/api.api.md          ← API

День 5 (1 час):
8. catalog/products-create.pmt.md
9. catalog/filters-create.pmt.md
10. catalog/search-create.pmt.md

День 6 (4 часа):
11. catalog/src/Products.php   ← код по промптам
12. catalog/src/Filters.php
13. catalog/src/Search.php

День 7 (1 час):
14. catalog/test.tst.md        ← тесты

ИТОГО: 14 файлов за неделю

День 1 (1 час):
1. lideravto-2026/index.yaml           ← мастер-файл
2. lideravto-2026/requirements.biz.md  ← требования

День 2 (2 часа):
3. lideravto-2026/roadmap.prj.md       ← план
4. lideravto-2026/architecture.arc.md  ← архитектура

День 3-7:
[Создание модулей внутри проекта]

Перед деплоем:
5. lideravto-2026/deployment.ops.md    ← инструкции

ИТОГО: 5 файлов проекта + файлы модулей

catalog/
├── purpose.biz.md
└── src/

catalog/
├── index.yaml         ← ПЕРВЫМ ДЕЛОМ!
├── purpose.biz.md
└── src/

День 1:
- index.yaml
- purpose.biz.md
- design.dsg.md
- spec.spc.md
- api.api.md
- test.tst.md
- deployment.ops.md   ← Зачем?!

День 1:
- index.yaml
- purpose.biz.md

День 2:
- design.dsg.md

День 3:
- spec.spc.md

... по мере необходимости

1. src/Products.php    ← сразу код
2. spec.spc.md         ← потом спека?!

1. index.yaml
2. purpose.biz.md
3. design.dsg.md
4. spec.spc.md
5. src/Products.php    ← код ПОСЛЕДНИМ

index.yaml:
  type: module
  purpose: Каталог товаров    ← краткое (1 строка)

purpose.biz.md:
  # Назначение

  Каталог товаров...          ← полное (много текста)

  ## Бизнес-задача
  ...

# catalog/index.yaml
type: module
children:
  - products
  - filters
  - search

# Catalog

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

- [Products](src/Products/)
- [Filters](src/Filters/)
- [Search](src/Search/)

ЛЮБОЙ УРОВЕНЬ:
1. index.yaml          ← ВСЕГДА

MODULE (обязательно):
1. index.yaml
2. .spc.md             ← минимум
3. src/                ← код

MODULE (рекомендуется):
1. index.yaml
2. purpose.biz.md
3. design.dsg.md
4. .spc.md
5. api.api.md
6. test.tst.md
7. src/

index.yaml    ← День 0 (мастер)
    ↓
.biz          ← День 1 (зачем)
    ↓
.arc/.dsg     ← День 2 (как общее)
    ↓
.spc          ← День 3-4 (детали)
    ↓
.api          ← День 5 (интерфейс)
    ↓
.pmt          ← День 6 (инструкции)
    ↓
src/          ← День 7+ (код)

Параллельно:
.ops, .str, .prj, .tst ← когда нужно