fix: resolve TypeScript type-check errors

- Add cacheHitRate to ProxyMetricsService, handler, and router schema - Fix StatCard to support string values and purple accent - Fix duplicate tabs keys in i18n translations (EN/ZH/RU) - Add missing cacheStatus translations across all languages
2026-04-23 02:50:09 -03:00
1 parent 0be7d7fea2
commit fd1b2b8bc0
@@ -0,0 +1,125 @@
+# Proxy Page — Advanced Features Hidden in Backend
+
+> Generated from oracle agent analysis of `src/server/modules/proxy/`
+> Date: 2026-04-22
+
+## Discovery
+The backend (`ProxyService`, `ProxyController`, `ProxyModule`) implements many sophisticated features that are **completely invisible** in the current UI. The proxy page only shows: port, protocol, API key, and basic start/stop.
+
+## Hidden Backend Features
+
+### 1. Advanced Routing & Scheduling Controls
+**Backend location**: `proxy.service.ts`, `proxy-scheduler.service.ts`
+**What's implemented**:
+- `scheduler.maxRequestsPerAccount`: Limit requests per account before switching
+- `scheduler.maxWaitTime`: Max time to wait for an available account
+- `scheduler.retryAttempts`: Number of retries per request
+- `scheduler.backoffStrategy`: `exponential` | `linear` | `fixed`
+- `scheduler.priorityAccounts`: Array of account IDs to prioritize
+
+**UI exposure**: None. These are hardcoded or set via config files only.
+
+### 2. Live Traffic Inspector
+**Backend location**: `traffic-logger.service.ts`
+**What's implemented**:
+- `TrafficLogger` captures every request/response with metadata
+- Fields: timestamp, requestId, accountId, model, promptTokens, completionTokens, latency, status, error
+- Log rotation and cleanup policies
+- Export to JSON/CSV
+
+**UI exposure**: None. Logs are only written to files.
+
+### 3. Circuit Breaker Dashboard
+**Backend location**: `proxy-circuit-breaker.service.ts`
+**What's implemented**:
+- Per-account circuit breaker state: `CLOSED`, `OPEN`, `HALF_OPEN`
+- Failure threshold and recovery timeout
+- When open: requests fail fast without hitting the API
+- Metrics: failure rate, last failure time, consecutive successes
+
+**UI exposure**: None. Circuit breaker state is internal only.
+
+### 4. Parity Testing Sandbox
+**Backend location**: `proxy-parity.service.ts`
+**What's implemented**:
+- Send identical requests to multiple models simultaneously
+- Compare responses for consistency
+- Detect model drift or API changes
+- Configurable test suites
+
+**UI exposure**: None. Only accessible via manual API calls or scripts.
+
+### 5. Custom Model Mapping Table
+**Backend location**: `proxy-model-mapper.service.ts`
+**What's implemented**:
+- Dynamic model resolution: `claude-opus-4` → `gemini-3-flash`
+- User-defined mappings stored in database
+- Regex-based model matching
+- Fallback chain: if mapped model unavailable, try next
+
+**UI exposure**: A static, read-only list is shown. No editing capability.
+
+### 6. Upstream Proxy Configuration
+**Backend location**: `proxy-upstream.service.ts`
+**What's implemented**:
+- `upstreamProxy.url`: Route all traffic through another proxy
+- `upstreamProxy.auth`: Basic auth or bearer token for upstream
+- `upstreamProxy.bypassList`: Domains to bypass
+
+**UI exposure**: None. Set via environment variables only.
+
+### 7. IDE Integration Quick-Setup
+**Backend location**: `proxy-config.service.ts` — `generateIdeConfig()`
+**What's implemented**:
+- Generates ready-to-paste configs for:
+  - Cursor (`settings.json`)
+  - VS Code + Cline/Roo Code
+  - OpenCode (`.env`)
+  - Claude Code (`claude_desktop_config.json`)
+  - Generic OpenAI client
+- Includes local IP detection, port, and API key
+
+**UI exposure**: Code examples are generic curl snippets. No IDE-specific configs.
+
+### 8. Health & Performance Metrics
+**Backend location**: `proxy-metrics.service.ts`
+**What's implemented**:
+- Request latency histogram (p50, p95, p99)
+- Requests per minute counter
+- Error rate by status code
+- Active connection gauge
+- Token throughput (tokens/minute)
+- Account utilization percentage
+
+**UI exposure**: None. Metrics are only exposed via a `/metrics` endpoint for Prometheus.
+
+### 9. Request Replay & Debug Tool
+**Backend location**: `proxy-replay.service.ts`
+**What's implemented**:
+- Store recent requests (last 100 by default)
+- Replay any request with one click
+- Modify headers/body before replay
+- Compare original vs. replayed response
+- Export request as curl command
+
+**UI exposure**: None.
+
+### 10. Global Timeout & Max Wait Controls
+**Backend location**: `proxy-config.service.ts`
+**What's implemented**:
+- `requestTimeout`: Global timeout for all upstream requests
+- `connectTimeout`: TCP connection timeout
+- `maxWaitTime`: Max time to wait for an available account
+- `idleTimeout`: Close idle connections after N seconds
+
+**UI exposure**: None. Hardcoded defaults.
+
+---
+
+## Recommendation
+Create a new "Advanced" tab on the proxy page that exposes these features progressively:
+1. **Phase 1**: Read-only views (circuit breaker status, health metrics, traffic logs)
+2. **Phase 2**: Interactive controls (model mapping editor, scheduler settings)
+3. **Phase 3**: Power-user tools (replay, parity testing, upstream proxy config)
+
+This would transform the proxy page from a simple on/off switch into a comprehensive API gateway dashboard.