# Сборка внешней обработки FordewindCert.epf

Инструкция по сборке файла внешней обработки **FordewindCert.epf**
(Fordewind Cert / Cert4U — электронное подписание документов, УКЭП + ПЭП)
из исходников в Конфигураторе 1С.

> Скомпилировать .epf без установленной платформы 1С:Предприятие нельзя.
> Здесь даны исходники и точная спецификация формы (FORM_SPEC.md), по которым
> .epf собирается за несколько минут.

---

## 1. Состав поставки

| Файл                        | Назначение                                              |
|-----------------------------|---------------------------------------------------------|
| `Module_ObjectModule.bsl`   | Модуль объекта обработки (СведенияОВнешнейОбработке).    |
| `Form_MainForm_Module.bsl`  | Модуль формы: HTTP-слой, ПЭП/УКЭП-сценарии, служебное.   |
| `CAdES_signing_module.bsl`  | Область УКЭП-подписания — **вставляется в модуль формы**.|
| `FORM_SPEC.md`              | Точная структура формы (реквизиты, элементы, команды).   |
| `README_СБОРКА.md`          | Эта инструкция.                                          |
| `1C_API_INSTRUCTION.md`     | Краткая инструкция по REST API для 1С-разработчика.      |

---

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

### Платформа
- **1С:Предприятие 8.3.21 и выше** (требуется штатный метод
  `НачатьПодписаниеДанныхCAdES`).
- Режим совместимости обработки: **не ниже «Версия 8.3.21»**.
- Основной режим запуска: **Управляемое приложение**.
- Свойство конфигурации/сеанса: **РежимИспользованияМодальности = Не использовать**
  (весь UI обработки асинхронный, совместим с этим режимом и веб-клиентом).

### Для сценария ПЭП (отправка по ссылке)
- Никаких дополнительных компонентов. Работает в **тонком, толстом и веб-клиенте**,
  в **безопасном режиме**.

### Для сценария УКЭП (локальное подписание)
- Установленный криптопровайдер с поддержкой ГОСТ — **КриптоПро CSP 5.0**.
- **Расширение работы с криптографией 1С**:
  - толстый клиент — устанавливается вместе с платформой;
  - веб-клиент — «1С:Расширение для работы с криптографией» (браузерное).
- Сертификат подписанта — в **личном хранилище** пользователя.
- УКЭП-подписание требует клиента с доступом к криптопровайдеру
  (тонкий/толстый клиент или веб-клиент с расширением). В «чистом» веб-клиенте
  без расширения доступен только ПЭП-сценарий.

---

## 3. Сборка в Конфигураторе (пошагово)

1. **Конфигуратор → Файл → Новый → Внешняя обработка.**

2. Свойства обработки:
   - Имя: `FordewindCert`
   - Синоним: `Fordewind Cert — Электронное подписание`
   - Комментарий: `Интеграция с сервисом электронного подписания (УКЭП/ПЭП)`

3. **Модуль объекта**: двойной клик по «Модуль объекта» → вставить целиком
   содержимое `Module_ObjectModule.bsl`.

4. **Создать форму**: правый клик на «Формы» → Добавить → Управляемая форма.
   - Имя: `ФормаОсновная`
   - Отметить «Назначить основной формой».

5. **Создать реквизиты и таблицы формы** строго по разделам 2.1–2.3 файла
   **FORM_SPEC.md** (реквизиты `АдресСервера`, `КлючAPI`, `ПутьAPI`,
   `АдресСервераНастройка`, `КлючAPIНастройка`, `ПутьAPIНастройка`,
   `РежимПесочницы`, `НазваниеДокумента`, `ОписаниеДокумента`,
   `ТипПодписиОтправка`, `ТекстРезультатаПроверки`, таблицы `ТаблицаДокументов`
   и `ТаблицаКлиентов`).

6. **Создать команды формы** по разделу 3 FORM_SPEC.md (11 команд), у каждой в
   свойстве «Действие» указать одноимённый обработчик.

7. **Разместить элементы** (страницы, поля, таблицы, кнопки) по разделу 4
   FORM_SPEC.md.

8. **Модуль формы**: открыть модуль формы «ФормаОсновная» и:
   - вставить целиком содержимое `Form_MainForm_Module.bsl`;
   - **в конец** модуля (после строки-маркера `↓↓↓ вставьте содержимое
     CAdES_signing_module.bsl ↓↓↓`) вставить целиком содержимое
     `CAdES_signing_module.bsl` (области `УКЭППодписание` и `УКЭПСлужебное`).
   - Убедиться, что события формы `ПриСозданииНаСервере` и `ПриОткрытии`
     привязаны в палитре свойств формы.

9. **Синтаксический контроль**: Конфигуратор → Текст → Проверить модуль
   (Ctrl+F7). Ошибок быть не должно.

10. **Сохранить .epf**: Файл → Сохранить как → `FordewindCert.epf`.

---

## 4. Выгрузка готового .epf

- В Конфигураторе: **Файл → Сохранить как → FordewindCert.epf**.
- Либо через пакетный режим (для CI):
  ```
  "C:\Program Files\1cv8\<версия>\bin\1cv8.exe" DESIGNER /F "<путь к ИБ>" ^
    /DumpExternalDataProcessorOrReport "FordewindCert.epf" "<имя обработки в дереве>"
  ```
  (имена ключей зависят от версии платформы; проще сохранить вручную).

---

## 5. Установка и настройка

**Ручной запуск:** Предприятие → Файл → Открыть → `FordewindCert.epf`.

**Через «Дополнительные отчёты и обработки» (БСП):**
Администрирование → Печатные формы, отчёты и обработки → Дополнительные
отчёты и обработки → Добавить → загрузить `FordewindCert.epf`.
Обработка регистрируется в **безопасном режиме**.

**Настройка (вкладка «Настройки»):**
1. Адрес сервера — домен без схемы: `cert4u.ru`.
2. Путь к API: `/api.php` (без каких-либо префиксов). Если в поле подставлено другое
   значение по умолчанию — замените его на `/api.php`, иначе запросы будут уходить мимо API.
3. API-ключ — из личного кабинета Cert4U: Настройки → «API-ключи». Ключ принадлежит
   вашему аккаунту: обработка видит только его документы и клиентов.
4. (Опционально) флажок «Тестовый режим (песочница)» — SMS/e-mail реально не
   отправляются, ПЭП-код возвращается как `000000`.
5. «Проверить подключение» → «Сохранить настройки».

Полная документация API (включая методы, которых нет в интерфейсе обработки:
`api_1c_send_document` — отправка одним запросом без создания клиента, `api_1c_settings` —
формат УКЭП аккаунта, создание клиентов через `POST api_1c_clients`, вебхуки) —
https://cert4u.ru/api-docs.html и https://cert4u.ru/rest-api.html, а также `1C_API_INSTRUCTION.md`.

---

## 6. Что изменилось относительно версии 1.0 (по итогам ревью)

- **УКЭП переведён на штатный механизм** `НачатьПодписаниеДанныхCAdES`
  (CAdES-BES, detached) — **без COM-объектов CAdESCOM**, кросс-платформенно.
- Модуль подписания **подключён к форме** и использует её единый HTTP-слой;
  удалён вызов несуществующей `ВыполнитьPOSTЗапросAPI` и хардкод адреса/ключа.
- **API-ключ передаётся в заголовке `X-Api-Key`**, а не в URL (не светится в
  логах). Сервер принимает и `X-Api-Key`, и `Authorization: Bearer`.
- Во всех HTTP-соединениях задан **таймаут** (60 c).
- **Идемпотентность**: на операциях создания/отправки шлётся заголовок
  `Idempotency-Key` (детерминированный хеш от содержимого/параметров) — обрыв
  связи не плодит дубли документов и повторные платные SMS.
- **Кросс-платформенность**: имя файла извлекается независимо от разделителя
  (`\` или `/`); все модальные вызовы заменены на асинхронные
  (`ПоказатьПредупреждение`, `НачатьВыборСертификата`, `НачатьПомещениеФайлов`,
  `НачатьПолучениеФайлов` и т. д.).
- **Обработка ошибок**: проверяется `КодСостояния` ответа; исключения не
  «глотаются» — причина логируется через `ПодробноеПредставлениеОшибки` в
  журнал регистрации, пользователю выводится понятное сообщение.
- **Настраиваемый путь API** (для cert4u.ru — `/api.php`)
  и **режим песочницы** (`X-Cert4U-Sandbox: 1`).

---

## 7. Чек-лист проверки после сборки (в песочнице)

1. Настройки: заполнить адрес/путь/ключ, включить «Песочницу», «Проверить
   подключение» → должно вернуться «Подключение успешно».
2. Вкладка «Документы»: «Обновить» → списки документов и клиентов загрузились.
3. Загрузка: указать название, «Загрузить документ» → появился документ в статусе
   «Новый».
4. «Подписать (сервер)» → статус «Подписан (сервер)».
5. Выбрать клиента, «Отправить клиенту» → вернулась ссылка и код ПЭП `000000`
   (песочница).
6. «Быстрая ПЭП-отправка» (файл + клиент) → ссылка и код `000000`.
7. «Подписать УКЭП и загрузить» (при необходимости с «ИНН подписанта») → затем «Отправить клиенту». Кнопки «Полный цикл» и «Подписать (сервер)» скрыты — серверная подпись отключена.
8. «Проверить подписи» → в поле результата выводится блок проверки.
9. «Скачать ZIP-архив» → файл сохраняется.
10. УКЭП (толстый клиент/веб с расширением): «Подписать УКЭП и загрузить» →
    диалог выбора сертификата, ввод PIN, статус «Подписан (сервер)», серверная
    криптопроверка «ПОДТВЕРЖДЕНА».
11. Повторить п.3 дважды с тем же файлом при обрыве — дубль не создаётся
    (идемпотентность).
12. Отключить «Песочницу» только после успешного прогона всех пунктов.

---

## 8. Что нужно проверить на живой 1С (за кадром)

- Точные сигнатуры асинхронных методов криптографии на конкретной сборке
  платформы (например, порядок параметров `НачатьПодписаниеДанныхCAdES` и наличие
  `НачатьВыборСертификата` — в старших релизах 8.3 они стабильны, но перед
  тиражированием прогнать синтаксический контроль на целевой версии).
- Работу выгрузки в веб-клиенте с установленным браузерным расширением
  криптографии (для УКЭП).
- Поведение `ЗаписьДанных` при смешанной записи текста и двоичных данных
  (multipart) на целевой платформе — при необходимости заменить на побайтовую
  сборку через БуферДвоичныхДанных.