Reklamator/docs/TECHNICAL_DEBT.md

Technical Debt

This document tracks known technical debt in the Reklamator project.

Definition

Technical debt refers to:

• Missing test coverage
• Known limitations or workarounds
• Deferred improvements
• Areas needing refactoring

---

Current Technical Debt

1. Missing Authentication Route Tests

Severity: Medium Phase Introduced: Phase 3 (MVP) Status: Open

Description: Authentication routes (login/logout) lack comprehensive test coverage. The routes work but were not covered by contract tests during initial implementation.

Missing Tests:

• Contract tests for /auth/login (GET)
• Contract tests for /auth/login (POST) with valid credentials
• Contract tests for /auth/login (POST) with invalid credentials
• Contract tests for /auth/logout
• Integration tests for complete login/logout flow
• Tests for session management
• Tests for authenticated vs unauthenticated access

Impact:

• Authentication bugs may go undetected until manual testing
• Risk of regression when modifying auth code

Mitigation:

• User model has comprehensive unit tests (15 tests) added after MVP
• Manual testing verified login/logout functionality
• CSRF protection tested manually (disabled in test config by design)

Plan to Resolve:

• Add authentication contract tests in Phase 5 when implementing dashboard (which requires authentication)
• Or address as standalone task before Phase 4

---

2. CSRF Testing Disabled in Test Environment

Severity: Low Phase Introduced: Phase 2 (Foundational) Status: Accepted (By Design)

Description: CSRF protection is disabled in test configuration (config/testing.py:17 - WTF_CSRF_ENABLED = False). This is a common testing practice but means CSRF bugs only appear in development/production.

Impact:

• CSRF-related bugs require manual testing to catch
• Forms without CSRF tokens will pass tests but fail in dev/prod

Bugs Found:

• Bug #1: Missing CSRF token in submission form (found manually)
• Bug #2: Missing CSRF token in login form (found manually)

Mitigation:

• Both forms now include CSRF tokens
• Manual testing checklist includes form submission
• CSRF protection verified working in development environment

Plan to Resolve:

• Consider adding integration tests with CSRF enabled
• Or document as accepted trade-off for simpler testing

---

3. Dashboard Routes Not Implemented

Severity: Low (Expected) Phase Introduced: Phase 3 (MVP) Status: Planned

Description: Login/logout routes reference dashboard endpoints that don't exist yet:

• admin.dashboard (Phase 6 - User Story 4)
• dashboard.list (Phase 5 - User Story 3)

Current Workaround:

• All users redirect to index page after login
• Base template shows "Coming in Phase X" messages
• TODO comments in code mark areas for future implementation

Impact:

• Users cannot access dashboards after login (expected for MVP)
• Navigation shows placeholder text instead of functional links

Plan to Resolve:

• Implement in Phase 5 (Product Owner Dashboard)
• Implement in Phase 6 (Admin Dashboard)

---

4. ClamAV Integration Not Fully Tested

Severity: Low Phase Introduced: Phase 3 (MVP) Status: Open

Description: ClamAV virus scanning has graceful degradation but limited test coverage. Tests run with ClamAV unavailable (skips scanning).

Missing Tests:

• Tests with actual ClamAV daemon running
• Tests for virus detection
• Tests for ClamAV connection failures
• Tests for scanning timeout

Impact:

• ClamAV integration relies on manual testing
• Virus scanning behavior not verified in automated tests

Mitigation:

• Code includes comprehensive error handling
• Logs warnings when ClamAV unavailable
• Falls back gracefully (allows upload, logs warning)

Plan to Resolve:

• Add mock ClamAV tests using unittest.mock
• Or add optional integration tests requiring ClamAV installation
• Document ClamAV setup in deployment guide

---

Bug Fixes Without Tests

All bugs found during manual testing should have regression tests added. Track them here:

Bug #1: Missing CSRF Token in Forms

Date Found: 2025-10-16 Severity: High Found By: Manual testing Fixed In: Commit b8d0d6d

Description: Submission and login forms were missing CSRF token fields, causing "Bad Request - The CSRF token is missing" errors.

Root Cause:

• Forms created without {{ csrf_token() }} hidden input
• CSRF disabled in test config meant tests didn't catch it

Test Coverage:

• ❌ No test added (CSRF disabled in test config by design)
• ✅ Manual testing verified fix

Lesson Learned:

• Always test forms in development environment
• Consider manual testing checklist for CSRF-protected forms

---

Bug #2: User Model is_active AttributeError

Date Found: 2025-10-16 Severity: High Found By: Manual testing (login attempt) Fixed In: Commit 73a9a74

Description: AttributeError: can't set attribute 'is_active' when loading users. Flask-Login's UserMixin provides is_active as read-only property, conflicting with instance attribute assignment.

Root Cause:

• Direct attribute assignment conflicted with Flask-Login property
• No unit tests for User model during Phase 2/3

Test Coverage:

• ✅ Added 15 comprehensive unit tests in tests/unit/test_user_model.py
• ✅ Specifically tests is_active property (test_user_is_active_property)
• ✅ Tests Flask-Login integration (test_user_flask_login_properties)

Lesson Learned:

• Test-First Discipline should apply to ALL models, not just user-facing features
• Flask-Login integration needs explicit testing

---

Bug #3: BuildError for Non-Existent Dashboard Routes

Date Found: 2025-10-16 Severity: Medium Found By: Manual testing (successful login) Fixed In: Commit d5fd7a7

Description: werkzeug.routing.exceptions.BuildError: Could not build url for endpoint 'admin.dashboard' after successful login. Auth routes tried to redirect to unimplemented dashboard routes.

Root Cause:

• Forward references to routes not yet implemented (Phase 5/6)
• No integration tests for login flow

Test Coverage:

• ❌ No test added (dashboards not implemented yet)
• ✅ Manual testing verified fix
• 📝 TODO comments added for future implementation

Lesson Learned:

• Avoid forward references to unimplemented routes
• Or use defensive checks (e.g., url_for() with try/except)
• Integration tests should verify redirect destinations

---

Resolution Priorities

1. High Priority: Add authentication route tests (Phase 5)
2. Medium Priority: Add ClamAV mock tests
3. Low Priority: Consider CSRF-enabled integration tests
4. Ongoing: Add regression test for each bug fix

---

Test Coverage Goals

Current Coverage (Phase 3 - MVP)

• Contract Tests: 8 tests (submission routes)
• Integration Tests: 2 tests (feedback submission)
• Unit Tests: 15 tests (User model)
• Total: 25 tests

Coverage by Component:

• ✅ Submission routes: Excellent (8 contract + 2 integration tests)
• ✅ User model: Excellent (15 unit tests)
• ✅ Feedback model: Good (tested via integration tests)
• ✅ Product model: Good (tested via integration tests)
• ⚠️ Authentication routes: Poor (0 tests)
• ⚠️ File validation: Partial (tested via submission tests)
• ❌ Admin routes: None (not implemented)
• ❌ Dashboard routes: None (not implemented)

Target Coverage (End of MVP+)

• All user-facing routes: Contract tests
• All models: Unit tests
• All services: Unit tests
• Critical flows: Integration tests
• Minimum: 80% code coverage

---

How to Add Tests for Bug Fixes

When fixing a bug:

1. Write a failing test that reproduces the bug
2. Verify the test fails with the buggy code
3. Fix the bug
4. Verify the test passes with the fixed code
5. Document the bug and test in this file
6. Commit test and fix together

See: .specify/memory/constitution.md - Bug Fix Protocol

---

Review Schedule

This document should be reviewed:

• After each phase completion
• When adding new features
• When fixing bugs
• Monthly during active development

Last Updated: 2025-10-16 (Phase 3 - MVP Complete)