refactor: Implement Zod schema validation for inventory effect payloads and enhance item route DTO type safety.

bot/modules/inventory/effect.registry.ts

@@ -7,7 +7,10 @@ import {
     handleColorRole,
     handleLootbox
 } from "./effect.handlers";
-import type { EffectHandler } from "./effect.types";
+import type { EffectHandler, ValidatedEffectPayload } from "./effect.types";
+import { EffectPayloadSchema } from "./effect.types";
+import { UserError } from "@shared/lib/errors";
+import type { Transaction } from "@shared/lib/types";
 
 export const effectHandlers: Record<string, EffectHandler> = {
     'ADD_XP': handleAddXp,
@@ -18,3 +21,21 @@ export const effectHandlers: Record<string, EffectHandler> = {
     'COLOR_ROLE': handleColorRole,
     'LOOTBOX': handleLootbox
 };
+
+export async function validateAndExecuteEffect(
+    effect: unknown,
+    userId: string,
+    tx: Transaction
+) {
+    const result = EffectPayloadSchema.safeParse(effect);
+    if (!result.success) {
+        throw new UserError(`Invalid effect configuration: ${result.error.message}`);
+    }
+
+    const handler = effectHandlers[result.data.type];
+    if (!handler) {
+        throw new UserError(`Unknown effect type: ${result.data.type}`);
+    }
+
+    return handler(userId, result.data, tx);
+}