@nexttylabs/echo 0.2.0

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

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

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

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