132 lines
6.7 KiB
Markdown
132 lines
6.7 KiB
Markdown
# Veza Integration Reference
|
||
|
||
## 1. Global Configuration
|
||
|
||
### Network & Environment
|
||
| Config | Value / Default | Source of Truth |
|
||
|--------|----------------|-----------------|
|
||
| **Backend Port** | `:8080` (Default) | `cmd/api/main.go` |
|
||
| **Frontend Port** | `:3000` or `:5173` | `vite.config.ts` |
|
||
| **API Base URL** | `http://localhost:8080` | `apps/web/src/config/env.ts` (`VITE_API_URL`) |
|
||
| **Auth Header** | `Authorization: Bearer <token>` | `apps/web/src/services/api/client.ts` |
|
||
| **Time Format** | ISO 8601 Strings (`2023-12-25T15:04:05Z`) | JSON serialization of `time.Time` |
|
||
|
||
### System Limits
|
||
| Parameter | Limit | implemented In |
|
||
|-----------|-------|----------------|
|
||
| **Max Track Size** | 100 MB | `internal/core/track/service.go` |
|
||
| **Supported Audio** | MP3, FLAC, WAV, OGG, M4A, AAC | `internal/core/track/service.go` |
|
||
| **Request Timeout** | 10s (Scan), 30s (Upload/Assembly) | `internal/core/track/handler.go` |
|
||
| **Client Timeout** | 10,000ms | `apps/web/src/services/api/client.ts` |
|
||
|
||
---
|
||
|
||
## 2. API Surface Coverage
|
||
|
||
This table compares available Backend routes with Frontend service implementations.
|
||
|
||
### 🟢 Fully Implemented | ⚠️ Partial / Discrepancy | ❌ Missing in Frontend
|
||
|
||
#### Auth & Users
|
||
| Method | URL | Frontend Function | Status | Notes |
|
||
|--------|-----|-------------------|--------|-------|
|
||
| `POST` | `/api/v1/auth/login` | `authApi.login` | 🟢 | |
|
||
| `POST` | `/api/v1/auth/register` | `authApi.register` | 🟢 | |
|
||
| `POST` | `/api/v1/auth/refresh` | `client.ts` (interceptor) | 🟢 | Auto-refresh on 401 |
|
||
| `POST` | `/api/v1/auth/logout` | `authApi.logout` | 🟢 | |
|
||
| `GET` | `/api/v1/auth/me` | `authApi.getMe` | 🟢 | |
|
||
| `GET` | `/api/v1/users/:id` | `userApi.getUser` | 🟢 | |
|
||
| `PUT` | `/api/v1/users/:id` | `userApi.updateUser` | 🟢 | Requires Ownership or Admin |
|
||
|
||
#### Tracks (Core)
|
||
| Method | URL | Frontend Function | Status | Notes |
|
||
|--------|-----|-------------------|--------|-------|
|
||
| `GET` | `/api/v1/tracks` | `trackApi.getTracks` | 🟢 | Supports pagination & filters |
|
||
| `POST` | `/api/v1/tracks` | `trackApi.uploadTrack` | ⚠️ | **CRITICAL GAP**: Backend ignores metadata fields (see Section 5) |
|
||
| `GET` | `/api/v1/tracks/:id` | `trackApi.getTrack` | 🟢 | |
|
||
| `PUT` | `/api/v1/tracks/:id` | `trackApi.updateTrack` | 🟢 | |
|
||
| `DELETE` | `/api/v1/tracks/:id` | `trackApi.deleteTrack` | ❌ | Function missing in `trackApi.ts` currently |
|
||
| `GET` | `/api/v1/tracks/:id/status` | `trackApi.pollTrackStatus` | 🟢 | Used for async upload polling |
|
||
|
||
#### Tracks (Features)
|
||
| Method | URL | Frontend Function | Status | Notes |
|
||
|--------|-----|-------------------|--------|-------|
|
||
| `GET` | `/api/v1/tracks/:id/stats` | `trackApi.getTrackStats` | 🟢 | |
|
||
| `GET` | `/api/v1/tracks/:id/history` | `trackApi.getTrackHistory` | 🟢 | |
|
||
| `GET` | `/api/v1/tracks/:id/download` | `trackApi.downloadTrack` | 🟢 | |
|
||
| `POST` | `/api/v1/tracks/:id/like` | `trackApi.likeTrack` | 🟢 | |
|
||
| `DELETE` | `/api/v1/tracks/:id/like` | `trackApi.unlikeTrack` | 🟢 | |
|
||
| `GET` | `/api/v1/tracks/:id/likes` | `trackApi.getTrackLikes` | 🟢 | |
|
||
| `POST` | `/api/v1/tracks/:id/share` | `trackApi.createTrackShare` | 🟢 | |
|
||
|
||
#### Upload (Chunked)
|
||
| Method | URL | Frontend Function | Status | Notes |
|
||
|--------|-----|-------------------|--------|-------|
|
||
| `POST` | `/api/v1/tracks/initiate` | *No direct function* | ❌ | Chunked upload logic seems internal to `trackApi.uploadTrack` or unimplemented |
|
||
| `POST` | `/api/v1/tracks/chunk` | *No direct function* | ❌ | |
|
||
| `POST` | `/api/v1/tracks/complete` | *No direct function* | ❌ | |
|
||
|
||
---
|
||
|
||
## 3. Data Models Discrepancies
|
||
|
||
### User Model
|
||
| Field | Backend (`models.User`) | Frontend (`interfaces/User`) | Match? |
|
||
|-------|-------------------------|------------------------------|--------|
|
||
| `ID` | `uuid.UUID` | `string` | ✅ |
|
||
| `Username` | `string` | `string` | ✅ |
|
||
| `Birthdate` | `*time.Time` (Nullable) | `string` | ⚠️ Frontend expects ISO string, Backend sends strict null or time |
|
||
| `UsernameChangedAt` | `*time.Time` | `string` | ⚠️ Same as above |
|
||
| `TokenVersion` | `int` | *Missing* | ⚠️ Internal field? |
|
||
|
||
### Track Model
|
||
| Field | Backend (`models.Track`) | Frontend (`interfaces/Track`) | Match? |
|
||
|-------|--------------------------|-------------------------------|--------|
|
||
| `UserID` | `CreatorID` (JSON) | `creator_id` | ✅ JSON tag aligns |
|
||
| `FileID` | `*uuid.UUID` (Nullable) | `string` | ⚠️ Optional vs Nullable |
|
||
| `Duration` | `int` (Seconds) | `number` | ✅ |
|
||
| `CoverArtPath` | `cover_art_path` | `cover_art_path` | ✅ |
|
||
| `StreamManifestURL`| `stream_manifest_url` | `stream_manifest_url` | ✅ |
|
||
| `UpdatedAt` | `time.Time` | `string` | ✅ |
|
||
|
||
---
|
||
|
||
## 4. Error Handling Protocol
|
||
|
||
### Protocol Mismatch Alert 🚨
|
||
There is a **divergence** between how the Backend reports errors and how the Frontend expects them.
|
||
|
||
**Backend Format (`middleware.ErrorHandler`):**
|
||
```json
|
||
{
|
||
"error": {
|
||
"code": 1234,
|
||
"message": "Error message",
|
||
"details": ["Validation error 1"]
|
||
}
|
||
}
|
||
```
|
||
*Note: The root object DOES NOT contain `success: false`.*
|
||
|
||
**Frontend Expectation (`utils/apiErrorHandler.ts`):**
|
||
1. Checks for `{ success: false, error: { ... } }`
|
||
2. OR Checks for `{ code: ..., message: ... }` (Root level)
|
||
|
||
**Consequence**: The Frontend `parseApiError` function will likely fail to extract the structured `ApiError` from the Backend's response, falling back to a generic "An unexpected error occurred" or the raw HTTP status message, losing valuable context (like validation details or specific error codes).
|
||
|
||
---
|
||
|
||
## 5. Action Items (Prioritized)
|
||
|
||
### 🚨 P0 - Critical Integration Fixes
|
||
* **Fix Error Parsing**: Update `apps/web/src/utils/apiErrorHandler.ts` to handle the `{ error: { code: ... } }` format (without `success` field) or update the Backend Middleware to wrap errors in `{ success: false, ... }`.
|
||
* **Fix Track Upload Metadata**: The Frontend creates a `FormData` with `title`, `artist`, `genre`, etc., but the Backend `UploadTrack` handler **ignores** all fields except `file`.
|
||
* *Remediation*: Update Backend `UploadTrack` to parse `c.PostForm` fields and pass them to `TrackService`.
|
||
|
||
### ⚠️ P1 - Type Safety & Feature Gaps
|
||
* **Implement Chunked Uploads**: The Frontend is missing the implementation for `/tracks/initiate`, `/tracks/chunk`, and `/tracks/complete`. Large file uploads will be unreliable.
|
||
* **Date Normalization**: Ensure Frontend correctly handles `null` values for `birthdate` and `username_changed_at` instead of potentially expecting empty strings or undefined.
|
||
|
||
### ℹ️ P2 - Completeness
|
||
* **Implement Delete**: Add `deleteTrack` to `trackApi.ts`.
|
||
* **Sync Async Flows**: Ensure the "Polling" logic in Frontend correctly interprets the Backend's `202 Accepted` response.
|