@cartanova/qgrid-cli 2.6.6 → 2.6.8

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

@@ -0,0 +1,263 @@
+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.schema";
+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,
+        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 };
+  }
+}
+
+export const SettingModel = new SettingModelClass();

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

@@ -0,0 +1,80 @@
+import { describe, expect, it } from "vitest";
+
+import { findSettingDef, maskSecret, SETTING_DEFS, validateSettingValue } from "./setting.schema";
+
+describe("validateSettingValue", () => {
+  const intDef = findSettingDef("openai.maxWorkersPerToken")!;
+  const boolDef = findSettingDef("openai.autoscale")!;
+  const numDef = findSettingDef("openai.maxEstimatedRssGiB")!;
+
+  it("정수 범위를 벗어나면 거부한다", () => {
+    // 저장을 막지 않으면 런타임에서 조용히 기본값으로 떨어져 원인을 찾기 어렵다.
+    expect(validateSettingValue(intDef, "21")).toMatchObject({ ok: false });
+    expect(validateSettingValue(intDef, "0")).toMatchObject({ ok: false });
+    expect(validateSettingValue(intDef, "20")).toMatchObject({ ok: true, value: "20" });
+  });
+
+  it("정수 자리에 소수를 넣으면 거부한다", () => {
+    expect(validateSettingValue(intDef, "3.5")).toMatchObject({ ok: false });
+  });
+
+  it("숫자가 아닌 값을 거부한다", () => {
+    expect(validateSettingValue(intDef, "많이")).toMatchObject({ ok: false });
+  });
+
+  it("실수 설정은 소수를 허용한다", () => {
+    expect(validateSettingValue(numDef, "16.5")).toMatchObject({ ok: true, value: "16.5" });
+  });
+
+  it("boolean 은 true/false 만 받는다", () => {
+    expect(validateSettingValue(boolDef, "true")).toMatchObject({ ok: true });
+    expect(validateSettingValue(boolDef, "false")).toMatchObject({ ok: true });
+    expect(validateSettingValue(boolDef, "1")).toMatchObject({ ok: false });
+  });
+
+  it("앞뒤 공백은 저장 전에 떨어뜨린다", () => {
+    expect(validateSettingValue(intDef, "  7  ")).toMatchObject({ ok: true, value: "7" });
+  });
+});
+
+describe("maskSecret", () => {
+  it("긴 값은 앞뒤만 남긴다", () => {
+    expect(maskSecret("xoxb-1234567890-abcdefghij")).toBe("xoxb-123...ghij");
+  });
+
+  it("짧은 값은 통째로 가린다", () => {
+    // 앞뒤를 남기면 짧은 값은 사실상 전부 노출된다.
+    expect(maskSecret("short")).toBe("***");
+  });
+});
+
+describe("SETTING_DEFS", () => {
+  it("키가 중복되지 않는다", () => {
+    const keys = SETTING_DEFS.map((d) => d.key);
+    expect(new Set(keys).size).toBe(keys.length);
+  });
+
+  it("env 키도 중복되지 않는다", () => {
+    // 겹치면 한 env 를 두 설정이 서로 덮어쓴다.
+    const envKeys = SETTING_DEFS.map((d) => d.envKey);
+    expect(new Set(envKeys).size).toBe(envKeys.length);
+  });
+
+  it("정의되지 않은 키는 찾지 못한다", () => {
+    expect(findSettingDef("nope.bad")).toBeUndefined();
+  });
+
+  it("64 GiB 호스트 기준 메모리 설정의 오입력 상한을 둔다", () => {
+    const rss = findSettingDef("openai.maxEstimatedRssGiB")!;
+    const available = findSettingDef("openai.minHostAvailableGiB")!;
+
+    expect(rss.max).toBe(32);
+    expect(available.max).toBe(64);
+    expect(validateSettingValue(rss, "32")).toMatchObject({ ok: true });
+    expect(validateSettingValue(rss, "32.5")).toMatchObject({ ok: false });
+    expect(validateSettingValue(available, "64")).toMatchObject({ ok: true });
+    expect(validateSettingValue(available, "64.5")).toMatchObject({ ok: false });
+    expect(rss.help).toContain("OOM");
+    expect(available.help).toContain("오토스케일");
+  });
+});

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

@@ -0,0 +1,174 @@
+/**
+ * 관리 가능한 런타임 설정 목록.
+ *
+ * 키·env 이름·타입·검증을 한 곳에 모아 API 와 UI 가 같은 정의를 본다. 여기 없는 env 는
+ * 화면에서 바꿀 수 없다 — DB 접속 정보나 포트처럼 서버가 뜨기 전에 필요한 값들이다.
+ */
+
+export type SettingKind = "boolean" | "integer" | "number" | "string" | "secret";
+
+/** 화면에서 묶어 보여줄 단위. 9개를 평평하게 나열하면 어디를 봐야 할지 알 수 없다. */
+export type SettingGroup = "openai" | "slack";
+
+export type SettingDef = {
+  key: string;
+  group: SettingGroup;
+  envKey: string;
+  label: string;
+  kind: SettingKind;
+  /** 적용 시점. 워커 설정은 dispatcher 생성자에서 한 번만 읽혀 재시작이 필요하다. */
+  applies: "immediate" | "restart";
+  min?: number;
+  max?: 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.expiryReminderMinutes",
+    fallback: "0",
+    group: "slack",
+    envKey: "SLACK_EXPIRY_REMINDER_INTERVAL_MINUTES",
+    label: "만료 알림 반복 주기 (분)",
+    kind: "integer",
+    applies: "immediate",
+    min: 0,
+    max: 1440,
+    help: "0 이면 반복 알림을 끕니다",
+  },
+  {
+    key: "slack.channelId",
+    fallback: "",
+    group: "slack",
+    envKey: "SLACK_CHANNEL_ID",
+    label: "Slack 채널 ID",
+    kind: "string",
+    applies: "immediate",
+    help: "사용자 ID(U...)를 넣으면 그 사람 DM 으로 갑니다",
+  },
+  {
+    key: "slack.userMap",
+    fallback: "",
+    group: "slack",
+    envKey: "SLACK_USER_MAP",
+    label: "Slack 사용자 매핑",
+    kind: "string",
+    applies: "immediate",
+    help: "토큰명:SlackUserId 를 쉼표로. 공용 계정은 넣지 않습니다",
+  },
+  {
+    key: "slack.botToken",
+    fallback: "",
+    group: "slack",
+    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 === "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.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();
+  });
+});

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

@@ -0,0 +1,85 @@
+/**
+ * 런타임 설정 조회 캐시.
+ *
+ * 값의 출처는 DB(`settings`) → env 순이다. env 를 남겨두는 이유는 전환 때문이다 — dev0 는
+ * `ecosystem.config.json` 으로 값을 주입하는데, DB 만 보게 만들면 배포 직후 설정이 전부
+ * 기본값으로 떨어진다.
+ *
+ * 설정은 요청 경로(워커 스케일링, 알림 전송)에서 읽히므로 매번 DB 를 때리지 않고 메모리에
+ * 둔다. `immediate` 변경도 현재 API 프로세스에만 즉시 반영된다. 인스턴스가 여러 개면 다른
+ * 인스턴스의 캐시는 갱신되지 않으며, 이 범위에서는 프로세스 간 전파를 두지 않는다.
+ */
+import { getLogger } from "@logtape/logtape";
+
+import { SettingModel } from "./setting.model";
+
+const logger = getLogger(["qgrid", "setting"]);
+
+/** 로드 전에는 null 이라 전부 env 로 떨어진다. */
+let cache: Map<string, string> | null = null;
+
+type SettingChangeHandler = (key: string) => void;
+export type SettingPersistence = Pick<
+  typeof SettingModel,
+  "clearByKey" | "findAllAsMap" | "setByKey"
+>;
+let settingChangeHandler: SettingChangeHandler | null = null;
+
+/**
+ * 런타임 소비자는 상위 조립 계층에서 하나만 등록한다. handler 는 동기 작업만 해야 하며,
+ * 실패해도 이미 성공한 DB 저장을 실패로 바꾸지 않는다.
+ */
+export function setSettingChangeHandler(handler: SettingChangeHandler | null): void {
+  settingChangeHandler = handler;
+}
+
+function notifySettingChanged(key: string): void {
+  try {
+    settingChangeHandler?.(key);
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    logger.warn(`setting change handler failed for ${key}: ${message}`);
+  }
+}
+
+export async function loadSettings(persistence: SettingPersistence = SettingModel): Promise<void> {
+  try {
+    cache = await persistence.findAllAsMap();
+    logger.info(`settings loaded: ${cache.size} stored`);
+  } catch (e) {
+    // 테이블이 아직 없는 배포(마이그레이션 전)에서도 서버는 떠야 한다.
+    cache = new Map();
+    logger.warn(`settings load failed, using env only: ${(e as Error).message}`);
+  }
+}
+
+/** DB → env 순. 둘 다 없으면 undefined 라 호출부의 기본값으로 떨어진다. */
+export function getSetting(key: string, envKey: string): string | undefined {
+  return cache?.get(key) ?? process.env[envKey];
+}
+
+/** 저장된 값인지 — 화면에서 출처를 구분해 보여준다. */
+export function isStored(key: string): boolean {
+  return cache?.has(key) ?? false;
+}
+
+export async function saveSetting(
+  key: string,
+  value: string,
+  persistence: SettingPersistence = SettingModel,
+): Promise<void> {
+  await persistence.setByKey(key, value);
+  cache ??= new Map();
+  cache.set(key, value);
+  notifySettingChanged(key);
+}
+
+/** 저장값을 지워 env 기본값으로 되돌린다. */
+export async function resetSetting(
+  key: string,
+  persistence: SettingPersistence = SettingModel,
+): Promise<void> {
+  await persistence.clearByKey(key);
+  cache?.delete(key);
+  notifySettingChanged(key);
+}