@nexttylabs/echo 0.2.0

package/docs/plans/2026-01-06-file-upload-support.md

@@ -0,0 +1,804 @@
+# File Upload Support Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Add MVP file upload support for feedback with local storage, server validation, and attachment linking at upload time.
+
+**Architecture:** Add an `attachments` table with a feedback relation, implement server-side upload validation + storage, expose `/api/upload`, and extend feedback submission to link uploaded attachments. Integrate a client-side upload UI into the feedback form.
+
+**Tech Stack:** Next.js App Router (Route Handlers), TypeScript, Drizzle ORM (Postgres), Bun tests, Shadcn UI
+
+### Task 1: Add attachments schema + relations + migration (feedbackId required)
+
+**Files:**
+- Create: `lib/db/schema/attachments.ts`
+- Modify: `lib/db/schema/feedback.ts`
+- Modify: `lib/db/schema/index.ts`
+- Modify: `lib/db/migrations/*` (generated by drizzle-kit)
+
+**Step 1: Write the failing test**
+
+Create `tests/lib/attachments-schema.test.ts`:
+
+```ts
+import { describe, expect, it } from "bun:test";
+import { attachments } from "@/lib/db/schema/attachments";
+
+describe("attachments schema", () => {
+  it("defines required columns", () => {
+    expect(attachments).toBeDefined();
+    expect(attachments["feedbackId"]).toBeDefined();
+    expect(attachments["fileName"]).toBeDefined();
+    expect(attachments["filePath"]).toBeDefined();
+    expect(attachments["fileSize"]).toBeDefined();
+    expect(attachments["mimeType"]).toBeDefined();
+  });
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun test tests/lib/attachments-schema.test.ts`
+Expected: FAIL with module not found (`attachments.ts`).
+
+**Step 3: Write minimal implementation**
+
+Create `lib/db/schema/attachments.ts`:
+
+```ts
+import { index, integer, pgTable, serial, text, timestamp } from "drizzle-orm/pg-core";
+import { relations } from "drizzle-orm";
+import { feedback } from "./feedback";
+
+export const attachments = pgTable(
+  "attachments",
+  {
+    attachmentId: serial("attachmentId").primaryKey(),
+    feedbackId: integer("feedbackId")
+      .notNull()
+      .references(() => feedback.feedbackId, { onDelete: "cascade" }),
+    fileName: text("fileName").notNull(),
+    filePath: text("filePath").notNull(),
+    fileSize: integer("fileSize").notNull(),
+    mimeType: text("mimeType").notNull(),
+    createdAt: timestamp("createdAt").defaultNow().notNull(),
+  },
+  (table) => ({
+    feedbackIdx: index("idx_attachments_feedbackId").on(table.feedbackId),
+  }),
+);
+
+export const attachmentRelations = relations(attachments, ({ one }) => ({
+  feedback: one(feedback, {
+    fields: [attachments.feedbackId],
+    references: [feedback.feedbackId],
+  }),
+}));
+
+export type Attachment = typeof attachments.$inferSelect;
+export type NewAttachment = typeof attachments.$inferInsert;
+```
+
+Update `lib/db/schema/feedback.ts`:
+
+```ts
+import { relations } from "drizzle-orm";
+import { attachments } from "./attachments";
+
+export const feedbackRelations = relations(feedback, ({ many }) => ({
+  attachments: many(attachments),
+}));
+```
+
+Update `lib/db/schema/index.ts`:
+
+```ts
+export * from "./attachments";
+```
+
+Generate migration via Drizzle:
+
+```bash
+bun run db:generate
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun test tests/lib/attachments-schema.test.ts`
+Expected: PASS.
+
+**Step 5: Commit**
+
+```bash
+git add lib/db/schema/attachments.ts lib/db/schema/feedback.ts lib/db/schema/index.ts lib/db/migrations tests/lib/attachments-schema.test.ts
+
+git commit -m "feat: add attachments schema"
+```
+
+### Task 2: Add file validation + local storage utilities
+
+**Files:**
+- Create: `lib/upload/file-validator.ts`
+- Create: `lib/upload/storage.ts`
+- Create: `public/uploads/.gitkeep`
+
+**Step 1: Write the failing test**
+
+Create `tests/lib/file-validator.test.ts`:
+
+```ts
+import { describe, expect, it } from "bun:test";
+import { validateFile, MAX_FILE_SIZE } from "@/lib/upload/file-validator";
+
+describe("validateFile", () => {
+  it("rejects files over max size", () => {
+    const file = new File([new ArrayBuffer(MAX_FILE_SIZE + 1)], "big.png", {
+      type: "image/png",
+    });
+
+    const result = validateFile(file);
+    expect(result.valid).toBe(false);
+    if (!result.valid) {
+      expect(result.code).toBe("FILE_TOO_LARGE");
+    }
+  });
+
+  it("rejects unsupported types", () => {
+    const file = new File(["hello"], "note.txt", { type: "text/plain" });
+    const result = validateFile(file);
+    expect(result.valid).toBe(false);
+    if (!result.valid) {
+      expect(result.code).toBe("INVALID_FILE_TYPE");
+    }
+  });
+
+  it("accepts allowed types within size", () => {
+    const file = new File(["data"], "image.png", { type: "image/png" });
+    const result = validateFile(file);
+    expect(result.valid).toBe(true);
+  });
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun test tests/lib/file-validator.test.ts`
+Expected: FAIL with module not found.
+
+**Step 3: Write minimal implementation**
+
+Create `lib/upload/file-validator.ts`:
+
+```ts
+export const MAX_FILE_SIZE = 5 * 1024 * 1024;
+
+export const ALLOWED_MIME_TYPES = [
+  "image/png",
+  "image/jpeg",
+  "image/jpg",
+  "image/gif",
+  "application/pdf",
+] as const;
+
+export type AllowedMimeType = (typeof ALLOWED_MIME_TYPES)[number];
+
+export type FileValidationResult =
+  | { valid: true; mimeType: AllowedMimeType }
+  | { valid: false; error: string; code: "INVALID_FILE_TYPE" | "FILE_TOO_LARGE" };
+
+export function validateFile(file: File): FileValidationResult {
+  if (file.size > MAX_FILE_SIZE) {
+    return {
+      valid: false,
+      error: "文件大小不能超过 5MB",
+      code: "FILE_TOO_LARGE",
+    };
+  }
+
+  if (!ALLOWED_MIME_TYPES.includes(file.type as AllowedMimeType)) {
+    return {
+      valid: false,
+      error: "不支持的文件类型",
+      code: "INVALID_FILE_TYPE",
+    };
+  }
+
+  return { valid: true, mimeType: file.type as AllowedMimeType };
+}
+```
+
+Create `lib/upload/storage.ts`:
+
+```ts
+import { mkdir, writeFile, unlink } from "fs/promises";
+import { join } from "path";
+import { randomUUID } from "crypto";
+
+export interface StoredFile {
+  fileName: string;
+  filePath: string;
+  fullPath: string;
+}
+
+export function generateUniqueFileName(originalName: string): string {
+  const ext = originalName.split(".").pop() ?? "";
+  const uuid = randomUUID();
+  return ext ? `${uuid}.${ext}` : uuid;
+}
+
+export async function saveFile(
+  file: File,
+  uploadDir: string = "public/uploads",
+): Promise<StoredFile> {
+  await mkdir(uploadDir, { recursive: true });
+
+  const uniqueFileName = generateUniqueFileName(file.name);
+  const fullPath = join(uploadDir, uniqueFileName);
+
+  const buffer = Buffer.from(await file.arrayBuffer());
+  await writeFile(fullPath, buffer);
+
+  return {
+    fileName: file.name,
+    filePath: fullPath.replace(/^public\//, ""),
+    fullPath,
+  };
+}
+
+export async function deleteFile(fullPath: string): Promise<void> {
+  try {
+    await unlink(fullPath);
+  } catch (error) {
+    console.error("Failed to delete file:", fullPath, error);
+  }
+}
+```
+
+Add `public/uploads/.gitkeep` (empty file).
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun test tests/lib/file-validator.test.ts`
+Expected: PASS.
+
+**Step 5: Commit**
+
+```bash
+git add lib/upload/file-validator.ts lib/upload/storage.ts public/uploads/.gitkeep tests/lib/file-validator.test.ts
+
+git commit -m "feat: add file upload validation and storage"
+```
+
+### Task 3: Add upload API handler + route
+
+**Files:**
+- Create: `app/api/upload/handler.ts`
+- Create: `app/api/upload/route.ts`
+
+**Step 1: Write the failing test**
+
+Create `tests/api/upload.test.ts`:
+
+```ts
+import { describe, expect, it } from "bun:test";
+import { buildUploadHandler } from "@/app/api/upload/handler";
+import { attachments } from "@/lib/db/schema";
+
+const makeDeps = () => {
+  const inserted: Record<string, unknown>[] = [];
+  const db = {
+    insert: (table?: unknown) => ({
+      values: (values: Record<string, unknown>) => {
+        if (table === attachments) {
+          inserted.push(values);
+        }
+        return {
+          returning: async () => [
+            { attachmentId: 1, ...values, createdAt: new Date() },
+          ],
+        };
+      },
+    }),
+  };
+
+  const saveFile = async (file: File) => ({
+    fileName: file.name,
+    filePath: `uploads/${file.name}`,
+    fullPath: `/tmp/${file.name}`,
+  });
+
+  const validateFile = (file: File) =>
+    file.type === "text/plain"
+      ? { valid: false, error: "不支持的文件类型", code: "INVALID_FILE_TYPE" as const }
+      : { valid: true, mimeType: file.type as "image/png" };
+
+  return { db, saveFile, validateFile, inserted };
+};
+
+describe("POST /api/upload", () => {
+  it("rejects invalid file types", async () => {
+    const deps = makeDeps();
+    const handler = buildUploadHandler(deps);
+
+    const form = new FormData();
+    form.append("files", new File(["x"], "bad.txt", { type: "text/plain" }));
+    form.append("feedbackId", "1");
+
+    const res = await handler(new Request("http://localhost/api/upload", {
+      method: "POST",
+      body: form,
+    }));
+
+    const json = await res.json();
+    expect(res.status).toBe(400);
+    expect(json.code).toBe("VALIDATION_ERROR");
+  });
+
+  it("uploads valid files", async () => {
+    const deps = makeDeps();
+    const handler = buildUploadHandler(deps);
+
+    const form = new FormData();
+    form.append("files", new File(["x"], "good.png", { type: "image/png" }));
+    form.append("feedbackId", "1");
+
+    const res = await handler(new Request("http://localhost/api/upload", {
+      method: "POST",
+      body: form,
+    }));
+
+    const json = await res.json();
+    expect(res.status).toBe(201);
+    expect(json.data[0].attachmentId).toBe(1);
+    expect(deps.inserted.length).toBe(1);
+  });
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun test tests/api/upload.test.ts`
+Expected: FAIL with module not found (`handler`).
+
+**Step 3: Write minimal implementation**
+
+Create `app/api/upload/handler.ts`:
+
+```ts
+import { NextResponse } from "next/server";
+import { attachments } from "@/lib/db/schema";
+import { apiError, validationError } from "@/lib/api/errors";
+import type { FileValidationResult } from "@/lib/upload/file-validator";
+import type { db as database } from "@/lib/db";
+
+type Database = NonNullable<typeof database>;
+
+type UploadDeps = {
+  db: {
+    insert: Database["insert"];
+  };
+  validateFile: (file: File) => FileValidationResult;
+  saveFile: (file: File) => Promise<{ fileName: string; filePath: string; fullPath: string }>;
+};
+
+export function buildUploadHandler(deps: UploadDeps) {
+  return async function POST(req: Request) {
+    try {
+      const formData = await req.formData();
+      const feedbackIdRaw = formData.get("feedbackId");
+      const feedbackId = Number(feedbackIdRaw);
+      if (!feedbackIdRaw || Number.isNaN(feedbackId)) {
+        return validationError(undefined, "feedbackId is required");
+      }
+      const files = formData.getAll("files").filter(Boolean) as File[];
+
+      if (!files.length) {
+        return validationError(undefined, "No files provided");
+      }
+
+      const validationResults = files.map(deps.validateFile);
+      const invalid = validationResults.filter((result) => !result.valid);
+      if (invalid.length) {
+        return validationError(invalid, "Validation failed");
+      }
+
+      const saved = await Promise.all(
+        files.map(async (file) => {
+          const stored = await deps.saveFile(file);
+          const [attachment] = await deps.db
+            .insert(attachments)
+            .values({
+              feedbackId,
+              fileName: stored.fileName,
+              filePath: stored.filePath,
+              fileSize: file.size,
+              mimeType: file.type,
+            })
+            .returning();
+          return attachment;
+        }),
+      );
+
+      return NextResponse.json({ data: saved }, { status: 201 });
+    } catch (error) {
+      return apiError(error);
+    }
+  };
+}
+```
+
+Create `app/api/upload/route.ts`:
+
+```ts
+import { NextResponse } from "next/server";
+import { buildUploadHandler } from "./handler";
+import { db } from "@/lib/db";
+import { validateFile } from "@/lib/upload/file-validator";
+import { saveFile } from "@/lib/upload/storage";
+
+export const dynamic = "force-dynamic";
+export const runtime = "nodejs";
+
+export async function POST(req: Request) {
+  if (!db) {
+    return NextResponse.json(
+      { error: "Database not configured", code: "DATABASE_NOT_CONFIGURED" },
+      { status: 500 },
+    );
+  }
+
+  const handler = buildUploadHandler({ db, validateFile, saveFile });
+  return handler(req);
+}
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun test tests/api/upload.test.ts`
+Expected: PASS.
+
+**Step 5: Commit**
+
+```bash
+git add app/api/upload/handler.ts app/api/upload/route.ts tests/api/upload.test.ts
+
+git commit -m "feat: add upload api"
+```
+
+### Task 4: Update feedback form flow to upload after feedback creation
+
+**Files:**
+- Create: `components/feedback/file-upload.tsx`
+- Modify: `components/feedback/embedded-feedback-form.tsx`
+- Modify: `tests/components/feedback/embedded-feedback-form.test.tsx`
+
+**Step 1: Write the failing test**
+
+Update `tests/components/feedback/embedded-feedback-form.test.tsx`:
+
+```tsx
+it("includes file upload UI", () => {
+  render(<EmbeddedFeedbackForm />);
+  expect(screen.getByText("拖拽文件到此处，或点击选择文件")).toBeInTheDocument();
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun test tests/components/feedback/embedded-feedback-form.test.tsx`
+Expected: FAIL (upload UI not rendered).
+
+**Step 3: Write minimal implementation**
+
+Create `components/feedback/file-upload.tsx` and accept `feedbackId`:
+
+```tsx
+"use client";
+
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { Upload, File as FileIcon, X } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { cn } from "@/lib/utils";
+
+type UploadStatus = "pending" | "uploading" | "success" | "error";
+
+interface UploadedFile {
+  file: File;
+  preview?: string;
+  status: UploadStatus;
+  attachmentId?: number;
+}
+
+interface FileUploadProps {
+  feedbackId?: number;
+  onUploaded?: (ids: number[]) => void;
+  maxSize?: number;
+  accept?: string;
+}
+
+export function FileUpload({
+  feedbackId,
+  onUploaded,
+  maxSize = 5 * 1024 * 1024,
+  accept = "image/png,image/jpeg,image/gif,application/pdf",
+}: FileUploadProps) {
+  const [files, setFiles] = useState<UploadedFile[]>([]);
+  const [isDragging, setIsDragging] = useState(false);
+
+  const allowedTypes = useMemo(() => accept.split(","), [accept]);
+
+  const validateFile = useCallback(
+    (file: File): string | null => {
+      if (file.size > maxSize) {
+        return "文件大小不能超过 5MB";
+      }
+      if (!allowedTypes.includes(file.type)) {
+        return "不支持的文件类型";
+      }
+      return null;
+    },
+    [maxSize, allowedTypes],
+  );
+
+  const handleFiles = useCallback(
+    (newFiles: File[]) => {
+      const validFiles: UploadedFile[] = [];
+
+      for (const file of newFiles) {
+        const error = validateFile(file);
+        if (error) {
+          alert(error);
+          continue;
+        }
+
+        const preview = file.type.startsWith("image/")
+          ? URL.createObjectURL(file)
+          : undefined;
+
+        validFiles.push({ file, preview, status: "pending" });
+      }
+
+      setFiles((prev) => [...prev, ...validFiles]);
+    },
+    [validateFile],
+  );
+
+  useEffect(() => {
+    return () => {
+      files.forEach((file) => {
+        if (file.preview) {
+          URL.revokeObjectURL(file.preview);
+        }
+      });
+    };
+  }, [files]);
+
+  const uploadFiles = async () => {
+    if (!feedbackId) {
+      alert("请先提交反馈");
+      return;
+    }
+    const pending = files.filter((file) => file.status === "pending");
+
+    for (const fileItem of pending) {
+      setFiles((prev) =>
+        prev.map((item) =>
+          item === fileItem ? { ...item, status: "uploading" } : item,
+        ),
+      );
+
+      try {
+        const formData = new FormData();
+        formData.append("files", fileItem.file);
+        formData.append("feedbackId", String(feedbackId));
+
+        const response = await fetch("/api/upload", {
+          method: "POST",
+          body: formData,
+        });
+
+        if (!response.ok) {
+          setFiles((prev) =>
+            prev.map((item) =>
+              item === fileItem ? { ...item, status: "error" } : item,
+            ),
+          );
+          continue;
+        }
+
+        const result = await response.json();
+        const attachmentId = result.data?.[0]?.attachmentId as number | undefined;
+
+        setFiles((prev) =>
+          prev.map((item) =>
+            item === fileItem
+              ? { ...item, status: "success", attachmentId }
+              : item,
+          ),
+        );
+      } catch {
+        setFiles((prev) =>
+          prev.map((item) =>
+            item === fileItem ? { ...item, status: "error" } : item,
+          ),
+        );
+      }
+    }
+
+    const uploadedIds = files
+      .filter((file) => file.attachmentId !== undefined)
+      .map((file) => file.attachmentId as number);
+
+    onUploaded?.(uploadedIds);
+  };
+
+  const removeFile = (fileItem: UploadedFile) => {
+    setFiles((prev) => prev.filter((file) => file !== fileItem));
+    if (fileItem.preview) {
+      URL.revokeObjectURL(fileItem.preview);
+    }
+  };
+
+  return (
+    <div className="space-y-4">
+      <div
+        onDragOver={(event) => {
+          event.preventDefault();
+          setIsDragging(true);
+        }}
+        onDragLeave={() => setIsDragging(false)}
+        onDrop={(event) => {
+          event.preventDefault();
+          setIsDragging(false);
+          handleFiles(Array.from(event.dataTransfer.files));
+        }}
+        className={cn(
+          "border-2 border-dashed rounded-lg p-6 text-center transition-colors",
+          isDragging
+            ? "border-primary bg-primary/5"
+            : "border-muted-foreground/25 hover:border-muted-foreground/50",
+        )}
+      >
+        <input
+          id="file-upload"
+          type="file"
+          multiple
+          accept={accept}
+          onChange={(event) =>
+            handleFiles(Array.from(event.target.files ?? []))
+          }
+          className="hidden"
+        />
+        <label htmlFor="file-upload" className="cursor-pointer">
+          <Upload className="mx-auto h-10 w-10 text-muted-foreground mb-2" />
+          <p className="text-sm text-muted-foreground">
+            拖拽文件到此处，或点击选择文件
+          </p>
+          <p className="text-xs text-muted-foreground mt-1">
+            支持 PNG, JPG, GIF, PDF (最大 5MB)
+          </p>
+        </label>
+      </div>
+
+      {files.length > 0 && (
+        <div className="space-y-2">
+          {files.map((fileItem) => (
+            <div
+              key={`${fileItem.file.name}-${fileItem.file.size}`}
+              className="flex items-center gap-3 p-3 border rounded-lg"
+            >
+              {fileItem.preview ? (
+                <img
+                  src={fileItem.preview}
+                  alt={fileItem.file.name}
+                  className="w-12 h-12 object-cover rounded"
+                />
+              ) : (
+                <div className="w-12 h-12 bg-muted rounded flex items-center justify-center">
+                  <FileIcon className="w-6 h-6 text-muted-foreground" />
+                </div>
+              )}
+
+              <div className="flex-1 min-w-0">
+                <p className="text-sm font-medium truncate">
+                  {fileItem.file.name}
+                </p>
+                <p className="text-xs text-muted-foreground">
+                  {(fileItem.file.size / 1024).toFixed(1)} KB
+                </p>
+              </div>
+
+              <div className="text-xs">
+                {fileItem.status === "pending" && "待上传"}
+                {fileItem.status === "uploading" && "上传中..."}
+                {fileItem.status === "success" && "✓ 已上传"}
+                {fileItem.status === "error" && "✗ 上传失败"}
+              </div>
+
+              <Button
+                type="button"
+                variant="ghost"
+                size="icon"
+                onClick={() => removeFile(fileItem)}
+              >
+                <X className="w-4 h-4" />
+              </Button>
+            </div>
+          ))}
+
+          <Button
+            type="button"
+            onClick={uploadFiles}
+            disabled={!feedbackId || files.every((file) => file.status !== "pending")}
+            className="w-full"
+          >
+            上传文件
+          </Button>
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+Update `components/feedback/embedded-feedback-form.tsx` to create feedback first and then allow upload:
+
+```tsx
+import { FileUpload } from "./file-upload";
+
+const [feedbackId, setFeedbackId] = useState<number | null>(null);
+
+const onSubmit = async (data: FeedbackInput) => {
+  const response = await fetch("/api/feedback", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(data),
+  });
+
+  if (!response.ok) {
+    return;
+  }
+
+  const result = await response.json();
+  setFeedbackId(result.data.feedbackId);
+};
+
+// In JSX, before footer
+<FileUpload feedbackId={feedbackId ?? undefined} />
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun test tests/components/feedback/embedded-feedback-form.test.tsx`
+Expected: PASS.
+
+**Step 5: Commit**
+
+```bash
+git add components/feedback/file-upload.tsx components/feedback/embedded-feedback-form.tsx tests/components/feedback/embedded-feedback-form.test.tsx
+
+git commit -m "feat: add feedback upload UI"
+```
+
+### Task 5: Final validation
+
+**Files:**
+- None
+
+**Step 1: Run full test suite**
+
+Run: `bun test`
+Expected: PASS.
+
+**Step 2: Run lint**
+
+Run: `bun run lint`
+Expected: PASS.
+
+**Step 3: Commit (if needed)**
+
+```bash
+git status -sb
+```
+
+If any missing changes remain, add and commit with a descriptive message.