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)