1008 lines
35 KiB
Markdown
1008 lines
35 KiB
Markdown
# CLAUDE.md
|
|
|
|
Este archivo proporciona orientación a Claude Code (claude.ai/code) para trabajar con el código de este repositorio.
|
|
|
|
## Contexto
|
|
|
|
**Prueba técnica** para posición de **Desarrollador Master .NET/Angular** en **Inter Rapidísimo**.
|
|
- Cargo: Desarrollador Senior .NET/Angular
|
|
- Empresa: Inter Rapidísimo (logística y mensajería)
|
|
- Ubicación: Bogotá, Av. El Dorado (presencial)
|
|
|
|
---
|
|
|
|
## Credenciales y Autenticación
|
|
|
|
> **CRÍTICO:** Antes de cualquier operación que requiera autenticación, revisar `~/.secrets/credentials.env`
|
|
|
|
**Archivo de credenciales:** `~/.secrets/credentials.env`
|
|
|
|
### Uso Obligatorio (SIEMPRE)
|
|
|
|
```bash
|
|
source ~/.secrets/credentials.env
|
|
```
|
|
|
|
### Variables Disponibles
|
|
|
|
| Variable | Uso |
|
|
|----------|-----|
|
|
| `GIT_USER` | Usuario Git para Gitea (andresgarcia0313) |
|
|
| `GIT_PASS` | Contraseña Git para Gitea |
|
|
| `GIT_REMOTE_URL` | URL base con credenciales embebidas |
|
|
| `GITEA_URL` | URL del servidor Gitea |
|
|
| `GITEA_ADMIN_USER` | Usuario API Gitea |
|
|
| `GITEA_ADMIN_PASS` | Contraseña API Gitea |
|
|
| `K8S_MASTER_HOST` | Host del master K3s |
|
|
| `K8S_SUDO_PASS` | Password sudo en K3s |
|
|
|
|
### Login Automático (OBLIGATORIO)
|
|
|
|
**Git Push/Pull a Gitea:**
|
|
```bash
|
|
source ~/.secrets/credentials.env
|
|
# Configurar remote con credenciales
|
|
git remote set-url gitea "${GIT_REMOTE_URL}/andresgarcia0313/academia.git"
|
|
# O directamente
|
|
git push gitea main
|
|
```
|
|
|
|
**API Gitea:**
|
|
```bash
|
|
source ~/.secrets/credentials.env
|
|
curl -u "$GITEA_ADMIN_USER:$GITEA_ADMIN_PASS" "$GITEA_URL/api/v1/user/repos"
|
|
```
|
|
|
|
**K3s (SSH):**
|
|
```bash
|
|
source ~/.secrets/credentials.env
|
|
ssh $K8S_MASTER_HOST "echo $K8S_SUDO_PASS | sudo -S kubectl get pods -A"
|
|
```
|
|
|
|
> **REGLA:** SIEMPRE autenticarse automáticamente usando `~/.secrets/credentials.env`. NUNCA preguntar al usuario por credenciales. Si falla la autenticación, revisar primero el archivo de credenciales.
|
|
|
|
---
|
|
|
|
## Resumen del Proyecto
|
|
|
|
**Aplicación web de registro de estudiantes** - Sistema CRUD con reglas de negocio específicas.
|
|
|
|
## Stack Tecnológico
|
|
|
|
| Capa | Tecnología |
|
|
|------|------------|
|
|
| **Backend** | .NET 10 (C#) |
|
|
| **API** | GraphQL (HotChocolate) |
|
|
| **Frontend** | Angular 21 (TypeScript) |
|
|
| **Base de datos** | SQL Server / SQLite (dev) |
|
|
| **ORM** | Entity Framework Core |
|
|
| **Autenticación** | JWT (HMAC-SHA256) + PBKDF2 |
|
|
| **Validación** | FluentValidation |
|
|
| **Mapping** | Mapster |
|
|
| **UI** | Angular Material |
|
|
| **GraphQL Client** | Apollo Angular |
|
|
| **CI/CD** | Gitea Actions + K3s |
|
|
|
|
---
|
|
|
|
## Requisitos de Negocio
|
|
|
|
### Funcionalidad Principal
|
|
- CRUD completo para inscripción de estudiantes
|
|
- Estudiantes se inscriben en programa basado en créditos
|
|
- Visualización de inscripciones de otros estudiantes (solo nombres en clases compartidas)
|
|
|
|
### Reglas del Dominio (CRÍTICAS)
|
|
- **10 asignaturas** en total, cada una vale **3 créditos**
|
|
- **5 profesores**, cada uno imparte **exactamente 2 asignaturas**
|
|
- Estudiantes pueden seleccionar **máximo 3 asignaturas** (= 9 créditos)
|
|
- **Restricción clave:** Un estudiante NO puede tener clases con el mismo profesor
|
|
|
|
---
|
|
|
|
## Arquitectura
|
|
|
|
### Clean Architecture + CQRS (4 Capas)
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ HOST (Composition Root) │
|
|
│ Program.cs / DI / Configuration │
|
|
└──────────────────────────────┬──────────────────────────────────┘
|
|
│
|
|
┌──────────────────────────────▼──────────────────────────────────┐
|
|
│ ADAPTERS │
|
|
│ ┌─────────────────────────────────────────────────────────┐ │
|
|
│ │ DRIVING (Primary) │ DRIVEN (Secondary) │ │
|
|
│ │ ───────────────── │ ────────────────── │ │
|
|
│ │ GraphQL API ◄──Angular SPA │ Persistence (EF Core) │ │
|
|
│ │ (HotChocolate) │ DataLoaders │ │
|
|
│ │ Middleware │ External Services │ │
|
|
│ └─────────────────────────────────────────────────────────┘ │
|
|
└──────────────────────────────┬──────────────────────────────────┘
|
|
│
|
|
┌──────────────────────────────▼──────────────────────────────────┐
|
|
│ APPLICATION │
|
|
│ ┌─────────────────────────────────────────────────────────┐ │
|
|
│ │ Commands / Queries / Handlers / DTOs / Validators │ │
|
|
│ └─────────────────────────────────────────────────────────┘ │
|
|
└──────────────────────────────┬──────────────────────────────────┘
|
|
│
|
|
┌──────────────────────────────▼──────────────────────────────────┐
|
|
│ DOMAIN │
|
|
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────────┐ │
|
|
│ │ Entities │ │ Value │ │ Domain │ │ Ports │ │
|
|
│ │ │ │ Objects │ │ Services │ │ (Contracts) │ │
|
|
│ └───────────┘ └───────────┘ └───────────┘ └───────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### Regla de Dependencia (INVIOLABLE)
|
|
|
|
```
|
|
Host → Adapters → Application → Domain
|
|
│ ▲
|
|
└── implementa Ports ────┘
|
|
|
|
• Domain define Ports (interfaces)
|
|
• Adapters/Driven implementa Ports
|
|
• Domain NO depende de NADA externo
|
|
```
|
|
|
|
### Nomenclatura Ports & Adapters
|
|
|
|
| Término | Significado | Ubicación |
|
|
|---------|-------------|-----------|
|
|
| **Ports** | Contratos/Interfaces | `Domain/Ports/` |
|
|
| **Driving Adapters** | Entrada (quien llama) | `Adapters/Driving/` |
|
|
| **Driven Adapters** | Salida (a quien se llama) | `Adapters/Driven/` |
|
|
|
|
### Diagramas UML
|
|
|
|
Ubicación: `docs/architecture/diagrams/`
|
|
|
|
| Diagrama | Archivo | Propósito |
|
|
|----------|---------|-----------|
|
|
| Casos de Uso | `01-use-cases.puml` | Funcionalidades del estudiante |
|
|
| Modelo de Dominio | `02-domain-model.puml` | Entidades y Value Objects |
|
|
| Secuencia | `03-sequence-enrollment.puml` | Flujo de inscripción |
|
|
| Componentes | `04-components.puml` | Arquitectura del sistema |
|
|
| Entidad-Relación | `05-entity-relationship.puml` | Modelo de base de datos |
|
|
| Estados | `06-state-enrollment.puml` | Estados de inscripción |
|
|
| Despliegue | `07-deployment.puml` | Infraestructura Docker |
|
|
| C4 Contexto | `08-c4-context.puml` | Vista de alto nivel |
|
|
|
|
Regenerar SVG: `cat archivo.puml | plantuml -tsvg -pipe > archivo.svg`
|
|
|
|
---
|
|
|
|
## Estructura del Proyecto
|
|
|
|
```
|
|
/
|
|
├── src/
|
|
│ │
|
|
│ │ ═══════════════ BACKEND (.NET 10) ═══════════════
|
|
│ │
|
|
│ ├── backend/
|
|
│ │ │
|
|
│ │ ├── Domain/ # ENTITIES (Núcleo puro)
|
|
│ │ │ ├── Entities/ # Student, Subject, Professor, Enrollment, User
|
|
│ │ │ ├── ValueObjects/ # Email
|
|
│ │ │ ├── ReadModels/ # ClassmateInfo
|
|
│ │ │ ├── Exceptions/ # DomainException
|
|
│ │ │ ├── Ports/
|
|
│ │ │ │ └── Repositories/ # IStudentRepository, IUserRepository, etc.
|
|
│ │ │ └── Services/ # EnrollmentDomainService
|
|
│ │ │
|
|
│ │ ├── Application/ # USE CASES (CQRS)
|
|
│ │ │ ├── Common/
|
|
│ │ │ │ ├── Behaviors/ # ValidationBehavior
|
|
│ │ │ │ └── ValidationPatterns.cs # Regex patterns centralizados
|
|
│ │ │ ├── Auth/ # Autenticación
|
|
│ │ │ │ ├── Commands/ # LoginCommand, RegisterCommand, ResetPasswordCommand
|
|
│ │ │ │ ├── DTOs/ # AuthDtos (LoginRequest, RegisterRequest, etc.)
|
|
│ │ │ │ ├── IJwtService.cs # Interfaz JWT
|
|
│ │ │ │ ├── IPasswordService.cs # Interfaz hashing
|
|
│ │ │ │ └── JwtOptions.cs # Configuración JWT
|
|
│ │ │ ├── Students/
|
|
│ │ │ │ ├── Commands/ # CreateStudent, UpdateStudent, DeleteStudent
|
|
│ │ │ │ ├── Queries/ # GetStudents, GetStudentById, GetStudentsPaged
|
|
│ │ │ │ └── DTOs/ # StudentDto
|
|
│ │ │ ├── Subjects/
|
|
│ │ │ │ ├── Queries/ # GetSubjects, GetAvailableSubjects
|
|
│ │ │ │ └── DTOs/ # SubjectDto
|
|
│ │ │ ├── Professors/
|
|
│ │ │ │ ├── Queries/ # GetProfessors
|
|
│ │ │ │ └── DTOs/ # ProfessorDto
|
|
│ │ │ ├── Enrollments/
|
|
│ │ │ │ ├── Commands/ # EnrollStudent, UnenrollStudent
|
|
│ │ │ │ ├── Queries/ # GetClassmates
|
|
│ │ │ │ └── DTOs/ # EnrollmentDtos
|
|
│ │ │ └── DependencyInjection.cs
|
|
│ │ │
|
|
│ │ ├── Adapters/ # INTERFACE ADAPTERS
|
|
│ │ │ │
|
|
│ │ │ ├── Driving/ # Entrada (Primary)
|
|
│ │ │ │ └── Api/ # GraphQL (HotChocolate)
|
|
│ │ │ │ ├── Types/
|
|
│ │ │ │ │ ├── Auth/ # AuthMutations, AuthQueries
|
|
│ │ │ │ │ ├── Students/ # StudentType
|
|
│ │ │ │ │ ├── Subjects/ # SubjectType
|
|
│ │ │ │ │ ├── Professors/ # ProfessorType
|
|
│ │ │ │ │ ├── Enrollments/ # EnrollmentType
|
|
│ │ │ │ │ ├── Query.cs
|
|
│ │ │ │ │ └── Mutation.cs
|
|
│ │ │ │ ├── Middleware/ # GraphQLErrorFilter
|
|
│ │ │ │ └── Extensions/ # GraphQLExtensions
|
|
│ │ │ │
|
|
│ │ │ └── Driven/ # Salida (Secondary)
|
|
│ │ │ └── Persistence/ # EF Core
|
|
│ │ │ ├── Context/ # AppDbContext
|
|
│ │ │ ├── Configurations/# Fluent API configs (incl. UserConfiguration)
|
|
│ │ │ ├── Repositories/ # Student, Subject, Professor, Enrollment, User, UnitOfWork
|
|
│ │ │ ├── Services/ # JwtService, PasswordService
|
|
│ │ │ ├── DataLoaders/ # StudentById, SubjectById, ProfessorById
|
|
│ │ │ ├── Migrations/ # InitialCreate, SeedData, AddUsersTable
|
|
│ │ │ ├── Seeding/ # DataSeeder
|
|
│ │ │ ├── CompiledQueries.cs
|
|
│ │ │ └── DependencyInjection.cs
|
|
│ │ │
|
|
│ │ └── Host/ # COMPOSITION ROOT
|
|
│ │ └── Program.cs
|
|
│ │
|
|
│ │ ═══════════════ FRONTEND (Angular 21) ═══════════════
|
|
│ │
|
|
│ └── frontend/
|
|
│ ├── src/
|
|
│ │ ├── app/
|
|
│ │ │ ├── core/ # Singleton services
|
|
│ │ │ │ ├── services/ # AuthService, StudentService, EnrollmentService, NotificationService
|
|
│ │ │ │ ├── guards/ # auth.guard.ts (authGuard, adminGuard, guestGuard)
|
|
│ │ │ │ ├── interceptors/ # ErrorInterceptor, AuthInterceptor
|
|
│ │ │ │ ├── models/ # student.model.ts
|
|
│ │ │ │ └── graphql/
|
|
│ │ │ │ ├── queries/ # students.queries.ts
|
|
│ │ │ │ ├── mutations/ # students.mutations.ts, auth.mutations.ts
|
|
│ │ │ │ └── generated/ # types.ts (Apollo codegen)
|
|
│ │ │ ├── shared/ # Componentes reutilizables
|
|
│ │ │ │ ├── components/ui/ # ConfirmDialog, EmptyState, LoadingSpinner
|
|
│ │ │ │ └── pipes/ # credits.pipe, initials.pipe
|
|
│ │ │ └── features/ # Módulos por funcionalidad
|
|
│ │ │ ├── auth/ # Autenticación
|
|
│ │ │ │ └── pages/ # Login, Register, ResetPassword
|
|
│ │ │ ├── dashboard/ # Dashboard estudiante
|
|
│ │ │ │ └── pages/ # StudentDashboard
|
|
│ │ │ ├── students/
|
|
│ │ │ │ └── pages/ # StudentList, StudentForm
|
|
│ │ │ ├── enrollment/
|
|
│ │ │ │ └── pages/ # EnrollmentPage
|
|
│ │ │ └── classmates/
|
|
│ │ │ └── pages/ # ClassmatesPage
|
|
│ │ ├── environments/ # environment.ts, environment.prod.ts
|
|
│ │ └── main.ts
|
|
│ └── e2e/ # Playwright E2E tests
|
|
│ ├── mocks/ # graphql.mock.ts
|
|
│ ├── student-crud.spec.ts
|
|
│ ├── enrollment.spec.ts
|
|
│ └── classmates.spec.ts
|
|
│
|
|
├── tests/ # Backend tests
|
|
│ ├── Common/ # Builders compartidos
|
|
│ │ └── Builders/ # StudentBuilder, SubjectBuilder, etc.
|
|
│ ├── Domain.Tests/
|
|
│ │ ├── Entities/ # StudentTests
|
|
│ │ ├── ValueObjects/ # EmailTests
|
|
│ │ └── Services/ # EnrollmentDomainServiceTests
|
|
│ ├── Application.Tests/
|
|
│ │ ├── Students/ # StudentCommandsTests, StudentQueriesTests
|
|
│ │ ├── Enrollments/ # EnrollStudent, Unenroll, GetClassmates Tests
|
|
│ │ ├── Subjects/ # SubjectQueriesTests
|
|
│ │ ├── Professors/ # ProfessorQueriesTests
|
|
│ │ └── Validators/ # ValidatorTests
|
|
│ └── Integration.Tests/ # EnrollmentFlowTests
|
|
│
|
|
├── scripts/
|
|
│ └── dev-start.sh # Script desarrollo local (SQLite)
|
|
│
|
|
├── docs/
|
|
│ ├── architecture/
|
|
│ │ └── decisions/ # ADR-001 a ADR-004
|
|
│ ├── entregables/
|
|
│ │ ├── 01-analisis/ # Requisitos, reglas, historias, riesgos
|
|
│ │ ├── 02-diseno/ # Arquitectura, modelo dominio, DB, GraphQL, UI
|
|
│ │ └── 03-configuracion/ # Repositorio, .NET, Angular, DB, env, calidad
|
|
│ ├── qa/ # Reportes de QA
|
|
│ │ ├── QA-REPORT-*-MANUAL-TESTS.md
|
|
│ │ └── QA-REPORT-*-REGRESSION-TESTS.md
|
|
│ ├── CODE_REVIEW_CHECKLIST.md
|
|
│ ├── DEFECTOS_QA.md # Defectos encontrados
|
|
│ ├── DEPLOYMENT.md
|
|
│ ├── ENTREGABLES.md
|
|
│ ├── OWASP_CHECKLIST.md
|
|
│ ├── PLAN_ACTIVIDADES.md
|
|
│ ├── RECOMMENDATIONS.md # Recomendaciones de mejora
|
|
│ └── Prueba Técnica.md
|
|
│
|
|
├── database/
|
|
│ ├── stored-procedures/
|
|
│ └── views/
|
|
│
|
|
├── deploy/
|
|
│ ├── docker/
|
|
│ │ ├── Dockerfile.api # Multi-stage Alpine + .NET 10
|
|
│ │ ├── Dockerfile.frontend # Multi-stage Node + Nginx
|
|
│ │ ├── docker-compose.yml
|
|
│ │ ├── nginx.conf # Proxy + SPA routing
|
|
│ │ └── start.sh # Script de despliegue Docker
|
|
│ ├── k3s/ # Kubernetes manifests
|
|
│ │ ├── api.yaml # Deployment + Service API
|
|
│ │ ├── frontend.yaml # Deployment + Service Frontend
|
|
│ │ ├── sqlserver.yaml # StatefulSet SQL Server
|
|
│ │ ├── ingress.yaml # Traefik + HTTPS
|
|
│ │ ├── hpa.yaml # Horizontal Pod Autoscaler
|
|
│ │ ├── kustomization.yaml # Kustomize overlay
|
|
│ │ └── deploy.sh # Script orquestación K3s
|
|
│ └── scripts/
|
|
│ └── deploy-k3s.sh # Deploy remoto
|
|
│
|
|
└── .gitea/
|
|
└── workflows/
|
|
└── deploy.yaml # CI/CD Pipeline
|
|
```
|
|
|
|
---
|
|
|
|
## Comandos de Desarrollo
|
|
|
|
### Backend (.NET)
|
|
|
|
```bash
|
|
# Restaurar dependencias
|
|
dotnet restore
|
|
|
|
# Build completo
|
|
dotnet build
|
|
|
|
# Ejecutar GraphQL API (puerto 5000/5001)
|
|
dotnet run --project src/backend/Host
|
|
|
|
# Tests
|
|
dotnet test # Todos
|
|
dotnet test --filter "Category=Unit" # Solo unit
|
|
dotnet test --filter "Category=Integration" # Solo integration
|
|
|
|
# Migraciones EF Core
|
|
dotnet ef migrations add InitialCreate \
|
|
-p src/backend/Adapters/Driven/Persistence \
|
|
-s src/backend/Host
|
|
dotnet ef database update \
|
|
-p src/backend/Adapters/Driven/Persistence \
|
|
-s src/backend/Host
|
|
|
|
# Watch mode (hot reload)
|
|
dotnet watch run --project src/backend/Host
|
|
|
|
# GraphQL Playground disponible en: https://localhost:5001/graphql
|
|
```
|
|
|
|
### Frontend (Angular)
|
|
|
|
```bash
|
|
cd src/frontend
|
|
|
|
# Instalar dependencias
|
|
npm install
|
|
|
|
# Servidor desarrollo (puerto 4200)
|
|
ng serve
|
|
|
|
# Build producción
|
|
ng build --configuration production
|
|
|
|
# Tests unitarios
|
|
ng test
|
|
ng test --watch=false --code-coverage # Con coverage
|
|
|
|
# E2E tests
|
|
npx playwright test
|
|
|
|
# Lint
|
|
ng lint
|
|
|
|
# Generar componente
|
|
ng g c features/students/components/my-component --standalone
|
|
```
|
|
|
|
### Desarrollo Local (Sin Docker)
|
|
|
|
Script que levanta backend + frontend con **SQLite** (sin necesidad de SQL Server):
|
|
|
|
```bash
|
|
# Iniciar todo
|
|
./scripts/dev-start.sh start
|
|
|
|
# Ver estado
|
|
./scripts/dev-start.sh status
|
|
|
|
# Detener
|
|
./scripts/dev-start.sh stop
|
|
|
|
# Reiniciar
|
|
./scripts/dev-start.sh restart
|
|
```
|
|
|
|
**Características:**
|
|
- Backend usa SQLite en `./data/dev.db`
|
|
- No requiere Docker ni SQL Server
|
|
- Frontend en puerto 4200
|
|
- Backend en puerto 5000
|
|
- Hot reload habilitado
|
|
- PIDs guardados para cleanup
|
|
|
|
### Docker
|
|
|
|
```bash
|
|
# Levantar todo el stack
|
|
docker-compose up -d
|
|
|
|
# Solo base de datos
|
|
docker-compose up -d sqlserver
|
|
|
|
# Rebuild
|
|
docker-compose up -d --build
|
|
|
|
# Logs
|
|
docker-compose logs -f api
|
|
```
|
|
|
|
### Docker Compose Optimizado (Producción)
|
|
|
|
Ubicación: `deploy/docker/`
|
|
|
|
```bash
|
|
cd deploy/docker
|
|
./start.sh # Despliegue con un solo comando
|
|
```
|
|
|
|
**Recursos asignados (optimizado para 12 cores / 15GB RAM):**
|
|
|
|
| Servicio | CPU | RAM | Características |
|
|
|----------|-----|-----|-----------------|
|
|
| SQL Server | 2 cores | 2.5 GB | Volumen persistente |
|
|
| API .NET | 4 cores | 1.5 GB | Server GC, ReadyToRun, Health check |
|
|
| Frontend | 2 cores | 256 MB | Nginx + Brotli, cache agresivo |
|
|
|
|
**URLs después del despliegue:**
|
|
- Frontend: http://localhost
|
|
- API GraphQL: http://localhost:5000/graphql
|
|
- Health Check: http://localhost:5000/health
|
|
|
|
### Despliegue K3s (Producción)
|
|
|
|
**Dominio:** `https://academia.ingeniumcodex.com`
|
|
|
|
```bash
|
|
cd deploy/k3s
|
|
./deploy.sh all # Build + transfer + deploy completo
|
|
./deploy.sh status # Ver estado
|
|
./deploy.sh clean # Eliminar namespace
|
|
```
|
|
|
|
**URLs de producción:**
|
|
- Frontend: https://academia.ingeniumcodex.com
|
|
- API GraphQL: https://academia.ingeniumcodex.com/graphql
|
|
- Health Check: https://academia.ingeniumcodex.com/health
|
|
|
|
**Autenticación:**
|
|
- Login: https://academia.ingeniumcodex.com/login
|
|
- Registro estudiantes: https://academia.ingeniumcodex.com/register
|
|
- Reset password: https://academia.ingeniumcodex.com/reset-password
|
|
- Dashboard estudiante: https://academia.ingeniumcodex.com/dashboard
|
|
|
|
**Namespace:** `academia`
|
|
|
|
### CI/CD Pipeline (Gitea Actions)
|
|
|
|
**Ubicación:** `.gitea/workflows/deploy.yaml`
|
|
|
|
**Trigger:** Push a `main`
|
|
|
|
**Flujo automático:**
|
|
1. Checkout código
|
|
2. Sync a K3s master vía rsync
|
|
3. Build imágenes en paralelo (API + Frontend)
|
|
4. Import a K3s containerd
|
|
5. Apply Kustomize manifests
|
|
6. Rolling restart deployments
|
|
7. Health checks
|
|
8. Rollback automático si falla
|
|
|
|
**Secretos requeridos en Gitea:**
|
|
- `K3S_SSH_KEY`: Clave SSH privada
|
|
- `K3S_SUDO_PASS`: Password sudo en K3s
|
|
|
|
**Tiempo de despliegue:** ~3-5 minutos
|
|
|
|
---
|
|
|
|
## GraphQL API
|
|
|
|
**Endpoint:** `https://localhost:5001/graphql`
|
|
**Playground:** `https://localhost:5001/graphql` (Banana Cake Pop)
|
|
|
|
### Queries
|
|
|
|
```graphql
|
|
# Obtener usuario autenticado (requiere JWT)
|
|
query Me {
|
|
me {
|
|
id
|
|
username
|
|
role
|
|
studentId
|
|
studentName
|
|
}
|
|
}
|
|
|
|
# Obtener todos los estudiantes
|
|
query GetStudents {
|
|
students {
|
|
id
|
|
name
|
|
email
|
|
totalCredits
|
|
enrollments {
|
|
subject {
|
|
name
|
|
credits
|
|
professor { name }
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
# Obtener estudiante por ID
|
|
query GetStudentById($id: Int!) {
|
|
student(id: $id) {
|
|
id
|
|
name
|
|
email
|
|
enrollments { subject { name } }
|
|
}
|
|
}
|
|
|
|
# Obtener todas las materias
|
|
query GetSubjects {
|
|
subjects {
|
|
id
|
|
name
|
|
credits
|
|
professor { id name }
|
|
}
|
|
}
|
|
|
|
# Obtener materias disponibles para un estudiante (filtra restricciones)
|
|
query GetAvailableSubjects($studentId: Int!) {
|
|
availableSubjects(studentId: $studentId) {
|
|
id
|
|
name
|
|
credits
|
|
professor { name }
|
|
isAvailable # false si ya tiene materia del mismo profesor
|
|
unavailableReason # "Ya tienes una materia con este profesor"
|
|
}
|
|
}
|
|
|
|
# Ver compañeros de clase por materia
|
|
query GetClassmates($studentId: Int!) {
|
|
classmates(studentId: $studentId) {
|
|
subjectName
|
|
students { name }
|
|
}
|
|
}
|
|
|
|
# Obtener todos los profesores
|
|
query GetProfessors {
|
|
professors {
|
|
id
|
|
name
|
|
subjects { id name }
|
|
}
|
|
}
|
|
```
|
|
|
|
### Mutations
|
|
|
|
```graphql
|
|
# ========== AUTENTICACIÓN ==========
|
|
|
|
# Login
|
|
mutation Login($input: LoginRequestInput!) {
|
|
login(input: $input) {
|
|
success
|
|
token
|
|
error
|
|
user {
|
|
id
|
|
username
|
|
role
|
|
studentId
|
|
studentName
|
|
}
|
|
}
|
|
}
|
|
|
|
# Registro (crea User + Student opcionalmente)
|
|
mutation Register($input: RegisterRequestInput!) {
|
|
register(input: $input) {
|
|
success
|
|
token
|
|
error
|
|
recoveryCode # Solo se muestra UNA vez
|
|
user { id username role studentId studentName }
|
|
}
|
|
}
|
|
|
|
# Recuperar contraseña
|
|
mutation ResetPassword($input: ResetPasswordRequestInput!) {
|
|
resetPassword(input: $input) {
|
|
success
|
|
error
|
|
}
|
|
}
|
|
|
|
# ========== ESTUDIANTES ==========
|
|
|
|
# Crear estudiante
|
|
mutation CreateStudent($input: CreateStudentInput!) {
|
|
createStudent(input: $input) {
|
|
student { id name email }
|
|
errors
|
|
}
|
|
}
|
|
|
|
# Actualizar estudiante
|
|
mutation UpdateStudent($id: Int!, $input: UpdateStudentInput!) {
|
|
updateStudent(id: $id, input: $input) {
|
|
student { id name email }
|
|
errors
|
|
}
|
|
}
|
|
|
|
# Eliminar estudiante
|
|
mutation DeleteStudent($id: Int!) {
|
|
deleteStudent(id: $id) {
|
|
success
|
|
errors
|
|
}
|
|
}
|
|
|
|
# Inscribir estudiante en materia
|
|
mutation EnrollStudent($input: EnrollStudentInput!) {
|
|
enrollStudent(input: $input) {
|
|
enrollment {
|
|
id
|
|
student { name }
|
|
subject { name }
|
|
}
|
|
errors # ["Máximo 3 materias", "Ya tienes materia con este profesor"]
|
|
}
|
|
}
|
|
|
|
# Cancelar inscripción
|
|
mutation UnenrollStudent($enrollmentId: Int!) {
|
|
unenrollStudent(enrollmentId: $enrollmentId) {
|
|
success
|
|
errors
|
|
}
|
|
}
|
|
```
|
|
|
|
### Subscriptions (Opcional - Tiempo Real)
|
|
|
|
```graphql
|
|
# Notificación cuando un estudiante se inscribe
|
|
subscription OnStudentEnrolled {
|
|
studentEnrolled {
|
|
student { name }
|
|
subject { name }
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Autenticación
|
|
|
|
### Sistema JWT
|
|
|
|
**Algoritmo:** HMAC-SHA256
|
|
**Expiración:** Configurable (default 60 min)
|
|
**Hashing passwords:** PBKDF2-SHA256 con 100,000 iteraciones
|
|
|
|
### Flujos de Autenticación
|
|
|
|
| Flujo | Endpoint | Descripción |
|
|
|-------|----------|-------------|
|
|
| **Login** | `mutation login` | Valida credenciales, retorna JWT + UserInfo |
|
|
| **Registro** | `mutation register` | Crea User + Student (opcional), genera Recovery Code |
|
|
| **Reset Password** | `mutation resetPassword` | Valida recovery code, actualiza password |
|
|
|
|
### Entidad User
|
|
|
|
```csharp
|
|
public class User {
|
|
public int Id;
|
|
public string Username; // Almacenado en minúsculas
|
|
public string PasswordHash; // PBKDF2-SHA256
|
|
public string RecoveryCodeHash; // Para reset password
|
|
public string Role; // "Admin" | "Student"
|
|
public int? StudentId; // FK a Student (nullable)
|
|
public DateTime CreatedAt;
|
|
public DateTime? LastLoginAt;
|
|
}
|
|
```
|
|
|
|
### Roles y Guards
|
|
|
|
| Rol | Acceso |
|
|
|-----|--------|
|
|
| **Admin** | CRUD completo de estudiantes, ver todo |
|
|
| **Student** | Dashboard propio, inscripciones propias, ver compañeros |
|
|
|
|
**Guards Angular:**
|
|
- `authGuard`: Requiere autenticación → redirige a `/login`
|
|
- `adminGuard`: Requiere role Admin → redirige a `/dashboard`
|
|
- `guestGuard`: Solo no autenticados → redirige a `/dashboard`
|
|
|
|
### Variables de Entorno JWT
|
|
|
|
```bash
|
|
JWT_SECRET_KEY # Secret para firmar tokens (REQUERIDO, mín. 32 chars)
|
|
JWT_ISSUER # Default: "StudentEnrollmentApi"
|
|
JWT_AUDIENCE # Default: "StudentEnrollmentApp"
|
|
JWT_EXPIRATION_MINUTES # Default: 60
|
|
```
|
|
|
|
### Seguridad Implementada
|
|
|
|
- **PBKDF2-SHA256** con 100,000 iteraciones (salt 16 bytes)
|
|
- **Fixed-time comparison** para recovery codes (timing attacks)
|
|
- **Rate limiting**: 30 mutations/min, 100 queries/min
|
|
- **JWT validation**: Issuer, Audience, Lifetime, SigningKey
|
|
- **Recovery code**: 12 caracteres, mostrado solo una vez
|
|
- **Serilog**: Filtra tokens y passwords de logs
|
|
|
|
---
|
|
|
|
## Validaciones de Negocio
|
|
|
|
### Ubicación en el Código
|
|
|
|
| Validación | Capa | Ruta |
|
|
|------------|------|------|
|
|
| Email válido | Domain | `Domain/ValueObjects/Email.cs` |
|
|
| Max 3 materias | Domain | `Domain/Services/EnrollmentDomainService.cs` |
|
|
| No repetir profesor | Domain | `Domain/Services/EnrollmentDomainService.cs` |
|
|
| Datos request válidos | Application | `Application/{Feature}/Commands/*Validator.cs` |
|
|
| Estudiante existe | Application | `Application/{Feature}/Commands/*Handler.cs` |
|
|
| Repos implementados | Adapters | `Adapters/Driven/Persistence/Repositories/` |
|
|
|
|
### Reglas Críticas
|
|
|
|
```csharp
|
|
// Domain/Services/EnrollmentDomainService.cs
|
|
public void ValidateEnrollment(Student student, Subject newSubject)
|
|
{
|
|
// Regla 1: Max 3 materias
|
|
if (student.Enrollments.Count >= 3)
|
|
throw new MaxEnrollmentsExceededException(student.Id);
|
|
|
|
// Regla 2: No repetir profesor
|
|
var professorIds = student.Enrollments.Select(e => e.Subject.ProfessorId);
|
|
if (professorIds.Contains(newSubject.ProfessorId))
|
|
throw new SameProfessorConstraintException(student.Id, newSubject.ProfessorId);
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Manejo de Errores
|
|
|
|
### Códigos de Error del Backend
|
|
|
|
| Código | Mensaje Usuario | Causa |
|
|
|--------|-----------------|-------|
|
|
| `MAX_ENROLLMENTS` | Has alcanzado el límite máximo de 3 materias | Estudiante intenta inscribir 4ta materia |
|
|
| `SAME_PROFESSOR` | Ya tienes una materia con este profesor | Violación restricción profesor único |
|
|
| `STUDENT_NOT_FOUND` | El estudiante no existe en el sistema | ID inválido o eliminado |
|
|
| `SUBJECT_NOT_FOUND` | La materia seleccionada no existe | ID materia inválido |
|
|
| `DUPLICATE_ENROLLMENT` | Ya estás inscrito en esta materia | Inscripción duplicada |
|
|
| `VALIDATION_ERROR` | Los datos ingresados no son válidos | FluentValidation falló |
|
|
| `NETWORK_ERROR` | No se pudo conectar con el servidor | API no disponible |
|
|
| `INVALID_CREDENTIALS` | Usuario o contraseña incorrectos | Login fallido |
|
|
| `USERNAME_EXISTS` | El nombre de usuario ya está en uso | Registro duplicado |
|
|
| `INVALID_RECOVERY_CODE` | Código de recuperación inválido | Reset password fallido |
|
|
| `UNAUTHORIZED` | No tienes permiso para esta acción | JWT inválido o expirado |
|
|
|
|
### Frontend: Servicio de Errores
|
|
|
|
```typescript
|
|
// core/services/error-handler.service.ts
|
|
// Uso en componentes:
|
|
this.errorHandler.handle(error, 'Contexto.accion');
|
|
|
|
// Características:
|
|
// - Mensajes amigables para usuarios
|
|
// - Logging detallado en consola (solo dev)
|
|
// - Traducción automática de códigos GraphQL
|
|
```
|
|
|
|
### Backend: Filtro de Errores
|
|
|
|
```csharp
|
|
// Adapters/Driving/Api/Middleware/GraphQLErrorFilter.cs
|
|
// Transforma excepciones de dominio a errores GraphQL
|
|
// con código y mensaje estructurado
|
|
```
|
|
|
|
### Monitoreo de Conectividad
|
|
|
|
El sistema verifica la conexión con el servidor cada **5 segundos**:
|
|
|
|
| Componente | Archivo | Función |
|
|
|------------|---------|---------|
|
|
| Backend | `Host/Program.cs` | Endpoint `/health` con estado DB |
|
|
| Servicio | `core/services/connectivity.service.ts` | Polling y estado reactivo |
|
|
| Overlay | `shared/components/ui/connectivity-overlay/` | UI bloqueante |
|
|
|
|
**Comportamiento:**
|
|
- Verifica `/health` cada 5 segundos
|
|
- Requiere 2 fallos consecutivos para mostrar overlay (evita falsos positivos)
|
|
- Overlay bloquea toda interacción hasta restaurar conexión
|
|
- Muestra instrucciones para solucionar el problema
|
|
|
|
---
|
|
|
|
## Convenciones
|
|
|
|
### .NET
|
|
- **Async/Await:** Todos los métodos I/O
|
|
- **Records:** Para DTOs inmutables
|
|
- **Nullable:** Habilitado globalmente
|
|
- **Naming:** PascalCase clases/métodos, camelCase variables
|
|
|
|
### Angular
|
|
- **Standalone:** Todos los componentes
|
|
- **Signals:** Estado reactivo
|
|
- **Lazy Loading:** Por feature
|
|
- **OnPush:** Change detection strategy
|
|
|
|
### Commits
|
|
```
|
|
feat(students): add create student form
|
|
fix(enrollment): validate professor constraint
|
|
refactor(api): extract validation middleware
|
|
test(domain): add enrollment policy tests
|
|
docs(readme): update setup instructions
|
|
```
|
|
|
|
---
|
|
|
|
## Restricciones Críticas
|
|
|
|
### NUNCA
|
|
- Modificar sin leer archivo completo primero
|
|
- Archivos > 100 líneas (refactorizar)
|
|
- Hardcodear connection strings
|
|
- Lógica de negocio en Controllers
|
|
- Exponer entidades de dominio en API
|
|
|
|
### SIEMPRE
|
|
- DTOs para entrada/salida
|
|
- Tests para reglas de negocio
|
|
- Validar antes de persistir
|
|
- Async en operaciones I/O
|
|
|
|
---
|
|
|
|
## Actualización de Documentación (OBLIGATORIO)
|
|
|
|
> **REGLA:** Después de implementar cambios significativos, SIEMPRE actualizar la documentación correspondiente.
|
|
|
|
### Cuándo Actualizar
|
|
|
|
| Tipo de Cambio | Documentos a Actualizar |
|
|
|----------------|------------------------|
|
|
| Nueva entidad/campo en dominio | `DI-002-modelo-dominio.md`, `02-domain-model.puml` |
|
|
| Nuevo endpoint GraphQL | `DI-004-esquema-graphql.md` |
|
|
| Nueva funcionalidad | `AN-001-requisitos-funcionales.md`, `AN-003-historias-usuario.md` |
|
|
| Cambios en arquitectura | `DI-001-arquitectura-backend.md`, `04-components.puml` |
|
|
| Nuevo flujo de usuario | `03-sequence-*.puml`, historia de usuario correspondiente |
|
|
| Cambios en BD | `DI-003-diseno-base-datos.md`, `05-entity-relationship.puml` |
|
|
| Nuevas rutas/páginas | `DI-005-arquitectura-frontend.md`, `DI-006-componentes-ui.md` |
|
|
| Cambios en despliegue | `DEPLOYMENT.md`, `07-deployment.puml` |
|
|
| Cualquier cambio significativo | `ENTREGABLES.md`, `README.md` |
|
|
|
|
### Archivos de Documentación
|
|
|
|
```
|
|
docs/
|
|
├── entregables/
|
|
│ ├── 01-analisis/ # Requisitos, historias, reglas
|
|
│ ├── 02-diseno/ # Arquitectura, modelo, esquemas
|
|
│ └── 03-configuracion/ # Setup, variables, calidad
|
|
├── architecture/
|
|
│ ├── decisions/ # ADRs (decisiones arquitectónicas)
|
|
│ └── diagrams/ # Diagramas PUML + SVG
|
|
├── qa/ # Reportes de QA
|
|
├── ENTREGABLES.md # Resumen ejecutivo
|
|
├── DEPLOYMENT.md # Guía de despliegue
|
|
└── README.md (raíz) # Documentación principal
|
|
```
|
|
|
|
### Diagramas PlantUML
|
|
|
|
**Ubicación:** `docs/architecture/diagrams/`
|
|
|
|
| Diagrama | Archivo | Actualizar cuando... |
|
|
|----------|---------|---------------------|
|
|
| Casos de Uso | `01-use-cases.puml` | Nuevas funcionalidades de usuario |
|
|
| Modelo Dominio | `02-domain-model.puml` | Cambios en entidades/relaciones |
|
|
| Secuencia | `03-sequence-*.puml` | Nuevos flujos o cambios en existentes |
|
|
| Componentes | `04-components.puml` | Cambios en arquitectura |
|
|
| E-R | `05-entity-relationship.puml` | Cambios en base de datos |
|
|
| Estados | `06-state-*.puml` | Nuevos estados o transiciones |
|
|
| Despliegue | `07-deployment.puml` | Cambios en infraestructura |
|
|
| C4 | `08-c4-context.puml` | Cambios en contexto del sistema |
|
|
|
|
**Validar y regenerar PUML después de modificar:**
|
|
```bash
|
|
# Validar que compila (sin errores)
|
|
cat docs/architecture/diagrams/archivo.puml | plantuml -tpng -pipe > /dev/null && echo "OK" || echo "ERROR"
|
|
|
|
# Regenerar PNG y SVG
|
|
cd docs/architecture/diagrams
|
|
cat archivo.puml | plantuml -tpng -pipe > archivo.png
|
|
cat archivo.puml | plantuml -tsvg -pipe > archivo.svg
|
|
|
|
# Validar TODOS los diagramas
|
|
for f in docs/architecture/diagrams/*.puml; do
|
|
echo -n "Validando $f... "
|
|
cat "$f" | plantuml -tpng -pipe > /dev/null 2>&1 && echo "OK" || echo "ERROR"
|
|
done
|
|
```
|
|
|
|
### Proceso de Actualización
|
|
|
|
1. **Identificar** qué documentos afecta el cambio
|
|
2. **Actualizar** archivos MD con la nueva información
|
|
3. **Modificar** diagramas PUML si aplica
|
|
4. **Validar** que los PUML compilan sin errores
|
|
5. **Regenerar** PNG y SVG de diagramas modificados
|
|
6. **Verificar** consistencia entre documentos
|
|
|
|
> **IMPORTANTE:** SIEMPRE validar que los archivos PUML compilan antes de hacer commit. Un diagrama con errores de sintaxis rompe la documentación.
|
|
|
|
### Ejemplo
|
|
|
|
Si se agrega un nuevo campo `ActivationCode` a la entidad `Student`:
|
|
|
|
1. ✅ Actualizar `DI-002-modelo-dominio.md` (agregar campo)
|
|
2. ✅ Actualizar `02-domain-model.puml` (diagrama de clases)
|
|
3. ✅ Actualizar `DI-004-esquema-graphql.md` (si se expone en API)
|
|
4. ✅ Actualizar `AN-001-requisitos-funcionales.md` (si es nuevo requisito)
|
|
5. ✅ Actualizar `ENTREGABLES.md` (resumen de funcionalidades)
|
|
|
|
---
|
|
|
|
## Ciclo OODA
|
|
|
|
1. **OBSERVAR:** ¿Qué se solicita? ¿Qué existe?
|
|
2. **ORIENTAR:** ¿Riesgos? ¿Restricciones?
|
|
3. **DECIDIR:** Si hay duda, investigar primero
|
|
4. **ACTUAR:** Ejecutar con precisión, validar
|
|
|
|
> **Regla de oro:** "Mide dos veces, corta una"
|