docs(panel-guide): add marzban and unified product roadmaps

PANEL_GUIDE_SOURCE_OF_TRUTH.md

@@ -1228,6 +1228,7 @@ Index:
 - `docs/panel-guide/11-troubleshooting-runbook.md`
 - `docs/panel-guide/12-change-management-and-rollout.md`
 - `docs/panel-guide/13-feature-file-map-and-decision-log.md`
+- `docs/panel-guide/14-marzban-inspired-roadmap.md`
 - `docs/panel-guide/99-session-context-transfer-2026-02-18.md`
 
 Use those files for day-to-day operations and implementation reference.

docs/panel-guide/14-marzban-inspired-roadmap.md

@@ -0,0 +1,210 @@
+# 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.

docs/panel-guide/15-remnawave-hiddify-analysis.md

@@ -0,0 +1,82 @@
+# 15. Remnawave + Hiddify Analysis
+
+## Purpose
+
+This document captures features from `remnawave/panel` and `hiddify/Hiddify-Manager` that can inspire our custom `3x-ui`, with focus on low-breakage adoption.
+
+## Remnawave (panel) Findings
+
+### Product shape
+
+- TypeScript-oriented ecosystem (panel/backend/frontend/node tooling around Xray).
+- Strong operator UX around users, nodes, templates, routing rules, squads, and notifications.
+
+### Standout capabilities
+
+- Squad model: group-based control over what users can access.
+- Template/rule engine: conditional responses and per-client template behavior.
+- Webhooks: event delivery for user/node/service/error events.
+- Notification tuning: per-channel per-event control.
+- HWID device limits and device history/management.
+- SDK and automation orientation for external integrations.
+
+### What to borrow first
+
+1. Event webhooks in `3x-ui` for user/client/inbound lifecycle changes.
+2. Notification matrix (events x channels) rather than global on/off.
+3. Device management UI for client anti-sharing controls.
+4. A simplified policy-group model (Remnawave squads inspiration) for assigning many inbounds to many clients cleanly.
+
+## Hiddify-Manager Findings
+
+### Product shape
+
+- Operationally heavy Linux stack: panel + generated configs + many services.
+- Template generation pipeline for Xray/Sing-box/HAProxy/nginx and helper services.
+
+### Standout capabilities
+
+- Broad protocol and transport coverage (including newer stacks).
+- HAProxy/nginx map-based dispatch and multiplexing.
+- Auto-update/backup and operational scripts.
+- Extra operator tooling (short links, helper pages, bot integration).
+
+### What to borrow first
+
+1. Template-first config generation mindset for complex transport combinations.
+2. Optional HAProxy/nginx routing templates as an advanced deployment profile.
+3. Operational guardrails: backup/update helpers and health checks.
+
+## Fit For Custom 3x-ui
+
+### Low-risk, high-value (phase 1)
+
+1. Webhook events and signed delivery.
+2. Notification preference matrix.
+3. Better client detail pages (usage, devices, assignment visibility).
+
+### Medium effort (phase 2)
+
+1. Policy groups for inbound bundles and client assignment.
+2. Template/rule editor for client-aware output behavior.
+3. More advanced export/subscription templates.
+
+### High effort / platform-level (phase 3)
+
+1. Full map-based edge routing orchestration (HAProxy/nginx style).
+2. Multi-core orchestration parity (Xray + Sing-box in one control plane).
+3. Full installer-grade lifecycle automation comparable to Hiddify.
+
+## Recommended Direction
+
+Prefer **Remnawave-inspired UX/control-plane features first** because they map well to our current custom `3x-ui` UI/backend extension path.
+
+Adopt **Hiddify-inspired ops architecture selectively** as optional deployment modules, not as core assumptions for all users.
+
+## Safe Implementation Rules
+
+1. Add each feature behind a feature flag.
+2. Keep backward compatibility for existing inbound/client behavior.
+3. Add migration scripts with rollback steps.
+4. Ship contract tests for webhook payloads and assignment logic.
+5. Validate new behavior in local sqlite dev + one staging VPS before production rollout.

docs/panel-guide/16-unified-product-roadmap.md

@@ -0,0 +1,221 @@
+# 16. Unified Product Roadmap (3x-ui Custom)
+
+## Objective
+
+Build a production-grade custom `3x-ui` that keeps current compatibility while adding modern client management, automation, policy control, and optional advanced ops capabilities inspired by Marzban, Remnawave, and Hiddify.
+
+## Source of ideas
+
+- `3x-ui` baseline: inbound-centric model, compatibility, existing operator workflows.
+- Marzban inspiration: node architecture, webhook/admin automation, host/profile concepts.
+- Remnawave inspiration: squads/policy groups, template/rule engine, notification matrix, HWID management.
+- Hiddify inspiration: template-driven config generation, advanced edge routing, strong operational tooling.
+
+## Product principles
+
+1. Backward-compatible by default.
+2. Additive changes first, migrations only with rollback.
+3. Feature flags for every major module.
+4. Safe defaults for exposure, auth, and transport settings.
+5. Operator-first UX: fast bulk actions, clear observability, low-click routine tasks.
+
+## Current baseline (already done)
+
+- Centralized client page exists (`/panel/clients`) with master client + inbound assignment sync.
+- Local dev tooling exists (`justfile`, `air`, sqlite dev flow).
+- Documentation split exists under `docs/panel-guide`.
+
+## Roadmap phases
+
+## Phase 0: Stabilize Foundation (1 week)
+
+### Deliverables
+
+1. Harden current client-center behavior.
+2. Add regression tests for assignment/sync paths.
+3. Add lightweight structured audit for client mutations.
+
+### Acceptance criteria
+
+1. No regression in existing inbound CRUD and client operations.
+2. Sync errors are user-visible and recoverable.
+3. Automated tests cover add/update/delete + attach/detach flows.
+
+## Phase 1: Operator Productivity Core (2-3 weeks)
+
+### Deliverables
+
+1. Plan presets (`30d-100GB`, `90d-300GB`, `unlimited`) with one-click apply.
+2. Bulk client actions: extend expiry, add/reset quota, enable/disable, tag/comment edits.
+3. Better client details: assigned inbounds, usage summary, expiry status, quick actions.
+4. Audit log UI/API for sensitive changes.
+
+### Inspiration mapping
+
+- Marzban: plan-like lifecycle and operational workflows.
+- Remnawave: stronger user detail and admin ergonomics.
+
+### Acceptance criteria
+
+1. Operator can modify 100+ clients via previewed bulk action safely.
+2. Every sensitive operation writes immutable audit records.
+3. Average clicks for common tasks reduced (create client, assign inbounds, extend plan).
+
+## Phase 2: Automation and Integration (2 weeks)
+
+### Deliverables
+
+1. Webhook endpoints with per-event filtering and HMAC signatures.
+2. Delivery logs, retry policy, and test-send action.
+3. Notification matrix (event x channel) with sane defaults.
+
+### Inspiration mapping
+
+- Remnawave: webhook scopes + fine-grained notification tuning.
+- Marzban: external integration-friendly operator model.
+
+### Acceptance criteria
+
+1. Webhook payload contracts are versioned and documented.
+2. Failed deliveries are visible with retry status.
+3. Operators can disable noisy events without disabling all alerts.
+
+## Phase 3: Policy Groups and Access Model (2-3 weeks)
+
+### Deliverables
+
+1. Policy groups (squad-like) to assign bundles of inbounds/settings to clients.
+2. Group-level limits/metadata inheritance with per-client override.
+3. Group-based bulk assignment and membership management UI.
+
+### Inspiration mapping
+
+- Remnawave: Internal/External squad model.
+
+### Acceptance criteria
+
+1. Many-to-many assignment handled without manual per-inbound editing.
+2. Inheritance and override behavior is deterministic and documented.
+3. Migration from existing direct assignment remains seamless.
+
+## Phase 4: Template and Subscription Engine (3-4 weeks)
+
+### Deliverables
+
+1. Host/profile template manager with preview variables.
+2. Output templates by client/app/core (xray/sing-box/mihomo style profiles).
+3. Rule-based response behavior (safe subset first): header/app-based template selection.
+
+### Inspiration mapping
+
+- Remnawave: templates + response rules.
+- Marzban: host/profile customization model.
+
+### Acceptance criteria
+
+1. Operators can preview rendered output before publishing.
+2. Template changes are versioned and rollbackable.
+3. Existing subscription links continue working.
+
+## Phase 5: Security and Anti-Abuse Layer (2-3 weeks)
+
+### Deliverables
+
+1. Device tracking and optional HWID/device limits per client.
+2. Risk controls: suspicious device churn alerts, quick revoke flows.
+3. Policy options for account sharing tolerance level.
+
+### Inspiration mapping
+
+- Remnawave: HWID/device management and anti-sharing controls.
+
+### Acceptance criteria
+
+1. Device history is queryable per client.
+2. Operators can enforce or relax limits per policy group.
+3. Enforcement failures fail safe and are auditable.
+
+## Phase 6: Advanced Ops Profile (Optional, staged, 4-8 weeks)
+
+### Deliverables
+
+1. Template-driven advanced config generation module.
+2. Optional edge routing profile (HAProxy/nginx map-based patterns).
+3. Optional multi-core orchestration profile (xray + sing-box).
+4. Backup/update/health-check operational toolkit.
+
+### Inspiration mapping
+
+- Hiddify: config generation and ops automation.
+
+### Acceptance criteria
+
+1. Advanced profile is optional and isolated from default path.
+2. Health checks and rollback mechanisms are mandatory.
+3. Security review passes before enabling in production.
+
+## Cross-cutting workstreams
+
+## Data model and migration safety
+
+1. Every schema change gets forward + rollback migration plan.
+2. Soft launch new tables/columns before hard dependencies.
+3. Keep legacy APIs until replacement is validated.
+
+## API design and compatibility
+
+1. Version new APIs under clear prefixes when behavior differs.
+2. Keep old endpoint behavior stable unless explicitly deprecated.
+3. Add contract tests for webhook/template/assignment APIs.
+
+## UI/UX consistency
+
+1. Preserve current mental model for existing users.
+2. Expose advanced controls progressively (basic vs advanced tabs).
+3. Add inline docs/tooltips for protocol-sensitive fields.
+
+## Testing and quality gates
+
+1. Unit tests for model/service logic.
+2. Integration tests for db migrations and sync flows.
+3. UI flow tests (Playwright) for client lifecycle and bulk operations.
+4. Staging soak test before each phase release.
+
+## Security controls
+
+1. HMAC for outbound webhooks.
+2. RBAC prep for future multi-admin model.
+3. Secret rotation support for API tokens and webhook secrets.
+4. Harden defaults for exposed panels and management ports.
+
+## Release strategy
+
+1. Release per phase behind feature flags.
+2. Rollout order: local sqlite -> staging VPS -> production VPS.
+3. Each release ships with:
+   - migration notes
+   - rollback procedure
+   - updated docs in `docs/panel-guide`
+   - smoke test checklist
+
+## Success metrics
+
+1. Time to create + assign a client drops by at least 50%.
+2. Bulk operations complete with zero silent failures.
+3. Webhook delivery success rate stays above 99% after retries.
+4. Support incidents caused by misconfiguration trend downward.
+5. No increase in critical outages after enabling new modules.
+
+## Suggested execution order
+
+1. Phase 0 + Phase 1 immediately.
+2. Phase 2 next (automation unlock).
+3. Phase 3 and Phase 4 together only after Phase 1/2 are stable.
+4. Phase 5 once policy groups are in place.
+5. Phase 6 only as opt-in advanced deployment profile.
+
+## Non-goals (for now)
+
+1. Full rewrite of 3x-ui core architecture.
+2. Mandatory multi-core or edge-router stack for all users.
+3. Breaking changes to existing inbound-native workflows.

docs/panel-guide/README.md

@@ -17,7 +17,10 @@ This folder is the focused replacement for the monolithic `PANEL_GUIDE_SOURCE_OF
 11. `11-troubleshooting-runbook.md`
 12. `12-change-management-and-rollout.md`
 13. `13-feature-file-map-and-decision-log.md`
-14. `99-session-context-transfer-2026-02-18.md`
+14. `14-marzban-inspired-roadmap.md`
+15. `15-remnawave-hiddify-analysis.md`
+16. `16-unified-product-roadmap.md`
+17. `99-session-context-transfer-2026-02-18.md`
 
 ## Recommended read order
 
@@ -32,7 +35,10 @@ This folder is the focused replacement for the monolithic `PANEL_GUIDE_SOURCE_OF
 9. Read `11` for incident/debug operation.
 10. Read `12` before any risky rollout/migration.
 11. Read `13` before modifying custom feature code.
-12. Read `99` for full session handoff context.
+12. Read `14` for Marzban-inspired implementation roadmap.
+13. Read `15` for Remnawave + Hiddify inspiration and adoption phases.
+14. Read `16` for the complete unified execution roadmap.
+15. Read `99` for full session handoff context.
 
 ## Scope note