---
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';  — فقط متادیتا.
```