دليل المطوّر

كيفية إعداد بيئة تطوير محلية والمساهمة بالكود في SnapOtter.

المتطلبات المسبقة

• Node.js 22.22+
• pnpm 9+ (corepack enable && corepack prepare pnpm@latest --activate)
• Docker (مطلوب لـ Postgres + Redis المحليين، وبناء الحاويات، وميزات الذكاء الاصطناعي)
• Git

يلزم Python 3.11+ فقط إذا كنت تعمل على الوحدة الجانبية للذكاء الاصطناعي/تعلّم الآلة (إزالة الخلفية، والتكبير، و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

يبدأ هذا خادمي تطوير:

الخدمة	العنوان	ملاحظات
الواجهة الأمامية	http://localhost:1351	خادم تطوير 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

أعراف الكود

• علامات اقتباس مزدوجة، وفواصل منقوطة، وإزاحة بمسافتين (يفرضها 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" إلى أن تحصل على صورة مرجعية. حدّث الصور المرجعية في طلب السحب نفسه الذي يضيف الأداة، حتى تبقى المقارنة المرئية الليلية ناجحة.

يولّد 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> ويفتح طلب سحب مسودة (chore/visual-baselines-linux-... وchore/visual-baselines-darwin-...) مقابل main يحتوي على ملفات PNG المُعاد توليدها. يتضمن وصف كل طلب سحب مسودة أمر gh run download؛ شغّل كليهما من جذر نسختك المحلية لوضع ملفات PNG في فرعك، ثم أنشئ commit لها وأغلق طلبَي السحب المسودة. استخدم update_snapshots=all بدلًا من ذلك إذا فات changed لقطةً كنت تتوقع أن تتغيّر. يتطلب التشغيل صلاحية كتابة على المستودع، لذا إذا كان فرعك في fork، فاذكر في طلب السحب أنه يحتاج إلى تحديث الصور المرجعية وسيشغّله أحد المشرفين.

على جهاز Mac، يمكنك أيضًا تحديث الصور المرجعية لـ darwin محليًا لتكرار أسرع:

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

وفي كل الأحوال، افتح كل ملف PNG جديد أو معدّل قبل إنشاء commit له: فالصورة المرجعية تسجّل ما عُرض كما هو، معطوبًا كان أم لا.

لا يحتاج الإصدار إلى أي من هذا. رقم إصدار التطبيق مُقنَّع في كل لقطة شاشة تعرضه، لذا فإن رفعه لا يغيّر أي صورة مرجعية.

بناء 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/التطوير فقط)
RATE_LIMIT_PER_MIN	1000	حد معدل API في الدقيقة (0 = معطّل)
MAX_UPLOAD_SIZE_MB	100	الحد الأقصى لحجم الرفع بالميغابايت (0 = غير محدود)