wip 12
This commit is contained in:
@@ -1,299 +0,0 @@
|
||||
# API V1 Admin vs Legacy Implementation Comparison
|
||||
|
||||
## Overview
|
||||
This document compares the V1 API admin implementations with the legacy API implementations to identify deviations and ensure adequate information is returned for the React app.
|
||||
|
||||
---
|
||||
|
||||
## 1. GET /admin
|
||||
|
||||
### V1 Implementation
|
||||
- Returns: `GetAdmin200JSONResponse` with `DatabaseInfo`
|
||||
- DatabaseInfo contains: `documentsSize`, `activitySize`, `progressSize`, `devicesSize`
|
||||
- Gets documents count from `GetDocumentsSize(nil)`
|
||||
- Aggregates activity/progress/devices across all users using `GetDatabaseInfo`
|
||||
|
||||
### Legacy Implementation
|
||||
- Function: `appGetAdmin`
|
||||
- Returns: HTML template page
|
||||
- No direct database info returned in endpoint
|
||||
- Template uses base template variables
|
||||
|
||||
### Deviations
|
||||
**None** - V1 provides more detailed information which is beneficial for React app
|
||||
|
||||
### React App Requirements
|
||||
✅ **Sufficient** - V1 returns all database statistics needed for admin dashboard
|
||||
|
||||
---
|
||||
|
||||
## 2. POST /admin (Admin Actions)
|
||||
|
||||
### V1 Implementation
|
||||
- Actions: `BACKUP`, `RESTORE`, `CACHE_TABLES`, `METADATA_MATCH`
|
||||
- Returns: `PostAdminAction200ApplicationoctetStreamResponse` with Body as io.Reader
|
||||
- BACKUP: Streams ZIP file via pipe
|
||||
- RESTORE: Returns success message as stream
|
||||
- CACHE_TABLES: Returns confirmation message as stream
|
||||
- METADATA_MATCH: Returns not implemented message as stream
|
||||
|
||||
### Legacy Implementation
|
||||
- Function: `appPerformAdminAction`
|
||||
- Actions: Same as V1
|
||||
- BACKUP: Streams ZIP with proper Content-Disposition header
|
||||
- RESTORE: After restore, redirects to `/login`
|
||||
- CACHE_TABLES: Runs async, returns to admin page
|
||||
- METADATA_MATCH: TODO (not implemented)
|
||||
|
||||
### Deviations
|
||||
1. **RESTORE Response**: V1 returns success message, legacy redirects to login
|
||||
- **Impact**: React app won't be redirected, but will get success confirmation
|
||||
- **Recommendation**: Consider adding redirect URL in response for React to handle
|
||||
|
||||
2. **CACHE_TABLES Response**: V1 returns stream, legacy returns to admin page
|
||||
- **Impact**: Different response format but both provide confirmation
|
||||
- **Recommendation**: Acceptable for REST API
|
||||
|
||||
3. **METADATA_MATCH Response**: Both not implemented
|
||||
- **Impact**: None
|
||||
|
||||
### React App Requirements
|
||||
✅ **Sufficient** - V1 returns confirmation messages for all actions
|
||||
⚠️ **Consideration**: RESTORE doesn't redirect - React app will need to handle auth state
|
||||
|
||||
---
|
||||
|
||||
## 3. GET /admin/users
|
||||
|
||||
### V1 Implementation
|
||||
- Returns: `GetUsers200JSONResponse` with array of `User` objects
|
||||
- User object fields: `Id`, `Admin`, `CreatedAt`
|
||||
- Data from: `s.db.Queries.GetUsers(ctx)`
|
||||
|
||||
### Legacy Implementation
|
||||
- Function: `appGetAdminUsers`
|
||||
- Returns: HTML template with user data
|
||||
- Template variables available: `.Data` contains all user fields
|
||||
- User fields from DB: `ID`, `Pass`, `AuthHash`, `Admin`, `Timezone`, `CreatedAt`
|
||||
- Template only uses: `$user.ID`, `$user.Admin`, `$user.CreatedAt`
|
||||
|
||||
### Deviations
|
||||
**None** - V1 returns exactly the fields used by the legacy template
|
||||
|
||||
### React App Requirements
|
||||
✅ **Sufficient** - All fields used by legacy admin users page are included
|
||||
|
||||
---
|
||||
|
||||
## 4. POST /admin/users (User CRUD)
|
||||
|
||||
### V1 Implementation
|
||||
- Operations: `CREATE`, `UPDATE`, `DELETE`
|
||||
- Returns: `UpdateUser200JSONResponse` with updated users list
|
||||
- Validation:
|
||||
- User cannot be empty
|
||||
- Password required for CREATE
|
||||
- Something to update for UPDATE
|
||||
- Last admin protection for DELETE and UPDATE
|
||||
- Same business logic as legacy
|
||||
|
||||
### Legacy Implementation
|
||||
- Function: `appUpdateAdminUsers`
|
||||
- Operations: Same as V1
|
||||
- Returns: HTML template with updated user list
|
||||
- Same validation and business logic
|
||||
|
||||
### Deviations
|
||||
**None** - V1 mirrors legacy business logic exactly
|
||||
|
||||
### React App Requirements
|
||||
✅ **Sufficient** - V1 returns updated users list after operation
|
||||
|
||||
---
|
||||
|
||||
## 5. GET /admin/import
|
||||
|
||||
### V1 Implementation
|
||||
- Parameters: `directory` (optional), `select` (optional)
|
||||
- Returns: `GetImportDirectory200JSONResponse`
|
||||
- Response fields: `CurrentPath`, `Items` (array of `DirectoryItem`)
|
||||
- DirectoryItem fields: `Name`, `Path`
|
||||
- Default path: `s.cfg.DataPath` if no directory specified
|
||||
- If `select` parameter set, returns empty items with selected path
|
||||
|
||||
### Legacy Implementation
|
||||
- Function: `appGetAdminImport`
|
||||
- Parameters: Same as V1
|
||||
- Returns: HTML template
|
||||
- Template variables: `.CurrentPath`, `.Data` (array of directory names)
|
||||
- Same default path logic
|
||||
|
||||
### Deviations
|
||||
1. **DirectoryItem structure**: V1 includes `Path` field, legacy only uses names
|
||||
- **Impact**: V1 provides more information (beneficial for React)
|
||||
- **Recommendation**: Acceptable improvement
|
||||
|
||||
### React App Requirements
|
||||
✅ **Sufficient** - V1 provides all information plus additional path data
|
||||
|
||||
---
|
||||
|
||||
## 6. POST /admin/import
|
||||
|
||||
### V1 Implementation
|
||||
- Parameters: `directory`, `type` (DIRECT or COPY)
|
||||
- Returns: `PostImport200JSONResponse` with `ImportResult` array
|
||||
- ImportResult fields: `Id`, `Name`, `Path`, `Status`, `Error`
|
||||
- Status values: `SUCCESS`, `EXISTS`, `FAILED`
|
||||
- Same transaction and error handling as legacy
|
||||
- Results sorted by status priority
|
||||
|
||||
### Legacy Implementation
|
||||
- Function: `appPerformAdminImport`
|
||||
- Parameters: Same as V1
|
||||
- Returns: HTML template with results (redirects to import-results page)
|
||||
- Result fields: `ID`, `Name`, `Path`, `Status`, `Error`
|
||||
- Same status values and priority
|
||||
|
||||
### Deviations
|
||||
**None** - V1 mirrors legacy exactly
|
||||
|
||||
### React App Requirements
|
||||
✅ **Sufficient** - All import result information included
|
||||
|
||||
---
|
||||
|
||||
## 7. GET /admin/import-results
|
||||
|
||||
### V1 Implementation
|
||||
- Returns: `GetImportResults200JSONResponse` with empty `ImportResult` array
|
||||
- Note: Results returned immediately after import in POST /admin/import
|
||||
- Legacy behavior: Results displayed on separate page after POST
|
||||
|
||||
### Legacy Implementation
|
||||
- No separate endpoint
|
||||
- Results shown on `page/admin-import-results` template after POST redirect
|
||||
|
||||
### Deviations
|
||||
1. **Endpoint Purpose**: Legacy doesn't have this endpoint
|
||||
- **Impact**: V1 endpoint returns empty results
|
||||
- **Recommendation**: Consider storing results in session/memory for retrieval
|
||||
- **Alternative**: React app can cache results from POST response
|
||||
|
||||
### React App Requirements
|
||||
⚠️ **Limited** - Endpoint returns empty, React app should cache POST results
|
||||
💡 **Suggestion**: Enhance to store/retrieve results from session or memory
|
||||
|
||||
---
|
||||
|
||||
## 8. GET /admin/logs
|
||||
|
||||
### V1 Implementation
|
||||
- Parameters: `filter` (optional)
|
||||
- Returns: `GetLogs200JSONResponse` with `Logs` and `Filter`
|
||||
- Log lines: Pretty-printed JSON with indentation
|
||||
- Supports JQ filters for complex filtering
|
||||
- Supports basic string filters (quoted)
|
||||
- Filters only pretty JSON lines
|
||||
|
||||
### Legacy Implementation
|
||||
- Function: `appGetAdminLogs`
|
||||
- Parameters: Same as V1
|
||||
- Returns: HTML template with filtered logs
|
||||
- Same JQ and basic filter logic
|
||||
- Template variables: `.Data` (log lines), `.Filter`
|
||||
|
||||
### Deviations
|
||||
**None** - V1 mirrors legacy exactly
|
||||
|
||||
### React App Requirements
|
||||
✅ **Sufficient** - All log information and filtering capabilities included
|
||||
|
||||
---
|
||||
|
||||
## Summary of Deviations
|
||||
|
||||
### Critical (Requires Action)
|
||||
None identified
|
||||
|
||||
### Important (Consideration)
|
||||
1. **RESTORE redirect**: Legacy redirects to login after restore, V1 doesn't
|
||||
- **Impact**: React app won't automatically redirect
|
||||
- **Recommendation**: Add `redirect_url` field to response or document expected behavior
|
||||
|
||||
2. **Import-results endpoint**: Returns empty results
|
||||
- **Impact**: Cannot retrieve previous import results
|
||||
- **Recommendation**: Store results in session/memory or cache on client side
|
||||
|
||||
### Minor (Acceptable Differences)
|
||||
1. **DirectoryItem includes Path**: V1 includes path field
|
||||
- **Impact**: Additional information available
|
||||
- **Recommendation**: Acceptable improvement
|
||||
|
||||
2. **Response formats**: V1 returns JSON, legacy returns HTML
|
||||
- **Impact**: Expected for REST API migration
|
||||
- **Recommendation**: Acceptable
|
||||
|
||||
### No Deviations
|
||||
- GET /admin (actually provides MORE info)
|
||||
- GET /admin/users
|
||||
- POST /admin/users
|
||||
- POST /admin/import
|
||||
- GET /admin/logs
|
||||
|
||||
---
|
||||
|
||||
## Database Access Compliance
|
||||
|
||||
✅ **All database access uses existing SQLC queries**
|
||||
- `GetDocumentsSize` - Document count
|
||||
- `GetUsers` - User list
|
||||
- `GetDatabaseInfo` - Per-user stats
|
||||
- `CreateUser` - User creation
|
||||
- `UpdateUser` - User updates
|
||||
- `DeleteUser` - User deletion
|
||||
- `GetUser` - Single user retrieval
|
||||
- `GetDocument` - Document lookup
|
||||
- `UpsertDocument` - Document upsert
|
||||
- `CacheTempTables` - Table caching
|
||||
- `Reload` - Database reload
|
||||
|
||||
❌ **No ad-hoc SQL queries used**
|
||||
|
||||
---
|
||||
|
||||
## Business Logic Compliance
|
||||
|
||||
✅ **All critical business logic mirrors legacy**
|
||||
- User validation (empty user, password requirements)
|
||||
- Last admin protection
|
||||
- Transaction handling for imports
|
||||
- Backup/restore validation and flow
|
||||
- Auth hash rotation after restore
|
||||
- Log filtering with JQ support
|
||||
|
||||
---
|
||||
|
||||
## Recommendations for React App
|
||||
|
||||
1. **Handle restore redirect**: After successful restore, redirect to login page
|
||||
2. **Cache import results**: Store POST import results for display
|
||||
3. **Leverage additional data**: Use `Path` field in DirectoryItem for better UX
|
||||
4. **Error handling**: All error responses follow consistent pattern with message
|
||||
|
||||
---
|
||||
|
||||
## Conclusion
|
||||
|
||||
The V1 API admin implementations successfully mirror the legacy implementations with:
|
||||
- ✅ All required data fields for React app
|
||||
- ✅ Same business logic and validation
|
||||
- ✅ Proper use of existing SQLC queries
|
||||
- ✅ No critical deviations
|
||||
|
||||
Minor improvements and acceptable RESTful patterns:
|
||||
- Additional data fields (DirectoryItem.Path)
|
||||
- RESTful JSON responses instead of HTML
|
||||
- Confirmation messages for async operations
|
||||
|
||||
**Status**: Ready for React app integration
|
||||
Reference in New Issue
Block a user