# استاندارد ساخت و به‌روزرسانی کاتالوگ «فیلم‌بازی»
> این سند را هر بار که خواستی فیلم‌ها را از صفر بسازی یا گسترش دهی دنبال کن تا خروجی دقیقاً منطبق با اپ باشد.

---

## ۰) اسکیمای هر فیلم (تغییرش نده)
هر آبجکت در `films.json` باید این کلیدها را داشته باشد:

```json
{
  "id": "tt1375666",                // شناسه IMDb واقعی؛ اگر نبود: tt9 + شناسه TMDB
  "tmdbId": 27205,                  // شناسه TMDB (برای پوستر تضمینی)
  "marquee": "Inception",           // عنوان انگلیسی
  "fa": "تلقین",                    // عنوان فارسی
  "native": "",                     // عنوان به زبان اصلی (اگر غیرانگلیسی)
  "year": 2010,
  "runtime": 148,
  "genres": ["علمی تخیلی","اکشن","هیجان انگیز"],   // فقط از واژگان استانداردِ زیر
  "director": ["کریستوفر نولان"],   // فارسی
  "cast": [{"n":"لئوناردو دی‌کاپریو"}],             // فارسی؛ n = نام، c = نقش (اختیاری)
  "lang": "en",
  "country": "US",
  "rating": 8.4,
  "overview": "خلاصهٔ فارسیِ یک‌خطی و دقیق.",
  "posterUrl": "https://api.cashf-team.xyz/poster/poster.php?tmdb=27205&imdb=tt1375666&title=Inception&year=2010"
}
```

### واژگانِ استانداردِ ژانر (فقط از این‌ها استفاده کن)
`درام، جنایی، کمدی، اکشن، علمی تخیلی، معمایی، ماجراجویی، بیوگرافی، فانتزی، عاشقانه، هیجان انگیز، انیمیشن، وسترن، جنگی، وحشت، تاریخی، خانوادگی، نوآر، ورزشی، مستند، موزیکال، کمدی سیاه، روانشناختی، فلسفی`

### فرمتِ پوستر (مهم)
همیشه حالتِ `?tmdb=<id>&imdb=<id>&title=<url-enc>&year=<year>` — چون پوسترِ tmdb **تضمینی** است. (نیازمندِ نسخهٔ جدید `poster.php` که پارامتر `tmdb` را می‌فهمد.)

---

## ۱) ترتیبِ عملیات (از صفر)
```
① generate_films.php   → کشیدن فیلم‌های محبوب از TMDB با اسکیما + فیلتر ایمنی
② enrich_films.php     → شناسه TMDB، پوستر تضمینی، نام و خلاصهٔ فارسیِ رسمی
③ فارسی‌سازی دستی      → نام/خلاصهٔ فیلم‌هایی که TMDB فارسی نداشت
④ پاکسازی              → حذف محتوای حساس + فیلم‌های اکران‌نشده (سال ≥ سالِ بعد)
⑤ اعتبارسنجی           → JSON سالم، idهای یکتا، بدون تکراری
⑥ استقرار              → data/films.json (سرور) + app/src/main/assets/films.json (اپ)
```

---

## ۲) قانون‌های ایمنی (سخت‌گیرانه)
اپ در ایران/کافه‌بازار منتشر می‌شود؛ این‌ها **حذف** می‌شوند:
- **مستهجن/اروتیک:** هر فیلمی با پرچم adult در TMDB، یا با کلیدواژه‌های جنسی در عنوان/خلاصه/کلیدواژه‌ها (porn, erotic, nymphomaniac, sex tape, softcore, …).
- **فرنچایزها/عناوینِ مشخص:** Fifty Shades، 365 Days، Nymphomaniac، 9 Songs، Blue Lagoon، Emmanuelle، Showgirls، Basic Instinct، Room in Rome، Caligula و…
- **اکستریم/خشنِ افراطی:** A Serbian Film، Human Centipede، Cannibal Holocaust، Martyrs، Salò، Irreversible.
- **کودک‌آزاری (بسیار مهم):** Pretty Baby، Lolita و هر محتوای مرتبط با کودک.

**نکتهٔ تطبیق:** همیشه با تطبیقِ **دقیق/ابتدای‌عنوان** حذف کن، نه زیررشته — وگرنه فیلم‌های سالم مثل Salt، The Proposal، When Harry Met Sally اشتباهی پاک می‌شوند.

---

## ۳) پاکسازیِ کیفیت
- **اکران‌نشده‌ها:** فیلم‌های `year ≥ سالِ جاری+۱` (مثلاً ۲۰۲۶) امتیازِ جعلیِ بالا و دادهٔ ناقص دارند → حذف.
- **بدونِ خلاصه و بدونِ پوستر و کم‌رأی:** کاندیدِ حذف (کیفیت به‌جای کمیت — با روحِ لترباکس سازگارتر).

---

## ۴) فارسی‌سازی
- **اولویت:** فیلم‌های `year ≤ امسال` و `rating ≥ ۷` (چون کاربر این‌ها را می‌بیند).
- نامِ فیلم = ترجمهٔ رایجِ فارسی (نه ترجمهٔ تحت‌اللفظی)، خلاصه = یک جملهٔ دقیق و بی‌اسپویل.
- نام‌های خاص (کارگردان/بازیگر) را از انگلیسی به فارسی برگردان تا با بقیهٔ کاتالوگ یکدست بماند.
- فارسیِ خوبِ موجود را **بازنویسی نکن** (فقط جای خالی/انگلیسی را پر کن).

---

## ۵) اعتبارسنجی (قبل از استقرار)
- JSON سالم و قابلِ parse.
- `id`ها یکتا؛ بدون تکراری بر اساسِ (عنوان + سال).
- همهٔ فیلدهای اجباری موجود؛ `genres` فقط از واژگانِ استاندارد.
- هیچ‌کدام از عناوینِ بخشِ ایمنی حاضر نباشند.
- `posterUrl` همه در حالتِ `tmdb`.

---

## ۶) محلِ دقیقِ فایل‌ها
| فایل | مسیر |
|---|---|
| کاتالوگ (اپ) | `app/src/main/assets/films.json` |
| کاتالوگ (سرور) | `api.cashf-team.xyz/data/films.json` |
| مجموعه‌ها (اپ/سرور) | `.../assets/collections.json` و `data/collections.json` |
| پروکسی پوستر | `api.cashf-team.xyz/poster/poster.php` (+ `config.php`) |
| اسکریپت‌ها | کنارِ `poster.php`: `generate_films.php`، `enrich_films.php` |

> چون اپ اول از **سرور** می‌خواند، برای دیدنِ تغییر بدونِ آپدیتِ اپ، فقط `data/*.json` را روی سرور به‌روز کن. نسخهٔ assets فقط فالبکِ آفلاین است.