{
  "title": "الگوی README سرویس",
  "slug": "team/platform/standards/readme-template",
  "url": "/docs/team/platform/standards/readme-template",
  "frontmatter": {
    "layout": "doc",
    "title": "الگوی README سرویس",
    "description": "ساختار اجباری docs/README.md — بخش‌ها، ترتیب و مثال کامل",
    "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": "الگوی README سرویس",
      "content": "**Service README Template**\n\nنسخه 1.0 | الگوی اجباری برای `docs/README.md` هر سرویس\n\n---"
    },
    {
      "level": 2,
      "heading": "1. ساختار اجباری",
      "content": "فایل `docs/README.md` هر سرویس باید **دقیقاً** شامل این بخش‌ها با همین ترتیب باشد:\n\n```markdown"
    },
    {
      "level": 1,
      "heading": "{نام سرویس}",
      "content": "> {یک جمله — این سرویس مسئول چه کاری است}"
    },
    {
      "level": 2,
      "heading": "مسئولیت‌ها",
      "content": "{لیست مواردی که این سرویس در اختیار دارد}"
    },
    {
      "level": 2,
      "heading": "شروع سریع",
      "content": "{حداقل مراحل برای اجرای محلی}"
    },
    {
      "level": 2,
      "heading": "متغیرهای محیط",
      "content": "| متغیر | الزامی | مقدار پیش‌فرض | توضیحات |\n|---|---|---|---|\n| `SERVICE_DB_URL` | بله | `postgres://localhost:5432/db` | آدرس دیتابیس |"
    },
    {
      "level": 2,
      "heading": "API",
      "content": "{لینک به openapi.yaml یا خلاصه نقاط پایانی}"
    },
    {
      "level": 2,
      "heading": "رویدادها",
      "content": ""
    },
    {
      "level": 3,
      "heading": "منتشر می‌کند (Publishes)",
      "content": "{لیست رویدادهای خروجی}"
    },
    {
      "level": 3,
      "heading": "مصرف می‌کند (Subscribes)",
      "content": "{لیست رویدادهای ورودی}"
    },
    {
      "level": 2,
      "heading": "دیتابیس",
      "content": "{موتور دیتابیس، محل فایل طرح}"
    },
    {
      "level": 2,
      "heading": "وابستگی‌ها",
      "content": "{سرویس‌های دیگری که این سرویس مستقیماً صدا می‌زند}\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "2. مثال کامل",
      "content": "```markdown"
    },
    {
      "level": 1,
      "heading": "سرویس سفارش (Order Service)",
      "content": "> مدیریت چرخه عمر سفارشات از ایجاد تا تحویل و اختلاف"
    },
    {
      "level": 2,
      "heading": "مسئولیت‌ها",
      "content": "- ایجاد و مدیریت سفارشات\n- مدیریت وضعیت‌های سفارش (Pending → Paid → Delivered → Completed)\n- مدیریت اختلافات و انصراف\n- انتشار رویدادهای مرتبط با سفارش"
    },
    {
      "level": 2,
      "heading": "شروع سریع",
      "content": "# order-service بخشی از monorepo است — clone کل repo:\n    git clone https://github.com/nons/nons-api\n    cd nons-api/services/order-service\n    cd order-service\n    cp .env.example .env\n    npm install\n    npm run dev\n\nسرویس در `http://localhost:3000` در دسترس خواهد بود."
    },
    {
      "level": 2,
      "heading": "متغیرهای محیط",
      "content": "| متغیر | الزامی | مقدار پیش‌فرض | توضیحات |\n|---|---|---|---|\n| `ORDER_DB_URL` | بله | `postgres://localhost:5432/order_db` | آدرس دیتابیس PostgreSQL |\n| `ORDER_REDIS_URL` | خیر | `redis://localhost:6379` | آدرس Redis برای کش |\n| `ORDER_GUARANTEE_TIMEOUT_HOURS` | خیر | `24` | مدت زمان گارانتی بر حسب ساعت |\n| `NATS_URL` | بله | `nats://localhost:4222` | آدرس NATS server |\n| `NATS_CLUSTER_ID` | بله | `nons-cluster` | شناسه کلاستر NATS |"
    },
    {
      "level": 2,
      "heading": "API",
      "content": "مشخصات کامل API در [openapi.yaml](openapi.yaml) موجود است."
    },
    {
      "level": 3,
      "heading": "نقاط پایانی اصلی",
      "content": "| Method | Path | توضیحات |\n|---|---|---|\n| POST | `/v1/orders` | ایجاد سفارش جدید |\n| GET | `/v1/orders/:id` | دریافت جزئیات سفارش |\n| PATCH | `/v1/orders/:id/status` | به‌روزرسانی وضعیت سفارش |"
    },
    {
      "level": 2,
      "heading": "رویدادها",
      "content": ""
    },
    {
      "level": 3,
      "heading": "منتشر می‌کند (Publishes)",
      "content": "| رویداد | توضیحات |\n|---|---|\n| `nons.order.created` | سفارش جدید ایجاد شد |\n| `nons.order.paid` | سفارش پرداخت شد |\n| `nons.order.delivered` | سفارش تحویل شد |\n| `nons.order.disputed` | اختلاف برای سفارش ثبت شد |"
    },
    {
      "level": 3,
      "heading": "مصرف می‌کند (Subscribes)",
      "content": "| رویداد | منبع | عکس‌العمل |\n|---|---|---|\n| `nons.payment.released` | Payment Service | آزادسازی وجوه به فروشنده |\n| `nons.user.suspended` | Auth Service | لغو سفارش‌های در انتظار کاربر |"
    },
    {
      "level": 2,
      "heading": "دیتابیس",
      "content": "- **موتور:** PostgreSQL 15\n- **طرح:** [database.md](database.md)\n- **مهاجرت:** پوشه `migrations/` در ریشه سرویس"
    },
    {
      "level": 3,
      "heading": "موجودیت‌های اصلی",
      "content": "- `orders` — سفارشات\n- `order_items` — آیتم‌های سفارش\n- `order_status_history` — تاریخچه وضعیت‌ها"
    },
    {
      "level": 2,
      "heading": "وابستگی‌ها",
      "content": "| سرویس | نوع وابستگی |\n|---|---|\n| Auth Service | احراز هویت کاربران |\n| Payment Service | پرداخت و مدیریت Escrow |\n| Notification Service | ارسال نوتیفیکیشن به کاربران |\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "3. قوانین",
      "content": "| قانون | توضیح |\n|---|---|\n| ترتیب ثابت | بخش‌ها باید به همین ترتیب باشند |\n| همه بخش‌ها اجباری | حتی اگر خالی باشند — `---` بگذارید |\n| زبان | توضیحات فارسی، مقادیر و نام‌ها انگلیسی |\n| به‌روزرسانی | هر PR که رفتار را تغییر می‌دهد باید README را به‌روز کند |\n| لینک‌ها | به `openapi.yaml` و `database.md` لینک مستقیم بدهید |"
    }
  ]
}