@nexttylabs/echo 0.4.0 → 0.6.0

package/docs/plans/2026-01-09-portal-execution-plan.md

@@ -1,408 +0,0 @@
-# Portal Experience Implementation Plan
-
-> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
-
-**Goal:** Deliver the portal experience (IA shell + submission prefill + inline duplicate suggestions) as a cohesive, test-driven rollout.
-
-**Architecture:** Add a public `app/portal` route with lightweight presentational components. Enhance the embedded feedback form with URL prefill parsing and inline duplicate suggestions backed by a similarity API route that reuses existing duplicate detection logic.
-
-**Tech Stack:** Next.js App Router, React 19, TypeScript, Tailwind v4, shadcn/ui, Drizzle, bun:test
-
-**Featurebase-aligned portal requirements (for scope decisions):**
-- 反馈板块（Boards）与 AI 自动分配
-- 排序与筛选：Top/Recent/Trending；按状态/板块/标签/ETA/创建日期过滤
-- 默认排序可配置
-- 贡献者榜单：按投票/评论/被采纳计分；可隐藏/匿名化
-- 门户分享方式：链接 / Widget（含截图工具）/ 嵌入式 Portal
-- 门户文案与 CTA 可配置（含板块级覆盖）
-- 门户多语言（自动检测 + 手动切换）与可选自动翻译
-- 反馈分析：按日/周/月统计；Top viewed/voted/commented；Widget vs Portal 来源
-- 门户模块开关（禁用反馈视图）
-
-### Task 1: Add portal route + shell component
-
-**Files:**
-- Create: `app/portal/page.tsx`
-- Create: `components/portal/portal-shell.tsx`
-- Create: `components/portal/portal-nav.tsx`
-- Test: `tests/app/portal-page.test.ts`
-
-**Step 1: Write the failing test**
-
-```ts
-import { describe, expect, it } from "bun:test";
-import PortalPage, {
-  PORTAL_TITLE,
-  PORTAL_SECTIONS,
-} from "@/app/portal/page";
-
-describe("portal page", () => {
-  it("exports a function", () => {
-    expect(typeof PortalPage).toBe("function");
-  });
-
-  it("exposes portal labels", () => {
-    expect(PORTAL_TITLE).toBe("反馈中心");
-    expect(PORTAL_SECTIONS).toEqual([
-      { label: "反馈", href: "/portal" },
-      { label: "路线图", href: "/portal/roadmap" },
-      { label: "变更日志", href: "/portal/changelog" },
-      { label: "帮助中心", href: "/portal/help" },
-    ]);
-  });
-});
-```
-
-**Step 2: Run test to verify it fails**
-
-Run: `bun test tests/app/portal-page.test.ts`
-Expected: FAIL with "Cannot find module '@/app/portal/page'"
-
-**Step 3: Write minimal implementation**
-
-```tsx
-export const PORTAL_TITLE = "反馈中心";
-export const PORTAL_SECTIONS = [
-  { label: "反馈", href: "/portal" },
-  { label: "路线图", href: "/portal/roadmap" },
-  { label: "变更日志", href: "/portal/changelog" },
-  { label: "帮助中心", href: "/portal/help" },
-] as const;
-
-export default function PortalPage() {
-  return (
-    <PortalShell title={PORTAL_TITLE} sections={PORTAL_SECTIONS} />
-  );
-}
-```
-
-**Step 4: Run test to verify it passes**
-
-Run: `bun test tests/app/portal-page.test.ts`
-Expected: PASS
-
-**Step 5: Commit**
-
-```bash
-git add app/portal/page.tsx components/portal/portal-shell.tsx components/portal/portal-nav.tsx tests/app/portal-page.test.ts
-
-git commit -m "feat: add portal shell route"
-```
-
-### Task 2: Link public feedback detail back to portal
-
-**Files:**
-- Modify: `app/feedback/[id]/page.tsx`
-- Test: `tests/app/feedback-detail-page.test.ts`
-
-**Step 1: Write the failing test**
-
-```ts
-import { describe, expect, it } from "bun:test";
-import { FEEDBACK_BACK_HOME_LABEL } from "@/app/feedback/[id]/page";
-
-describe("feedback detail page", () => {
-  it("keeps back label unchanged", () => {
-    expect(FEEDBACK_BACK_HOME_LABEL).toBe("返回首页");
-  });
-});
-```
-
-**Step 2: Run test to verify it fails**
-
-Run: `bun test tests/app/feedback-detail-page.test.ts`
-Expected: PASS (baseline coverage) — then update test expectations if label changes.
-
-**Step 3: Write minimal implementation**
-
-```tsx
-<Button asChild variant="outline" size="sm">
-  <Link href="/portal">{FEEDBACK_BACK_HOME_LABEL}</Link>
-</Button>
-```
-
-**Step 4: Run test to verify it passes**
-
-Run: `bun test tests/app/feedback-detail-page.test.ts`
-Expected: PASS
-
-**Step 5: Commit**
-
-```bash
-git add app/feedback/[id]/page.tsx tests/app/feedback-detail-page.test.ts
-
-git commit -m "feat: link feedback detail back to portal"
-```
-
-### Task 3: Add prefill parser utility
-
-**Files:**
-- Create: `lib/feedback/prefill.ts`
-- Test: `tests/lib/feedback-prefill.test.ts`
-
-**Step 1: Write the failing test**
-
-```ts
-import { describe, expect, it } from "bun:test";
-import { parseFeedbackPrefill } from "@/lib/feedback/prefill";
-
-const params = new URLSearchParams({
-  title: "导出报告错位",
-  description: "PDF 排版错位",
-  type: "bug",
-  priority: "high",
-});
-
-describe("parseFeedbackPrefill", () => {
-  it("parses known fields", () => {
-    expect(parseFeedbackPrefill(params)).toEqual({
-      title: "导出报告错位",
-      description: "PDF 排版错位",
-      type: "bug",
-      priority: "high",
-    });
-  });
-
-  it("ignores unknown fields", () => {
-    const extra = new URLSearchParams({ title: "x", source: "email" });
-    expect(parseFeedbackPrefill(extra)).toEqual({ title: "x" });
-  });
-});
-```
-
-**Step 2: Run test to verify it fails**
-
-Run: `bun test tests/lib/feedback-prefill.test.ts`
-Expected: FAIL with "Cannot find module '@/lib/feedback/prefill'"
-
-**Step 3: Write minimal implementation**
-
-```ts
-import { feedbackTypeEnum, priorityEnum } from "@/lib/validators/feedback";
-
-type Prefill = Partial<{
-  title: string;
-  description: string;
-  type: "bug" | "feature" | "issue" | "other";
-  priority: "low" | "medium" | "high";
-}>;
-
-export function parseFeedbackPrefill(params: URLSearchParams): Prefill {
-  const prefill: Prefill = {};
-  const title = params.get("title");
-  const description = params.get("description");
-  const type = params.get("type");
-  const priority = params.get("priority");
-
-  if (title) prefill.title = title;
-  if (description) prefill.description = description;
-  if (type && feedbackTypeEnum.safeParse(type).success) {
-    prefill.type = type as Prefill["type"];
-  }
-  if (priority && priorityEnum.safeParse(priority).success) {
-    prefill.priority = priority as Prefill["priority"];
-  }
-  return prefill;
-}
-```
-
-**Step 4: Run test to verify it passes**
-
-Run: `bun test tests/lib/feedback-prefill.test.ts`
-Expected: PASS
-
-**Step 5: Commit**
-
-```bash
-git add lib/feedback/prefill.ts tests/lib/feedback-prefill.test.ts
-
-git commit -m "feat: add feedback prefill parser"
-```
-
-### Task 4: Wire prefill into embedded feedback form
-
-**Files:**
-- Modify: `components/feedback/embedded-feedback-form.tsx`
-- Modify: `tests/components/feedback/embedded-feedback-form.test.tsx`
-
-**Step 1: Write the failing test**
-
-```ts
-import { describe, expect, it } from "bun:test";
-import { FEEDBACK_PREFILL_KEYS } from "@/components/feedback/embedded-feedback-form";
-
-describe("EmbeddedFeedbackForm prefill", () => {
-  it("exposes prefill keys", () => {
-    expect(FEEDBACK_PREFILL_KEYS).toEqual([
-      "title",
-      "description",
-      "type",
-      "priority",
-    ]);
-  });
-});
-```
-
-**Step 2: Run test to verify it fails**
-
-Run: `bun test tests/components/feedback/embedded-feedback-form.test.tsx`
-Expected: FAIL with "FEEDBACK_PREFILL_KEYS is not defined"
-
-**Step 3: Write minimal implementation**
-
-```tsx
-export const FEEDBACK_PREFILL_KEYS = [
-  "title",
-  "description",
-  "type",
-  "priority",
-] as const;
-
-const searchParams = useSearchParams();
-const prefill = useMemo(
-  () => (searchParams ? parseFeedbackPrefill(searchParams) : {}),
-  [searchParams]
-);
-
-const form = useForm<BaseFeedbackInput>({
-  resolver: zodResolver(baseFeedbackSchema),
-  defaultValues: {
-    title: prefill.title ?? "",
-    description: prefill.description ?? "",
-    type: prefill.type ?? "issue",
-    priority: prefill.priority ?? "medium",
-  },
-  mode: "onBlur",
-});
-```
-
-**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/embedded-feedback-form.tsx tests/components/feedback/embedded-feedback-form.test.tsx
-
-git commit -m "feat: support feedback form prefill"
-```
-
-### Task 5: Add similarity API route + helper
-
-**Files:**
-- Create: `app/api/feedback/similar/route.ts`
-- Create: `lib/feedback/find-similar.ts`
-- Test: `tests/api/feedback-similar.test.ts`
-
-**Step 1: Write the failing test**
-
-```ts
-import { describe, expect, it } from "bun:test";
-import { buildSimilarResponse } from "@/lib/feedback/find-similar";
-
-const sample = [{
-  feedbackId: 1,
-  title: "批量导入联系人",
-  description: "CSV 导入",
-}];
-
-describe("buildSimilarResponse", () => {
-  it("returns scored suggestions", () => {
-    const result = buildSimilarResponse("导入联系人", "", sample);
-    expect(result.length).toBeGreaterThan(0);
-    expect(result[0]).toHaveProperty("feedbackId", 1);
-    expect(result[0]).toHaveProperty("similarity");
-  });
-});
-```
-
-**Step 2: Run test to verify it fails**
-
-Run: `bun test tests/api/feedback-similar.test.ts`
-Expected: FAIL with "Cannot find module '@/lib/feedback/find-similar'"
-
-**Step 3: Write minimal implementation**
-
-```ts
-import { findDuplicates } from "@/lib/services/ai/duplicate-detector";
-
-export function buildSimilarResponse(
-  title: string,
-  description: string,
-  existing: Array<{ feedbackId: number; title: string; description?: string | null }>
-) {
-  return findDuplicates(
-    { title, description },
-    existing.map((item) => ({
-      feedbackId: item.feedbackId,
-      title: item.title,
-      description: item.description ?? "",
-    }))
-  );
-}
-```
-
-**Step 4: Run test to verify it passes**
-
-Run: `bun test tests/api/feedback-similar.test.ts`
-Expected: PASS
-
-**Step 5: Commit**
-
-```bash
-git add app/api/feedback/similar/route.ts lib/feedback/find-similar.ts tests/api/feedback-similar.test.ts
-
-git commit -m "feat: add feedback similarity endpoint"
-```
-
-### Task 6: Render inline duplicate suggestions in the form
-
-**Files:**
-- Create: `components/feedback/duplicate-suggestions-inline.tsx`
-- Modify: `components/feedback/embedded-feedback-form.tsx`
-- Test: `tests/components/feedback/duplicate-suggestions-inline.test.tsx`
-
-**Step 1: Write the failing test**
-
-```ts
-import { describe, expect, it } from "bun:test";
-import { DuplicateSuggestionsInline } from "@/components/feedback/duplicate-suggestions-inline";
-
-const isFn = (value: unknown) => typeof value === "function";
-
-describe("DuplicateSuggestionsInline", () => {
-  it("exports a component", () => {
-    expect(isFn(DuplicateSuggestionsInline)).toBe(true);
-  });
-});
-```
-
-**Step 2: Run test to verify it fails**
-
-Run: `bun test tests/components/feedback/duplicate-suggestions-inline.test.tsx`
-Expected: FAIL with "Cannot find module '@/components/feedback/duplicate-suggestions-inline'"
-
-**Step 3: Write minimal implementation**
-
-```tsx
-export function DuplicateSuggestionsInline({ query }: { query: string }) {
-  // fetch `/api/feedback/similar?title=${encodeURIComponent(query)}`
-  // render a compact list linking to `/feedback/:id`
-  return null;
-}
-```
-
-**Step 4: Run test to verify it passes**
-
-Run: `bun test tests/components/feedback/duplicate-suggestions-inline.test.tsx`
-Expected: PASS
-
-**Step 5: Commit**
-
-```bash
-git add components/feedback/duplicate-suggestions-inline.tsx components/feedback/embedded-feedback-form.tsx tests/components/feedback/duplicate-suggestions-inline.test.tsx
-
-git commit -m "feat: show inline duplicate suggestions"
-```

package/docs/plans/2026-01-09-project-delete-feature-design.md

@@ -1,163 +0,0 @@
-# 项目删除功能设计
-
-**日期**: 2026-01-09  
-**状态**: 已批准
-
-## 概述
-
-为项目管理功能添加删除能力，允许管理员安全地删除项目。使用输入项目名称确认的方式防止误删除。
-
-## 需求
-
-- 只有管理员（admin）可以删除项目
-- 删除前必须输入完整项目名称进行确认
-- 删除成功后跳转到项目列表页面
-- 删除是永久性的，会级联删除所有相关数据（通过数据库外键 onDelete: cascade）
-- 显示警告信息，告知用户删除的后果
-
-## 技术实现
-
-### 1. 后端 API
-
-**已存在**: `/api/projects/[projectId]` DELETE 端点
-- 权限检查：仅限 admin 角色
-- 数据库删除：使用 Drizzle ORM 删除项目记录
-- 级联删除：通过数据库外键自动处理（projects.organizationId 引用 organizations.id，设置了 onDelete: cascade）
-
-### 2. 前端组件
-
-#### 2.1 删除按钮区域（ProjectSettings 组件）
-
-**位置**: `components/project/project-settings.tsx`
-
-在现有的 Widget 配置卡片下方添加新的"危险区域"卡片：
-
-```tsx
-<Card className="border-destructive/50">
-  <CardHeader>
-    <CardTitle className="text-destructive">危险区域</CardTitle>
-    <CardDescription>
-      这些操作不可逆，请谨慎操作
-    </CardDescription>
-  </CardHeader>
-  <CardContent>
-    <div className="flex items-start justify-between">
-      <div>
-        <h4 className="font-medium">删除项目</h4>
-        <p className="text-sm text-muted-foreground">
-          永久删除此项目及其所有相关数据
-        </p>
-      </div>
-      <Button variant="destructive" onClick={openDeleteDialog}>
-        删除项目
-      </Button>
-    </div>
-  </CardContent>
-</Card>
-```
-
-#### 2.2 删除确认对话框组件
-
-**新建组件**: `components/project/delete-project-dialog.tsx`
-
-**功能要求**:
-- 使用 shadcn Dialog 组件
-- 显示警告图标和警告文本
-- 包含输入框，要求用户输入完整项目名称
-- 实时验证输入内容
-- 只有输入完全匹配时才启用删除按钮
-- 显示加载状态（删除进行中）
-- 删除成功后跳转到 `/settings/projects`
-
-**对话框内容**:
-```
-标题: 删除项目
-图标: AlertTriangle（红色）
-
-警告文本:
-此操作不可撤销。删除项目将会：
-• 永久删除项目的所有配置
-• 删除所有相关的反馈数据
-• 删除所有相关的评论和附件
-
-输入框:
-请输入项目名称 "{projectName}" 以确认删除
-
-按钮:
-- 取消（outline variant）
-- 删除项目（destructive variant，仅在输入正确时可用）
-```
-
-### 3. 状态管理和错误处理
-
-**状态**:
-- `isOpen`: 对话框是否打开
-- `isDeleting`: 是否正在删除
-- `confirmText`: 用户输入的确认文本
-- `error`: 删除错误信息
-
-**错误处理**:
-- 网络错误：显示错误提示，不关闭对话框
-- 权限错误：显示"权限不足"错误
-- 项目不存在：显示"项目未找到"错误
-
-### 4. 用户流程
-
-1. 用户在项目设置页面向下滚动到"危险区域"
-2. 点击"删除项目"按钮
-3. 弹出确认对话框
-4. 查看警告信息
-5. 输入完整项目名称
-6. 点击"删除项目"按钮（此时已启用）
-7. 显示加载状态
-8. 删除成功后自动跳转到 `/settings/projects`
-9. 显示成功提示（toast）
-
-## UI/UX 设计
-
-### 视觉层次
-- 危险区域使用浅红色边框突出显示
-- 删除按钮使用 destructive variant（红色背景）
-- 对话框中的警告图标使用红色
-- 确认输入框下方显示灰色提示文本
-
-### 可访问性
-- 对话框支持键盘导航（ESC 关闭，Tab 切换）
-- 表单提交使用 Enter 键（输入正确时）
-- 使用 ARIA 标签标记警告区域
-- 输入框有明确的 label 和 placeholder
-
-## 文件清单
-
-### 新建文件
-- `components/project/delete-project-dialog.tsx` - 删除确认对话框组件
-
-### 修改文件
-- `components/project/project-settings.tsx` - 添加危险区域和删除按钮
-
-### 依赖组件（已存在）
-- `components/ui/dialog.tsx` - shadcn Dialog 组件
-- `components/ui/button.tsx` - shadcn Button 组件
-- `components/ui/card.tsx` - shadcn Card 组件
-- `components/ui/input.tsx` - shadcn Input 组件
-
-## 安全考虑
-
-1. **权限控制**: 后端 API 已实现，仅 admin 可删除
-2. **确认机制**: 必须输入完整项目名称，防止误操作
-3. **不可逆警告**: 明确告知用户删除后果
-4. **级联删除**: 数据库层面自动处理，避免孤立数据
-
-## 测试要点
-
-1. **权限测试**: 非 admin 用户不应看到删除按钮
-2. **输入验证**: 只有完全匹配才能启用删除按钮
-3. **删除成功**: 项目被删除并跳转到列表页
-4. **错误处理**: 网络错误、权限错误等正确显示
-5. **级联删除**: 相关数据正确删除（需数据库层面验证）
-
-## 未来优化
-
-1. 软删除：考虑添加 deletedAt 字段实现软删除
-2. 删除前统计：显示将被删除的反馈数量
-3. 导出备份：删除前允许导出项目数据