# FNS Receipt Service

Express-сервис на Node.js 22 для создания чеков через ФНС и отправки ссылки на чек по email.

## Локальный запуск

```bash
npm install
cp .env.example .env
npm start
```

Сервис запустится на порту из `PORT` или на `4000` по умолчанию.

Админ-интерфейс доступен по адресу:

```http
GET /admin
```

Для входа используется значение `API_PASS`. Через интерфейс можно смотреть локальный журнал чеков, синхронизировать последние чеки из кабинета ФНС, создавать чек вручную, проверять ФНС/SMTP и менять параметры сервиса без отдельного фронтенд-фреймворка.

Swagger UI доступен по адресу:

```http
GET /swagger
```

OpenAPI JSON доступен по адресу:

```http
GET /openapi.json
```

## Docker

Сборка образа:

```bash
docker build -t fns-receipt-service .
```

Запуск контейнера:

```bash
docker run --env-file .env -p 3000:3000 fns-receipt-service
```

## Переменные окружения

Заполните эти переменные в Timeweb Cloud в разделе переменных окружения:

```env
INN=123456789012
PASSWORD=your_fns_password
APPNAME=Название проекта
ADMIN_EMAIL=admin@example.com
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=noreply@example.com
SMTP_PASS=email_app_password
SMTP_MAIL_FROM=noreply@example.com
API_PASS=strong_api_password
JWT_SECRET=long_random_jwt_secret
ADMIN_SESSION_HOURS=12
PORT=3000
HOST=0.0.0.0
FNS_TIMEOUT_MS=30000
SMTP_TIMEOUT_MS=15000
```

`API_PASS` используется как пароль входа в админ-панель и должен совпадать с `api_pass` в старых запросах к `POST /api/v1/create-receipt`. После входа UI получает JWT и дальше отправляет запросы с `Authorization: Bearer <token>`.

`JWT_SECRET` лучше задавать отдельно от `API_PASS`. Если `JWT_SECRET` не задан, сервис подпишет JWT через `API_PASS`, но для продакшена это менее удобно при ротации пароля.

Настройки, измененные через UI, сохраняются в `data/config.json` и перекрывают значения из `.env`. Сетевые параметры `PORT` и `HOST` применятся после перезапуска процесса.

## Timeweb Cloud

Что заполнить при Docker-деплое:

| Поле | Значение |
| --- | --- |
| Dockerfile | `Dockerfile` |
| Порт | `3000` |
| Путь до директории проекта | `/fns-receipt-service` |
| Путь проверки состояния | `/health` |

Команду запуска для Docker-деплоя отдельно указывать не нужно: она уже задана в `Dockerfile` как `CMD ["node", "/app/server.js"]`.

## API

Проверка состояния:

```http
GET /health
```

Создание чека:

```http
POST /api/v1/create-receipt
Content-Type: application/json

{
  "api_pass": "strong_api_password",
  "email": "client@example.com",
  "items": [
    {
      "id": "order-1",
      "name": "Услуга",
      "price": 1000,
      "quantity": 1
    }
  ]
}
```

Поле `email` обязательно: на этот адрес сервис отправит письмо со ссылкой на чек после успешного создания чека в ФНС.

Если чек создан в ФНС, но письмо клиенту не отправилось, API вернет `success: true`, `receiptCreated: true`, `emailSent: false`, `receiptId`, `printLink` и `technicalError`. Ошибка отправки сохранится в `error.json`.

Все успешно созданные чеки сохраняются в локальный журнал `data/receipts.json`, чтобы в UI была связь между чеком, email пользователя и позициями заказа. Синхронизация с ФНС подтягивает последние чеки из кабинета, но для старых чеков, созданных не этим сервисом, email пользователя может быть неизвестен.