feat(hub): add org members, teams, and project team-access APIs

Manage memberships with last-OWNER protection, team lifecycle (archive revokes TEAM grants), and TEAM→PROJECT access under org admin auth.
2026-07-10 00:55:34 +08:00
parent 1f8510a47f
commit 683d5674d1
7 changed files with 1008 additions and 0 deletions
@@ -0,0 +1,213 @@
+/**
+ * Organization membership management for org admin (ADR-0021).
+ *
+ * Role rules (product pin, not yet in Lean):
+ * 1. Actor must be OWNER or ADMIN (enforced at HTTP layer).
+ * 2. Only OWNER can grant/revoke OWNER or modify another OWNER.
+ * 3. Cannot revoke or demote the last remaining OWNER.
+ * 4. ADMIN cannot modify OWNER memberships.
+ */
+import type { OrganizationMemberRole, PrismaClient } from "@prisma/client";
+
+export interface OrgMemberRow {
+  readonly userId: string;
+  readonly feishuOpenId: string;
+  readonly displayName: string;
+  readonly avatarUrl: string | null;
+  readonly role: OrganizationMemberRole;
+  readonly createdAt: string;
+}
+
+export async function listOrgMembers(
+  prisma: PrismaClient,
+  organizationId: string,
+): Promise<readonly OrgMemberRow[]> {
+  const rows = await prisma.organizationMembership.findMany({
+    where: { organizationId, revokedAt: null },
+    select: {
+      role: true,
+      createdAt: true,
+      user: {
+        select: { id: true, feishuOpenId: true, displayName: true, avatarUrl: true },
+      },
+    },
+    orderBy: [{ role: "asc" }, { createdAt: "asc" }],
+  });
+  return rows.map((row) => ({
+    userId: row.user.id,
+    feishuOpenId: row.user.feishuOpenId,
+    displayName: row.user.displayName,
+    avatarUrl: row.user.avatarUrl,
+    role: row.role,
+    createdAt: row.createdAt.toISOString(),
+  }));
+}
+
+export async function addOrgMember(
+  prisma: PrismaClient,
+  input: {
+    readonly organizationId: string;
+    readonly actorRole: OrganizationMemberRole;
+    readonly feishuOpenId: string;
+    readonly displayName?: string | undefined;
+    readonly role: OrganizationMemberRole;
+  },
+): Promise<OrgMemberRow> {
+  const openId = requireNonEmpty(input.feishuOpenId, "feishuOpenId");
+  assertCanAssignRole(input.actorRole, input.role, /* targetIsOwner */ false);
+
+  const user = await prisma.user.upsert({
+    where: { feishuOpenId: openId },
+    create: {
+      feishuOpenId: openId,
+      displayName: input.displayName?.trim() || openId,
+    },
+    update: {
+      ...(input.displayName !== undefined && input.displayName.trim() !== ""
+        ? { displayName: input.displayName.trim() }
+        : {}),
+    },
+  });
+
+  const existing = await prisma.organizationMembership.findFirst({
+    where: { organizationId: input.organizationId, userId: user.id, revokedAt: null },
+  });
+  if (existing !== null) {
+    throw new Error(`user ${user.id} is already an active member`);
+  }
+
+  const membership = await prisma.organizationMembership.create({
+    data: {
+      organizationId: input.organizationId,
+      userId: user.id,
+      role: input.role,
+    },
+  });
+
+  return {
+    userId: user.id,
+    feishuOpenId: user.feishuOpenId,
+    displayName: user.displayName,
+    avatarUrl: user.avatarUrl,
+    role: membership.role,
+    createdAt: membership.createdAt.toISOString(),
+  };
+}
+
+export async function setOrgMemberRole(
+  prisma: PrismaClient,
+  input: {
+    readonly organizationId: string;
+    readonly actorUserId: string;
+    readonly actorRole: OrganizationMemberRole;
+    readonly targetUserId: string;
+    readonly role: OrganizationMemberRole;
+  },
+): Promise<OrgMemberRow> {
+  const membership = await prisma.organizationMembership.findFirst({
+    where: {
+      organizationId: input.organizationId,
+      userId: input.targetUserId,
+      revokedAt: null,
+    },
+    select: {
+      id: true,
+      role: true,
+      createdAt: true,
+      user: {
+        select: { id: true, feishuOpenId: true, displayName: true, avatarUrl: true },
+      },
+    },
+  });
+  if (membership === null) {
+    throw new Error(`member not found: ${input.targetUserId}`);
+  }
+
+  assertCanAssignRole(input.actorRole, input.role, membership.role === "OWNER");
+  if (membership.role === "OWNER" && input.actorRole !== "OWNER") {
+    throw new Error("cannot modify OWNER membership as ADMIN");
+  }
+  if (membership.role === "OWNER" && input.role !== "OWNER") {
+    await assertNotLastOwner(prisma, input.organizationId, input.targetUserId);
+  }
+
+  const updated = await prisma.organizationMembership.update({
+    where: { id: membership.id },
+    data: { role: input.role },
+  });
+
+  return {
+    userId: membership.user.id,
+    feishuOpenId: membership.user.feishuOpenId,
+    displayName: membership.user.displayName,
+    avatarUrl: membership.user.avatarUrl,
+    role: updated.role,
+    createdAt: membership.createdAt.toISOString(),
+  };
+}
+
+export async function revokeOrgMember(
+  prisma: PrismaClient,
+  input: {
+    readonly organizationId: string;
+    readonly actorUserId: string;
+    readonly actorRole: OrganizationMemberRole;
+    readonly targetUserId: string;
+  },
+): Promise<{ readonly revoked: true; readonly userId: string }> {
+  const membership = await prisma.organizationMembership.findFirst({
+    where: {
+      organizationId: input.organizationId,
+      userId: input.targetUserId,
+      revokedAt: null,
+    },
+    select: { id: true, role: true },
+  });
+  if (membership === null) {
+    throw new Error(`member not found: ${input.targetUserId}`);
+  }
+  if (membership.role === "OWNER" && input.actorRole !== "OWNER") {
+    throw new Error("cannot revoke OWNER membership as ADMIN");
+  }
+  if (membership.role === "OWNER") {
+    await assertNotLastOwner(prisma, input.organizationId, input.targetUserId);
+  }
+
+  await prisma.organizationMembership.update({
+    where: { id: membership.id },
+    data: { revokedAt: new Date() },
+  });
+  return { revoked: true as const, userId: input.targetUserId };
+}
+
+function assertCanAssignRole(
+  actorRole: OrganizationMemberRole,
+  newRole: OrganizationMemberRole,
+  targetIsOwner: boolean,
+): void {
+  if (newRole === "OWNER" && actorRole !== "OWNER") {
+    throw new Error("only OWNER can grant OWNER role");
+  }
+  if (targetIsOwner && actorRole !== "OWNER") {
+    throw new Error("cannot modify OWNER membership as ADMIN");
+  }
+}
+
+async function assertNotLastOwner(
+  prisma: PrismaClient,
+  organizationId: string,
+  targetUserId: string,
+): Promise<void> {
+  const owners = await prisma.organizationMembership.count({
+    where: { organizationId, role: "OWNER", revokedAt: null },
+  });
+  if (owners <= 1) {
+    throw new Error(`cannot revoke or demote last OWNER (${targetUserId})`);
+  }
+}
+
+function requireNonEmpty(value: string, label: string): string {
+  const trimmed = value.trim();
+  if (trimmed === "") throw new Error(`${label} is required`);
+  return trimmed;
+}