Member Schema¶

member schema 는 길드 멤버 상태와 웹 조인 진행 기록을 저장한다.

Schema purpose¶

• PostgreSQL schema — member
• Corresponding domain — engine/member/
• sqlc package — db/queries/member/

대규모 길드의 멤버 조회와 Live Sync 배치 갱신을 수용해야 한다. 인덱스 설계가 중요.

Tables¶

member.members¶

길드 멤버 레코드.

CREATE TABLE member.members (
    id                UUID PRIMARY KEY,
    guild_id          UUID NOT NULL REFERENCES guild.guilds(id),
    discord_user_id   TEXT NOT NULL,
    user_id           UUID REFERENCES identity.users(id),
    joined_via        TEXT NOT NULL CHECK (joined_via IN ('web_join', 'direct', 'restored')),
    joined_at         TIMESTAMPTZ NOT NULL,
    left_at           TIMESTAMPTZ,
    role_ids          TEXT[] NOT NULL DEFAULT '{}',
    nickname          TEXT,
    created_at        TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at        TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    CONSTRAINT members_guild_discord_unique UNIQUE (guild_id, discord_user_id)
);

Columns

Indexes

Foreign keys

Invariants

• (guild_id, discord_user_id) 유일 — 같은 길드에 같은 Discord 유저 레코드 1개
• 재가입 시 기존 row 의 left_at NULL 로 초기화, joined_at 갱신
• role_ids 는 Discord role snowflake 배열

member.web_join_requests¶

웹 조인 진행 상태 추적.

CREATE TABLE member.web_join_requests (
    id                      UUID PRIMARY KEY,
    guild_id                UUID NOT NULL REFERENCES guild.guilds(id),
    discord_user_id         TEXT NOT NULL,
    state                   TEXT NOT NULL CHECK (state IN ('pending', 'completed', 'failed')),
    encrypted_access_token  BYTEA,
    attempted_at            TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    completed_at            TIMESTAMPTZ,
    failure_reason          TEXT
);

Columns

Indexes

Invariants

• state = 'pending' 이 1시간 초과면 cron 이 failed 로 전환 + token 삭제
• completed 또는 failed 시 encrypted_access_token NULL 로 설정 (보안)

Relationships¶

erDiagram
    MEMBERS }o--|| GUILDS : "belongs to"
    MEMBERS }o--o| USERS : "linked to (optional)"
    WEB_JOIN_REQUESTS }o--|| GUILDS : "targets"

Cross-schema references¶

Query patterns¶

• UpsertMember — Live Sync 가 호출
• MarkMemberLeft — 탈퇴 이벤트
• GetMemberByGuildAndDiscordID — 특정 멤버 조회
• ListActiveMembers — 길드 멤버 목록 (페이지네이션)
• CountActiveMembers — 플랜 한도 체크용
• InsertWebJoinRequest — 웹 조인 시작
• CompleteWebJoinRequest — 완료 처리 (token 삭제 포함)
• ExpireStalePendingRequests — cron 용

Data retention¶

• Members — 영구 보관 (감사 목적), soft leave 로 유지
• Web join requests — 90일 후 완료/실패 기록 삭제 (cron)
• Access tokens — completed 또는 failed 시 즉시 NULL

Migration history¶

See also¶

• domain/member.md — Member 도메인
• data/guild-schema.md — 참조하는 Guild
• data/identity-schema.md — 연결된 User
• flows/web-join.md — 웹 조인 흐름
• adr/0020-postgres-schema-per-domain.md — schema 분리