@nexttylabs/echo 0.2.0

package/docs/plans/2026-01-09-phase2-3-plan.md

@@ -0,0 +1,654 @@
+# Phase 2 & Phase 3 Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Deliver Phase 2 (JWT identify + portal theming + portal copy + sorting + contributors + analytics + sharing) and Phase 3 (project switcher + anonymous submissions + portal SEO + multilingual + portal module toggle).
+
+**Architecture:** Add a JWT identify endpoint for frictionless sessions, a portal theme/copy/sorting config layer that drives UI and defaults, and contributor/leaderboard settings that can be toggled or anonymized. Extend portal capabilities with analytics, sharing, project filters, anonymous submissions, SEO configuration, multilingual support, and module enable/disable switches.
+
+**Tech Stack:** Next.js App Router, React 19, TypeScript, Tailwind v4, Drizzle, bun:test
+
+---
+
+## Phase 2 (Growth)
+
+### Task 1: JWT Identify API
+
+**Files:**
+- Create: `app/api/identify/jwt/route.ts`
+- Create: `lib/auth/jwt-identity.ts`
+- Test: `tests/api/identify-jwt.test.ts`
+
+**Step 1: Write the failing test**
+
+```ts
+import { describe, expect, it } from "bun:test";
+import { parseJwtIdentity } from "@/lib/auth/jwt-identity";
+
+describe("parseJwtIdentity", () => {
+  it("returns null when token is empty", () => {
+    expect(parseJwtIdentity("")).toBe(null);
+  });
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun test tests/api/identify-jwt.test.ts`
+Expected: FAIL with "Cannot find module '@/lib/auth/jwt-identity'"
+
+**Step 3: Write minimal implementation**
+
+```ts
+export function parseJwtIdentity(token: string) {
+  if (!token) return null;
+  return { token };
+}
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun test tests/api/identify-jwt.test.ts`
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add app/api/identify/jwt/route.ts lib/auth/jwt-identity.ts tests/api/identify-jwt.test.ts
+
+git commit -m "feat: add jwt identify endpoint"
+```
+
+---
+
+### Task 2: Portal Theme Templates + Branding
+
+**Files:**
+- Create: `lib/portal/theme.ts`
+- Create: `app/(dashboard)/settings/portal-theme/page.tsx`
+- Modify: `app/portal/page.tsx`
+- Test: `tests/lib/portal-theme.test.ts`
+
+**Step 1: Write the failing test**
+
+```ts
+import { describe, expect, it } from "bun:test";
+import { getDefaultPortalTheme } from "@/lib/portal/theme";
+
+describe("portal theme", () => {
+  it("returns a default theme", () => {
+    expect(getDefaultPortalTheme()).toHaveProperty("name");
+  });
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun test tests/lib/portal-theme.test.ts`
+Expected: FAIL with "Cannot find module '@/lib/portal/theme'"
+
+**Step 3: Write minimal implementation**
+
+```ts
+export function getDefaultPortalTheme() {
+  return { name: "clean" };
+}
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun test tests/lib/portal-theme.test.ts`
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add lib/portal/theme.ts app/(dashboard)/settings/portal-theme/page.tsx app/portal/page.tsx tests/lib/portal-theme.test.ts
+
+git commit -m "feat: add portal theme config"
+```
+
+---
+
+### Task 3: Portal Copy + CTA Customization
+
+**Files:**
+- Create: `lib/portal/portal-copy.ts`
+- Create: `app/(dashboard)/settings/portal-copy/page.tsx`
+- Modify: `components/portal/portal-shell.tsx`
+- Test: `tests/lib/portal-copy.test.ts`
+
+**Step 1: Write the failing test**
+
+```ts
+import { describe, expect, it } from "bun:test";
+import { getDefaultPortalCopy } from "@/lib/portal/portal-copy";
+
+describe("portal copy", () => {
+  it("returns defaults", () => {
+    const copy = getDefaultPortalCopy();
+    expect(copy).toHaveProperty("title");
+    expect(copy).toHaveProperty("ctaLabel");
+  });
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun test tests/lib/portal-copy.test.ts`
+Expected: FAIL with "Cannot find module '@/lib/portal/portal-copy'"
+
+**Step 3: Write minimal implementation**
+
+```ts
+export function getDefaultPortalCopy() {
+  return { title: "反馈中心", description: "", ctaLabel: "提交反馈" };
+}
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun test tests/lib/portal-copy.test.ts`
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add lib/portal/portal-copy.ts app/(dashboard)/settings/portal-copy/page.tsx components/portal/portal-shell.tsx tests/lib/portal-copy.test.ts
+
+git commit -m "feat: add portal copy settings"
+```
+
+---
+
+### Task 4: Default Sorting Configuration
+
+**Files:**
+- Create: `lib/portal/sorting.ts`
+- Modify: `components/portal/portal-shell.tsx`
+- Test: `tests/lib/portal-sorting.test.ts`
+
+**Step 1: Write the failing test**
+
+```ts
+import { describe, expect, it } from "bun:test";
+import { getDefaultPortalSorting } from "@/lib/portal/sorting";
+
+describe("portal sorting", () => {
+  it("defaults to top", () => {
+    expect(getDefaultPortalSorting().order).toBe("top");
+  });
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun test tests/lib/portal-sorting.test.ts`
+Expected: FAIL with "Cannot find module '@/lib/portal/sorting'"
+
+**Step 3: Write minimal implementation**
+
+```ts
+export function getDefaultPortalSorting() {
+  return { order: "top" } as const;
+}
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun test tests/lib/portal-sorting.test.ts`
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add lib/portal/sorting.ts components/portal/portal-shell.tsx tests/lib/portal-sorting.test.ts
+
+git commit -m "feat: add portal default sorting"
+```
+
+---
+
+### Task 5: Contributor Levels & Badges
+
+**Files:**
+- Create: `lib/portal/contributors.ts`
+- Create: `components/portal/contributor-badge.tsx`
+- Modify: `components/feedback/feedback-detail.tsx`
+- Test: `tests/lib/portal-contributors.test.ts`
+
+**Step 1: Write the failing test**
+
+```ts
+import { describe, expect, it } from "bun:test";
+import { getContributorLevel } from "@/lib/portal/contributors";
+
+describe("contributors", () => {
+  it("returns level 1 by default", () => {
+    expect(getContributorLevel({ votes: 0, comments: 0, accepted: 0 })).toBe(1);
+  });
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun test tests/lib/portal-contributors.test.ts`
+Expected: FAIL with "Cannot find module '@/lib/portal/contributors'"
+
+**Step 3: Write minimal implementation**
+
+```ts
+export function getContributorLevel() {
+  return 1;
+}
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun test tests/lib/portal-contributors.test.ts`
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add lib/portal/contributors.ts components/portal/contributor-badge.tsx components/feedback/feedback-detail.tsx tests/lib/portal-contributors.test.ts
+
+git commit -m "feat: add contributor levels"
+```
+
+---
+
+### Task 6: Leaderboard Visibility + Anonymize Toggle
+
+**Files:**
+- Create: `lib/portal/leaderboard-settings.ts`
+- Create: `components/portal/leaderboard.tsx`
+- Modify: `app/portal/page.tsx`
+- Test: `tests/lib/portal-leaderboard-settings.test.ts`
+
+**Step 1: Write the failing test**
+
+```ts
+import { describe, expect, it } from "bun:test";
+import { getDefaultLeaderboardSettings } from "@/lib/portal/leaderboard-settings";
+
+describe("portal leaderboard settings", () => {
+  it("defaults to visible", () => {
+    expect(getDefaultLeaderboardSettings().enabled).toBe(true);
+  });
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun test tests/lib/portal-leaderboard-settings.test.ts`
+Expected: FAIL with "Cannot find module '@/lib/portal/leaderboard-settings'"
+
+**Step 3: Write minimal implementation**
+
+```ts
+export function getDefaultLeaderboardSettings() {
+  return { enabled: true, anonymizeUsers: false };
+}
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun test tests/lib/portal-leaderboard-settings.test.ts`
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add lib/portal/leaderboard-settings.ts components/portal/leaderboard.tsx app/portal/page.tsx tests/lib/portal-leaderboard-settings.test.ts
+
+git commit -m "feat: add leaderboard visibility settings"
+```
+
+---
+
+### Task 7: Portal Analytics Dashboard
+
+**Files:**
+- Create: `lib/portal/analytics.ts`
+- Create: `app/(dashboard)/analytics/portal/page.tsx`
+- Test: `tests/lib/portal-analytics.test.ts`
+
+**Step 1: Write the failing test**
+
+```ts
+import { describe, expect, it } from "bun:test";
+import { getEmptyPortalAnalytics } from "@/lib/portal/analytics";
+
+describe("portal analytics", () => {
+  it("returns default analytics structure", () => {
+    expect(getEmptyPortalAnalytics()).toHaveProperty("timeseries");
+  });
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun test tests/lib/portal-analytics.test.ts`
+Expected: FAIL with "Cannot find module '@/lib/portal/analytics'"
+
+**Step 3: Write minimal implementation**
+
+```ts
+export function getEmptyPortalAnalytics() {
+  return { timeseries: [], topViewed: [], topVoted: [], topCommented: [] };
+}
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun test tests/lib/portal-analytics.test.ts`
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add lib/portal/analytics.ts app/(dashboard)/analytics/portal/page.tsx tests/lib/portal-analytics.test.ts
+
+git commit -m "feat: add portal analytics dashboard"
+```
+
+---
+
+### Task 8: Portal Sharing Settings
+
+**Files:**
+- Create: `lib/portal/sharing.ts`
+- Create: `app/(dashboard)/settings/portal-sharing/page.tsx`
+- Test: `tests/lib/portal-sharing.test.ts`
+
+**Step 1: Write the failing test**
+
+```ts
+import { describe, expect, it } from "bun:test";
+import { getPortalShareMethods } from "@/lib/portal/sharing";
+
+describe("portal sharing", () => {
+  it("lists share methods", () => {
+    expect(getPortalShareMethods()).toEqual(["link", "widget", "embedded"]);
+  });
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun test tests/lib/portal-sharing.test.ts`
+Expected: FAIL with "Cannot find module '@/lib/portal/sharing'"
+
+**Step 3: Write minimal implementation**
+
+```ts
+export function getPortalShareMethods() {
+  return ["link", "widget", "embedded"] as const;
+}
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun test tests/lib/portal-sharing.test.ts`
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add lib/portal/sharing.ts app/(dashboard)/settings/portal-sharing/page.tsx tests/lib/portal-sharing.test.ts
+
+git commit -m "feat: add portal sharing settings"
+```
+
+---
+
+## Phase 3 (Expansion)
+
+### Task 9: Portal Project Switcher
+
+**Files:**
+- Create: `components/portal/project-switcher.tsx`
+- Modify: `app/portal/page.tsx`
+- Test: `tests/components/portal-project-switcher.test.tsx`
+
+**Step 1: Write the failing test**
+
+```ts
+import { describe, expect, it } from "bun:test";
+import { ProjectSwitcher } from "@/components/portal/project-switcher";
+
+describe("ProjectSwitcher", () => {
+  it("exports a component", () => {
+    expect(typeof ProjectSwitcher).toBe("function");
+  });
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun test tests/components/portal-project-switcher.test.tsx`
+Expected: FAIL with "Cannot find module '@/components/portal/project-switcher'"
+
+**Step 3: Write minimal implementation**
+
+```tsx
+export function ProjectSwitcher() {
+  return null;
+}
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun test tests/components/portal-project-switcher.test.tsx`
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add components/portal/project-switcher.tsx app/portal/page.tsx tests/components/portal-project-switcher.test.tsx
+
+git commit -m "feat: add portal project switcher"
+```
+
+---
+
+### Task 10: Anonymous Submissions
+
+**Files:**
+- Modify: `lib/validators/feedback.ts`
+- Modify: `components/feedback/embedded-feedback-form.tsx`
+- Modify: `app/api/feedback/route.ts`
+- Test: `tests/lib/feedback-schema.test.ts`
+
+**Step 1: Write the failing test**
+
+```ts
+import { describe, expect, it } from "bun:test";
+import { feedbackSchema } from "@/lib/validators/feedback";
+
+describe("feedback schema", () => {
+  it("supports anonymous", () => {
+    const result = feedbackSchema.safeParse({
+      title: "t",
+      description: "d",
+      isAnonymous: true,
+    });
+    expect(result.success).toBe(true);
+  });
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun test tests/lib/feedback-schema.test.ts`
+Expected: FAIL with "Unknown key 'isAnonymous'"
+
+**Step 3: Write minimal implementation**
+
+```ts
+export const feedbackSchema = baseFeedbackSchema.extend({
+  submittedOnBehalf: z.boolean().optional().default(false),
+  customerInfo: customerInfoSchema.optional(),
+  isAnonymous: z.boolean().optional().default(false),
+});
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun test tests/lib/feedback-schema.test.ts`
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add lib/validators/feedback.ts components/feedback/embedded-feedback-form.tsx app/api/feedback/route.ts tests/lib/feedback-schema.test.ts
+
+git commit -m "feat: support anonymous feedback"
+```
+
+---
+
+### Task 11: Portal SEO Configuration
+
+**Files:**
+- Create: `lib/portal/seo.ts`
+- Create: `app/(dashboard)/settings/portal-seo/page.tsx`
+- Modify: `app/portal/page.tsx`
+- Test: `tests/lib/portal-seo.test.ts`
+
+**Step 1: Write the failing test**
+
+```ts
+import { describe, expect, it } from "bun:test";
+import { getDefaultPortalSeo } from "@/lib/portal/seo";
+
+describe("portal seo", () => {
+  it("returns defaults", () => {
+    expect(getDefaultPortalSeo()).toHaveProperty("title");
+  });
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun test tests/lib/portal-seo.test.ts`
+Expected: FAIL with "Cannot find module '@/lib/portal/seo'"
+
+**Step 3: Write minimal implementation**
+
+```ts
+export function getDefaultPortalSeo() {
+  return { title: "反馈中心" };
+}
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun test tests/lib/portal-seo.test.ts`
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add lib/portal/seo.ts app/(dashboard)/settings/portal-seo/page.tsx app/portal/page.tsx tests/lib/portal-seo.test.ts
+
+git commit -m "feat: add portal seo config"
+```
+
+---
+
+### Task 12: Multilingual Portal Settings
+
+**Files:**
+- Create: `lib/portal/i18n.ts`
+- Create: `app/(dashboard)/settings/portal-languages/page.tsx`
+- Modify: `app/portal/page.tsx`
+- Test: `tests/lib/portal-i18n.test.ts`
+
+**Step 1: Write the failing test**
+
+```ts
+import { describe, expect, it } from "bun:test";
+import { getDefaultPortalI18n } from "@/lib/portal/i18n";
+
+describe("portal i18n", () => {
+  it("returns default locale", () => {
+    expect(getDefaultPortalI18n().defaultLocale).toBe("en");
+  });
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun test tests/lib/portal-i18n.test.ts`
+Expected: FAIL with "Cannot find module '@/lib/portal/i18n'"
+
+**Step 3: Write minimal implementation**
+
+```ts
+export function getDefaultPortalI18n() {
+  return { defaultLocale: "en", supportedLocales: ["en", "zh-CN"] };
+}
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun test tests/lib/portal-i18n.test.ts`
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add lib/portal/i18n.ts app/(dashboard)/settings/portal-languages/page.tsx app/portal/page.tsx tests/lib/portal-i18n.test.ts
+
+git commit -m "feat: add portal language settings"
+```
+
+---
+
+### Task 13: Portal Module Toggle (Disable Feedback View)
+
+**Files:**
+- Create: `lib/portal/modules.ts`
+- Modify: `app/portal/page.tsx`
+- Test: `tests/lib/portal-modules.test.ts`
+
+**Step 1: Write the failing test**
+
+```ts
+import { describe, expect, it } from "bun:test";
+import { getDefaultPortalModules } from "@/lib/portal/modules";
+
+describe("portal modules", () => {
+  it("enables feedback module by default", () => {
+    expect(getDefaultPortalModules().feedback).toBe(true);
+  });
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun test tests/lib/portal-modules.test.ts`
+Expected: FAIL with "Cannot find module '@/lib/portal/modules'"
+
+**Step 3: Write minimal implementation**
+
+```ts
+export function getDefaultPortalModules() {
+  return { feedback: true, roadmap: true, changelog: true, help: true };
+}
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun test tests/lib/portal-modules.test.ts`
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add lib/portal/modules.ts app/portal/page.tsx tests/lib/portal-modules.test.ts
+
+git commit -m "feat: add portal module toggles"
+```