# ADR-007: Интеграция с 1С через CSV-выгрузки

**Дата:** 2026-04-13
**Статус:** Proposed
**Связанные ADR:** ADR-001 (архитектура), ADR-006 (интеграция платформы)

---

## Контекст

Бухгалтер работает в 1С и ведёт:
- Управленческий учёт выручки и расходов
- Формирование налоговой отчётности (УСН)
- Акты, счета-фактуры (при необходимости)
- Амортизацию оборудования

Наша платформа PocketBase хранит все операционные данные (аренды, платежи, возвраты, пени), но 1С — это отдельная система бухгалтера, к которой у нас нет прямого доступа.

**Что уже есть:**
- Kit Online (251 ₽/мес) автоматически передаёт фискальные чеки в ОФД → ФНС. **Это не заменяет бухучёт** — Kit Online закрывает только 54-ФЗ.
- PocketBase содержит полный журнал операций для сверки

**Что нужно:** способ передавать бухгалтеру первичные данные для учёта в 1С без дублирования ввода.

---

## Решение

**CSV-выгрузки из админ-панели**. Бухгалтер скачивает отчёты раз в неделю/месяц и импортирует в 1С штатными средствами (обработки загрузки из табличных документов).

### Почему CSV

| Критерий | CSV | HTTP-сервисы 1С | CommerceML/EnterpriseData |
|----------|:---:|:---------------:|:-------------------------:|
| Срок разработки | 1-2 дня | 1-2 недели | 3-4 недели |
| Работает с любой 1С | ✅ | Только с сетевой 1С | Только с типовыми конфигурациями |
| Зависимость от версии 1С | Нет | Высокая | Средняя |
| Реалтайм | Нет | Да | Да |
| Подходит для MVP (<50 аренд/день) | ✅ | Избыточно | Избыточно |
| Трудозатраты бухгалтера | 1-2 ч/мес | 0 | 0 |

При объёме >50 аренд/день или нескольких постаматов CSV перестанет масштабироваться — тогда переход на **HTTP-сервисы 1С** (v2).

---

## Формат выгрузок

Все отчёты — **CSV UTF-8 with BOM** (требование 1С для корректной кодировки), разделитель `;` (стандарт для русской локали), даты в формате `YYYY-MM-DD HH:MM:SS`, суммы в рублях с копейками (`1234.56`).

### 1. Реестр аренд (`rentals-YYYY-MM.csv`)

Основной документ для учёта выручки.

| Колонка | Тип | Описание | Пример |
|---------|-----|----------|--------|
| `rental_id` | string | UUID аренды | `a1b2c3...` |
| `created_at` | datetime | Дата создания | `2026-04-13 14:30:00` |
| `completed_at` | datetime | Дата завершения | `2026-04-14 10:15:00` |
| `client_phone` | string | Телефон клиента (маскированный) | `+7 (9**) ***-12-34` |
| `equipment_name` | string | Наименование оборудования | `Перфоратор Bosch GBH 2-26` |
| `equipment_id` | string | Код номенклатуры | `EQ-001` |
| `locker_id` | string | Постамат | `LKR-MSK-001` |
| `duration_hours` | number | Длительность аренды | `20` |
| `rental_amount` | decimal | Сумма аренды | `500.00` |
| `deposit_amount` | decimal | Холд залога | `3000.00` |
| `deposit_charged` | decimal | Списано с залога (пени/ущерб) | `0.00` |
| `payment_method` | string | `sbp` / `card` | `sbp` |
| `payment_provider` | string | `tbank` / `cloudpayments` | `tbank` |
| `commission_amount` | decimal | Комиссия эквайринга | `2.00` |
| `fiscal_receipt_id` | string | Номер чека Kit Online | `KO-2026-041300123` |
| `fiscal_receipt_url` | string | Ссылка на электронный чек | `https://kitonline.ru/r/xyz` |
| `status` | string | `completed` / `cancelled` / `overdue` | `completed` |

### 2. Реестр платежей (`payments-YYYY-MM.csv`)

Детализация всех платёжных операций.

| Колонка | Тип | Описание |
|---------|-----|----------|
| `payment_id` | string | UUID платежа |
| `rental_id` | string | UUID аренды (если применимо) |
| `operation_type` | string | `auth` / `charge` / `confirm` / `void` / `refund` |
| `provider` | string | `tbank_sbp` / `cloudpayments` |
| `amount` | decimal | Сумма операции |
| `commission_amount` | decimal | Комиссия |
| `net_amount` | decimal | Сумма к зачислению (amount − commission) |
| `bank_transaction_id` | string | ID операции в банке |
| `processed_at` | datetime | Время операции |
| `status` | string | `success` / `failed` / `pending` |

### 3. Реестр пени и штрафов (`penalties-YYYY-MM.csv`)

Отдельная номенклатура в 1С — это прочие доходы, не выручка от аренды.

| Колонка | Тип |
|---------|-----|
| `penalty_id` | string |
| `rental_id` | string |
| `penalty_type` | string | `overdue` / `damage` / `loss` |
| `amount` | decimal |
| `charged_at` | datetime |
| `fiscal_receipt_id` | string |

### 4. Реестр возвратов (`refunds-YYYY-MM.csv`)

Возвраты залогов и частичные возвраты.

| Колонка | Тип |
|---------|-----|
| `refund_id` | string |
| `rental_id` | string |
| `refund_type` | string | `deposit_full` / `deposit_partial` / `rental_refund` |
| `amount` | decimal |
| `reason` | string |
| `processed_at` | datetime |

### 5. Справочник оборудования (`equipment.csv`)

Выгружается по запросу (не периодически) — для синхронизации номенклатуры.

| Колонка | Тип |
|---------|-----|
| `equipment_id` | string | Код в нашей системе |
| `name` | string |
| `category` | string |
| `purchase_price` | decimal | Закупочная стоимость |
| `purchase_date` | date |
| `status` | string | `active` / `retired` / `lost` |

### 6. Справочник постаматов (`lockers.csv`)

| Колонка | Тип |
|---------|-----|
| `locker_id` | string |
| `address` | string |
| `monthly_rent` | decimal | Ставка аренды места |
| `activation_date` | date |

---

## Административный интерфейс

Админ-панель (PocketBase Admin UI extension или отдельный раздел) → меню **«Бухгалтерия»**:

```
┌─ Бухгалтерия ─────────────────────────────────────────────┐
│                                                            │
│  Период: [Апрель 2026 ▾]   Формат: [CSV (1С) ▾]          │
│                                                            │
│  ┌──────────────────────────────────────────────────────┐ │
│  │ Отчёт                    │ Записей │ Действие       │ │
│  ├──────────────────────────┼─────────┼────────────────┤ │
│  │ Реестр аренд             │   342   │ [Скачать CSV]  │ │
│  │ Реестр платежей          │   687   │ [Скачать CSV]  │ │
│  │ Реестр пени и штрафов    │    18   │ [Скачать CSV]  │ │
│  │ Реестр возвратов         │    12   │ [Скачать CSV]  │ │
│  │ Справочник оборудования  │    16   │ [Скачать CSV]  │ │
│  │ Справочник постаматов    │     1   │ [Скачать CSV]  │ │
│  └──────────────────────────────────────────────────────┘ │
│                                                            │
│  [Скачать все одним ZIP]                                   │
│                                                            │
│  ─────────────────────────────────────────────────────    │
│  Последняя выгрузка: 2026-04-12 18:30                      │
│                                                            │
└────────────────────────────────────────────────────────────┘
```

**Требования:**
- Доступ только для роли `accountant` и `admin`
- Журнал выгрузок (кто, когда, какие периоды скачал) — для аудита
- Автоматическая отправка на email бухгалтера в 1-е число каждого месяца за предыдущий (опционально, P1)
- Дельта-выгрузки — только новые/изменённые записи с последней выгрузки (P2)

---

## Процесс работы бухгалтера

**Ежемесячно (до 5-го числа следующего месяца):**

1. Бухгалтер заходит в админ-панель, выбирает период «Прошлый месяц»
2. Скачивает ZIP с 4 отчётами
3. Загружает в 1С через штатную обработку «Загрузка из табличного документа»:
   - `rentals-*.csv` → документ «Реализация услуг» (группа номенклатуры «Аренда инструмента»)
   - `payments-*.csv` → банковские выписки (для сверки с банком)
   - `penalties-*.csv` → документ «Оказание услуг» (номенклатура «Пени за просрочку»)
   - `refunds-*.csv` → документ «Возврат от покупателя»
4. Проводит сверку с выписками Т-Банк и CloudPayments
5. Сверяет с чеками Kit Online (ОФД кабинет)

**Разовая настройка (при первом запуске):**
- Заведение в 1С номенклатуры «Аренда инструмента», «Пени за просрочку», «Залог»
- Настройка правил загрузки CSV (колонки → реквизиты)
- Заведение справочников контрагентов (клиенты — по мере появления)

---

## Разделение ответственности

| Что | Где ведётся | Источник истины |
|-----|-------------|-----------------|
| Фискальные чеки (54-ФЗ) | Kit Online → ОФД → ФНС | Kit Online |
| Журнал операций (аренды, платежи) | PocketBase | PocketBase |
| Бухгалтерский учёт (Дт/Кт) | 1С:Бухгалтерия | 1С |
| Налоговая отчётность (УСН) | 1С:Бухгалтерия | 1С |
| Расходы (аренда места, зарплата, закупка) | 1С:Бухгалтерия | 1С (заносит бухгалтер вручную) |

**Платформа НЕ ведёт бухучёт** — только отдаёт первичные данные. Проводки, регистры, отчётность — в 1С.

---

## Реализация

### Go-хук для генерации CSV

```go
// routes/admin/export.go
func ExportRentalsCSV(c echo.Context) error {
    period := c.QueryParam("period") // "2026-04"
    start, end := parsePeriod(period)

    rentals, err := app.Dao().FindRentalsByPeriod(start, end)
    if err != nil { return err }

    c.Response().Header().Set("Content-Type", "text/csv; charset=utf-8")
    c.Response().Header().Set(
        "Content-Disposition",
        fmt.Sprintf(`attachment; filename="rentals-%s.csv"`, period),
    )

    // BOM для корректного открытия в Excel/1С
    c.Response().Write([]byte{0xEF, 0xBB, 0xBF})

    w := csv.NewWriter(c.Response())
    w.Comma = ';'
    w.Write([]string{"rental_id", "created_at", ...})
    for _, r := range rentals {
        w.Write([]string{r.ID, r.CreatedAt.Format("2006-01-02 15:04:05"), ...})
    }
    w.Flush()
    return nil
}
```

### Журнал выгрузок (audit log)

Отдельная коллекция PocketBase `export_log`:

| Поле | Тип |
|------|-----|
| user_id | relation(users) |
| report_type | string |
| period | string |
| downloaded_at | datetime |
| row_count | number |

---

## Последствия

### Положительные

- **Минимум разработки** — 1-2 дня работы, никаких зависимостей от конфигурации 1С бухгалтера
- **Не блокирует запуск MVP** — Kit Online закрывает 54-ФЗ, бухучёт можно настраивать параллельно с пилотом
- **Работает с любой 1С** — Бухгалтерия 3.0, УНФ, Управление торговлей
- **Прозрачность** — CSV можно открыть в Excel для ручной проверки
- **Аудит** — журнал выгрузок фиксирует кто и когда скачал данные

### Отрицательные / Риски

| Риск | Вероятность | Митигация |
|------|------------|-----------|
| Бухгалтер забывает скачать отчёт | Средняя | Автоматическая отправка на email 1-го числа |
| Кодировка / разделитель ломается при импорте в 1С | Низкая | BOM UTF-8, разделитель `;`, тестовая выгрузка при настройке |
| Дубли при повторной загрузке | Средняя | Уникальный `rental_id` в CSV — 1С отслеживает по нему |
| При >50 аренд/день CSV становится неудобным | Средняя | Миграция на HTTP-сервисы 1С в v2 |
| Требование «реалтайм» от бухгалтера/налоговой | Низкая | Чеки и так идут реалтайм через Kit Online; бухучёт исторически работает на периоде |
| Утечка персональных данных клиентов через CSV | Средняя | Маскирование телефонов, доступ только `accountant`+`admin`, журнал выгрузок |

---

## Альтернативы (рассмотрены и отвергнуты)

### HTTP-сервисы 1С (REST/SOAP)

- **Против для MVP:** Требует 1С, доступной из интернета (или VPN между нашим сервером и бухгалтерской 1С). Бухгалтер-аутсорсер обычно держит 1С у себя на ноутбуке. Сильная зависимость от конфигурации 1С — правки на стороне бухгалтера при любых изменениях API. Избыточно при <50 аренд/день
- **За:** Реалтайм, без ручного труда бухгалтера
- **Вердикт:** Откладываем до v2 (если объём вырастет)

### CommerceML / EnterpriseData (стандартный XML-обмен)

- **Против:** Ориентирован на обмен товарами/заказами между интернет-магазином и 1С:Управление торговлей. Не подходит для услуг аренды. Сложная схема, избыточна
- **Вердикт:** Не применимо для нашей модели

### Прямая запись в базу 1С (через COM / ODBC)

- **Против:** Работает только на Windows-сервере с установленной 1С. Хрупко, ломается при обновлениях 1С. Не масштабируется
- **Вердикт:** Антипаттерн, никогда

### Полный отказ от 1С (учёт в нашей системе)

- **Против:** Требует разработки полноценного бухгалтерского модуля (Дт/Кт, регистры, отчётность ФНС). Это отдельный бизнес, не наш скоуп. Бухгалтер-специалист эффективнее в 1С, чем в кастомной системе
- **Вердикт:** Нет

---

## Следующие шаги

1. Уточнить у бухгалтера:
   - Версия 1С (Бухгалтерия 3.0 / УНФ / другая)
   - Система налогообложения (УСН 6% / УСН 15% / НПД / ОСН)
   - Периодичность выгрузок (ежемесячно / еженедельно)
   - Требуется ли акт об оказанных услугах на каждую аренду (обычно нет — чек Kit Online достаточен для B2C)
2. Реализовать эндпоинты `/api/v1/admin/export/*` и UI выгрузок (Фаза 1, неделя 5-6)
3. Провести тестовую выгрузку с бухгалтером на реальной 1С до запуска пилота
4. Настроить правила импорта на стороне 1С (один раз, силами бухгалтера)

---

## Ссылки

- [ADR-001: Архитектура системы](ADR-001-system-architecture.md) — §7 (Kit Online)
- [ADR-006: Интеграция платформы, постамата и приложения](ADR-006-integration-platform-postmat-app.md)
- [1С:Бухгалтерия — Загрузка из табличного документа](https://its.1c.ru/db/metod8dev/content/5829/hdoc)
- [Kit Online API](https://kitonline.ru/api/)