205 lines
9.4 KiB
Markdown
205 lines
9.4 KiB
Markdown
# 🧠 Roo Context File - Service Finder Master Book 2.0.1
|
|
**Generated:** 2026-03-26
|
|
**Auditor:** Projekt Manager Gemini
|
|
**Purpose:** System reality snapshot for Roo AI memory & future development context
|
|
|
|
---
|
|
|
|
## 📊 CURRENT SYSTEM REALITY (70+ DB Tables, Multi-Schema)
|
|
|
|
### 🗄️ Database Schema Overview (19 Schemas, 127+ Tables)
|
|
| Schema | Table Count | Status |
|
|
|--------|-------------|--------|
|
|
| audit | 5 | Active (Audit logs) |
|
|
| data | 0 | Not in list (maybe missing) |
|
|
| finance | 6 | Active (Triple Wallet, Ledger) |
|
|
| fleet | 6 | Active (Fleet management) |
|
|
| gamification | 11 | Active (XP, Badges, Leaderboard) |
|
|
| identity | 7 | Active (Person/User dual model) |
|
|
| marketplace | 12 | Active (Services, Providers) |
|
|
| public | 4 | System tables |
|
|
| system | 15 | Active (Parameters, Translations) |
|
|
| tiger | 34 | PostGIS extension tables |
|
|
| topology | 2 | PostGIS extension tables |
|
|
| vehicle | 25 | Active (Assets, Definitions, History) |
|
|
| **TOTAL** | **127+** | **Established multi-schema architecture** |
|
|
|
|
### ✅ 100% WORKING COMPONENTS (Verified)
|
|
1. **Authentication & Token Handling** - JWT with dual entity (Person/User)
|
|
2. **Basic Routing** - FastAPI operational on port 8000
|
|
3. **Database Connection Pool** - Async SQLAlchemy 2.0+ with PostgreSQL
|
|
4. **Docker Stack** - 30+ containers running (API, Frontend, DB, Redis, MinIO, etc.)
|
|
5. **Robot Ecosystem** - 10+ specialized workers active (Discovery, Hunter, Enricher, Validator, Auditor)
|
|
6. **Multi-Schema Isolation** - DDD principles enforced (identity, finance, vehicle domains separated)
|
|
|
|
### 🔄 ESTABLISHED WORKFLOWS
|
|
- **Vehicle Creation**: 2-step Draft → Active process (frontend calls `/api/v1/vehicles/register`, backend uses `/api/v1/assets/vehicles`)
|
|
- **MDM Deduplication**: Merge only when make, technical_code, and engine_capacity match
|
|
- **Triple Wallet Economy**: Local/EUR/Token balances with audit trail
|
|
- **Robot Quota Management**: `.quota_dvla.json` tracking for API rate limits
|
|
|
|
---
|
|
|
|
## ⚠️ KNOWN GAPS & BROKEN PIPES
|
|
|
|
### 🔴 CRITICAL (Blocking Production)
|
|
1. **API Endpoint Mismatch**
|
|
- Frontend `AddVehicle.vue` calls `/api/v1/vehicles/register` (404 Not Found)
|
|
- Correct endpoint is `/api/v1/assets/vehicles` (requires authentication)
|
|
- **Impact**: Vehicle creation fails for users
|
|
|
|
2. **Missing 2-Step Vehicle Creation Backend Logic**
|
|
- Documented 2-step process (Draft → Active) not fully implemented
|
|
- `AssetService.create_or_claim_vehicle()` handles VIN conflicts but draft logic unclear
|
|
|
|
3. **Authentication Endpoint 404**
|
|
- `/api/v1/auth/me` returns 404 (should be `/api/v1/users/me` or similar)
|
|
- **Impact**: Frontend cannot validate user session
|
|
|
|
### 🟡 HIGH PRIORITY (Functional but Incomplete)
|
|
4. **Mocked/Broken Catalog Endpoints**
|
|
- `/api/v1/catalog/brands` - 404 (likely moved to `/api/v1/vehicles/search/brands`)
|
|
- `/api/v1/vehicles/search/brands` - 404 (needs implementation)
|
|
|
|
5. **Frontend/Backend API Version Drift**
|
|
- Frontend uses hardcoded IP `192.168.100.43:8000` instead of env variable
|
|
- Multiple API calls expecting different response formats
|
|
|
|
6. **Missing Historical Data (occurrence_date)**
|
|
- Epic requirement: "Historical Data (múltbéli költségek, szervizek) bevezetése"
|
|
- `occurrence_date` field not consistently implemented across cost tables
|
|
|
|
### 🟢 MEDIUM PRIORITY (Architectural Debt)
|
|
7. **Inconsistent Error Handling**
|
|
- Some endpoints return plain text errors, others JSON
|
|
- No standardized error schema
|
|
|
|
8. **Missing AnalyticsService (TCO/km)**
|
|
- Flotta Analytics (Total Cost of Ownership per km) not implemented
|
|
- Required for fleet manager dashboards
|
|
|
|
9. **Robot-0-GB Discovery CSV Path**
|
|
- Robot expects `/mnt/nas/app_data/uk_mot_data.csv` but file existence not verified
|
|
|
|
---
|
|
|
|
## 🏛️ ARCHITECTURAL RULES (Must Preserve)
|
|
|
|
### 🚫 STRICT PROHIBITIONS
|
|
1. **No Yellow Text on White Backgrounds** - Accessibility violation
|
|
2. **Never Hardcode API Keys** - Use `config.py` + `.env` only
|
|
3. **No Direct Database Drops** - Use Alembic migrations only
|
|
4. **No Sync Blocking Calls** - All I/O must be async in FastAPI endpoints
|
|
5. **No Schema Mixing** - Finance data stays in `finance` schema, vehicle in `vehicle`, etc.
|
|
|
|
### ✅ MANDATORY PATTERNS
|
|
6. **Vehicle Creation is 2-Step**
|
|
- Step 1: Draft (VIN optional, basic info)
|
|
- Step 2: Active (technical enrichment, digital twin creation)
|
|
- XP reward only after Step 2 completion
|
|
|
|
7. **Deduplication Logic**
|
|
- Merge ONLY when `make`, `technical_code`, AND `engine_capacity` match
|
|
- Generate N/A and UNKNOWN fallback codes for SQL constraint compatibility
|
|
|
|
8. **Robot Quota Enforcement**
|
|
- All external API calls must respect `DVLA_DAILY_LIMIT` from `.env`
|
|
- Log usage in `.quota_dvla.json` with timestamp
|
|
|
|
9. **Triple Wallet Transactions**
|
|
- Every financial movement must create audit trail in `finance.ledger`
|
|
- Balance checks before deductions
|
|
|
|
### 🔧 TECHNICAL CONSTRAINTS
|
|
10. **Docker Compose V2 Only** - Use `docker compose` (space), not `docker-compose`
|
|
11. **Roo-Helper Container for Scripts** - All Python operations via `docker exec roo-helper`
|
|
12. **Test Database Isolation** - Unit tests must use `service_finder_test` or SQLite in-memory
|
|
13. **Logging Standard** - Use `logging.getLogger(__name__)`, no `print()` in production
|
|
|
|
---
|
|
|
|
## 📈 SYSTEM HEALTH ASSESSMENT (60% → 70% Complete)
|
|
|
|
### ✅ STRENGTHS
|
|
- **Robust Database Foundation**: 127+ tables across 19 schemas, well-normalized
|
|
- **Active Robot Fleet**: 10+ specialized workers running continuously
|
|
- **Containerized Infrastructure**: Full Docker stack with monitoring
|
|
- **Domain-Driven Design**: Clear separation of concerns (identity, finance, vehicle, marketplace)
|
|
|
|
### ⚠️ WEAKNESSES
|
|
- **Frontend/Backend Integration**: API mismatches causing 404 errors
|
|
- **Documentation/Code Drift**: Master Book 2.0 docs don't match actual endpoints
|
|
- **Incomplete User Flows**: Vehicle creation, authentication need fixing
|
|
- **Limited Testing**: Unit test coverage unknown, integration tests sparse
|
|
|
|
### 🎯 IMMEDIATE NEXT STEPS (PHASE 2)
|
|
1. **Fix API Endpoint Mismatches** - Align frontend calls with backend routes
|
|
2. **Implement 2-Step Vehicle Creation** - Complete draft/active workflow
|
|
3. **Add Historical Data Fields** - `occurrence_date` across cost tables
|
|
4. **Build AnalyticsService** - TCO/km calculations for fleet managers
|
|
5. **Create Integration Test Suite** - Verify end-to-end user journeys
|
|
|
|
---
|
|
|
|
## 🔗 KEY DEPENDENCIES & RISKS
|
|
|
|
### 🔄 INTERNAL DEPENDENCIES
|
|
- **PostgreSQL 15+** with PostGIS extension (spatial data)
|
|
- **Redis** for caching and session management
|
|
- **MinIO** for document/evidence storage
|
|
- **Ollama** (local AI) + Gemini/Groq (fallback) for OCR/AI
|
|
|
|
### 🌐 EXTERNAL DEPENDENCIES
|
|
- **DVLA VES API** (UK vehicle data) - Rate limited, requires API key
|
|
- **RDW API** (Dutch vehicle data) - Public but rate limited
|
|
- **OpenStreetMap** (service location data) - No API key required
|
|
- **SendGrid** (email) - API key required
|
|
|
|
### ⚠️ RISK FACTORS
|
|
- **Single Point of Failure**: Shared PostgreSQL instance
|
|
- **API Rate Limits**: DVLA (1000/day), RDW (unknown)
|
|
- **Data Volume**: UK MOT CSV (~10M records) requires efficient processing
|
|
- **Complexity**: 30+ Docker containers increase orchestration complexity
|
|
|
|
---
|
|
|
|
## 📝 AUDIT METHODOLOGY
|
|
1. **Codebase Analysis**: Read backend endpoints, frontend views/stores
|
|
2. **Database Inspection**: Schema enumeration via PostgreSQL queries
|
|
3. **API Testing**: Direct endpoint calls from roo-helper container
|
|
4. **Documentation Comparison**: Master Book 2.0 vs actual implementation
|
|
5. **Rule Extraction**: From `.roo/rules/` and code patterns
|
|
|
|
---
|
|
|
|
**NEXT ACTION**: Create Gitea issues for each identified gap, prioritize by criticality, begin implementation with Fast Coder mode.
|
|
---
|
|
|
|
## 🏗️ RULE ARCHITECTURE OPTIMIZATION (2026-03-27)
|
|
|
|
### Multi-Mode Schema Consolidation
|
|
- **Updated `00-global.md`**: Added mandatory directives: Docker Compose V2, color scheme (#1e3a8a), DB verification with `sync_engine.py`, ticket verification with `gitea_manager.py`, mandatory 2-step vehicle flow (Draft → Active).
|
|
- **Merged `02-architecture.md` into `architect.md`**: Enhanced architect rules with DDD, schema separation, project directory map, and SQL error handling.
|
|
- **Merged `04-debug-protocol.md` into `fast-coder.md`**: Added debug protocol steps and rapid API wiring guidelines (Pydantic validation, frontend integration).
|
|
- **Path verification**: Updated all references to use `docker compose exec roo-helper` (consistent with Docker Compose V2).
|
|
|
|
### Environment Cleanup Plan
|
|
Identified redundant test folders and orphaned files for archiving (rename to .old and move to archive):
|
|
- `backend/app/test_outside/` → `archive/test_outside_old/`
|
|
- `backend/app/tests_internal/` → `archive/tests_internal_old/`
|
|
- Various `.bak` and `.old` files scattered across the codebase (to be moved to archive).
|
|
|
|
### Mode Boundary Clarification
|
|
Each mode now has clear boundaries to prevent hallucination overlap:
|
|
- **Architect**: Focus on DDD, schema design, system integrity, and Kanban management.
|
|
- **Fast Coder**: Focus on surgical coding, API wiring, Pydantic validation, and frontend integration.
|
|
- **Auditor/Debugger**: Focus on verification, logging, and systematic debugging.
|
|
|
|
### Next Steps
|
|
- Execute archiving of identified redundant files.
|
|
- Validate that all rule paths are correct and functional.
|
|
- Ensure each mode's custom instructions reflect the updated rule sets.
|
|
|
|
---
|
|
|
|
*This file will be updated after each major system change. Maintain as single source of truth for Roo AI context.* |