سند اجرایی برنامه توسعه دیتابیس سرویس پایلوت پروفایل و احراز هویت متارنگ

تحلیل کدبیس مخزن مرکزی Metaverse-Rang-Microservice، طراحی معماری ترکیبی (MySQL + MongoDB Sharded Pods + Redis CQRS) و نقشه راه اجرای پایلوت روی کانتینر auth-service در تراز مقیاس میلیونی

شناسنامه سند و مشخصات اجرایی پایلوت

سرویس و کانتینر هدف پایلوت: metarang-microservices-api-auth-service، با پورت gRPC برابر با 50051 و پورت HTTP برابر با 8066.

مخزن مرجع کدبیس (Monorepo): github.com/iranpsc/Metaverse-Rang-Microservice، مبتنی بر Go 1.22+ Workspace.

دامنه عملکردی سرویس پایلوت: احراز هویت، پروفایل عمومی و خصوصی شهروندان (CitizenProfile)، اطلاعات شخصی، حریم خصوصی، KYC و حساب‌های بانکی.

معماری پایگاه داده هدف (V3.1): معماری ترکیبی (Polyglot) شامل MySQL 8.0 به‌عنوان هسته رابطه‌ای، MongoDB 7.0 Sharded Pods برای داده‌های رمزنگاری‌شده و CQRS، Redis Cluster و MinIO.

شکل ۱: کانتینر فعال سرویس پایلوت (auth-service) در محیط اجرایی که مسئولیت کامل مدیریت پروفایل شهروندان، تنظیمات حریم خصوصی و احراز هویت را بر عهده دارد.

۱. یافته‌های کلیدی از کالبدشکافی ریپازیتوری مرکزی میکروسرویس متارنگ

بررسی دقیق سورس‌کد مخزن مرکزی (Metaverse-Rang-Microservice) نشان می‌دهد که معماری فعلی پروژه بر پایه یک Monorepo به زبان Go (نسخه ۱.۲۲ به بالا با go.work) و ۱۶ میکروسرویس مجزا بنا شده است. مهم‌ترین یافته معماری در خصوص سرویس پروفایل این است که در کدبیس فعلی، میکروسرویس مستقلی تحت عنوان profile-service وجود ندارد؛ بلکه تمامی موجودیت‌ها، ریپازیتوری‌ها و متدهای gRPC مربوط به «پروفایل شهروندی (CitizenProfile)»، «اطلاعات شخصی (personal_infos)»، «تنظیمات حریم خصوصی (settings / privacies)»، «احراز هویت سندی (kycs)»، «حساب‌های بانکی (bank_accounts)» و «محدودیت‌های پروفایل (profile_limitations)» در داخل سرویس services/auth-service پیاده‌سازی شده‌اند.

چرا انتخاب کانتینر auth-service به‌عنوان پایلوت دیتابیس V3 بهترین تصمیم مهندسی است؟

سرویس auth-service در فایل shared/proto/auth.proto پنج سرویس gRPC مجزا شامل AuthService، UserService، CitizenService، KYCService و ProfileLimitationService را میزبانی می‌کند. اجرای پایلوت روی این سرویس امکان می‌دهد تا بدون دستکاری ۱۵ میکروسرویس دیگر، همزمان «پایداری تراکنشی MySQL برای نشست‌ها و قفل‌های امنیتی» و «مهاجرت پروفایل شهروندی به پادهای رمزنگاری‌شده MongoDB و مدل CQRS» در پرترافیک‌ترین نقطه سیستم آزمایش و تثبیت شود.

۱.۱. نقشه فعلی فایل‌ها، جداول MySQL و گلوگاه‌های مقیاس میلیونی در auth-service

در حال حاضر تمامی ۱۳ ریپازیتوری موجود در پوشه services/auth-service/internal/repository/ از طریق پکیج مشترک shared/pkg/db/connection.go به یک دیتابیس واحد MySQL به نام metarang_db متصل می‌شوند. وضعیت فعلی هر بخش از کد و تعارض یا گلوگاه آن در برابر الزامات «سند جامع معماری دیتابیس نسخه ۳ (V3)» به شرح زیر است.

ریپازیتوری citizen_repository.go

جداول فعلی در MySQL (scripts/schema.sql): users، kycs، settings و images.

کوئری‌ها و رفتار فعلی در کدبیس Go: اجرای ۴ کوئری مجزا در GetCitizenByCode و استفاده از شرط WHERE LOWER(code) = LOWER(?).

گلوگاه در مقیاس میلیونی و تعارض با سند V3: اعمال تابع LOWER روی ستون code باعث از کار افتادن ایندکس B-Tree و وقوع Full Table Scan می‌شود؛ همچنین اجرای ۴ کوئری مجزا در هر بازدید صفحه شهروند، MySQL را در ترافیک سئو قفل می‌کند.

ریپازیتوری personal_info_repository.go

جداول فعلی در MySQL: personal_infos.

کوئری‌ها و رفتار فعلی در کدبیس Go: اجرای SELECT و INSERT ... ON DUPLICATE KEY UPDATE روی ستون‌های شغل، تحصیلات، خاطره و علایق.

گلوگاه در مقیاس میلیونی و تعارض با سند V3: تمامی خاطرات (memory)، پیش‌بینی‌ها (prediction)، شیوه حل مسئله و علایق (passions) به صورت متن خام (Plaintext) در MySQL ذخیره می‌شوند که نقض صریح اصل Zero-Trust سند V3 است.

ریپازیتوری settings_repository.go

جداول فعلی در MySQL: settings با ستون JSON به نام privacy.

کوئری‌ها و رفتار فعلی در کدبیس Go: واکشی رشته JSON تنظیمات حریم خصوصی در زمان خواندن پروفایل.

گلوگاه در مقیاس میلیونی و تعارض با سند V3: فقدان تفکیک مخزن نوشتن از مخزن خواندن عمومی (CQRS)؛ فیلتر شدن فیلدهای خصوصی در لایه اپلیکیشن به جای حذف فیزیکی از Public Projection Store انجام می‌شود.

ریپازیتوری kyc_repository.go

جداول فعلی در MySQL: kycs و bank_accounts.

کوئری‌ها و رفتار فعلی در کدبیس Go: نگهداری کد ملی (melli_code)، تاریخ تولد، شماره شبا (shaba_num) و شماره کارت (card_num).

گلوگاه در مقیاس میلیونی و تعارض با سند V3: ذخیره‌سازی اطلاعات هویتی و بانکی به صورت متن شفاف بدون رمزنگاری در حالت سکون (Data-at-Rest) و استفاده از الگوی قدیمی Polymorphic لاراول (bankable_type).

ریپازیتوری account_security_repository.go

جداول فعلی در MySQL: account_securities و otps.

کوئری‌ها و رفتار فعلی در کدبیس Go: مدیریت قفل امنیت حساب شهروندی (unlocked, until, length) و تأیید دو مرحله‌ای (2FA).

گلوگاه در مقیاس میلیونی و تعارض با سند V3: ناهمخوانی اسکیما میان فایل scripts/schema.sql و کوئری‌های کد؛ ستون‌های 2fa_type، 2fa_secret و is_2fa_enabled در اسکیما پایه تعریف نشده‌اند.

پکیج shared/pkg/db/connection.go

جداول فعلی در MySQL: کل دیتابیس metarang_db.

کوئری‌ها و رفتار فعلی در کدبیس Go: تنظیمات پیش‌فرض MaxOpenConns = 25، MaxIdleConns = 5 و ConnMaxLifetime = 5m.

گلوگاه در مقیاس میلیونی و تعارض با سند V3: در ترافیک میلیونی، محدودیت ۲۵ اتصال باز به ازای هر نمونه از auth-service باعث صف انتظار طولانی (Connection Starvation) در فراخوانی‌های ValidateToken می‌شود.

ماژول internal/pubsub/redis_publisher.go

جداول فعلی در MySQL: کانال Redis Pub/Sub با نام user-status.

کوئری‌ها و رفتار فعلی در کدبیس Go: انتشار وضعیت آنلاین/آفلاین با presenceOfflineTTL = 10m و presenceSuppressTTL = 2m.

گلوگاه در مقیاس میلیونی و تعارض با سند V3: استفاده از Pub/Sub معمولی فاقد پایداری پیام (Persistence) است؛ برای همگام‌سازی CQRS و ابطال کش زیر ۱۰۰ میلی‌ثانیه به Redis Streams یا Change Streams نیاز است.

۲. معماری هدف دیتابیس سرویس پایلوت (نسخه ترکیبی V3.1)

بر اساس تحلیل فوق، در برنامه توسعه دیتابیس سرویس پایلوت، به جای حذف کامل MySQL یا انتقال کورکورانه تمام جداول به MongoDB، از «معماری چندپایگاهی تخصصی (Polyglot Persistence)» استفاده می‌شود. در این معماری، داده‌های احراز هویت و امنیت حساب روی MySQL بهینه‌سازی‌شده باقی می‌مانند و داده‌های پروفایل شهروندی، اطلاعات خصوصی و نمایه‌های عمومی سئو به کلاستر شاردشده MongoDB و کش Redis منتقل می‌گردند.

شکل ۲: مقایسه زمان پاسخ‌گویی صدک ۹۹ (P99 Latency) در بار ۱۰٬۰۰۰ درخواست بر ثانیه (چپ) و نحوه توزیع بار IOPS میان لایه‌های ذخیره‌سازی در معماری پایلوت V3.1 (راست).

۲.۱. ماتریس تخصیص موجودیت‌های auth-service به موتورهای ذخیره‌سازی

لایه اول: هسته احراز هویت و امنیت حساب (Auth & Security Core)

موتور پایگاه داده: MySQL 8.0+ همراه با ProxySQL و Read Replica.

جداول تخصیص‌یافته: users، personal_access_tokens، account_securities، otps و profile_limitations.

الگوی دسترسی و مکانیزم امنیتی: استفاده از تراکنش‌های ACID، ایندکس پوششی روی ستون code، قفل زمانی امنیت حساب و کشینگ توکن‌ها در cache_repository.go.

لایه دوم: مخزن نوشتن پادهای رمزنگاری‌شده (Encrypted Write Store)

موتور پایگاه داده: MongoDB 7.0+ Sharded Cluster.

کالکشن‌های تخصیص‌یافته: کالکشن citizen_pods شامل ماژول‌های personal_info، privacy_settings و private_notes.

الگوی دسترسی و مکانیزم امنیتی: رمزنگاری سمت کلاینت با AES-256-GCM؛ کلید مشتق‌شده از Argon2id یا امضای EIP-712؛ شاردینگ ترکیبی هش‌شده بر اساس citizen_id.

لایه سوم: خزانه هویتی و بانکی (KYC & Banking Vault)

موتور پایگاه داده: MySQL 8.0+ با ستون‌های رمزنگاری‌شده و Blind Index.

جداول تخصیص‌یافته: kycs و bank_accounts.

الگوی دسترسی و مکانیزم امنیتی: رمزنگاری پاکتی (AES-256-GCM Envelope Encryption) روی کد ملی و شماره شبا/کارت، به همراه ستون هش HMAC-SHA256 برای یکتاسنجی و جستجوی دقیق.

لایه چهارم: مخزن خواندن عمومی و سئو (Public Projection Store)

موتور پایگاه داده: MongoDB Read Store به همراه Redis Cluster.

کالکشن‌ها و کلیدهای تخصیص‌یافته: کالکشن public_citizen_profiles و کلید کش citizen:pub:{code}.

الگوی دسترسی و مکانیزم امنیتی: سند ازپیش‌تجمیع‌شده (Materialized View) حاوی صرفاً فیلدهای عمومی تأییدشده، برای پاسخ‌گویی زیر ۱۰ میلی‌ثانیه به Next.js SSR/PPR.

لایه پنجم: لایه انجماد داده‌های راکد (Cold Storage Tier)

موتور ذخیره‌سازی: MinIO / Ceph S3 با فشرده‌سازی Zstandard.

باکت تخصیص‌یافته: metarang-cold-pods برای حساب‌های با last_seen بیش از ۹۰ روز.

الگوی دسترسی و مکانیزم امنیتی: انتقال خودکار اسناد citizen_pods کاربران غیرفعال به Object Storage و بازگردانی آنی (Hydration) به محض وقوع رویداد Login.

۳. طراحی دقیق اسکیماها، ایندکس‌ها و اسناد دیتابیس در پایلوت

۳.۱. اسکریپت مایگریشن بهینه‌سازی و رفع نقص‌های MySQL

در گام نخست پایلوت، اسکریپت مایگریشن زیر در مسیر scripts/migrations/2026_10_18_auth_v3_pilot_optimizations.sql اجرا می‌شود تا ضمن رفع مغایرت جدول account_securities، مشکل Full Table Scan روی کد شهروندی (HM-XXXXXXX) و ذخیره‌سازی متن خام در جداول kycs و bank_accounts برطرف گردد.

اسکریپت ۱: مایگریشن بهینه‌سازی MySQL و افزودن ستون‌های رمزنگاری و Blind Index

-- File: scripts/migrations/2026_10_18_auth_v3_pilot_optimizations.sql
-- 1. Fix case-insensitive lookup on users.code (eliminates WHERE LOWER(code) = LOWER(?))
ALTER TABLE `users`
  MODIFY COLUMN `code` VARCHAR(64) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NOT NULL,
  ADD UNIQUE INDEX `idx_users_code_unique` (`code`),
  ADD INDEX `idx_users_referrer_score` (`referrer_id`, `score` DESC),
  ADD INDEX `idx_users_last_seen_cold_tier` (`last_seen`, `id`);

-- 2. Reconcile account_securities schema with account_security_repository.go
ALTER TABLE `account_securities`
  ADD COLUMN `2fa_type` VARCHAR(32) DEFAULT NULL AFTER `last_activity`,
  ADD COLUMN `2fa_secret` VARBINARY(512) DEFAULT NULL AFTER `2fa_type`,
  ADD COLUMN `2fa_recovery_codes` VARBINARY(1024) DEFAULT NULL AFTER `2fa_secret`,
  ADD COLUMN `is_2fa_enabled` TINYINT(1) NOT NULL DEFAULT 0 AFTER `2fa_recovery_codes`,
  ADD UNIQUE INDEX `idx_account_securities_user_unique` (`user_id`);

-- 3. Add Envelope Encryption & Blind Index columns to kycs and bank_accounts
ALTER TABLE `kycs`
  ADD COLUMN `melli_code_hash` CHAR(64) DEFAULT NULL AFTER `melli_code`,
  ADD COLUMN `encrypted_pii_blob` MEDIUMBLOB DEFAULT NULL AFTER `birthdate`,
  ADD COLUMN `encryption_iv` BINARY(12) DEFAULT NULL AFTER `encrypted_pii_blob`,
  ADD UNIQUE INDEX `idx_kycs_melli_code_hash` (`melli_code_hash`),
  ADD UNIQUE INDEX `idx_kycs_user_id_unique` (`user_id`);

ALTER TABLE `bank_accounts`
  ADD COLUMN `shaba_hash` CHAR(64) DEFAULT NULL AFTER `shaba_num`,
  ADD COLUMN `card_hash` CHAR(64) DEFAULT NULL AFTER `card_num`,
  ADD COLUMN `encrypted_bank_blob` BLOB DEFAULT NULL AFTER `card_hash`,
  ADD COLUMN `encryption_iv` BINARY(12) DEFAULT NULL AFTER `encrypted_bank_blob`,
  ADD INDEX `idx_bank_accounts_shaba_hash` (`shaba_hash`);

۳.۲. ساختار کالکشن شاردشده citizen_pods در MongoDB (مخزن نوشتن V3)

مطابق بخش ۵.۱ سند معماری V3 (و با اصلاح کلید شاردینگ از حالت رشته ترتیبی به کلید ترکیبی هش‌شده جهت جلوگیری از تجمع بار روی یک نود)، کالکشن citizen_pods جایگزین جداول personal_infos و settings می‌شود. تنها فیلدهایی که کاربر در تنظیمات حریم خصوصی آن‌ها را عمومی (public) علامت زده در بخش public_cleartext قرار می‌گیرند و کل اطلاعات شخصی در قالب بسته رمزنگاری‌شده AES-256-GCM در encrypted_payload ذخیره می‌شود.

اسکریپت ۲: پیکربندی شاردینگ و ساختار سند پاد رمزنگاری‌شده در کالکشن citizen_pods

// MongoDB Sharding & Index Setup Script (scripts/mongo_init_v3.js)
sh.enableSharding("metarang_v3");

// Compound Hashed Shard Key prevents hot-spots on sequential HM-XXXXXXX IDs
sh.shardCollection(
  "metarang_v3.citizen_pods",
  { "citizen_id": "hashed", "module": 1 }
);

db.citizen_pods.createIndex(
  { "citizen_id": 1, "module": 1 },
  { unique: true, name: "idx_citizen_module_unique" }
);
db.citizen_pods.createIndex(
  { "user_id": 1, "module": 1 },
  { name: "idx_userid_module" }
);
db.citizen_pods.createIndex(
  { "tier_status": 1, "updated_at": 1 },
  { name: "idx_cold_tier_archival" }
);

// Sample Document in metarang_v3.citizen_pods
{
  "_id": ObjectId("673c8f12a4b89e0012ab34cd"),
  "citizen_id": "HM-2000001",
  "user_id": NumberLong(10452),
  "module": "personal_info",
  "schema_version": 3,
  "privacy_flags": {
    "occupation": true,
    "education": true,
    "loved_city": true,
    "loved_country": true,
    "loved_language": true,
    "about": true,
    "memory": false,
    "passions": false,
    "prediction": false,
    "problem_solving": false
  },
  "public_cleartext": {
    "occupation": "معمار سیستم‌های توزیع‌شده",
    "education": "کارشناسی ارشد مهندسی کامپیوتر",
    "loved_city": "تهران",
    "loved_country": "ایران",
    "loved_language": "فارسی",
    "about": "توسعه‌دهنده زیرساخت کلان‌داده متارنگ"
  },
  "encrypted_payload": {
    "ciphertext": "base64_encoded_aes_256_gcm_ciphertext_of_all_private_fields...",
    "iv": "3a7b9c1d2e5f801122334455",
    "auth_tag": "88e2c1b490abcdef1234567890abcdef",
    "algorithm": "AES-256-GCM",
    "kdf_mode": "Argon2id_v1.3|EIP712_HKDF_SHA256",
    "key_fingerprint": "a1b2c3d4e5f60718"
  },
  "tier_status": "HOT",
  "created_at": NumberLong(1727641242),
  "updated_at": NumberLong(1727641242)
}

۳.۳. ساختار کالکشن public_citizen_profiles (مخزن خواندن عمومی CQRS)

در کدبیس فعلی، هر بار که متد gRPC به نام GetCitizenProfile فراخوانی می‌شود، سرویس auth-service چهار کوئری به جداول users، kycs، settings و images در MySQL می‌زند و سپس به سرویس‌های levels-service (پورت 50054) و commercial-service (پورت 50052) درخواست ارسال می‌کند. در معماری V3.1، تمامی این اطلاعات عمومی در کالکشن public_citizen_profiles به صورت یک سند تخت و آماده (Pre-computed Projection) نگهداری می‌شوند تا تنها با ۱ عملیات خواندن زیر ۲ میلی‌ثانیه واکشی گردند.

اسکریپت ۳: ساختار سند مخزن خواندن عمومی (Public Projection Store) جهت صفحات سئو و پروفایل شهروندی

// Collection: metarang_v3.public_citizen_profiles
// Covering Index for instant SEO & Next.js SSR lookups
db.public_citizen_profiles.createIndex(
  { "code_lower": 1 },
  { unique: true, name: "idx_public_code_lower_unique" }
);

{
  "_id": "HM-2000001",
  "code_lower": "hm-2000001",
  "user_id": NumberLong(10452),
  "display_name": "حسین قدیری",
  "kyc_verified_badge": true,
  "citizen_level": 14,
  "score": 168.96,
  "avatars": [
    { "id": 891, "url": "https://storage.rgb.irpsc.com/users/10452/avatar1.webp" }
  ],
  "public_personal_info": {
    "occupation": "معمار سیستم‌های توزیع‌شده",
    "education": "کارشناسی ارشد مهندسی کامپیوتر",
    "loved_city": "تهران",
    "about": "توسعه‌دهنده زیرساخت کلان‌داده متارنگ"
  },
  "referral_stats": {
    "direct_referrals_count": 42,
    "last_updated": NumberLong(1727641000)
  },
  "cache_tag": "citizen-HM-2000001",
  "updated_at": NumberLong(1727641242)
}

۴. الزامات و تغییرات اجرایی در کدهای Go سرویس auth-service

برای پیاده‌سازی معماری فوق در مخزن Metaverse-Rang-Microservice، تغییرات زیر به صورت ماژولار و با حفظ سازگاری کامل با قراردادهای gRPC فعلی (Backward-Compatible) در سرویس auth-service و پکیج shared اعمال می‌گردند.

۱. ارتقای پکیج دیتابیس مشترک (shared/pkg/db/connection.go و mongo.go)

در فایل connection.go مقادیر پیش‌فرض استخر اتصال MySQL برای سرویس‌های پرترافیک از MaxOpenConns=25 به MaxOpenConns=100 و MaxIdleConns=25 (با ConnMaxIdleTime=5m) ارتقا می‌یابد. همچنین فایل جدید shared/pkg/db/mongo.go با درایور رسمی go.mongodb.org/mongo-driver/v2/mongo و استخر اتصالات پیش‌گرم (MinPoolSize=20, MaxPoolSize=200) و فشرده‌سازی Zstandard اضافه می‌شود.

۲. افزودن ریپازیتوری پاد رمزنگاری‌شده (internal/repository/pod_repository.go)

این ریپازیتوری جدید وظیفه درج و به‌روزرسانی اتمیک اسناد در کالکشن citizen_pods و خواندن سریع از کالکشن public_citizen_profiles را بر عهده می‌گیرد و جایگزین کوئری‌های مستقیم به جداول personal_infos و settings می‌شود.

۳. پیاده‌سازی موتور CQRS و ابطال کش زیر ۱۰۰ میلی‌ثانیه در internal/service/observer_service.go

یک گوروتین پایدار (Background Worker) با استفاده از قابلیت Change Streams (متد Watch در MongoDB) تغییرات کالکشن citizen_pods را به صورت بلادرنگ رصد می‌کند. به محض اینکه شهروند در متد UpsertSettings یکی از فیلدهای خود را از حالت Public به Private تغییر دهد، این پردازشگر ظرف کمتر از ۱۰ میلی‌ثانیه فیلد مربوطه را با دستور $unset از کالکشن public_citizen_profiles حذف کرده، کلید کش Redis (citizen:pub:hm-xxxxxxx) را پاک می‌کند و رویداد ابطال کش را با امضای HMAC-SHA256 روی استریم Redis ارسال می‌نماید تا فرانت‌اند Next.js کش صفحه را باطل کند.

۴. مکانیزم آب‌رسانی آنی داده‌های منجمد (Cold Tier Hydration) در internal/service/auth_service.go

در متدهای ورود کاربر (Callback و ValidateToken)، چنانچه وضعیت پاد شهروند در Redis یا ایندکس مختصر برابر با COLD باشد، یک وظیفه اولویت‌دار (High-Priority Hydration) بسته فشرده‌شده Zstandard شهروند را از باکت MinIO/S3 (از طریق کلاینت S3 داخلی یا storage-service) واکشی و بازگشایی کرده و مجدداً در کالکشن citizen_pods درج می‌کند.

نمونه کد ۴: پیاده‌سازی حلقه همگام‌سازی بلادرنگ CQRS و ابطال کش در observer_service.go

// File: services/auth-service/internal/service/observer_service.go (CQRS Privacy Sync Engine)
func (o *ObserverService) WatchCitizenPodsCQRS(ctx context.Context) error {
    pipeline := mongo.Pipeline{
        bson.D{{Key: "$match", Value: bson.D{
            {Key: "operationType", Value: bson.D{{Key: "$in", Value: bson.A{"insert", "update", "replace"}}}},
        }}},
    }
    opts := options.ChangeStream().SetFullDocument(options.UpdateLookup)
    stream, err := o.mongoDB.Collection("citizen_pods").Watch(ctx, pipeline, opts)
    if err != nil {
        return fmt.Errorf("failed to open citizen_pods change stream: %w", err)
    }
    defer stream.Close(ctx)

    for stream.Next(ctx) {
        var event CitizenPodChangeEvent
        if err := stream.Decode(&event); err != nil {
            continue
        }
        doc := event.FullDocument
        // 1. Project ONLY verified public_cleartext fields into public_citizen_profiles
        update := bson.D{{Key: "$set", Value: bson.D{
            {Key: "public_personal_info", doc.PublicCleartext},
            {Key: "updated_at", time.Now().Unix()},
        }}}
        _, _ = o.mongoDB.Collection("public_citizen_profiles").UpdateOne(
            ctx, bson.D{{Key: "_id", Value: doc.CitizenID}}, update, options.Update().SetUpsert(true),
        )
        // 2. Invalidate Redis Read Cache & Queue Debounced HMAC Revalidation Event for Next.js
        cacheKey := fmt.Sprintf("citizen:pub:%s", strings.ToLower(doc.CitizenID))
        _ = o.redisClient.Del(ctx, cacheKey).Err()
        _ = o.publishRevalidateStream(ctx, doc.CitizenID)
    }
    return stream.Err()
}

۵. نقشه راه ۴ مرحله‌ای اجرای پایلوت و مهاجرت بدون قطعی (Zero-Downtime Rollout)

از آنجا که کانتینر auth-service در حال حاضر در محیط عملیاتی فعال است (Up & Healthy)، مهاجرت دیتابیس نباید هیچ‌گونه اختلالی در ورود کاربران یا نمایش صفحات پروفایل ایجاد کند. به همین منظور، فرآیند گذار با الگوی مهندسی Dual-Write / Shadow-Read در ۴ فاز هفتگی اجرا می‌شود.

فاز ۱: بهینه‌سازی MySQL و برپایی هسته MongoDB

بازه زمانی: هفته اول.

اقدامات عملیاتی در دیتابیس و کدهای auth-service: اجرای مایگریشن ایندکس users.code و اصلاح جدول account_securities؛ حذف تابع LOWER از citizen_repository.go؛ راه‌اندازی کلاستر شاردشده MongoDB و افزودن پکیج shared/pkg/db/mongo.go.

معیار پذیرش و گیت کنترل کیفی (KPI / Exit Gate): کاهش زمان اجرای کوئری GetCitizenByCode در MySQL از ۱۴۰ میلی‌ثانیه به زیر ۲ میلی‌ثانیه؛ برقراری استخر اتصال پایدار به MongoDB.

فاز ۲: نوشتن دوگانه (Dual-Write) و مهاجرت داده‌های قبلی

بازه زمانی: هفته دوم.

اقدامات عملیاتی در دیتابیس و کدهای auth-service: اصلاح personal_info_service.go و settings_service.go برای نوشتن همزمان در MySQL و کالکشن citizen_pods؛ اجرای اسکریپت Backfill برای انتقال رکوردهای فعلی جداول personal_infos و settings به MongoDB.

معیار پذیرش و گیت کنترل کیفی (KPI / Exit Gate): برابری ۱۰۰ درصدی تعداد رکوردها و هش داده‌های عمومی میان جداول MySQL و کالکشن‌های citizen_pods و public_citizen_profiles.

فاز ۳: فعال‌سازی CQRS و سوئیچ خواندن عمومی (Shadow-Read -> Cutover)

بازه زمانی: هفته سوم.

اقدامات عملیاتی در دیتابیس و کدهای auth-service: فعال‌سازی پردازشگر Change Stream در observer_service.go؛ تغییر مسیر متد GetCitizenProfile به خواندن از کش Redis و کالکشن public_citizen_profiles؛ اتصال وب‌هوک HMAC به Next.js.

معیار پذیرش و گیت کنترل کیفی (KPI / Exit Gate): کاهش زمان پاسخ‌گویی متد gRPC GetCitizenProfile به زیر ۱۰ میلی‌ثانیه (P99)؛ تأیید پاکسازی آنی فیلدهای خصوصی‌شده از خروجی Next.js در کمتر از ۱۰۰ میلی‌ثانیه.

فاز ۴: رمزنگاری کلاینت (Zero-Knowledge)، انجماد سرد و تست بار k6

بازه زمانی: هفته چهارم.

اقدامات عملیاتی در دیتابیس و کدهای auth-service: ارتقای shared/proto/auth.proto برای دریافت بسته رمزنگاری‌شده AES-256-GCM از کلاینت؛ رمزنگاری پاکتی جداول kycs و bank_accounts؛ فعال‌سازی آرشیو ۹۰ روزه به MinIO و اجرای تست بار k6.

معیار پذیرش و گیت کنترل کیفی (KPI / Exit Gate): تحمل بار ۱۰٬۰۰۰ درخواست همزمان در ثانیه (RPS) روی auth-service با نرخ خطای صفر درصد، مکث GC زیر ۵ میلی‌ثانیه و حذف کامل داده‌های شخصی متن خام از دیسک.

۶. فهرست دقیق فایل‌های نیازمند تغییر یا ایجاد در مخزن گیت‌هاب

تیم توسعه بک‌اند (Go) و DevOps برای اجرای کامل این برنامه پایلوت باید دقیقاً ۱۰ فایل زیر را در مخزن مرکزی Metaverse-Rang-Microservice ایجاد یا ویرایش نمایند.

۱. مسیر: scripts/migrations/2026_10_18_auth_v3_pilot_optimizations.sql

نوع تغییر: ایجاد فایل جدید.

شرح دقیق تغییرات مهندسی: مایگریشن اصلاح Collation و ایندکس ستون code در جدول users، افزودن ستون‌های 2FA به account_securities و ستون‌های رمزنگاری/Blind Index به kycs و bank_accounts.

۲. مسیر: scripts/mongo_init_v3.js

نوع تغییر: ایجاد فایل جدید.

شرح دقیق تغییرات مهندسی: اسکریپت راه‌اندازی شاردینگ ترکیبی هش‌شده روی کالکشن citizen_pods و ایجاد ایندکس‌های پوششی روی کالکشن public_citizen_profiles.

۳. مسیر: shared/pkg/db/connection.go