# docs/features — документация по фичам

Эта директория хранит описания **фич** проекта TeleCart: по одной поддиректории на фичу.
Цель — дать агенту (и человеку) возможность быстро восстановить контекст по конкретной
части системы, не перечитывая весь код: что фича делает, через какие точки входит, какие
файлы за неё отвечают и как данные текут по слоям.

Вложенные `CLAUDE.md` подхватываются Claude Code автоматически при чтении файлов из их
директории — поэтому индекс фичи читается «по требованию», когда работа касается этой фичи.

## Структура

```
docs/features/
├── CLAUDE.md        # этот файл: конвенции + реестр фич
├── _TEMPLATE.md     # шаблон для новой фичи (копировать при описании)
└── <feature-slug>/
    └── CLAUDE.md    # индексный файл конкретной фичи
```

## Конвенции

- **Имя папки** — `kebab-case`, по сути фичи: `cart`, `telegram-webhook`, `form-builder`.
- **Один индекс на фичу** — `<feature-slug>/CLAUDE.md`, заполняется по `_TEMPLATE.md`.
- **Ссылки на код — обязательны.** Указывай реальные пути (`module/.../src/Handlers/CartHandler.php`)
  и `action` из карт маршрутов. Код — источник истины; документация лишь навигирует к нему.
- **Не дублируй код.** Описывай назначение, поток и нюансы, а не построчный пересказ — он устареет.
- **Связывай фичи** через ссылки на их папки (например `[checkout](../checkout/CLAUDE.md)`).
- Если описанное в доке расходится с кодом — прав код; обнови доку.

## Как добавить фичу

1. `cp _TEMPLATE.md <feature-slug>/CLAUDE.md` (создав папку).
2. Заполни секции шаблона, опираясь на реальный код.
3. Добавь строку в реестр ниже.

## Реестр фич

| Фича           | Путь                                                   | Краткое описание                                                          |
|----------------|--------------------------------------------------------|--------------------------------------------------------------------------|
| cart           | [cart/CLAUDE.md](cart/CLAUDE.md)                       | Корзина: наполнение, просмотр, передача в оформление заказа               |
| settings       | [settings/CLAUDE.md](settings/CLAUDE.md)              | Каркас настроек: форма в админке → хранение → чтение на backend           |
| telecart-pulse | [telecart-pulse/CLAUDE.md](telecart-pulse/CLAUDE.md)  | Связка с SaaS: события кампаний и heartbeat (телеметрия окружения)        |

<!-- Новые фичи добавляй строкой в таблицу выше, по алфавиту. -->