AgentSkillsCN

zod

在仓库中使用Zod的约定（schemas文件夹、越南语消息、与react-hook-form和服务器操作的集成）。

SKILL.md
--- frontmatter
name: zod
description: Quy ước dùng Zod trong repo (schemas folder, Vietnamese messages, integration với react-hook-form và server actions).

Nguồn trong repo

  • •Schemas: apps/web/src/schemas/*.ts
    • •Ví dụ: apps/web/src/schemas/blog.ts
  • •Resolver: @hookform/resolvers/zod (đã dùng trong admin forms).

Quy ước

  • •Định nghĩa schema ở apps/web/src/schemas/<domain>.ts.
  • •Xuất type bằng z.infer<typeof schema> để không bị drift.
  • •Message validation phải tiếng Việt (giữ thuật ngữ kỹ thuật English khi cần).

Pattern hay dùng (CẬP NHẬT ZOD V4)

  • •Optional + nullable (match DB):
    • •z.string().max(160).optional().nullable()
  • •UUID:
    • •z.string().uuid()
  • •Enum status:
    • •z.enum(['draft', 'published', 'archived'], { error: 'Trạng thái không hợp lệ' })
  • •Zod v4: Dùng error: thay vì message: cho custom errors:
    typescript
    // Zod 4 pattern (KHUYẾN NGHỊ)
z.string().min(5, { error: "Quá ngắn, tối thiểu 5 ký tự" })

// Zod 3 pattern (vẫn hoạt động nhưng không khuyến nghị)
z.string().min(5, { message: "Quá ngắn" })

Với react-hook-form

  • •resolver: zodResolver(schema)
  • •Prefer useForm<FormData, unknown, FormData> để types khớp.

Với server actions / route handlers

  • •Validate input bằng schema.safeParse(data).
  • •Không throw raw ZodError ra UI; map sang message tiếng Việt hoặc cấu trúc lỗi form.

Tránh

  • •Tránh z.any() (repo strict TS). Nếu cần, dùng z.unknown() và refine.
  • •Tránh duplicate rule giữa client & server; schema nên dùng chung.