@nexttylabs/echo 0.3.0 → 0.5.0

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

@@ -1,804 +0,0 @@
-# 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.