表单与用户交互：把一次提交做成可信的系统

app/
└── boards/
    └── [boardId]/
        ├── actions.ts
        └── tasks/
            └── new/
                └── page.tsx
lib/
├── auth/
│   └── require-board-permission.ts
└── db.ts

// app/boards/[boardId]/actions.ts
'use server'
 
import { redirect } from 'next/navigation'
import { updateTag } from 'next/cache'
import { db } from '@/lib/db'
import { requireBoardPermission } from '@/lib/auth/require-board-permission'
 
function readText(formData: FormData, name: string): string {
  const value = formData.get(name)
  return

// app/boards/[boardId]/tasks/new/page.tsx
import { createTask } from '../../actions'
 
type NewTaskPageProps = {
  params: Promise<{ boardId: string }>
}
 
export default async function NewTaskPage({
  params,
}: NewTaskPageProps) {
  const { boardId } = await params
  const createTaskForBoard

// app/boards/[boardId]/tasks/[taskId]/page.tsx
import { revalidatePath } from 'next/cache'
import { db } from '@/lib/db'
import { requireBoardPermission } from '@/lib/auth/require-board-permission'
 
type TaskPageProps = {
  params: Promise<{ boardId: string; taskId: string }>
}
 
export default async function TaskPage({ params }: TaskPageProps

// app/boards/[boardId]/task-actions.ts
'use server'
 
import { updateTag } from 'next/cache'
import { db } from '@/lib/db'
import { requireBoardPermission } from '@/lib/auth/require-board-permission'
 
export async function completeTask(
  boardId: string,
  taskId: string,
): Promise<void> {
  await requireBoardPermission(boardId, 'task:complete')

// app/boards/[boardId]/complete-task-button.tsx
'use client'
 
import { useTransition } from 'react'
import { completeTask } from './task-actions'
 
type CompleteTaskButtonProps = {
  boardId: string
  taskId: string
}
 
export function CompleteTaskButton({
  boardId,
  taskId,
}: CompleteTaskButtonProps) {
  const [isPending, 

// app/boards/[boardId]/tasks/new/task-draft-form.tsx
'use client'
 
import { useActionState } from 'react'
import { saveTaskDraft } from '../../task-form-actions'
import type { TaskFormState } from '@/lib/tasks/task-form-state'
 
const initialState: TaskFormState = {
  status: 'idle',
  message: '',
  fieldErrors: {},
  values: {
    title: '',
    description: '',
    priority: 'medium'

export async function saveTaskDraft(
  boardId: string,
  previousState: TaskFormState,
  formData: FormData,
): Promise<TaskFormState> {
  // boardId 来自 bind
  // previousState 与 formData 由 useActionState 依次补入
  return previousState
}

// lib/tasks/task-input.ts
import { z } from 'zod'
 
export const taskInputSchema = z.object({
  title: z
    .string()
    .trim()
    .min(2, '标题至少需要 2 个字符')
    .max(80, '标题不能超过 80 个字符'),
  description: z
    .string()
    .trim()

import {
  taskInputSchema,
  taskValuesFromFormData,
} from '@/lib/tasks/task-input'
 
const rawValues = taskValuesFromFormData(formData)
const parsed = taskInputSchema.safeParse(rawValues)
 
if (!parsed.success) {
  return {
    status: 'error',
    message: '请检查标出的字段',
    fieldErrors: parsed.error.flatten().fieldErrors,
    values: rawValues,
  }
}

// lib/tasks/task-form-state.ts
export type TaskFormValues = {
  title: string
  description: string
  priority: string
  labelIds: string[]
}
 
export type TaskFormState = {
  status: 'idle' | 'error' | 'saved'
  message: string
  fieldErrors: {
    title?:

// app/boards/[boardId]/task-form-actions.ts
'use server'
 
import { updateTag } from 'next/cache'
import { db } from '@/lib/db'
import { requireBoardPermission } from '@/lib/auth/require-board-permission'
import {
  taskInputSchema,
  taskValuesFromFormData,
} from '@/lib/tasks/task-input'
import type { TaskFormState } from '@/lib/tasks/task-form-state'
 
export async function saveTaskDraft(
  boardId: string,
  previousState

// app/boards/[boardId]/tasks/new/task-draft-form.tsx
'use client'
 
import { useActionState } from 'react'
import { useFormStatus } from 'react-dom'
import { saveTaskDraft } from '../../task-form-actions'
import {
  initialTaskFormState,
  type TaskFormState,
} from '@/lib/tasks/task-form-state'
 
function FieldError({
  id,
  errors,
}: {
  id: string
  errors

// 错误示意：这里读到的是更外层表单，或者始终是空闲状态
'use client'
 
import { useFormStatus } from 'react-dom'
 
export function TaskForm() {
  const { pending } = useFormStatus()
 
  return (
    <form>
      <button disabled={pending}>保存</button>
    </form>
  )
}

'use client'
 
import { useFormStatus } from 'react-dom'
 
export function SubmitFeedback() {
  const { pending, data } = useFormStatus()
  const titleValue = data?.get('title')
  const title =
    typeof titleValue === 'string' ? titleValue.trim() : ''
 
  return

// app/boards/[boardId]/task-lifecycle-actions.ts
'use server'
 
import { redirect } from 'next/navigation'
import { updateTag } from 'next/cache'
import { db } from '@/lib/db'
import { requireBoardPermission } from '@/lib/auth/require-board-permission'
import {
  taskInputSchema,
  taskValuesFromFormData,
} from '@/lib/tasks/task-input'
 
export async function saveExistingDraft(
  boardId: string,
  taskId:

// app/boards/[boardId]/tasks/[taskId]/task-editor.tsx
import {
  publishTask,
  saveExistingDraft,
} from '../../task-lifecycle-actions'
import { TaskActionButtons } from './task-action-buttons'
 
type TaskEditorProps = {
  boardId: string
  task: {
    id: string
    title: string
    description: string | null
    priority: 'low' | 'medium'

// app/boards/[boardId]/tasks/[taskId]/task-action-buttons.tsx
'use client'
 
import { useFormStatus } from 'react-dom'
 
type FormAction = (formData: FormData) => Promise<void>
 
type TaskActionButtonsProps = {
  saveDraftAction: FormAction
  publishAction: FormAction
}
 
export function TaskActionButtons({
  saveDraftAction,
  publishAction

// lib/auth/require-board-permission.ts
import { redirect } from 'next/navigation'
import { db } from '@/lib/db'
import { verifySession } from '@/lib/auth/session'
 
type BoardPermission =
  | 'task:create'
  | 'task:edit'
  | 'task:publish'
  | 'task:complete'
  | 'comment:create'
  | 'attachment:create'
 
const rolePermissions: Record<string, Set<

// next.config.ts
import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  experimental: {
    serverActions: {
      allowedOrigins: [
        'boardflow.example.com',
        '*.internal.boardflow.example.com',
      ],
    },
  },
}
 
export default nextConfig

// app/boards/[boardId]/publish-actions.ts
'use server'
 
import { redirect } from 'next/navigation'
import { updateTag } from 'next/cache'
import { db } from '@/lib/db'
import { requireBoardPermission } from '@/lib/auth/require-board-permission'
 
type PublishState = {
  status: 'idle' | 'error'
  message: string
  revision: number
}
 
export async function

// app/boards/[boardId]/error.tsx
'use client'
 
import { useEffect } from 'react'
 
export default function BoardError({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  useEffect(() => {
    console.error

// app/boards/[boardId]/comment-actions.ts
'use server'
 
import { updateTag } from 'next/cache'
import { db } from '@/lib/db'
import { requireBoardPermission } from '@/lib/auth/require-board-permission'
 
export async function addComment(
  boardId: string,
  taskId: string,
  formData: FormData,
): Promise<{ ok: true } 

import { revalidateTag } from 'next/cache'
 
revalidateTag(`board:` + boardId + `:weekly-stats`, 'max')

import { revalidatePath } from 'next/cache'
 
revalidatePath(`/boards/` + boardId)

'use server'
 
import { refresh } from 'next/cache'
import { db } from '@/lib/db'
import { verifySession } from '@/lib/auth/session'
 
export async function dismissTaskNotice(noticeId: string) {
  const session = await verifySession()
 
  if (!session) {
    throw new Error('UNAUTHENTICATED')
  }

// app/boards/[boardId]/tasks/[taskId]/comment-list.tsx
'use client'
 
import { useOptimistic, useState } from 'react'
import { addComment } from '../../comment-actions'
 
type Comment = {
  id: string
  body: string
  authorName: string
  pending?: boolean
}
 
type CommentListProps = {
  boardId: string
  taskId: string

CREATE TABLE mutation_receipt (
  id UUID PRIMARY KEY,
  actor_id UUID NOT NULL,
  idempotency_key UUID NOT NULL,
  payload_fingerprint TEXT NOT NULL,
  status TEXT NOT NULL CHECK (status IN ('processing', 'completed')),
  response_json JSONB,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  completed_at TIMESTAMPTZ,
  UNIQUE

// app/boards/[boardId]/tasks/new/idempotent-task-form.tsx
import { randomUUID } from 'node:crypto'
import { redirect } from 'next/navigation'
import { createTaskOnce } from '../../idempotent-task-actions'
 
export function IdempotentTaskForm({
  boardId,
}: {
  boardId: string
}) {
  const idempotencyKey = randomUUID()
 
  async function createAndOpen(formData: FormData

// app/boards/[boardId]/idempotent-task-actions.ts
'use server'
 
import { createHash, randomUUID } from 'node:crypto'
import { updateTag } from 'next/cache'
import { z } from 'zod'
import { db } from '@/lib/db'
import { requireBoardPermission } from '@/lib/auth/require-board-permission'
import {
  taskInputSchema,
  taskValuesFromFormData,
} from '@/lib/tasks/task-input'
import { isUniqueConstraintError } from '@/lib/db/errors'
 
const idempotencyKeySchema

import { uploadSmallAttachment } from './attachment-actions'
 
export function AttachmentForm({
  boardId,
  taskId,
}: {
  boardId: string
  taskId: string
}) {
  const upload = uploadSmallAttachment.bind(null, boardId, taskId)
 
  return (
    <form action={upload}>
      <label

// app/boards/[boardId]/tasks/[taskId]/attachment-actions.ts
'use server'
 
import { randomUUID } from 'node:crypto'
import { updateTag } from 'next/cache'
import { db } from '@/lib/db'
import { storage } from '@/lib/storage'
import { requireBoardPermission } from '@/lib/auth/require-board-permission'
 
const MAX_ACTION_FILE_BYTES = 750_000
 
type DetectedFile = {
  extension: 'png' | 'pdf'
  contentType:

// next.config.ts
import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  experimental: {
    serverActions: {
      bodySizeLimit: '2mb',
    },
  },
}
 
export default nextConfig

// next.config.ts
import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  deploymentId: process.env.DEPLOYMENT_VERSION,
  experimental: {
    serverActions: {
      bodySizeLimit: '2mb',
      allowedOrigins: ['boardflow.example.com'],
    },
  },
}
 
export default nextConfig

// lib/tasks/task-input.test.ts
import { describe, expect, it } from 'vitest'
import {
  taskInputSchema,
  taskValuesFromFormData,
} from './task-input'
 
describe('taskInputSchema', () => {
  it('整理空格并保留多个标签字段', () => {
    const formData = new FormData()
    formData.set('title', '  修复登录页  ')
    formData.set

// e2e/create-task.spec.ts
import { expect, test } from '@playwright/test'
 
test('成员创建任务并进入详情页', async ({ page }) => {
  await page.goto('/boards/demo/tasks/new')
 
  await page.getByLabel('任务标题').fill('整理发布检查表')
  await page.getByLabel('任务说明').fill('覆盖回滚与缓存检查')

'use client'
 
import { useEffect, useRef } from 'react'
import type { TaskFormState } from '@/lib/tasks/task-form-state'
 
export function TaskErrorSummary({
  state,
}: {
  state: TaskFormState
}) {
  const summaryRef = useRef<HTMLDivElement>(null)
  const hasErrors =
    state.status === 'error' &&

'use server'
 
export async function publish(formData: FormData) {
  const userId = formData.get('userId') as string
  const taskId = formData.get('taskId') as string
  const title = formData.get('title') as string
 
  try {