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

# هدف

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

# اصول

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

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

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

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

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

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

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

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

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

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

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

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

نگهداشت‌پذیری را بدون بازنویسی گسترده بهبود دهید.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• مستندات مرتبط در همان شاخهٔ تغییرات رفتاری به‌روزرسانی شده‌اند.
• وقتی مستندات تولیدشده یا API لمس شده‌اند، بررسی‌های drift آن‌ها پاس می‌شوند.
• تحویل نهایی هر اعتبارسنجی ردشده و دلیل رد شدن آن را نام می‌برد.

# بخش نخست پیشنهادی

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

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

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

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

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

# 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.