# Progress Tracker & Master Document: Cloud Storage Folder Path Resolution
## Status
- [ ] Phase 0: Initialization (Setup)
- [x] Phase 1: Context Discovery (Explorer)
- [x] Phase 2: Technical Design (Architect)
- [x] Phase 3: Technical Planning (Planner)
- [x] Phase 4: Implementation (Phase 1 MVP)
- [ ] Phase 5: Verification & Handoff
## Phase 0: Initialization
- [x] Create feature branch `feature/cloud-storage-path-resolution`
- [x] Initialize blackboard `php artisan agent:mem:init`
- [x] Create Progress Tracker (this file)
---
# 📖 MASTER IMPLEMENTATION DOCUMENT
This document guarantees context persistence across agent sessions for the two-phased roadmap.
## Fase 1: MVP + Folder Resolution Caching (Entrega Inicial)
**Objetivo:** Resolver el problema crítico de la subida a raíz, implementar soporte absoluto de `path` y `folder_id`, y optimizar la recursividad de Google Drive para evitar fallos de API limits (N+1).
### 1.1 Core Infrastructure & Normalization
- **Archivo:** `src/App/Services/CloudServices/Helpers/CloudStoragePathHelper.php` (Nuevo)
- **Implementación:**
- Crear un Trait/Clase Estática `CloudStoragePathHelper`.
- Método `normalizePath(string $path): string`. Reglas: Trim slashes, rechazar `.` y `..` (lanzar `InvalidPathException` HTTP 422).
- Validar máximo 5 niveles de profundidad y 255 caracteres totales.
- Rechazar caracteres inválidos según el proveedor evaluado.
### 1.2 Actualización de Contratos
- **Archivos:** `CloudStorageProvider.php`, `CloudStorageService.php`
- **Implementación:**
- Agregar parámetro a la interfaz: `public function upload(string $path, $contents, ?string $filename = null, ?string $folderId = null): string;`
- Inyectar desde el form request `$folderId` a `$tempStorageService->uploadFileFromUpload()` en el `CloudStorageController`.
### 1.3 Microsoft OneDrive Integration
- **Archivo:** `MicrosoftGraphProvider.php`
- **Implementación:**
- Si `$folderId` existe y no es 'root', construir endpoint tipo ID: `items/{$folderId}:/{$filename}:/content`.
- Si se usa ruta, usar path addressing: `items/root:/{$normalizedPath}/{$filename}:/content`.
- Check de Muerte (GET a ruta padre antes de POST). Si Graph da 404, disparar `InvalidPathException` ("La ruta no existe"). Sin auto-creación.
### 1.4 Google Drive Integration & Cache Isolation (Mejora Crítica)
- **Archivo:** `GoogleWorkspaceProvider.php`
- **Implementación:**
- Eliminar el ineficiente `dirname()`.
- Implementar Caminata Recursiva (Folder Walk): `resolveFolderChain(string $path): string`.
- **Aislamiento de Caché (IMPORTANTE):** Para evitar mezclar llaves en Redis, usar la propiedad única de la configuración que amarra al tenant. E.j., `Cache::remember("gdrive_folder_config_{$this->config->id}_" . md5($path), 3600, ... )`.
- Si existe ambigüedad o falta una carpeta (404 virtual), fallar rápido con HTT 422.
### 1.5 Controller & Error Catching
- **Archivo:** `CloudStorageController.php`
- **Implementación:**
- Try/catch envolviendo la llamada al proveedor.
- Regla de Precedencia: `folder_id` sobreescribe `path` si ambos llegan.
- Loguear errores a nivel aplicación sin exponer stack traces al JSON client. Devolver `success: false` y un `message` claro y humanizado.
---
## Fase 2: Enterprise Features (Futura Iteración/PR Separado)
**Objetivo:** Escalabilidad corporativa (Auto-create, Tenant Isolation, Async Tasks).
### 2.1 Auto-Creación Recursiva de Carpetas
- **Flujo Google:** En el "Folder Walk", en lugar de fallar, inyectar un POST a `files.create` mimeType Folder en el Level actual y continuar recursión.
- **Flujo Microsoft:** Emplear la sintaxis `@microsoft.graph.conflictBehavior = 'rename'` desde la raíz creando secuencialmente.
### 2.2 Inversión de Root Context y Aislamiento Tenancy (Root Jail)
- Inyectar en BD o Service Context un "Master Folder ID" de ese tenant.
- En `CloudStoragePathHelper`, prepender este Jail Hash a todo payload de usuario (e.j. `Facturas/` -> `[ROOT_UUID]/Facturas/`).
### 2.3 Estrategias y Políticas de Conflicto Configurable
- Permitir configuración UI: `rename`, `replace`, `abort`.
- Alterar las banderas API (ej: Drive API upload `uploadType=multipart` junto con un Delete/Update del ID detectado si la política es `replace`).
### 2.4 Hacia el Event Backbone (Subidas Asíncronas)
- Recibir multi-part de Nginx. Escribir temporal. Enviar Dispatch a Work Queue (Cloud Tasks/PubSub/Rabbit).
- Worker procesa la validación larga (Folder Walk). Notifica cliente vía websockets (Laravel Echo).
---
## Fase 3: Consolidación UX & Cumplimiento (Sesión Actual)
### 3.1 Unificación de Interfaz (Combobox)
- [x] Implementar un `` con `