18. Integración full-stack: del clic al COMMIT

// Sin dependencias de Angular, Nest, Node ni ORM. Solo TypeScript puro.
export const TASK_STATUSES = ['todo', 'in_progress', 'done'] as const;
export type TaskStatus = (typeof TASK_STATUSES)[number];

/** Lo que la API DEVUELVE. Es un contrato público: cambiarlo rompe clientes. */
export interface TaskDto {
  id: string; title: string; description: string | null;
  status: TaskStatus; projectId: string;
  assignee: { id: string; name: string } | null;
  tags: { id: string; name: string; color: string }[];
  dueDate: string | null;                  // ISO 8601 en UTC, nunca un Date
  completedAt: string | null; updatedAt: string;
  version: number;                         // bloqueo optimista (18.13)
}

/** Lo que la API ACEPTA al cambiar el estado. */
export interface UpdateTaskStatusDto { status: TaskStatus; version: number }

// Reglas puras compartidas por las dos capas: una sola definición.
export const TASK_TITLE_MIN = 3;
export const TASK_TITLE_MAX = 200;

export function esTransicionValida(desde: TaskStatus, hasta: TaskStatus): boolean {
  if (desde === hasta) return false;
  return !(desde === 'done' && hasta === 'in_progress');   // reabrir vuelve a 'todo'
}

@Component({
  selector: 'tf-task-item',
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <li class="task" [class.task--done]="completada()">
      <input type="checkbox" [id]="'task-' + task().id" [checked]="completada()"
             [disabled]="guardando()" (change)="alternar($event)" />
      <label [for]="'task-' + task().id">{{ task().title }}</label>
      @if (guardando()) { <span aria-live="polite">Guardando…</span> }
    </li>`,
})
export class TaskItemComponent {
  readonly task = input.required<TaskDto>();          // entrada de solo lectura
  private readonly store = inject(TaskStore);
  protected readonly completada = computed(() => this.task().status === 'done');
  // El store expone qué ids están en vuelo; así no duplicamos estado aquí.
  protected readonly guardando = computed(() => this.store.enVuelo().has(this.task().id));

  protected alternar(evento: Event): void {
    const marcada = (evento.target as HTMLInputElement).checked;
    void this.store.cambiarEstado(this.task().id, marcada ? 'done' : 'todo');
  }
}

@Injectable({ providedIn: 'root' })
export class TaskStore {
  private readonly api = inject(TasksApi);
  private readonly toasts = inject(ToastService);
  private readonly _tasks = signal<readonly TaskDto[]>([]);
  private readonly _enVuelo = signal<ReadonlySet<string>>(new Set());
  readonly tasks = this._tasks.asReadonly();
  readonly enVuelo = this._enVuelo.asReadonly();
  readonly pendientes = computed(() => this._tasks().filter((t) => t.status !== 'done').length);

  async cambiarEstado(id: string, status: TaskStatus): Promise<void> {
    const original = this._tasks();                          // instantánea para revertir
    const actual = original.find((t) => t.id === id);
    if (!actual || actual.status === status) return;
    // (1) OPTIMISMO: pintamos el resultado esperado ya mismo.
    this.parchear(id, (t) => ({ ...t, status,
      completedAt: status === 'done' ? new Date().toISOString() : null }));
    this.marcarEnVuelo(id, true);
    try {
      // (2) La versión que enviamos es la que el usuario TENÍA al pulsar.
      const confirmada = await this.api.cambiarEstado(id, { status, version: actual.version });
      // (3) RECONCILIACIÓN: la respuesta sustituye a nuestra suposición; trae la
      //     version y el updatedAt reales, que no podíamos adivinar.
      this.parchear(id, () => confirmada);
    } catch (e) {
      this._tasks.set(original);                             // (4) REVERSIÓN exacta
      await this.resolverConflicto(e as ApiError, id, status);
    } finally { this.marcarEnVuelo(id, false); }
  }

  private parchear(id: string, fn: (t: TaskDto) => TaskDto): void {
    this._tasks.update((l) => l.map((t) => (t.id === id ? fn(t) : t)));
  }

  private marcarEnVuelo(id: string, activo: boolean): void {
    this._enVuelo.update((set) => {
      const copia = new Set(set);        // nueva referencia: la señal notifica
      activo ? copia.add(id) : copia.delete(id);
      return copia;
    });
  }
}

@Injectable({ providedIn: 'root' })
export class TasksApi {
  private readonly http = inject(HttpClient);
  private readonly base = `${environment.apiUrl}/v1/tasks`;

  obtener = (id: string): Promise<TaskDto> =>
    firstValueFrom(this.http.get<TaskDto>(`${this.base}/${id}`));
  // El tipo del cuerpo y el de la respuesta salen los dos de @taskflow/shared.
  cambiarEstado = (id: string, dto: UpdateTaskStatusDto): Promise<TaskDto> =>
    firstValueFrom(this.http.patch<TaskDto>(`${this.base}/${id}/status`, dto));
}

export const authInterceptor: HttpInterceptorFn = (req, next) => {
  const token = inject(AuthService).accessToken();     // señal con el token en memoria
  // Nunca adjuntes el token a peticiones ajenas: enviarías credenciales a un tercero.
  const esNuestraApi = req.url.startsWith(environment.apiUrl) || req.url.startsWith('/api/');
  if (!token || !esNuestraApi) return next(req);
  return next(req.clone({ setHeaders: { Authorization: `Bearer ${token}` } }));
};

// EL ORDEN IMPORTA: la petición los recorre de arriba abajo; el error, al revés.
provideHttpClient(withInterceptors([authInterceptor, errorInterceptor]))

PATCH /api/v1/tasks/7c9a1f3e-2b4d-4f61-9a0c-1d2e3f4a5b6c/status HTTP/1.1
Host: api.taskflow.example
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
X-Request-Id: 3f1c8a92-5e77-4a10-b3d5-9c0e2f8a1b44
Origin: https://app.taskflow.example

{"status":"done","version":7}

export const almacenContexto = new AsyncLocalStorage<{ requestId: string }>();

export function requestIdMiddleware(req: Request, res: Response, next: NextFunction): void {
  // Respetamos el id del cliente o del balanceador si viene; si no, lo creamos.
  const requestId = (req.header('x-request-id') ?? randomUUID()).slice(0, 64);
  res.setHeader('X-Request-Id', requestId);
  // AsyncLocalStorage propaga el contexto a través de await, timers y promesas sin
  // pasarlo por parámetro: es lo mismo que hace RequestContext de MikroORM.
  almacenContexto.run({ requestId }, () => next());
}

// @mikro-orm/nestjs registra su middleware, que envuelve cada petición en un
// RequestContext (EM forkeado). Sin él, todas compartirían el Identity Map. Desastre.
@Module({ imports: [MikroOrmModule.forRoot()] })
export class AppModule implements NestModule {
  configure(c: MiddlewareConsumer): void { c.apply(requestIdMiddleware).forRoutes('*'); }
}

/** Autorización a nivel de recurso: no basta con estar autenticado. */
@Injectable()
export class TaskOwnershipGuard implements CanActivate {
  constructor(private readonly em: EntityManager) {}
  async canActivate(ctx: ExecutionContext): Promise<boolean> {
    const req = ctx.switchToHttp().getRequest();
    const taskId: string | undefined = req.params?.id;
    if (!taskId) return true;
    // Consulta mínima: comprobamos pertenencia, no cargamos el agregado.
    const puede = await this.em.count(Task, {
      id: taskId, project: { team: { members: { id: req.user.id } } } });
    // 403 y no 404: si prefieres no filtrar la existencia, devuelve 404 (ver la FAQ).
    if (!puede) throw new ForbiddenException('No perteneces al equipo de esta tarea');
    return true;
  }
}

// La clase IMPLEMENTA el contrato compartido: si alguien cambia el tipo en
// libs/shared, esta clase deja de compilar. El contrato no puede desincronizarse.
export class UpdateTaskStatusDto implements Contrato {
  @IsIn(TASK_STATUSES as readonly string[], { message: 'estado no permitido' })
  status!: TaskStatus;
  @Type(() => Number) @IsInt({ message: 'la versión debe ser un entero' }) @Min(1)
  version!: number;
}

app.useGlobalPipes(new ValidationPipe({
  whitelist: true,              // elimina propiedades no declaradas en el DTO
  forbidNonWhitelisted: true,   // y falla si llegan: detecta clientes desactualizados
  transform: true,              // instancia la clase (necesario para @Type)
  transformOptions: { enableImplicitConversion: false },
}));

@Controller({ path: 'tasks', version: '1' })
@UseGuards(JwtAuthGuard, TaskOwnershipGuard)      // se ejecutan en este orden
export class TasksController {
  constructor(private readonly cambiarEstado: CambiarEstadoTareaUseCase) {}
  // El controlador solo traduce HTTP → comando y devuelve el DTO. Nada más.
  @Patch(':id/status')
  patchStatus(@Param('id', ParseUUIDPipe) id: string, @Body() dto: UpdateTaskStatusDto,
              @CurrentUser() usuario: AuthUser): Promise<TaskDto> {
    return this.cambiarEstado.ejecutar({ taskId: id, ...dto, actorId: usuario.id });
  }
}

@Entity({ tableName: 'tasks' })
export class Task {
  @PrimaryKey({ type: 'uuid' }) id: string = randomUUID();
  @Property({ length: TASK_TITLE_MAX }) title!: string;
  @Property({ type: 'text', nullable: true }) description: string | null = null;
  // items acepta el array del contrato compartido: una sola definición del enum.
  @Enum({ items: () => TASK_STATUSES as unknown as string[], nativeEnumName: 'task_status' })
  status: TaskStatus = 'todo';
  @ManyToOne(() => Project, { ref: true }) project!: Ref<Project>;
  @ManyToOne(() => User, { ref: true, nullable: true }) assignee: Ref<User> | null = null;
  @ManyToMany(() => Tag) tags = new Collection<Tag>(this);
  @OneToMany(() => Comment, (c) => c.task) comments = new Collection<Comment>(this);
  @Property({ nullable: true }) completedAt: Date | null = null;
  @Property({ onUpdate: () => new Date() }) updatedAt: Date = new Date();
  /** Bloqueo optimista: MikroORM añade WHERE version = ? a cada UPDATE. */
  @Property({ version: true }) version!: number;
  // La invariante vive AQUÍ, no en el controlador ni en el servicio.
  cambiarEstado(nuevo: TaskStatus, actorId: string): void {
    if (!esTransicionValida(this.status, nuevo)) throw new TransicionInvalidaError();  // → 422
    this.status = nuevo;
    this.completedAt = nuevo === 'done' ? new Date() : null;
    this.lastActorId = actorId;
  }
}

@Injectable()
export class CambiarEstadoTareaUseCase {
  constructor(private readonly em: EntityManager, private readonly eventos: TaskEventsPublisher) {}
  async ejecutar(cmd: CambiarEstadoCommand): Promise<TaskDto> {
    // La transacción abarca TODO el caso de uso: si algo falla, no queda nada a medias.
    const dto = await this.em.transactional(async (em) => {
      const task = await em.findOneOrFail(Task, { id: cmd.taskId },
        { populate: ['assignee', 'tags'] });         // lo que el DTO necesita: sin N+1
      // Si la versión no coincide → OptimisticLockError → 409.
      em.lock(task, LockMode.OPTIMISTIC, { lockVersion: cmd.version });
      task.cambiarEstado(cmd.status, cmd.actorId);   // invariantes de dominio
      // flush() AQUÍ: el DTO necesita version y updatedAt ya aplicados.
      await em.flush();
      return TaskMapper.aDto(task);
    });
    // Efectos externos FUERA y DESPUÉS del commit: si difundes antes, anuncias
    // un cambio que quizá se deshaga.
    this.eventos.publicarCambioDeEstado(dto);
    return dto;
  }
}

BEGIN;
select "t0".*, "a1"."id" as "a1__id", "a1"."name" as "a1__name"
  from "tasks" as "t0" left join "users" as "a1" on "t0"."assignee_id" = "a1"."id"
 where "t0"."id" = $1 limit 1;
select "t1".*, "t0"."task_id" as "fk__task_id" from "task_tags" as "t0"
 inner join "tags" as "t1" on "t0"."tag_id" = "t1"."id" where "t0"."task_id" in ($1);
-- flush(): solo las columnas que cambiaron + la condición de versión.
update "tasks" set "status" = $1, "completed_at" = $2, "updated_at" = $3,
       "last_actor_id" = $4, "version" = "version" + 1
 where "id" = $5 and "version" = $6;
-- Si esto afecta a 0 filas → OptimisticLockError → 409 (ver 18.13).
COMMIT;

export const TaskMapper = {
  // Frontera explícita entidad → DTO: añadir una columna NO la publica sola.
  aDto: (task: Task): TaskDto => ({
    id: task.id, title: task.title, description: task.description, status: task.status,
    projectId: task.project.id,                  // Ref: el id sin cargar el proyecto
    assignee: task.assignee ? { id: task.assignee.$.id, name: task.assignee.$.name } : null,
    tags: task.tags.getItems().map((t) => ({ id: t.id, name: t.name, color: t.color })),
    dueDate: task.dueDate?.toISOString() ?? null,
    completedAt: task.completedAt?.toISOString() ?? null,
    updatedAt: task.updatedAt.toISOString(), version: task.version,
  }),
};

const config = new DocumentBuilder()
  .setTitle('TaskFlow API').setVersion('1.0.0').addBearerAuth().build();
const document = SwaggerModule.createDocument(app, config);
SwaggerModule.setup('docs', app, document);   // interfaz en /docs, JSON en /docs-json

// En CI conviene volcarlo a un fichero versionado para detectar cambios de contrato.
if (process.env.DUMP_OPENAPI) await writeFile('openapi.json', JSON.stringify(document, null, 2));

# A · tipos + cliente moderno
npx @hey-api/openapi-ts -i http://localhost:3000/docs-json -o apps/web/src/app/api-generated
# B · servicios Angular basados en HttpClient
npx ng-openapi-gen --input http://localhost:3000/docs-json --output apps/web/src/app/api-generated
# C · solo los TIPOS del esquema, sin cliente
npx openapi-typescript http://localhost:3000/docs-json -o apps/web/src/app/api.types.ts

app.setGlobalPrefix('api');
app.enableVersioning({ type: VersioningType.URI, defaultVersion: '1' });
// Rutas resultantes: /api/v1/tasks, /api/v2/tasks…
// El controlador declara @Controller({ path: 'tasks', version: '1' }).

export const API_ERROR_CODES = [
  'VALIDATION_FAILED',   // 400 · el cuerpo no cumple el DTO
  'UNAUTHENTICATED',     // 401 · falta el token o ha caducado
  'FORBIDDEN',           // 403 · autenticado pero sin permiso
  'NOT_FOUND',           // 404 · no existe (o no debes saber que existe)
  'CONFLICT',            // 409 · choque con el estado actual (unicidad)
  'VERSION_CONFLICT',    // 409 · concurrencia optimista: alguien te adelantó
  'UNPROCESSABLE',       // 422 · sintaxis correcta, regla de negocio incumplida
  'RATE_LIMITED',        // 429 · demasiadas peticiones
  'INTERNAL',            // 500 · fallo nuestro; nunca expongas el detalle
] as const;
export type ApiErrorCode = (typeof API_ERROR_CODES)[number];

export interface FieldError {
  field: string;    // 'title', o 'assignee.id' para anidados
  code: string;     // 'minLength', 'isEmail'... estable, apto para traducir
  message: string;  // texto por defecto, por si no hay traducción
}

export interface ApiErrorBody {
  error: { code: ApiErrorCode; message: string; details?: FieldError[];
           requestId: string; timestamp: string; path: string };
}

@Catch()   // sin argumentos: captura absolutamente todo
export class ApiExceptionFilter implements ExceptionFilter {
  private readonly logger = new Logger(ApiExceptionFilter.name);

  catch(exception: unknown, host: ArgumentsHost): void {
    const ctx = host.switchToHttp();
    const req = ctx.getRequest<Request>(), res = ctx.getResponse<Response>();
    const requestId = almacenContexto.getStore()?.requestId ?? 'sin-contexto';
    const { status, code, message, details } = this.traducir(exception);
    // El log SIEMPRE lleva el detalle completo; la respuesta, no.
    this.logger[status >= 500 ? 'error' : 'warn']({
      requestId, status, code, path: req.originalUrl, method: req.method,
      err: exception instanceof Error ? exception.message : exception,
    }, status >= 500 && exception instanceof Error ? exception.stack : undefined);
    const cuerpo: ApiErrorBody = { error: {
      code,
      message: status >= 500 ? 'Error interno del servidor' : message,   // nunca filtres el interno
      ...(details?.length ? { details } : {}),
      requestId, timestamp: new Date().toISOString(), path: req.originalUrl,
    }};
    res.setHeader('X-Request-Id', requestId);
    res.status(status).json(cuerpo);
  }

  private traducir(e: unknown): { status: number; code: ApiErrorCode; message: string; details?: FieldError[] } {
    // 1 · Errores de MikroORM: se traducen ANTES que HttpException.
    if (e instanceof OptimisticLockError) return { status: 409, code: 'VERSION_CONFLICT', message: 'El recurso ha cambiado desde que lo cargaste' };
    if (e instanceof UniqueConstraintViolationException) return { status: 409, code: 'CONFLICT', message: 'Ya existe un registro con esos datos' };
    if (e instanceof ForeignKeyConstraintViolationException) return { status: 409, code: 'CONFLICT', message: 'La operación viola una referencia existente' };
    if (e instanceof NotFoundError) return { status: 404, code: 'NOT_FOUND', message: 'Recurso no encontrado' };
    // 2 · Errores de dominio propios: 422, la sintaxis era correcta.
    if (e instanceof ErrorDeDominio) return { status: 422, code: 'UNPROCESSABLE', message: e.message };
    // 3 · Excepciones HTTP de Nest, incluida la del ValidationPipe.
    if (e instanceof HttpException) {
      const status = e.getStatus(), resp = e.getResponse();
      const bruto = typeof resp === 'string' ? { message: resp } : (resp as Record<string, unknown>);
      if (status === 400 && Array.isArray(bruto['details']))
        return { status, code: 'VALIDATION_FAILED', message: 'Los datos enviados no son válidos',
                 details: bruto['details'] as FieldError[] };
      const porEstado: Partial<Record<number, ApiErrorCode>> = {
        400: 'VALIDATION_FAILED', 401: 'UNAUTHENTICATED', 403: 'FORBIDDEN',
        404: 'NOT_FOUND', 409: 'CONFLICT', 422: 'UNPROCESSABLE', 429: 'RATE_LIMITED' };
      return { status, code: porEstado[status] ?? 'INTERNAL', message: String(bruto['message'] ?? e.message) };
    }
    return { status: 500, code: 'INTERNAL', message: 'Error interno del servidor' };  // 4 · fallo nuestro
  }
}

/** Error normalizado: todo el frontend trabaja SOLO con esta clase. */
export class ApiError extends Error {
  constructor(
    readonly code: ApiErrorCode | 'NETWORK' | 'TIMEOUT',
    readonly status: number,
    readonly requestId: string,
    readonly details: FieldError[] = [],
    mensaje = 'Se ha producido un error',
  ) { super(mensaje); this.name = 'ApiError'; }

  mensajeParaUsuario(): string {
    const textos: Record<string, string> = {
      NETWORK: 'Sin conexión. Comprueba tu red e inténtalo de nuevo.',
      TIMEOUT: 'El servidor tarda demasiado en responder.',
      UNAUTHENTICATED: 'Tu sesión ha caducado. Vuelve a iniciar sesión.',
      FORBIDDEN: 'No tienes permiso para realizar esta acción.',
      NOT_FOUND: 'El elemento ya no existe.',
      CONFLICT: 'La operación choca con datos existentes.',
      VERSION_CONFLICT: 'Otra persona ha modificado este elemento.',
      VALIDATION_FAILED: 'Revisa los datos del formulario.',
      RATE_LIMITED: 'Demasiadas peticiones. Espera unos segundos.',
      INTERNAL: 'Error inesperado. Ya estamos avisados.',
      UNPROCESSABLE: this.message,   // el servidor ya explica la regla incumplida
    };
    return textos[this.code] ?? this.message;
  }
}

export function desdeRespuesta(e: HttpErrorResponse): ApiError {
  const requestId = e.headers?.get('X-Request-Id') ?? 'desconocido';
  // status 0 = la petición ni siquiera llegó: red caída, DNS, o CORS bloqueado.
  if (e.status === 0) return new ApiError('NETWORK', 0, requestId);
  const cuerpo = e.error as Partial<ApiErrorBody> | null;
  if (cuerpo?.error?.code) {
    const { code, message, details, requestId: rid } = cuerpo.error;
    return new ApiError(code, e.status, rid ?? requestId, details ?? [], message);
  }
  // Error que NO sigue nuestro contrato (un 502 del reverse proxy, una página HTML).
  return new ApiError('INTERNAL', e.status, requestId, [], 'Respuesta inesperada del servidor');
}

@Injectable({ providedIn: 'root' })
export class AuthService {
  // El access token vive SOLO en memoria: al recargar se recupera con el refresh
  // de la cookie HttpOnly, y ningún XSS puede leerlo.
  private readonly _accessToken = signal<string | null>(null);
  private readonly _usuario = signal<UserDto | null>(null);
  readonly accessToken = this._accessToken.asReadonly();
  readonly autenticado = computed(() => this._accessToken() !== null);
  /** Evita la estampida: N peticiones que fallan a la vez comparten UN refresco. */
  private refrescoEnCurso: Observable<AuthTokensDto> | null = null;
  login(dto: LoginDto): Observable<AuthTokensDto> {
    // withCredentials para que el navegador acepte y guarde la cookie de refresco.
    return this.http.post<AuthTokensDto>('/api/v1/auth/login', dto, { withCredentials: true })
      .pipe(tap((r) => { this._accessToken.set(r.accessToken); this._usuario.set(r.user); }));
  }

  refrescarUnaVez(): Observable<AuthTokensDto> {
    this.refrescoEnCurso ??= this.http
      .post<AuthTokensDto>('/api/v1/auth/refresh', {}, { withCredentials: true })
      .pipe(tap((r) => this._accessToken.set(r.accessToken)),
            finalize(() => { this.refrescoEnCurso = null; }),
            shareReplay({ bufferSize: 1, refCount: true }));
    return this.refrescoEnCurso;
  }
}

// ── FRONTEND: guard de navegación. Ergonomía, NO seguridad. ──
export const authGuard: CanActivateFn = (_ruta, estado) => {
  const auth = inject(AuthService);
  const router = inject(Router);
  if (auth.autenticado()) return true;
  // Conservamos el destino para volver tras el login.
  return router.createUrlTree(['/login'], { queryParams: { redirectTo: estado.url } });
};

// ── BACKEND: aquí está la seguridad de verdad. ──
@Injectable()
export class JwtStrategy extends PassportStrategy(Strategy, 'jwt') {
  constructor(config: ConfigService) {
    super({
      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(), ignoreExpiration: false,
      secretOrKey: config.getOrThrow<string>('JWT_SECRET'),
      issuer: 'taskflow-api', audience: 'taskflow-web',
    });
  }
  // Lo que devuelve validate() acaba en req.user: nunca el usuario entero.
  validate(payload: { sub: string; email: string }): AuthUser {
    return { id: payload.sub, email: payload.email };
  }
}

export interface Paginated<T> {
  items: T[];
  total: number;      // filas que cumplen el filtro, no las de la página
  page: number;       // 1-indexado, como lo entiende un humano
  pageSize: number; totalPages: number;
}

export const TASK_SORT_FIELDS = ['createdAt', 'dueDate', 'title', 'status'] as const;
export type TaskSortField = (typeof TASK_SORT_FIELDS)[number];

export interface TaskQuery {
  page?: number; pageSize?: number;
  sort?: TaskSortField; dir?: 'asc' | 'desc';
  status?: TaskStatus; projectId?: string; assigneeId?: string;
  q?: string;         // búsqueda por título
}

async ejecutar(q: ListTasksQueryDto, actorId: string): Promise<Paginated<TaskDto>> {
  // 1 · FilterQuery<Task> hace que el compilador rechace un campo inexistente.
  const where: FilterQuery<Task> = {
    // Filtro de seguridad SIEMPRE presente (o un @Filter global, capítulo 17).
    project: { team: { members: { id: actorId } } },
    ...(q.status ? { status: q.status } : {}),
    ...(q.projectId ? { project: q.projectId } : {}),
    ...(q.q ? { title: { $ilike: `%${q.q}%` } } : {}),
  };
  // 2 · Orden de lista blanca + "id" como desempate: paginación estable.
  const options: FindOptions<Task, 'assignee' | 'tags'> = {
    populate: ['assignee', 'tags'],            // evita el N+1 al mapear
    orderBy: { [q.sort]: q.dir === 'asc' ? QueryOrder.ASC : QueryOrder.DESC, id: QueryOrder.ASC },
    limit: q.pageSize, offset: (q.page - 1) * q.pageSize,
  };
  // 3 · findAndCount emite el SELECT y un COUNT(*) con el MISMO where.
  const [tareas, total] = await this.em.findAndCount(Task, where, options);
  return {
    items: tareas.map(TaskMapper.aDto), total, page: q.page, pageSize: q.pageSize,
    totalPages: Math.max(1, Math.ceil(total / q.pageSize)),
  };
}

@Component({
  selector: 'tf-task-list',
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <label>Buscar <input type="search" [value]="texto()" (input)="alBuscar($event)" /></label>
    <table>
      <thead><tr>@for (c of camposOrdenables; track c) {
        <th><button type="button" (click)="ordenarPor(c)" [attr.aria-sort]="ariaSort(c)">{{ c }}</button></th>
      }</tr></thead>
      <tbody>@for (t of pagina()?.items ?? []; track t.id) {
        <tr><td>{{ t.title }}</td><td>{{ t.status }}</td></tr>
      } @empty {
        <tr><td colspan="4">No hay tareas que cumplan el filtro.</td></tr>
      }</tbody>
    </table>
    @if (recurso.isLoading()) { <p role="status">Cargando…</p> }
    @if (recurso.error()) { <p role="alert">No se pudo cargar la lista.</p> }
    <nav aria-label="Paginación">
      <button [disabled]="filtros().page === 1" (click)="irA(filtros().page - 1)">Anterior</button>
      <span>Página {{ filtros().page }} de {{ pagina()?.totalPages ?? 1 }}</span>
      <button [disabled]="esUltima()" (click)="irA(filtros().page + 1)">Siguiente</button>
    </nav>`,
})
export class TaskListComponent {
  private readonly api = inject(TasksApi);
  protected readonly camposOrdenables = TASK_SORT_FIELDS;
  /** UN solo objeto de filtros: cambiar cualquier campo dispara UNA recarga. */
  protected readonly filtros = signal<Required<Pick<TaskQuery, 'page' | 'sort' | 'dir'>> & TaskQuery>(
    { page: 1, pageSize: 20, sort: 'createdAt', dir: 'desc' });
  protected readonly texto = computed(() => this.filtros().q ?? '');
  // Al cambiar params() cancela la petición anterior y lanza la nueva.
  protected readonly recurso = rxResource({
    params: () => this.filtros(),
    stream: ({ params }) => this.api.listar(params),
  });
  protected readonly pagina = computed(() => this.recurso.value());
  protected readonly esUltima = computed(() => this.filtros().page >= (this.pagina()?.totalPages ?? 1));
  protected irA(page: number): void { this.filtros.update((f) => ({ ...f, page })); }
  protected ordenarPor(sort: TaskSortField): void {
    // Cambiar el orden o el texto SIEMPRE vuelve a la página 1.
    this.filtros.update((f) => ({
      ...f, sort, page: 1, dir: f.sort === sort && f.dir === 'desc' ? 'asc' : 'desc' }));
  }

  protected alBuscar(e: Event): void {
    const q = (e.target as HTMLInputElement).value.trim() || undefined;
    this.filtros.update((f) => ({ ...f, q, page: 1 }));
  }

  protected ariaSort(campo: TaskSortField): 'ascending' | 'descending' | 'none' {
    if (this.filtros().sort !== campo) return 'none';
    return this.filtros().dir === 'asc' ? 'ascending' : 'descending';
  }
}

// ── libs/shared ──
export const TASK_TITLE_MIN = 3;
export const TASK_TITLE_MAX = 200;

// ── apps/web · formulario reactivo ──
titulo: new FormControl('', { nonNullable: true, validators: [
  Validators.required, Validators.minLength(TASK_TITLE_MIN), Validators.maxLength(TASK_TITLE_MAX),
]}),

// ── apps/api · DTO ──
@IsString() @MinLength(TASK_TITLE_MIN) @MaxLength(TASK_TITLE_MAX) title!: string;

// ── apps/api · entidad, que genera la migración ──
@Property({ length: TASK_TITLE_MAX }) title!: string;

// ── migración: varchar(200) not null, más el mínimo como restricción explícita:
//    alter table "tasks" add constraint "tasks_title_min" check (char_length(title) >= 3);

/** form.get() acepta notación de punto, así que 'assignee.id' funciona tal cual. */
export function aplicarErroresServidor(form: FormGroup, error: ApiError): void {
  let alguno = false;
  for (const detalle of error.details) {
    const control = form.get(detalle.field);
    if (!control) continue;
    // 'servidor' es una clave propia: no pisa los errores de los Validators.
    control.setErrors({ ...(control.errors ?? {}), servidor: detalle.message });
    control.markAsTouched();
    alguno = true;
  }
  // Lo que no corresponde a ningún campo se muestra a nivel de formulario.
  if (!alguno) form.setErrors({ ...(form.errors ?? {}), servidor: error.mensajeParaUsuario() });
}

protected async guardar(): Promise<void> {
  if (this.form.invalid) { this.form.markAllAsTouched(); return; }
  this.enviando.set(true);
  try {
    const creada = await this.api.crear(this.form.getRawValue());
    this.store.anadir(creada);
    void this.router.navigate(['/tasks', creada.id]);
  } catch (e) {
    const error = e as ApiError;
    if (error.code === 'VALIDATION_FAILED' || error.code === 'CONFLICT') aplicarErroresServidor(this.form, error);
    else this.errorGeneral.set(error.mensajeParaUsuario());
  } finally {
    this.enviando.set(false);      // el botón se rehabilita PASE LO QUE PASE
  }
}

<label for="titulo">Título</label>
<input id="titulo" formControlName="titulo" [attr.aria-invalid]="esInvalido('titulo')"
       [attr.aria-describedby]="esInvalido('titulo') ? 'titulo-error' : null" />
@if (esInvalido('titulo')) {
  <p id="titulo-error" class="error" role="alert">
    @let errores = form.controls.titulo.errors;
    @if (errores?.['required']) { El título es obligatorio. }
    @else if (errores?.['minlength']) { Mínimo 3 caracteres. }
    @else if (errores?.['maxlength']) { Máximo 200 caracteres. }
    @else if (errores?.['servidor']) { {{ errores['servidor'] }} }
  </p>
}

export type EstadoSubida =
  | { tipo: 'progreso'; porcentaje: number }
  | { tipo: 'hecho'; adjunto: AttachmentDto };

subir(taskId: string, archivo: File): Observable<EstadoSubida> {
  const datos = new FormData();
  datos.append('file', archivo, archivo.name);   // 'file' = nombre del FileInterceptor
  return this.http
    .post<AttachmentDto>(`/api/v1/tasks/${taskId}/attachments`, datos, {
      reportProgress: true,     // sin esto no llegan los eventos de progreso
      observe: 'events',        // recibimos el flujo completo, no solo el cuerpo
    })
    .pipe(
      map((ev): EstadoSubida | null => {
        // total puede ser undefined si no se informa de Content-Length.
        if (ev.type === HttpEventType.UploadProgress)
          return { tipo: 'progreso', porcentaje: ev.total ? Math.round(100 * ev.loaded / ev.total) : 0 };
        if (ev.type === HttpEventType.Response && ev.body) return { tipo: 'hecho', adjunto: ev.body };
        return null;
      }),
      filter((e): e is EstadoSubida => e !== null),
    );
}

// IMPORTANTE: NO pongas Content-Type a mano. El navegador debe generar
// 'multipart/form-data; boundary=----WebKitFormBoundary...' él solo. Si lo fijas
// tú, falta el boundary y el servidor no puede parsear nada.

// ── apps/api · attachments.controller.ts ──
const TIPOS_PERMITIDOS = ['image/png', 'image/jpeg', 'image/webp', 'application/pdf'];

@Post()
@UseInterceptors(FileInterceptor('file', {
  limits: { fileSize: 10 * 1024 * 1024, files: 1 },   // el límite REAL, en el servidor
  // OJO: mimetype lo declara el CLIENTE. Filtro barato de primera línea, no una
  // garantía: la comprobación seria es por número mágico (magic bytes).
  fileFilter: (_req, file, cb) => cb(null, TIPOS_PERMITIDOS.includes(file.mimetype)),
}))
async subirArchivo(
  @Param('taskId', ParseUUIDPipe) taskId: string,
  @UploadedFile() file: Express.Multer.File,
  @CurrentUser() usuario: AuthUser,
): Promise<AttachmentDto> {
  if (!file) throw new BadRequestException('Falta el archivo o el tipo no está permitido');
  return this.subir.ejecutar({ taskId, file, actorId: usuario.id });
}

@Get(':id/download')
@UseGuards(JwtAuthGuard)
async descargar(@Param('id', ParseUUIDPipe) id: string, @CurrentUser() usuario: AuthUser,
                @Res({ passthrough: true }) res: Response): Promise<void> {
  // 1 · La autorización se comprueba AQUÍ, no en el bucket. Un bucket público con
  //     nombres "difíciles de adivinar" no es control de acceso.
  const adjunto = await this.em.findOneOrFail(Attachment, {
    id, task: { project: { team: { members: { id: usuario.id } } } } });
  // 2 · Redirección a una URL firmada de corta duración: el binario sale de S3,
  //     no de nuestro proceso, pero el permiso lo hemos decidido nosotros.
  const url = await this.storage.urlDescargaFirmada(adjunto.storageKey, {
    expiraEnSegundos: 60, nombreDescarga: adjunto.filename });
  res.redirect(302, url);
}

@WebSocketGateway({ namespace: '/rt', cors: { origin: ORIGENES, credentials: true } })
export class TasksGateway implements OnGatewayConnection {
  @WebSocketServer() private server!: Server;
  async handleConnection(socket: Socket): Promise<void> {
    // El handshake TAMBIÉN se autentica: un WebSocket no hereda los guards HTTP.
    const usuario = await this.auth.verificarToken(socket.handshake.auth?.['token']);
    if (!usuario) { socket.disconnect(true); return; }
    // Salas por proyecto: cada cliente recibe solo lo que puede ver. Difundir a
    // todos y filtrar en el cliente sería una fuga de datos.
    for (const id of await this.proyectos.idsVisiblesPara(usuario.id)) await socket.join(`project:${id}`);
  }

  emitirCambio(dto: TaskDto): void {
    // El evento lleva el DTO COMPLETO, no solo el id: así el cliente no hace un GET
    // por cada notificación (que sería un N+1 provocado por el frontend).
    this.server.to(`project:${dto.projectId}`).emit('task.updated', dto);
  }
}

// ── apps/web · realtime.service.ts ──
readonly estado = signal<'conectado' | 'reconectando' | 'desincronizado'>('reconectando');

conectar(): void {
  this.socket = io('/rt', { auth: { token: this.auth.accessToken() } });
  this.socket.on('connect', () => {
    // Al (re)conectar SIEMPRE resincronizamos: mientras estábamos fuera pudimos
    // perder eventos, y no hay forma de saber cuáles.
    this.store.recargarTodo().then(() => this.estado.set('conectado'));
  });
  this.socket.on('disconnect', () => this.estado.set('reconectando'));
  // Si tras varios intentos no volvemos, avisamos en vez de enseñar datos viejos
  // como si fueran actuales.
  this.socket.io.on('reconnect_failed', () => this.estado.set('desincronizado'));
  this.socket.on('task.updated', (dto: TaskDto) => this.store.aplicarRemoto(dto));
}

// ── En el store: la regla de oro es comparar VERSIONES, porque los mensajes de
//    WebSocket pueden llegar desordenados o duplicados. ──
aplicarRemoto(remoto: TaskDto): void {
  // Si tenemos una petición en vuelo para esa tarea, nuestro cambio optimista es
  // más reciente: lo ignoramos y esperamos a nuestra propia respuesta.
  if (this._enVuelo().has(remoto.id)) return;
  this._tasks.update((lista) => {
    const i = lista.findIndex((t) => t.id === remoto.id);
    if (i === -1) return lista;                             // no está en la vista actual
    if (lista[i].version >= remoto.version) return lista;   // evento antiguo: descartar
    const copia = [...lista]; copia[i] = remoto; return copia;
  });
}

private async resolverConflicto(error: ApiError, id: string, intento: TaskStatus): Promise<void> {
  if (error.code !== 'VERSION_CONFLICT') {
    this.toasts.error(error.mensajeParaUsuario(), { requestId: error.requestId });
    return;
  }
  const servidor = await this.api.obtener(id);   // la verdad actual
  // A · RECARGAR: siempre correcta, a veces molesta; descarta el intento del
  //     usuario. Vale para datos de solo lectura o cambios triviales.
  this.parchear(id, () => servidor);
  // B · FUSIONAR cuando no hay solape real (Ana tocó el título y Bruno el estado).
  //     Solo es seguro con campos verificablemente independientes.
  if (servidor.status !== intento) {
    await this.api.cambiarEstado(id, { status: intento, version: servidor.version })
      .then((ok) => this.parchear(id, () => ok))
      .catch(() => this.toasts.avisar('No se pudo aplicar tu cambio; revisa la tarea.'));
    return;
  }
  // C · AVISAR y que decida el usuario. Obligatoria si el conflicto afecta a texto
  //     tecleado: nunca tires a la basura lo que alguien ha escrito.
  this.toasts.conflicto({
    mensaje: `«${servidor.title}» fue modificada por otra persona.`,
    acciones: [
      { texto: 'Ver la versión actual', accion: () => this.parchear(id, () => servidor) },
      { texto: 'Aplicar mi cambio igualmente',
        accion: () => this.api.cambiarEstado(id, { status: intento, version: servidor.version }) },
    ],
  });
}

{
  "/api": { "target": "http://localhost:3000", "secure": false, "changeOrigin": true },
  "/rt":  { "target": "http://localhost:3000", "ws": true, "secure": false }
}

// En angular.json, dentro de la configuración de serve:
//   "options": { "proxyConfig": "apps/web/proxy.conf.json" }

export const environment = {
  production: true,
  apiUrl: '/api',                  // mismo origen: ruta relativa, sin dominio
  wsUrl: '/rt',
  sentryDsn: 'https://abc123@o0.ingest.sentry.io/0',   // público por diseño
  featureFlags: { tiempoReal: true },
};

// TODO ESTO ACABA EN EL BUNDLE QUE DESCARGA CUALQUIERA: el environment del frontend
// no es un secreto, es configuración pública. Cualquiera abre main-XYZ.js y lo lee.
//   SÍ: URLs, flags, claves PÚBLICAS (Stripe pk_, Maps con restricción de dominio)
//   NO: claves privadas, secretos de JWT, cadenas de conexión, tokens de admin
// Si algo debe ser secreto, la operación que lo usa vive en el backend.

{
  "name": "taskflow",
  "private": true,
  "workspaces": ["apps/*", "libs/*"],
  "scripts": {
    "dev": "concurrently -n db,api,web -c blue,magenta,green \"npm:dev:db\" \"npm:dev:api\" \"npm:dev:web\"",
    "dev:db": "docker compose up postgres minio",
    "dev:api": "npm run start:dev --workspace=@taskflow/api",
    "dev:web": "npm run start --workspace=@taskflow/web",
    "build": "npm run build --workspaces --if-present",
    "test": "npm run test --workspaces --if-present",
    "db:migrate": "npm run mikro-orm --workspace=@taskflow/api -- migration:up",
    "openapi": "npm run dump:openapi --workspace=@taskflow/api && npm run gen:client --workspace=@taskflow/web"
  }
}