{
  "title": "استایل گاید — راهنمای یکپارچه استانداردها",
  "slug": "team/platform/standards/index",
  "url": "/docs/team/platform/standards/index",
  "frontmatter": {
    "layout": "doc",
    "title": "استایل گاید — راهنمای یکپارچه استانداردها",
    "description": "نمای کلی تمام استانداردهای پروژه — راهنما و دسترسی سریع به مستندات",
    "version": "2.0.0",
    "status": "PRIVATE",
    "author": "xoxxel",
    "owner": "xoxxel",
    "created_at": "2026-06-06",
    "updated_at": "2026-06-12",
    "tags": "",
    "reviewers": ""
  },
  "sections": [
    {
      "level": 1,
      "heading": "استایل گاید — راهنمای یکپارچه استانداردها",
      "content": "**Global Style Guide**\n\nنسخه 2.0 | الزامی برای همه سرویس‌ها، پکیج‌ها و مشارکت‌کنندگان\n\n> این سند نمای کلی تمام استانداردهای پروژه نونز است. هر بخش به یک فایل مجزا لینک می‌دهد که جزئیات کامل در آن آمده.\n\n---"
    },
    {
      "level": 2,
      "heading": "اصول پایه",
      "content": "- **فارغ از تکنولوژی:** این استانداردها برای همه سرویس‌ها صرف نظر از زبان یا فریم‌ورک الزامی است\n- **زبان رسمی:** کد منبع به انگلیسی — مستندات محصول به فارسی\n- **اجرا:** رعایت این استانداردها برای همه اعضای تیم الزامی است\n\n---"
    },
    {
      "level": 2,
      "heading": "۱. استانداردهای عمومی",
      "content": "| #   | عنوان                    | توضیح کوتاه                                                       | فایل                                                 |\n| --- | ------------------------ | ----------------------------------------------------------------- | ---------------------------------------------------- |\n| ۱   | **خط مشی زبان**          | زبان رسمی کد (انگلیسی)، موارد مجاز فارسی، ممنوعیت‌ها              | [`language-policy.md`](language-policy.md)           |\n| ۲   | **قراردادهای نام‌گذاری** | فایل‌ها، دیتابیس، env vars، Docker images، NATS، API، Error Codes | [`naming-conventions.md`](naming-conventions.md)     |\n| ۳   | **ساختار مخزن**          | ساختار استاندارد هر سرویس، monorepo، مرجع سریع                    | [`repository-structure.md`](repository-structure.md) |\n| ۴   | **نسخه‌بندی**            | Semantic Versioning، پیش‌انتشار، تگ‌گذاری، وابستگی نسخه‌ها        | [`versioning-policy.md`](versioning-policy.md)       |\n| ۵   | **امنیت**                | رازها، parameterized queries، JWT expiry، HTTP-only cookies       | [`security-policy.md`](security-policy.md)           |\n\n---"
    },
    {
      "level": 2,
      "heading": "۲. مستندات و ارتباطات",
      "content": "| #   | عنوان                   | توضیح کوتاه                                                | فایل                                         |\n| --- | ----------------------- | ---------------------------------------------------------- | -------------------------------------------- |\n| ۶   | **مستندات سرویس**       | فایل‌های اجباری `docs/`، توضیح هر فایل، قوانین به‌روزرسانی | [`docs-policy.md`](docs-policy.md)           |\n| ۷   | **الگوی README**        | ساختار اجباری `docs/README.md` با مثال کامل                | [`readme-template.md`](readme-template.md)   |\n| ۸   | **تغییرات (CHANGELOG)** | ساختار Keep a Changelog، بخش‌ها، چرخه به‌روزرسانی          | [`changelog-policy.md`](changelog-policy.md) |\n\n---"
    },
    {
      "level": 2,
      "heading": "۳. طراحی API",
      "content": "| #   | عنوان                     | توضیح کوتاه                                          | فایل                                                               |\n| --- | ------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------ |\n| ۹   | **راهنمای طراحی API**     | مرجع رسمی طراحی API — نسخه‌گذاری، پوسته پاسخ، خطا، صفحه‌بندی، فیلتر، مرتب‌سازی، جستجو، تاریخ، شناسه، احراز هویت، نام‌گذاری، کدهای وضعیت، Nullable، Deprecation | [`api-design-guidelines.md`](../api/api-design-guidelines) |\n| ۱۰  | **راهنمای تولید OpenAPI** | استاندارد تولید، اعتبارسنجی و انتشار OpenAPI — نسخه، ابزار، پایپلاین CI، فراداده، امنیت | [`openapi-guidelines.md`](../api/openapi-guidelines) |\n| ۱۱  | **قرارداد رویداد**        | پوسته استاندارد NATS، فیلدها، versioning payload     | [`event-contract.md`](event-contract.md)                            |\n\n---"
    },
    {
      "level": 2,
      "heading": "۴. توسعه و کیفیت",
      "content": "| #   | عنوان                     | توضیح کوتاه                        | فایل                                             |\n| --- | ------------------------- | ---------------------------------- | ------------------------------------------------ |\n| ۱۲  | **تست**                   | واحد و یکپارچه، CI، پوشش، قوانین   | [`testing-policy.md`](testing-policy.md)         |\n| ۱۳  | **استاندارد لاگ‌نویسی**   | JSON ساختاریافته، سطوح، قوانین PII | [`logging-standard.md`](logging-standard.md)     |\n| ۱۴  | **تعریف انجام شده (DoD)** | چک‌لیست کامل پذیرش Feature/PR      | [`definition-of-done.md`](definition-of-done.md) |\n\n---"
    },
    {
      "level": 2,
      "heading": "۵. چرخه عمر سرویس",
      "content": "| #   | عنوان                  | توضیح کوتاه                                     | فایل                                                                            |\n| --- | ---------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------- |\n| ۱۵  | **بلوپرینت**           | الزامات پیش از توسعه، فایل‌ها، تأیید تیمی       | [`blueprint-policy.md`](blueprint-policy.md)                                    |\n| ۱۶  | **دمو (پیش‌نمایش)**    | HTML/CSS ساده، قوانین فنی، همگام‌سازی با سرویس  | [`demo-policy.md`](demo-policy.md)                                              |\n| ۱۷  | **گیت (کامیت و برنچ)** | فرمت کامیت، فرمت برنچ، workflow، PR             | [`git-policy.md`](git-policy.md)                                                |\n| ۱۸  | **مصنوعات ساخت**       | `.dockerignore`، multi-stage build، امنیت build | [`build-artifact-policy.md`](/docs/team/devops/standards/build-artifact-policy) |"
    },
    {
      "level": 2,
      "heading": "۶. یکپارچگی و حاکمیت",
      "content": "| #   | عنوان                     | توضیح کوتاه                                                    | فایل                                                                                 |\n| --- | -------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------ |\n| ۱۹  | **قرارداد مجوز (Permission Contract)** | تعریف، ثبت و مصرف Permissions توسط سرویس‌ها در IAM | [`permission-contract-standard.md`](permission-contract-standard.md)                 |\n| ۲۰  | **همگام‌سازی مجوزها و SDK** | راهکار هماهنگی مجوزهای IAM، هدرهای Auth و زنجیره codegen SDK | [`permission-and-sdk-sync-standard.md`](permission-and-sdk-sync-standard.md)         |\n\n---"
    },
    {
      "level": 2,
      "heading": "مرجع سریع",
      "content": "| محتوا                      | مکان                                                           |\n| -------------------------- | -------------------------------------------------------------- |\n| استاندارد طراحی API        | [`docs/team/platform/api/api-design-guidelines.md`](../api/api-design-guidelines) |\n| استاندارد تولید OpenAPI    | [`docs/team/platform/api/openapi-guidelines.md`](../api/openapi-guidelines) |\n| قراردادهای پلتفرم (Proto)  | `nons-api/contracts/`                                          |\n| انواع داده Platform        | `nons-api/contracts/*.proto` (تولیدشده در `nons-api/packages/contracts`) |\n| قراردادهای API و کدهای خطا | `nons-api/contracts/*.proto` (تولیدشده در `nons-api/packages/contracts`) |\n| کاتالوگ رویدادها           | `nons-api/catalog/events/` (YAML) + ساختار Envelope در Proto   |\n| قرارداد لاگینگ             | `nons-api/packages/logging/`                                   |\n| مصنوعات فرانت‌اند (Types, API Client, Hooks) | `.nons/generated/` (تولیدشده توسط `nons generate`)          |\n| انتزاعات دامنه             | `nons-api/core/`                                               |\n| کد منبع سرویس              | `nons-api/services/{name}/src/`                                |\n| تست‌های سرویس              | `nons-api/services/{name}/tests/`                              |\n| مستندات سرویس              | `nons-api/services/{name}/docs/`                               |\n| دموی سرویس                 | `nons-api/services/{name}/demo/`                               |\n| طرح اولیه سرویس            | `nons-api/services/{name}/blueprint/`                          |\n| تغییرات سرویس              | `nons-api/services/{name}/CHANGELOG.md`                        |\n| مانیفست‌های K8s            | `nons-api/infra/k8s/`                                          |\n| اسرار                      | هیچ‌کجا در git — از secret manager استفاده کنید      |\n\n---"
    },
    {
      "level": 2,
      "heading": "مسیر یادگیری پیشنهادی",
      "content": "1. [`language-policy.md`](language-policy.md) — قوانین زبانی\n2. [`naming-conventions.md`](naming-conventions.md) — نام‌گذاری\n3. [`repository-structure.md`](repository-structure.md) — ساختار پروژه\n4. [`api-design-guidelines.md`](../api/api-design-guidelines) — استاندارد طراحی API\n5. [`openapi-guidelines.md`](../api/openapi-guidelines) — استاندارد تولید OpenAPI\n6. [`git-policy.md`](git-policy.md) — گردش کار گیت\n7. [`definition-of-done.md`](definition-of-done.md) — تعریف انجام شده\n8. [`ADR-Platform-001_Contract-Layer`](../ADR/ADR-Platform-001) — معماری لایه قراردادها\n9. [`ADR-Platform-004`](../ADR/ADR-Platform-004) — استراتژی مدیریت قراردادها و تولید مصنوعات کلاینت\n10. سایر استانداردها بر اساس نیاز"
    }
  ]
}