سند اجرایی و معماری عملیاتی: استقرار ایجنت هوشمند Jules، پایپ‌لاین جامع CI/CD و خودکارسازی تضمین کیفیت (QA) و امنیت

. چکیده مدیریتی و هدف استراتژیک (Executive Summary)

در مقیاس فعلی پلتفرم ملی متارنگ که شامل بیش از ۶۰ صفحه مستقل، هزاران کامپوننت پویا، ساختارهای چندزبانه با ده‌ها هزار کلیدواژه و ماژول‌های تعاملی سه‌بعدی است، اتکا به بررسی انسانی پس از هر انتشار به یک گلوگاه عملیاتی تبدیل شده است. در حال حاضر، حدود ۷۰٪ ساختار پروژه فرانت‌اند داینامیک بوده و داده‌های خود را به صورت زنده از APIها دریافت می‌کند؛ موضوعی که باعث شده بررسی دستی صحت نمایش داده‌ها، تست تمام ورودی‌ها (Inputs)، ممیزی دقیق سئو (شامل شمارش کاراکترهای عنوان و توضیحات متا)، اسکیما (Schema)، شاخص‌های عملکرد (Performance) و دسترسی‌پذیری (Accessibility) بیش از ۸ ساعت زمان مدیریتی و مهندسی را در هر چرخه توسعه به خود اختصاص دهد.

این سند اجرایی، نقشه راه صفر تا صد اتصال ایجنت هوشمند کدنویسی Jules و پیاده‌سازی زیرساخت CI/CD خودکار را بر روی برنچ dev ریپازیتوری Metaverse-Rang-Front-NextJS تدوین می‌کند. هدف این طرح، اجرای موازی استانداردهای تست و امنیت در کنار تسک «کشینگ چندسطحی و معماری PPR»، کاهش زمان بررسی انسانی از ۸ ساعت به صفر دقیقه در مرحله تست (و تنها چند دقیقه بررسی نهایی Pull Request) و خلق یک الگوی استاندارد (Blueprint) برای استقرار سریع در ۳۵ ریپازیتوری دیگر سازمان است.

۲. معماری حاکمیت گیت، جریان کاری Jules و جداسازی محیط‌ها

از آنجا که تمامی ریپازیتوری‌ها فعال و در حال توسعه مستمر هستند و ادغام در برنچ اصلی منجر به استقرار خودکار در محیط پروداکشن می‌شود، چرخه فعالیت Jules تحت یک پروتکل کنترل‌شده چهارمرحله‌ای تعریف می‌گردد:

1. نقطه اتصال و برنچ هدف (Target Base Branch):
   • ایجنت Jules صرفاً به برنچ dev متصل می‌شود و هیچ‌گونه دسترسی مستقیم برای کامیت یا مرج روی برنچ main نخواهد داشت.
   • به ازای هر ماژول یا تسک (تست‌نویسی، رفع باگ امنیتی، یا پیاده‌سازی کشینگ)، Jules یک برنچ فرعی ایزوله (مانند jules/test-seo-validators یا jules/sec-cache-hmac) از روی dev منشعب کرده و خروجی را در قالب Pull Request (PR) به مقصد dev ارسال می‌کند.
2. محیط اجرای ایزوله و استانداردسازی .env.example:
   • برای اینکه Jules بتواند در محیط Sandbox خود پروژه را بدون نیاز به کلیدهای واقعی پروداکشن بیلد و تست کند، فایل .env.example در ریشه برنچ dev ایجاد می‌شود.
   • مطابق الزامات امنیتی معماری مرجع، متغیرهای حساس و کلیدهای ارتباطی بین‌سرویسی هرگز در متغیرهای دارای پیشوند NEXT_PUBLIC_ قرار نمی‌گیرند.
   • متغیرهای محیطی تست شامل آدرس سرویس داخلی Go (INTERNAL_GO_SERVICE_URL)، توکن سرویس داخلی (INTERNAL_SERVICE_KEY) و کلید مشترک رمزنگاری ابطال کش (HMAC-SHA256 Secret) با مقادیر Mock استاندارد در .env.example تعریف می‌شوند تا Jules بتواند جریان داده را شبیه‌سازی کند.
3. دروازه بررسی انسانی و استقرار (Human-in-the-Loop & CD):
   • پس از ارسال PR توسط Jules به برنچ dev، پایپ‌لاین GitHub Actions به صورت خودکار تمام تست‌های واحد، یکپارچه‌سازی، سئو، پرفرمنس و امنیت را اجرا می‌کند.
   • تنها پس از سبز شدن تمامی چک‌های اتوماتیک، تیم فنی و مدیریت گیت‌هاب کد را بازبینی (Code Review) و در dev ادغام می‌کنند.
   • مرج نهایی از dev به main منحصراً توسط انسان انجام شده و بلافاصله فرآیند استقرار خودکار (Auto-Deploy) روی سرورهای پروداکشن آغاز می‌گردد.

۳. همگام‌سازی موازی با معماری کشینگ چندسطحی و رندرینگ ترکیبی (PPR)

اجرای این پروژه به صورت موازی با تسک کشینگ فرانت‌اند پیش می‌رود تا Jules در حین بازآرایی کدها، تست‌های مربوط به معماری جدید را نیز بنویسد و صحت آن‌ها را تضمین کند:

• تفکیک کامپوننت‌های سرور و کلاینت (RSC vs. Client Components):
  • کامپوننت‌های سرور (RSC) بدون ارسال جاوااسکریپت اضافه به مرورگر، وظیفه ارتباط با میکروسرویس‌های Go، واکشی داده‌های سنگین و پردازش متون را بر عهده می‌گیرند.
  • کامپوننت‌های کلاینت ('use client') صرفاً به برگ‌های پایانی درخت DOM (جاهایی که به رویدادهایی نظیر onClick، onChange، هوک‌های useState و useEffect یا وب‌سوکت نیاز است) محدود می‌شوند.
  • Jules موظف است در تمام ۶۰+ صفحه، مرزهای تعلیق (Suspense Boundaries) و اسکلت‌های بارگذاری (مانند SkeletonStats) را پیاده‌سازی و تست کند تا پوسته استاتیک صفحه (PropertyStaticShell) بلافاصله رندر شده و داده‌های پویا (DynamicFinancialStats) به صورت استریم ناهمگام دریافت شوند.
• تست و پیاده‌سازی خط لوله ابطال کش مبتنی بر تگ (Tag-Based Cache Invalidation):
  • در توابع واکشی داده (نظیر getPropertyData)، درخواست‌ها با هدر X-Internal-Token و تگ‌های مفهومی دقیق (مانند property-${propertyId}، properties-list و global-catalog) به همراه کش ۲۴ ساعته (revalidate: 86400) علامت‌گذاری می‌شوند.
  • Jules تست‌های یکپارچه‌سازی درگاه ابطال کش (POST /api/v1/revalidate) را می‌نویسد تا اطمینان حاصل شود که با شلیک وب‌هوک امضاشده از سمت میکروسرویس Go، تابع revalidateTag دقیقاً کلید مربوطه را در فایل‌سیستم یا حافظه Redis باطل و نوسازی می‌کند.
• مهندسی دیکشنری‌های چندزبانه افرازشده (Chunked i18n Dictionaries):
  • به جای ارسال فایل‌های حجیم ترجمه به کلاینت که راندمان مرورگر را کاهش می‌دهد، دیکشنری‌ها در سطح سرور به فضاهای نام مجزا شامل common.json (هدر، فوتر، منو و احراز هویت)، properties.json (مشخصات املاک، تراکم، ابزارها و رنگ‌ها)، governance.json (حد تأثیر، شوراهای داوری، رأی‌گیری و کتاب قانون) و metaverse3d.json (روم‌ها، تنظیمات شبکه، کنترل‌های گرافیکی و وب‌سوکت) تفکیک می‌شوند.
  • Jules با اعمال ماژول server-only در getDictionary.ts و نوشتن تست‌های مربوط به تگ ابطال زنده i18n-fa-properties از کش Redis، صحت بارگذاری سمت سرور ترجمه‌ها را تضمین می‌کند.
• استانداردسازی بارگذاری تنبل (Lazy Loading) ماژول‌های سه‌بعدی:
  • برای جلوگیری از پدیده Long Tasks و قفل شدن نخ اصلی جاوااسکریپت در هنگام لود نقشه‌های سه‌بعدی، چت سوکت و نمودارهای تاریخچه دارایی‌ها، کامپوننت‌های سنگین مبتنی بر Three.js و WebGL با next/dynamic (با تنظیم ssr: false) و هوک useInView (با حاشیه دید rootMargin: '200px 0px' و triggerOnce: true) ایزوله می‌شوند.

۴. معماری پایپ‌لاین خودکار تست و تضمین کیفیت (جایگزین ۸ ساعت بررسی دستی)

برای حذف کامل بررسی دستی صفحات، ورودی‌ها، سئو و داده‌های داینامیک، پایپ‌لاین CI/CD در GitHub Actions بر روی ۴ ستون خودکار بنا می‌شود که Jules وظیفه نوشتن اسکریپت‌های تست آن‌ها را بر عهده دارد:

۴.۱. موتور ممیزی خودکار سئو، شمارش کاراکترها و اسکیما (Automated SEO & Schema Gate)

به جای بررسی چشمی تک‌به‌تک صفحات، یک سوئیت تست مبتنی بر Playwright طراحی می‌شود که به صورت خودکار تمام مسیرهای ایستا و داینامیک (بیش از ۶۰ صفحه شامل داشبوردهای شهروندی، املاک تجاری قرمز، مسکونی زرد، آموزشی آبی، سامانه‌های رأی‌گیری و تحلیل توکن‌های PSC و PSD) را پیمایش می‌کند:

• کنترل دقیق طول کاراکترهای <title>: بررسی خودکار وجود تگ عنوان در تمام صفحات و زبان‌ها و اطمینان از قرارگیری تعداد کاراکترها در بازه استاندارد سئو (مثلاً بین ۳۰ تا ۶۰ کاراکتر؛ در صورت تخطی حتی در یک صفحه، بیلد CI متوقف شده و صفحه خاطی گزارش می‌شود).
• کنترل دقیق <meta name="description">: بررسی عدم تکرار، عدم خالی بودن و شمارش دقیق کاراکترهای توضیحات متا (بازه استاندارد ۱۲۰ تا ۱۵۵ کاراکتر) در صفحات داینامیک.
• اعتبارسنجی ساختار JSON-LD Schema و OpenGraph: پارس کردن خودکار اسکریپت‌های application/ld+json در هر صفحه و تطبیق فیلدهای اجباری آن با استانداردهای Schema.org به همراه بررسی تگ‌های canonical و hreflang.

۴.۲. دروازه شاخص‌های حیاتی وب، پرفرمنس و دسترسی‌پذیری (Lighthouse CI Gate)

راه‌اندازی Google Lighthouse CI روی GitHub Actions که در هر Pull Request صفحات نمونه را رندر کرده و قوانین زیر را به صورت خودکار بررسی می‌کند:

• ممیزی ۴ شاخص اصلی: الزام به کسب امتیاز بالای ۹۰ تا ۱۰۰ در معیارهای SEO، Accessibility (دسترسی‌پذیری)، Best Practices (بهترین شیوه‌ها) و Performance.
• تضمین اهداف زمانی معماری مرجع: بررسی خودکار زمان پاسخ اولیه پوسته ایستا (TTFB در حدود ۵۰ میلی‌ثانیه)، بارگذاری اسکلت صفحه و ابرداده‌های سئو در زیر ۳۰۰ میلی‌ثانیه (FCP/TTI) و رسیدن به بارگذاری اولیه زیر ۱۰۰ میلی‌ثانیه در صفحات کش‌شده.

۴.۳. تست صحت انتشار ۷۰٪ داده‌های داینامیک و قراردادهای API (API Contract & Integration Testing)

از آنجا که ۷۰٪ پروژه داینامیک است و اطلاعات را از میکروسرویس‌های هسته Go و لایه گذرگاه Envoy Proxy / Go Gateway دریافت می‌کند، Jules با استفاده از Vitest، React Testing Library و MSW (Mock Service Worker) موارد زیر را پوشش می‌دهد:

• تست صحت رندر داده‌های دریافتی (Data Rendering Integrity): شبیه‌سازی پاسخ‌های API برای قیمت‌های لحظه‌ای دارایی‌ها، موجودی کیف پول‌ها، تراکنش‌های PSC/PSD و مشخصات املاک و بررسی اینکه مقادیر دریافتی از JSON دقیقاً و بدون تغییر، خطا یا undefined در DOM نهایی منتشر می‌شوند.
• تست مقاومت در برابر خطای API (Resilience & Fallback): بررسی رفتار مرزهای Suspense و Error Boundary در زمان تأخیر یا قطع ارتباط با بک‌اند Go تا صفحه کرش نکرده و اسکلتون یا پیام استاندارد نمایش داده شود.

۴.۴. تست خودکار تمامی ورودی‌ها، فرم‌ها و تعاملات کاربری (Automated UI & Input Testing)

برای حذف تست دستی فرم‌ها و اینپوت‌ها، Jules برای تمامی کامپوننت‌های دارای 'use client' تست‌های تعاملی می‌نویسد:

• تست اعتبارسنجی (Validation) تمام فیلدهای ورودی، فرم‌های جستجو، فیلترهای املاک، فرم‌های رأی‌گیری، حد تأثیر و مودال‌های شهروندی.
• تست سناریوهای ورودی مرزی (مقادیر خالی، کاراکترهای غیرمجاز، اعداد منفی در تراکنش‌ها و رشته‌های بسیار طولانی) و اطمینان از عملکرد صحیح دکمه‌ها و رویدادهای onClick و onChange.

۵. ماتریس تست‌های امنیتی خودکار (منطبق بر استانداردهای افتا، OWASP ASVS و ISO/IEC 27034)

مطابق الزامات امنیتی پروژه‌های با مقیاس ملی و دستورالعمل‌های مرکز افتا، استانداردهای خانواده ISO/IEC 27034 و OWASP ASVS، لایه امنیتی پایپ‌لاین و تست‌های Jules شامل ۴ محور زیر خواهد بود:

1. ممیزی خودکار مرز داده و عدم نشت کلیدها (Secret & Boundary Leak Prevention):
   • اسکن خودکار کدها در CI برای اطمینان از اینکه هیچ‌یک از کلیدهای ارتباطی بین‌سرویسی یا داده‌های هویتی حساس در کامپوننت‌های کلاینت یا متغیرهای دارای پیشوند NEXT_PUBLIC_ قرار نگرفته‌اند و تمام تبادلات حساس صرفاً در Server Components انجام می‌شوند.
2. تست‌های نفوذ و پاکسازی ورودی‌ها در برابر XSS و Injection:
   • Jules تست‌های امنیتی ویژه‌ای با پی‌لودهای مخرب XSS روی تمامی ورودی‌های کاربر (بخش‌های پرسش و پاسخ، مقالات و نظرات شهروندی) اجرا می‌کند تا اطمینان حاصل شود که داده‌ها پیش از رندر توسط کتابخانه‌های استاندارد نظیر DOMPurify پاکسازی (Sanitize) می‌شوند.
   • تست خودکار لایه Middleware جهت احراز ثبت و صحت هدرهای امنیتی CSP، HSTS و X-Frame-Options در تمامی پاسخ‌های سرور.
3. تست امنیتی درگاه ابطال کش در برابر حملات Replay و DoS:
   • نوشتن تست‌های امنیتی روی اندپوینت ابطال کش (/api/revalidate و /api/v1/revalidate) جهت بررسی صحت امضای کریپتوگرافیک مبتنی بر کلید مشترک (HMAC-SHA256) در هدر X-Revalidation-Signature و اعتبارسنجی Timestamp.
   • این تست‌ها تضمین می‌کنند که درخواست‌های فاقد امضای معتبر یا درخواست‌های تکرارشده (Replay Attacks) فوراً رد شده و امکان پاکسازی غیرمجاز کش و تحمیل بار محروم‌سازی از سرویس (DoS) به دیتابیس PostgreSQL و سرورهای Go وجود ندارد.
4. پایش مستمر آسیب‌پذیری کتابخانه‌های Next.js (SCA & SAST):
   • اجرای خودکار ممیزی وابستگی‌ها (npm audit / CodeQL / Semgrep) در هر PR روی برنچ dev و مأموریت دادن به Jules برای ارتقای ایمن کتابخانه‌های آسیب‌پذیر بدون شکستن کدهای موجود.

۶. نقشه راه اجرایی گام‌به‌گام (Action Plan) در ریپازیتوری پایلوت

۷. نتیجه نهایی و دستاوردهای کمی برای سطوح عالی مدیریتی (Target Outcomes)

با تکمیل این فرآیند بر روی ریپازیتوری Metaverse-Rang-Front-NextJS، نتایج ملموس زیر در داشبورد مدیریتی پروژه ثبت خواهد شد:

1. صرفه‌جویی ۱۰۰ درصدی در زمان تست دستی مدیریتی: حذف کامل بیش از ۸ ساعت بررسی دستی پس از هر توسعه؛ تمامی ۶۰+ صفحه، ورودی‌ها، شمارش کاراکترهای تایتل و دسکریپشن، اسکیما، دسترسی‌پذیری و صحت داده‌های API در کمتر از ۵ دقیقه توسط پایپ‌لاین CI به صورت خودکار بررسی و گزارش می‌شوند.
2. جهش شاخص‌های عملکرد و تجربه کاربری: تحویل بیش از ۶۰ صفحه وب‌سایت با حفظ کامل اصول سئو و دسترسی‌پذیری بالا در بازه زمانی زیر ۱۰۰ میلی‌ثانیه برای بارگذاری اولیه و کاهش بار ترافیکی تحمیل‌شده به بک‌اند Go برای واکشی کدهای استاتیک به صفر.
3. تضمین امنیت در تراز استانداردهای ملی و بین‌المللی: انطباق کامل کدها با الزامات مرکز افتا، ISO/IEC 27034 و OWASP ASVS از طریق تست خودکار هدرهای امنیتی، پاکسازی ورودی‌ها با DOMPurify و محافظت رمزنگاری‌شده HMAC-SHA256 از اندپوینت‌های کش.
4. آمادگی زیرساخت برای مقیاس‌پذیری سازمانی: تبدیل این ریپازیتوری به ویترین استاندارد مهندسی شرکت تعاونی زنجیره تأمین بهشت جهت اتصال ساختاریافته ۳۵ ریپازیتوری دیگر بدون ایجاد وقفه در توسعه روزانه تیم‌ها.