@nexttylabs/echo 0.4.0 → 0.6.0

package/docs/plans/2026-01-16-admin-feedback-filters-implementation.md

@@ -1,293 +0,0 @@
-# Admin Feedback Filters & Sorting Implementation Plan
-
-> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
-
-**Goal:** Add URL-driven filters/sorting/pagination to /admin/feedback, including assignee/hasVotes/hasReplies, plus members API with client caching.
-
-**Architecture:** Server-side query parameters drive list data. A new members endpoint provides assignee candidates. Frontend controls update URL, triggering fetches. Data remains in existing feedback API.
-
-**Tech Stack:** Next.js App Router, React 19, TypeScript, Tailwind v4, Bun, Drizzle ORM.
-
----
-
-### Task 1: Add organization members list endpoint
-
-**Files:**
-- Create: `app/api/organizations/[orgId]/members/route.ts`
-- Create: `app/api/organizations/[orgId]/members/handler.ts`
-- Test: `tests/api/organization-members-list.test.ts`
-
-**Step 1: Write the failing test**
-
-```ts
-import { describe, expect, it, mock } from "bun:test";
-import { NextRequest } from "next/server";
-
-describe("GET /api/organizations/[orgId]/members", () => {
-  it("returns members with displayName", async () => {
-    const mockDb = {
-      select: mock(() => ({
-        from: mock(() => ({
-          innerJoin: mock(() => ({
-            where: mock(() => Promise.resolve([
-              { userId: "user_1", displayName: "Ada" },
-            ])),
-          })),
-        })),
-      })),
-    };
-
-    mock.module("@/lib/auth/config", () => ({
-      auth: { api: { getSession: mock(() => Promise.resolve({ user: { id: "user_1" } })) } },
-    }));
-
-    mock.module("@/lib/db", () => ({ db: mockDb }));
-
-    const { GET } = await import("@/app/api/organizations/[orgId]/members/route");
-    const req = new NextRequest("http://localhost:3000/api/organizations/org_1/members");
-    const res = await GET(req, { params: Promise.resolve({ orgId: "org_1" }) });
-
-    expect(res.status).toBe(200);
-    const json = await res.json();
-    expect(json.data[0]).toHaveProperty("userId");
-    expect(json.data[0]).toHaveProperty("displayName");
-  });
-});
-```
-
-**Step 2: Run test to verify it fails**
-
-Run: `bun test tests/api/organization-members-list.test.ts`
-Expected: FAIL (module not found or handler missing)
-
-**Step 3: Write minimal implementation**
-
-```ts
-// handler.ts
-import { NextResponse } from "next/server";
-import { assertOrganizationAccess } from "@/lib/auth/organization";
-import { organizationMembers, user } from "@/lib/db/schema";
-import { eq } from "drizzle-orm";
-
-export function buildListMembersHandler({ auth, db }: { auth: any; db: any }) {
-  return async function GET(req: Request, context: { params: { orgId: string } | Promise<{ orgId: string }> }) {
-    const session = await auth.api.getSession({ headers: req.headers });
-    if (!session) return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
-
-    const { orgId } = await Promise.resolve(context.params);
-    try {
-      await assertOrganizationAccess(db, session.user.id, orgId);
-    } catch {
-      return NextResponse.json({ error: "Forbidden" }, { status: 403 });
-    }
-
-    const rows = await db
-      .select({
-        userId: organizationMembers.userId,
-        displayName: user.name,
-        email: user.email,
-      })
-      .from(organizationMembers)
-      .innerJoin(user, eq(organizationMembers.userId, user.id))
-      .where(eq(organizationMembers.organizationId, orgId));
-
-    const data = rows.map((row: any) => ({
-      userId: row.userId,
-      displayName: row.displayName ?? row.email ?? "未知成员",
-    }));
-
-    return NextResponse.json({ data }, { status: 200 });
-  };
-}
-```
-
-**Step 4: Run test to verify it passes**
-
-Run: `bun test tests/api/organization-members-list.test.ts`
-Expected: PASS
-
-**Step 5: Commit**
-
-```bash
-git add app/api/organizations/[orgId]/members/route.ts app/api/organizations/[orgId]/members/handler.ts tests/api/organization-members-list.test.ts
-git commit -m "feat: add organization members list endpoint"
-```
-
----
-
-### Task 2: Add query param parsing/serialization helpers
-
-**Files:**
-- Create: `lib/feedback/filters.ts`
-- Test: `tests/feedback/filters.test.ts`
-
-**Step 1: Write the failing test**
-
-```ts
-import { describe, expect, it } from "bun:test";
-import { parseCsvParam, serializeCsvParam } from "@/lib/feedback/filters";
-
-describe("filters helpers", () => {
-  it("parses csv into array", () => {
-    expect(parseCsvParam("a,b")).toEqual(["a", "b"]);
-  });
-
-  it("serializes array into csv", () => {
-    expect(serializeCsvParam(["a", "b"])).toBe("a,b");
-  });
-});
-```
-
-**Step 2: Run test to verify it fails**
-
-Run: `bun test tests/feedback/filters.test.ts`
-Expected: FAIL (module missing)
-
-**Step 3: Write minimal implementation**
-
-```ts
-export function parseCsvParam(value?: string | null) {
-  if (!value) return [];
-  return value
-    .split(",")
-    .map((item) => item.trim())
-    .filter(Boolean);
-}
-
-export function serializeCsvParam(values: string[]) {
-  return values.filter(Boolean).join(",");
-}
-```
-
-**Step 4: Run test to verify it passes**
-
-Run: `bun test tests/feedback/filters.test.ts`
-Expected: PASS
-
-**Step 5: Commit**
-
-```bash
-git add lib/feedback/filters.ts tests/feedback/filters.test.ts
-git commit -m "chore: add feedback filter helpers"
-```
-
----
-
-### Task 3: Add Feedback list controls UI (filters + sorting)
-
-**Files:**
-- Create: `components/feedback/feedback-list-controls.tsx`
-- Modify: `components/feedback/feedback-list.tsx`
-- Modify: `components/shared/pagination.tsx`
-
-**Step 1: Write the failing test**
-
-```ts
-import { describe, expect, it } from "bun:test";
-import { render } from "@testing-library/react";
-import { FeedbackListControls } from "@/components/feedback/feedback-list-controls";
-
-describe("FeedbackListControls", () => {
-  it("renders filters and sort controls", () => {
-    const { getByLabelText } = render(
-      <FeedbackListControls
-        organizationId="org_1"
-        total={10}
-        pageSize={20}
-        onUpdate={() => {}}
-      />
-    );
-    expect(getByLabelText("搜索反馈")).toBeTruthy();
-  });
-});
-```
-
-**Step 2: Run test to verify it fails**
-
-Run: `bun test tests/components/feedback-list-controls.test.tsx`
-Expected: FAIL (component missing)
-
-**Step 3: Write minimal implementation**
-
-- Add controls for search, status/type/priority/assignee/hasVotes/hasReplies, and sort
-- Read/write URL params via `useSearchParams` + `useRouter`
-- Reset page to 1 on change
-- Add cached assignee list loading
-- Update `FeedbackList` to pass current params and render controls
-- Add `aria-label` to pagination icon buttons and replace "..." with "…"
-
-**Step 4: Run test to verify it passes**
-
-Run: `bun test tests/components/feedback-list-controls.test.tsx`
-Expected: PASS
-
-**Step 5: Commit**
-
-```bash
-git add components/feedback/feedback-list-controls.tsx components/feedback/feedback-list.tsx components/shared/pagination.tsx
-git commit -m "feat: add feedback list controls"
-```
-
----
-
-### Task 4: Extend /api/feedback filtering for new params
-
-**Files:**
-- Modify: `app/api/feedback/route.ts`
-- Modify: `app/api/feedback/handler.ts`
-- Test: `tests/api/feedback-filter.test.ts`
-
-**Step 1: Write the failing test**
-
-```ts
-it("filters by assignee and hasVotes", async () => {
-  const req = new NextRequest("http://localhost:3000/api/feedback?assignee=user_1&hasVotes=true&organizationId=org_1");
-  const res = await GET(req);
-  expect(res.status).toBe(200);
-});
-```
-
-**Step 2: Run test to verify it fails**
-
-Run: `bun test tests/api/feedback-filter.test.ts`
-Expected: FAIL (missing behavior)
-
-**Step 3: Write minimal implementation**
-
-- Parse CSV params for `status/type/priority/assignee/hasVotes/hasReplies`
-- Apply `assignee` filter (includes `unassigned`)
-- Apply `hasVotes` filter (`voteCount > 0` or `= 0`)
-- Apply `hasReplies` filter (`replyCount > 0` or `= 0`)
-
-**Step 4: Run test to verify it passes**
-
-Run: `bun test tests/api/feedback-filter.test.ts`
-Expected: PASS
-
-**Step 5: Commit**
-
-```bash
-git add app/api/feedback/route.ts app/api/feedback/handler.ts tests/api/feedback-filter.test.ts
-git commit -m "feat: add feedback filters for assignee and replies"
-```
-
----
-
-### Task 5: Full verification
-
-**Step 1: Run lint**
-
-Run: `bun run lint`
-Expected: 0 errors
-
-**Step 2: Run relevant tests**
-
-Run: `bun test tests/api/organization-members-list.test.ts tests/feedback/filters.test.ts tests/components/feedback-list-controls.test.tsx tests/api/feedback-filter.test.ts`
-Expected: PASS
-
-**Step 3: Commit any remaining fixes**
-
-```bash
-git add -A
-git commit -m "chore: finalize feedback filters"
-```

package/docs/plans/2026-01-16-admin-feedback-route-consolidation.md

@@ -1,180 +0,0 @@
-# Admin Feedback Route Consolidation Implementation Plan
-
-> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
-
-**Goal:** Move all feedback management routes under `/admin`, removing legacy `/feedback` and `/feedback/new` dashboard paths.
-
-**Architecture:** Keep admin list and detail at `/admin/feedback` and `/admin/feedback/[id]`, add `/admin/feedback/new` by moving the submit-on-behalf page, and delete the old dashboard feedback list. Update all internal links and list defaults to use the `/admin` base. No redirects.
-
-**Tech Stack:** Next.js App Router, React, TypeScript, Tailwind CSS, Bun.
-
-### Task 1: Remove legacy dashboard feedback list route
-
-**Files:**
-- Delete: `app/(dashboard)/feedback/page.tsx`
-
-**Step 1: Write the failing test**
-
-```ts
-// tests/e2e/feedback-management.spec.ts (add a case asserting /feedback is 404)
-// Example (Playwright):
-// await page.goto("/feedback");
-// await expect(page.getByText("Not Found")).toBeVisible();
-```
-
-**Step 2: Run test to verify it fails**
-
-Run: `bun run test tests/e2e/feedback-management.spec.ts`
-Expected: FAIL because `/feedback` still exists
-
-**Step 3: Remove the legacy route**
-
-```ts
-// Delete file: app/(dashboard)/feedback/page.tsx
-```
-
-**Step 4: Run test to verify it passes**
-
-Run: `bun run test tests/e2e/feedback-management.spec.ts`
-Expected: PASS
-
-**Step 5: Commit**
-
-```bash
-git add app/(dashboard)/feedback/page.tsx tests/e2e/feedback-management.spec.ts
-git commit -m "refactor: remove legacy feedback list route"
-```
-
-### Task 2: Move submit-on-behalf route under /admin
-
-**Files:**
-- Move: `app/(dashboard)/feedback/new/page.tsx` → `app/(dashboard)/admin/feedback/new/page.tsx`
-
-**Step 1: Write the failing test**
-
-```ts
-// tests/e2e/feedback-customer.spec.ts (update /feedback/new -> /admin/feedback/new and assert old path 404)
-```
-
-**Step 2: Run test to verify it fails**
-
-Run: `bun run test tests/e2e/feedback-customer.spec.ts`
-Expected: FAIL with old URL
-
-**Step 3: Move the route file**
-
-```bash
-mkdir -p app/(dashboard)/admin/feedback/new
-mv app/(dashboard)/feedback/new/page.tsx app/(dashboard)/admin/feedback/new/page.tsx
-```
-
-**Step 4: Run test to verify it passes**
-
-Run: `bun run test tests/e2e/feedback-customer.spec.ts`
-Expected: PASS
-
-**Step 5: Commit**
-
-```bash
-git add app/(dashboard)/admin/feedback/new/page.tsx app/(dashboard)/feedback/new/page.tsx tests/e2e/feedback-customer.spec.ts
-git commit -m "refactor: move submit-on-behalf route under admin"
-```
-
-### Task 3: Update navigation links to /admin
-
-**Files:**
-- Modify: `components/layout/sidebar.tsx`
-- Modify: `components/dashboard/quick-actions.tsx`
-- Modify: `components/dashboard/recent-feedback-list.tsx`
-
-**Step 1: Write the failing test**
-
-```ts
-// tests/e2e/feedback-management.spec.ts or a unit test
-// Assert sidebar/quick-actions links resolve to /admin/feedback and /admin/feedback/new
-```
-
-**Step 2: Run test to verify it fails**
-
-Run: `bun run test tests/e2e/feedback-management.spec.ts`
-Expected: FAIL (links still /feedback)
-
-**Step 3: Update links**
-
-```ts
-// sidebar: /feedback -> /admin/feedback
-// quick-actions: /feedback -> /admin/feedback
-// recent-feedback-list: /feedback -> /admin/feedback, /feedback/new -> /admin/feedback/new
-```
-
-**Step 4: Run test to verify it passes**
-
-Run: `bun run test tests/e2e/feedback-management.spec.ts`
-Expected: PASS
-
-**Step 5: Commit**
-
-```bash
-git add components/layout/sidebar.tsx components/dashboard/quick-actions.tsx components/dashboard/recent-feedback-list.tsx tests/e2e/feedback-management.spec.ts
-git commit -m "refactor: point feedback navigation to admin routes"
-```
-
-### Task 4: Default feedback list base path to /admin
-
-**Files:**
-- Modify: `components/feedback/feedback-list.tsx`
-- Modify: `components/feedback/feedback-list-item.tsx`
-
-**Step 1: Write the failing test**
-
-```ts
-// tests/components/feedback/feedback-list.test.tsx (new)
-// Render FeedbackList without basePath and assert item links are /admin/feedback/:id
-```
-
-**Step 2: Run test to verify it fails**
-
-Run: `bun run test tests/components/feedback/feedback-list.test.tsx`
-Expected: FAIL because default basePath is /feedback
-
-**Step 3: Update defaults**
-
-```ts
-// basePath default: "/feedback" -> "/admin/feedback"
-```
-
-**Step 4: Run test to verify it passes**
-
-Run: `bun run test tests/components/feedback/feedback-list.test.tsx`
-Expected: PASS
-
-**Step 5: Commit**
-
-```bash
-git add components/feedback/feedback-list.tsx components/feedback/feedback-list-item.tsx tests/components/feedback/feedback-list.test.tsx
-git commit -m "refactor: default feedback list links to admin"
-```
-
-### Task 5: Verification
-
-**Files:**
-- (No new files)
-
-**Step 1: Run lint**
-
-Run: `bun run lint`
-Expected: Warnings only; no new errors
-
-**Step 2: Smoke-check routes**
-
-- `/admin/feedback` loads list
-- `/admin/feedback/[id]` loads detail
-- `/admin/feedback/new` loads submit-on-behalf form
-- `/feedback` and `/feedback/new` 404
-
-**Step 3: Commit (if needed)**
-
-```bash
-git add -A
-git commit -m "chore: verify admin feedback routes"
-```

package/docs/plans/2026-01-16-e2e-test-fixes.md

@@ -1,158 +0,0 @@
-# E2E Test Fixes Implementation Plan
-
-> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
-
-**Goal:** Run the requested Playwright E2E specs and fix any failures until they pass.
-
-**Architecture:** Use the existing Playwright specs as the failing tests, trace failures to the responsible UI/API layer, and apply minimal, targeted fixes. Re-run each spec after each fix to validate.
-
-**Tech Stack:** Next.js (App Router), React, TypeScript, Bun, Playwright.
-
----
-
-### Task 1: Establish execution workspace
-
-**Files:**
-- Modify: `.gitignore` (only if `.worktrees/` is not ignored)
-
-**Step 1: Check preferred worktree directory**
-Run: `ls -d .worktrees 2>/dev/null || ls -d worktrees 2>/dev/null`
-Expected: one of the directories exists; otherwise proceed to CLAUDE.md preference.
-
-**Step 2: Check CLAUDE.md for worktree guidance**
-Run: `grep -i "worktree.*director" CLAUDE.md 2>/dev/null`
-Expected: guidance or no output.
-
-**Step 3: Verify ignore if using project-local directory**
-Run: `git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null`
-Expected: zero exit code; if not ignored, add and commit `.gitignore` entry.
-
-**Step 4: Create worktree and install deps**
-Run:
-```
-project=$(basename "$(git rev-parse --show-toplevel)")
-branch="fix/e2e-tests-2026-01-16"
-path=".worktrees/$branch"
-
-git worktree add "$path" -b "$branch"
-cd "$path"
-bun install
-```
-Expected: worktree created and dependencies installed.
-
-**Step 5: Baseline test command (single spec)**
-Run: `bunx playwright test tests/e2e/health-check.spec.ts`
-Expected: If failing, stop and report; if passing, continue.
-
----
-
-### Task 2: Fix `tests/e2e/feedback-management.spec.ts`
-
-**Files:**
-- Modify: `tests/e2e/feedback-management.spec.ts`
-- Modify: `app/**` (as indicated by failure)
-
-**Step 1: Run spec to capture failure**
-Run: `bunx playwright test tests/e2e/feedback-management.spec.ts`
-Expected: FAIL with specific error output.
-
-**Step 2: Root cause investigation**
-- Identify failing assertion, locator, or API response in the error output.
-- Trace to the source file indicated by stack/trace.
-
-**Step 3: Minimal fix**
-- Update the failing locator/expectation to match current UI OR fix the underlying UI/API issue.
-- Keep scope minimal; avoid refactors.
-
-**Step 4: Verify**
-Run: `bunx playwright test tests/e2e/feedback-management.spec.ts`
-Expected: PASS.
-
----
-
-### Task 3: Fix `tests/e2e/feedback-submit.spec.ts`
-
-**Files:**
-- Modify: `tests/e2e/feedback-submit.spec.ts`
-- Modify: `app/**` (as indicated by failure)
-
-**Step 1: Run spec to capture failure**
-Run: `bunx playwright test tests/e2e/feedback-submit.spec.ts`
-Expected: FAIL with specific error output.
-
-**Step 2: Root cause investigation**
-- Identify failing step, response, or UI mismatch.
-- Trace to responsible route/component.
-
-**Step 3: Minimal fix**
-- Adjust test expectations or fix underlying behavior.
-
-**Step 4: Verify**
-Run: `bunx playwright test tests/e2e/feedback-submit.spec.ts`
-Expected: PASS.
-
----
-
-### Task 4: Fix `tests/e2e/feedback-view.spec.ts`
-
-**Files:**
-- Modify: `tests/e2e/feedback-view.spec.ts`
-- Modify: `app/**` (as indicated by failure)
-
-**Step 1: Run spec to capture failure**
-Run: `bunx playwright test tests/e2e/feedback-view.spec.ts`
-Expected: FAIL with specific error output.
-
-**Step 2: Root cause investigation**
-- Identify failing expectations and any missing data/fixtures.
-- Trace to page/data-loading code.
-
-**Step 3: Minimal fix**
-- Adjust test to current UI or fix underlying page/data.
-
-**Step 4: Verify**
-Run: `bunx playwright test tests/e2e/feedback-view.spec.ts`
-Expected: PASS.
-
----
-
-### Task 5: Fix `tests/e2e/health-check.spec.ts`
-
-**Files:**
-- Modify: `app/health/route.ts`
-- Modify: `tests/e2e/health-check.spec.ts` (only if test is outdated)
-
-**Step 1: Run spec to capture failure**
-Run: `bunx playwright test tests/e2e/health-check.spec.ts`
-Expected: FAIL with specific error output.
-
-**Step 2: Root cause investigation**
-- Verify health endpoint route exists and matches test expectation.
-- Validate response shape and status.
-
-**Step 3: Minimal fix**
-- Adjust endpoint or test to align expected contract.
-
-**Step 4: Verify**
-Run: `bunx playwright test tests/e2e/health-check.spec.ts`
-Expected: PASS.
-
----
-
-### Task 6: Final verification (requested specs)
-
-**Files:**
-- None (test run)
-
-**Step 1: Run requested specs in order**
-Run:
-```
-bunx playwright test tests/e2e/feedback-management.spec.ts
-bunx playwright test tests/e2e/feedback-submit.spec.ts
-bunx playwright test tests/e2e/feedback-view.spec.ts
-bunx playwright test tests/e2e/health-check.spec.ts
-```
-Expected: All PASS.
-
-**Step 2: Report results**
-Summarize changes, test outcomes, and any follow-ups.