sonamu 0.10.12 → 0.10.13

package/src/ui/api.ts

@@ -20,8 +20,8 @@ import {
   ServiceUnavailableException,
 } from "../exceptions/so-exceptions";
 import { TemplateManager } from "../template/template-manager";
-import { DataExplorer } from "../testing/data-explorer";
-import { FixtureGenerator } from "../testing/fixture-generator";
+import { DataExplorer, type DataExplorerOptions } from "../testing/data-explorer";
+import { FixtureGenerator, type FixtureGenerationSpec } from "../testing/fixture-generator";
 import { FixtureManager } from "../testing/fixture-manager";
 import { type DuplicateCheckOptions } from "../testing/fixture-manager";
 import { BUILT_IN_TYPE_IDS, TemplateKey } from "../types/types";
@@ -35,8 +35,10 @@ import {
   type FlattenSubsetRow,
   type PathAndCode,
 } from "../types/types";
+import { isObjectValue } from "../utils/runtime-value";
 import { nonNullable } from "../utils/utils";
 import { setAiApi } from "./ai-api";
+import { forwardAsyncErrors } from "./async-route";
 import { type CddAddRuleRequest } from "./cdd-service";
 import {
   addRule,
@@ -50,30 +52,41 @@ import {
 } from "./cdd-service";
 import { registerMigrationsApi } from "./migrations-api";
 
-export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
-  fastify.register(
-    async (server) => {
-      // waitForHMRCompleted
-      async function waitForHMRCompleted<T>(fn: () => Promise<T>): Promise<T> {
-        const waitPromise = new Promise<void>((resolve) => {
-          const handler = () => {
-            clearTimeout(timeout);
-            resolve();
-          };
+interface EntityTemplateInput {
+  entityId: string;
+  enumId?: string;
+}
 
-          const timeout = setTimeout(() => {
-            Sonamu.syncer.eventEmitter.off("onHMRCompleted", handler);
-            resolve();
-          }, 1500);
+async function waitForHMRCompleted<T>(fn: () => Promise<T>): Promise<T> {
+  const waitPromise = new Promise<void>((resolve) => {
+    const handler = () => {
+      clearTimeout(timeout);
+      resolve();
+    };
 
-          Sonamu.syncer.eventEmitter.once("onHMRCompleted", handler);
-        });
+    const timeout = setTimeout(() => {
+      Sonamu.syncer.eventEmitter.off("onHMRCompleted", handler);
+      resolve();
+    }, 1500);
+
+    Sonamu.syncer.eventEmitter.once("onHMRCompleted", handler);
+  });
 
-        const result = await fn();
-        await waitPromise;
-        return result;
-      }
+  const result = await fn();
+  await waitPromise;
+  return result;
+}
 
+function flattenSubsetRows(subsetRows: EntitySubsetRow[]): FlattenSubsetRow[] {
+  return subsetRows.flatMap((subsetRow) => {
+    const { children, ...sRow } = subsetRow;
+    return [sRow, ...flattenSubsetRows(children)];
+  });
+}
+
+export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
+  fastify.register(
+    async (server) => {
       await setAiApi(server);
       await registerMigrationsApi(server);
 
@@ -87,185 +100,188 @@ export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
           preset?: "types" | "entity.json" | "generated";
           absPath?: string;
         };
-      }>("/api/tools/openVscode", async (request) => {
-        const { entityId, preset, absPath } = request.query;
-
-        const targetPath = (() => {
-          if (entityId && preset) {
-            const entity = EntityManager.get(entityId);
-            const { names } = entity;
-
-            const { apiRootPath } = Sonamu;
-            const filename = (() => {
-              switch (preset) {
-                case "types":
-                  return `${names.fs}.types.ts`;
-                case "entity.json":
-                  return `${names.fs}.entity.json`;
-                case "generated":
-                  return `${names.fs}.generated.ts`;
+      }>("/api/tools/openVscode", (request) =>
+        forwardAsyncErrors(async () => {
+          const { entityId, preset, absPath } = request.query;
+
+          const targetPath = (() => {
+            if (entityId && preset) {
+              const entity = EntityManager.get(entityId);
+              const { names } = entity;
+
+              const { apiRootPath } = Sonamu;
+              const filename = (() => {
+                switch (preset) {
+                  case "types":
+                    return `${names.fs}.types.ts`;
+                  case "entity.json":
+                    return `${names.fs}.entity.json`;
+                  case "generated":
+                    return `${names.fs}.generated.ts`;
+                }
+                return undefined;
+              })();
+              return `${apiRootPath}/src/application/${entity.names.parentFs}/${filename}`;
+            } else {
+              if (!absPath) {
+                throw new BadRequestException(SD("sonamu.error.presetOrAbsPathRequired"));
               }
-            })();
-            return `${apiRootPath}/src/application/${entity.names.parentFs}/${filename}`;
-          } else {
-            if (!absPath) {
-              throw new BadRequestException(SD("sonamu.error.presetOrAbsPathRequired"));
+              return absPath;
             }
-            return absPath;
-          }
-        })();
-        execSync(`code ${targetPath}`);
-      });
+          })();
+          execSync(`code ${targetPath}`);
+        }),
+      );
 
       server.get<{
         Querystring: {
           editor: "vscode" | "cursor" | "zed";
           absPath: string;
         };
-      }>("/api/tools/openEditor", async (request) => {
-        const commands = {
-          vscode: "code",
-          cursor: "cursor",
-          zed: "zed",
-        } as const;
-        const command = commands[request.query.editor];
-        if (command === undefined) {
-          throw new BadRequestException(SD("error.badRequest"));
-        }
+      }>("/api/tools/openEditor", (request) =>
+        forwardAsyncErrors(async () => {
+          const commands = {
+            vscode: "code",
+            cursor: "cursor",
+            zed: "zed",
+          } as const;
+          const command = commands[request.query.editor];
+          if (command === undefined) {
+            throw new BadRequestException(SD("error.badRequest"));
+          }
 
-        // 셸을 거치지 않아 파일 경로가 명령으로 해석되지 않도록 합니다.
-        execFileSync(command, [request.query.absPath]);
-      });
+          // 셸을 거치지 않아 파일 경로가 명령으로 해석되지 않도록 합니다.
+          execFileSync(command, [request.query.absPath]);
+        }),
+      );
 
       server.get<{
         Querystring: {
           origin: string;
           entityId?: string;
         };
-      }>("/api/tools/getSuggestion", async (request) => {
-        const { origin, entityId } = request.query;
-
-        // 치환 용어집
-        const glossary = new Map<string, string>([
-          ["status", "상태"],
-          ["type", "타입"],
-          ["image", "이미지"],
-          ["images", "이미지리스트"],
-          ["url", "URL"],
-          ["id", "ID"],
-          ["name", `{EntityID}명`],
-          ["title", "{EntityID}명"],
-          ["parent", "상위{EntityID}"],
-          ["desc", "설명"],
-          ["at", "일시"],
-          ["created", "등록"],
-          ["updated", "수정"],
-          ["deleted", "삭제"],
-          ["by", "유저"],
-          ["date", "일자"],
-          ["time", "시간"],
-          ["ko", "(한글)"],
-          ["en", "(영문)"],
-          ["krw", "(원)"],
-          ["usd", "(USD)"],
-          ["color", "컬러"],
-          ["code", "코드"],
-          ["x", "X좌표"],
-          ["y", "Y좌표"],
-          ["current", "현재"],
-          ["stock", "재고"],
-          ["total", "총"],
-          ["admin", "관리자"],
-          ["group", "그룹"],
-          ["item", "아이템"],
-          ["cnt", "수량"],
-          ["price", "가격"],
-          ["preset", "프리셋"],
-          ["acct", "계좌"],
-          ["tel", "전화번호"],
-          ["no", "번호"],
-          ["body", "내용"],
-          ["content", "내용"],
-          ["orderno", "정렬순서"],
-          ["priority", "우선순위"],
-          ["text", "텍스트"],
-          ["key", "키"],
-          ["sum", "합산"],
-          ["expected", "예상"],
-          ["actual", "실제"],
-        ]);
-        // 전체 엔티티 순회하며, 엔티티 타이틀과 프롭 설명을 치환 용어집에 추가
-        for (const entityId of EntityManager.getAllIds()) {
-          const entity = EntityManager.get(entityId);
-          if ((entity.title ?? "") !== "") {
-            glossary.set(inflection.underscore(entity.id), entity.title);
-            glossary.set(
-              inflection.underscore(inflection.pluralize(entity.id)),
-              `${entity.title}리스트`,
-            );
-          }
-
-          entity.props.forEach((prop) => {
-            if (glossary.has(prop.name)) {
-              return;
-            }
-            if (prop.desc) {
-              glossary.set(prop.name, prop.desc.replace(entity.title ?? "", "{EntityID}"));
+      }>("/api/tools/getSuggestion", (request) =>
+        forwardAsyncErrors(async () => {
+          const { origin, entityId } = request.query;
+
+          // 치환 용어집
+          const glossary = new Map<string, string>([
+            ["status", "상태"],
+            ["type", "타입"],
+            ["image", "이미지"],
+            ["images", "이미지리스트"],
+            ["url", "URL"],
+            ["id", "ID"],
+            ["name", `{EntityID}명`],
+            ["title", "{EntityID}명"],
+            ["parent", "상위{EntityID}"],
+            ["desc", "설명"],
+            ["at", "일시"],
+            ["created", "등록"],
+            ["updated", "수정"],
+            ["deleted", "삭제"],
+            ["by", "유저"],
+            ["date", "일자"],
+            ["time", "시간"],
+            ["ko", "(한글)"],
+            ["en", "(영문)"],
+            ["krw", "(원)"],
+            ["usd", "(USD)"],
+            ["color", "컬러"],
+            ["code", "코드"],
+            ["x", "X좌표"],
+            ["y", "Y좌표"],
+            ["current", "현재"],
+            ["stock", "재고"],
+            ["total", "총"],
+            ["admin", "관리자"],
+            ["group", "그룹"],
+            ["item", "아이템"],
+            ["cnt", "수량"],
+            ["price", "가격"],
+            ["preset", "프리셋"],
+            ["acct", "계좌"],
+            ["tel", "전화번호"],
+            ["no", "번호"],
+            ["body", "내용"],
+            ["content", "내용"],
+            ["orderno", "정렬순서"],
+            ["priority", "우선순위"],
+            ["text", "텍스트"],
+            ["key", "키"],
+            ["sum", "합산"],
+            ["expected", "예상"],
+            ["actual", "실제"],
+          ]);
+          // 전체 엔티티 순회하며, 엔티티 타이틀과 프롭 설명을 치환 용어집에 추가
+          for (const glossaryEntityId of EntityManager.getAllIds()) {
+            const glossaryEntity = EntityManager.get(glossaryEntityId);
+            if ((glossaryEntity.title ?? "") !== "") {
+              glossary.set(inflection.underscore(glossaryEntity.id), glossaryEntity.title);
+              glossary.set(
+                inflection.underscore(inflection.pluralize(glossaryEntity.id)),
+                `${glossaryEntity.title}리스트`,
+              );
             }
-          });
-        }
 
-        const suggested = (() => {
-          // 단어 분리, 가능한 조합 생성
-          const words = origin.split("_");
-          const combinations = [...range(words.length, 0, -1)].flatMap((len) => {
-            return [
-              ...range(0, words.length - len + 1, (idx) => {
-                return {
-                  len,
-                  w: words.slice(idx, idx + len).join("_"),
-                };
-              }),
-            ];
-          });
-
-          // 조합을 순회하며, 치환 용어집에 있는 단어가 포함된 경우, 치환 용어로 치환
-          const REPLACED_PREFIX = "#REPLACED//"; // 치환된 단어를 join 이후에도 식별하기 위해 prefix 추가
-          let remainArr: string[] = [...words];
-          for (const comb of combinations) {
-            const remainStr = remainArr.join("_");
-            if (remainStr.includes(comb.w) && glossary.has(comb.w)) {
-              remainArr = remainStr
-                .replace(comb.w, REPLACED_PREFIX + glossary.get(comb.w))
-                .split("_");
-            }
+            glossaryEntity.props.forEach((prop) => {
+              if (glossary.has(prop.name)) {
+                return;
+              }
+              if (prop.desc) {
+                glossary.set(
+                  prop.name,
+                  prop.desc.replace(glossaryEntity.title ?? "", "{EntityID}"),
+                );
+              }
+            });
           }
 
-          return remainArr
-            .map((r) => {
-              if (r.startsWith(REPLACED_PREFIX)) {
-                return r.replace(REPLACED_PREFIX, "");
-              } else {
-                return r.toUpperCase();
+          const suggested = (() => {
+            // 단어 분리, 가능한 조합 생성
+            const words = origin.split("_");
+            const combinations = [...range(words.length, 0, -1)].flatMap((len) => {
+              return [
+                ...range(0, words.length - len + 1, (idx) => {
+                  return {
+                    len,
+                    w: words.slice(idx, idx + len).join("_"),
+                  };
+                }),
+              ];
+            });
+
+            // 조합을 순회하며, 치환 용어집에 있는 단어가 포함된 경우, 치환 용어로 치환
+            const REPLACED_PREFIX = "#REPLACED//"; // 치환된 단어를 join 이후에도 식별하기 위해 prefix 추가
+            let remainArr: string[] = [...words];
+            for (const comb of combinations) {
+              const remainStr = remainArr.join("_");
+              if (remainStr.includes(comb.w) && glossary.has(comb.w)) {
+                remainArr = remainStr
+                  .replace(comb.w, REPLACED_PREFIX + glossary.get(comb.w))
+                  .split("_");
               }
-            })
-            .join("")
-            .replace(/{EntityID}/g, entityId ? EntityManager.get(entityId).title : "");
-        })();
+            }
 
-        return { suggested };
-      });
+            return remainArr
+              .map((r) => {
+                if (r.startsWith(REPLACED_PREFIX)) {
+                  return r.replace(REPLACED_PREFIX, "");
+                } else {
+                  return r.toUpperCase();
+                }
+              })
+              .join("")
+              .replace(/{EntityID}/g, entityId ? EntityManager.get(entityId).title : "");
+          })();
+
+          return { suggested };
+        }),
+      );
 
       server.get("/api/entity/findMany", async () => {
         const entityIds = EntityManager.getAllIds();
 
-        function flattenSubsetRows(subsetRows: EntitySubsetRow[]): FlattenSubsetRow[] {
-          return subsetRows.flatMap((subsetRow) => {
-            const { children, ...sRow } = subsetRow;
-            return [sRow, ...flattenSubsetRows(children)];
-          });
-        }
-
         const entities = await Promise.all(
           entityIds.map((entityId) => {
             const entity = EntityManager.get(entityId);
@@ -307,45 +323,55 @@ export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
           filter?: "enums" | "types";
           reload?: "1";
         };
-      }>("/api/entity/typeIds", async (request): Promise<{ typeIds: string[] }> => {
-        const { filter, reload } = request.query;
-
-        if (reload === "1") {
-          await Sonamu.syncer.autoloadTypes();
-        }
-
-        const typeIds = (() => {
-          // 프로젝트에서 정의한 타입들
-          const projectTypeIds = Object.entries(Sonamu.syncer.types)
-            .filter(([_typeId, zodType]) => (zodType._zod.def.type as string) !== "enum")
-            .map(([typeId, _zodType]) => typeId);
-
-          // 내장 타입들 (sonamu 코어에서 제공)
-          const builtInTypeIds = [...BUILT_IN_TYPE_IDS];
-
-          // 모든 타입 병합
-          const allTypeIds = [...builtInTypeIds, ...projectTypeIds];
+      }>(
+        "/api/entity/typeIds",
+        (request): Promise<{ typeIds: string[] }> =>
+          forwardAsyncErrors(async () => {
+            const { filter, reload } = request.query;
+
+            if (reload === "1") {
+              await Sonamu.syncer.autoloadTypes();
+            }
 
-          if (filter === "types") {
-            return allTypeIds;
-          }
+            const typeIds = (() => {
+              // 프로젝트에서 정의한 타입들
+              const projectTypeIds = Object.entries(Sonamu.syncer.types)
+                .filter(([_typeId, zodType]) => {
+                  const { _zod: zodMetadata } = zodType;
+                  return (
+                    /* SAFETY: UI 도구의 Zod 입력 스키마가 이 값의 타입을 보장한다. */ (zodMetadata
+                      .def.type as string) !== "enum"
+                  );
+                })
+                .map(([typeId, _zodType]) => typeId);
+
+              // 내장 타입들 (sonamu 코어에서 제공)
+              const builtInTypeIds = [...BUILT_IN_TYPE_IDS];
+
+              // 모든 타입 병합
+              const allTypeIds = [...builtInTypeIds, ...projectTypeIds];
+
+              if (filter === "types") {
+                return allTypeIds;
+              }
 
-          const enumIds = EntityManager.getAllIds().flatMap((entityId) => {
-            const entity = EntityManager.get(entityId);
-            return Object.keys(entity.enumLabels);
-          });
+              const enumIds = EntityManager.getAllIds().flatMap((entityId) => {
+                const entity = EntityManager.get(entityId);
+                return Object.keys(entity.enumLabels);
+              });
 
-          if (filter === "enums") {
-            return enumIds;
-          } else {
-            return [...allTypeIds, ...enumIds];
-          }
-        })();
+              if (filter === "enums") {
+                return enumIds;
+              } else {
+                return [...allTypeIds, ...enumIds];
+              }
+            })();
 
-        return {
-          typeIds,
-        };
-      });
+            return {
+              typeIds,
+            };
+          }),
+      );
 
       server.post<{
         Body: {
@@ -356,25 +382,29 @@ export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
             parentId?: string;
           };
         };
-      }>("/api/entity/create", async (request) => {
-        return await waitForHMRCompleted(async () => {
-          const { form } = request.body;
-          await Sonamu.syncer.createEntity({ ...form, entityId: form.id });
+      }>("/api/entity/create", (request) =>
+        forwardAsyncErrors(async () => {
+          return await waitForHMRCompleted(async () => {
+            const { form } = request.body;
+            await Sonamu.syncer.createEntity({ ...form, entityId: form.id });
 
-          return 1;
-        });
-      });
+            return 1;
+          });
+        }),
+      );
 
       server.post<{
         Body: {
           entityId: string;
         };
-      }>("/api/entity/del", async (request) => {
-        return await waitForHMRCompleted(async () => {
-          const { entityId } = request.body;
-          return await Sonamu.syncer.delEntity(entityId);
-        });
-      });
+      }>("/api/entity/del", (request) =>
+        forwardAsyncErrors(async () => {
+          return await waitForHMRCompleted(async () => {
+            const { entityId } = request.body;
+            return await Sonamu.syncer.delEntity(entityId);
+          });
+        }),
+      );
 
       server.post<{
         Body: {
@@ -385,18 +415,20 @@ export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
             parentId?: string;
           };
         };
-      }>("/api/entity/modifyEntityBase", async (request) => {
-        return await waitForHMRCompleted(async () => {
-          const { entityId, newValues } = request.body;
-          const entity = EntityManager.get(entityId);
-          entity.title = newValues.title;
-          entity.table = newValues.table;
-          entity.parentId = newValues.parentId;
-          await entity.save();
+      }>("/api/entity/modifyEntityBase", (request) =>
+        forwardAsyncErrors(async () => {
+          return await waitForHMRCompleted(async () => {
+            const { entityId, newValues } = request.body;
+            const entity = EntityManager.get(entityId);
+            entity.title = newValues.title;
+            entity.table = newValues.table;
+            entity.parentId = newValues.parentId;
+            await entity.save();
 
-          return 1;
-        });
-      });
+            return 1;
+          });
+        }),
+      );
 
       server.post<{
         Body: {
@@ -405,40 +437,44 @@ export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
           fields: string[];
           fieldsInternal?: string[];
         };
-      }>("/api/entity/modifySubset", async (request) => {
-        return await waitForHMRCompleted(async () => {
-          const { entityId, subsetKey, fields, fieldsInternal } = request.body;
-          const entity = EntityManager.get(entityId);
-          entity.subsets[subsetKey] = fields;
-          if (fieldsInternal !== undefined) {
-            if (fieldsInternal.length > 0) {
-              entity.subsetsInternal[subsetKey] = fieldsInternal;
-            } else {
-              delete entity.subsetsInternal[subsetKey];
+      }>("/api/entity/modifySubset", (request) =>
+        forwardAsyncErrors(async () => {
+          return await waitForHMRCompleted(async () => {
+            const { entityId, subsetKey, fields, fieldsInternal } = request.body;
+            const entity = EntityManager.get(entityId);
+            entity.subsets[subsetKey] = fields;
+            if (fieldsInternal !== undefined) {
+              if (fieldsInternal.length > 0) {
+                entity.subsetsInternal[subsetKey] = fieldsInternal;
+              } else {
+                delete entity.subsetsInternal[subsetKey];
+              }
             }
-          }
-          await entity.save();
+            await entity.save();
 
-          return { updated: fields, updatedInternal: fieldsInternal };
-        });
-      });
+            return { updated: fields, updatedInternal: fieldsInternal };
+          });
+        }),
+      );
 
       server.post<{
         Body: {
           entityId: string;
           subsetKey: string;
         };
-      }>("/api/entity/delSubset", async (request) => {
-        return await waitForHMRCompleted(async () => {
-          const { entityId, subsetKey } = request.body;
-          const entity = EntityManager.get(entityId);
-          delete entity.subsets[subsetKey];
-          delete entity.subsetsInternal[subsetKey];
-          await entity.save();
+      }>("/api/entity/delSubset", (request) =>
+        forwardAsyncErrors(async () => {
+          return await waitForHMRCompleted(async () => {
+            const { entityId, subsetKey } = request.body;
+            const entity = EntityManager.get(entityId);
+            delete entity.subsets[subsetKey];
+            delete entity.subsetsInternal[subsetKey];
+            await entity.save();
 
-          return 1;
-        });
-      });
+            return 1;
+          });
+        }),
+      );
 
       server.post<{
         Body: {
@@ -446,14 +482,16 @@ export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
           newProp: EntityProp;
           at?: number;
         };
-      }>("/api/entity/createProp", async (request) => {
-        return await waitForHMRCompleted(async () => {
-          const { entityId, at, newProp } = request.body;
-          const entity = EntityManager.get(entityId);
-          await entity.createProp(newProp, at);
-          return true;
-        });
-      });
+      }>("/api/entity/createProp", (request) =>
+        forwardAsyncErrors(async () => {
+          return await waitForHMRCompleted(async () => {
+            const { entityId, at, newProp } = request.body;
+            const entity = EntityManager.get(entityId);
+            await entity.createProp(newProp, at);
+            return true;
+          });
+        }),
+      );
 
       server.post<{
         Body: {
@@ -461,31 +499,35 @@ export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
           newProp: EntityProp;
           at: number;
         };
-      }>("/api/entity/modifyProp", async (request) => {
-        return await waitForHMRCompleted(async () => {
-          const { entityId, at, newProp } = request.body;
+      }>("/api/entity/modifyProp", (request) =>
+        forwardAsyncErrors(async () => {
+          return await waitForHMRCompleted(async () => {
+            const { entityId, at, newProp } = request.body;
 
-          const entity = EntityManager.get(entityId);
-          entity.modifyProp(newProp, at);
+            const entity = EntityManager.get(entityId);
+            entity.modifyProp(newProp, at);
 
-          return true;
-        });
-      });
+            return true;
+          });
+        }),
+      );
 
       server.post<{
         Body: {
           entityId: string;
           at: number;
         };
-      }>("/api/entity/delProp", async (request) => {
-        return await waitForHMRCompleted(async () => {
-          const { entityId, at } = request.body;
+      }>("/api/entity/delProp", (request) =>
+        forwardAsyncErrors(async () => {
+          return await waitForHMRCompleted(async () => {
+            const { entityId, at } = request.body;
 
-          const entity = EntityManager.get(entityId);
-          entity.delProp(at);
-          return true;
-        });
-      });
+            const entity = EntityManager.get(entityId);
+            entity.delProp(at);
+            return true;
+          });
+        }),
+      );
 
       server.post<{
         Body: {
@@ -493,76 +535,84 @@ export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
           at: number;
           to: number;
         };
-      }>("/api/entity/moveProp", async (request) => {
-        return await waitForHMRCompleted(async () => {
-          const { entityId, at, to } = request.body;
+      }>("/api/entity/moveProp", (request) =>
+        forwardAsyncErrors(async () => {
+          return await waitForHMRCompleted(async () => {
+            const { entityId, at, to } = request.body;
 
-          const entity = EntityManager.get(entityId);
-          entity.moveProp(at, to);
+            const entity = EntityManager.get(entityId);
+            entity.moveProp(at, to);
 
-          return true;
-        });
-      });
+            return true;
+          });
+        }),
+      );
 
       server.post<{
         Body: {
           entityId: string;
           indexes: EntityIndex[];
         };
-      }>("/api/entity/modifyIndexes", async (request) => {
-        return await waitForHMRCompleted(async () => {
-          const { entityId, indexes } = request.body;
-          const entity = EntityManager.get(entityId);
-          entity.indexes = indexes;
-          await entity.save();
+      }>("/api/entity/modifyIndexes", (request) =>
+        forwardAsyncErrors(async () => {
+          return await waitForHMRCompleted(async () => {
+            const { entityId, indexes } = request.body;
+            const entity = EntityManager.get(entityId);
+            entity.indexes = indexes;
+            await entity.save();
 
-          return { updated: indexes };
-        });
-      });
+            return { updated: indexes };
+          });
+        }),
+      );
 
       server.post<{
         Body: {
           entityId: string;
           enumLabels: Entity["enumLabels"];
         };
-      }>("/api/entity/modifyEnumLabels", async (request) => {
-        return await waitForHMRCompleted(async () => {
-          const { entityId, enumLabels } = request.body;
-          const entity = EntityManager.get(entityId);
-          entity.enumLabels = enumLabels;
-          await entity.save();
+      }>("/api/entity/modifyEnumLabels", (request) =>
+        forwardAsyncErrors(async () => {
+          return await waitForHMRCompleted(async () => {
+            const { entityId, enumLabels } = request.body;
+            const entity = EntityManager.get(entityId);
+            entity.enumLabels = enumLabels;
+            await entity.save();
 
-          return { updated: enumLabels };
-        });
-      });
+            return { updated: enumLabels };
+          });
+        }),
+      );
 
       server.post<{
         Body: {
           entityId: string;
           newEnumId: string;
         };
-      }>("/api/entity/createEnumId", async (request) => {
-        return await waitForHMRCompleted(async () => {
-          const { entityId, newEnumId } = request.body;
-          const entity = EntityManager.get(entityId);
+      }>("/api/entity/createEnumId", (request) =>
+        forwardAsyncErrors(async () => {
+          return await waitForHMRCompleted(async () => {
+            const { entityId, newEnumId } = request.body;
+            const entity = EntityManager.get(entityId);
 
-          if (entity.enumLabels[newEnumId]) {
-            throw new Error(`이미 존재하는 enumId입니다: ${newEnumId}`);
-          }
+            if (entity.enumLabels[newEnumId]) {
+              throw new Error(`이미 존재하는 enumId입니다: ${newEnumId}`);
+            }
 
-          entity.enumLabels[newEnumId] = newEnumId.endsWith("Status")
-            ? {
-                active: "노출",
-                hidden: "숨김",
-              }
-            : {
-                "": "",
-              };
-          await entity.save();
+            entity.enumLabels[newEnumId] = newEnumId.endsWith("Status")
+              ? {
+                  active: "노출",
+                  hidden: "숨김",
+                }
+              : {
+                  "": "",
+                };
+            await entity.save();
 
-          return 1;
-        });
-      });
+            return 1;
+          });
+        }),
+      );
 
       server.post<{
         Body: {
@@ -572,58 +622,62 @@ export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
             after: string;
           };
         };
-      }>("/api/entity/modifyEnumId", async (request) => {
-        return await waitForHMRCompleted(async () => {
-          const { entityId, enumId } = request.body;
-          const entityIds = EntityManager.getAllIds();
-          const isExists = entityIds.some((entityId) => {
-            const entity = EntityManager.get(entityId);
-            return Object.keys(entity.enumLabels).includes(enumId.after);
-          });
-          if (isExists) {
-            throw new Error(`이미 존재하는 EnumId입니다: ${enumId.after}`);
-          }
+      }>("/api/entity/modifyEnumId", (request) =>
+        forwardAsyncErrors(async () => {
+          return await waitForHMRCompleted(async () => {
+            const { entityId, enumId } = request.body;
+            const entityIds = EntityManager.getAllIds();
+            const isExists = entityIds.some((candidateEntityId) => {
+              const candidateEntity = EntityManager.get(candidateEntityId);
+              return Object.keys(candidateEntity.enumLabels).includes(enumId.after);
+            });
+            if (isExists) {
+              throw new Error(`이미 존재하는 EnumId입니다: ${enumId.after}`);
+            }
 
-          const entity = EntityManager.get(entityId);
-          entity.enumLabels[enumId.after] = entity.enumLabels[enumId.before];
-          delete entity.enumLabels[enumId.before];
+            const entity = EntityManager.get(entityId);
+            entity.enumLabels[enumId.after] = entity.enumLabels[enumId.before];
+            delete entity.enumLabels[enumId.before];
 
-          await entity.save();
+            await entity.save();
 
-          for (const entityId of entityIds) {
-            const entity = EntityManager.get(entityId);
-            for (const prop of entity.props) {
-              if (prop.type === "enum" && prop.id === enumId.before) {
-                prop.id = enumId.after;
+            for (const relatedEntityId of entityIds) {
+              const relatedEntity = EntityManager.get(relatedEntityId);
+              for (const prop of relatedEntity.props) {
+                if (prop.type === "enum" && prop.id === enumId.before) {
+                  prop.id = enumId.after;
+                }
               }
+              await relatedEntity.save();
             }
-            await entity.save();
-          }
-        });
-      });
+          });
+        }),
+      );
 
       server.post<{
         Body: {
           entityId: string;
           enumId: string;
         };
-      }>("/api/entity/deleteEnumId", async (request) => {
-        return await waitForHMRCompleted(async () => {
-          const { entityId, enumId } = request.body;
-
-          const entityIds = EntityManager.getAllIds();
-          const isReferenced = entityIds
-            .flatMap((entityId) => EntityManager.get(entityId).props)
-            .some((prop) => prop.type === "enum" && prop.id === enumId);
-          if (isReferenced) {
-            throw new Error(`${enumId}를 참조하는 프로퍼티가 존재합니다.`);
-          }
+      }>("/api/entity/deleteEnumId", (request) =>
+        forwardAsyncErrors(async () => {
+          return await waitForHMRCompleted(async () => {
+            const { entityId, enumId } = request.body;
+
+            const entityIds = EntityManager.getAllIds();
+            const isReferenced = entityIds
+              .flatMap((referencingEntityId) => EntityManager.get(referencingEntityId).props)
+              .some((prop) => prop.type === "enum" && prop.id === enumId);
+            if (isReferenced) {
+              throw new Error(`${enumId}를 참조하는 프로퍼티가 존재합니다.`);
+            }
 
-          const entity = EntityManager.get(entityId);
-          delete entity.enumLabels[enumId];
-          await entity.save();
-        });
-      });
+            const entity = EntityManager.get(entityId);
+            delete entity.enumLabels[enumId];
+            await entity.save();
+          });
+        }),
+      );
 
       server.post<{
         Body: {
@@ -634,28 +688,32 @@ export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
           subsetKey?: string;
           cone: Cone;
         };
-      }>("/api/entity/updateCone", async (request) => {
-        return await waitForHMRCompleted(async () => {
-          const { entityId, target, propName, enumId, subsetKey, cone } = request.body;
-          const entity = EntityManager.get(entityId);
+      }>("/api/entity/updateCone", (request) =>
+        forwardAsyncErrors(async () => {
+          return await waitForHMRCompleted(async () => {
+            const { entityId, target, propName, enumId, subsetKey, cone } = request.body;
+            const entity = EntityManager.get(entityId);
 
-          if (target === "entity") {
-            entity.cone = cone;
-          } else if (target === "prop" && propName) {
-            const prop = entity.props.find((p) => p.name === propName);
-            if (prop) {
-              (prop as { cone?: Cone }).cone = cone;
+            if (target === "entity") {
+              entity.cone = cone;
+            } else if (target === "prop" && propName) {
+              const prop = entity.props.find((p) => p.name === propName);
+              if (prop) {
+                /* SAFETY: UI 도구의 Zod 입력 스키마가 이 값의 타입을 보장한다. */ (
+                  prop as { cone?: Cone }
+                ).cone = cone;
+              }
+            } else if (target === "enum" && enumId) {
+              entity.enumCones[enumId] = cone;
+            } else if (target === "subset" && subsetKey) {
+              entity.subsetCones[subsetKey] = cone;
             }
-          } else if (target === "enum" && enumId) {
-            entity.enumCones[enumId] = cone;
-          } else if (target === "subset" && subsetKey) {
-            entity.subsetCones[subsetKey] = cone;
-          }
 
-          await entity.save();
-          return true;
-        });
-      });
+            await entity.save();
+            return true;
+          });
+        }),
+      );
 
       server.post<{
         Body: {
@@ -673,6 +731,7 @@ export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
             const entity = EntityManager.get(entityId);
 
             // locale 기본값: Sonamu.config.i18n.defaultLocale 사용
+            // SAFETY: i18n 구성 스키마가 지원 locale을 ko/en/ja로 제한한다.
             const effectiveLocale =
               locale ?? (Sonamu.config.i18n.defaultLocale as "ko" | "en" | "ja");
 
@@ -728,51 +787,55 @@ export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
         Querystring: {
           entityId: string;
         };
-      }>("/api/entity/getTableColumns", async (request) => {
-        const { entityId } = request.query;
-        const entity = EntityManager.get(entityId);
-        const columns = entity.getTableColumns();
-        return { columns };
-      });
+      }>("/api/entity/getTableColumns", (request) =>
+        forwardAsyncErrors(async () => {
+          const { entityId } = request.query;
+          const entity = EntityManager.get(entityId);
+          const columns = entity.getTableColumns();
+          return { columns };
+        }),
+      );
 
       server.post<{
         Body: {
           entityIds: string[];
           templateKeys: string[];
         };
-      }>("/api/scaffolding/getStatus", async (request) => {
-        const { entityIds, templateKeys: _templateKeys } = request.body;
-        if ((entityIds ?? []).length === 0) {
-          throw new BadRequestException(SD("sonamu.error.entityIdsRequired"));
-        } else if ((_templateKeys ?? []).length === 0) {
-          throw new BadRequestException(SD("sonamu.error.templateKeysRequired"));
-        }
+      }>("/api/scaffolding/getStatus", (request) =>
+        forwardAsyncErrors(async () => {
+          const { entityIds, templateKeys: _templateKeys } = request.body;
+          if ((entityIds ?? []).length === 0) {
+            throw new BadRequestException(SD("sonamu.error.entityIdsRequired"));
+          } else if ((_templateKeys ?? []).length === 0) {
+            throw new BadRequestException(SD("sonamu.error.templateKeysRequired"));
+          }
 
-        // sorting
-        entityIds.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
-        const templateKeys = TemplateKey.options.filter((tk) => _templateKeys.includes(tk));
+          // sorting
+          entityIds.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+          const templateKeys = TemplateKey.options.filter((tk) => _templateKeys.includes(tk));
 
-        const combinations = entityIds.flatMap((entityId) => {
-          return templateKeys.map((templateKey) => [entityId, templateKey]);
-        });
+          const combinations = entityIds.flatMap((entityId) => {
+            return templateKeys.map((templateKey) => [entityId, templateKey]);
+          });
 
-        const statuses = await Promise.all(
-          combinations.map(async ([entityId, templateKey]) => {
-            const { subPath, fullPath, isExists } = await Sonamu.syncer.checkExistsGenCode(
-              entityId,
-              templateKey as TemplateKey,
-            );
-            return {
-              entityId,
-              templateKey,
-              subPath,
-              fullPath,
-              isExists,
-            };
-          }),
-        );
-        return { statuses };
-      });
+          const statuses = await Promise.all(
+            combinations.map(async ([entityId, templateKey]) => {
+              const { subPath, fullPath, isExists } = await Sonamu.syncer.checkExistsGenCode(
+                entityId,
+                /* SAFETY: UI 도구의 Zod 입력 스키마가 이 값의 타입을 보장한다. */ templateKey as TemplateKey,
+              );
+              return {
+                entityId,
+                templateKey,
+                subPath,
+                fullPath,
+                isExists,
+              };
+            }),
+          );
+          return { statuses };
+        }),
+      );
 
       server.post<{
         Body: {
@@ -783,54 +846,53 @@ export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
             overwrite?: boolean;
           }[];
         };
-      }>("/api/scaffolding/generate", async (request) => {
-        const { options } = request.body;
-        if (options.length === 0) {
-          throw new BadRequestException(SD("sonamu.error.optionsRequired"));
-        }
-
-        // 1. 모든 템플릿에서 필요한 dict 키를 수집
-        const keys = options.flatMap(({ templateKey }) => {
-          const template = TemplateManager.get(templateKey);
-          return template.getRequiredDictKeys() ?? [];
-        });
+      }>("/api/scaffolding/generate", (request) =>
+        forwardAsyncErrors(async () => {
+          const { options } = request.body;
+          if (options.length === 0) {
+            throw new BadRequestException(SD("sonamu.error.optionsRequired"));
+          }
 
-        // 2. target별로 ensureDictKeys 호출 (순차 처리)
-        await sonamuDictionary.ensureDictKeys([...new Set(keys)]);
+          // 1. 모든 템플릿에서 필요한 dict 키를 수집
+          const keys = options.flatMap(({ templateKey }) => {
+            const template = TemplateManager.get(templateKey);
+            return template.getRequiredDictKeys() ?? [];
+          });
 
-        // 3. 템플릿 생성 (병렬 처리)
-        const result = await Promise.all(
-          options.map(async ({ entityId, templateKey, enumId, overwrite }) => {
-            try {
-              return await Sonamu.syncer.generateTemplate(
-                templateKey as TemplateKey,
-                {
-                  entityId,
-                  enumId,
-                } as {
-                  entityId: string;
-                  enumId?: string;
-                },
-                {
-                  overwrite,
-                },
-              );
-            } catch (e) {
-              if (isSoException(e) && e.statusCode === 541) {
-                return null;
-              } else {
-                console.error(e);
-                throw e;
+          // 2. target별로 ensureDictKeys 호출 (순차 처리)
+          await sonamuDictionary.ensureDictKeys([...new Set(keys)]);
+
+          // 3. 템플릿 생성 (병렬 처리)
+          const result = await Promise.all(
+            options.map(async ({ entityId, templateKey, enumId, overwrite }) => {
+              try {
+                return await Sonamu.syncer.generateTemplate(
+                  /* SAFETY: UI 도구의 Zod 입력 스키마가 이 값의 타입을 보장한다. */ templateKey as TemplateKey,
+                  /* SAFETY: UI 도구의 Zod 입력 스키마가 Entity 템플릿 옵션을 보장한다. */ {
+                    entityId,
+                    enumId,
+                  } as EntityTemplateInput,
+                  {
+                    overwrite,
+                  },
+                );
+              } catch (e) {
+                if (isSoException(e) && e.statusCode === 541) {
+                  return null;
+                } else {
+                  console.error(e);
+                  throw e;
+                }
               }
-            }
-          }),
-        );
+            }),
+          );
 
-        if (result.filter(nonNullable).length === 0) {
-          throw new ServiceUnavailableException(SD("sonamu.error.allFilesGenerated"));
-        }
-        return result;
-      });
+          if (result.filter(nonNullable).length === 0) {
+            throw new ServiceUnavailableException(SD("sonamu.error.allFilesGenerated"));
+          }
+          return result;
+        }),
+      );
 
       server.post<{
         Body: {
@@ -840,48 +902,63 @@ export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
             enumId?: string;
           };
         };
-      }>("/api/scaffolding/preview", async (request): Promise<{ pathAndCodes: PathAndCode[] }> => {
-        const { option } = request.body;
+      }>(
+        "/api/scaffolding/preview",
+        (request): Promise<{ pathAndCodes: PathAndCode[] }> =>
+          forwardAsyncErrors(async () => {
+            const { option } = request.body;
 
-        try {
-          const { templateKey, ...templateOptions } = option;
-          const pathAndCodes = await Sonamu.syncer.renderTemplate(
-            templateKey as TemplateKey,
-            templateOptions,
-          );
-
-          return { pathAndCodes };
-        } catch (e) {
-          console.error(e);
-          throw e;
-        }
-      });
+            try {
+              const { templateKey, ...templateOptions } = option;
+              const pathAndCodes = await Sonamu.syncer.renderTemplate(
+                /* SAFETY: UI 도구의 Zod 입력 스키마가 이 값의 타입을 보장한다. */ templateKey as TemplateKey,
+                templateOptions,
+              );
 
-      server.post("/api/fixture", async (request) => {
-        const { sourceDB, targetDB, search, duplicateCheck } = request.body as {
-          sourceDB: keyof SonamuDBConfig;
-          targetDB: keyof SonamuDBConfig;
-          search: FixtureSearchOptions;
-          duplicateCheck?: DuplicateCheckOptions;
-        };
+              return { pathAndCodes };
+            } catch (e) {
+              console.error(e);
+              throw e;
+            }
+          }),
+      );
+
+      server.post("/api/fixture", (request) =>
+        forwardAsyncErrors(async () => {
+          const { sourceDB, targetDB, search, duplicateCheck } =
+            /* SAFETY: UI 도구의 Zod 입력 스키마가 이 값의 타입을 보장한다. */ request.body as {
+              sourceDB: keyof SonamuDBConfig;
+              targetDB: keyof SonamuDBConfig;
+              search: FixtureSearchOptions;
+              duplicateCheck?: DuplicateCheckOptions;
+            };
 
-        return FixtureManager.getFixtures(sourceDB, targetDB, search, duplicateCheck);
-      });
+          return FixtureManager.getFixtures(sourceDB, targetDB, search, duplicateCheck);
+        }),
+      );
 
-      server.post("/api/fixture/import", async (request) => {
-        const { db, fixtures } = request.body as {
-          db: keyof SonamuDBConfig;
-          fixtures: FixtureRecord[];
-        };
+      server.post("/api/fixture/import", (request) =>
+        forwardAsyncErrors(async () => {
+          const { db, fixtures } =
+            /* SAFETY: UI 도구의 Zod 입력 스키마가 이 값의 타입을 보장한다. */ request.body as {
+              db: keyof SonamuDBConfig;
+              fixtures: FixtureRecord[];
+            };
 
-        return FixtureManager.insertFixtures(db, fixtures);
-      });
+          return FixtureManager.insertFixtures(db, fixtures);
+        }),
+      );
 
-      server.post("/api/fixture/addFixtureLoader", async (request) => {
-        const { code } = request.body as { code: string };
+      server.post("/api/fixture/addFixtureLoader", (request) =>
+        forwardAsyncErrors(async () => {
+          const { code } =
+            /* SAFETY: UI 도구의 Zod 입력 스키마가 이 값의 타입을 보장한다. */ request.body as {
+              code: string;
+            };
 
-        return FixtureManager.addFixtureLoader(code);
-      });
+          return FixtureManager.addFixtureLoader(code);
+        }),
+      );
 
       server.get("/api/i18n/dictionary", async () => {
         return sonamuDictionary.getDictionary();
@@ -898,14 +975,16 @@ export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
           .send(buffer);
       });
 
-      server.post("/api/i18n/import", async (request) => {
-        const data = await request.file();
-        if (!data) {
-          throw new BadRequestException(SD("sonamu.error.fileNotUploaded"));
-        }
-        const buffer = await data.toBuffer();
-        return sonamuDictionary.importFromExcel(buffer);
-      });
+      server.post("/api/i18n/import", (request) =>
+        forwardAsyncErrors(async () => {
+          const data = await request.file();
+          if (!data) {
+            throw new BadRequestException(SD("sonamu.error.fileNotUploaded"));
+          }
+          const buffer = await data.toBuffer();
+          return sonamuDictionary.importFromExcel(buffer);
+        }),
+      );
 
       server.post<{
         Body: {
@@ -914,33 +993,41 @@ export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
           source: "entity" | "project" | "sonamu";
           values: Record<string, string>;
         };
-      }>("/api/i18n/update", async (request) => {
-        await sonamuDictionary.updateEntry(request.body);
-        return { success: true };
-      });
+      }>("/api/i18n/update", (request) =>
+        forwardAsyncErrors(async () => {
+          await sonamuDictionary.updateEntry(request.body);
+          return { success: true };
+        }),
+      );
 
       server.post<{
         Body: {
           key: string;
           values: Record<string, string>;
         };
-      }>("/api/i18n/create", async (request) => {
-        await sonamuDictionary.createEntry(request.body);
-        return { success: true };
-      });
+      }>("/api/i18n/create", (request) =>
+        forwardAsyncErrors(async () => {
+          await sonamuDictionary.createEntry(request.body);
+          return { success: true };
+        }),
+      );
 
       server.post<{
         Body: {
           key: string;
         };
-      }>("/api/i18n/delete", async (request) => {
-        await sonamuDictionary.deleteEntry(request.body.key);
-        return { success: true };
-      });
-
-      server.post<{ Body: { keys: string[] } }>("/api/i18n/checkUsage", async (request) => {
-        return sonamuDictionary.checkUsage(request.body.keys);
-      });
+      }>("/api/i18n/delete", (request) =>
+        forwardAsyncErrors(async () => {
+          await sonamuDictionary.deleteEntry(request.body.key);
+          return { success: true };
+        }),
+      );
+
+      server.post<{ Body: { keys: string[] } }>("/api/i18n/checkUsage", (request) =>
+        forwardAsyncErrors(async () => {
+          return sonamuDictionary.checkUsage(request.body.keys);
+        }),
+      );
 
       // Tasks API
       server.get("/api/tasks/status", async () => {
@@ -968,61 +1055,71 @@ export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
           createdAfter?: string;
           createdBefore?: string;
         };
-      }>("/api/tasks/workflowRuns", async (request) => {
-        const backend = Sonamu.workflows.backend;
-        const { limit, after, before, order, status, workflowName, createdAfter, createdBefore } =
-          request.query;
-        return backend.listWorkflowRuns({
-          limit: limit ? Number.parseInt(limit, 10) : undefined,
-          after,
-          before,
-          order,
-          status: status ? status.split(",") : undefined,
-          workflowName: workflowName || undefined,
-          createdAfter: createdAfter ? new Date(createdAfter) : undefined,
-          createdBefore: createdBefore ? new Date(createdBefore) : undefined,
-        });
-      });
+      }>("/api/tasks/workflowRuns", (request) =>
+        forwardAsyncErrors(async () => {
+          const backend = Sonamu.workflows.backend;
+          const { limit, after, before, order, status, workflowName, createdAfter, createdBefore } =
+            request.query;
+          return backend.listWorkflowRuns({
+            limit: limit ? Number.parseInt(limit, 10) : undefined,
+            after,
+            before,
+            order,
+            status: status ? status.split(",") : undefined,
+            workflowName: workflowName || undefined,
+            createdAfter: createdAfter ? new Date(createdAfter) : undefined,
+            createdBefore: createdBefore ? new Date(createdBefore) : undefined,
+          });
+        }),
+      );
 
       server.get<{
         Params: { id: string };
-      }>("/api/tasks/workflowRuns/:id", async (request) => {
-        const backend = Sonamu.workflows.backend;
-        const workflowRun = await backend.getWorkflowRun({
-          workflowRunId: request.params.id,
-        });
-        if (!workflowRun) {
-          throw new Error(`Workflow run not found: ${request.params.id}`);
-        }
-        return workflowRun;
-      });
+      }>("/api/tasks/workflowRuns/:id", (request) =>
+        forwardAsyncErrors(async () => {
+          const backend = Sonamu.workflows.backend;
+          const workflowRun = await backend.getWorkflowRun({
+            workflowRunId: request.params.id,
+          });
+          if (!workflowRun) {
+            throw new Error(`Workflow run not found: ${request.params.id}`);
+          }
+          return workflowRun;
+        }),
+      );
 
       server.post<{
         Params: { id: string };
-      }>("/api/tasks/workflowRuns/:id/cancel", async (request) => {
-        const backend = Sonamu.workflows.backend;
-        return backend.cancelWorkflowRun({
-          workflowRunId: request.params.id,
-        });
-      });
+      }>("/api/tasks/workflowRuns/:id/cancel", (request) =>
+        forwardAsyncErrors(async () => {
+          const backend = Sonamu.workflows.backend;
+          return backend.cancelWorkflowRun({
+            workflowRunId: request.params.id,
+          });
+        }),
+      );
 
       server.post<{
         Params: { id: string };
-      }>("/api/tasks/workflowRuns/:id/pause", async (request) => {
-        const backend = Sonamu.workflows.backend;
-        return backend.pauseWorkflowRun({
-          workflowRunId: request.params.id,
-        });
-      });
+      }>("/api/tasks/workflowRuns/:id/pause", (request) =>
+        forwardAsyncErrors(async () => {
+          const backend = Sonamu.workflows.backend;
+          return backend.pauseWorkflowRun({
+            workflowRunId: request.params.id,
+          });
+        }),
+      );
 
       server.post<{
         Params: { id: string };
-      }>("/api/tasks/workflowRuns/:id/resume", async (request) => {
-        const backend = Sonamu.workflows.backend;
-        return backend.resumeWorkflowRun({
-          workflowRunId: request.params.id,
-        });
-      });
+      }>("/api/tasks/workflowRuns/:id/resume", (request) =>
+        forwardAsyncErrors(async () => {
+          const backend = Sonamu.workflows.backend;
+          return backend.resumeWorkflowRun({
+            workflowRunId: request.params.id,
+          });
+        }),
+      );
 
       server.get<{
         Params: { id: string };
@@ -1031,32 +1128,36 @@ export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
           after?: string;
           before?: string;
         };
-      }>("/api/tasks/workflowRuns/:id/steps", async (request) => {
-        const backend = Sonamu.workflows.backend;
-        const { limit, after, before } = request.query;
-        return backend.listStepAttempts({
-          workflowRunId: request.params.id,
-          limit: limit ? Number.parseInt(limit, 10) : undefined,
-          after,
-          before,
-        });
-      });
+      }>("/api/tasks/workflowRuns/:id/steps", (request) =>
+        forwardAsyncErrors(async () => {
+          const backend = Sonamu.workflows.backend;
+          const { limit, after, before } = request.query;
+          return backend.listStepAttempts({
+            workflowRunId: request.params.id,
+            limit: limit ? Number.parseInt(limit, 10) : undefined,
+            after,
+            before,
+          });
+        }),
+      );
 
       /**
        * Health Check API
        * MCP 도구가 Sonamu 서버를 자동 감지하기 위한 엔드포인트
        */
-      server.get("/api/sonamu/health", async (request) => {
-        const address = request.server.server.address();
-        const port = address && typeof address === "object" ? address.port : 0;
-
-        return {
-          ok: true,
-          project: process.cwd().split("/").pop() || "unknown",
-          port,
-          timestamp: new Date().toISOString(),
-        };
-      });
+      server.get("/api/sonamu/health", (request) =>
+        forwardAsyncErrors(async () => {
+          const address = request.server.server.address();
+          const port = address && isObjectValue(address) ? address.port : 0;
+
+          return {
+            ok: true,
+            project: process.cwd().split("/").pop() || "unknown",
+            port,
+            timestamp: new Date().toISOString(),
+          };
+        }),
+      );
 
       /**
        * Fixture 생성 API
@@ -1065,7 +1166,7 @@ export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
         Body: {
           entity: string;
           count?: number;
-          overrides?: Record<string, unknown>;
+          overrides?: FixtureGenerationSpec["overrides"];
           targetDb?: "fixture" | "test";
         };
       }>("/api/sonamu/fixture/generate", async (request, reply) => {
@@ -1116,7 +1217,7 @@ export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
           entity: string;
           strategy: "sample" | "recent" | "random" | "query";
           limit?: number;
-          where?: Record<string, unknown>;
+          where?: DataExplorerOptions["where"];
         };
       }>("/api/sonamu/fixture/explore", async (request, reply) => {
         const { entity, strategy, limit = 10, where } = request.body;
@@ -1265,35 +1366,45 @@ export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
         return getCddTree();
       });
 
-      server.post<{ Body: { filePath: string } }>("/api/cdd/readContent", async (request) => {
-        const { filePath } = request.body;
-        return readContent(filePath);
-      });
-
-      server.post<{ Body: { filePath: string } }>("/api/cdd/editContent", async (request) => {
-        const { filePath } = request.body;
-        return editContent(filePath);
-      });
-
-      server.post<{ Body: { filePath: string } }>("/api/cdd/openSource", async (request) => {
-        const { filePath } = request.body;
-        openSourceFile(filePath);
-        return { success: true };
-      });
+      server.post<{ Body: { filePath: string } }>("/api/cdd/readContent", (request) =>
+        forwardAsyncErrors(async () => {
+          const { filePath } = request.body;
+          return readContent(filePath);
+        }),
+      );
+
+      server.post<{ Body: { filePath: string } }>("/api/cdd/editContent", (request) =>
+        forwardAsyncErrors(async () => {
+          const { filePath } = request.body;
+          return editContent(filePath);
+        }),
+      );
+
+      server.post<{ Body: { filePath: string } }>("/api/cdd/openSource", (request) =>
+        forwardAsyncErrors(async () => {
+          const { filePath } = request.body;
+          openSourceFile(filePath);
+          return { success: true };
+        }),
+      );
 
       // CDD Rules API
       server.get("/api/cdd/rules", async () => {
         return listRules();
       });
 
-      server.post<{ Body: { ruleKey: string } }>("/api/cdd/readRule", async (request) => {
-        const { ruleKey } = request.body;
-        return readRule(ruleKey);
-      });
-
-      server.post<{ Body: CddAddRuleRequest }>("/api/cdd/addRule", async (request) => {
-        return addRule(request.body);
-      });
+      server.post<{ Body: { ruleKey: string } }>("/api/cdd/readRule", (request) =>
+        forwardAsyncErrors(async () => {
+          const { ruleKey } = request.body;
+          return readRule(ruleKey);
+        }),
+      );
+
+      server.post<{ Body: CddAddRuleRequest }>("/api/cdd/addRule", (request) =>
+        forwardAsyncErrors(async () => {
+          return addRule(request.body);
+        }),
+      );
 
       // CDD AC API
       server.get("/api/cdd/ac", async () => {