3x-ui/docs/panel-guide/16-unified-product-roadmap.md

# 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.