Hướng dẫn dành cho nhà phát triển

Cách thiết lập một môi trường phát triển cục bộ và đóng góp mã cho SnapOtter.

Điều kiện tiên quyết

• Node.js 22.22+
• pnpm 9+ (corepack enable && corepack prepare pnpm@latest --activate)
• Docker (bắt buộc cho Postgres + Redis cục bộ, dựng container, và các tính năng AI)
• Git

Python 3.11+ chỉ cần thiết nếu bạn đang làm việc trên sidecar AI/ML (xóa nền, phóng đại, OCR).

Thiết lập

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

Điều này khởi động hai máy chủ dev:

Dịch vụ	URL	Ghi chú
Frontend	http://localhost:1351	Máy chủ dev Vite, proxy /api
Backend	http://localhost:13490	API Fastify (truy cập qua proxy)

Mở http://localhost:1351 trong trình duyệt của bạn. Đăng nhập bằng admin / admin. Bạn sẽ được nhắc đổi mật khẩu ở lần đăng nhập đầu tiên.

Cấu trúc dự án

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

Lệnh

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

Quy ước mã

• Dấu nháy kép, dấu chấm phẩy, thụt lề 2 khoảng trắng (được ép buộc bởi Biome)
• ES module trong tất cả các workspace
• Conventional commits cho semantic-release
• Zod cho tất cả việc xác thực đầu vào API
• Không sửa đổi các tệp cấu hình Biome, TypeScript, hoặc trình soạn thảo. Hãy sửa mã, không sửa linter.

Cơ sở dữ liệu

PostgreSQL 17 qua Drizzle ORM (pg-core). Dev cục bộ yêu cầu Postgres và Redis đang chạy - hãy khởi động chúng bằng:

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

Điều này cung cấp cho bạn Postgres trên cổng 5432 và Redis trên cổng 6379. Sau đó tạo và áp dụng các di trú:

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

Lược đồ được định nghĩa trong apps/api/src/db/schema.ts. Các bảng: users, sessions, settings, jobs, apiKeys, pipelines, teams, userFiles, roles, auditLog.

Thêm một công cụ mới

Mọi công cụ đều tuân theo cùng một mẫu. Đây là một ví dụ tối giản.

1. Route backend

Tạo 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",
      };
    },
  });
}

Rồi đăng ký nó trong apps/api/src/routes/tools/index.ts.

2. Thành phần thiết lập frontend

Tạo 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>
  );
}

Rồi đăng ký nó trong tool registry của frontend tại 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 }],

Các chế độ hiển thị: "side-by-side", "before-after", "live-preview", "no-comparison", "interactive-crop", "interactive-eraser", "no-dropzone".

3. Mục i18n

Thêm vào packages/shared/src/i18n/en.ts:

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

4. Kiểm thử

Thêm một thuộc tính data-testid vào nút hành động của bạn (như đã trình bày ở trên) để các kiểm thử e2e có thể nhắm vào nó một cách đáng tin cậy.

Dựng Docker

Dựng image sản xuất đầy đủ ở cục bộ:

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

Dùng các cache mount BuildKit để dựng lại nhanh hơn:

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

Tên miền phiên bản phát hành

SnapOtter cố ý có ba miền phiên bản. Không sao chép tên miền này sang tên miền khác trong quá trình phát hành:

• Phiên bản phát hành ứng dụng bao gồm tệp kê khai gốc, tất cả các gói không gian làm việc riêng tư và APP_VERSION. Semantic-release cung cấp giá trị này và pnpm version:sync <version> cập nhật mọi không gian làm việc trước khi phát hành ứng dụng.
• OpenAPI info.version là hợp đồng chính API công cộng ổn định. Tất cả các thông số kỹ thuật được bản địa hóa vẫn có trên <major>.0.0 cho các bản phát hành ứng dụng tương thích và chỉ thay đổi khi hợp đồng API chuyển sang phiên bản chính mới.
• docker/feature-manifest.json giữ imageVersion: 2.0.0 là kỷ nguyên lưu trữ gói tính năng kế thừa bất biến. Những đường dẫn lưu trữ v2 đó không phải là phiên bản gói ứng dụng. OCR chính xác sử dụng định dạng thời gian chạy v3 và ghi lại nguồn gốc phát hành ứng dụng của nó một cách riêng biệt.

tests/unit/infra/release-version-policy.test.ts thực thi các ranh giới này. Miền phiên bản mới hoặc quá trình di chuyển phải cập nhật hợp đồng đó và thiết kế di chuyển thành phần lạ có liên quan cùng nhau. Các giá trị API và gói kế thừa độc lập tồn tại trong config/release-version-policy.json; Đồng bộ hóa phiên bản ứng dụng không bao giờ được viết lại tệp chính sách đó một cách ngầm định.

Biến môi trường

Xem Hướng dẫn cấu hình để biết danh sách đầy đủ. Những biến quan trọng cho việc phát triển:

Biến	Mặc định	Mô tả
AUTH_ENABLED	true	Bật/tắt xác thực
DEFAULT_USERNAME	admin	Tên người dùng quản trị mặc định
DEFAULT_PASSWORD	admin	Mật khẩu quản trị mặc định
SKIP_MUST_CHANGE_PASSWORD	false	Bỏ qua việc buộc đổi mật khẩu (chỉ CI/dev)
RATE_LIMIT_PER_MIN	1000	Giới hạn tốc độ API mỗi phút (0 = tắt)
MAX_UPLOAD_SIZE_MB	100	Kích thước tải lên tối đa tính bằng MB (0 = không giới hạn)