feat(frontend): drive form validation from Zod schemas

NodeFormModal — full conversion to AntD Form.useForm with antdRule
on every required field. Inline field errors replace the single
'fillRequired' toast. testConnection now runs validateFields(['address','port'])
before sending.

ClientFormModal and ClientBulkAddModal — minimal conversion: keep the
existing useState-driven controlled-component pattern, but replace the
hand-rolled `if (!form.x)` checks with schema.safeParse(form). The
schema is the single source of truth for required-ness and types;
ClientCreateFormSchema layers on the create-only `inboundIds.min(1)` rule.

New schemas (in src/schemas/):
  NodeFormSchema (node.ts)
  ClientFormSchema / ClientCreateFormSchema (client.ts)
  ClientBulkAddFormSchema (client.ts)

Other 16+ form modals stay on the current pattern — the antdRule adapter
ships from the first Zod pass for opportunistic migration as forms are
touched.

frontend/src/pages/clients/ClientBulkAddModal.tsx

@@ -9,6 +9,7 @@ import { HttpUtil, RandomUtil, SizeFormatter } from '@/utils';
 import { TLS_FLOW_CONTROL } from '@/models/inbound';
 import DateTimePicker from '@/components/DateTimePicker';
 import type { InboundOption } from '@/hooks/useClients';
+import { ClientBulkAddFormSchema, type ClientBulkAddFormValues } from '@/schemas/client';
 
 const FLOW_OPTIONS = Object.values(TLS_FLOW_CONTROL);
 const JSON_HEADERS = { headers: { 'Content-Type': 'application/json' } } as const;
@@ -17,11 +18,6 @@ const MULTI_CLIENT_PROTOCOLS = new Set([
   'shadowsocks', 'vless', 'vmess', 'trojan', 'hysteria', 'hysteria2',
 ]);
 
-interface ApiMsg {
-  success?: boolean;
-  msg?: string;
-}
-
 interface ClientBulkAddModalProps {
   open: boolean;
   inbounds: InboundOption[];
@@ -30,21 +26,7 @@ interface ClientBulkAddModalProps {
   onSaved?: () => void;
 }
 
-interface FormState {
+type FormState = ClientBulkAddFormValues;
-  emailMethod: number;
-  firstNum: number;
-  lastNum: number;
-  emailPrefix: string;
-  emailPostfix: string;
-  quantity: number;
-  subId: string;
-  comment: string;
-  flow: string;
-  limitIp: number;
-  totalGB: number;
-  expiryTime: number;
-  inboundIds: number[];
-}
 
 function emptyForm(): FormState {
   return {
@@ -152,8 +134,9 @@ export default function ClientBulkAddModal({
   }
 
   async function submit() {
-    if (!Array.isArray(form.inboundIds) || form.inboundIds.length === 0) {
+    const validated = ClientBulkAddFormSchema.safeParse(form);
-      messageApi.error(t('pages.clients.selectInbound'));
+    if (!validated.success) {
+      messageApi.error(t(validated.error.issues[0]?.message ?? 'somethingWentWrong'));
       return;
     }
     const emails = buildEmails();
@@ -177,7 +160,7 @@ export default function ClientBulkAddModal({
           enable: true,
         };
         const payload = { client, inboundIds: form.inboundIds };
-        return HttpUtil.post('/panel/api/clients/add', payload, silentJsonOpts) as Promise<ApiMsg>;
+        return HttpUtil.post('/panel/api/clients/add', payload, silentJsonOpts);
       }));
       let ok = 0;
       let failed = 0;

frontend/src/pages/clients/ClientFormModal.tsx

@@ -21,6 +21,7 @@ import { HttpUtil, RandomUtil } from '@/utils';
 import DateTimePicker from '@/components/DateTimePicker';
 import { TLS_FLOW_CONTROL } from '@/models/inbound';
 import type { ClientRecord, InboundOption } from '@/hooks/useClients';
+import { ClientFormSchema, ClientCreateFormSchema } from '@/schemas/client';
 import './ClientFormModal.css';
 
 const FLOW_OPTIONS = Object.values(TLS_FLOW_CONTROL);
@@ -268,12 +269,27 @@ export default function ClientFormModal({
   }
 
   async function onSubmit() {
-    if (!form.email || form.email.trim() === '') {
+    const schema = isEdit ? ClientFormSchema : ClientCreateFormSchema;
-      messageApi.error(`${t('pages.clients.email')} *`);
+    const validated = schema.safeParse({
-      return;
+      email: form.email,
-    }
+      subId: form.subId,
-    if (!isEdit && (!form.inboundIds || form.inboundIds.length === 0)) {
+      uuid: form.uuid,
-      messageApi.error(t('pages.clients.selectInbound'));
+      password: form.password,
+      auth: form.auth,
+      flow: form.flow,
+      reverseTag: form.reverseTag,
+      totalGB: form.totalGB,
+      delayedStart: form.delayedStart,
+      delayedDays: form.delayedDays,
+      limitIp: form.limitIp,
+      tgId: form.tgId,
+      comment: form.comment,
+      enable: form.enable,
+      inboundIds: form.inboundIds,
+    });
+    if (!validated.success) {
+      const issue = validated.error.issues[0];
+      messageApi.error(t(issue?.message ?? 'somethingWentWrong'));
       return;
     }
     const expiryTime = form.delayedStart

frontend/src/pages/nodes/NodeFormModal.tsx

@@ -15,7 +15,8 @@ import {
 } from 'antd';
 import type { NodeRecord } from '@/api/queries/useNodesQuery';
 import type { Msg } from '@/utils';
-import type { ProbeResult } from '@/schemas/node';
+import { NodeFormSchema, type NodeFormValues, type ProbeResult } from '@/schemas/node';
+import { antdRule } from '@/utils/zodForm';
 import './NodeFormModal.css';
 
 type Mode = 'add' | 'edit';
@@ -29,20 +30,7 @@ interface NodeFormModalProps {
   onOpenChange: (open: boolean) => void;
 }
 
-interface FormState {
+function defaultValues(): NodeFormValues {
-  id: number;
-  name: string;
-  remark: string;
-  scheme: 'http' | 'https';
-  address: string;
-  port: number;
-  basePath: string;
-  apiToken: string;
-  enable: boolean;
-  allowPrivateAddress: boolean;
-}
-
-function defaultForm(): FormState {
   return {
     id: 0,
     name: '',
@@ -66,68 +54,59 @@ export default function NodeFormModal({
   onOpenChange,
 }: NodeFormModalProps) {
   const { t } = useTranslation();
+  const [form] = Form.useForm<NodeFormValues>();
   const [messageApi, messageContextHolder] = message.useMessage();
 
-  const [form, setForm] = useState<FormState>(defaultForm);
   const [submitting, setSubmitting] = useState(false);
   const [testing, setTesting] = useState(false);
-  const [testResult, setTestResult] = useState<{
+  const [testResult, setTestResult] = useState<ProbeResult | null>(null);
-    status: string;
-    latencyMs?: number;
-    xrayVersion?: string;
-    error?: string;
-  } | null>(null);
 
   useEffect(() => {
     if (!open) return;
-    const base = defaultForm();
+    const base = defaultValues();
-    const next: FormState = mode === 'edit' && node
+    const next: NodeFormValues = mode === 'edit' && node
       ? {
         ...base,
-        ...(node as unknown as Partial<FormState>),
+        ...(node as unknown as Partial<NodeFormValues>),
         id: node.id,
         scheme: (node.scheme as 'http' | 'https') || base.scheme,
       }
       : base;
-     
+    form.resetFields();
-    setForm(next);
+    form.setFieldsValue(next);
     setTestResult(null);
-     
+  }, [open, mode, node, form]);
-  }, [open, mode, node]);
 
   const title = useMemo(
     () => (mode === 'edit' ? t('pages.nodes.editNode') : t('pages.nodes.addNode')),
     [mode, t],
   );
 
-  function buildPayload(): Partial<NodeRecord> {
+  function buildPayload(values: NodeFormValues): Partial<NodeRecord> {
     return {
-      id: form.id || 0,
+      id: values.id || 0,
-      name: form.name?.trim() || '',
+      name: values.name.trim(),
-      remark: form.remark?.trim() || '',
+      remark: values.remark?.trim() || '',
-      scheme: form.scheme || 'https',
+      scheme: values.scheme,
-      address: form.address?.trim() || '',
+      address: values.address.trim(),
-      port: Number(form.port) || 0,
+      port: values.port,
-      basePath: form.basePath?.trim() || '/',
+      basePath: values.basePath.trim() || '/',
-      apiToken: form.apiToken?.trim() || '',
+      apiToken: values.apiToken.trim(),
-      enable: !!form.enable,
+      enable: values.enable,
-      allowPrivateAddress: !!form.allowPrivateAddress,
+      allowPrivateAddress: values.allowPrivateAddress,
     };
   }
 
-  function update<K extends keyof FormState>(key: K, value: FormState[K]) {
-    setForm((prev) => ({ ...prev, [key]: value }));
-  }
-
   async function onTest() {
+    try {
+      await form.validateFields(['address', 'port']);
+    } catch {
+      return;
+    }
     setTesting(true);
     setTestResult(null);
     try {
-      const payload = buildPayload();
+      const payload = buildPayload(form.getFieldsValue(true));
-      if (!payload.address || !payload.port) {
-        messageApi.error(t('pages.nodes.toasts.fillRequired'));
-        return;
-      }
       const msg = await testConnection(payload);
       if (msg?.success && msg.obj) {
         setTestResult(msg.obj);
@@ -139,15 +118,15 @@ export default function NodeFormModal({
     }
   }
 
-  async function onSave() {
+  async function onFinish(values: NodeFormValues) {
-    const payload = buildPayload();
+    const result = NodeFormSchema.safeParse(values);
-    if (!payload.name || !payload.address || !payload.port) {
+    if (!result.success) {
-      messageApi.error(t('pages.nodes.toasts.fillRequired'));
+      messageApi.error(t(result.error.issues[0]?.message ?? 'pages.nodes.toasts.fillRequired'));
       return;
     }
     setSubmitting(true);
     try {
-      const msg = await save(payload);
+      const msg = await save(buildPayload(result.data));
       if (msg?.success) {
         onOpenChange(false);
       }
@@ -171,33 +150,36 @@ export default function NodeFormModal({
         cancelText={t('cancel')}
         mask={{ closable: false }}
         width="640px"
-      onOk={onSave}
+        onOk={() => form.submit()}
         onCancel={close}
       >
-      <Form layout="vertical">
+        <Form
+          form={form}
+          layout="vertical"
+          initialValues={defaultValues()}
+          onFinish={onFinish}
+        >
           <Row gutter={16}>
             <Col xs={24} md={12}>
-            <Form.Item label={t('pages.nodes.name')} required>
+              <Form.Item
-              <Input
+                label={t('pages.nodes.name')}
-                value={form.name}
+                name="name"
-                placeholder={t('pages.nodes.namePlaceholder')}
+                rules={[antdRule(NodeFormSchema.shape.name, t)]}
-                onChange={(e) => update('name', e.target.value)}
+              >
-              />
+                <Input placeholder={t('pages.nodes.namePlaceholder')} />
               </Form.Item>
             </Col>
             <Col xs={24} md={12}>
-            <Form.Item label={t('pages.nodes.remark')}>
+              <Form.Item label={t('pages.nodes.remark')} name="remark">
-              <Input value={form.remark} onChange={(e) => update('remark', e.target.value)} />
+                <Input />
               </Form.Item>
             </Col>
           </Row>
 
           <Row gutter={16}>
             <Col xs={24} md={6}>
-            <Form.Item label={t('pages.nodes.scheme')}>
+              <Form.Item label={t('pages.nodes.scheme')} name="scheme">
                 <Select
-                value={form.scheme}
-                onChange={(v) => update('scheme', v)}
                   options={[
                     { value: 'https', label: 'https' },
                     { value: 'http', label: 'http' },
@@ -206,59 +188,58 @@ export default function NodeFormModal({
               </Form.Item>
             </Col>
             <Col xs={24} md={12}>
-            <Form.Item label={t('pages.nodes.address')} required>
+              <Form.Item
-              <Input
+                label={t('pages.nodes.address')}
-                value={form.address}
+                name="address"
-                placeholder={t('pages.nodes.addressPlaceholder')}
+                rules={[antdRule(NodeFormSchema.shape.address, t)]}
-                onChange={(e) => update('address', e.target.value)}
+              >
-              />
+                <Input placeholder={t('pages.nodes.addressPlaceholder')} />
               </Form.Item>
             </Col>
             <Col xs={24} md={6}>
-            <Form.Item label={t('pages.nodes.port')} required>
+              <Form.Item
-              <InputNumber
+                label={t('pages.nodes.port')}
-                value={form.port}
+                name="port"
-                min={1}
+                rules={[antdRule(NodeFormSchema.shape.port, t)]}
-                max={65535}
+              >
-                style={{ width: '100%' }}
+                <InputNumber min={1} max={65535} style={{ width: '100%' }} />
-                onChange={(v) => update('port', Number(v) || 0)}
-              />
               </Form.Item>
             </Col>
           </Row>
 
           <Row gutter={16}>
             <Col xs={24} md={12}>
-            <Form.Item label={t('pages.nodes.basePath')}>
+              <Form.Item label={t('pages.nodes.basePath')} name="basePath">
-              <Input
+                <Input placeholder="/" />
-                value={form.basePath}
-                placeholder="/"
-                onChange={(e) => update('basePath', e.target.value)}
-              />
               </Form.Item>
             </Col>
             <Col xs={24} md={12}>
-            <Form.Item label={t('pages.nodes.enable')}>
+              <Form.Item
-              <Switch checked={form.enable} onChange={(v) => update('enable', v)} />
+                label={t('pages.nodes.enable')}
+                name="enable"
+                valuePropName="checked"
+              >
+                <Switch />
               </Form.Item>
             </Col>
           </Row>
 
-        <Form.Item label={t('pages.nodes.allowPrivateAddress')}>
+          <Form.Item
-          <Switch
+            label={t('pages.nodes.allowPrivateAddress')}
-            checked={form.allowPrivateAddress}
+            name="allowPrivateAddress"
-            onChange={(v) => update('allowPrivateAddress', v)}
+            valuePropName="checked"
-          />
+            extra={t('pages.nodes.allowPrivateAddressHint')}
-          <div className="hint">{t('pages.nodes.allowPrivateAddressHint')}</div>
+          >
+            <Switch />
           </Form.Item>
 
-        <Form.Item label={t('pages.nodes.apiToken')} required>
+          <Form.Item
-          <Input.Password
+            label={t('pages.nodes.apiToken')}
-            value={form.apiToken}
+            name="apiToken"
-            placeholder={t('pages.nodes.apiTokenPlaceholder')}
+            rules={[antdRule(NodeFormSchema.shape.apiToken, t)]}
-            onChange={(e) => update('apiToken', e.target.value)}
+            extra={t('pages.nodes.apiTokenHint')}
-          />
+          >
-          <div className="hint">{t('pages.nodes.apiTokenHint')}</div>
+            <Input.Password placeholder={t('pages.nodes.apiTokenPlaceholder')} />
           </Form.Item>
 
           <div className="test-row">

frontend/src/schemas/client.ts

@@ -83,6 +83,44 @@ export const DelDepletedResultSchema = z.object({
 
 export const OnlinesSchema = nullableStringArray;
 
+export const ClientFormSchema = z.object({
+  email: z.string().trim().min(1, 'pages.clients.email'),
+  subId: z.string(),
+  uuid: z.string(),
+  password: z.string(),
+  auth: z.string(),
+  flow: z.string(),
+  reverseTag: z.string(),
+  totalGB: z.number().min(0),
+  delayedStart: z.boolean(),
+  delayedDays: z.number().int().min(0),
+  limitIp: z.number().int().min(0),
+  tgId: z.number().int().min(0),
+  comment: z.string(),
+  enable: z.boolean(),
+  inboundIds: z.array(z.number()),
+});
+
+export const ClientCreateFormSchema = ClientFormSchema.extend({
+  inboundIds: z.array(z.number()).min(1, 'pages.clients.selectInbound'),
+});
+
+export const ClientBulkAddFormSchema = z.object({
+  emailMethod: z.number().int().min(0).max(4),
+  firstNum: z.number().int().min(1),
+  lastNum: z.number().int().min(1),
+  emailPrefix: z.string(),
+  emailPostfix: z.string(),
+  quantity: z.number().int().min(1).max(100),
+  subId: z.string(),
+  comment: z.string(),
+  flow: z.string(),
+  limitIp: z.number().int().min(0),
+  totalGB: z.number().min(0),
+  expiryTime: z.number(),
+  inboundIds: z.array(z.number()).min(1, 'pages.clients.selectInbound'),
+});
+
 export type ClientRecord = z.infer<typeof ClientRecordSchema>;
 export type ClientTraffic = z.infer<typeof ClientTrafficSchema>;
 export type InboundOption = z.infer<typeof InboundOptionSchema>;
@@ -90,3 +128,5 @@ export type ClientsSummary = z.infer<typeof ClientsSummarySchema>;
 export type ClientPageResponse = z.infer<typeof ClientPageResponseSchema>;
 export type ClientHydrate = z.infer<typeof ClientHydrateSchema>;
 export type BulkAdjustResult = z.infer<typeof BulkAdjustResultSchema>;
+export type ClientBulkAddFormValues = z.infer<typeof ClientBulkAddFormSchema>;
+export type ClientFormValues = z.infer<typeof ClientFormSchema>;

frontend/src/schemas/node.ts

@@ -35,5 +35,19 @@ export const ProbeResultSchema = z.object({
   error: z.string().optional(),
 }).loose();
 
+export const NodeFormSchema = z.object({
+  id: z.number().optional(),
+  name: z.string().trim().min(1, 'pages.nodes.toasts.fillRequired'),
+  remark: z.string().optional(),
+  scheme: z.enum(['http', 'https']),
+  address: z.string().trim().min(1, 'pages.nodes.toasts.fillRequired'),
+  port: z.number().int().min(1).max(65535),
+  basePath: z.string(),
+  apiToken: z.string().trim().min(1, 'pages.nodes.toasts.fillRequired'),
+  enable: z.boolean(),
+  allowPrivateAddress: z.boolean(),
+});
+
 export type NodeRecord = z.infer<typeof NodeRecordSchema>;
 export type ProbeResult = z.infer<typeof ProbeResultSchema>;
+export type NodeFormValues = z.infer<typeof NodeFormSchema>;