bookhoard/SCAN_SETTINGS_MIGRATION_PLAN.md

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

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

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

-- 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:

-- 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:

-- Remove:
-- name: UpdateScanSettings :exec
-- name: GetScanSettings :one

3. Router Changes: internal/router/library.go

Add to existing adminLibrary group:

// 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

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

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)

podman compose down -v
podman compose up -d

Option 2: Manual Migration (Preserves Data)

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.