3x-ui/docs/panel-guide/14-marzban-inspired-roadmap.md

# 14. Marzban-Inspired Roadmap (Implementation Draft)

## Goal

Borrow high-impact ideas from Marzban and implement them safely in custom 3x-ui without breaking existing inbound-native workflows.

## Reference baseline

This draft is based on Marzban concepts visible in official repo/docs (node architecture, host settings, webhooks, CLI/admin flows), adapted to current 3x-ui architecture and your implemented client-center extension.

---

## Phase 1 (fast, low-risk, high ROI)

### 1) Plan Presets (User Templates)

Purpose:
- Reusable client plans (for example: `30d-100GB`, `90d-300GB`, `Unlimited`).

DB:
- `plan_presets`:
  - `id`, `user_id`, `name`, `total_gb`, `duration_days`, `limit_ip`, `enable`, `comment`, `created_at`, `updated_at`

API:
- `GET /panel/api/plans/list`
- `POST /panel/api/plans/add`
- `POST /panel/api/plans/update/:id`
- `POST /panel/api/plans/del/:id`

UI:
- Add `Plans` tab/page.
- In `/panel/clients`, add “Apply Plan” selector for create/edit.

Acceptance:
- Create plan once and apply to new/existing master clients in one click.

---

### 2) Webhook Events

Purpose:
- External automation (billing, CRM, alerts) decoupled from panel internals.

DB:
- `webhook_endpoints`:
  - `id`, `user_id`, `name`, `url`, `secret`, `enabled`, `event_filter_json`, `created_at`, `updated_at`
- `webhook_deliveries`:
  - `id`, `endpoint_id`, `event`, `payload_json`, `status_code`, `success`, `error`, `created_at`

Events (initial):
- `master_client.created`
- `master_client.updated`
- `master_client.deleted`
- `assignment.created`
- `assignment.updated`
- `assignment.deleted`
- `inbound.client.sync_failed`

API:
- `GET /panel/api/webhooks/list`
- `POST /panel/api/webhooks/add`
- `POST /panel/api/webhooks/update/:id`
- `POST /panel/api/webhooks/del/:id`
- `GET /panel/api/webhooks/deliveries`
- `POST /panel/api/webhooks/test/:id`

Implementation note:
- HMAC signature header with endpoint secret.
- Non-blocking async delivery queue + retry policy.

Acceptance:
- Webhook test succeeds and deliveries are visible/auditable.

---

### 3) Host/Profile Settings Templates

Purpose:
- Better subscription/profile text rendering with variables.

DB:
- `host_templates`:
  - `id`, `user_id`, `name`, `template_text`, `enabled`, `created_at`, `updated_at`

Template variables (v1):
- `{{master_name}}`
- `{{email_prefix}}`
- `{{inbound_remark}}`
- `{{protocol}}`
- `{{port}}`
- `{{expiry_time}}`
- `{{days_left}}`
- `{{total_gb}}`
- `{{used_gb}}`
- `{{remaining_gb}}`

API:
- `GET /panel/api/host-templates/list`
- `POST /panel/api/host-templates/add`
- `POST /panel/api/host-templates/update/:id`
- `POST /panel/api/host-templates/del/:id`
- `POST /panel/api/host-templates/preview`

UI:
- `Settings -> Subscription` add template manager/preview.

Acceptance:
- Template preview and rendered subscription info align with selected inbound/client.

---

## Phase 2 (medium effort, operational depth)

### 4) Bulk Policy Actions

Purpose:
- Apply +days/+GB/enable/disable/comments to selected master clients.

API:
- `POST /panel/api/clients/bulk`
  - filters: ids, tags, enabled state
  - operations: set/adjust fields

Safety:
- Dry-run mode (`preview=true`) returns mutation summary.

Acceptance:
- Admin can bulk-modify 100+ clients with preview and audit trail.

---

### 5) Audit Log

DB:
- `audit_logs`:
  - actor, action, target_type, target_id, before_json, after_json, created_at

Coverage:
- Client-center, plan, webhook, template, inbound sync actions.

Acceptance:
- Every sensitive action has immutable audit row.

---

## Phase 3 (advanced, higher risk)

### 6) Multi-admin Ownership / RBAC

Roles:
- `owner`, `admin`, `operator`, `viewer`

Scope:
- Per-user ownership of master clients and optional inbound scope controls.

Acceptance:
- Role matrix enforced on APIs and UI actions.

---

### 7) Node Architecture (Marzban-style inspiration)

Purpose:
- Manage remote xray nodes from a central control panel.

Model (initial):
- Central panel keeps desired state.
- Node agent pulls signed config deltas + pushes health/traffic.

Major components:
- `nodes` table and node auth keys
- Node heartbeat + capability registry
- Config distribution queue
- Health and lag monitoring

Acceptance:
- One remote node managed reliably with inbound/client sync and health checks.

---

## Cross-cutting engineering rules

1. Additive-first: keep old APIs/UI working.
2. Feature flags for each new module.
3. Idempotent sync operations.
4. Queue + retries for external IO (webhooks/nodes).
5. Full rollback path (DB backup + binary rollback).

---

## Suggested first implementation sprint (5-7 days)

1. `plan_presets` DB/API/UI
2. Webhook endpoints + delivery log + test button
3. Host template CRUD + preview
4. Minimal audit logs for these three modules

Deliverable at sprint end:
- Operators can provision clients faster, integrate billing/automation, and improve subscription profile quality without architecture-breaking changes.

---

## Fit with current custom code

Already aligned foundations:
- Master client model exists (`MasterClient`, `MasterClientInbound`).
- Central clients API/UI exists (`/panel/clients`, `/panel/api/clients/*`).
- Dev workflow exists (`.air.toml`, `justfile`).

So this roadmap extends current direction directly, no redesign needed for Phase 1.