Lukas
275aeb4544
- Add /api/setup/unresolved/done endpoint to mark phase complete - NFO scan now runs after series sync during initialization - Middleware redirects to /login after setup complete (was /loading) - Done button allows skipping folder resolution with redirect to NFO scan phase
206 lines
8.2 KiB
Markdown
206 lines
8.2 KiB
Markdown
# Navigation & Redirect Logic
|
|
|
|
This document describes the setup flow navigation, covering how users progress from initial setup through to the main application.
|
|
|
|
## Overview
|
|
|
|
The application uses a middleware-based redirect system to ensure users complete setup before accessing the main app. The flow involves multiple pages handling setup completion, unresolved folder detection, and initialization.
|
|
|
|
## Setup Flow
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|
│ SETUP FLOW │
|
|
├─────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ /setup ──► /loading ──► /setup/unresolved ──► /loading ──► /login │
|
|
│ │ │ │ │ │
|
|
│ │ │ │ │ │
|
|
│ ▼ ▼ ▼ ▼ │
|
|
│ (first (Series Scan + (has folders) (all resolved) │
|
|
│ time) NFO Scan) │ │
|
|
│ │ │ │
|
|
│ │ │ │
|
|
│ │ ▼ │
|
|
│ │ [Done button] ──► marks complete │
|
|
│ │ │ │
|
|
│ │ ▼ │
|
|
│ │ /loading (NFO phase runs again) │
|
|
│ │ │ │
|
|
│ └────────┴─────────────────────────────────────┘
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
**New Navigation Order:**
|
|
1. `/setup` → Initial configuration
|
|
2. `/loading` → Series scan + NFO scan
|
|
3. `/setup/unresolved` → Resolve folders (if any)
|
|
4. `/loading` → NFO scan runs again
|
|
5. `/login` → Authentication
|
|
|
|
**Key Changes:**
|
|
- After `/setup/unresolved`, the "Done" button marks the phase as complete
|
|
- Revisiting `/setup/unresolved` after completion → redirects to `/loading`
|
|
- `/loading` always goes to `/setup/unresolved` if unresolved folders exist
|
|
- NFO scan runs as a separate phase after series sync during initialization
|
|
|
|
## Middleware: SetupRedirectMiddleware
|
|
|
|
**File:** `src/server/middleware/setup_redirect.py`
|
|
|
|
The middleware intercepts all requests and redirects to `/setup` if:
|
|
- No master password is configured
|
|
- Configuration file is missing or invalid
|
|
|
|
### Exempt Paths (always accessible)
|
|
|
|
| Path | Purpose |
|
|
|------|---------|
|
|
| `/setup` | Initial setup page |
|
|
| `/setup/unresolved` | Unresolved folder resolution |
|
|
| `/loading` | Initialization progress page |
|
|
| `/login` | Authentication |
|
|
| `/api/auth/*` | Auth endpoints |
|
|
| `/api/config/*` | Config API |
|
|
| `/api/health` | Health check |
|
|
| `/static/*` | Static assets |
|
|
|
|
### Middleware Logic
|
|
|
|
1. **Setup incomplete** → Redirect to `/setup`
|
|
2. **Setup complete, accessing `/setup`** → Redirect to `/login`
|
|
3. **Setup complete, accessing `/loading`** → Allow access (page handles its own redirect)
|
|
4. **Setup complete, accessing `/setup/unresolved`**:
|
|
- If `unresolved_completed` flag is set → Redirect to `/loading`
|
|
- Otherwise → Allow access
|
|
5. **API requests during setup** → Return 503 with `setup_url`
|
|
|
|
## Pages
|
|
|
|
### 1. Setup Page (`/setup`)
|
|
|
|
**File:** `src/server/web/templates/setup.html`
|
|
|
|
Handles initial configuration:
|
|
- Master password creation
|
|
- Anime directory selection
|
|
- Database initialization
|
|
|
|
**Post-completion flow:**
|
|
- Redirects to `/loading` to begin initialization
|
|
|
|
### 2. Loading Page (`/loading`)
|
|
|
|
**File:** `src/server/web/templates/loading.html`
|
|
|
|
Shows initialization progress via WebSocket:
|
|
- Series scanning
|
|
- Database population
|
|
- Logo/image loading
|
|
|
|
**Post-initialization flow:**
|
|
```javascript
|
|
async function checkUnresolvedAndProceed() {
|
|
// Fetch unresolved folders via API
|
|
const res = await fetch('/api/setup/unresolved', {
|
|
headers: { 'Authorization': `Bearer ${token}` }
|
|
});
|
|
const folders = await res.json();
|
|
|
|
if (folders.length > 0) {
|
|
// Has unresolved folders → go to resolution page
|
|
window.location.href = '/setup/unresolved';
|
|
} else {
|
|
// No unresolved folders → go to login
|
|
window.location.href = '/login';
|
|
}
|
|
}
|
|
```
|
|
|
|
### 3. Unresolved Folders Page (`/setup/unresolved`)
|
|
|
|
**File:** `src/server/web/templates/unresolved.html`
|
|
|
|
Allows manual resolution of folders that couldn't be auto-matched:
|
|
- Shows list of unresolved folders
|
|
- Provides search suggestions
|
|
- Input field for entering provider key
|
|
- Resolve/delete actions
|
|
- **Done button** at top to complete the phase without resolving all folders
|
|
|
|
**Post-resolution flow:**
|
|
```javascript
|
|
// After clicking "Done" button
|
|
async function handleDone() {
|
|
// Call API to mark phase as complete
|
|
await fetch('/api/setup/unresolved/done', { method: 'POST' });
|
|
// Redirect to loading for final NFO scan
|
|
window.location.href = '/loading';
|
|
}
|
|
```
|
|
|
|
**Done button behavior:**
|
|
- Marks all remaining folders as handled
|
|
- Sets `unresolved_completed` flag in config
|
|
- Redirects to `/loading` to run final NFO scan
|
|
- After completion, `/setup/unresolved` becomes inaccessible (redirects to `/loading`)
|
|
|
|
### 4. Login Page (`/login`)
|
|
|
|
**File:** `src/server/web/templates/login.html`
|
|
|
|
Authentication page. After successful login → redirect to `/` (main app).
|
|
|
|
## API Endpoints
|
|
|
|
### Unresolved Folders API
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| `GET` | `/api/setup/unresolved` | List all unresolved folders |
|
|
| `GET` | `/api/setup/unresolved/{folder_name}` | Get specific folder details |
|
|
| `POST` | `/api/setup/unresolved/{folder_name}/resolve` | Resolve with provider key |
|
|
| `POST` | `/api/setup/unresolved/{folder_name}/search` | Re-search for matches |
|
|
| `DELETE` | `/api/setup/unresolved/{folder_name}` | Remove folder from tracking |
|
|
| `POST` | `/api/setup/unresolved/done` | Mark unresolved phase as complete |
|
|
|
|
### Auth API
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| `POST` | `/api/auth/setup` | Create master password |
|
|
| `POST` | `/api/auth/login` | Authenticate |
|
|
| `POST` | `/api/auth/logout` | End session |
|
|
|
|
## Key Files
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `src/server/middleware/setup_redirect.py` | Redirect middleware |
|
|
| `src/server/controllers/page_controller.py` | Page route handlers |
|
|
| `src/server/web/templates/setup.html` | Setup template |
|
|
| `src/server/web/templates/loading.html` | Loading template |
|
|
| `src/server/web/templates/unresolved.html` | Unresolved folders template |
|
|
| `src/server/api/setup_endpoints.py` | Unresolved folders API |
|
|
| `src/server/database/service.py` | UnresolvedFolderService |
|
|
|
|
## Common Issues
|
|
|
|
### Redirect Loop
|
|
|
|
**Symptom:** Browser keeps redirecting between pages.
|
|
|
|
**Causes:**
|
|
1. `loading.html` always redirected to `/setup/unresolved` without checking if any exist
|
|
2. `unresolved.html` redirected to `/` which middleware redirected back to `/login`
|
|
|
|
**Fix:** See the navigation logic updates in loading.html and unresolved.html.
|
|
|
|
### Can't Access Unresolved Page After Setup
|
|
|
|
**Symptom:** Middleware redirects to `/login` instead of allowing access to `/setup/unresolved`.
|
|
|
|
**Cause:** `/setup/unresolved` is in the exempt paths but the request may not be reaching it due to completion check timing.
|
|
|
|
**Fix:** The middleware allows access to `/loading` which handles the redirect to `/setup/unresolved` after initialization. |