Añadir 02-version.md

2026-05-23 02:35:09 +00:00
parent 2c9d5cf406
commit fa3a5ed3d2
1 changed files with 461 additions and 0 deletions
--- a/02-version.md.-.md
+++ b/02-version.md.-.md
@@ -0,0 +1,461 @@
+# Problemas de Versiones
+
+Soluciones a conflictos de versiones de SDK, librerías y herramientas.
+
+---
+
+## Flutter / Dart SDK
+
+### Equipo usa versiones diferentes
+
+**Síntoma:**
+```
+pubspec.lock tiene conflictos en cada git pull
+```
+
+**Causa:** Algunos usan Flutter 3.44, otros 3.22, etc.
+
+**Solución:** **Usar FVM para sincronizar versiones.**
+
+```bash
+# En la raíz del proyecto (una sola vez por el líder)
+fvm use 3.44.0
+# Esto crea .fvm/fvm_config.json
+
+# Commitear el archivo
+git add .fvm/fvm_config.json
+git commit -m "Fijar versión de Flutter a 3.44.0"
+git push
+
+# Todos los demás:
+git pull
+fvm install  # instala la versión del proyecto
+fvm flutter pub get
+```
+
+**Ventaja:** Todos usan exactamente la misma versión sin conflictos.
+
+---
+
+### Error: "The current Dart SDK version is X but Y is required"
+
+**Síntoma:**
+```
+The current Dart SDK version is 3.12.0.
+Because basura_app requires SDK version >=3.8.0 <4.0.0, version solving failed.
+```
+
+**Causa:** Tu `pubspec.yaml` pide una versión que no tienes.
+
+**Solución:**
+
+**Opción 1:** Ajustar `pubspec.yaml` a tu versión:
+```yaml
+environment:
+  sdk: '>=3.4.0 <4.0.0'  # compatible con Flutter 3.22+
+```
+
+**Opción 2:** Actualizar Flutter:
+```bash
+fvm install 3.44.0
+fvm use 3.44.0
+fvm flutter pub get
+```
+
+---
+
+### Error: "Unsupported Dart SDK constraint"
+
+**Síntoma:**
+```
+The lower bound of "sdk: '>=3.8.0 <4.0.0'" must be 2.12.0 or higher
+```
+
+**Causa:** Versión muy antigua de Flutter.
+
+**Solución:**
+```bash
+# Actualizar Flutter
+flutter upgrade
+
+# O usar FVM
+fvm install 3.44.0
+fvm use 3.44.0
+```
+
+---
+
+## Java JDK
+
+### Error: "Gradle requires Java 11 or higher"
+
+**Síntoma:**
+```
+ERROR: JAVA_HOME is set to an invalid directory
+```
+
+**Causa:** Java muy antiguo o `JAVA_HOME` mal configurado.
+
+**Solución:**
+```bash
+# 1. Instalar Java 17 (recomendado)
+# Linux:
+sudo apt install openjdk-17-jdk
+
+# macOS:
+brew install openjdk@17
+
+# Windows:
+# Descargar desde adoptium.net
+
+# 2. Verificar
+java -version  # debe mostrar "17.x.x"
+
+# 3. Configurar JAVA_HOME
+# Linux/macOS (.bashrc o .zshrc):
+export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
+
+# Windows (System Properties → Environment Variables):
+JAVA_HOME=C:\Program Files\Java\jdk-17
+```
+
+---
+
+### Error: "Unsupported class file major version 65"
+
+**Síntoma:**
+```
+Unsupported class file major version 65
+```
+
+**Causa:** Estás usando Java 21 (version 65) pero Gradle necesita Java 17 (version 61).
+
+**Solución:**
+```bash
+# Cambiar a Java 17
+# Linux:
+sudo update-alternatives --config java
+# Selecciona java-17-openjdk
+
+# macOS:
+export JAVA_HOME=/usr/local/opt/openjdk@17
+
+# Windows:
+# Desinstalar Java 21
+# Instalar Java 17 desde adoptium.net
+
+# Verificar
+java -version  # DEBE mostrar "17.x.x"
+```
+
+---
+
+## Python / pip
+
+### Error: "No module named 'fastapi'"
+
+**Síntoma:**
+```
+ModuleNotFoundError: No module named 'fastapi'
+```
+
+**Causa:** Dependencias no instaladas o virtualenv no activado.
+
+**Solución:**
+```bash
+# 1. Activar virtualenv
+source venv/bin/activate  # Linux/macOS
+venv\Scripts\activate     # Windows
+
+# 2. Instalar dependencias
+pip install -r requirements.txt
+
+# 3. Verificar
+pip list | grep fastapi
+```
+
+---
+
+### Error: "externally-managed-environment"
+
+**Síntoma:**
+```
+error: externally-managed-environment
+This environment is externally managed
+```
+
+**Causa:** Python 3.11+ en algunas distros bloquea `pip install` global.
+
+**Solución:**
+```bash
+# Opción 1: Usar virtualenv (recomendado)
+python -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+
+# Opción 2: Forzar (no recomendado)
+pip install --break-system-packages -r requirements.txt
+```
+
+---
+
+### Versiones de paquetes incompatibles
+
+**Síntoma:**
+```
+ERROR: pip's dependency resolver does not currently take into account 
+all the packages that are installed
+```
+
+**Causa:** Conflicto entre versiones de dependencias.
+
+**Solución:**
+```bash
+# 1. Limpiar caché de pip
+pip cache purge
+
+# 2. Reinstalar desde cero
+pip uninstall -y -r requirements.txt
+pip install -r requirements.txt
+
+# 3. Si persiste, fijar versiones exactas en requirements.txt
+fastapi==0.111.0  # en lugar de fastapi>=0.111.0
+```
+
+---
+
+## Dependencias de Flutter
+
+### Error: "version solving failed"
+
+**Síntoma:**
+```
+Because basura_app depends on flutter_riverpod ^2.6.1 which requires SDK version >=3.0.0,
+version solving failed.
+```
+
+**Causa:** Paquete incompatible con tu versión de Flutter.
+
+**Solución:**
+
+**Opción 1:** Actualizar Flutter:
+```bash
+fvm install 3.44.0
+fvm use 3.44.0
+```
+
+**Opción 2:** Bajar la versión del paquete:
+```yaml
+dependencies:
+  flutter_riverpod: ^2.4.0  # versión más antigua compatible
+```
+
+---
+
+### Error: "pubspec.lock differs from pubspec.yaml"
+
+**Síntoma:**
+```
+The pubspec.lock file has changed since the last pub get
+```
+
+**Causa:** Alguien modificó `pubspec.yaml` pero no corrió `pub get`.
+
+**Solución:**
+```bash
+fvm flutter pub get
+
+# Commitear pubspec.lock
+git add pubspec.lock
+git commit -m "Actualizar pubspec.lock"
+```
+
+---
+
+### Error: "package has incompatible Dart SDK constraint"
+
+**Síntoma:**
+```
+The current Dart SDK version is 3.12.0.
+Package 'some_package' requires SDK version ^2.17.0.
+```
+
+**Causa:** Un paquete viejo no soporta Dart 3.x.
+
+**Solución:**
+```bash
+# 1. Buscar versión actualizada del paquete
+flutter pub upgrade some_package
+
+# 2. Si no existe, usar versión compatible
+# En pubspec.yaml:
+some_package: ^1.0.0  # versión vieja que funcione
+```
+
+---
+
+## Git merge de pubspec.lock
+
+### Conflicto en pubspec.lock
+
+**Síntoma:**
+```
+CONFLICT (content): Merge conflict in pubspec.lock
+```
+
+**Causa:** Dos personas agregaron dependencias diferentes.
+
+**Solución:**
+```bash
+# NO resolver manualmente — dejar que Flutter lo regenere
+
+# 1. Quedarte con una versión (la tuya o la de ellos)
+git checkout --theirs pubspec.lock
+# o
+git checkout --ours pubspec.lock
+
+# 2. Regenerar desde pubspec.yaml
+fvm flutter pub get
+
+# 3. Commitear el nuevo lock
+git add pubspec.lock
+git commit -m "Regenerado pubspec.lock"
+```
+
+---
+
+## Problemas con FVM
+
+### Error: "fvm: command not found"
+
+**Síntoma:**
+```
+zsh: command not found: fvm
+```
+
+**Causa:** FVM no está en el PATH.
+
+**Solución:**
+```bash
+# Agregar al PATH
+# Linux/macOS (.bashrc o .zshrc):
+export PATH="$PATH":"$HOME/.pub-cache/bin"
+
+# Reiniciar terminal
+source ~/.zshrc  # o ~/.bashrc
+
+# Verificar
+fvm --version
+```
+
+---
+
+### Error: "Flutter SDK not found"
+
+**Síntoma:**
+```
+FVM: Flutter SDK not found at /Users/you/.fvm/versions/3.44.0
+```
+
+**Causa:** La versión no está instalada.
+
+**Solución:**
+```bash
+# Instalar la versión
+fvm install 3.44.0
+
+# Listar versiones instaladas
+fvm list
+```
+
+---
+
+### IDE no reconoce el SDK de FVM
+
+**Síntoma:** Android Studio usa Flutter global en lugar de `.fvm/flutter_sdk`.
+
+**Solución:**
+
+**Android Studio:**
+1. Settings → Languages & Frameworks → Flutter
+2. Flutter SDK path: `<proyecto>/.fvm/flutter_sdk`
+
+**VS Code:**
+```json
+// .vscode/settings.json
+{
+  "dart.flutterSdkPath": ".fvm/flutter_sdk"
+}
+```
+
+---
+
+## Downgrade de versiones
+
+### Bajar de Flutter 3.44 a 3.22
+
+**Razón:** Linux tiene problemas con Java 21 + Flutter 3.44.
+
+**Proceso:**
+```bash
+# 1. Instalar la versión LTS
+fvm install 3.22.0
+fvm use 3.22.0
+
+# 2. Actualizar pubspec.yaml
+# environment:
+#   sdk: '>=3.4.0 <4.0.0'
+#   flutter: '>=3.22.0'
+
+# 3. Actualizar dependencias
+fvm flutter pub get
+
+# 4. Commitear cambios
+git add .fvm/fvm_config.json pubspec.yaml pubspec.lock
+git commit -m "Downgrade a Flutter 3.22 LTS"
+
+# 5. Notificar al equipo para que todos hagan:
+fvm install 3.22.0
+fvm flutter pub get
+```
+
+---
+
+## Tabla de compatibilidad
+
+| Flutter | Dart | Java | Riverpod | Dio |
+|---------|------|------|----------|-----|
+| 3.44.0  | 3.8  | 17   | ^2.6.1   | ^5.4.0 |
+| 3.22.0  | 3.4  | 17   | ^2.4.0   | ^5.3.0 |
+| 3.19.0  | 3.3  | 17   | ^2.3.0   | ^5.2.0 |
+
+---
+
+## Verificar versiones actuales
+
+```bash
+# Flutter y Dart
+flutter --version
+
+# Java
+java -version
+
+# Python
+python --version
+
+# pip
+pip --version
+
+# Git
+git --version
+
+# FVM (si lo usas)
+fvm --version
+```
+
+---
+
+## Siguiente paso
+
+- [Debug del simulador](03-debug-simulador.md) — verificar estado del backend
+- [Errores comunes](01-errores-comunes.md) — volver a problemas generales