starr-philproperties/utils/defaultGroup.util.js

/**
 * Every user belongs to exactly one group at all times — a real group, or the
 * NOGRP placeholder if they haven't been assigned one yet. NOGRP is a normal
 * row-backed group (not a computed "users with no group" view), so every
 * writer that moves a user in or out of a real group must also keep their
 * NOGRP row in sync. This util is the single place that invariant is
 * enforced — see project memory "NOGRP dual-membership fix" (2026-07-15) for
 * the bug this replaced (users silently stuck in both NOGRP and a real group).
 */
const { mdl_UserGroups, mdl_UserGroupMembers } = require('../models/users/user_groups.mdl');

const NOGRP_CODE = 'NOGRP';

async function getDefaultGroupId() {
  const nogrp = await mdl_UserGroups.findOne({ where: { group_code: NOGRP_CODE, is_active: true }, attributes: ['group_id'] });
  return nogrp ? nogrp.group_id : null;
}

/** Registration fallback: enroll a brand-new user into NOGRP. */
async function enrollDefaultGroup(user_id, { transaction, createdBy = null } = {}) {
  const group_id = await getDefaultGroupId();
  if (!group_id) return null;
  return mdl_UserGroupMembers.create({ group_id, user_id, createdBy }, { transaction });
}

/**
 * Call after adding user_ids to a real group: drops their stale NOGRP row so
 * they don't sit in both simultaneously. No-op if group_id being added to IS
 * NOGRP itself.
 */
async function dropDefaultGroupMembership(user_ids, group_id, { updatedBy = null } = {}) {
  const nogrpId = await getDefaultGroupId();
  if (!nogrpId || Number(nogrpId) === Number(group_id)) return;

  await mdl_UserGroupMembers.update(
    { deletedBy: updatedBy },
    { where: { user_id: user_ids, group_id: nogrpId } }
  );
  await mdl_UserGroupMembers.destroy({ where: { user_id: user_ids, group_id: nogrpId } });
}

/**
 * Call after removing user_ids from a group: re-enrolls into NOGRP whichever
 * of those users are left with zero active group memberships.
 */
async function reconcileDefaultGroup(user_ids, { createdBy = null } = {}) {
  const nogrpId = await getDefaultGroupId();
  if (!nogrpId) return;

  const remaining = await mdl_UserGroupMembers.findAll({
    where: { user_id: user_ids }, attributes: ['user_id'], group: ['user_id'],
  });
  const stillGrouped = new Set(remaining.map((m) => m.user_id));
  const orphaned = user_ids.filter((id) => !stillGrouped.has(id));
  if (!orphaned.length) return;

  await mdl_UserGroupMembers.restore({ where: { user_id: orphaned, group_id: nogrpId } });
  await mdl_UserGroupMembers.update(
    { deletedBy: null, updatedBy: createdBy },
    { where: { user_id: orphaned, group_id: nogrpId }, paranoid: false }
  );
  await mdl_UserGroupMembers.bulkCreate(
    orphaned.map((user_id) => ({ user_id, group_id: nogrpId, createdBy })),
    { ignoreDuplicates: true }
  );
}

/**
 * Invite-link login: if user_id is currently sitting in NOGRP, move them into
 * the group identified by group_code. Never reassigns someone already parked
 * in a real (non-NOGRP) group — an invite link used post-login only fills in
 * an ungrouped user's group, it doesn't override an existing one. No-op if
 * group_code doesn't resolve to an active group.
 */
async function switchFromNogrpByCode(user_id, group_code, { updatedBy = null } = {}) {
  if (!group_code) return null;

  const group = await mdl_UserGroups.findOne({
    where: { group_code: group_code.toUpperCase().trim(), is_active: true },
  });
  if (!group) return null;

  const membership = await mdl_UserGroupMembers.findOne({
    where:   { user_id },
    include: [{ model: mdl_UserGroups, attributes: ['group_code'] }],
  });
  if (membership) {
    if (membership.UserGroup?.group_code !== NOGRP_CODE) return null; // already in a real group — leave it alone
    if (Number(membership.group_id) === Number(group.group_id)) return group; // already in this exact group
  }

  await mdl_UserGroupMembers.create({ group_id: group.group_id, user_id, createdBy: updatedBy });
  await dropDefaultGroupMembership([user_id], group.group_id, { updatedBy });

  return group;
}

module.exports = { NOGRP_CODE, getDefaultGroupId, enrollDefaultGroup, dropDefaultGroupMembership, reconcileDefaultGroup, switchFromNogrpByCode };