@cartanova/qgrid-cli 2.6.6 → 2.6.8

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

@@ -0,0 +1,51 @@
+import { z } from "zod";
+
+import { SettingBaseSchema, SettingBaseListParams } from "../sonamu.generated";
+
+// Setting - ListParams
+export const SettingListParams = SettingBaseListParams;
+export type SettingListParams = z.infer<typeof SettingListParams>;
+
+// Setting - SaveParams
+export const SettingSaveParams = SettingBaseSchema.partial({ id: true, created_at: true });
+export type SettingSaveParams = z.infer<typeof SettingSaveParams>;
+
+// ── 설정 API 응답 스키마 ──
+
+export const SettingKind = z.enum(["boolean", "integer", "number", "string", "secret"]);
+export type SettingKind = z.infer<typeof SettingKind>;
+
+export const SettingApplies = z.enum(["immediate", "restart"]);
+export type SettingApplies = z.infer<typeof SettingApplies>;
+
+export const SettingSource = z.enum(["db", "env", "default"]);
+export type SettingSource = z.infer<typeof SettingSource>;
+
+export const SettingItem = z.object({
+  key: z.string(),
+  group: z.string(),
+  label: z.string(),
+  kind: SettingKind,
+  applies: SettingApplies,
+  /** 현재 적용 중인 값. 눈 토글을 지원하기 위해 secret 도 원본으로 내려간다. */
+  value: z.string(),
+  /** 이 값이 어디서 왔는지. 화면에서 출처를 보여줘야 "왜 안 바뀌지"가 없다. */
+  source: SettingSource,
+  min: z.number().nullable(),
+  max: z.number().nullable(),
+  help: z.string().nullable(),
+});
+export type SettingItem = z.infer<typeof SettingItem>;
+
+/** 화면에서 바꿀 수 없는 기동 시점 값들 — 어떤 환경에 붙어 있는지 확인용. */
+export const RuntimeInfoItem = z.object({
+  label: z.string(),
+  value: z.string(),
+});
+export type RuntimeInfoItem = z.infer<typeof RuntimeInfoItem>;
+
+export const SettingsResponse = z.object({
+  settings: SettingItem.array(),
+  runtime: RuntimeInfoItem.array(),
+});
+export type SettingsResponse = z.infer<typeof SettingsResponse>;

package/bundle/src/application/sonamu.generated.http

@@ -70,6 +70,53 @@ Content-Type: application/json
 
 ###
 
+GET {{baseUrl}}/api/setting/findById
+	?subset=A
+	&id=0
+Content-Type: application/json
+
+###
+
+GET {{baseUrl}}/api/setting/findMany
+	?subset=A
+	&rawParams[num]=24
+	&rawParams[page]=1
+	&rawParams[search]=key
+	&rawParams[keyword]=KEYWORD
+	&rawParams[orderBy]=key-asc
+	&rawParams[queryMode]=both
+	&rawParams[id]=0
+	&rawParams[sonamuFilter]=unknown-custom
+	&rawParams[key]=KEY
+Content-Type: application/json
+
+###
+
+GET {{baseUrl}}/api/setting/listSettings
+	?
+Content-Type: application/json
+
+###
+
+POST {{baseUrl}}/api/setting/updateSetting
+Content-Type: application/json
+
+{
+  "key": "KEY",
+  "value": "VALUE"
+}
+
+###
+
+POST {{baseUrl}}/api/setting/resetSetting
+Content-Type: application/json
+
+{
+  "key": "KEY"
+}
+
+###
+
 GET {{baseUrl}}/api/requestLogStep/findById
 	?subset=A
 	&id=0

package/bundle/src/application/sonamu.generated.sso.ts

@@ -8,9 +8,11 @@ import { type PuriWrapper, type DatabaseSchemaExtend, type PuriLoaderQueries } f
 import {
   type RequestLogSubsetKey,
   type RequestLogStepSubsetKey,
+  type SettingSubsetKey,
   type TokenSubsetKey,
   type RequestLogBaseSchema,
   type RequestLogStepBaseSchema,
+  type SettingBaseSchema,
   type TokenBaseSchema,
 } from "./sonamu.generated";
 
@@ -176,6 +178,24 @@ export const requestLogStepLoaderQueries = {
   I: [],
 } as const satisfies PuriLoaderQueries<RequestLogStepSubsetKey>;
 
+// SubsetQuery: Setting
+export const settingSubsetQueries = {
+  A: (qbWrapper: PuriWrapper<DatabaseSchemaExtend>) => {
+    return qbWrapper.from("settings").select({
+      id: "settings.id",
+      created_at: "settings.created_at",
+      key: "settings.key",
+      value: "settings.value",
+      updated_at: "settings.updated_at",
+    });
+  },
+};
+
+// LoaderQuery: Setting
+export const settingLoaderQueries = {
+  A: [],
+} as const satisfies PuriLoaderQueries<SettingSubsetKey>;
+
 // SubsetQuery: Token
 export const tokenSubsetQueries = {
   A: (qbWrapper: PuriWrapper<DatabaseSchemaExtend>) => {
@@ -206,6 +226,7 @@ declare module "sonamu" {
   export interface DatabaseSchemaExtend {
     request_logs: RequestLogBaseSchema;
     request_log_steps: RequestLogStepBaseSchema;
+    settings: SettingBaseSchema;
     tokens: TokenBaseSchema;
   }
 

package/bundle/src/application/sonamu.generated.ts

@@ -127,6 +127,14 @@ export const RequestLogStepSearchField = z.enum(["id"]).describe("RequestLogStep
 export type RequestLogStepSearchField = z.infer<typeof RequestLogStepSearchField>;
 export const RequestLogStepSearchFieldLabel = { id: "ID" };
 
+// Enums: Setting
+export const SettingOrderBy = z.enum(["key-asc"]).describe("SettingOrderBy");
+export type SettingOrderBy = z.infer<typeof SettingOrderBy>;
+export const SettingOrderByLabel = { "key-asc": "키순" };
+export const SettingSearchField = z.enum(["key"]).describe("SettingSearchField");
+export type SettingSearchField = z.infer<typeof SettingSearchField>;
+export const SettingSearchFieldLabel = { key: "키" };
+
 // Enums: Token
 export const TokenOrderBy = z.enum(["id-desc", "ord-asc"]).describe("TokenOrderBy");
 export type TokenOrderBy = z.infer<typeof TokenOrderBy>;
@@ -262,6 +270,18 @@ export type RequestLogStepBaseSchema = z.infer<typeof RequestLogStepBaseSchema>
   ];
 };
 
+// BaseSchema: Setting
+export const SettingBaseSchema = z.object({
+  id: z.int(),
+  created_at: z.date(),
+  key: z.string().max(100),
+  value: z.string(),
+  updated_at: z.date().nullable(),
+});
+export type SettingBaseSchema = z.infer<typeof SettingBaseSchema> & {
+  readonly __hasDefault__: readonly ["created_at", "updated_at", "id"];
+};
+
 // BaseSchema: Token
 export const TokenBaseSchema = z.object({
   id: z.int(),
@@ -319,6 +339,22 @@ export const RequestLogStepBaseListParams = z
   .partial();
 export type RequestLogStepBaseListParams = z.infer<typeof RequestLogStepBaseListParams>;
 
+// BaseListParams: Setting
+export const SettingBaseListParams = z
+  .object({
+    num: z.number().int().nonnegative(),
+    page: z.number().int().min(1),
+    search: SettingSearchField,
+    keyword: z.string(),
+    orderBy: SettingOrderBy,
+    queryMode: SonamuQueryMode,
+    id: zArrayable(z.number().int().positive()),
+    sonamuFilter: z.custom<ApplySonamuFilter<SettingBaseSchema, never, never>>(),
+    key: z.string().max(100),
+  })
+  .partial();
+export type SettingBaseListParams = z.infer<typeof SettingBaseListParams>;
+
 // BaseListParams: Token
 export const TokenBaseListParams = z
   .object({
@@ -486,6 +522,21 @@ export type RequestLogStepSubsetMapping = {
 export const RequestLogStepSubsetKey = z.enum(["A", "T", "I"]);
 export type RequestLogStepSubsetKey = z.infer<typeof RequestLogStepSubsetKey>;
 
+// Subsets: Setting
+export const SettingSubsetA = z.object({
+  id: z.int(),
+  created_at: z.date(),
+  key: z.string().max(100),
+  value: z.string(),
+  updated_at: z.date().nullable(),
+});
+export type SettingSubsetA = z.infer<typeof SettingSubsetA>;
+export type SettingSubsetMapping = {
+  A: SettingSubsetA;
+};
+export const SettingSubsetKey = z.enum(["A"]);
+export type SettingSubsetKey = z.infer<typeof SettingSubsetKey>;
+
 // Subsets: Token
 export const TokenSubsetA = z.object({
   id: z.int(),

package/bundle/src/i18n/en.ts

@@ -47,6 +47,8 @@ export default {
   "error.internalServerError": "Internal server error",
   "error.notFound": "Not found",
   "error.serviceUnavailable": "Service unavailable",
+  "setting.invalidValue": (reason: string) => `Invalid setting value: ${reason}`,
+  "setting.unknownKey": (key: string) => `Unknown setting key ${key}`,
   "qgrid.dispatcherFailed": (provider: string) => `${provider} dispatcher failed to initialize`,
   "qgrid.dispatcherStarting": (provider: string) =>
     `${provider} dispatcher is starting up. Please retry shortly`,

package/bundle/src/i18n/ko.ts

@@ -46,6 +46,8 @@ export default {
   "error.internalServerError": "서버 오류가 발생했습니다",
   "error.notFound": "찾을 수 없습니다",
   "error.serviceUnavailable": "서비스를 사용할 수 없습니다",
+  "setting.invalidValue": (reason: string) => `설정 값이 올바르지 않습니다: ${reason}`,
+  "setting.unknownKey": (key: string) => `알 수 없는 설정 키 ${key}`,
   "qgrid.dispatcherFailed": (provider: string) => `${provider} dispatcher 초기화에 실패했습니다`,
   "qgrid.dispatcherStarting": (provider: string) =>
     `${provider} dispatcher 기동 중입니다. 잠시 후 다시 시도해주세요`,

package/bundle/src/i18n/sd.generated.ts

@@ -297,6 +297,14 @@ const entityLabels = {
   "enum.RequestLogStepType.tool_call": "Tool 호출",
   "enum.RequestLogStepOrderBy.id-asc": "ID순",
   "enum.RequestLogStepSearchField.id": "ID",
+  "entity.Setting": "Setting",
+  "entity.Setting.id": "ID",
+  "entity.Setting.created_at": "등록일시",
+  "entity.Setting.key": "설정 키 (예: openai.maxWorkersPerToken)",
+  "entity.Setting.value": "설정 값 (문자열 저장, 앱에서 파싱·검증)",
+  "entity.Setting.updated_at": "최종 수정일시",
+  "enum.SettingOrderBy.key-asc": "키순",
+  "enum.SettingSearchField.key": "키",
   "entity.Token": "Token",
   "entity.Token.id": "ID",
   "entity.Token.created_at": "등록일시",

package/bundle/src/migrations/20260808194708_create__settings.ts

@@ -0,0 +1,19 @@
+import { type Knex } from "knex";
+
+export async function up(knex: Knex): Promise<void> {
+  await knex.schema.createTable("settings", (table) => {
+    table.increments().primary();
+    table
+      .timestamp("created_at", { useTz: true, precision: 3 })
+      .notNullable()
+      .defaultTo(knex.raw("CURRENT_TIMESTAMP"));
+    table.string("key", 100).notNullable();
+    table.text("value").notNullable();
+    table.timestamp("updated_at", { useTz: true, precision: 3 }).nullable();
+  });
+  await knex.raw(`CREATE UNIQUE INDEX settings_key_unique ON settings USING btree(key);`);
+}
+
+export async function down(knex: Knex): Promise<void> {
+  return knex.schema.dropTable("settings");
+}

package/bundle/src/sonamu.config.ts

@@ -8,6 +8,7 @@ import { drivers as cacheDrivers, store } from "sonamu/cache";
 
 import { monitLogSink } from "./application/monit/log-buffer";
 import {
+  rescheduleExpiredTokenReminder,
   startExpiredTokenReminder,
   stopExpiredTokenReminder,
 } from "./application/qgrid/expired-token-reminder";
@@ -15,6 +16,7 @@ import { QgridDispatcher } from "./application/qgrid/qgrid.dispatcher";
 import { QgridFrame } from "./application/qgrid/qgrid.frame";
 import { TokenSubscriber } from "./application/qgrid/token-subscriber";
 import { ensureTokensTrigger } from "./application/qgrid/token-trigger-setup";
+import { loadSettings, setSettingChangeHandler } from "./application/setting/setting.store";
 import { handleServerError } from "./server-error-handler";
 import { AnthropicDispatcher } from "./utils/providers/anthropic/anthropic-dispatcher";
 import { OpenAIDispatcher } from "./utils/providers/openai/openai-dispatcher";
@@ -170,6 +172,13 @@ export default defineConfig({
       onStart: async () => {
         const log = getLogger(["qgrid", "startup"]);
 
+        // dispatcher 가 생성자에서 워커 설정을 읽으므로 그 전에 올려야 한다.
+        await loadSettings();
+        // 런타임 설정 소비자를 상위 계층에서 연결해 setting 모듈이 qgrid 를 역참조하지 않게 한다.
+        setSettingChangeHandler((key) => {
+          if (key === "slack.expiryReminderMinutes") rescheduleExpiredTokenReminder();
+        });
+
         let triggerReady = true;
         try {
           await ensureTokensTrigger(connConfig);
@@ -221,6 +230,7 @@ export default defineConfig({
       onShutdown: async () => {
         const log = getLogger(["qgrid", "startup"]);
         stopExpiredTokenReminder();
+        setSettingChangeHandler(null);
         if (QgridDispatcher.openaiDispatcher) {
           await QgridDispatcher.openaiDispatcher.stop();
         }

package/bundle/src/utils/providers/openai/openai-dispatcher.test.ts

@@ -251,6 +251,18 @@ describe("OpenAIDispatcher worker capacity", () => {
     expect(estimateOpenAIWorkerRssGiB(50)).toBeCloseTo(8.56, 2);
     expect(estimateOpenAIWorkerRssGiB(60)).toBeCloseTo(10.13, 2);
   });
+
+  it("clamps memory guard inputs to the 64 GiB host policy", () => {
+    expect(
+      resolveOpenAIWorkerPoolConfig({
+        QGRID_OPENAI_MAX_ESTIMATED_RSS_GIB: "999",
+        QGRID_OPENAI_MIN_HOST_AVAILABLE_GIB: "999",
+      }),
+    ).toMatchObject({
+      maxEstimatedRssGiB: 32,
+      minHostAvailableGiB: 64,
+    });
+  });
 });
 
 describe("OpenAIDispatcher monit stats", () => {

package/bundle/src/utils/providers/openai/openai-worker-pool-config.ts

@@ -1,3 +1,10 @@
+import {
+  MAX_OPENAI_ESTIMATED_RSS_GIB,
+  MAX_OPENAI_MIN_HOST_AVAILABLE_GIB,
+  SETTING_DEFS,
+} from "../../../application/setting/setting.schema";
+import { getSetting } from "../../../application/setting/setting.store";
+
 export const MAX_OPENAI_WORKERS_PER_TOKEN = 20;
 const DEFAULT_OPENAI_MIN_WORKERS_PER_TOKEN = 1;
 const DEFAULT_OPENAI_MAX_WORKERS_PER_TOKEN = 3;
@@ -26,14 +33,35 @@ function boundedInteger(
   return Math.max(min, Math.min(Math.floor(parsed), max));
 }
 
-function boundedNumber(value: string | undefined, fallback: number, min: number): number {
+function boundedNumber(
+  value: string | undefined,
+  fallback: number,
+  min: number,
+  max: number,
+): number {
   const parsed = Number(value);
   if (!Number.isFinite(parsed)) return fallback;
-  return Math.max(min, parsed);
+  return Math.max(min, Math.min(parsed, max));
+}
+
+/**
+ * 설정 저장소(DB) 를 먼저 보고 없으면 env 로 떨어지는 조회 객체.
+ *
+ * 기존 파싱 로직이 `env[KEY]` 형태를 전제하므로, 소스만 바꿔 끼우고 검증·기본값 처리는
+ * 그대로 둔다. `get` 접근만 지원하므로 `in`이나 `Object.keys()`로 조회하지 않는다. 테스트는
+ * `env` 인자에 순수한 맵을 넘겨 저장소를 우회한다.
+ */
+function settingsBackedEnv(): Record<string, string | undefined> {
+  return new Proxy({} as Record<string, string | undefined>, {
+    get: (_target, prop: string) => {
+      const def = SETTING_DEFS.find((d) => d.envKey === prop);
+      return def ? getSetting(def.key, def.envKey) : process.env[prop];
+    },
+  });
 }
 
 export function resolveOpenAIWorkerPoolConfig(
-  env: Record<string, string | undefined> = process.env,
+  env: Record<string, string | undefined> = settingsBackedEnv(),
 ): OpenAIWorkerPoolConfig {
   const autoscale = env.QGRID_OPENAI_AUTOSCALE !== "false" && env.QGRID_OPENAI_AUTOSCALE !== "0";
   const minWorkersPerToken = boundedInteger(
@@ -64,8 +92,18 @@ export function resolveOpenAIWorkerPoolConfig(
       1_000,
       24 * 60 * 60_000,
     ),
-    maxEstimatedRssGiB: boundedNumber(env.QGRID_OPENAI_MAX_ESTIMATED_RSS_GIB, 16, 1),
-    minHostAvailableGiB: boundedNumber(env.QGRID_OPENAI_MIN_HOST_AVAILABLE_GIB, 20, 0),
+    maxEstimatedRssGiB: boundedNumber(
+      env.QGRID_OPENAI_MAX_ESTIMATED_RSS_GIB,
+      16,
+      1,
+      MAX_OPENAI_ESTIMATED_RSS_GIB,
+    ),
+    minHostAvailableGiB: boundedNumber(
+      env.QGRID_OPENAI_MIN_HOST_AVAILABLE_GIB,
+      20,
+      0,
+      MAX_OPENAI_MIN_HOST_AVAILABLE_GIB,
+    ),
   };
 }
 

package/bundle/src/utils/quiet-hours.ts

@@ -0,0 +1,40 @@
+/**
+ * Slack 알림 조용 시간.
+ *
+ * 토큰 만료는 사람이 재로그인해야 풀리는데, 그 사람이 자거나 쉬는 동안 알려도 할 수 있는
+ * 일이 없다. 평일 업무 시간에만 알리고 나머지는 다음 근무 시간으로 미룬다 — 만료 알림은
+ * 주기적으로 반복되므로 조용 시간에 버려도 아침 첫 주기에 다시 온다.
+ *
+ * 다만 provider 의 마지막 토큰이 죽는 것은 서비스 정지 신호라 이 규칙에서 제외한다
+ * (호출부가 `notifySlack` 을 그냥 호출하면 된다).
+ */
+
+/** 이 시각부터(포함) 조용해진다. */
+const QUIET_FROM_HOUR = 20;
+/** 이 시각부터(포함) 다시 알린다. */
+const QUIET_UNTIL_HOUR = 8;
+
+/**
+ * 서버가 UTC 로 돌아도 한국 시간으로 판정한다. dev0 는 UTC 이므로 `getHours()` 를 그대로
+ * 쓰면 "저녁 8시"가 한국 시간 새벽 5시가 된다.
+ */
+function seoulParts(at: Date): { hour: number; weekday: string } {
+  const formatter = new Intl.DateTimeFormat("en-US", {
+    timeZone: "Asia/Seoul",
+    hour: "numeric",
+    hour12: false,
+    weekday: "short",
+  });
+  const parts = formatter.formatToParts(at);
+  const hour = Number(parts.find((p) => p.type === "hour")?.value ?? "0");
+  const weekday = parts.find((p) => p.type === "weekday")?.value ?? "";
+  // Intl 은 자정을 24 로 줄 수 있다. 0..23 으로 맞춘다.
+  return { hour: hour % 24, weekday };
+}
+
+/** 주말이거나 20시~익일 8시면 조용 시간. */
+export function isQuietHours(at: Date = new Date()): boolean {
+  const { hour, weekday } = seoulParts(at);
+  if (weekday === "Sat" || weekday === "Sun") return true;
+  return hour >= QUIET_FROM_HOUR || hour < QUIET_UNTIL_HOUR;
+}

package/bundle/src/utils/slack-notify.test.ts

@@ -1,21 +1,29 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
-import { notifySlack, SLACK_COLOR } from "./slack-notify";
+import { isQuietHours } from "./quiet-hours";
+import { notifySlack, SLACK_COLOR, type SlackNotification } from "./slack-notify";
 
-describe("notifySlack", () => {
-  const savedToken = process.env.SLACK_BOT_TOKEN;
-  const savedChannel = process.env.SLACK_CHANNEL_ID;
+const settingMock = vi.fn();
+
+const notify = (notification: SlackNotification) => notifySlack(notification, settingMock);
+
+/** 한국 시간을 UTC 로 표현한다 — dev0 가 UTC 라 이 변환이 실제 운영 조건이다. */
+function seoul(iso: string): Date {
+  return new Date(`${iso}+09:00`);
+}
+
+/** 평일 업무 시간. 조용 시간에 막히지 않도록 전송 케이스의 기준 시각으로 쓴다. */
+const WORKING_HOURS = seoul("2026-08-05T14:00:00");
 
+describe("notifySlack", () => {
   beforeEach(() => {
-    process.env.SLACK_BOT_TOKEN = "xoxb-test";
-    process.env.SLACK_CHANNEL_ID = "C123";
+    settingMock.mockImplementation((key: string) =>
+      key === "slack.botToken" ? "xoxb-test" : key === "slack.channelId" ? "C123" : undefined,
+    );
   });
 
   afterEach(() => {
-    if (savedToken === undefined) delete process.env.SLACK_BOT_TOKEN;
-    else process.env.SLACK_BOT_TOKEN = savedToken;
-    if (savedChannel === undefined) delete process.env.SLACK_CHANNEL_ID;
-    else process.env.SLACK_CHANNEL_ID = savedChannel;
+    settingMock.mockReset();
     vi.restoreAllMocks();
   });
 
@@ -24,11 +32,12 @@ describe("notifySlack", () => {
       .spyOn(globalThis, "fetch")
       .mockResolvedValue(new Response(JSON.stringify({ ok: true })));
 
-    await notifySlack({
+    await notify({
       title: "토큰 추가",
       subject: "anthropic/test-token",
       context: "anthropic · 요청 처리에 사용됩니다",
       color: SLACK_COLOR.good,
+      now: WORKING_HOURS,
     });
 
     expect(fetchMock).toHaveBeenCalledTimes(1);
@@ -62,11 +71,12 @@ describe("notifySlack", () => {
       .spyOn(globalThis, "fetch")
       .mockResolvedValue(new Response(JSON.stringify({ ok: true })));
 
-    await notifySlack({ title: "제목만" });
+    await notify({ title: "제목만", now: WORKING_HOURS });
 
-    const body = JSON.parse(
-      (fetchMock.mock.calls[0]![1] as RequestInit).body as string,
-    ) as { text?: string; attachments: [{ fallback: string; color?: string; blocks: unknown[] }] };
+    const body = JSON.parse((fetchMock.mock.calls[0]![1] as RequestInit).body as string) as {
+      text?: string;
+      attachments: [{ fallback: string; color?: string; blocks: unknown[] }];
+    };
     // 최상위 text 를 보내지 않아야 blocks 렌더 화면에서 제목이 중복되지 않는다.
     expect(body.text).toBeUndefined();
     expect(body.attachments[0].fallback).toBe("제목만");
@@ -74,11 +84,11 @@ describe("notifySlack", () => {
     expect(body.attachments[0].blocks).toHaveLength(1);
   });
 
-  it("skips the request entirely when env is not configured", async () => {
-    delete process.env.SLACK_BOT_TOKEN;
+  it("skips the request entirely when Slack is not configured", async () => {
+    settingMock.mockReturnValue(undefined);
     const fetchMock = vi.spyOn(globalThis, "fetch");
 
-    await expect(notifySlack({ title: "hello" })).resolves.toBeUndefined();
+    await expect(notify({ title: "hello", now: WORKING_HOURS })).resolves.toBeUndefined();
 
     expect(fetchMock).not.toHaveBeenCalled();
   });
@@ -88,12 +98,70 @@ describe("notifySlack", () => {
       new Response(JSON.stringify({ ok: false, error: "not_in_channel" })),
     );
 
-    await expect(notifySlack({ title: "hello" })).resolves.toBeUndefined();
+    await expect(notify({ title: "hello", now: WORKING_HOURS })).resolves.toBeUndefined();
   });
 
   it("swallows network and timeout failures", async () => {
     vi.spyOn(globalThis, "fetch").mockRejectedValue(new Error("timed out"));
 
-    await expect(notifySlack({ title: "hello" })).resolves.toBeUndefined();
+    await expect(notify({ title: "hello", now: WORKING_HOURS })).resolves.toBeUndefined();
+  });
+
+  it("조용 시간에는 보통 알림을 보내지 않는다", async () => {
+    const fetchMock = vi.spyOn(globalThis, "fetch");
+
+    await notify({ title: "세션 만료", now: seoul("2026-08-05T22:00:00") });
+
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("urgent 알림은 조용 시간에도 보낸다", async () => {
+    // provider 전체가 죽은 상황은 다음 근무일까지 미룰 수 없다.
+    const fetchMock = vi
+      .spyOn(globalThis, "fetch")
+      .mockResolvedValue(new Response(JSON.stringify({ ok: true })));
+
+    await notify({
+      title: "마지막 토큰 사망",
+      urgent: true,
+      now: seoul("2026-08-05T22:00:00"),
+    });
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("isQuietHours", () => {
+  it("평일 업무 시간에는 알린다", () => {
+    // 2026-08-05 는 수요일
+    expect(isQuietHours(seoul("2026-08-05T09:00:00"))).toBe(false);
+    expect(isQuietHours(seoul("2026-08-05T19:59:00"))).toBe(false);
+  });
+
+  it("평일 20시부터 다음날 8시까지 조용하다", () => {
+    expect(isQuietHours(seoul("2026-08-05T20:00:00"))).toBe(true);
+    expect(isQuietHours(seoul("2026-08-06T00:00:00"))).toBe(true);
+    expect(isQuietHours(seoul("2026-08-06T07:59:00"))).toBe(true);
+    expect(isQuietHours(seoul("2026-08-06T08:00:00"))).toBe(false);
+  });
+
+  it("주말은 시간과 무관하게 조용하다", () => {
+    // 2026-08-08 토요일, 08-09 일요일
+    expect(isQuietHours(seoul("2026-08-08T10:00:00"))).toBe(true);
+    expect(isQuietHours(seoul("2026-08-09T12:00:00"))).toBe(true);
+  });
+
+  it("월요일 8시에 다시 알리기 시작한다", () => {
+    expect(isQuietHours(seoul("2026-08-10T07:59:00"))).toBe(true);
+    expect(isQuietHours(seoul("2026-08-10T08:00:00"))).toBe(false);
+  });
+
+  it("서버가 UTC 여도 한국 시간으로 판정한다", () => {
+    // UTC 23시 = 한국 다음날 08시 → 업무 시간
+    expect(isQuietHours(new Date("2026-08-04T23:00:00Z"))).toBe(false);
+    // UTC 12시 = 한국 21시 → 조용 시간
+    expect(isQuietHours(new Date("2026-08-05T12:00:00Z"))).toBe(true);
+    // UTC 금요일 22시 = 한국 토요일 07시 → 주말
+    expect(isQuietHours(new Date("2026-08-07T22:00:00Z"))).toBe(true);
   });
 });

package/bundle/src/utils/slack-notify.ts

@@ -2,10 +2,14 @@
  * Slack 알림 (chat.postMessage).
  *
  * fail-open: env 미설정이면 조용히 no-op 이고, 전송 실패는 warn 로그로만 남긴다.
+ * 조용 시간(주말·20~8시)에는 `urgent` 가 아닌 알림을 보내지 않는다.
  * 알림 경로가 토큰 라우팅이나 오류 전파를 지연·차단해서는 안 된다.
  */
 import { getLogger } from "@logtape/logtape";
 
+import { getSetting } from "../application/setting/setting.store";
+import { isQuietHours } from "./quiet-hours";
+
 const logger = getLogger(["qgrid", "slack"]);
 
 const SLACK_POST_MESSAGE_URL = "https://slack.com/api/chat.postMessage";
@@ -25,17 +29,33 @@ export type SlackNotification = {
   /** 제목 아래 작은 글씨로 내려가는 부가 정보 — 읽지 않아도 되는 것들. */
   context?: string;
   color?: (typeof SLACK_COLOR)[keyof typeof SLACK_COLOR];
+  /**
+   * 조용 시간(주말·20~8시)에도 보낸다. 서비스가 멈춘 상태처럼 지금 알지 않으면 손해가
+   * 커지는 사건에만 쓴다 — 남용하면 조용 시간 자체가 무의미해진다.
+   */
+  urgent?: boolean;
+  /** 조용 시간 판정 기준 시각. 테스트에서 시계를 고정할 때만 넘긴다. */
+  now?: Date;
 };
 
-export async function notifySlack(notification: SlackNotification): Promise<void> {
-  const botToken = process.env.SLACK_BOT_TOKEN;
-  const channel = process.env.SLACK_CHANNEL_ID;
-  const { title, subject, context, color } = notification;
+export async function notifySlack(
+  notification: SlackNotification,
+  readSetting: typeof getSetting = getSetting,
+): Promise<void> {
+  const botToken = readSetting("slack.botToken", "SLACK_BOT_TOKEN");
+  const channel = readSetting("slack.channelId", "SLACK_CHANNEL_ID");
+  const { title, subject, context, color, urgent, now } = notification;
   if (!botToken || !channel) {
     logger.debug(`slack not configured, skipping notification: ${title} ${subject ?? ""}`);
     return;
   }
 
+  // 만료 알림은 주기적으로 반복되므로 여기서 버려도 다음 근무 시간 첫 주기에 다시 온다.
+  if (!urgent && isQuietHours(now)) {
+    logger.debug(`quiet hours, skipping notification: ${title} ${subject ?? ""}`);
+    return;
+  }
+
   const blocks: unknown[] = [
     {
       type: "section",