TorbatYar/docs/progress.md

پیشرفت پروژه (Progress)

فاز ۱ — Core Platform ✅

زیرساخت و ساختار

• ساختار کامل پروژه با جداسازی اجباری backend/ و frontend/
• کتابخانه مشترک backend/shared-lib
• بخش ۲.۱ معماری: Frontend & Backend Separation

سرویس هسته (core-service)

• پیکربندی، دیتابیس، cache، logging، security پایه
• مدل‌ها، APIها، Entitlement، Celery، Outbox
• تست‌ها و مستندات

Frontend

• Next.js مستقل، API Client، White-label theme

---

فاز ۲ — Identity & Access + SSO ✅

shared-lib

• shared/auth/jwt.py — JWTValidator مشترک
• shared/auth/roles.py — نقش‌های استاندارد پلتفرم
• رویدادهای Identity در shared/events.py

Identity & Access Service

• سرویس مستقل در backend/services/identity-access/
• دیتابیس identity_access_db (database-per-service)
• مدل‌ها: UserProfile, TenantMembership
• Keycloak Admin Client + token exchange (BFF)
• APIها: /auth/config, /auth/token, /auth/me, /users, /tenants/{id}/members
• Alembic migration + Dockerfile
• تست‌های پایه

Keycloak

• Realm import: infrastructure/keycloak/realm/superapp-realm.json
• Clients: superapp-frontend, core-service, identity-access-service
• نقش‌ها و کاربر admin نمونه
• docker-compose با --import-realm

محافظت APIهای Core

• AUTH_REQUIRED قابل تنظیم از env
• require_platform_admin, require_tenant_admin, require_authenticated
• اعمال روی همه endpointهای مدیریتی

Frontend SSO

• lib/auth.ts — OIDC flow
• صفحات /login, /auth/callback, /dashboard
• AuthGuard و useAuth hook
• API Client با Bearer token

زیرساخت

• identity-access-service در docker-compose (پورت 8001)
• frontend در docker-compose (پورت 3000، dev + hot-reload)
• ارتقای Next.js به 15.5.18 (پچ امنیتی — نسخه 14 دیگر پشتیبانی امنیتی ندارد)
• infrastructure/postgres/init-dbs.sql برای ساخت identity_access_db
• به‌روزرسانی .env.example

مستندات

• architecture.md (بخش SSO فاز ۲)
• database_schema.md (identity_access_db)
• services_contracts.md (APIهای Identity)
• progress.md, last_step.md

---

فاز ۳ — OTP Login + Tenant Management ✅

Backend (core-service)

• مدل users و migration Alembic (0002_users)
• OTP request/verify: /api/v1/auth/otp/request, /api/v1/auth/otp/verify
• ثبت‌نام خودکار کاربر + audit log
• یکپارچگی Payamak-Panel SendOtp
• JWT محلی (HS256) برای کاربران OTP
• Admin Tenant CRUD: /api/v1/admin/tenants با owner mapping
• فیلتر لیست tenant بر اساس مالک (Platform Admin: همه / Tenant Admin: فقط مالک)

Frontend

• lib/api.ts — API Client یکپارچه با Bearer token
• /admin/login — جریان OTP دو مرحله‌ای با countdown
• /admin/tenants — داشبورد لیست tenant
• /admin/tenants/new — فرم ایجاد tenant

تست‌ها

• test_otp_auth.py — OTP flow و tenant با JWT

مستندات

• architecture.md (بخش OTP)
• progress.md, last_step.md
• .env.example (Payamak + NEXT_PUBLIC_BACKEND_URL)

---

فاز ۴ — Tenant Onboarding و Workspace Activation ✅

در بریف پروژه این فاز با عنوان «Phase 3: operationalizing tenant onboarding and workspace activation» معرفی شده است. چون در شماره‌گذاری داخلی این سند «فاز ۳» قبلاً به OTP Login + Tenant Management اختصاص یافته بود، این تحویل به‌عنوان فاز ۴ ثبت می‌شود (محتوا دقیقاً همان «Phase 3» بریف است).

Backend (core-service)

• مدل TenantMembership + جدول tenant_memberships (نقش/وضعیت/owner)
• چرخهٔ عمر tenant: draft / pending_activation / active / suspended / archived
• پروفایل/برندینگ روی tenants: business_type, default_locale, timezone, primary_color, secondary_color, logo_url, favicon_url, onboarding_completed
• domains.is_primary و domains.verification_status
• users.current_tenant_id (tenant انتخاب‌شده جاری)
• Seed پلن‌های پیش‌فرض FREE/STARTER (migration + ensure_default_plan)
• UserService.resolve_current — یکپارچه‌سازی resolve کاربر Core از JWT محلی (OTP) یا JWT کیکلوک (SSO، بر اساس keycloak_sub)
• MembershipService — عضویت owner، لیست عضویت‌ها، ensure_role (authorization سبک با bypass برای platform_admin)
• OnboardingService — ایجاد tenant، برندینگ، دامنه، تکمیل/فعال‌سازی
• TenantContextService — ساخت TenantContextRead کامل برای frontend
• APIهای جدید: GET /me, GET /me/tenants, POST /onboarding/tenant, PATCH /onboarding/tenant/{id}/branding, PATCH /onboarding/tenant/{id}/domain, POST /onboarding/tenant/{id}/complete, GET /tenant/current, POST /tenant/switch
• Migration 0005_tenant_onboarding (ستون‌ها، جدول جدید، seed پلن‌ها)
• PLATFORM_BASE_DOMAIN در config برای تخصیص خودکار زیردامنه

تست‌ها

• app/tests/test_onboarding.py — جریان کامل onboarding (ساخت tenant، برندینگ، دامنه، تکمیل، /me, /tenant/current, /tenant/switch) + حالات forbidden/duplicate/owner-required
• کل test suite موجود (test_otp_auth, test_tenants, test_domains, ...) بدون رگرسیون اجرا شد

Frontend

• lib/api.ts — انواع و متدهای api.me, api.onboarding, api.tenantContext (بدون تغییر ساختار قبلی api.tenants/api.auth)
• hooks/useMe.ts — بارگذاری /api/v1/me
• app/onboarding/page.tsx — ویزارد تک‌صفحه‌ای ۴ مرحله‌ای (کسب‌وکار → برندینگ → دامنه → بازبینی) با قابلیت ازسرگیری onboarding ناتمام
• app/dashboard/page.tsx — داشبورد واقعی workspace (نام، وضعیت، پلن، دامنه، وضعیت onboarding، نقش کاربر) + redirect خودکار به /onboarding در صورت نیاز
• components/TenantSwitcher.tsx — سوییچر ساده (فقط با بیش از یک عضویت نمایش داده می‌شود)
• Type-check تمیز (tsc --noEmit)

زیرساخت

• PLATFORM_BASE_DOMAIN در .env و .env.example

مستندات

• architecture.md (بخش ۱۱ — فاز ۴)
• database_schema.md (tenant_memberships جدید Core، ستون‌های جدید tenants/domains/users، توضیح تمایز با جدول هم‌نام Identity)
• services_contracts.md (بخش ۷ — Onboarding و Tenant Context)
• progress.md, last_step.md

محدودیت‌های شناخته‌شده (عمداً خارج از این فاز)

• درگاه پرداخت واقعی برای اشتراک (فقط ساختار provisioning پیاده شده)
• تأیید واقعی دامنهٔ اختصاصی (DNS/TXT) — فعلاً فقط pending
• tenantهای ساخته‌شده از مسیر قدیمی POST /admin/tenants عضویت/پلن خودکار نمی‌گیرند (آن مسیر به فاز ۱/۲ تعلق دارد و در این فاز بازنویسی نشده)
• JIT provisioning کامل کاربر Core از JWT کیکلوک (کاربر SSO بدون رکورد Core فعلاً خطای forbidden می‌گیرد)

فازهای بعدی (Backlog)

• پیاده‌سازی اولین ماژول بیزینسی واقعی (نگاه کنید به last_step.md)
• White-label runtime rendering (تشخیص tenant از دامنه + اعمال برند در frontend)
• JIT provisioning کامل کاربر Core از SSO کیکلوک
• Permission management پیشرفته (نقش‌های سفارشی، دعوت اعضا)
• تأیید واقعی دامنهٔ اختصاصی (DNS/TXT) و درگاه پرداخت
• Subscription & Entitlement به‌عنوان سرویس مستقل
• Message bus واقعی برای انتشار رویدادها
• Reverse proxy (Nginx/Traefik) و TLS