@cartanova/qgrid-cli 2.6.7 → 2.6.9

package/bundle/src/application/setting/setting.constant.ts

@@ -0,0 +1,250 @@
+/**
+ * 관리 가능한 런타임 설정 목록.
+ *
+ * 키·env 이름·타입·검증을 한 곳에 모아 API 와 UI 가 같은 정의를 본다. 여기 없는 env 는
+ * 화면에서 바꿀 수 없다 — DB 접속 정보나 포트처럼 서버가 뜨기 전에 필요한 값들이다.
+ *
+ * `settings` 테이블은 `(key, value)` 문자열 쌍만 담는 그릇이라(`setting.entity.json`),
+ * "이 키가 정수인지·범위가 얼마인지·화면에 뭐라고 쓸지"를 담을 곳이 따로 필요하다.
+ * 그 메타데이터가 여기 있다 — DB 스키마가 아니라 앱이 아는 상수 목록이다.
+ */
+
+export type SettingKind = "boolean" | "integer" | "number" | "string" | "secret" | "preset";
+
+/**
+ * 화면에서 묶어 보여줄 단위. 평평하게 나열하면 어디를 봐야 할지 알 수 없다.
+ *
+ * Slack 은 "언제 보낼까"(slack)와 "어디로 보낼까"(slackConnection)를 나눈다 — 앞은 운영
+ * 중 자주 만지고 뒤는 한 번 맞추면 끝이라 수명이 다르다.
+ */
+export type SettingGroup = "openai" | "slack" | "slackConnection";
+
+export type SettingDef = {
+  key: string;
+  group: SettingGroup;
+  envKey: string;
+  label: string;
+  kind: SettingKind;
+  /** 적용 시점. 워커 설정은 dispatcher 생성자에서 한 번만 읽혀 재시작이 필요하다. */
+  applies: "immediate" | "restart";
+  min?: number;
+  max?: number;
+  /** `preset` 종류에서 고를 수 있는 값. 이 목록 밖의 값은 저장되지 않는다. */
+  presets?: number[];
+  /**
+   * 저장값도 env 도 없을 때 실제로 적용되는 값. 화면을 비워두면 "설정 안 됨"으로 읽히지만
+   * 실제로는 이 값이 돌고 있다 — 소비처의 기본값과 반드시 같아야 한다.
+   */
+  fallback: string;
+  help?: string;
+};
+
+/** 64 GiB 운영 호스트에서 세 자리 오입력을 막는 설정 상한. 안전을 보장하는 값은 아니다. */
+export const MAX_OPENAI_ESTIMATED_RSS_GIB = 32;
+export const MAX_OPENAI_MIN_HOST_AVAILABLE_GIB = 64;
+
+export const SETTING_DEFS: SettingDef[] = [
+  {
+    key: "openai.autoscale",
+    fallback: "true",
+    group: "openai",
+    envKey: "QGRID_OPENAI_AUTOSCALE",
+    label: "OpenAI 워커 오토스케일",
+    kind: "boolean",
+    applies: "restart",
+    help: "끄면 워커 수가 최소값으로 고정됩니다",
+  },
+  {
+    key: "openai.minWorkersPerToken",
+    fallback: "1",
+    group: "openai",
+    envKey: "QGRID_OPENAI_MIN_WORKERS_PER_TOKEN",
+    label: "토큰당 최소 워커",
+    kind: "integer",
+    applies: "restart",
+    min: 1,
+    max: 20,
+  },
+  {
+    key: "openai.maxWorkersPerToken",
+    fallback: "3",
+    group: "openai",
+    envKey: "QGRID_OPENAI_MAX_WORKERS_PER_TOKEN",
+    label: "토큰당 최대 워커",
+    kind: "integer",
+    applies: "restart",
+    min: 1,
+    max: 20,
+    help: "오토스케일이 꺼져 있으면 무시됩니다",
+  },
+  {
+    key: "openai.maxEstimatedRssGiB",
+    fallback: "16",
+    group: "openai",
+    envKey: "QGRID_OPENAI_MAX_ESTIMATED_RSS_GIB",
+    label: "워커 메모리 상한 (GiB)",
+    kind: "number",
+    applies: "restart",
+    min: 1,
+    max: MAX_OPENAI_ESTIMATED_RSS_GIB,
+    help: "이 추정치를 넘기면 워커를 더 늘리지 않습니다. 올릴수록 OOM 위험이 커지며 상한은 오입력 방지용입니다",
+  },
+  {
+    key: "openai.minHostAvailableGiB",
+    fallback: "20",
+    group: "openai",
+    envKey: "QGRID_OPENAI_MIN_HOST_AVAILABLE_GIB",
+    label: "호스트 여유 메모리 하한 (GiB)",
+    kind: "number",
+    applies: "restart",
+    min: 0,
+    max: MAX_OPENAI_MIN_HOST_AVAILABLE_GIB,
+    help: "호스트 여유가 이 값 아래면 스케일업을 멈춥니다. 확장을 끄려면 오토스케일을 끄세요",
+  },
+  {
+    key: "slack.enabled",
+    fallback: "true",
+    group: "slack",
+    envKey: "SLACK_ENABLED",
+    label: "Slack 알림",
+    kind: "boolean",
+    applies: "immediate",
+    help: "연휴처럼 규칙으로 잡을 수 없는 기간에 끕니다. 서비스 정지급 장애 알림은 꺼도 전달됩니다",
+  },
+  {
+    key: "slack.remindersEnabled",
+    fallback: "true",
+    group: "slack",
+    envKey: "SLACK_REMINDERS_ENABLED",
+    label: "만료 알림 반복",
+    kind: "boolean",
+    applies: "immediate",
+    help: "끄면 반복만 멈추고 만료 순간의 알림은 그대로 갑니다",
+  },
+  {
+    key: "slack.expiryReminderMinutes",
+    fallback: "60",
+    group: "slack",
+    envKey: "SLACK_EXPIRY_REMINDER_INTERVAL_MINUTES",
+    label: "반복 주기",
+    kind: "preset",
+    applies: "immediate",
+    // 자유 입력 대신 고정 선택지를 쓴다 — "얼마나 자주 재촉할까"라서 1분 단위 정밀도가
+    // 의미 없고, 잘못 넣으면 채널이 시끄러워진다. 끄는 것은 remindersEnabled 가 맡는다.
+    presets: [10, 30, 60, 180],
+    help: "재로그인이 필요한 토큰이 남아 있는 동안 이 주기로 다시 알립니다",
+  },
+  {
+    key: "slack.quietFromHour",
+    fallback: "20",
+    group: "slack",
+    envKey: "SLACK_QUIET_FROM_HOUR",
+    label: "조용 시간 시작",
+    kind: "integer",
+    applies: "immediate",
+    min: 0,
+    max: 23,
+    help: "이 시각부터 알리지 않습니다 (한국 시간)",
+  },
+  {
+    key: "slack.quietUntilHour",
+    fallback: "8",
+    group: "slack",
+    envKey: "SLACK_QUIET_UNTIL_HOUR",
+    label: "조용 시간 종료",
+    kind: "integer",
+    applies: "immediate",
+    min: 0,
+    max: 23,
+    help: "이 시각부터 다시 알립니다. 시작보다 빠르면 자정을 넘는 구간이 됩니다",
+  },
+  {
+    key: "slack.notifyOnWeekends",
+    fallback: "false",
+    group: "slack",
+    envKey: "SLACK_NOTIFY_ON_WEEKENDS",
+    label: "주말에도 알림",
+    kind: "boolean",
+    applies: "immediate",
+    help: "켜면 주말에도 위의 조용 시간 규칙만 적용됩니다",
+  },
+  {
+    key: "slack.channelId",
+    fallback: "",
+    group: "slackConnection",
+    envKey: "SLACK_CHANNEL_ID",
+    label: "Slack 채널 ID",
+    kind: "string",
+    applies: "immediate",
+    help: "사용자 ID(U...)를 넣으면 그 사람 DM 으로 갑니다",
+  },
+  {
+    key: "slack.userMap",
+    fallback: "",
+    group: "slackConnection",
+    envKey: "SLACK_USER_MAP",
+    label: "Slack 사용자 매핑",
+    kind: "string",
+    applies: "immediate",
+    help: "토큰명:SlackUserId 를 쉼표로. 공용 계정은 넣지 않습니다",
+  },
+  {
+    key: "slack.botToken",
+    fallback: "",
+    group: "slackConnection",
+    envKey: "SLACK_BOT_TOKEN",
+    label: "Slack 봇 토큰",
+    kind: "secret",
+    applies: "immediate",
+  },
+];
+
+export function findSettingDef(key: string): SettingDef | undefined {
+  return SETTING_DEFS.find((d) => d.key === key);
+}
+
+/** 저장 전 검증. 잘못된 값이 들어가면 런타임에서 조용히 기본값으로 떨어져 원인을 찾기 어렵다. */
+export function validateSettingValue(
+  def: SettingDef,
+  raw: string,
+): { ok: true; value: string } | { ok: false; error: string } {
+  const trimmed = raw.trim();
+
+  if (def.kind === "boolean") {
+    if (!["true", "false"].includes(trimmed)) return { ok: false, error: "true 또는 false" };
+    return { ok: true, value: trimmed };
+  }
+
+  if (def.kind === "preset") {
+    // 화면은 버튼만 주지만 API 는 아무 값이나 받을 수 있다. 목록 밖의 값이 들어오면
+    // 화면에서 아무 버튼도 선택돼 보이지 않아 "왜 안 바뀌지"가 된다.
+    const parsed = Number(trimmed);
+    if (!def.presets?.includes(parsed)) {
+      return { ok: false, error: `${def.presets?.join(", ") ?? ""} 중 하나여야 합니다` };
+    }
+    return { ok: true, value: String(parsed) };
+  }
+
+  if (def.kind === "integer" || def.kind === "number") {
+    const parsed = Number(trimmed);
+    if (!Number.isFinite(parsed)) return { ok: false, error: "숫자를 입력하세요" };
+    if (def.kind === "integer" && !Number.isInteger(parsed)) {
+      return { ok: false, error: "정수를 입력하세요" };
+    }
+    if (def.min !== undefined && parsed < def.min) {
+      return { ok: false, error: `${def.min} 이상이어야 합니다` };
+    }
+    if (def.max !== undefined && parsed > def.max) {
+      return { ok: false, error: `${def.max} 이하여야 합니다` };
+    }
+    return { ok: true, value: String(parsed) };
+  }
+
+  return { ok: true, value: trimmed };
+}
+
+/** 화면에 그대로 내려보내면 안 되는 값. 앞뒤만 남긴다. */
+export function maskSecret(value: string): string {
+  if (value.length <= 12) return "***";
+  return `${value.slice(0, 8)}...${value.slice(-4)}`;
+}

package/bundle/src/application/setting/setting.entity.json

@@ -0,0 +1,59 @@
+{
+  "id": "Setting",
+  "table": "settings",
+  "title": "Setting",
+  "props": [
+    {
+      "name": "id",
+      "type": "integer",
+      "desc": "ID"
+    },
+    {
+      "name": "created_at",
+      "desc": "등록일시",
+      "dbDefault": "CURRENT_TIMESTAMP",
+      "type": "date"
+    },
+    {
+      "name": "key",
+      "type": "string",
+      "length": 100,
+      "desc": "설정 키 (예: openai.maxWorkersPerToken)",
+      "toFilter": true
+    },
+    {
+      "name": "value",
+      "type": "string",
+      "desc": "설정 값 (문자열 저장, 앱에서 파싱·검증)"
+    },
+    {
+      "name": "updated_at",
+      "type": "date",
+      "nullable": true,
+      "desc": "최종 수정일시"
+    }
+  ],
+  "indexes": [
+    {
+      "type": "unique",
+      "name": "settings_key_unique",
+      "columns": [
+        {
+          "name": "key"
+        }
+      ],
+      "using": "btree"
+    }
+  ],
+  "subsets": {
+    "A": ["id", "created_at", "key", "value", "updated_at"]
+  },
+  "enums": {
+    "SettingOrderBy": {
+      "key-asc": "키순"
+    },
+    "SettingSearchField": {
+      "key": "키"
+    }
+  }
+}

package/bundle/src/application/setting/setting.model.ts

@@ -0,0 +1,277 @@
+import {
+  BaseModelClass,
+  type ListResult,
+  asArray,
+  NotFoundException,
+  BadRequestException,
+  api,
+  exhaustive,
+} from "sonamu";
+
+import { SD } from "../../i18n/sd.generated";
+import { type SettingSubsetKey, type SettingSubsetMapping } from "../sonamu.generated";
+import { settingSubsetQueries, settingLoaderQueries } from "../sonamu.generated.sso";
+import { findSettingDef, maskSecret, SETTING_DEFS, validateSettingValue } from "./setting.constant";
+import {
+  getSetting,
+  isStored,
+  resetSetting as resetStoredSetting,
+  saveSetting as saveStoredSetting,
+} from "./setting.store";
+import {
+  type RuntimeInfoItem,
+  type SettingApplies,
+  type SettingItem,
+  type SettingListParams,
+  type SettingSaveParams,
+  type SettingsResponse,
+} from "./setting.types";
+
+/*
+  Setting Model
+*/
+class SettingModelClass extends BaseModelClass<
+  SettingSubsetKey,
+  SettingSubsetMapping,
+  typeof settingSubsetQueries,
+  typeof settingLoaderQueries
+> {
+  constructor() {
+    super("Setting", settingSubsetQueries, settingLoaderQueries);
+  }
+
+  @api({ httpMethod: "GET", clients: ["axios", "tanstack-query"], resourceName: "Setting" })
+  async findById<T extends SettingSubsetKey>(
+    subset: T,
+    id: number,
+  ): Promise<SettingSubsetMapping[T]> {
+    const { rows } = await this.findMany(subset, {
+      id,
+      num: 1,
+      page: 1,
+    });
+    if (!rows[0]) {
+      throw new NotFoundException(SD("error.entityNotFound")("Setting", id));
+    }
+
+    return rows[0];
+  }
+
+  async findOne<T extends SettingSubsetKey>(
+    subset: T,
+    listParams: SettingListParams,
+  ): Promise<SettingSubsetMapping[T] | null> {
+    const { rows } = await this.findMany(subset, {
+      ...listParams,
+      num: 1,
+      page: 1,
+    });
+
+    return rows[0] ?? null;
+  }
+
+  @api({ httpMethod: "GET", clients: ["axios", "tanstack-query"], resourceName: "Settings" })
+  async findMany<T extends SettingSubsetKey, LP extends SettingListParams>(
+    subset: T,
+    rawParams?: LP,
+  ): Promise<ListResult<LP, SettingSubsetMapping[T]>> {
+    // params with defaults
+    const params = {
+      num: 24,
+      page: 1,
+      search: "key" as const,
+      orderBy: "key-asc" as const,
+      ...rawParams,
+    } satisfies SettingListParams;
+
+    // build queries
+    const { qb, onSubset: _ } = this.getSubsetQueries(subset);
+
+    // id
+    if (params.id) {
+      qb.whereIn("settings.id", asArray(params.id));
+    }
+
+    // key — toFilter prop 이지만 스캐폴딩이 만들어주지 않아 직접 건다.
+    if (params.key) {
+      qb.where("settings.key", params.key);
+    }
+
+    // search-keyword
+    if (params.search && params.keyword && params.keyword.length > 0) {
+      if (params.search === "key") {
+        qb.where("settings.key", "like", `%${params.keyword}%`);
+      } else {
+        throw new BadRequestException(SD("error.unknownSearchField")(params.search));
+      }
+    }
+
+    // orderBy
+    if (params.orderBy) {
+      // default orderBy
+      if (params.orderBy === "key-asc") {
+        qb.orderBy("settings.key", "asc");
+      } else {
+        exhaustive(params.orderBy);
+      }
+    }
+
+    const enhancers = this.createEnhancers({
+      A: (row) => ({
+        ...row,
+        // 서브셋별로 virtual 필드 계산로직 추가
+      }),
+    });
+
+    return this.executeSubsetQuery({
+      subset,
+      qb,
+      params,
+      enhancers,
+      debug: false,
+    });
+  }
+
+  async save(spa: SettingSaveParams[]): Promise<number[]> {
+    const wdb = this.getPuri("w");
+
+    // register
+    spa.forEach((sp) => {
+      wdb.ubRegister("settings", sp);
+    });
+
+    // transaction
+    return wdb.transaction(async (trx) => {
+      const ids = await trx.ubUpsert("settings");
+
+      return ids;
+    });
+  }
+
+  async del(ids: number[]): Promise<number> {
+    const wdb = this.getPuri("w");
+
+    // transaction
+    await wdb.transaction(async (trx) => {
+      return trx.table("settings").whereIn("settings.id", ids).delete();
+    });
+
+    return ids.length;
+  }
+
+  /** 저장된 설정 전체를 key→value 로. 부팅 시 한 번 읽어 메모리에 올린다. */
+  async findAllAsMap(): Promise<Map<string, string>> {
+    const { rows } = await this.findMany("A", { num: 0, page: 1 });
+    return new Map(rows.map((r) => [r.key, r.value]));
+  }
+
+  /**
+   * key 로 upsert 한다. `save` 는 id 기준이라 key 중복을 걸러내지 못해, 기존 행을 먼저 찾아
+   * id 를 실어 보낸다.
+   */
+  async setByKey(key: string, value: string): Promise<void> {
+    const existing = await this.findOne("A", { key, num: 1, page: 1 });
+    await this.save([
+      {
+        ...(existing ? { id: existing.id } : {}),
+        key,
+        value,
+        updated_at: new Date(),
+      },
+    ]);
+  }
+
+  /** 저장값을 지워 env 기본값으로 되돌린다. */
+  async clearByKey(key: string): Promise<void> {
+    const existing = await this.findOne("A", { key, num: 1, page: 1 });
+    if (existing) await this.del([existing.id]);
+  }
+
+  /**
+   * 편집 가능한 설정과 읽기 전용 런타임 정보. 편집 대상은 `SETTING_DEFS` 에 정의된 것뿐이다 —
+   * DB 접속 정보나 포트는 서버가 뜨기 전에 필요해 화면에서 바꿀 수 없다.
+   */
+  @api({ httpMethod: "GET", clients: ["axios", "tanstack-query"], resourceName: "SettingList" })
+  async listSettings(): Promise<SettingsResponse> {
+    const settings: SettingItem[] = SETTING_DEFS.map((def) => {
+      // 저장값도 env 도 없으면 코드 기본값이 실제로 적용 중이다. 빈칸으로 두면 화면과
+      // 런타임이 어긋나 보인다.
+      const stored = isStored(def.key);
+      const raw = getSetting(def.key, def.envKey);
+      const effective = raw ?? def.fallback;
+      const source = stored ? "db" : raw !== undefined ? "env" : "default";
+
+      return {
+        key: def.key,
+        group: def.group,
+        label: def.label,
+        kind: def.kind,
+        applies: def.applies,
+        // 눈 토글을 위해 secret 도 원본을 내려보낸다. 이 엔드포인트는 배포 경계에서 인증해야
+        // 하며, dev0 는 Caddy 인증을 통과한 운영자만 접근할 수 있다.
+        value: effective,
+        source,
+        min: def.min ?? null,
+        max: def.max ?? null,
+        presets: def.presets ?? [],
+        help: def.help ?? null,
+      };
+    });
+
+    return { settings, runtime: this.runtimeInfo() };
+  }
+
+  private runtimeInfo(): RuntimeInfoItem[] {
+    const env = process.env;
+    const password = env.QGRID_DB_PASSWORD ?? env.SONAMU_DB_PASSWORD ?? "";
+    return [
+      { label: "NODE_ENV", value: env.NODE_ENV ?? "-" },
+      { label: "HOST", value: env.HOST ?? "localhost" },
+      { label: "PORT", value: env.PORT ?? "44900" },
+      { label: "DB Host", value: env.QGRID_DB_HOST ?? env.SONAMU_DB_HOST ?? "-" },
+      { label: "DB Port", value: env.QGRID_DB_PORT ?? env.SONAMU_DB_PORT ?? "-" },
+      { label: "DB Name", value: env.QGRID_DB_NAME ?? env.SONAMU_DB_NAME ?? "-" },
+      { label: "DB User", value: env.QGRID_DB_USER ?? env.SONAMU_DB_USER ?? "-" },
+      { label: "DB Password", value: password ? maskSecret(password) : "-" },
+    ];
+  }
+
+  @api({ httpMethod: "POST", clients: ["axios", "tanstack-mutation"] })
+  async updateSetting(key: string, value: string): Promise<{ applies: SettingApplies }> {
+    const def = findSettingDef(key);
+    if (!def) throw new BadRequestException(SD("setting.unknownKey")(key));
+
+    const validation = validateSettingValue(def, value);
+    if (!validation.ok) {
+      throw new BadRequestException(SD("setting.invalidValue")(validation.error));
+    }
+
+    await saveStoredSetting(key, validation.value);
+    return { applies: def.applies };
+  }
+
+  /** 저장값을 지워 env 기본값으로 되돌린다. */
+  @api({ httpMethod: "POST", clients: ["axios", "tanstack-mutation"] })
+  async resetSetting(key: string): Promise<{ applies: SettingApplies }> {
+    const def = findSettingDef(key);
+    if (!def) throw new BadRequestException(SD("setting.unknownKey")(key));
+
+    await resetStoredSetting(key);
+    return { applies: def.applies };
+  }
+
+  /**
+   * 만료 알림을 지금 한 번 보낸다. 주기를 기다리지 않고 설정이 제대로 붙었는지 확인하거나,
+   * 재로그인을 재촉할 때 쓴다. 보낸 건수를 돌려줘 "보낼 대상 없음"과 구분한다.
+   */
+  @api({ httpMethod: "POST", clients: ["axios", "tanstack-mutation"] })
+  async triggerExpiryReminder(): Promise<{ sent: number }> {
+    // 동적 import 로 알림 모듈을 호출 시점에만 끌어온다. 정적으로 걸면
+    // setting.model → expired-token-reminder → token.model 경로가 생겨,
+    // token.model 을 mock 하는 테스트가 실제 모듈을 먼저 로드하게 된다.
+    const { sendExpiredTokenReminderNow } = await import("../qgrid/expired-token-reminder");
+    return { sent: await sendExpiredTokenReminderNow() };
+  }
+}
+
+export const SettingModel = new SettingModelClass();

package/bundle/src/application/setting/setting.store.test.ts

@@ -0,0 +1,87 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import {
+  getSetting,
+  isStored,
+  loadSettings,
+  resetSetting,
+  saveSetting,
+  setSettingChangeHandler,
+} from "./setting.store";
+
+const settingModelMock = {
+  clearByKey: vi.fn(),
+  findAllAsMap: vi.fn(),
+  setByKey: vi.fn(),
+};
+
+describe("setting change handler", () => {
+  beforeEach(async () => {
+    settingModelMock.clearByKey.mockReset();
+    settingModelMock.findAllAsMap.mockReset();
+    settingModelMock.setByKey.mockReset();
+    settingModelMock.clearByKey.mockResolvedValue(undefined);
+    settingModelMock.findAllAsMap.mockResolvedValue(new Map());
+    settingModelMock.setByKey.mockResolvedValue(undefined);
+    setSettingChangeHandler(null);
+    await loadSettings(settingModelMock);
+  });
+
+  it("DB 저장과 캐시 갱신이 끝난 뒤 변경을 알린다", async () => {
+    const observed: Array<[string, string | undefined]> = [];
+    setSettingChangeHandler((key) => {
+      observed.push([key, getSetting(key, "TEST_SETTING")]);
+    });
+
+    await saveSetting("slack.userMap", "yds:U-NEW", settingModelMock);
+
+    expect(settingModelMock.setByKey).toHaveBeenCalledWith("slack.userMap", "yds:U-NEW");
+    expect(observed).toEqual([["slack.userMap", "yds:U-NEW"]]);
+  });
+
+  it("reset 후 저장값을 지운 상태로 변경을 알린다", async () => {
+    settingModelMock.findAllAsMap.mockResolvedValueOnce(
+      new Map([["slack.expiryReminderMinutes", "30"]]),
+    );
+    await loadSettings(settingModelMock);
+    const observed: boolean[] = [];
+    setSettingChangeHandler((key) => observed.push(isStored(key)));
+
+    await resetSetting("slack.expiryReminderMinutes", settingModelMock);
+
+    expect(settingModelMock.clearByKey).toHaveBeenCalledWith("slack.expiryReminderMinutes");
+    expect(observed).toEqual([false]);
+  });
+
+  it("설정 로드는 변경 이벤트를 만들지 않는다", async () => {
+    const handler = vi.fn();
+    setSettingChangeHandler(handler);
+    settingModelMock.findAllAsMap.mockResolvedValueOnce(new Map([["slack.userMap", "yds:U1"]]));
+
+    await loadSettings(settingModelMock);
+
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it("handler 실패가 이미 성공한 저장을 실패로 바꾸지 않는다", async () => {
+    setSettingChangeHandler(() => {
+      throw new Error("reschedule failed");
+    });
+
+    await expect(saveSetting("slack.userMap", "yds:U1", settingModelMock)).resolves.toBeUndefined();
+    expect(getSetting("slack.userMap", "TEST_SETTING")).toBe("yds:U1");
+  });
+
+  it("DB 저장이 실패하면 캐시와 handler를 건드리지 않는다", async () => {
+    const handler = vi.fn();
+    setSettingChangeHandler(handler);
+    settingModelMock.setByKey.mockRejectedValueOnce(new Error("db failed"));
+
+    await expect(saveSetting("slack.userMap", "yds:U1", settingModelMock)).rejects.toThrow(
+      "db failed",
+    );
+
+    expect(getSetting("slack.userMap", "TEST_SETTING")).toBeUndefined();
+    expect(handler).not.toHaveBeenCalled();
+  });
+});