Desarrollo

Convenciones y estándares de desarrollo

Reglas Críticas (No Negociables)

Reglas que SIEMPRE se aplican
  1. TypeScript obligatorio - NUNCA usar JavaScript puro en proyectos nuevos
  2. No Docker para proyectos nuevos (usar systemd + venv)
  3. Puertos: Rango 8101-8199 para servicios de aplicación
  4. GitHub: Todos los repos bajo github.com/illanes00/

Stack por Lenguaje

Python (Backend)

Aspecto Estándar
Versión Python 3.10+ (preferido 3.11)
Framework FastAPI (APIs), Flask solo legacy
Linting Ruff
Formatting Black (line-length: 100)
Type hints Obligatorios en todas las funciones
Testing pytest + pytest-asyncio

TypeScript/JavaScript (Frontend)

Aspecto Estándar
Versión Node.js 18+
Modo ES Modules ("type": "module")
TypeScript Strict mode siempre
Linting ESLint + Prettier
Frameworks Next.js 14, Vite + React, Express
Styling Tailwind CSS (nunca CSS-in-JS)

Estructura de Proyecto Python

proyecto/
├── app/
│   ├── main.py          # FastAPI entry point
│   ├── api/v1/          # Routers versionados
│   ├── models/          # SQLAlchemy ORM
│   ├── schemas/         # Pydantic validators
│   └── services/        # Business logic
├── tests/
├── deploy/
│   ├── systemd.service
│   └── caddy.caddy
├── run.py               # Dev server entry
├── requirements.txt
└── .env.example

Commits y Git

Formato: Conventional Commits en inglés

feat(api): add user authentication endpoint
fix(ui): correct button alignment on mobile
docs(readme): update installation instructions

Tipos válidos: feat, fix, docs, style, refactor, test, chore

Branches: - main - Producción - develop - Staging - feature/* - Desarrollo

Endpoints Obligatorios

Toda API debe implementar:

@app.get("/healthz")
def healthz():
    return {"ok": True}

@app.get("/readyz")
def readyz():
    return {"ok": True}

@app.get("/version")
def version():
    return {"name": "proyecto", "sha": os.getenv("GIT_SHA", "dev")}

Anti-Patterns (NO HACER)

  1. ❌ Usar JavaScript puro (siempre TypeScript)
  2. ❌ Crear Dockerfiles para proyectos nuevos
  3. ❌ Hardcodear credenciales o tokens
  4. ❌ Usar CSS-in-JS (usar Tailwind)
  5. ❌ Crear proyectos fuera de /srv/projects/
  6. ❌ Commitear archivos .env
  7. ❌ Ignorar type hints en Python/TypeScript

Más Información