---
read_when:
    - برنامه‌ریزی برای یک دور گسترده نوسازی اپلیکیشن OpenClaw
    - به‌روزرسانی استانداردهای پیاده‌سازی فرانت‌اند برای کار روی برنامه یا Control UI
    - تبدیل یک بازبینی گستردهٔ کیفیت محصول به کار مهندسی مرحله‌بندی‌شده
summary: طرح جامع مدرن‌سازی برنامه همراه با به‌روزرسانی‌های مهارت تحویل فرانت‌اند
title: برنامه نوسازی برنامه کاربردی
x-i18n:
    generated_at: "2026-04-29T23:31:48Z"
    model: gpt-5.5
    provider: openai
    source_hash: 667a133cb867bb1d4d09e097925704c8b77d20ca6117a62a4c60d29ab1097283
    source_path: reference/application-modernization-plan.md
    workflow: 16
---

# طرح نوسازی برنامه

## هدف

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

## اصول

- معماری فعلی را حفظ کنید، مگر اینکه یک مرز به‌طور قابل اثبات باعث ناپایداری،
  هزینه عملکردی، یا باگ‌های قابل مشاهده برای کاربر شود.
- برای هر مسئله، کوچک‌ترین وصله درست را ترجیح دهید، سپس تکرار کنید.
- اصلاحات ضروری را از پرداخت‌های اختیاری جدا کنید تا نگه‌دارندگان بتوانند کارهای
  باارزش را بدون انتظار برای تصمیم‌های سلیقه‌ای ادغام کنند.
- رفتار رو به Plugin را مستند و با نسخه‌های قبلی سازگار نگه دارید.
- پیش از ادعای رفع شدن یک پسرفت، رفتار منتشرشده، قراردادهای وابستگی، و تست‌ها را
  تأیید کنید.
- ابتدا مسیر اصلی کاربر را بهتر کنید: راه‌اندازی اولیه، احراز هویت، چت، تنظیم
  فراهم‌کننده، مدیریت Plugin، و عیب‌یابی.

## فاز ۱: ممیزی خط مبنا

پیش از تغییر دادن برنامه، وضعیت فعلی آن را فهرست کنید.

- گردش‌کارهای اصلی کاربر و سطوح کدی را که مالک آن‌ها هستند شناسایی کنید.
- امکانات بی‌اثر، تنظیمات تکراری، وضعیت‌های خطای نامشخص، و مسیرهای رندر پرهزینه
  را فهرست کنید.
- فرمان‌های اعتبارسنجی فعلی را برای هر سطح ثبت کنید.
- مسائل را به‌عنوان ضروری، پیشنهادی، یا اختیاری علامت‌گذاری کنید.
- مسدودکننده‌های شناخته‌شده‌ای را که به بازبینی مالک نیاز دارند مستند کنید، به‌ویژه
  تغییرات API، امنیتی، انتشار، و قرارداد Plugin.

تعریف انجام‌شده:

- یک فهرست مسئله با ارجاع‌های فایل از ریشه مخزن.
- هر مسئله شدت، سطح مالک، اثر مورد انتظار بر کاربر، و مسیر اعتبارسنجی پیشنهادی دارد.
- هیچ مورد پاک‌سازی حدسی با اصلاحات ضروری مخلوط نشده است.

## فاز ۲: پاک‌سازی محصول و UX

گردش‌کارهای قابل مشاهده را اولویت‌بندی کنید و ابهام را حذف کنید.

- متن راه‌اندازی اولیه و حالت‌های خالی پیرامون احراز هویت مدل، وضعیت Gateway،
  و تنظیم Plugin را دقیق‌تر کنید.
- امکانات بی‌اثر را در جاهایی که هیچ اقدامی ممکن نیست حذف یا غیرفعال کنید.
- اقدام‌های مهم را در عرض‌های واکنش‌گرا قابل مشاهده نگه دارید، به‌جای اینکه آن‌ها
  را پشت فرض‌های شکننده چیدمان پنهان کنید.
- زبان وضعیت تکراری را یکپارچه کنید تا خطاها یک منبع حقیقت داشته باشند.
- برای تنظیمات پیشرفته افشای تدریجی اضافه کنید، در حالی که تنظیمات اصلی سریع
  باقی بمانند.

اعتبارسنجی پیشنهادی:

- مسیر موفق دستی برای تنظیم اولین اجرا و شروع کار کاربر موجود.
- تست‌های متمرکز برای هر منطق مسیریابی، ماندگاری پیکربندی، یا استخراج وضعیت.
- اسکرین‌شات‌های مرورگر برای سطوح واکنش‌گرای تغییریافته.

## فاز ۳: محکم‌سازی معماری فرانت‌اند

قابلیت نگهداری را بدون بازنویسی گسترده بهتر کنید.

- تبدیل‌های تکراری وضعیت UI را به کمک‌کننده‌های باریک و نوع‌دار منتقل کنید.
- مسئولیت‌های دریافت داده، ماندگاری، و نمایش را جدا نگه دارید.
- الگوهای موجود hook، store، و component را به انتزاع‌های جدید ترجیح دهید.
- componentهای بیش‌ازحد بزرگ را فقط وقتی تقسیم کنید که وابستگی را کاهش دهد یا
  تست‌ها را روشن‌تر کند.
- از معرفی وضعیت سراسری گسترده برای تعاملات محلی پنل پرهیز کنید.

محافظ‌های ضروری:

- رفتار عمومی را به‌عنوان اثر جانبی تقسیم فایل‌ها تغییر ندهید.
- رفتار دسترس‌پذیری را برای منوها، دیالوگ‌ها، تب‌ها، و پیمایش با کیبورد سالم نگه دارید.
- تأیید کنید که حالت‌های بارگذاری، خالی، خطا، و خوش‌بینانه همچنان رندر می‌شوند.

## فاز ۴: عملکرد و قابلیت اطمینان

به‌جای بهینه‌سازی نظری گسترده، دردهای اندازه‌گیری‌شده را هدف بگیرید.

- هزینه‌های شروع برنامه، انتقال مسیر، فهرست بزرگ، و transcript چت را اندازه‌گیری کنید.
- داده‌های مشتق‌شده پرهزینه و تکراری را در جاهایی که پروفایل‌گیری ارزش را ثابت
  می‌کند با selectorهای memoized یا کمک‌کننده‌های cache‌شده جایگزین کنید.
- اسکن‌های قابل اجتناب شبکه یا فایل‌سیستم را در مسیرهای داغ کاهش دهید.
- پیش از ساخت payload مدل، ترتیب قطعی را برای ورودی‌های prompt، registry، فایل،
  Plugin، و شبکه حفظ کنید.
- تست‌های سبک پسرفت برای کمک‌کننده‌های داغ و مرزهای قرارداد اضافه کنید.

تعریف انجام‌شده:

- هر تغییر عملکردی خط مبنا، اثر مورد انتظار، اثر واقعی، و شکاف باقی‌مانده را ثبت می‌کند.
- وقتی اندازه‌گیری ارزان در دسترس است، هیچ وصله عملکردی صرفاً بر اساس شهود ادغام نمی‌شود.

## فاز ۵: سخت‌سازی نوع، قرارداد، و تست

درستی را در نقاط مرزی که کاربران و نویسندگان Plugin به آن وابسته‌اند افزایش دهید.

- رشته‌های runtime آزاد را با unionهای تفکیک‌شده یا فهرست‌های کد بسته جایگزین کنید.
- ورودی‌های خارجی را با کمک‌کننده‌های schema موجود یا zod اعتبارسنجی کنید.
- پیرامون manifestهای Plugin، catalogهای فراهم‌کننده، پیام‌های پروتکل Gateway،
  و رفتار مهاجرت پیکربندی، تست قرارداد اضافه کنید.
- مسیرهای سازگاری را به‌جای مهاجرت‌های پنهان زمان شروع، در جریان‌های doctor یا repair نگه دارید.
- از وابستگی مخصوص تست به جزئیات داخلی Plugin پرهیز کنید؛ از facadeهای SDK و barrelهای
  مستند استفاده کنید.

اعتبارسنجی پیشنهادی:

- `pnpm check:changed`
- تست‌های هدفمند برای هر مرز تغییریافته.
- `pnpm build` وقتی مرزهای lazy، بسته‌بندی، یا سطوح منتشرشده تغییر می‌کنند.

## فاز ۶: مستندات و آمادگی انتشار

مستندات رو به کاربر را با رفتار هماهنگ نگه دارید.

- مستندات را همراه با تغییرات رفتار، API، پیکربندی، راه‌اندازی اولیه، یا Plugin به‌روزرسانی کنید.
- فقط برای تغییرات قابل مشاهده برای کاربر ورودی changelog اضافه کنید.
- اصطلاح‌شناسی Plugin را رو به کاربر نگه دارید؛ نام‌های داخلی package را فقط جایی
  استفاده کنید که برای مشارکت‌کنندگان لازم است.
- تأیید کنید که دستورالعمل‌های انتشار و نصب همچنان با سطح فرمان فعلی مطابقت دارند.

تعریف انجام‌شده:

- مستندات مرتبط در همان شاخه تغییرات رفتاری به‌روزرسانی شده‌اند.
- بررسی‌های drift مستندات تولیدشده یا API، در صورت لمس شدن، قبول می‌شوند.
- handoff هر اعتبارسنجی ردشده و دلیل رد شدن آن را نام می‌برد.

## بخش اول پیشنهادی

با یک گذر محدود روی Control UI و راه‌اندازی اولیه شروع کنید:

- سطوح تنظیم اولین اجرا، آمادگی احراز هویت فراهم‌کننده، وضعیت Gateway، و تنظیم
  Plugin را ممیزی کنید.
- اقدام‌های بی‌اثر را حذف کنید و حالت‌های شکست را روشن‌تر کنید.
- تست‌های متمرکز را برای استخراج وضعیت و ماندگاری پیکربندی اضافه یا به‌روزرسانی کنید.
- `pnpm check:changed` را اجرا کنید.

این کار با ریسک معماری محدود، ارزش بالایی برای کاربر ایجاد می‌کند.

## به‌روزرسانی مهارت فرانت‌اند

از این بخش برای به‌روزرسانی `SKILL.md` متمرکز بر فرانت‌اند که همراه وظیفه
نوسازی ارائه شده است استفاده کنید. اگر این راهنما را به‌عنوان یک skill محلی مخزن
برای OpenClaw می‌پذیرید، ابتدا `.agents/skills/openclaw-frontend/SKILL.md` را
بسازید، frontmatter مربوط به آن skill هدف را نگه دارید، سپس راهنمای بدنه را با
محتوای زیر اضافه یا جایگزین کنید.

```markdown
# Frontend Delivery Standards

Use this skill when implementing or reviewing user-facing React, Next.js,
desktop webview, or app UI work.

## Operating rules

- Start from the existing product workflow and code conventions.
- Prefer the smallest correct patch that improves the current user path.
- Separate required fixes from optional polish in the handoff.
- Do not build marketing pages when the request is for an application surface.
- Keep actions visible and usable across supported viewport sizes.
- Remove dead affordances instead of leaving controls that cannot act.
- Preserve loading, empty, error, success, and permission states.
- Use existing design-system components, hooks, stores, and icons before adding
  new primitives.

## Implementation checklist

1. Identify the primary user task and the component or route that owns it.
2. Read the local component patterns before editing.
3. Patch the narrowest surface that solves the issue.
4. Add responsive constraints for fixed-format controls, toolbars, grids, and
   counters so text and hover states cannot resize the layout unexpectedly.
5. Keep data loading, state derivation, and rendering responsibilities clear.
6. Add tests when logic, persistence, routing, permissions, or shared helpers
   change.
7. Verify the main happy path and the most relevant edge case.

## Visual quality gates

- Text must fit inside its container on mobile and desktop.
- Toolbars may wrap, but controls must remain reachable.
- Buttons should use familiar icons when the icon is clearer than text.
- Cards should be used for repeated items, modals, and framed tools, not for
  every page section.
- Avoid one-note color palettes and decorative backgrounds that compete with
  operational content.
- Dense product surfaces should optimize for scanning, comparison, and repeated
  use.

## Handoff format

Report:

- What changed.
- What user behavior changed.
- Required validation that passed.
- Any validation skipped and the concrete reason.
- Optional follow-up work, clearly separated from required fixes.
```
