تحویل OTP و عملیات Development

Adapter فعلی OTP را فقط برای توسعه و Test در Structured Log می‌نویسد. این Adapter ابزار Debug است و در Staging یا Production Fail-closed می‌شود.

Configuration

متغیر	Development/Test	Staging/Production
OTP_DELIVERY_MODE=log	مجاز	ممنوع
OTP_HMAC_PEPPER	مجاز برای Local	ممنوع
OTP_HMAC_PEPPER_FILE	مجاز	مسیر ترجیحی Secret

اگر Pepper در Development تنظیم نشده باشد، Process یک Pepper موقت می‌سازد. Restart در این حالت Challengeهای قبلی را غیرقابل تایید می‌کند؛ برای Flow چندمرحله‌ای Local باید Pepper پایدار و ساختگی در .env قرار گیرد.

اجرای محلی

Copy-Item .env.example .env
go run ./cmd/api

Migrationهای Pending پیش از Listener اجرا می‌شوند. Event لاگ Development با نام development_otp_generated شامل OTP و Mobile Maskشده است. این Log فقط روی سیستم توسعه امن خوانده می‌شود و نباید در Screenshot، Issue یا CI Artifact منتشر شود.

Swagger UI در http://localhost:8080/docs/ و Contract خام در http://localhost:8080/openapi.yaml در دسترس‌اند.

جایگزینی با ملی‌پیامک

Adapter ملی‌پیامک باید Interface OTPDeliverer را پیاده کند تا Application و Domain تغییر نکنند. قبل از فعال‌سازی:

1. Credential از Secret File یا Secret Manager خوانده شود.
2. Request Timeout، Response Mapping و Error Classification تعریف شود.
3. Transactional Outbox و Worker تحویل پایدار اضافه شود.
4. Provider Message ID بدون OTP و Mobile کامل Audit شود.
5. Retry فقط برای خطاهای گذرا و با Backoff و Jitter باشد.
6. Cost، Delivery Latency، Failure Rate و Duplicate Delivery Metric داشته باشند.
7. Contract و Runbook Provider با Test Sandbox تایید شوند.

معیار حذف Adapter موقت

پس از موفقیت End-to-end ملی‌پیامک در محیط غیر Production، وجود log به Development/Test محدود می‌ماند و Composition محیط‌های دیگر فقط Adapter واقعی را می‌پذیرد. هیچ Fallback خودکار از SMS به Log مجاز نیست.