@astram/identity 0.16.0 → 0.17.1

package/migrations/1710000000105-OwnDepartmentsAndBranches.cjs

@@ -0,0 +1,327 @@
+/**
+ * Framework identity migration — each company OWNS its departments and branches (G-012, spec §4).
+ *
+ * WHY: `departments` / `branches` were global catalogs (one "Sales" row shared by every company
+ * that used the name, `UNIQUE (d_name)`), so no company could safely rename or delete its own.
+ * After this migration every row has one owner company (`d_company_uuid` / `b_company_uuid`),
+ * names are unique per company, and no row is shared between companies.
+ *
+ * Steps, per table (idempotent; a half-applied state is completed, a re-run changes nothing):
+ *   1. ADD the nullable owner column, its index `idx_<table>_company` and
+ *      `FK_<table>_company` -> `companies (c_uuid)` ON DELETE CASCADE, each when absent.
+ *   2. OWNER. A row with no owner that a junction row links gets the linked company with the
+ *      smallest `c_uuid`. A row with no owner and no junction row that postings reference gets the
+ *      posting's membership company with the smallest `c_uuid`. Every owned row then gets a
+ *      junction row to its owner when it has none, so no posting points at an unowned row. Only
+ *      `IS NULL` owners are written: a re-run never overwrites an owner.
+ *   3. DROP the global unique `IDX_<table>_name` when present (copies share the name).
+ *   4. SPLIT. For every (company, row) where the company is not the row's owner — a junction row,
+ *      or a posting of that company's memberships — the company gets its own copy: an existing
+ *      row it owns with the same name (column collation) is reused, else one is inserted
+ *      (`UUID()`, same name, that owner). The company's junction row to the copy is added, that
+ *      company's postings are repointed to the copy, and only then its junction row to the
+ *      original is deleted (creates before deletes, so a re-run after a partial failure resumes).
+ *      A re-run finds no (company, row) off the owner and does nothing.
+ *   5. ADD UNIQUE `IDX_<table>_company_name (owner, name)` when absent; duplicates (only possible
+ *      on a database that never had the global unique) fail with the names, nothing indexed.
+ * A row linked to no company and referenced by no posting keeps a NULL owner (root only).
+ *
+ * `down`: refuses (no change) while any name exists more than once in a table whose global
+ * unique is absent; otherwise drops the per-company unique, re-adds the global unique, drops the
+ * FK, the index and the column (IF EXISTS each). Split copies are not merged back.
+ *
+ * Names: schema from `ctx.schemas` (`frameworkSchemasForMigration`), so the four-database,
+ * namespace and single layouts all work (single: framework tables unprefixed in one database, as
+ * in `...101`). Literal table/column/index names, every value `?`-bound, no hardcoded ids. Sorts
+ * after `...001` (catalogs), `...002` (junctions, postings) and `...102` (the latest published).
+ */
+
+const { frameworkSchemasForMigration } = require('@astram/core');
+
+const MIGRATION = '1710000000105-OwnDepartmentsAndBranches';
+/** Duplicate groups listed in a failure message; the rest are counted. */
+const MAX_LISTED = 50;
+
+const KINDS = [
+  {
+    label: 'department',
+    table: 'departments',
+    pk: 'd_uuid',
+    name: 'd_name',
+    created: 'd_created_at',
+    owner: 'd_company_uuid',
+    index: 'idx_departments_company',
+    fk: 'FK_departments_company',
+    globalUnique: 'IDX_departments_name',
+    companyUnique: 'IDX_departments_company_name',
+    junction: 'company_departments',
+    jCompany: 'cd_company_uuid',
+    jUnit: 'cd_department_uuid',
+    posting: 'mp_department_uuid',
+  },
+  {
+    label: 'branch',
+    table: 'branches',
+    pk: 'b_uuid',
+    name: 'b_name',
+    created: 'b_created_at',
+    owner: 'b_company_uuid',
+    index: 'idx_branches_company',
+    fk: 'FK_branches_company',
+    globalUnique: 'IDX_branches_name',
+    companyUnique: 'IDX_branches_company_name',
+    junction: 'company_branches',
+    jCompany: 'cb_company_uuid',
+    jUnit: 'cb_branch_uuid',
+    posting: 'mp_branch_uuid',
+  },
+];
+
+const rowsOf = (result) => (Array.isArray(result) ? result : []);
+
+const present = async (query, sql, params) => rowsOf(await query(sql, params)).length > 0;
+
+const hasColumn = (query, APP, table, column) =>
+  present(
+    query,
+    `SELECT 1 AS n FROM information_schema.COLUMNS
+      WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ? AND COLUMN_NAME = ? LIMIT 1`,
+    [APP, table, column],
+  );
+
+const hasIndex = (query, APP, table, index) =>
+  present(
+    query,
+    `SELECT 1 AS n FROM information_schema.STATISTICS
+      WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ? AND INDEX_NAME = ? LIMIT 1`,
+    [APP, table, index],
+  );
+
+const hasFk = (query, APP, table, fk) =>
+  present(
+    query,
+    `SELECT 1 AS n FROM information_schema.REFERENTIAL_CONSTRAINTS
+      WHERE CONSTRAINT_SCHEMA = ? AND TABLE_NAME = ? AND CONSTRAINT_NAME = ? LIMIT 1`,
+    [APP, table, fk],
+  );
+
+/** Step 1: owner column, its index and FK, each when absent. */
+async function addOwnerColumn(query, APP, k) {
+  const T = `\`${APP}\`.\`${k.table}\``;
+  if (!(await hasColumn(query, APP, k.table, k.owner))) {
+    await query(`ALTER TABLE ${T} ADD COLUMN ${k.owner} VARCHAR(36) NULL`);
+  }
+  if (!(await hasIndex(query, APP, k.table, k.index))) {
+    await query(`CREATE INDEX ${k.index} ON ${T} (${k.owner})`);
+  }
+  if (!(await hasFk(query, APP, k.table, k.fk))) {
+    await query(`ALTER TABLE ${T}
+      ADD CONSTRAINT ${k.fk} FOREIGN KEY (${k.owner})
+      REFERENCES \`${APP}\`.\`companies\` (c_uuid) ON DELETE CASCADE`);
+  }
+}
+
+/** Step 2: owners from junctions, then from postings; every owned row linked to its owner. */
+async function assignOwners(query, APP, k) {
+  const T = `\`${APP}\`.\`${k.table}\``;
+  const J = `\`${APP}\`.\`${k.junction}\``;
+  const MP = `\`${APP}\`.\`membership_posting\``;
+  const CM = `\`${APP}\`.\`company_membership\``;
+
+  await query(`UPDATE ${T} u
+      SET u.${k.owner} = (SELECT MIN(j.${k.jCompany}) FROM ${J} j WHERE j.${k.jUnit} = u.${k.pk})
+    WHERE u.${k.owner} IS NULL
+      AND EXISTS (SELECT 1 FROM ${J} j WHERE j.${k.jUnit} = u.${k.pk})`);
+
+  await query(`UPDATE ${T} u
+      SET u.${k.owner} = (SELECT MIN(cm.cm_company_uuid)
+        FROM ${MP} mp
+        JOIN ${CM} cm ON cm.cm_uuid = mp.mp_membership_uuid
+       WHERE mp.${k.posting} = u.${k.pk})
+    WHERE u.${k.owner} IS NULL
+      AND NOT EXISTS (SELECT 1 FROM ${J} j WHERE j.${k.jUnit} = u.${k.pk})
+      AND EXISTS (SELECT 1 FROM ${MP} mp WHERE mp.${k.posting} = u.${k.pk})`);
+
+  const unlinked = rowsOf(
+    await query(`SELECT u.${k.owner} AS company, u.${k.pk} AS unit FROM ${T} u
+       WHERE u.${k.owner} IS NOT NULL
+         AND NOT EXISTS (SELECT 1 FROM ${J} j
+                          WHERE j.${k.jCompany} = u.${k.owner} AND j.${k.jUnit} = u.${k.pk})
+       ORDER BY company, unit`),
+  );
+  for (const { company, unit } of unlinked) await link(query, APP, k, company, unit);
+}
+
+/** Insert the junction row (company, unit) when absent. */
+async function link(query, APP, k, company, unit) {
+  const J = `\`${APP}\`.\`${k.junction}\``;
+  await query(
+    `INSERT INTO ${J} (${k.jCompany}, ${k.jUnit})
+     SELECT ?, ? FROM DUAL
+      WHERE NOT EXISTS (SELECT 1 FROM ${J} WHERE ${k.jCompany} = ? AND ${k.jUnit} = ?)`,
+    [company, unit, company, unit],
+  );
+}
+
+/** Step 4: give every non-owner company that uses a row its own copy. */
+async function splitShared(query, APP, k) {
+  const T = `\`${APP}\`.\`${k.table}\``;
+  const J = `\`${APP}\`.\`${k.junction}\``;
+  const MP = `\`${APP}\`.\`membership_posting\``;
+  const CM = `\`${APP}\`.\`company_membership\``;
+
+  const pairs = rowsOf(
+    await query(`SELECT j.${k.jCompany} AS company, u.${k.pk} AS unit, u.${k.name} AS name
+        FROM ${J} j
+        JOIN ${T} u ON u.${k.pk} = j.${k.jUnit}
+       WHERE u.${k.owner} IS NOT NULL AND j.${k.jCompany} <> u.${k.owner}
+      UNION
+      SELECT cm.cm_company_uuid AS company, u.${k.pk} AS unit, u.${k.name} AS name
+        FROM ${MP} mp
+        JOIN ${CM} cm ON cm.cm_uuid = mp.mp_membership_uuid
+        JOIN ${T} u ON u.${k.pk} = mp.${k.posting}
+       WHERE u.${k.owner} IS NOT NULL AND cm.cm_company_uuid <> u.${k.owner}
+      ORDER BY company, unit`),
+  );
+
+  const findOwned = async (company, name) => {
+    const rows = rowsOf(
+      await query(
+        `SELECT ${k.pk} AS uuid FROM ${T} WHERE ${k.owner} = ? AND ${k.name} = ? ORDER BY ${k.pk} LIMIT 1`,
+        [company, name],
+      ),
+    );
+    return rows.length > 0 ? String(rows[0].uuid) : null;
+  };
+
+  for (const { company, unit, name } of pairs) {
+    let copy = await findOwned(company, name);
+    if (copy === null) {
+      await query(
+        `INSERT INTO ${T} (${k.pk}, ${k.name}, ${k.owner}, ${k.created})
+         SELECT UUID(), src.${k.name}, ?, src.${k.created} FROM ${T} src WHERE src.${k.pk} = ?`,
+        [company, unit],
+      );
+      copy = await findOwned(company, name);
+      if (copy === null) {
+        throw new Error(`${MIGRATION}: could not create a company-owned ${k.label} copy; re-run.`);
+      }
+    }
+    await link(query, APP, k, company, copy);
+    // Resume safety (security review P2): after a partial failure a membership may already hold the
+    // same posting (role + the other org unit) on the copy. Repointing its twin would break
+    // `IDX_mp_unique` (1062) and fail every re-run, so the twin on the original is removed first;
+    // the posting on the copy keeps the assignment.
+    const other = k.posting === 'mp_department_uuid' ? 'mp_branch_uuid' : 'mp_department_uuid';
+    await query(
+      `DELETE mp FROM ${MP} mp
+         JOIN ${CM} cm ON cm.cm_uuid = mp.mp_membership_uuid
+         JOIN ${MP} twin ON twin.mp_membership_uuid = mp.mp_membership_uuid
+                        AND twin.mp_role_uuid = mp.mp_role_uuid
+                        AND twin.${other} <=> mp.${other}
+                        AND twin.${k.posting} = ?
+        WHERE mp.${k.posting} = ? AND cm.cm_company_uuid = ?`,
+      [copy, unit, company],
+    );
+    await query(
+      `UPDATE ${MP} mp
+         JOIN ${CM} cm ON cm.cm_uuid = mp.mp_membership_uuid
+          SET mp.${k.posting} = ?
+        WHERE mp.${k.posting} = ? AND cm.cm_company_uuid = ?`,
+      [copy, unit, company],
+    );
+    await query(`DELETE FROM ${J} WHERE ${k.jCompany} = ? AND ${k.jUnit} = ?`, [company, unit]);
+  }
+}
+
+function duplicateError(k, APP, groups, scope, tail) {
+  const listed = groups.slice(0, MAX_LISTED).map((g) => `  - "${g.name}": ${g.n} rows`);
+  if (groups.length > MAX_LISTED) listed.push(`  - ... and ${groups.length - MAX_LISTED} more`);
+  return new Error(
+    `${MIGRATION}: ${groups.length} ${k.label} name(s) occur more than once ${scope} in ` +
+      `${APP}.${k.table} (compared as the column collation does: case- and accent-insensitive):\n` +
+      `${listed.join('\n')}\n${tail}`,
+  );
+}
+
+/** Step 5: per-company unique when absent; duplicates fail with their names. */
+async function addCompanyUnique(query, APP, k) {
+  if (await hasIndex(query, APP, k.table, k.companyUnique)) return;
+  const groups = rowsOf(
+    await query(`SELECT MIN(${k.name}) AS name, COUNT(*) AS n
+        FROM \`${APP}\`.\`${k.table}\`
+       WHERE ${k.owner} IS NOT NULL
+       GROUP BY ${k.owner}, ${k.name}
+      HAVING COUNT(*) > 1
+       ORDER BY n DESC`),
+  );
+  if (groups.length > 0) {
+    throw duplicateError(
+      k,
+      APP,
+      groups,
+      'within one company',
+      `No unique index was created. Rename or remove the duplicates, then re-run astram-migrate.`,
+    );
+  }
+  await query(
+    `CREATE UNIQUE INDEX ${k.companyUnique} ON \`${APP}\`.\`${k.table}\` (${k.owner}, ${k.name})`,
+  );
+}
+
+async function up(ctx) {
+  const { query } = ctx;
+  const APP = frameworkSchemasForMigration(ctx, process.env).app;
+  for (const k of KINDS) {
+    await addOwnerColumn(query, APP, k);
+    await assignOwners(query, APP, k);
+    if (await hasIndex(query, APP, k.table, k.globalUnique)) {
+      await query(`DROP INDEX ${k.globalUnique} ON \`${APP}\`.\`${k.table}\``);
+    }
+    await splitShared(query, APP, k);
+    await addCompanyUnique(query, APP, k);
+  }
+}
+
+async function down(ctx) {
+  const { query } = ctx;
+  const APP = frameworkSchemasForMigration(ctx, process.env).app;
+
+  // Pre-check every table before changing any: the global unique cannot come back while a name
+  // is held by more than one row (a split copy, or two companies' own rows).
+  const restore = [];
+  for (const k of KINDS) {
+    if (await hasIndex(query, APP, k.table, k.globalUnique)) continue;
+    const groups = rowsOf(
+      await query(`SELECT MIN(${k.name}) AS name, COUNT(*) AS n
+          FROM \`${APP}\`.\`${k.table}\`
+         GROUP BY ${k.name}
+        HAVING COUNT(*) > 1
+         ORDER BY n DESC`),
+    );
+    if (groups.length > 0) {
+      throw duplicateError(
+        k,
+        APP,
+        groups,
+        'across companies',
+        'Nothing was rolled back: the global unique name index cannot be restored while these ' +
+          'exist (split copies are not merged back). Rename or remove them first.',
+      );
+    }
+    restore.push(k);
+  }
+
+  for (const k of KINDS) {
+    const T = `\`${APP}\`.\`${k.table}\``;
+    await query(`DROP INDEX IF EXISTS ${k.companyUnique} ON ${T}`);
+    if (restore.includes(k)) {
+      await query(`CREATE UNIQUE INDEX IF NOT EXISTS ${k.globalUnique} ON ${T} (${k.name})`);
+    }
+    await query(`ALTER TABLE ${T} DROP FOREIGN KEY IF EXISTS ${k.fk}`);
+    await query(`DROP INDEX IF EXISTS ${k.index} ON ${T}`);
+    await query(`ALTER TABLE ${T} DROP COLUMN IF EXISTS ${k.owner}`);
+  }
+}
+
+module.exports = { up, down };