TorbatYar/docs/progress.md

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

## فاز ۱ — Core Platform ✅

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

### سرویس هسته (core-service)
- [x] پیکربندی، دیتابیس، cache، logging، security پایه
- [x] مدل‌ها، APIها، Entitlement، Celery، Outbox
- [x] تست‌ها و مستندات

### Frontend
- [x] Next.js مستقل، API Client، White-label theme

---

## فاز ۲ — Identity & Access + SSO ✅

### shared-lib
- [x] `shared/auth/jwt.py` — JWTValidator مشترک
- [x] `shared/auth/roles.py` — نقش‌های استاندارد پلتفرم
- [x] رویدادهای Identity در `shared/events.py`

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

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

### محافظت APIهای Core
- [x] `AUTH_REQUIRED` قابل تنظیم از env
- [x] `require_platform_admin`, `require_tenant_admin`, `require_authenticated`
- [x] اعمال روی همه endpointهای مدیریتی

### Frontend SSO
- [x] `lib/auth.ts` — OIDC flow
- [x] صفحات `/login`, `/auth/callback`, `/dashboard`
- [x] `AuthGuard` و `useAuth` hook
- [x] API Client با Bearer token

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

### مستندات
- [x] architecture.md (بخش SSO فاز ۲)
- [x] database_schema.md (identity_access_db)
- [x] services_contracts.md (APIهای Identity)
- [x] progress.md, last_step.md

---

## فاز ۳ — OTP Login + Tenant Management ✅

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

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

### تست‌ها
- [x] `test_otp_auth.py` — OTP flow و tenant با JWT

### مستندات
- [x] architecture.md (بخش OTP)
- [x] progress.md, last_step.md
- [x] `.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)
- [x] مدل `TenantMembership` + جدول `tenant_memberships` (نقش/وضعیت/owner)
- [x] چرخهٔ عمر tenant: `draft` / `pending_activation` / `active` /
      `suspended` / `archived`
- [x] پروفایل/برندینگ روی `tenants`: `business_type`, `default_locale`,
      `timezone`, `primary_color`, `secondary_color`, `logo_url`,
      `favicon_url`, `onboarding_completed`
- [x] `domains.is_primary` و `domains.verification_status`
- [x] `users.current_tenant_id` (tenant انتخاب‌شده جاری)
- [x] Seed پلن‌های پیش‌فرض `FREE`/`STARTER` (migration + `ensure_default_plan`)
- [x] `UserService.resolve_current` — یکپارچه‌سازی resolve کاربر Core از JWT
      محلی (OTP) یا JWT کیکلوک (SSO، بر اساس `keycloak_sub`)
- [x] `MembershipService` — عضویت owner، لیست عضویت‌ها، `ensure_role`
      (authorization سبک با bypass برای `platform_admin`)
- [x] `OnboardingService` — ایجاد tenant، برندینگ، دامنه، تکمیل/فعال‌سازی
- [x] `TenantContextService` — ساخت `TenantContextRead` کامل برای frontend
- [x] 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`
- [x] Migration `0005_tenant_onboarding` (ستون‌ها، جدول جدید، seed پلن‌ها)
- [x] `PLATFORM_BASE_DOMAIN` در config برای تخصیص خودکار زیردامنه

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

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

### زیرساخت
- [x] `PLATFORM_BASE_DOMAIN` در `.env` و `.env.example`

### مستندات
- [x] architecture.md (بخش ۱۱ — فاز ۴)
- [x] database_schema.md (`tenant_memberships` جدید Core، ستون‌های جدید
      `tenants`/`domains`/`users`، توضیح تمایز با جدول هم‌نام Identity)
- [x] services_contracts.md (بخش ۷ — Onboarding و Tenant Context)
- [x] 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