---
name: sheets-writer
description: "Use when writing data to Google Sheets — content drafts, post statuses, tactic sections. Covers column map (A-Q), date formats, status values, and the migrate-drafts-to-sheet.js command."
context: fork
---
# Sheets Writer

## Когда использовать

Каждый раз когда создаёшь черновик поста или финализируешь раздел тактики — он должен попасть в Google Sheets. Это единственный источник правды для Жени.

## Команда записи

```bash
node scripts/migrate-drafts-to-sheet.js
```

Запускай из корня проекта (`/Users/techno/Desktop/Extreme_festival`).
Скрипт сканирует `output/drafts/*.md`, разбирает метаданные и пишет строки в лист «Контентная».

**Перед запуском:** убедись что файл черновика сохранён в `output/drafts/YYYY-MM-DD-slug.md`.

## Маппинг колонок — лист «Контентная»

Полная таблица: @references/column-map.md

| Колонка | Поле | Откуда берётся |
|---------|------|----------------|
| A | День недели (Пн/Вт/…) | Авто из даты |
| B | Дата публикации | Из имени файла (YYYY-MM-DD) |
| C | Рубрика | Из мета-блока черновика |
| D | S-ID | Из мета-блока (S-01, S-02, …) |
| E | Этап воронки | Из мета-блока |
| F | Маяк | Заполняет Женя вручную |
| G | Ссылка на медиа | Заполняется при публикации |
| H | Текст поста | Тело черновика |
| I | Цель текста | Из мета-блока (продающая часть А) |
| J | Продающая часть А→Б | Из мета-блока |
| K | Как сделать интересным (механика) | Из мета-блока |
| L | Формат | Из мета-блока (Пост ВК / ТГ / Reels / …) |
| M | Охват план | Из мета-блока (метрики план) |
| N | Охват факт | Заполняется после публикации |
| O | ERR% план | Из мета-блока |
| P | ERR% факт | Заполняется после публикации |
| Q | Статус | Черновик → На проверке → Одобрен → Опубликован |
| R+ | Баланс воронки | **Авто-формулы — НЕ ТРОГАТЬ** |

## Статусы (Q) — только эти значения

| Статус | Кто ставит | Когда |
|--------|-----------|-------|
| `Бэклог` | Система | Ячейка запланирована, контента нет |
| `Черновик` | Агент | После создания черновика |
| `На проверке` | Агент | После передачи Жене |
| `Одобрен` | Женя вручную | После утверждения |
| `Опубликован` | Женя вручную | После публикации |

**Агент никогда не ставит статус `Одобрен` или `Опубликован`** — это делает Женя.

## Формат дат

- В имени файла: `YYYY-MM-DD` (например, `2026-05-11-gruppa-nedeli.md`)
- В таблице колонка B: `DD.MM.YYYY` (например, `11.05.2026`)
- В мета-блоке черновика: `YYYY-MM-DD` (скрипт конвертирует автоматически)

## Структура файла черновика (обязательна для парсинга)

```markdown
> Рубрика: Презентация группы (S-01)
> Платформа: ВКонтакте
> S-ID: S-01
> Этап: Привлечение
> Продающая часть: [ситуация] → [результат]
> Механика: [из 8 механик]
> Формат: Пост ВК
> Дата: 2026-05-11
> Охват план: 3000
> ERR план: 4%

[Текст поста здесь]
```

Имя файла: `2026-05-11-gruppa-nedeli.md` в папке `output/drafts/`

## Правила записи в Sheets

1. **`valueInputOption: 'USER_ENTERED'`** — использовать всегда. Позволяет интерпретировать формулы и даты.
2. **Колонки R и дальше — не трогать** — там авто-формулы баланса воронки. Любая запись туда сломает подсчёт.
3. **Строки 1–3 — заголовки** — данные начинаются с строки 4 (`DATA_START_ROW = 4`).
4. **Дубликаты:** скрипт проверяет по дате+рубрике. Если строка уже есть — пропускает, не дублирует.
5. **Лист называется «Контентная»** — регистр важен.

## Частые ошибки

| Ошибка | Причина | Решение |
|--------|---------|---------|
| Скрипт не находит файлы | Файлы не в `output/drafts/` | Переместить файл в нужную папку |
| Дата не распозналась | Имя файла без `YYYY-MM-DD` префикса | Переименовать файл |
| Статус не обновился | Строка уже существует с другим статусом | Обновить вручную или через Sheets API PATCH |
| `R+ column overwrite` | Агент попытался записать в R+ | Убедиться что скрипт пишет только до Q |
| Auth error | Нет credentials.json или token.json | Проверить `notifier/credentials.json` |

## Gotchas

- Не запускай `migrate-drafts-to-sheet.js` больше одного раза подряд — дубликаты защищены, но лишние запросы к API тратят квоту
- Google Sheets API лимит: 300 запросов/минуту. При массовом импорте добавляй паузы
- Файл `notifier/.env` должен содержать `GOOGLE_SPREADSHEET_ID` — без него скрипт упадёт