15. Entidades, relaciones, herencia y embeddables

import { Collection, Entity, Enum, ManyToMany, ManyToOne, OneToMany, PrimaryKey, Property, Ref } from '@mikro-orm/core';

@Entity()
export class Project {
  @PrimaryKey() id!: number;
  @Property({ length: 120 }) name!: string;
  @Property({ default: false }) archived = false;

  // Lado PROPIETARIO: aquí nace la columna team_id de la tabla "project".
  @ManyToOne(() => Team, { ref: true }) team!: Ref<Team>;

  // Lado INVERSO: no crea ninguna columna. Es un espejo navegable.
  @OneToMany(() => Task, (task) => task.project)
  tasks = new Collection<Task>(this);
}

export type TaskStatus = 'todo' | 'doing' | 'done' | 'blocked';

@Entity()
export class Task {
  @PrimaryKey() id!: number;
  @Property({ length: 200 }) title!: string;
  @Property({ nullable: true }) dueDate?: Date;
  @Enum({ items: () => ['todo', 'doing', 'done', 'blocked'], default: 'todo' })
  status: TaskStatus = 'todo';

  @ManyToOne(() => Project, { ref: true, deleteRule: 'cascade' })                 // obligatoria
  project!: Ref<Project>;
  @ManyToOne(() => User, { ref: true, nullable: true, deleteRule: 'set null' })   // opcional
  assignee?: Ref<User>;
  @ManyToMany(() => Tag, (tag) => tag.tasks, { owner: true })                     // M:N puro
  tags = new Collection<Tag>(this);
  @OneToMany(() => Comment, (c) => c.task, { orphanRemoval: true })               // composición
  comments = new Collection<Comment>(this);
  @OneToMany(() => Attachment, (a) => a.task, { orphanRemoval: true })
  attachments = new Collection<Attachment>(this);
}

create table "project" (
  "id"       serial primary key,
  "name"     varchar(120) not null,
  "archived" boolean not null default false,
  "team_id"  int not null );             -- ← de @ManyToOne(() => Team)
alter table "project" add constraint "project_team_id_foreign"
  foreign key ("team_id") references "team" ("id") on update cascade;
create index "project_team_id_index" on "project" ("team_id");

create table "task" (
  "id"          serial primary key,
  "title"       varchar(200) not null,
  "status"      text check ("status" in ('todo','doing','done','blocked')) not null default 'todo',
  "due_date"    timestamptz null,
  "project_id"  int not null,            -- NOT NULL: relación obligatoria
  "assignee_id" int null );              -- NULL:     relación opcional
alter table "task" add constraint "task_project_id_foreign"
  foreign key ("project_id") references "project" ("id")
  on update cascade on delete cascade;   -- ← deleteRule: 'cascade'
alter table "task" add constraint "task_assignee_id_foreign"
  foreign key ("assignee_id") references "user" ("id")
  on update cascade on delete set null;  -- ← deleteRule: 'set null'

-- Y la tabla intermedia del M:N, que el ORM crea sin que exista clase alguna:
create table "task_tags" ( "task_id" int not null, "tag_id" int not null,
  constraint "task_tags_pkey" primary key ("task_id", "tag_id") );

@ManyToOne(() => Project, {
  ref: true,                 // la propiedad será Ref<Project>, no Project
  nullable: false,           // columna NOT NULL (valor por defecto)
  deleteRule: 'cascade',     // ON DELETE CASCADE en la FK  (v5: onDelete)
  updateRule: 'cascade',     // ON UPDATE CASCADE en la FK  (v5: onUpdateIntegrity)
  fieldName: 'project_id',   // nombre físico de la columna
  index: true,               // crea índice sobre la FK
  eager: false,              // NO cargar siempre (valor por defecto)
  mapToPk: false,            // si true, la propiedad es number en lugar de entidad
})
project!: Ref<Project>;

-- Modelo: Task.project es eager, Project.team es eager, Team.owner es eager.
-- El desarrollador solo quería los títulos:  em.find(Task, { status: 'todo' })
select "t0".* from "task" "t0" where "t0"."status" = 'todo';
select "p0".* from "project" "p0" where "p0"."id" in (7, 8, 11, 12, 15);
select "t0".* from "team"    "t0" where "t0"."id" in (1, 2, 3);
select "u0".* from "user"    "u0" where "u0"."id" in (4, 9, 21);
-- 4 consultas y tres tablas enteras en memoria para pintar una lista de títulos,
-- y ocurre en TODOS los endpoints que toquen Task, para siempre.

@OneToMany(() => Task, (task) => task.project, {
  orderBy: { position: 'asc' },   // orden por defecto al inicializar
  orphanRemoval: false,           // ver 15.10
})
tasks = new Collection<Task>(this);   // ← inicialización OBLIGATORIA

@Entity()
export class Task {
  @ManyToMany(() => Tag, (tag) => tag.tasks, {
    owner: true,                    // ESTE lado define la tabla intermedia
    pivotTable: 'task_tags',        // nombre; por defecto "task_tags"
    joinColumn: 'task_id',          // FK hacia el propietario
    inverseJoinColumn: 'tag_id',    // FK hacia el otro lado
    fixedOrder: false,              // ver más abajo
  })
  tags = new Collection<Tag>(this);
}

@Entity()
export class Tag {
  @PrimaryKey() id!: number;
  @Property({ unique: true, length: 40 }) name!: string;
  // Sin owner y CON mappedBy: es el espejo. No define nada.
  @ManyToMany(() => Task, (task) => task.tags)
  tasks = new Collection<Task>(this);
}

create table "task_tags" ( "task_id" int not null, "tag_id" int not null,
  constraint "task_tags_pkey" primary key ("task_id", "tag_id") );
alter table "task_tags" add constraint "task_tags_task_id_foreign"
  foreign key ("task_id") references "task" ("id") on update cascade on delete cascade;
-- (la restricción equivalente para "tag_id" se genera igual)

-- task.tags.add(tagUrgente); task.tags.remove(tagBug); await em.flush();
delete from "task_tags" where "task_id" = 1 and "tag_id" = 3;
insert into "task_tags" ("task_id", "tag_id") values (1, 7);

-- populate: ['tags'] con estrategia SELECT_IN:
select "t1".*, "t0"."task_id" as "fk__task_id"
  from "task_tags" as "t0"
  inner join "tag" as "t1" on "t0"."tag_id" = "t1"."id"
 where "t0"."task_id" in (1, 2, 3);

export type TeamRole = 'owner' | 'admin' | 'member' | 'guest';
@Entity()
export class TeamMembership {
  // Dos @ManyToOne marcados como primary forman una CLAVE PRIMARIA COMPUESTA:
  // la base de datos impide por sí sola dos membresías del mismo par.
  @ManyToOne(() => User, { primary: true, ref: true, deleteRule: 'cascade' })
  user!: Ref<User>;
  @ManyToOne(() => Team, { primary: true, ref: true, deleteRule: 'cascade' })
  team!: Ref<Team>;

  @Enum({ items: () => ['owner', 'admin', 'member', 'guest'], default: 'member' })
  role: TeamRole = 'member';       // ← el atributo que justifica toda la clase
  @Property() joinedAt: Date = new Date();
}

// Los lados inversos sustituyen a las colecciones M:N:
//   En User:  @OneToMany(() => TeamMembership, m => m.user)  memberships
//   En Team:  @OneToMany(() => TeamMembership, m => m.team)  members
// La relación M:N deja de existir: ahora son dos 1:N unidas por una entidad en
// medio. Es lo que hacía la base de datos, pero ahora la tabla del medio es TUYA.

create table "team_membership" (
  "user_id"   int not null,
  "team_id"   int not null,
  "role"      text check ("role" in ('owner','admin','member','guest')) not null default 'member',
  "joined_at" timestamptz not null,
  constraint "team_membership_pkey" primary key ("user_id", "team_id") );
-- Ahora esto es trivial, e imposible con un M:N automático:
select "u".* from "team_membership" "m"
  join "user" "u" on "u"."id" = "m"."user_id"
 where "m"."team_id" = 3 and "m"."role" in ('owner', 'admin');

@Entity()
export class User {
  // PROPIETARIO: la columna profile_id vivirá en la tabla "user".
  @OneToOne(() => UserProfile, (profile) => profile.user, {
    owner: true, ref: true,
    nullable: true,          // relación opcional: puede no tener perfil
    orphanRemoval: true,     // si se desvincula el perfil, se borra
  })
  profile?: Ref<UserProfile>;
}

@Entity()
export class UserProfile {
  @PrimaryKey() id!: number;
  @Property({ type: 'text', nullable: true }) bio?: string;
  @Property({ length: 40, default: 'Europe/Madrid' }) timezone = 'Europe/Madrid';
  // INVERSO: sin owner y con mappedBy. No genera columna.
  @OneToOne(() => User, (user) => user.profile)
  user!: User;
}

create table "user_profile" ( "id" serial primary key, "bio" text null,
  "timezone" varchar(40) not null default 'Europe/Madrid' );

alter table "user" add column "profile_id" int null;
alter table "user" add constraint "user_profile_id_unique" unique ("profile_id");
--                                                        ^^^^^^ convierte un N:1
--                          en un 1:1, porque la FK no se puede repetir.
alter table "user" add constraint "user_profile_id_foreign"
  foreign key ("profile_id") references "user_profile" ("id")
  on update cascade on delete set null;

const project = await em.findOne(Project, 7);
// select "p0".* from "project" "p0" where "p0"."id" = 7 limit 1;  ← no toca "task"
project.tasks.isInitialized();   // false
project.tasks.count();           // ValidationError: Collection<Task> of entity
                                 // Project[7] not initialized
for (const t of project.tasks) { /* … */ }   // itera sobre NADA

// 1) populate en la consulta original: lo más habitual y lo más eficiente
const p1 = await em.findOne(Project, 7, { populate: ['tasks'] });
// 2) init() con opciones propias
await p1.tasks.init({ where: { status: { $ne: 'done' } }, orderBy: { dueDate: 'asc' },
                      populate: ['assignee'] });
// 3) loadItems(): init() + devuelve el array tipado
const tareas = await p1.tasks.loadItems({ populate: ['tags'] });
// 4) em.populate() sobre entidades ya cargadas: una sola consulta adicional
const proyectos = await em.find(Project, {});
await em.populate(proyectos, ['tasks']);

await task.comments.init(); task.comments.count();
// select "c0".* from "comment" "c0" where "c0"."task_id" = 1;
// Transfiere todas las filas y construye todos los objetos: O(n) en red, memoria
// y CPU. Con 5.000 comentarios es un desastre.
await task.comments.loadCount();
// select count(*) as "count" from "comment" "c0" where "c0"."task_id" = 1;
// Una fila, un entero. El índice sobre task_id lo resuelve sin tocar la tabla.

const pagina = await task.comments.matching({
  where: { deletedAt: null }, orderBy: { createdAt: 'desc' },
  limit: 20, offset: 40, populate: ['author'],
  store: false,        // true = guarda el resultado dentro de la colección
});
// select "c0".* from "comment" "c0" where "c0"."task_id" = 1
//  and "c0"."deleted_at" is null order by "c0"."created_at" desc limit 20 offset 40;
task.comments.isInitialized();   // false: con store: false no la inicializa

// (a) mapToPk: la propiedad ES el identificador. Ni proxy ni Ref.
@ManyToOne(() => Project, { mapToPk: true })
project!: number;
task.project = 8;   // útil en importaciones masivas o entidades de solo escritura;
                    // el precio es perder la navegación (no hay .load()).

// (b) rel(): tipado cómodo cuando NO usas ref: true; ref(): construye un Ref
import { rel, ref, wrap, type Rel } from '@mikro-orm/core';
@ManyToOne(() => Project) project!: Rel<Project>;   // evita tipos circulares en TS
user.profile = ref(em.create(UserProfile, { timezone: 'Europe/Madrid' }));
// (c) wrap(): utilidad genérica que funciona con cualquier entidad
await wrap(task.assignee).init();
const plano = wrap(task).toObject();

const project = em.create(Project, { name: 'Rediseño', team: teamRef });
const t1 = em.create(Task, { title: 'Wireframes', project: ref(project) });
const t2 = em.create(Task, { title: 'Prototipo',  project: ref(project) });
await em.persistAndFlush(project);   // PERSIST está activo por defecto
// insert into "project" ("name","team_id") values ('Rediseño', 3) returning "id";
// insert into "task" ("title","project_id") values ('Wireframes', 12), ('Prototipo', 12);
// Nunca hizo falta persistir t1 ni t2 explícitamente.

-- em.find(Project, { archived: false }, { populate: ['tasks', 'tasks.assignee'] })
-- (A) LoadStrategy.SELECT_IN — valor por defecto en la v6
select "p0".* from "project" "p0" where "p0"."archived" = false;      -- 3 proyectos
select "t0".* from "task" "t0" where "t0"."project_id" in (7, 8, 11); -- 40 tareas
select "u0".* from "user" "u0" where "u0"."id" in (4, 9, 21);         -- 3 usuarios
-- 3 consultas; cada fila aparece UNA vez y el ORM las cose con el Identity Map.

-- (B) LoadStrategy.JOINED — añadiendo strategy: 'joined'
select "p0"."id", "p0"."name", "t1"."id" as "t1__id", "t1"."title" as "t1__title",
       "u2"."id" as "u2__id", "u2"."email" as "u2__email"
  from "project" "p0"
  left join "task" "t1" on "t1"."project_id" = "p0"."id"
  left join "user" "u2" on "u2"."id" = "t1"."assignee_id" where "p0"."archived" = false;
-- 1 sola consulta… pero los datos del proyecto se REPITEN una vez por tarea:
-- 40 filas arrastrando el nombre del proyecto. Producto cartesiano parcial.

import { LoadStrategy } from '@mikro-orm/core';
// (a) Global, en la configuración del ORM
export default defineConfig({ loadStrategy: LoadStrategy.SELECT_IN, /* … */ });
// (b) Por relación, en el decorador
@ManyToOne(() => Project, { ref: true, strategy: LoadStrategy.JOINED })
project!: Ref<Project>;
// (c) Por consulta: la más útil, porque es la más informada
await em.find(Project, { archived: false },
              { populate: ['tasks'], strategy: LoadStrategy.JOINED });

// Rutas anidadas separadas por punto; el tipado las valida (escribir
// 'project.ownr' es un error de compilación).
await em.find(Task, {}, { populate: ['project.team', 'assignee', 'tags'] });
// Todo lo que cuelgue de la entidad (v6; en v5 era populate: true)
await em.find(Task, {}, { populate: ['*'] });
// Carga parcial: solo estas columnas. Menos ancho de banda y menos memoria.
await em.find(Task, {}, { fields: ['title', 'status', 'project.name'] });

// populateWhere: condiciones aplicadas a las relaciones cargadas
await em.find(Project, { archived: false }, {
  populate: ['tasks'], populateWhere: { tasks: { status: { $ne: 'done' } } },
});
// select "t0".* from "task" "t0"
//  where "t0"."project_id" in (7, 8) and "t0"."status" != 'done';
// PopulateHint.INFER: aplica a las relaciones la MISMA condición del where principal
import { PopulateHint } from '@mikro-orm/core';
await em.find(Project, { tasks: { status: 'blocked' } }, {
  populate: ['tasks'], populateWhere: PopulateHint.INFER,   // solo las bloqueadas
});
// Por defecto es PopulateHint.ALL: filtra los PROYECTOS por tener alguna tarea
// bloqueada, pero luego carga TODAS las tareas de esos proyectos.

// populateOrderBy: ordenar las colecciones cargadas
await em.find(Project, {}, { populate: ['tasks'],
                             populateOrderBy: { tasks: { dueDate: 'asc' } } });

@Entity({
  discriminatorColumn: 'type',
  discriminatorMap: { bug: 'Bug', feature: 'Feature', chore: 'Chore' },
  abstract: true,          // no se instancia directamente
})
export abstract class BaseTask {
  @PrimaryKey() id!: number;
  @Property({ length: 200 }) title!: string;
  // La propiedad discriminadora se declara para poder leerla; la rellena el ORM.
  @Enum({ items: () => ['bug', 'feature', 'chore'] })
  type!: 'bug' | 'feature' | 'chore';
}

@Entity({ discriminatorValue: 'bug' })
export class Bug extends BaseTask {
  @Enum({ items: () => ['low', 'medium', 'high', 'critical'] })
  severity: 'low' | 'medium' | 'high' | 'critical' = 'medium';
  @Property({ type: 'text', nullable: true }) stepsToReproduce?: string;
}
@Entity({ discriminatorValue: 'feature' })
export class Feature extends BaseTask {
  @Property({ nullable: true }) storyPoints?: number;
}

@Entity({ discriminatorValue: 'chore' }) export class Chore extends BaseTask {}

-- em.find(Bug, { severity: 'critical' })
select "b0".* from "base_task" "b0"
 where "b0"."type" = 'bug' and "b0"."severity" = 'critical';
--     ^^^^^^^^^^^^^^^^^^ el ORM añade el discriminador automáticamente
-- em.find(BaseTask, {})  → devuelve Bug, Feature y Chore mezclados
select "b0".* from "base_task" "b0";
-- El ORM lee la columna "type" y construye la clase correcta de cada fila:
-- polimorfismo real, con una consulta, sin joins y sin UNION.

// abstract: true SIN discriminatorColumn → no genera tabla propia.
@Entity({ abstract: true })
export abstract class BaseEntity {
  [OptionalProps]?: 'createdAt' | 'updatedAt';
  @PrimaryKey() id!: number;
  @Property() createdAt: Date = new Date();
  @Property({ onUpdate: () => new Date() }) updatedAt: Date = new Date();
}

@Entity()
export class Tag extends BaseEntity {
  @Property({ unique: true, length: 40 }) name!: string;
}
// create table "tag" ("id" serial primary key, "created_at" timestamptz not null,
//   "updated_at" timestamptz not null, "name" varchar(40) not null);
// Esas tres columnas se repiten en cada entidad que herede.

@Embeddable()
export class Address {
  @Property({ length: 120 }) street!: string;
  @Property({ length: 60 })  city!: string;
  @Property({ length: 10 })  postalCode!: string;
  @Property({ length: 2, default: 'ES' }) country = 'ES';
  constructor(street: string, city: string, postalCode: string, country = 'ES') {
    this.street = street; this.city = city;
    this.postalCode = postalCode; this.country = country;
  }
  // Comportamiento propio: esto lo convierte en un value object de verdad.
  format(): string { return `${this.street}, ${this.postalCode} ${this.city}`; }
}

@Entity()
export class Team {
  @Embedded(() => Address, { prefix: 'billing_' })             // (a) en línea con prefijo
  billingAddress!: Address;
  @Embedded(() => Address, { prefix: false, nullable: true })  // (b) sin prefijo
  address?: Address;
  @Embedded(() => Address, { object: true, nullable: true })   // (c) columna JSON
  shippingAddress?: Address;
  @Embedded(() => Address, { array: true })                    // (d) array: siempre JSON
  previousAddresses: Address[] = [];
}

create table "team" (
  "id"                  serial primary key,
  "billing_street"      varchar(120) not null,   -- ┐
  "billing_city"        varchar(60)  not null,   -- │ (a) prefix: 'billing_'
  "billing_postal_code" varchar(10)  not null,   -- ┘  (+ billing_country)
  "street"              varchar(120) null,       -- ┐ (b) prefix: false
  "city"                varchar(60)  null,       -- ┘  (+ postal_code, country)
  "shipping_address"    jsonb null,              --   (c) object: true
  "previous_addresses"  jsonb not null default '[]' );  -- (d) array: true

-- En modo EN LÍNEA se indexa y se consulta como cualquier columna:
create index "team_billing_city_index" on "team" ("billing_city");
select * from "team" where "billing_city" = 'Bilbao';
-- En modo OBJETO hacen falta operadores JSON y es más difícil de indexar:
select * from "team" where "shipping_address"->>'city' = 'Bilbao';

import { Type, Platform, ValidationError, EntityProperty } from '@mikro-orm/core';
export class Email {
  private constructor(public readonly value: string) {}
  static create(raw: string): Email {
    const limpio = raw.trim().toLowerCase();
    if (!/^[^@\s]+@[^@\s]+\.[a-z]{2,}$/i.test(limpio)) {
      throw new ValidationError(`Email inválido: ${raw}`);
    }
    return new Email(limpio);
  }
}

// Type<TipoEnJS, TipoEnBD>
export class EmailType extends Type<Email | undefined, string | undefined> {
  // Objeto de TypeScript → valor que se manda a la base de datos
  convertToDatabaseValue(value: Email | string | undefined): string | undefined {
    if (value == null) return undefined;
    return value instanceof Email ? value.value : Email.create(value).value;
  }
  // Valor leído de la base de datos → objeto de TypeScript
  convertToJSValue(value: string | undefined): Email | undefined {
    return value == null ? undefined : Email.create(value);
  }
  getColumnType(prop: EntityProperty, platform: Platform): string {
    return platform.getVarcharTypeDeclarationSQL({ length: 254 });
  }
  compareAsType(): string { return 'string'; }   // cómo detectar cambios
}

// Uso: @Property({ type: EmailType, unique: true })  email!: Email;
// em.create(User, { email: Email.create('  ANA@Empresa.COM ') })
//   → insert into "user" ("email") values ('ana@empresa.com');

@Entity()
export class Category {
  @PrimaryKey() id!: number;
  @Property({ length: 80 }) name!: string;

  // Auto-referencia: la raíz tiene parent = null
  @ManyToOne(() => Category, { nullable: true, ref: true, deleteRule: 'cascade' })
  parent?: Ref<Category>;

  @OneToMany(() => Category, (c) => c.parent)
  children = new Collection<Category>(this);
}

-- Entidad: @Property({ length: 255, index: true }) path!: string;   ('/1/2/')
-- Todos los descendientes de "API" (id 2), a cualquier profundidad:
select * from "category" where "path" like '/1/2/%' order by "path";
-- Una sola consulta que usa el índice de prefijo: imbatible en lectura.
-- Los ancestros se extraen del propio path en memoria, sin consultar: [1, 2]
-- El precio: mover "API" bajo "Datos" obliga a reescribir el subárbol entero
update "category" set "path" = replace("path", '/1/2/', '/1/3/2/')
 where "path" like '/1/2/%';

@ManyToOne(() => TeamMembership, { ref: true })
membership!: Ref<TeamMembership>;

// Buscar por clave compuesta: objeto con todas las partes, o tupla
const m  = await em.findOne(TeamMembership, { user: 4, team: 3 });
const m2 = await em.findOne(TeamMembership, [4, 3]);

/*  create table "membership_note" ( "id" serial primary key,
      "membership_user_id" int not null,   -- ┐ una sola FK lógica
      "membership_team_id" int not null,   -- ┘ repartida en dos columnas
      "note"               text not null );
    alter table "membership_note" add constraint "membership_note_foreign"
      foreign key ("membership_user_id", "membership_team_id")
      references "team_membership" ("user_id", "team_id") on update cascade;  */

@Entity()
export class User {
  @Property({ hidden: true })                       // (1) nunca aparece en la salida
  passwordHash!: string;
  @Property({ serializer: (v: Date) => v.toISOString().slice(0, 10) })  // (2)
  birthDate!: Date;
  @Property({ serializedName: 'displayName' })      // (3) cambia la clave del JSON
  name!: string;
  @Property({ persist: false })                     // (4) getter calculado
  get initials(): string { return this.name.split(' ').map((p) => p[0]).join(''); }
}

const plano = wrap(user).toObject();   // sigue las relaciones YA cargadas y corta ciclos
const json  = wrap(user).toJSON();     // lo que usa JSON.stringify; delega en toObject()
const dto = serialize(user, {          // control fino, la opción más flexible
  populate: ['memberships.team'],      // qué relaciones incluir
  exclude: ['memberships.user'],       // qué cortar (evita el ciclo)
  forceObject: true,                   // relaciones no cargadas como { id }, no como 1
});

async invitar(teamId: number, userId: number, role: TeamRole) {
  // La PK compuesta impide duplicados en la base de datos, pero comprobarlo
  // antes permite dar un mensaje de error decente.
  const existe = await this.em.findOne(TeamMembership, { team: teamId, user: userId });
  if (existe) throw new ConflictException('El usuario ya pertenece al equipo');
  const membership = this.em.create(TeamMembership, {
    team: this.em.getReference(Team, teamId),
    user: this.em.getReference(User, userId),
    role, joinedAt: new Date(),
  });
  await this.em.flush();
  return membership;
}
async cambiarRol(teamId: number, userId: number, role: TeamRole) {
  const m = await this.em.findOneOrFail(TeamMembership, { team: teamId, user: userId });

  // Invariante de negocio: siempre debe quedar al menos un propietario.
  if (m.role === 'owner' && role !== 'owner') {
    const owners = await this.em.count(TeamMembership, { team: teamId, role: 'owner' });
    if (owners <= 1) throw new BadRequestException('El equipo necesita un propietario');
  }
  m.role = role;
  await this.em.flush();   // update "team_membership" set "role" = 'admin' where …
}

// Consultar la propia relación: imposible con un M:N automático.
async administradores(teamId: number): Promise<User[]> {
  const ms = await this.em.find(TeamMembership,
    { team: teamId, role: { $in: ['owner', 'admin'] } }, { populate: ['user'] });
  return ms.map((m) => m.user.$);
}

async sincronizarEtiquetas(taskId: number, nombres: string[]) {
  const task = await this.em.findOneOrFail(Task, taskId, { populate: ['tags'] });
  // upsertMany crea las que falten y devuelve todas: una sola ida y vuelta.
  const tags = await this.em.upsertMany(Tag, nombres.map((name) => ({ name })),
    { onConflictFields: ['name'] });
  task.tags.set(tags);   // calcula la diferencia: inserta las nuevas, borra las que sobran
  await this.em.flush();
}

// SQL para pasar de {bug, urgente} a {bug, backend}:
//   insert into "tag" ("name") values ('backend')
//     on conflict ("name") do update set "name" = excluded."name" returning "id";
//   delete from "task_tags" where "task_id" = 1 and "tag_id" = 9;  -- urgente
//   insert into "task_tags" ("task_id","tag_id") values (1, 12);   -- backend

@Entity()
export class Attachment {
  @PrimaryKey() id!: number;
  @Property({ length: 255 }) filename!: string;
  @Property({ length: 512 }) storageKey!: string;   // clave en S3 o en el disco

  // NOT NULL + cascade: un adjunto sin tarea no tiene sentido.
  @ManyToOne(() => Task, { ref: true, deleteRule: 'cascade' })
  task!: Ref<Task>;
  // El hook borra el fichero físico y solo se ejecuta si borra el ORM:
  // por eso aquí la cascada del ORM SÍ importa.
  @BeforeDelete()
  async borrarFichero() { await storage.delete(this.storageKey); }
}

// En Task: @OneToMany(() => Attachment, a => a.task, { orphanRemoval: true })
async eliminar(taskId: number, attachmentId: number) {
  const task = await this.em.findOneOrFail(Task, taskId, { populate: ['attachments'] });
  const adjunto = task.attachments.getItems().find((a) => a.id === attachmentId);
  if (!adjunto) throw new NotFoundException();
  task.attachments.remove(adjunto);   // orphanRemoval hace el resto
  await this.em.flush();
  // 1) @BeforeDelete borra el fichero de S3;  2) delete from "attachment" where "id" = 5;
}

async guardarPerfil(userId: number, dto: UpdateProfileDto) {
  const user = await this.em.findOneOrFail(User, userId, { populate: ['profile'] });
  if (!user.profile) {
    // Crear y enlazar: cascade PERSIST lo guarda junto con el usuario.
    user.profile = ref(this.em.create(UserProfile, { ...dto, user }));
  } else {
    this.em.assign(user.profile.$, dto);
  }
  await this.em.flush();
  return user.profile.$;
}

// Primera llamada:  insert into "user_profile" (…) values (…) returning "id";
//                   update "user" set "profile_id" = 31 where "id" = 4;
// Siguientes:       update "user_profile" set "bio" = '…' where "id" = 31;