# پیشوند هوش مصنوعی برای Khandan (فارسی)

## هدف
این «پیشوند» برای تقویت رابط کاربری بین یک مدل هوش مصنوعی و تیم توسعه Khandan استفاده می‌شود. این شامل زمینه، محیط، وظایف، دستورالعمل‌های امنیتی، و نیازهای کلی برای جلوگیری از درگیر شدن مدل در جزئیات کدنویسی یا ابزارهای خارجی پرهزینه است.

## زمینه کسب و کار (قابل اعتماد)
**Khandan (خاندان)** یک پلتفرم کاملاً شخصی، مستقل، و مبتنی بر وب می‌باشد که پیوند عمیقی بین اعضای خانواده پراکنده‌شده جغرافیایی می‌سازد. این سامانه سه قطب اصلی «حفظ خاطرات»، «صندوق‌های مالی»، و «مدیریت اموال بعد از مرگ» را با فناوری‌های نوین تلفیق می‌کند. از آنجا که هر فامیل ساختار منحصربه‌فردی دارد (روابط، فرهنگ، دارایی‌ها، نیازها)، بنیان کمی طراحی پلتفرم‌ها و رابط‌های کاربری رو به منفی است. بنیان کیفی ظرافت مستلزم برنامه‌نویسی ۵۰ ساله است؟ هیچ. ولی بنیان تکنولوژی وهو قابل استفاده در آنی زمان و مکان است.

## محیط شاخص (محیط چهارگانه)
- **زبان:** PHP 8.x خالص (کدی بدون استفاده از Laravel, Symfony, یا Express-type).
- **پایگاه داده:** SQLite3 (فایل واحد `khandan.db`) — بدون وابستگی به MySQL، PostgreSQL، MongoDB.
- **لایه کاربری:** HTML5 + CSS3 خالص (بدون Autoprefixer, SASS, یا Mantine).
- **جاوااسکریپت:** Vanilla JS (بدون React, Vue, Angular, بدون React Devtools).
- **پیشرفت:** مدیریت نسخه Git است؛ دستورات منفی: `git pull-origin-main` قبل از هر pull; تولید/آزمایشی در `development` / `master`.
- **پیشرفت‌کننده‌های مجاز:** عضو تیم اصلی پروژه (دونفر + یک مجری)

## وظایف اصلی

### ۱. بازنویسی سطح بالا
- با استفاده از **کنترل‌کننده‌های مسیر PHP**، یک REST-API تعریف کنید که `family` (خانواده) → `member` → `profile` → `tree` → `economic` → `legal` → `archive` تقسیم شود.
- یک **محدوده نقشه‌راهی واحد** (۵+ صفحه) شامل مسیر کاربری پدر خاندان تا عضو یک خاندان نمایش داده شده بر روی مرورگر به صورت واکنش‌گرا.
- **از پلتفرم‌های بومی (با Shift+Command+M) اجتناب کنید** و CSS را مستقیماً وارد کنید (`<?php echo file_get_contents('styles.css'); ?>`).
- **JS را به صورت ساده و انقباضی بنویسید** (مثلاً `scripts/forms.js` شاید، بدون قالانگ گسترده).
- **Put and commit** (مراحل ۱-۳).

### ۲. سکریپت‌های سمت سرور
- **Default controller** (مبدل‌های URL):
  - `GET /family/{id}/tree` (JSON گره‌های XML)
  - `POST /family/{id}/member` (ایجاد پروفایل)
  - `PUT /family/{id}/member/{mid}` (بروزرسانی)
- **Authentication**: PDO + Session + `password_hash`, هش SECRET سرور.
- **Encryption:** AES-256-CBC لایه Vault با کلیدی که از رمز عبور + salt مشتق شده.
- **Logger:** میک‌لاگر قابل نوشتن به فایل (خطاها در `logs/error.log`; اقدامات در `logs/actions.log`).

### ۳. پیکربندی پایگاه داده
- اسکریپت واسط PDO (`db/connect.php`):
  ```sql
  CREATE TABLE IF NOT EXISTS families (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, created DATETIME);
  CREATE TABLE IF NOT EXISTS members (id INTEGER PRIMARY KEY AUTOINCREMENT, family_id INTEGER, name TEXT, birth TEXT, death TEXT, profile_node TEXT, role TEXT);
  CREATE TABLE IF NOT EXISTS vault_items (id INTEGER PRIMARY KEY AUTOINCREMENT, member_id INTEGER, type TEXT, data_encrypted TEXT, key_encrypted TEXT, expires_at TEXT);
  ```
- **قوانین اصلی:** `foreign key` زند زندگی‌ها.
- **پشتیبان‌گیری:** در دسترس عضو تیم اصلی، زیر `/backups/khandan_YYYYMMDD.sql`.

### ۴. بررسی JSON متقارن
- **هر خروجی پذیرش‌های یکپارچه:** `Content-Type: application/json; charset=utf-8`
- **پدر خاندان:** `{"id": ۱، "name": "خاندان محمودی"}`
- **عضو:** `{"memberId": ۴۲، "profile": {"memberName": "..."}}`
- **KV:** مقادیر خالص `{"item": "value"}` (بدون ویژگی‌های اضافی اندروید).
- **None یک کلید نیست** &mdash; «null» در PHP = `null` در JSON.

### ۵. ایمنی (دقت بالا)
- **عددهای مهلک:** HSM تماس‌های پیمانی.
- **XSS**: `htmlspecialchars` روی همه خروجی‌های کاربر.
- **CSRF:** حفظ Session همراه با کوکی `XSRF-TOKEN` برای POST، Put, Delete.
- **File upload:** فقط فایل‌های مجاز: `{jpg,png,pdf,mp3,wav}`. حذف آسیب‌پذیر (regex اجازه داده نمی‌شود).
- **ورود امن:** حداکثر ۵ تلاش; قفل حساب برای ۱۵ دقیقه پس از ۵ تلاش ناموفق.
- **Permission propagation:** اعضا قابل دسترسی فقط به داده‌های خانواده خودشان؛ ریش‌سفیدان قابل دسترسی به خانواده‌های خودشان.

### ۶. انتشار FTP
- **از `deploy.php` استفاده کنید:** `(&$error, $messages = deploy(FTP_HOST, FTP_USER, FTP_PASS, REMOTE_ROOT, LOCAL_PATH))`
- **Arghavan:** از `fsockopen` برای فرآیندهای لینوکس با مدیریت زمان.
- **خطای FTP:** گزارش موثر به پایگاه وب.
- **Git pull قبل از deploy:** به طور خودکار تأیید کن.

## نیازهای عملی کلیدی
- **لوازم محیطی:** macOS/Linux (یا Windows + WSL). یک پوشه پروژه `kh` (یا پیشنهاد کنید). `git config --global user.email` و `user.name`؛ `php -v` >= ۸.۰.
- **کلید خصوصی:** (اختیاری) برای اتصال به سرویس‌های از راه دور اما فقط محلی؛ اگر نباشد، از `openssl_random_pseudo_bytes` استفاده کنید.
- **مدیریت صلاحیت‌های:** یک رول پایگاه داده داشته باشید (مثلاً `kh_user`). اعضای کلیدی از قبل تنظیم شده‌اند و نیاز به ترکیب مجدد ندارند.
- **راه‌اندازی پایگاه داده:** وارد `README.md` شوید: `php db/connect.php` (ایجاد `khandan.db` در `storage/`).

## ابزارهای ممنوع (واقع‌بین)
- **فریم‌ورک‌های بومی:**Laravel, CodeIgniter, Slim, Yii, Symphony, Phalcon, FuelPHP, Zend Framework, lub Algebra.
- **JavaScript UI library:** React, Vue, Angular, Svelte, Solid, Preact, Stimulus.
- **CSS frameworks:** Tailwind, Bootstrap, Bulma, Foundation, Milligram, Tailwind CSS. (استفاده از CSS خالص مجاز است)
- **کتابخانه‌های فلش:** Axios, JQuery (مدیوم), Lodash, Moment.js, Date-fns.
- **ابزارهای پیام:** Node.js, npm, Yarn, Bun.
- **کتابخانه‌های OIDC / OAuth:** OpenID Connect, Keycloak, Passport.js, Laravel Sanctum (بدون استفاده از فریم‌ورک PHP).

## استراتژی ارائه توضیحات (تشریحی)
- **هر پیام باید باهوش، مستقیم، و در حد ۱۲۰ کلمه باشد.** مثال:
  `\"برای Khandan، درخواست می‌کنیم یک گرافیکی SVG پویا HTML خام با قابلیت کشش و رها کردن، نصب پلتفرم تک‌ورودی PHP را پیاده‌سازی کنیم.\"`
- **برگه‌های داده‌ای دقیق:** موسیقیاب اکشن → بررسی خطاها و مدت زمان اجرای.
- **نگارش مستندهای محلی:** `docs/` شامل `architecture.md` (نقشه راه اون برای تدقيق معماری), `development-guide.md` (قوانین), `structure.md` (اسکریپت‌های واسط پایگاه داده).
- **پیشوند کمی:** فقط زبان، لیست دستورات، لیست اسکن‌های مورد اعتماد. بدون توضیحات اضافی.

## قواعد پذیرش
- **مرحله Unit tests:** دستورات: `php -r "require 'tests/unit/bootstrap.php'; (new\TestPlan())->run();"`
- **مرحله Benchmark:** `php -r "require 'tests/benchmark/memory-peak.php';`
- **مرحله Lint PHP:** `phpcs --standard=PEAR src/`
- **مرحله Naughty String:** حذف همه کدهای گشتی مثل `eval()`, `system()`. JSON out بر اساس `json_encode` تعریف می‌شود.

## پنجره اعتبار داخلی (به عنوان سوالات متقارن)
- **مخالف:** یک شکایت در GitHub. ناسازگاری ادعاهای فنی با مقدمه ارایه توضیحات رسمی.
- **خوب:** یک امضای گیت Xorax.

## قابلیت PWA
- تاریخ تحویل: <strong>ماه ۲</strong>
- روش‌های اضافی: `manifest.json` در `public/` (نصاب/نصب). Service worker در `public/sw.js`. 

## ارزیابی عملکرد تا پایان هفته ۲۴؛ بررسی عملکرد در پایان هفته ۲۶.

---

**نتیجه:** تحقق این وظایف به یک برنامه خالص PHP با طراحی حماسی اجباری تبدیل می‌شود که قابل نصب روی اندروید، iOS، و کامپیوتر است و از هر بروشور صرفه‌جویی در اندازه (`khandan.sw.js` vs ``) پیروی می‌کند. اگر به رأی خاصی نیاز دارید (مثلاً رابط کاربری کانترولر مصرف‌کننده)، به راحتی توضیح دهید. عملکرد قابل اینکه در <strong>۱۲ ساعت</strong> به اتمام برسد.

---

می‌توانید پرسش‌های دقیق برای سوالات بیشتری بپرسید.