Руководство разработчика

Как настроить локальную среду разработки и вносить код в SnapOtter.

Предварительные требования

• Node.js 22.22+
• pnpm 9+ (corepack enable && corepack prepare pnpm@latest --activate)
• Docker (требуется для локальных Postgres + Redis, сборок контейнеров и AI-функций)
• Git

Python 3.11+ нужен только если вы работаете над AI/ML-сайдкаром (удаление фона, апскейл, OCR).

Настройка

git clone https://github.com/snapotter-hq/snapotter.git
cd snapotter
docker compose -f docker-compose.dev.yml up -d   # start Postgres + Redis
pnpm install
pnpm dev

Это запускает два dev-сервера:

Сервис	URL	Примечания
Фронтенд	http://localhost:1351	Dev-сервер Vite, проксирует /api
Бэкенд	http://localhost:13490	Fastify API (доступ через прокси)

Откройте http://localhost:1351 в браузере. Войдите под admin / admin. При первом входе вам будет предложено сменить пароль.

Структура проекта

apps/
  api/              Fastify backend
  web/              Vite + React frontend
  docs/             VitePress documentation (this site)
packages/
  shared/           Constants, types, i18n strings
  image-engine/     Sharp-based image operations
  media-engine/     FFmpeg spawn + progress parsing
  doc-engine/       qpdf, LibreOffice, ghostscript wrappers
  ai/               Python sidecar bridge for ML models
tests/
  unit/             Vitest unit tests
  integration/      Vitest integration tests (full API)
  e2e/              Playwright end-to-end specs
  fixtures/         Small test images

Команды

pnpm dev                # start frontend + backend
pnpm build              # build all workspaces
pnpm typecheck          # TypeScript check across monorepo
pnpm lint               # Biome lint + format check
pnpm lint:fix           # auto-fix lint + format
pnpm test               # unit + integration tests
pnpm test:unit          # unit tests only
pnpm test:integration   # integration tests only
pnpm test:e2e           # Playwright e2e tests
pnpm test:coverage      # tests with coverage report

Соглашения по коду

• Двойные кавычки, точки с запятой, отступ в 2 пробела (обеспечивается Biome)
• ES-модули во всех воркспейсах
• Conventional commits для semantic-release
• Zod для всей валидации входных данных API
• Никаких изменений в конфигурационных файлах Biome, TypeScript или редактора. Исправляйте код, а не линтер.

База данных

PostgreSQL 17 через Drizzle ORM (pg-core). Локальная разработка требует запущенных Postgres и Redis — запустите их командой:

docker compose -f docker-compose.dev.yml up -d

Это даёт вам Postgres на порту 5432 и Redis на порту 6379. Затем сгенерируйте и примените миграции:

cd apps/api
npx drizzle-kit generate   # generate a migration from schema changes
npx drizzle-kit migrate    # apply pending migrations

Схема определена в apps/api/src/db/schema.ts. Таблицы: users, sessions, settings, jobs, apiKeys, pipelines, teams, userFiles, roles, auditLog.

Добавление нового инструмента

Каждый инструмент следует одному и тому же шаблону. Вот минимальный пример.

1. Бэкенд-маршрут

Создайте apps/api/src/routes/tools/my-tool.ts:

import { z } from "zod";
import type { FastifyInstance } from "fastify";
import { createToolRoute } from "../tool-factory.js";

const settingsSchema = z.object({
  intensity: z.number().min(0).max(100).default(50),
});

export function registerMyTool(app: FastifyInstance) {
  createToolRoute(app, {
    toolId: "my-tool",
    settingsSchema,
    async process(inputBuffer, settings, filename) {
      // Use sharp or other libraries to process the image
      const sharp = (await import("sharp")).default;
      const result = await sharp(inputBuffer)
        // ... your processing logic
        .toBuffer();

      return {
        buffer: result,
        filename: filename.replace(/\.[^.]+$/, ".png"),
        contentType: "image/png",
      };
    },
  });
}

Затем зарегистрируйте его в apps/api/src/routes/tools/index.ts.

2. Компонент настроек фронтенда

Создайте apps/web/src/components/tools/my-tool-settings.tsx:

import { useState } from "react";
import { useToolProcessor } from "@/hooks/use-tool-processor";
import { useFileStore } from "@/stores/file-store";

export function MyToolSettings() {
  const { files } = useFileStore();
  const { processFiles, processing, error, downloadUrl } =
    useToolProcessor("my-tool");

  const [intensity, setIntensity] = useState(50);

  const handleProcess = () => {
    processFiles(files, { intensity });
  };

  return (
    <div className="space-y-4">
      {/* your controls here */}
      <button
        type="button"
        onClick={handleProcess}
        disabled={files.length === 0 || processing}
        data-testid="my-tool-submit"
        className="w-full py-2.5 rounded-lg bg-primary text-primary-foreground font-medium disabled:opacity-50"
      >
        Process
      </button>
    </div>
  );
}

Затем зарегистрируйте его в реестре инструментов фронтенда в apps/web/src/lib/tool-registry.tsx:

// Add the lazy import
const MyToolSettings = lazy(() =>
  import("@/components/tools/my-tool-settings").then((m) => ({
    default: m.MyToolSettings,
  })),
);

// Add to the toolRegistry Map
["my-tool", { displayMode: "before-after", Settings: MyToolSettings }],

Режимы отображения: "side-by-side", "before-after", "live-preview", "no-comparison", "interactive-crop", "interactive-eraser", "no-dropzone".

3. Запись i18n

Добавьте в packages/shared/src/i18n/en.ts:

"my-tool": {
  name: "My Tool",
  description: "Short description of what this tool does",
},

4. Тесты

Добавьте атрибут data-testid к кнопке действия (как показано выше), чтобы e2e-тесты могли надёжно нацеливаться на неё.

5. Визуальные эталоны

Скриншот-тесты не допускают ни одного изменённого пикселя, а новый инструмент меняет то, что они отрисовывают: число инструментов на главной странице и в каталоге, новую карточку в сетке и собственную страницу, на которой tests/e2e/gui-visual-tools.spec.ts падает с "snapshot doesn't exist", пока у неё нет эталона. Обновите эталоны в том же PR, что и инструмент, чтобы ночное визуальное сравнение оставалось зелёным.

CI генерирует эталоны как для linux (ubuntu-latest), так и для darwin (macos-latest). Отправьте свою ветку и запустите на ней обновление:

gh workflow run update-visual-baselines.yml --ref <your-branch> -f update_snapshots=changed

Каждая задача ОС загружает артефакт visual-baselines-linux-<run-id>-<attempt> или visual-baselines-darwin-<run-id>-<attempt> и открывает черновой PR (chore/visual-baselines-linux-... и chore/visual-baselines-darwin-...) в main с перегенерированными PNG. В описании каждого чернового PR есть команда gh run download; выполните обе из корня вашего checkout, чтобы положить PNG в свою ветку, закоммитьте их и закройте черновые PR. Используйте update_snapshots=all, если changed пропускает скриншот, который должен был измениться. Для запуска нужен доступ на запись в репозиторий, поэтому если ваша ветка в форке, напишите в PR, что нужно обновить эталоны, и мейнтейнер запустит обновление.

На Mac вы также можете обновить эталоны darwin локально для более быстрой отладки:

pnpm playwright test --project=chromium-visual --project=mobile-chromium --project=tablet-chromium --update-snapshots=changed

В любом случае откройте каждый новый или изменённый PNG перед коммитом: эталон фиксирует то, что отрисовалось, сломанное или нет.

Релизу ничего из этого не нужно. Версия приложения замаскирована на каждом скриншоте, где она видна, поэтому её повышение не меняет ни одного эталона.

Сборки Docker

Соберите полный продакшен-образ локально:

docker build -f docker/Dockerfile -t snapotter:latest .

Используйте кэш-монтирования BuildKit для более быстрых пересборок:

DOCKER_BUILDKIT=1 docker build -f docker/Dockerfile -t snapotter:latest .

Домены релизной версии

SnapOtter намеренно имеет три домена версий. Не копируйте один домен в другой во время релиза:

• Версия выпуска приложения охватывает корневой манифест, все пакеты частной рабочей области и APP_VERSION. Semantic-release предоставляет это значение, а pnpm version:sync <version> обновляет каждую рабочую область перед выпуском приложения.
• OpenAPI info.version — стабильный публичный основной контракт API. Все локализованные спецификации остаются в <major>.0.0 для совместимых выпусков приложений и изменяются только при переходе контракта API на новую основную версию.
• docker/feature-manifest.json сохраняет imageVersion: 2.0.0 как неизменяемую устаревшую эпоху хранения пакетов функций. Эти пути к архивам версии 2 не являются версиями пакетов приложений. Accurate OCR использует формат времени выполнения v3 и записывает происхождение версии приложения отдельно.

tests/unit/infra/release-version-policy.test.ts обеспечивает соблюдение этих границ. Домен новой версии или миграция должны одновременно обновить этот контракт и соответствующий проект миграции артефакта. Независимые значения API и устаревшего пакета находятся в config/release-version-policy.json; синхронизация версий приложения никогда не должна неявно перезаписывать этот файл политики.

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

Полный список смотрите в руководстве по конфигурации. Ключевые для разработки:

Переменная	По умолчанию	Описание
AUTH_ENABLED	true	Включить/отключить аутентификацию
DEFAULT_USERNAME	admin	Имя пользователя администратора по умолчанию
DEFAULT_PASSWORD	admin	Пароль администратора по умолчанию
SKIP_MUST_CHANGE_PASSWORD	false	Пропустить принудительную смену пароля (только CI/dev)
RATE_LIMIT_PER_MIN	1000	Лимит частоты запросов к API в минуту (0 = отключено)
MAX_UPLOAD_SIZE_MB	100	Максимальный размер загрузки в МБ (0 = без ограничений)