Add referral_show setting and keep existing setting values intact.

Allow hiding the referral field on user registration via settings SQL and ConfigService, and document SQL-only Cursor rules that never overwrite live values. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-11 08:26:13 +02:00
parent fabce6176a
commit 4468eabd03
5 changed files with 145 additions and 9 deletions
@@ -0,0 +1,53 @@
+---
+description: khaneghi_server — فقط SQL؛ کد سرور را تغییر نده؛ value را عوض نکن
+alwaysApply: true
+---
+
+# khaneghi_server — SQL-only edits
+
+این ریپو Laravel API پلتفرم خانگی است (`khaneghi_server`؛ روی سرور معمولاً `…/server`).
+
+## قانون اصلی
+
+- **هرگز** کد اپلیکیشن/سرور را تغییر نده، مگر کاربر صریحاً بگوید «کد PHP/Laravel را هم عوض کن».
+- وقتی کاربر دستوری برای تغییر می‌دهد، **فقط فایل‌های `.sql`** را ویرایش/ایجاد کن — ترجیحاً زیر `database/sql/`.
+- سؤال، توضیح، و خواندن کل پروژه آزاد است؛ نوشتن فقط در محدودهٔ SQL.
+- **`value` ها تغییر نکنند:** برای ردیف‌های موجود در `settings` / `const` هرگز `UPDATE ... SET value = ...` ننویس و value زنده‌ای که ادمین/سیستم تنظیم کرده را عوض نکن. فقط کلید جدید با `INSERT ... WHERE NOT EXISTS` و پیش‌فرض اولیه. متادیتا (`title_fa`, `description`, `type`, `can_edit`) مجاز است. استثنا فقط اگر کاربر صریحاً بگوید value را عوض کن (و در SQL شرط خالی‌بودن مستند شود).
+
+## مجاز (editable)
+
+- `database/sql/**/*.sql` — patch، deploy، tenant merge، settings/const، ensure/alter
+- در صورت نیاز برای اجرای همان SQL: فقط به‌روزرسانی توضیحات داخل همان `.sql` (هدر/کامنت)
+
+## ممنوع (do not edit)
+
+- `app/**` — Controllers، Models، Services، `MigrateCommand`، Providers، Jobs، …
+- `routes/**`, `config/**`, `packages/**`, `resources/**`, `bootstrap/**`, `public/**`, `tests/**`
+- `database/migrations/**` (PHP) — مگر کاربر صریحاً migration بخواهد
+- `database/schema/mysql-schema.sql.reference` — dump مخرب با `DROP TABLE`؛ روی DB موجود اجرا/بازنویسی نکن
+- `.env`, `composer.json`, `composer.lock`, Docker، اسکریپت‌های root ops
+- بازنویسی `value` (و ترجیحاً `is_active`) ردیف‌های موجود settings یا const در SQLهای deploy
+
+اگر کار فقط با تغییر PHP حل می‌شود: **رد کن**، راه SQL پیشنهاد بده، یا بپرس آیا مجاز به لمس کد هستی.
+
+## قرارداد SQL
+
+- Idempotent بنویس (قابل اجرای چندباره).
+- **حفظ value:** در `deploy_settings_const*.sql` و هر patch جدید، برای ردیف موجود **هرگز** `UPDATE value` نزن. فقط INSERT کلید جدید با default؛ آپدیت فقط روی `title_fa` / `description` / `type` / `can_edit`. ترجیح آپگرید زنده: `deploy_settings_const_preserve_value_sync_can_edit.sql`.
+- Schema جدول/ستون را در settings SQL نگذار؛ برای ستون جدید از الگوی `database/sql/_helpers/safe_add_column.sql` / `ensure_*.sql` / `deploy_safe_schema.sql` پیروی کن.
+- نام‌گذاری: `add_*`, `alter_*`, `ensure_*`, `*_patch.sql`, `{tenant}_*`, `deploy_settings_const*.sql`.
+- قبل از پیشنهاد اجرا روی سرور: بکاپ؛ ترتیب DB موجود معمولاً: `baseline_migrations.sql` → `php artisan migrate` → `deploy_settings_const*.sql` (جزئیات: `database/sql/DEPLOY_CHECKLIST.md`).
+
+## ایمنی migrate
+
+- `app/Console/MigrateCommand.php` از auto-load اسکیما جلوگیری می‌کند — آن را لمس/حذف نکن.
+- روی DB موجود هرگز `mysql-schema.sql.reference` را پیشنهاد نکن.
+
+## مثال
+
+```text
+❌ کاربر: «فلگ X را در SettingsController چک کن» → فایل PHP را ادیت نکن؛ در صورت نیاز کلید را در SQL settings اضافه کن.
+❌ SQL: UPDATE settings SET value = 'false' WHERE key = 'referral_show';  — value زنده را عوض نکن.
+✅ کاربر: «کلید support_messengers را به deploy settings اضافه کن» → فقط database/sql/*.sql با INSERT WHERE NOT EXISTS.
+✅ SQL: UPDATE settings SET title_fa = '...', description = '...' WHERE key = 'referral_id';  — فقط متادیتا.
+```