رفتن به محتوای اصلی

شروع به کار

پیش‌نیازها​

  • Node ≥ 18 و npm (با پشتیبانی از workspaces)
  • Docker و Docker Compose
  • PostgreSQL (یا همان دیتابیس dev که خودِ compose برایتان بالا می‌آورد)

اجرای محلی (dev)​

# ۱) بالا آوردن دیتابیس dev (PostgreSQL روی پورت ۵۴۳۲)
docker compose -f docker-compose.dev.yml up -d

# ۲) نصب و اجرای همه‌چیز (API روی ۵۰۰۰، وب روی ۵۱۷۳)
cp .env.example .env        # متغیرهای محیطی را پر کنید
npm install
npm run db:migrate --workspace taghvimam-backend
npm run dev

در حالت dev، اپ وب درخواست‌های /api را خودش به API روی پورت ۵۰۰۰ پروکسی می‌کند؛ جزئیاتش در vite.config.ts است. اپ وب آفلاین‌اول است: خواندن و نوشتن مستقیم روی IndexedDB (Dexie) انجام می‌شود و موتورِ همگام‌سازی در پس‌زمینه با سرور آشتی می‌کند.

دستورهای دیگری هم که زیاد به کارتان می‌آید:

npm run build                                # build کل workspace‌ها
npm test --workspace taghvimam-backend       # اجرای تست‌های API (نیازمند DB)
npm run openapi:generate --workspace taghvimam-backend   # بازتولید specِ OpenAPI

مطمئن شوید بالا آمده​

# سلامت API
curl http://localhost:5000/health

# مستندات Swagger
curl http://localhost:5000/api-docs-json     # spec خام
# UI: http://localhost:5000/api-docs

و برای این‌که جریان احراز هویت را هم دستی امتحان کنید:

# ۱) ارسال OTP
curl -X POST http://localhost:5000/api/auth/send-otp \
  -H "Content-Type: application/json" \
  -d '{"phone": "09123456789"}'

# ۲) اعتبارسنجی OTP (کد در محیطِ غیرِ تولید در لاگِ سرور ثبت می‌شود)
curl -X POST http://localhost:5000/api/auth/verify-otp \
  -H "Content-Type: application/json" \
  -d '{"phone": "09123456789", "otp": "123456"}'

# ۳) دسترسی به یک منبعِ محافظت‌شده با token (دلتای همگام‌سازی)
curl -H "Authorization: Bearer <token>" http://localhost:5000/api/sync/changes

جزئیاتِ کاملِ توکن‌ها (access/refresh، مبتنی بر دستگاه) در صفحهٔ احراز هویت آمده است.

استقرار (production)​

cp .env.example .env     # تمام متغیرهای لازم: DATABASE_URL، JWT_*، SYNC_CURSOR_SECRET، …
docker compose up -d --build   # api + web + db + docs

همین سایت مستندات هم از پوشهٔ docs/ (پروژهٔ Docusaurus) build می‌شود و توسط container docs پشت Caddy روی docs.taghvimam.ir سرو می‌شود.

پیش از این‌که واقعاً استقرار بدهید، این چک‌لیست را مرور کنید:

  • رمزهای پیش‌فرض را عوض کرده‌اید.
  • JWT_SECRET و JWT_REFRESH_SECRET قوی و از هم متمایزند.
  • CORS_ORIGIN روی دامنهٔ واقعیِ فرانت‌اند تنظیم شده.
  • HTTPS فعال است (Caddy خودش TLS می‌گیرد، کاری لازم نیست).
  • فقط پورت‌های ضروری expose شده‌اند (API روی ۵۰۰۰).
  • بک‌آپ منظمِ دیتابیس (pg_dump) برقرار است.
  • لاگ‌ها برای فعالیتِ مشکوک پایش می‌شوند.

چند متغیر محیطیِ اختیاری هم هست که فقط وقتی به آن قابلیت‌ها نیاز دارید لازم می‌شوند:

NODE_ENV=production
PORT=5000

# Firebase (برای push notifications)
FIREBASE_PROJECT_ID=...
FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
FIREBASE_CLIENT_EMAIL=...
ENABLE_FIREBASE=true

# Rate limiting
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX_REQUESTS=100

فهرستِ کاملِ متغیرهای ضروری (نه فقط اختیاری‌ها) در صفحهٔ استقرار آمده است.