@core / forms

1.1.0 ▾

1.1.0

인증됨MIT

GitHub

폼과 리드 수집: 코드 또는 관리자에서 생성, 스팸 방지, GDPR 동의, 이메일 알림, 서명된 웹훅, CSV

코드파일 11개컨텍스트약 815토큰검사 통과

약 815토큰→ src/lib/forms/AGENTS.md→ .cursor/rules/genpm-core-forms.mdc

이것이 AI가 src/lib/forms에서 작업할 때 읽는 내용 그대로입니다. 그 외에는 컨텍스트에 아무것도 추가되지 않습니다.

@core/forms — rules for AI agents

Purpose

Contact and lead forms end to end: forms defined in code (defineForm with zod) or built by editors in the admin (forms content collection), anti-spam (@core/antispam), GDPR consent with a versioned text, stored submissions with source page and campaign parameters, and background processing (@core/jobs): team alert email, auto-reply, HMAC-signed webhook and onSubmission handlers. CSV export, retention and erasure helpers. Table: form_submissions.

Map

index.ts — public API: defineForm, submitForm, onSubmission, formsAdminResources, exportSubmissionsCsv, pruneSubmissions, deleteSubmissionsByEmail.
definitions.ts — code and admin-built definitions. submit.ts — submission and the forms.process job. admin.ts — admin, CSV, privacy.
react.ts — <Form formKey searchParams> (async server component; works without JavaScript).
adapters/hono.ts — formRoutes(). adapters/next.ts — formRoute (POST; HTML posts get a 303 back to the page).

Integration

Env: EMAIL_FROM (@core/email), optional FORMS_NOTIFY_TO (comma-separated default recipients) and FORMS_WEBHOOK_SECRET (≥ 32 chars, only with webhooks). Migrations as in src/lib/db/AGENTS.md; the @core/jobs cron must run.
Define code forms in a module imported at startup (e.g. src/genpm/forms.ts): defineForm({ key: 'contact', label: 'Contact', schema: z.object({ name: z.string().min(1), email: z.email(), message: z.string().min(5) }), emailField: 'email', consent: { required: true, version: '2026-10', text: '…' } }).
Mount formRoutes() or formRoute at /api/forms/<key> and render <Form formKey="contact" searchParams={await searchParams} />: it includes the anti-spam fields, the consent checkbox (never pre-checked) and shows the result after the 303. Custom markup: post to the same endpoint with honeypotProps, _ts and consent; JSON callers get { ok, reason, errors }. In Next.js Server Actions call submitForm(key, formData, { headers: await headers() }) instead.
Translate the messages with labels (keys: formLabels).
Add ...formsAdminResources() to src/genpm/admin.ts.
Verify: submit the form, run the cron, the team receives the email and the submission appears in the admin.

Conventions

Field names are the keys stored in data; keep them stable (exports and webhooks depend on them).
forms.process records each finished step in form_submissions.processed (notify, auto_reply, webhook, handler:<n>): a retry skips them, so emails and webhooks aren't repeated. Keep onSubmission handlers in a stable order.
Webhook receivers must verify x-genpm-signature (t=<unix>,v1=<hmac> over "<t>.<body>") and reject old timestamps.
Ask only for the data you need; define a retention period and schedule pruneSubmissions(days).
Permissions: submissions:read|update|delete|export, forms:* for admin-built forms.

Don't

Don't send emails or call webhooks inside the request; submitForm queues them.
Don't put submission values into HTML without escaping, or open CSV exports from other tools without the formula guard.
Don't add hidden fields that collect data the user didn't type.

# @core/forms — rules for AI agents

## Purpose
Contact and lead forms end to end: forms defined in code (`defineForm` with zod) or built by editors in the admin
(`forms` content collection), anti-spam (@core/antispam), GDPR consent with a versioned text, stored submissions with
source page and campaign parameters, and background processing (@core/jobs): team alert email, auto-reply,
HMAC-signed webhook and `onSubmission` handlers. CSV export, retention and erasure helpers. Table: `form_submissions`.

## Map
- `index.ts` — public API: `defineForm`, `submitForm`, `onSubmission`, `formsAdminResources`, `exportSubmissionsCsv`, `pruneSubmissions`, `deleteSubmissionsByEmail`.
- `definitions.ts` — code and admin-built definitions. `submit.ts` — submission and the `forms.process` job. `admin.ts` — admin, CSV, privacy.
- `react.ts` — `<Form formKey searchParams>` (async server component; works without JavaScript).
- `adapters/hono.ts` — `formRoutes()`. `adapters/next.ts` — `formRoute` (POST; HTML posts get a 303 back to the page).

## Integration
1. Env: `EMAIL_FROM` (@core/email), optional `FORMS_NOTIFY_TO` (comma-separated default recipients) and `FORMS_WEBHOOK_SECRET` (≥ 32 chars, only with webhooks). Migrations as in `src/lib/db/AGENTS.md`; the @core/jobs cron must run.
2. Define code forms in a module imported at startup (e.g. `src/genpm/forms.ts`):
   `defineForm({ key: 'contact', label: 'Contact', schema: z.object({ name: z.string().min(1), email: z.email(), message: z.string().min(5) }), emailField: 'email', consent: { required: true, version: '2026-10', text: '…' } })`.
3. Mount `formRoutes()` or `formRoute` at `/api/forms/<key>` and render `<Form formKey="contact" searchParams={await searchParams} />`:
   it includes the anti-spam fields, the consent checkbox (never pre-checked) and shows the result after the 303.
   Custom markup: post to the same endpoint with `honeypotProps`, `_ts` and `consent`; JSON callers get `{ ok, reason, errors }`.
   In Next.js Server Actions call `submitForm(key, formData, { headers: await headers() })` instead.
4. Translate the messages with `labels` (keys: `formLabels`).
5. Add `...formsAdminResources()` to `src/genpm/admin.ts`.
6. Verify: submit the form, run the cron, the team receives the email and the submission appears in the admin.

## Conventions
- Field names are the keys stored in `data`; keep them stable (exports and webhooks depend on them).
- `forms.process` records each finished step in `form_submissions.processed` (`notify`, `auto_reply`, `webhook`,
  `handler:<n>`): a retry skips them, so emails and webhooks aren't repeated. Keep `onSubmission` handlers in a stable order.
- Webhook receivers must verify `x-genpm-signature` (`t=<unix>,v1=<hmac>` over `"<t>.<body>"`) and reject old timestamps.
- Ask only for the data you need; define a retention period and schedule `pruneSubmissions(days)`.
- Permissions: `submissions:read|update|delete|export`, `forms:*` for admin-built forms.

## Don't
- Don't send emails or call webhooks inside the request; `submitForm` queues them.
- Don't put submission values into HTML without escaping, or open CSV exports from other tools without the formula guard.
- Don't add hidden fields that collect data the user didn't type.

.genpmignore 적용 후 주입될 정확한 트리입니다. 고정 대상:

src/lib/forms/schema.ts읽기 전용 · 76db1c0

// Tablas de @core/forms. Las recoge drizzle-kit vía src/lib/db/drizzle.config.ts.
import { index, jsonb, pgTable, text } from 'drizzle-orm/pg-core';
import { primaryId, timestamps } from '../db/index.ts';

export const formSubmissions = pgTable(
  'form_submissions',
  {
    id: primaryId('sub'),
    formKey: text('form_key').notNull(),
    data: jsonb('data').$type<Record<string, unknown>>().notNull(),
    /** Versión del texto de consentimiento aceptado (prueba RGPD), si el formulario lo pide. */
    consentVersion: text('consent_version'),
    /** Página desde la que se envió (sin query) y parámetros de campaña capturados. */
    sourcePath: text('source_path'),
    utm: jsonb('utm').$type<Record<string, string>>(),
    /** Pasos de `forms.process` ya hechos (`notify`, `auto_reply`, `webhook`, `handler:<n>`): un reintento no los repite. */
    processed: jsonb('processed').$type<string[]>().notNull().default([]),
    status: text('status', { enum: ['new', 'read', 'archived', 'spam'] })
      .notNull()
      .default('new'),
    ...timestamps,
  },
  (t) => [index('form_submissions_form_idx').on(t.formKey, t.createdAt)],
);

export type FormSubmission = typeof formSubmissions.$inferSelect;