انبار IP ثابت — راهنمای ادمین شرکت

| فیلد | مقدار |
|------|--------|
| **نسخه** | 1.3 |
| **آخرین بروزرسانی** | 2026-09-16 |
| **ماژول** | Inventory (Static IP) |
| **مخاطب** | ادمین شرکت (Tenant `/panel`) |

---

هدف

موجودی آدرس IP مشخص در BSS (جدا از افزایش `num_ips` در Virtualizor) با استخر جدا per نوع سرویس (ADSL / FTTH / LTE / Wireless / MVNO / VPS / سایر).

فروش از طریق **گزینه قابل‌تنظیم** با `inventory_kind = static_ip`؛ با خرید، IP از استخر همان scope تخصیص می‌شود تا پایان سرویس والد؛ با حذف افزونه یا لغو والد آزاد می‌شود.

---

منو (`/panel`)

مسیر: `/panel` → **انبار** → **IP ثابت**

| آیتم | کاربرد |
|------|--------|
| **استخرها** | CRUD + scope + فعال/غیرفعال + ایمپورت CIDR + دکمه **آموزش** |
| **آدرس‌ها** | لیست فیلتر وضعیت/استخر/نوع سرویس + مشتری + سرویس + تاریخ پایان + دکمه **آموزش** |

حذف استخر

حذف موقت استخر فقط وقتی مجاز است که:

همهٔ آدرس‌های استخر وضعیت **آزاد** (`available`) داشته باشند و به اشتراک وصل نباشند

تخصیص فعال (`reserved` / `assigned`) روی استخر نباشد

در غیر این صورت دکمهٔ حذف مخفی است و پیام «حذف مجاز نیست» نمایش داده می‌شود.

روی فرم گزینه قابل‌تنظیم هم دکمه **آموزش IP ثابت** هست.

ریسلر انبار را مدیریت نمی‌کند (همان ADR-020 / ADR-022).

---

راه‌اندازی سریع

**استخر جدید** با نوع سرویس مناسب (مثلاً FTTH)

**ایمپورت CIDR** (مثلاً `185.1.2.0/30`) یا افزودن دستی آدرس

روی افزونه/گزینه قابل‌تنظیم: **اتصال به انبار = IP ثابت** و **استخر سرویس** همان scope

در choice عنوانی مثل «۱ IP ثابت» بگذارید — عدد از برچسب خوانده می‌شود

---

Lifecycle

| رویداد | عمل |
|--------|------|
| خرید موفق (افزونه یا محصول با گزینه IP) | تخصیص از استخر؛ `ends_at = parent.ends_at` |
| تمدید سرویس والد | به‌روزرسانی `ends_at` تخصیص‌ها |
| حذف افزونه IP | آزادسازی |
| لغو سفارش / اتمام والد | آزادسازی |
| کمبود موجودی | خطا قبل از ثبت/پرداخت |

پس از تخصیص، روی اشتراک والد ذخیره می‌شود:

| کلید metadata | محتوا |
|---------------|--------|
| `static_ips` | لیست آدرس‌ها |
| `static_ip_gateway` | Gateway استخر (اگر چند استخر با gateway متفاوت: جدا با «، ») |
| `static_ip_subnet` | Subnet استخر (`cidr`؛ مثلاً `185.10.20.0/28`) |
| `static_ip_assignments` | جزئیات هر تخصیص: `address` / `gateway` / `cidr` / `subnet` / `pool_id` |

در پورتال مشتری و پنل VPS (Hostname/IP)، **Gateway** و **Subnet** کنار IP ثابت نمایش داده می‌شوند. مقادیر از فیلدهای **Gateway** و **CIDR** همان استخر انبار خوانده می‌شوند — روی فرم استخر (`/panel` → انبار → IP ثابت → استخرها) پر کنید.

فاز ۱: همگام‌سازی با Virtualizor/Proxmox و انتخاب دستی IP توسط مشتری خارج از محدوده است.

---

جداول

`inv_ip_pools`

`inv_ip_addresses`

`inv_ip_allocations`

سرویس‌ها: `StaticIpInventoryService`، `StaticIpOrderService`

---

مرتبط

[product-addons.md](product-addons.md)

[tenant-panel.md](tenant-panel.md)

ADR-022 در `docs/DECISIONS.md`