Phase 4 backend: teams data layer + membership management

- Migration 0003: teams + team_memberships (owner/admin/member, seat_limit)
- POST /v1/teams (Team-tier gated), GET /v1/teams/{id},
  GET|POST /v1/teams/{id}/members, DELETE …/members/{userId}
- Add-by-email (existing accounts), seat-cap enforcement (402), role-based
  authorization (admin to mutate; non-members get 404; owner unremovable)
- Invite notification email; Tier::can_own_team()

100 backend tests; fmt + clippy clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

cardclaws-backend/crates/cardclaws-db/migrations/0003_teams.sql

@@ -0,0 +1,23 @@
+-- 0003_teams.sql — Team tier data layer (PRD §21 Phase 4).
+
+CREATE TABLE teams (
+    id         UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    name       TEXT NOT NULL,
+    owner_id   UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    -- NULL = unlimited seats; otherwise the billed seat cap.
+    seat_limit INTEGER,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX idx_teams_owner ON teams(owner_id);
+
+CREATE TABLE team_memberships (
+    team_id    UUID NOT NULL REFERENCES teams(id) ON DELETE CASCADE,
+    user_id    UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    role       TEXT NOT NULL DEFAULT 'member'
+                   CHECK (role IN ('owner', 'admin', 'member')),
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    PRIMARY KEY (team_id, user_id)
+);
+
+CREATE INDEX idx_team_memberships_user ON team_memberships(user_id);

cardclaws-backend/crates/cardclaws-db/src/models/mod.rs

@@ -5,4 +5,5 @@ pub mod analytics;
 pub mod card;
 pub mod session;
 pub mod share_link;
+pub mod team;
 pub mod user;

cardclaws-backend/crates/cardclaws-db/src/models/team.rs

@@ -0,0 +1,25 @@
+use chrono::{DateTime, Utc};
+use serde::Serialize;
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, FromRow, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct TeamRow {
+    pub id: Uuid,
+    pub name: String,
+    pub owner_id: Uuid,
+    pub seat_limit: Option<i32>,
+    pub created_at: DateTime<Utc>,
+}
+
+/// A team member row joined with the user's identity, for member listings.
+#[derive(Debug, Clone, FromRow, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct MemberRow {
+    pub user_id: Uuid,
+    pub email: String,
+    pub display_name: String,
+    pub role: String,
+    pub created_at: DateTime<Utc>,
+}

cardclaws-backend/crates/cardclaws-db/src/queries/mod.rs

@@ -5,4 +5,5 @@ pub mod analytics;
 pub mod cards;
 pub mod sessions;
 pub mod share;
+pub mod teams;
 pub mod users;

cardclaws-backend/crates/cardclaws-db/src/queries/teams.rs

@@ -0,0 +1,92 @@
+//! Team + membership queries (PRD §21 Phase 4).
+
+use uuid::Uuid;
+
+use crate::models::team::{MemberRow, TeamRow};
+use crate::Db;
+
+pub async fn insert_team(
+    db: &Db,
+    name: &str,
+    owner_id: Uuid,
+    seat_limit: Option<i32>,
+) -> Result<TeamRow, sqlx::Error> {
+    sqlx::query_as(
+        r#"INSERT INTO teams (name, owner_id, seat_limit)
+           VALUES ($1, $2, $3)
+           RETURNING id, name, owner_id, seat_limit, created_at"#,
+    )
+    .bind(name)
+    .bind(owner_id)
+    .bind(seat_limit)
+    .fetch_one(db)
+    .await
+}
+
+pub async fn find_team(db: &Db, id: Uuid) -> Result<Option<TeamRow>, sqlx::Error> {
+    sqlx::query_as(r#"SELECT id, name, owner_id, seat_limit, created_at FROM teams WHERE id = $1"#)
+        .bind(id)
+        .fetch_optional(db)
+        .await
+}
+
+pub async fn insert_membership(
+    db: &Db,
+    team_id: Uuid,
+    user_id: Uuid,
+    role: &str,
+) -> Result<(), sqlx::Error> {
+    sqlx::query(r#"INSERT INTO team_memberships (team_id, user_id, role) VALUES ($1, $2, $3)"#)
+        .bind(team_id)
+        .bind(user_id)
+        .bind(role)
+        .execute(db)
+        .await?;
+    Ok(())
+}
+
+/// Return the caller's role in a team, if any.
+pub async fn member_role(
+    db: &Db,
+    team_id: Uuid,
+    user_id: Uuid,
+) -> Result<Option<String>, sqlx::Error> {
+    let row: Option<(String,)> =
+        sqlx::query_as(r#"SELECT role FROM team_memberships WHERE team_id = $1 AND user_id = $2"#)
+            .bind(team_id)
+            .bind(user_id)
+            .fetch_optional(db)
+            .await?;
+    Ok(row.map(|r| r.0))
+}
+
+pub async fn list_members(db: &Db, team_id: Uuid) -> Result<Vec<MemberRow>, sqlx::Error> {
+    sqlx::query_as(
+        r#"SELECT u.id AS user_id, u.email, u.display_name, m.role, m.created_at
+           FROM team_memberships m
+           JOIN users u ON u.id = m.user_id
+           WHERE m.team_id = $1
+           ORDER BY m.created_at ASC"#,
+    )
+    .bind(team_id)
+    .fetch_all(db)
+    .await
+}
+
+pub async fn count_members(db: &Db, team_id: Uuid) -> Result<i64, sqlx::Error> {
+    let (n,): (i64,) =
+        sqlx::query_as(r#"SELECT COUNT(*) FROM team_memberships WHERE team_id = $1"#)
+            .bind(team_id)
+            .fetch_one(db)
+            .await?;
+    Ok(n)
+}
+
+pub async fn delete_membership(db: &Db, team_id: Uuid, user_id: Uuid) -> Result<u64, sqlx::Error> {
+    let r = sqlx::query(r#"DELETE FROM team_memberships WHERE team_id = $1 AND user_id = $2"#)
+        .bind(team_id)
+        .bind(user_id)
+        .execute(db)
+        .await?;
+    Ok(r.rows_affected())
+}