Refine onboarding state and nickname checks

This commit is contained in:
dahyeon committed 2026-04-21 12:42:24 -07:00
1 parent 5579db54da
commit 9c013f7d4f
33 files changed
+1523 -119

No files matched your search

@@ -0,0 +1,74 @@
import { describe, expect, it } from "vitest";
import { checkOnboardingProgressTool } from "./check-onboarding-progress.js";
import type { OnboardingSession } from "@skills/onboarding/types";
function makeSession(
overrides?: Partial<OnboardingSession>,
): OnboardingSession {
return {
chatroomId: "room-1",
deadlineAt: new Date(Date.now() + 30 * 60 * 1000).toISOString(),
joinedAt: "2026-04-21T16:57:27.244Z",
kakaotalkNickname: "날으는꼴뚜기/95/여/D",
kakaotalkNicknameAliases: ["날으는꼴뚜기/95/여/D"],
kakaotalkNicknameVerified: true,
lastEventAt: "2026-04-21T17:00:03.862Z",
nicknameVerified: true,
photoVerified: true,
status: "pending",
userId: "user-1",
...overrides,
};
}
describe("checkOnboardingProgressTool", () => {
it("returns discord profile steps for extended sessions after step1", async () => {
const result = await checkOnboardingProgressTool.execute(
{
chatroomId: "room-1",
userId: "user-1",
},
{
chatroomId: "room-1",
session: makeSession({
discordProfileMessageVerified: false,
discordProfileNicknameVerified: false,
identityRoomJoined: true,
recruitingRoomJoined: true,
step1CompletedAt: "2026-04-21T16:57:44.767Z",
}),
userId: "user-1",
},
);
expect(result.step1Done).toBe(true);
expect(result.overallDone).toBe(false);
expect(result.remainingSteps).toEqual([
"discord-profile-nickname",
"discord-profile-message",
]);
expect(result.remainingStepLabels).toEqual([
"디스코드 프로필 닉네임 설정",
"디스코드 프로필 메시지 설정",
]);
});
it("treats legacy sessions as completed when nickname and photo are done", async () => {
const result = await checkOnboardingProgressTool.execute(
{
chatroomId: "room-1",
userId: "user-1",
},
{
chatroomId: "room-1",
session: makeSession(),
userId: "user-1",
},
);
expect(result.step1Done).toBe(true);
expect(result.overallDone).toBe(true);
expect(result.remainingSteps).toEqual([]);
});
});
+30 -20
View File
@@ -1,6 +1,16 @@
import { z } from "zod";
import { getOnboardingSessionKeyPrefix } from "../../config.js";
import type { OnboardingSession } from "@skills/onboarding/types";
import { normalizeOnboardingSession } from "@skills/onboarding/session";
import {
formatRemainingStep,
getRemainingSteps,
isOnboardingCompleted,
isStep1Completed,
} from "@skills/onboarding/state/progress";
import type {
OnboardingSession,
StoredOnboardingSession,
} from "@skills/onboarding/types";
import type { Tool } from "../tool.js";
const argsSchema = z.object({
@@ -11,32 +21,27 @@ const argsSchema = z.object({
const resultSchema = z.object({
nicknameDone: z.boolean(),
photoDone: z.boolean(),
remainingSteps: z.array(z.enum(["nickname", "photo"])),
step1Done: z.boolean(),
overallDone: z.boolean(),
remainingStepLabels: z.array(z.string()),
remainingSteps: z.array(z.enum([
"nickname",
"photo",
"identity-room",
"recruiting-room",
"discord-profile-nickname",
"discord-profile-message",
])),
deadlineInHours: z.number().nullable(),
});
function getRemainingSteps(session: OnboardingSession | null): Array<"nickname" | "photo"> {
if (!session) {
return ["nickname", "photo"];
}
const remaining: Array<"nickname" | "photo"> = [];
if (!session.nicknameVerified) {
remaining.push("nickname");
}
if (!session.photoVerified) {
remaining.push("photo");
}
return remaining;
}
export const checkOnboardingProgressTool: Tool<
z.infer<typeof argsSchema>,
z.infer<typeof resultSchema>
> = {
name: "check-onboarding-progress",
description:
"현재 유저의 온보딩 진행 상태를 읽어 남은 절차와 데드라인까지 남은 시간을 구조화해서 반환한다.",
"현재 유저의 온보딩 진행 상태를 읽어 카카오톡 단계와 디스코드 단계를 포함한 남은 절차를 구조화해서 반환한다.",
argsSchema,
resultSchema,
async execute(args, ctx) {
@@ -44,8 +49,10 @@ export const checkOnboardingProgressTool: Tool<
ctx.session && ctx.chatroomId === args.chatroomId && ctx.userId === args.userId
? ctx.session
: ctx.garnetClient
? await ctx.garnetClient.getJson<OnboardingSession>(
`${getOnboardingSessionKeyPrefix()}:onboarding:${args.chatroomId}:${args.userId}`,
? normalizeOnboardingSession(
await ctx.garnetClient.getJson<StoredOnboardingSession>(
`${getOnboardingSessionKeyPrefix()}:onboarding:${args.chatroomId}:${args.userId}`,
),
)
: null;
@@ -57,6 +64,9 @@ export const checkOnboardingProgressTool: Tool<
return {
nicknameDone: session?.nicknameVerified ?? false,
photoDone: session?.photoVerified ?? false,
step1Done: isStep1Completed(session),
overallDone: isOnboardingCompleted(session),
remainingStepLabels: getRemainingSteps(session).map(formatRemainingStep),
remainingSteps: getRemainingSteps(session),
deadlineInHours,
};
+4 -1
View File
@@ -3,13 +3,15 @@ import { checkOnboardingProgressTool } from "./check-onboarding-progress.js";
import { getRoomContextTool } from "./get-room-context.js";
import { lookupCommunityRuleTool } from "./lookup-community-rule.js";
import { validateNicknameTool } from "./validate-nickname.js";
import { verifyDiscordNicknameTool } from "./verify-discord-nickname.js";
export function createBuiltInToolRegistry(): ToolRegistry {
return new ToolRegistry()
.register(validateNicknameTool)
.register(checkOnboardingProgressTool)
.register(lookupCommunityRuleTool)
.register(getRoomContextTool);
.register(getRoomContextTool)
.register(verifyDiscordNicknameTool);
}
export {
@@ -17,4 +19,5 @@ export {
getRoomContextTool,
lookupCommunityRuleTool,
validateNicknameTool,
verifyDiscordNicknameTool,
};
@@ -0,0 +1,165 @@
import { describe, expect, it, vi } from "vitest";
import { verifyDiscordNicknameTool } from "./verify-discord-nickname.js";
import type { OnboardingSession } from "@skills/onboarding/types";
import type { DiscordMemberLookupResponse } from "@common/nats-subjects";
function makeSession(
overrides?: Partial<OnboardingSession>,
): OnboardingSession {
return {
chatroomId: "room-1",
deadlineAt: new Date(Date.now() + 30 * 60 * 1000).toISOString(),
joinedAt: "2026-04-17T00:00:00.000Z",
kakaotalkNickname: "프리리/95/여/E",
kakaotalkNicknameAliases: [],
kakaotalkNicknameVerified: true,
lastEventAt: new Date().toISOString(),
nicknameVerified: true,
photoVerified: false,
status: "pending",
userId: "user-1",
...overrides,
};
}
describe("verifyDiscordNicknameTool", () => {
it("returns nickname format guidance when the session nickname is invalid", async () => {
const result = await verifyDiscordNicknameTool.execute(
{},
{
session: makeSession({
kakaotalkNickname: "프리리/95/여D",
}),
},
);
expect(result.status).toBe("invalid-nickname-format");
expect(result.formatExample).toBe("홍길동/95/남/G");
expect(result.issueMessages?.length).toBeGreaterThan(0);
});
it("stores discordMemberId when a unique nickname match is found", async () => {
const setJson = vi.fn().mockResolvedValue(undefined);
const response: DiscordMemberLookupResponse = {
status: "ok",
nicknameMatches: [
{
memberId: "discord-1",
joinedAt: "2026-04-17T00:10:00.000Z",
globalName: "프리리",
guildNickname: "프리리#KR1/95/E",
matchedBy: "global-name",
username: "priri",
},
],
joinedAfterMatches: [],
};
const request = vi.fn(
async <TRequest = unknown, TResponse = unknown>(
_subject: string,
_payload: TRequest,
_options?: { timeoutMs?: number },
): Promise<TResponse> => response as TResponse,
);
const session = makeSession();
const result = await verifyDiscordNicknameTool.execute(
{},
{
chatroomId: session.chatroomId,
garnetClient: {
setJson,
} as never,
natsClient: {
request: request as never,
},
session,
userId: session.userId,
},
);
expect(result.status).toBe("matched-renamed");
expect(result.message).toContain("올바른 형식으로 설정되어 있어요");
expect(result.discordMemberId).toBe("discord-1");
expect(session.discordMemberId).toBe("discord-1");
expect(request).toHaveBeenCalledTimes(1);
expect(setJson).toHaveBeenCalledTimes(1);
});
it("does not mark renamed when only the raw kakao nickname matches literally", async () => {
const response: DiscordMemberLookupResponse = {
status: "ok",
nicknameMatches: [
{
memberId: "discord-1",
globalName: "프리리",
guildNickname: "프리리/95/여/E",
joinedAt: "2026-04-17T00:10:00.000Z",
matchedBy: "global-name",
username: "priri",
},
],
joinedAfterMatches: [],
};
const request = vi.fn(
async <TRequest = unknown, TResponse = unknown>(
_subject: string,
_payload: TRequest,
_options?: { timeoutMs?: number },
): Promise<TResponse> => response as TResponse,
);
const result = await verifyDiscordNicknameTool.execute(
{},
{
natsClient: {
request: request as never,
},
session: makeSession(),
},
);
expect(result.status).toBe("matched-pending-rename");
expect(result.message).toContain("이름#태그/출생연도/티어");
});
it("falls back to joined-after candidates and returns not-confirmed when ambiguous", async () => {
const response: DiscordMemberLookupResponse = {
status: "ok",
nicknameMatches: [],
joinedAfterMatches: [
{
memberId: "discord-1",
joinedAt: "2026-04-17T00:10:00.000Z",
username: "user-a",
},
{
memberId: "discord-2",
joinedAt: "2026-04-17T00:11:00.000Z",
username: "user-b",
},
],
};
const request = vi.fn(
async <TRequest = unknown, TResponse = unknown>(
_subject: string,
_payload: TRequest,
_options?: { timeoutMs?: number },
): Promise<TResponse> => response as TResponse,
);
const result = await verifyDiscordNicknameTool.execute(
{},
{
natsClient: {
request: request as never,
},
session: makeSession(),
},
);
expect(result.status).toBe("not-confirmed");
expect(result.reason).toBe("joined-after-ambiguous");
expect(result.joinedAfterMatchCount).toBe(2);
});
});
@@ -0,0 +1,366 @@
import { z } from "zod";
import {
getDiscordMemberLookupSubject,
getDiscordVerifyTimeoutMs,
getOnboardingSessionKeyPrefix,
} from "../../config.js";
import type {
DiscordMemberCandidate,
DiscordMemberLookupRequest,
DiscordMemberLookupResponse,
} from "@common/nats-subjects";
import { getContext, getRequestLogger } from "@obs/context";
import {
NICKNAME_FORMAT_EXAMPLE,
NICKNAME_FORMAT_TEXT,
} from "@skills/onboarding/constants";
import { analyzeNicknameIssues } from "@skills/onboarding/onboarding-templates";
import {
getKakaotalkNickname,
matchesDiscordNicknameRule,
parseKakaoNickname,
} from "@skills/onboarding/session";
import type { Tool, ToolContext } from "../tool.js";
const argsSchema = z.object({}).passthrough();
const resultSchema = z.object({
status: z.enum([
"invalid-nickname-format",
"lookup-unavailable",
"matched-pending-rename",
"matched-renamed",
"not-confirmed",
]),
message: z.string(),
reason: z
.enum([
"joined-after-ambiguous",
"joined-after-none",
"lookup-error",
"missing-search-name",
"missing-session",
"nickname-search-ambiguous",
"nickname-search-none",
"request-budget-exhausted",
])
.optional(),
expectedNickname: z.string().optional(),
searchName: z.string().optional(),
discordMemberId: z.string().optional(),
currentDisplayName: z.string().optional(),
formatExample: z.string().optional(),
guidance: z.string().optional(),
issueMessages: z.array(z.string()).optional(),
joinedAfterMatchCount: z.number().int().nonnegative().optional(),
matchSource: z.enum(["joined-after", "nickname"]).optional(),
matchedBy: z
.enum(["global-name", "guild-nickname", "joined-after", "username"])
.optional(),
nicknameMatchCount: z.number().int().nonnegative().optional(),
});
function pickDisplayName(candidate: DiscordMemberCandidate): string {
return (
candidate.guildNickname?.trim() ||
candidate.globalName?.trim() ||
candidate.username.trim()
);
}
function resolveTimeoutMs(): number | null {
const configured = getDiscordVerifyTimeoutMs();
const deadlineAt = getContext()?.deadlineAt;
if (!deadlineAt) {
return configured;
}
const remainingMs = Date.parse(deadlineAt) - Date.now() - 100;
if (!Number.isFinite(remainingMs) || remainingMs <= 0) {
return null;
}
return Math.min(configured, remainingMs);
}
async function persistDiscordMemberId(
memberId: string,
ctx: ToolContext,
): Promise<void> {
if (!ctx.garnetClient || !ctx.session) {
return;
}
const nextSession = {
...ctx.session,
discordMemberId: memberId,
};
const key = `${getOnboardingSessionKeyPrefix()}:onboarding:${nextSession.chatroomId}:${nextSession.userId}`;
await ctx.garnetClient.setJson(key, nextSession);
ctx.session.discordMemberId = memberId;
}
export const verifyDiscordNicknameTool: Tool<
z.infer<typeof argsSchema>,
z.infer<typeof resultSchema>
> = {
name: "verify-discord-nickname",
description:
"현재 유저의 카카오톡 인증 닉네임과 세션 입장 시각을 기준으로 디스코드 멤버를 찾아, 닉네임 변경이 확인됐는지 구조화해서 반환한다.",
argsSchema,
resultSchema,
async execute(_args, ctx) {
const logger = getRequestLogger();
if (!ctx.session) {
logger.debug("[VerifyDiscordNickname] Missing session in tool context");
return {
status: "lookup-unavailable" as const,
message: "세션 정보를 찾을 수 없어서 디스코드 닉네임을 조회할 수 없어요.",
reason: "missing-session" as const,
};
}
const expectedNickname = getKakaotalkNickname(ctx.session).trim();
logger.debug(
{
expectedNickname,
joinedAt: ctx.session.joinedAt,
nicknameVerified: ctx.session.nicknameVerified,
photoVerified: ctx.session.photoVerified,
},
"[VerifyDiscordNickname] Starting verification",
);
const issues = analyzeNicknameIssues(expectedNickname);
if (issues.length > 0) {
logger.debug(
{
expectedNickname,
issueMessages: issues.map((issue) => issue.message),
},
"[VerifyDiscordNickname] Nickname format invalid",
);
return {
status: "invalid-nickname-format" as const,
message: `카카오톡 닉네임 형식이 올바르지 않아요. ${NICKNAME_FORMAT_TEXT}`,
expectedNickname,
formatExample: NICKNAME_FORMAT_EXAMPLE,
guidance: NICKNAME_FORMAT_TEXT,
issueMessages: issues.map((issue) => issue.message),
};
}
const parsedKakaoNickname = parseKakaoNickname(expectedNickname);
const searchName = parsedKakaoNickname?.baseName ?? "";
if (!searchName) {
logger.debug(
{
expectedNickname,
},
"[VerifyDiscordNickname] Failed to derive search name",
);
return {
status: "lookup-unavailable" as const,
message: "닉네임에서 검색할 이름을 추출할 수 없어서 디스코드 조회가 불가능해요.",
reason: "missing-search-name" as const,
expectedNickname,
};
}
if (!ctx.natsClient) {
logger.debug(
{
expectedNickname,
searchName,
},
"[VerifyDiscordNickname] Missing NATS client in tool context",
);
return {
status: "lookup-unavailable" as const,
message: "지금은 디스코드 서버 조회가 불가능해요. 잠시 후 다시 시도해주세요.",
reason: "lookup-error" as const,
expectedNickname,
searchName,
};
}
const timeoutMs = resolveTimeoutMs();
if (!timeoutMs) {
logger.debug(
{
expectedNickname,
searchName,
},
"[VerifyDiscordNickname] No timeout budget left for lookup",
);
return {
status: "lookup-unavailable" as const,
message: "응답 시간이 부족해서 디스코드 조회를 건너뛰었어요. 다시 물어봐 주세요.",
reason: "request-budget-exhausted" as const,
expectedNickname,
searchName,
};
}
let lookupResult: DiscordMemberLookupResponse;
try {
const payload: DiscordMemberLookupRequest = {
chatroomId: ctx.chatroomId ?? ctx.session.chatroomId,
joinedAfter: ctx.session.joinedAt,
searchName,
userId: ctx.userId ?? ctx.session.userId,
};
logger.debug(
{
payload,
subject: getDiscordMemberLookupSubject(),
timeoutMs,
},
"[VerifyDiscordNickname] Sending lookup request",
);
lookupResult = await ctx.natsClient.request<
DiscordMemberLookupRequest,
DiscordMemberLookupResponse
>(getDiscordMemberLookupSubject(), payload, {
timeoutMs,
});
} catch {
logger.debug(
{
expectedNickname,
searchName,
},
"[VerifyDiscordNickname] Lookup request failed",
);
return {
status: "lookup-unavailable" as const,
message: "디스코드 서버 조회 중 오류가 발생했어요. 잠시 후 다시 시도해주세요.",
reason: "lookup-error" as const,
expectedNickname,
searchName,
};
}
if (lookupResult.status === "error") {
logger.debug(
{
expectedNickname,
reason: lookupResult.reason,
searchName,
},
"[VerifyDiscordNickname] Lookup service returned error",
);
return {
status: "lookup-unavailable" as const,
message: "디스코드 서버에서 오류가 반환됐어요. 잠시 후 다시 시도해주세요.",
reason: "lookup-error" as const,
expectedNickname,
searchName,
};
}
const nicknameMatches = lookupResult.nicknameMatches;
const joinedAfterMatches = lookupResult.joinedAfterMatches;
logger.debug(
{
expectedNickname,
joinedAfterMatches: joinedAfterMatches.length,
nicknameMatches: nicknameMatches.length,
searchName,
},
"[VerifyDiscordNickname] Lookup response received",
);
let candidate: DiscordMemberCandidate | null = null;
let matchSource: "joined-after" | "nickname" | undefined;
let reason:
| "joined-after-ambiguous"
| "joined-after-none"
| "nickname-search-ambiguous"
| "nickname-search-none"
| undefined;
if (nicknameMatches.length === 1) {
candidate = nicknameMatches[0] ?? null;
matchSource = "nickname";
} else if (nicknameMatches.length > 1) {
reason = "nickname-search-ambiguous";
} else if (joinedAfterMatches.length === 1) {
candidate = joinedAfterMatches[0] ?? null;
matchSource = "joined-after";
} else {
reason =
joinedAfterMatches.length === 0
? "joined-after-none"
: "joined-after-ambiguous";
}
if (!candidate) {
logger.debug(
{
expectedNickname,
joinedAfterMatchCount: joinedAfterMatches.length,
nicknameMatchCount: nicknameMatches.length,
reason:
reason ??
(nicknameMatches.length === 0
? "nickname-search-none"
: "nickname-search-ambiguous"),
searchName,
},
"[VerifyDiscordNickname] Verification not confirmed",
);
return {
status: "not-confirmed" as const,
message: `디스코드 서버에서 "${searchName}" 닉네임을 찾을 수 없었어요. 디스코드 서버에 가입했는지, 닉네임이 올바른지 확인해주세요.`,
reason:
reason ??
(nicknameMatches.length === 0
? "nickname-search-none"
: "nickname-search-ambiguous"),
expectedNickname,
searchName,
joinedAfterMatchCount: joinedAfterMatches.length,
nicknameMatchCount: nicknameMatches.length,
};
}
await persistDiscordMemberId(candidate.memberId, ctx);
const currentDisplayName = pickDisplayName(candidate);
const currentGuildNickname = candidate.guildNickname?.trim();
const isRenamed = matchesDiscordNicknameRule(
currentGuildNickname,
expectedNickname,
);
const status = isRenamed ? "matched-renamed" : "matched-pending-rename";
const message = isRenamed
? "디스코드 서버 닉네임이 올바른 형식으로 설정되어 있어요. 확인 완료!"
: currentGuildNickname
? `디스코드에서 유저를 찾았지만 서버 닉네임이 아직 올바른 형식으로 확인되지는 않았어요. 현재 서버 닉네임은 "${currentGuildNickname}"으로 보여요. 이름#태그/출생연도/티어 형식인지 확인해주세요.`
: `디스코드에서 유저를 찾았지만 서버 닉네임이 아직 설정되지 않았거나 확인되지 않았어요. 현재 표시 이름은 "${currentDisplayName}"으로 보여요. 서버 닉네임이 이름#태그/출생연도/티어 형식인지 확인해주세요.`;
logger.debug(
{
currentDisplayName,
discordMemberId: candidate.memberId,
expectedNickname,
matchSource,
matchedBy: candidate.matchedBy,
status,
},
"[VerifyDiscordNickname] Verification resolved",
);
return {
status,
message,
currentDisplayName,
discordMemberId: candidate.memberId,
expectedNickname,
matchSource,
matchedBy: candidate.matchedBy,
searchName,
};
},
};
+2
View File
@@ -1,10 +1,12 @@
import type { GarnetClient } from "@common/garnet";
import type { NatsClient } from "@common/nats";
import type { RoomContextService } from "@room/room-context-service";
import type { ZodType } from "zod";
import type { OnboardingSession } from "@skills/onboarding/types";
export interface ToolContext {
chatroomId?: string | undefined;
natsClient?: Pick<NatsClient, "request"> | undefined;
userId?: string | undefined;
session?: OnboardingSession | null | undefined;
garnetClient?: GarnetClient | undefined;