refactor: finalize media cleanup and prepare scan settings plan
- Complete media scanner cleanup (ebook → media terminology) - Update remaining comments for consistency - Add comprehensive scan settings migration plan - Comment updates in book_matching.go and main.go - Remove COMPLETE_MEDIA_CLEANUP_PLAN.md (completed) - Add SCAN_SETTINGS_MIGRATION_PLAN.md for future implementation
This commit is contained in:
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,287 @@
|
||||
# Scan Settings Migration Plan
|
||||
|
||||
## 🎯 Objective
|
||||
Move auto-scan settings from per-user storage to system-wide storage while preserving all existing functionality.
|
||||
|
||||
## 📊 Database Changes
|
||||
|
||||
### 1. Add `system_settings` Table
|
||||
```sql
|
||||
CREATE TABLE system_settings (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
setting_key VARCHAR(100) UNIQUE NOT NULL,
|
||||
setting_value TEXT NOT NULL,
|
||||
description TEXT,
|
||||
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
|
||||
);
|
||||
```
|
||||
|
||||
### 2. Add Default Settings Data
|
||||
```sql
|
||||
INSERT INTO system_settings (setting_key, setting_value, description) VALUES
|
||||
('scan_frequency_minutes', '60', 'How often to scan all libraries in minutes'),
|
||||
('auto_scan_enabled', 'true', 'Whether auto-scanning is enabled system-wide');
|
||||
```
|
||||
|
||||
### 3. Remove Scan Columns from `users` Table
|
||||
```sql
|
||||
-- Remove these lines from users table:
|
||||
scan_frequency_minutes INTEGER DEFAULT 60,
|
||||
auto_scan_enabled BOOLEAN DEFAULT true,
|
||||
```
|
||||
|
||||
## 🏗 Code Structure Changes
|
||||
|
||||
### 1. New File: `internal/handlers/system_settings.go`
|
||||
- Move `UpdateScanSettings` and `GetScanSettings` from `auth.go`
|
||||
- **Remove**: `MustGetAuthenticatedUser(c)` calls
|
||||
- **Remove**: All user ID usage in database operations
|
||||
- **Keep**: All validation, error handling, JSON response logic
|
||||
- **Change**: Database calls to use system_settings queries
|
||||
|
||||
### 2. Update Database Queries
|
||||
**Add to `internal/database/queries/queries.sql`:**
|
||||
```sql
|
||||
-- name: GetSystemSetting :one
|
||||
SELECT setting_value FROM system_settings WHERE setting_key = $1;
|
||||
|
||||
-- name: UpdateSystemSetting :exec
|
||||
UPDATE system_settings SET setting_value = $2, updated_at = NOW() WHERE setting_key = $1;
|
||||
|
||||
-- name: GetAllSystemSettings :many
|
||||
SELECT setting_key, setting_value, description FROM system_settings ORDER BY setting_key;
|
||||
```
|
||||
|
||||
**Remove from `internal/database/queries/queries.sql`:**
|
||||
```sql
|
||||
-- Remove:
|
||||
-- name: UpdateScanSettings :exec
|
||||
-- name: GetScanSettings :one
|
||||
```
|
||||
|
||||
### 3. Router Changes: `internal/router/library.go`
|
||||
**Add to existing `adminLibrary` group:**
|
||||
```go
|
||||
// System scan settings (admin-only)
|
||||
adminLibrary.GET("/scan-settings", cfg.SystemSettingsHandler.GetScanSettings)
|
||||
adminLibrary.PUT("/scan-settings", cfg.SystemSettingsHandler.UpdateScanSettings)
|
||||
```
|
||||
|
||||
## 🔄 Implementation Strategy
|
||||
|
||||
### What Stays the Same:
|
||||
- Endpoint paths (`/api/libraries/scan-settings`)
|
||||
- Request/response formats
|
||||
- Validation rules (15-1440 minutes, boolean enabled)
|
||||
- Error handling patterns
|
||||
- Basic handler structure
|
||||
|
||||
### What Changes:
|
||||
- Database storage location (users table → system_settings table)
|
||||
- Access control (per-user → admin-only)
|
||||
- Handler location (auth.go → system_settings.go)
|
||||
- Database queries (user-based → key-value based)
|
||||
|
||||
### What Gets Removed:
|
||||
- `MustGetAuthenticatedUser()` calls from scan handlers
|
||||
- User ID usage in scan operations
|
||||
- Scan columns from users table
|
||||
- Per-user scan settings queries
|
||||
|
||||
## 🧪 Testing Requirements
|
||||
|
||||
### Modify Existing Tests:
|
||||
- **Update scan settings tests** in `cmd/server/tests/user_test.go:489-563`
|
||||
- **Add admin role verification** to existing tests
|
||||
- **Add database integration** tests
|
||||
- **Update scheduler tests** in `internal/services/scheduler_test.go`
|
||||
|
||||
### Create New Tests:
|
||||
- **System settings handler tests** in new file `cmd/server/tests/system_settings_test.go`
|
||||
- **Admin middleware tests** in `internal/middleware/middleware_test.go`
|
||||
- **Integration tests** for cross-component behavior
|
||||
|
||||
### Test Success Criteria:
|
||||
- All existing tests still pass
|
||||
- New system settings tests pass
|
||||
- Admin middleware properly tested
|
||||
- Integration tests cover cross-component behavior
|
||||
|
||||
## 📚 Documentation Updates
|
||||
|
||||
### 1. Create System Settings API Documentation
|
||||
**New File**: `/docs/developer/api/system/settings.md`
|
||||
- Document `GET /api/libraries/scan-settings`
|
||||
- Document `PUT /api/libraries/scan-settings`
|
||||
- Include request/response examples
|
||||
- Include error response codes
|
||||
|
||||
### 2. Update Main API Reference
|
||||
**File**: `/docs/developer/api/api-reference.md`
|
||||
- Add "System Management" section
|
||||
- Link to new system settings documentation
|
||||
|
||||
### 3. Update Scanner Documentation
|
||||
**File**: `/docs/developer/api/scanner/overview.md`
|
||||
- Add section about system-wide scan settings
|
||||
- Document how scheduler uses system settings
|
||||
|
||||
## 🔧 Bruno API Tests
|
||||
|
||||
### Create System Settings Bruno Tests
|
||||
**New Directory**: `/bruno/system/`
|
||||
|
||||
**File**: `/bruno/system/get-scan-settings.bru`
|
||||
```bru
|
||||
meta {
|
||||
name: Get System Scan Settings
|
||||
type: http
|
||||
seq: 1
|
||||
}
|
||||
|
||||
get {
|
||||
url: {{base_url}}/api/libraries/scan-settings
|
||||
auth: inherit
|
||||
}
|
||||
|
||||
headers {
|
||||
Authorization: Bearer {{adminToken}}
|
||||
Content-Type: application/json
|
||||
}
|
||||
|
||||
script:post-response {
|
||||
res.status.should.equal(200);
|
||||
res.body.type.should.equal("application/json");
|
||||
res.body.data.should.have.property('scan_frequency_minutes');
|
||||
res.body.data.should.have.property('auto_scan_enabled');
|
||||
}
|
||||
|
||||
docs {
|
||||
## Get System Scan Settings
|
||||
|
||||
Retrieves current system-wide scan settings for all libraries.
|
||||
|
||||
**Authentication**: Admin token required
|
||||
**Response**: Current scan frequency and auto-scan status
|
||||
}
|
||||
```
|
||||
|
||||
**File**: `/bruno/system/update-scan-settings.bru`
|
||||
```bru
|
||||
meta {
|
||||
name: Update System Scan Settings
|
||||
type: http
|
||||
seq: 2
|
||||
}
|
||||
|
||||
put {
|
||||
url: {{base_url}}/api/libraries/scan-settings
|
||||
body: json
|
||||
auth: inherit
|
||||
}
|
||||
|
||||
headers {
|
||||
Authorization: Bearer {{adminToken}}
|
||||
Content-Type: application/json
|
||||
}
|
||||
|
||||
body:json {
|
||||
"scan_frequency_minutes": 30,
|
||||
"auto_scan_enabled": true
|
||||
}
|
||||
|
||||
script:post-response {
|
||||
res.status.should.equal(200);
|
||||
res.body.type.should.equal("application/json");
|
||||
res.body.should.have.property('message');
|
||||
}
|
||||
|
||||
docs {
|
||||
## Update System Scan Settings
|
||||
|
||||
Updates system-wide scan settings that apply to all libraries.
|
||||
|
||||
**Authentication**: Admin token required
|
||||
**Request**: Scan frequency (15-1440 minutes) and enabled status
|
||||
**Response**: Success message
|
||||
}
|
||||
```
|
||||
|
||||
## 📋 Implementation Order
|
||||
|
||||
### Phase 1: Database & Core Implementation
|
||||
1. **Database schema changes** - Add system_settings table
|
||||
2. **Database queries** - Add system settings queries
|
||||
3. **New handler file** - Create system_settings.go
|
||||
4. **Router registration** - Add routes to adminLibrary group
|
||||
5. **Update scheduler** - Change to use system settings
|
||||
|
||||
### Phase 2: Cleanup & Testing
|
||||
6. **Remove old handlers** - Delete from auth.go
|
||||
7. **Remove user table columns** - Clean up schema
|
||||
8. **Update/create tests** - Comprehensive test coverage
|
||||
9. **Verify functionality** - Integration testing
|
||||
|
||||
### Phase 3: Documentation & API Tests
|
||||
10. **Create documentation** - API docs and updates
|
||||
11. **Create Bruno tests** - API test coverage
|
||||
12. **Final verification** - End-to-end testing
|
||||
|
||||
## ✅ Success Criteria
|
||||
|
||||
### Functionality:
|
||||
- [ ] All existing API endpoints work with same paths
|
||||
- [ ] Only admin users can access scan settings
|
||||
- [ ] Settings apply system-wide to all libraries
|
||||
- [ ] No per-user scan data remaining in users table
|
||||
- [ ] Scheduler uses system-wide settings correctly
|
||||
|
||||
### Testing:
|
||||
- [ ] All existing tests still pass
|
||||
- [ ] New system settings tests pass
|
||||
- [ ] Admin middleware properly tested
|
||||
- [ ] Integration tests verify cross-component behavior
|
||||
|
||||
### Documentation:
|
||||
- [ ] API documentation complete and accurate
|
||||
- [ ] Bruno tests cover all scenarios
|
||||
- [ ] Main API reference updated
|
||||
- [ ] Documentation renders correctly
|
||||
|
||||
### API Compatibility:
|
||||
- [ ] Existing client code continues to work
|
||||
- [ ] Endpoint paths unchanged
|
||||
- [ ] Request/response formats preserved
|
||||
- [ ] Error handling patterns consistent
|
||||
|
||||
## 🔄 Database Migration
|
||||
|
||||
### Option 1: Fresh Database (Recommended for Development)
|
||||
```bash
|
||||
podman compose down -v
|
||||
podman compose up -d
|
||||
```
|
||||
|
||||
### Option 2: Manual Migration (Preserves Data)
|
||||
```bash
|
||||
podman exec bookhoard_db psql -U postgres -d bookhoard -c "
|
||||
CREATE TABLE system_settings (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
setting_key VARCHAR(100) UNIQUE NOT NULL,
|
||||
setting_value TEXT NOT NULL,
|
||||
description TEXT,
|
||||
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
|
||||
);
|
||||
|
||||
INSERT INTO system_settings (setting_key, setting_value, description) VALUES
|
||||
('scan_frequency_minutes', '60', 'How often to scan all libraries in minutes'),
|
||||
('auto_scan_enabled', 'true', 'Whether auto-scanning is enabled system-wide');
|
||||
|
||||
ALTER TABLE users DROP COLUMN IF EXISTS scan_frequency_minutes;
|
||||
ALTER TABLE users DROP COLUMN IF EXISTS auto_scan_enabled;
|
||||
"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**This plan preserves all existing functionality while moving to system-wide scan settings with minimal changes and comprehensive testing/documentation.**
|
||||
@@ -12,7 +12,7 @@ import (
|
||||
"github.com/labstack/echo/v4"
|
||||
)
|
||||
|
||||
// Book matching service (added to Handler struct in ebook.go initialization)
|
||||
// Book matching service (added to Handler struct in scanner.go initialization)
|
||||
func (h *Handler) getMatchingService() *services.BookMatchingService {
|
||||
return services.NewBookMatchingService(h.db)
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user