{
  "title": "سیاست مستندات سرویس",
  "slug": "team/platform/standards/docs-policy",
  "url": "/docs/team/platform/standards/docs-policy",
  "frontmatter": {
    "layout": "doc",
    "title": "سیاست مستندات سرویس",
    "description": "فایل‌های اجباری docs/، توضیح هر فایل و قوانین به‌روزرسانی",
    "version": "1.0.0",
    "status": "PRIVATE",
    "author": "xoxxel",
    "owner": "xoxxel",
    "created_at": "2026-06-07",
    "updated_at": "2026-06-07",
    "tags": "",
    "reviewers": ""
  },
  "sections": [
    {
      "level": 1,
      "heading": "سیاست مستندات سرویس",
      "content": "**Service Documentation Policy**\n\nنسخه 1.0 | الزامی برای همه سرویس‌ها\n\n---"
    },
    {
      "level": 2,
      "heading": "1. اصل اساسی",
      "content": "هر سرویس مستندات خود را داخل پوشه `docs/` خود نگهداری می‌کند.  \n**هیچ مستند سرویسی خارج از دایرکتوری سرویس زندگی نمی‌کند.**\n\n---"
    },
    {
      "level": 2,
      "heading": "2. فایل‌های اجباری",
      "content": "| فایل | محتوا | اجباری |\n|---|---|---|\n| `README.md` | راه‌اندازی، متغیرهای محیط، دستورالعمل اجرا، خلاصه نقاط پایانی | ✅ |\n| `openapi.yaml` | مشخصات کامل OpenAPI 3.0 برای همه نقاط پایانی | ✅ |\n| `events.md` | رویدادهای منتشر شده (با payload) و مصرف شده | ✅ |\n| `database.md` | نمای کلی طرح دیتابیس، نکات مهاجرت | ✅ |\n\n---"
    },
    {
      "level": 2,
      "heading": "3. فایل‌های اختیاری اما توصیه شده",
      "content": "| فایل | محتوا |\n|---|---|\n| `adr/` | تصمیمات معماری خاص این سرویس (Architecture Decision Records) |\n| `runbook.md` | نحوه اشکال‌زدایی مشکلات رایج در محیط تولید |\n| `load-testing.md` | سناریوها و نتایج تست بار |\n| `migration-guide.md` | راهنمای مهاجرت برای نسخه‌های MAJOR |\n\n---"
    },
    {
      "level": 2,
      "heading": "4. توضیح فایل‌های اجباری",
      "content": ""
    },
    {
      "level": 3,
      "heading": "`README.md`",
      "content": "- اولین فایلی که هر توسعه‌دهنده می‌خواند\n- باید طبق الگوی بخش ۶ (README Template) نوشته شود\n- شامل راه‌اندازی، متغیرهای محیط، API، رویدادها، دیتابیس"
    },
    {
      "level": 3,
      "heading": "`openapi.yaml`",
      "content": "- مشخصات کامل OpenAPI 3.0\n- شامل همه endpoints با متد، مسیر، پارامترها، درخواست و پاسخ\n- همراه با سرویس به‌روزرسانی شود\n\n```yaml\nopenapi: 3.0.0\ninfo:\n  title: Order Service\n  version: 1.0.0\npaths:\n  /v1/orders:\n    post:\n      summary: Create a new order\n      requestBody:\n        required: true\n        content:\n          application/json:\n            schema:\n              type: object\n              properties:\n                productId:\n                  type: string\n                  format: uuid\n                quantity:\n                  type: integer\n                  minimum: 1\n      responses:\n        '201':\n          description: Order created\n```"
    },
    {
      "level": 3,
      "heading": "`events.md`",
      "content": "- رویدادهایی که سرویس **منتشر می‌کند** (Publishes)\n- رویدادهایی که سرویس **مصرف می‌کند** (Subscribes)\n- هر رویداد با payload نمونه\n\n```markdown"
    },
    {
      "level": 1,
      "heading": "Events",
      "content": ""
    },
    {
      "level": 2,
      "heading": "Publishes",
      "content": ""
    },
    {
      "level": 3,
      "heading": "`nons.order.created`",
      "content": "```json\n{\n  \"id\": \"uuid-v7\",\n  \"type\": \"order.created\",\n  \"version\": \"1\",\n  \"payload\": {\n    \"orderId\": \"uuid\",\n    \"sellerId\": \"uuid\",\n    \"amount\": 100.00\n  }\n}\n```"
    },
    {
      "level": 2,
      "heading": "Subscribes",
      "content": ""
    },
    {
      "level": 3,
      "heading": "`nons.payment.released`",
      "content": "- action: آزادسازی وجوه\n```"
    },
    {
      "level": 3,
      "heading": "`database.md`",
      "content": "- موتور دیتابیس (PostgreSQL, MongoDB, Redis)\n- موجودیت‌های اصلی با فیلدهای کلیدی\n- روابط بین موجودیت‌ها\n- نکات مهاجرت و ایندکس‌های مهم\n\n---"
    },
    {
      "level": 2,
      "heading": "5. قوانین",
      "content": "| قانون | توضیح |\n|---|---|\n| خودکفایی | مستندات هر سرویس در مخزن همان سرویس |\n| هم‌گامی | تغییر در سرویس = به‌روزرسانی مستندات مربوطه |\n| زبان | مستندات سرویس به **فارسی** نوشته می‌شوند (مقادیر و نام‌ها انگلیسی) |\n| بازبینی | مستندات در PR بازبینی می‌شوند |\n| ADR | تصمیمات معماری مهم باید در `adr/` مستند شوند |\n\n---"
    },
    {
      "level": 2,
      "heading": "6. چک‌لیست به‌روزرسانی",
      "content": "| تغییر در سرویس | مستندات نیازمند به‌روزرسانی |\n|---|---|\n| اضافه شدن endpoint | `openapi.yaml` ✅ |\n| تغییر payload رویداد | `events.md` ✅ |\n| تغییر دیتابیس | `database.md` ✅ |\n| تغییر راه‌اندازی | `README.md` ✅ |\n| تصمیم معماری جدید | `adr/` ✅ |\n| تغییر رفتار | `README.md` + docs مربوطه ✅ |"
    }
  ]
}