@nexttylabs/echo 0.4.0 → 0.5.0

package/docs/plans/2026-01-10-project-settings-tabs-design-implementation.md

@@ -1,296 +0,0 @@
-# Project Settings Tabs Implementation Plan
-
-> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
-
-**Goal:** Restructure project settings into three top-level tabs (通用设置 / Widget / Portal) and embed the Portal overview flow within the Portal tab.
-
-**Architecture:** Convert the project settings UI into a tabbed layout using the existing shadcn Tabs component. Extract the Portal overview into a reusable component so it can be rendered both inside the Portal tab and the dedicated Portal route pages.
-
-**Tech Stack:** Next.js App Router, React 19, TypeScript, shadcn/ui (Tabs, Card, Button, Badge, Switch), Tailwind CSS.
-
-### Task 1: Add a reusable Portal overview component
-
-**Files:**
-- Create: `components/portal/portal-overview.tsx`
-- Modify: `app/(dashboard)/settings/projects/[projectSlug]/portal/page.tsx`
-- Test: `tests/components/portal-overview.test.tsx`
-
-**Step 1: Write the failing test**
-
-```ts
-import { describe, expect, it } from "bun:test";
-import { PortalOverview } from "@/components/portal/portal-overview";
-
-describe("PortalOverview", () => {
-  it("exports a component", () => {
-    expect(typeof PortalOverview).toBe("function");
-  });
-});
-```
-
-**Step 2: Run test to verify it fails**
-
-Run: `bun test tests/components/portal-overview.test.tsx`
-Expected: FAIL with "Cannot find module '@/components/portal/portal-overview'"
-
-**Step 3: Write minimal implementation**
-
-```tsx
-import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
-import { Badge } from "@/components/ui/badge";
-import { Button } from "@/components/ui/button";
-import { PortalModulesPanel } from "@/components/portal/portal-modules-panel";
-import { getDefaultPortalModules } from "@/lib/portal/modules";
-import type { PortalConfig } from "@/lib/db/schema/projects";
-
-export function PortalOverview({
-  projectSlug,
-  portalLink,
-  portalConfig,
-  projectId,
-}: {
-  projectSlug: string;
-  portalLink: string;
-  portalConfig: PortalConfig | null;
-  projectId: string;
-}) {
-  const portalEnabled = portalConfig?.sharing?.enabled ?? true;
-  const themeSummary = portalConfig?.theme?.primaryColor
-    ? `主色 ${portalConfig.theme.primaryColor}`
-    : "使用默认主题";
-  const languageSummary = portalConfig?.defaultLanguage ?? "zh-CN";
-  const seoSummary = portalConfig?.seo?.metaTitle
-    ? portalConfig.seo.metaTitle
-    : "未设置 SEO 标题";
-
-  const modules = portalConfig?.modules ?? getDefaultPortalModules();
-
-  return (
-    <div className="space-y-8">
-      <Card className="border-slate-200/80 bg-white/80 shadow-sm">
-        <CardHeader className="flex flex-col gap-3 md:flex-row md:items-center md:justify-between">
-          <div>
-            <CardTitle className="text-xl">Portal 状态</CardTitle>
-            <CardDescription>当前项目的门户入口与可见性</CardDescription>
-          </div>
-          <div className="flex flex-wrap items-center gap-3">
-            <Badge variant={portalEnabled ? "default" : "outline"}>
-              {portalEnabled ? "公开中" : "已关闭"}
-            </Badge>
-            <Button asChild variant="outline" size="sm">
-              <a href={portalLink}>预览 Portal</a>
-            </Button>
-            <Button asChild size="sm">
-              <a href={portalLink}>打开 Portal</a>
-            </Button>
-          </div>
-        </CardHeader>
-        <CardContent>
-          <div className="text-sm text-slate-600">
-            门户链接：<span className="font-medium text-slate-900">{portalLink}</span>
-          </div>
-        </CardContent>
-      </Card>
-
-      <div className="grid gap-6 lg:grid-cols-3">
-        <PortalGroupCard
-          title="体验"
-          description="主题、文案与语言"
-          items={[
-            themeSummary,
-            portalConfig?.copy?.title ? `标题：${portalConfig.copy.title}` : "未设置门户标题",
-            `默认语言：${languageSummary}`,
-          ]}
-          href={`/settings/projects/${projectSlug}/portal/experience`}
-        />
-        <PortalGroupCard
-          title="传播"
-          description="分享与 SEO 配置"
-          items={[
-            seoSummary,
-            portalConfig?.sharing?.socialSharing ? "社交分享已配置" : "未配置社交分享",
-            portalConfig?.seo?.ogImage ? "已设置 OG 图片" : "未设置 OG 图片",
-          ]}
-          href={`/settings/projects/${projectSlug}/portal/growth`}
-        />
-        <PortalGroupCard
-          title="可见性"
-          description="公开权限与索引"
-          items={[
-            portalEnabled ? "门户公开" : "门户关闭",
-            portalConfig?.sharing?.allowPublicVoting ? "允许公开投票" : "关闭公开投票",
-            portalConfig?.seo?.noIndex ? "禁止索引" : "允许索引",
-          ]}
-          href={`/settings/projects/${projectSlug}/portal/access`}
-        />
-      </div>
-
-      <details className="group">
-        <summary className="cursor-pointer list-none text-sm font-semibold text-slate-700">
-          <span className="inline-flex items-center gap-2">
-            <span className="rounded-full bg-slate-200 px-2 py-0.5 text-xs font-medium text-slate-600">
-              模块开关
-            </span>
-            管理 Portal 模块显示
-          </span>
-        </summary>
-        <div className="mt-4">
-          <PortalModulesPanel projectId={projectId} initialModules={modules} />
-        </div>
-      </details>
-    </div>
-  );
-}
-
-function PortalGroupCard({
-  title,
-  description,
-  items,
-  href,
-}: {
-  title: string;
-  description: string;
-  items: string[];
-  href: string;
-}) {
-  return (
-    <Card className="border-slate-200/80 bg-white/80 shadow-sm">
-      <CardHeader>
-        <CardTitle className="text-lg">{title}</CardTitle>
-        <CardDescription>{description}</CardDescription>
-      </CardHeader>
-      <CardContent className="space-y-3">
-        <ul className="space-y-1 text-sm text-slate-600">
-          {items.map((item) => (
-            <li key={item}>• {item}</li>
-          ))}
-        </ul>
-        <Button asChild variant="outline" size="sm">
-          <a href={href}>进入设置</a>
-        </Button>
-      </CardContent>
-    </Card>
-  );
-}
-```
-
-**Step 4: Run test to verify it passes**
-
-Run: `bun test tests/components/portal-overview.test.tsx`
-Expected: PASS
-
-**Step 5: Commit**
-
-```bash
-git add components/portal/portal-overview.tsx app/(dashboard)/settings/projects/[projectSlug]/portal/page.tsx tests/components/portal-overview.test.tsx
-git commit -m "feat: extract portal overview component"
-```
-
-### Task 2: Add tabs to project settings (通用设置 / Widget / Portal)
-
-**Files:**
-- Modify: `components/project/project-settings.tsx`
-- Modify: `app/(dashboard)/settings/projects/[projectSlug]/page.tsx`
-- Test: `tests/components/project-settings-tabs.test.tsx`
-
-**Step 1: Write the failing test**
-
-```ts
-import { describe, expect, it } from "bun:test";
-import { ProjectSettings } from "@/components/project/project-settings";
-
-describe("ProjectSettings tabs", () => {
-  it("exports a component", () => {
-    expect(typeof ProjectSettings).toBe("function");
-  });
-});
-```
-
-**Step 2: Run test to verify it fails**
-
-Run: `bun test tests/components/project-settings-tabs.test.tsx`
-Expected: PASS (component exists) — update test to check for tabs labels after implementation
-
-**Step 3: Write minimal implementation**
-
-- Use `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent` from `components/ui/tabs.tsx`
-- Create three tabs: 通用设置 / Widget / Portal
-- Move existing Widget form + preview into Widget tab
-- Move Portal entry into Portal tab and render `PortalOverview` component
-- Keep “危险区域” inside 通用设置 tab
-
-**Step 4: Run test to verify it passes**
-
-Run: `bun test tests/components/project-settings-tabs.test.tsx`
-Expected: PASS
-
-**Step 5: Commit**
-
-```bash
-git add components/project/project-settings.tsx app/(dashboard)/settings/projects/[projectSlug]/page.tsx tests/components/project-settings-tabs.test.tsx
-git commit -m "feat: add project settings tabs"
-```
-
-### Task 3: Wire Portal tab to new overview and subpages
-
-**Files:**
-- Modify: `components/project/project-settings.tsx`
-- Modify: `app/(dashboard)/settings/projects/[projectSlug]/portal/page.tsx`
-- Test: `tests/app/project-portal-overview.test.tsx`
-
-**Step 1: Write the failing test**
-
-```ts
-import { describe, expect, it } from "bun:test";
-import { PortalOverview } from "@/components/portal/portal-overview";
-
-describe("Portal overview routing", () => {
-  it("exports a component", () => {
-    expect(typeof PortalOverview).toBe("function");
-  });
-});
-```
-
-**Step 2: Run test to verify it fails**
-
-Run: `bun test tests/app/project-portal-overview.test.tsx`
-Expected: PASS
-
-**Step 3: Write minimal implementation**
-
-- Replace inline overview markup in portal overview page with `PortalOverview`
-- Use same component in Portal tab content
-
-**Step 4: Run test to verify it passes**
-
-Run: `bun test tests/app/project-portal-overview.test.tsx`
-Expected: PASS
-
-**Step 5: Commit**
-
-```bash
-git add components/project/project-settings.tsx app/(dashboard)/settings/projects/[projectSlug]/portal/page.tsx tests/app/project-portal-overview.test.tsx
-git commit -m "feat: embed portal overview in project settings"
-```
-
-### Task 4: Verification
-
-**Files:**
-- None
-
-**Step 1: Run lint**
-
-Run: `bun run lint`
-Expected: PASS with existing warnings only
-
-**Step 2: Manual check**
-
-- Visit `/settings/projects/[projectSlug]` and verify tabs and content
-- Visit `/settings/projects/[projectSlug]/portal` and verify overview + module toggle
-- Verify Portal subpages still accessible
-
-**Step 3: Commit (if needed)**
-
-```bash
-git status -sb
-```

package/docs/plans/2026-01-14-e2e-playwright-feedback.md

@@ -1,173 +0,0 @@
-# Playwright Feedback Submission E2E Implementation Plan
-
-> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
-
-**Goal:** Add a Playwright E2E smoke test that registers a user, opens the organization portal, submits feedback, and confirms it appears in the list.
-
-**Architecture:** Use Playwright for browser automation and `page.request` to call `/api/auth/register` in the same browser context to seed a user+organization, then drive the portal UI to create a feedback post. Store test config in `playwright.config.ts` with a local dev server and standard artifacts.
-
-**Tech Stack:** Playwright, Bun, Next.js App Router, better-auth, Drizzle/Postgres.
-
-### Task 1: Add the failing E2E test (red)
-
-**Files:**
-- Create: `tests/e2e/feedback-submit.spec.ts`
-
-**Step 1: Write the failing test**
-
-```ts
-import { test, expect } from "@playwright/test";
-
-function uniqueEmail() {
-  return `e2e+${Date.now()}@example.com`;
-}
-
-function uniqueTitle() {
-  return `E2E feedback ${Date.now()}`;
-}
-
-test("feedback submission from portal creates a new post", async ({ page }) => {
-  const email = uniqueEmail();
-  const password = "StrongPass123!";
-  const name = "E2E User";
-
-  const register = await page.request.post("/api/auth/register", {
-    data: { name, email, password },
-  });
-
-  expect(register.ok()).toBeTruthy();
-  const json = await register.json();
-  const slug = json?.data?.organization?.slug;
-  expect(slug).toBeTruthy();
-
-  const title = uniqueTitle();
-
-  await page.goto(`/${slug}`);
-  await page.getByRole("button", { name: "Submit Feedback" }).click();
-
-  await page.getByLabel("Title").fill(title);
-  await page.getByLabel("Description").fill("This is an E2E submission.");
-  await page.getByRole("button", { name: "Create Post" }).click();
-
-  await expect(page.getByRole("heading", { name: title })).toBeVisible();
-});
-```
-
-**Step 2: Run test to verify it fails**
-
-Run: `bunx playwright test tests/e2e/feedback-submit.spec.ts`
-Expected: FAIL because Playwright is not installed/configured.
-
-### Task 2: Add Playwright tooling/configuration (green for tooling)
-
-**Files:**
-- Create: `playwright.config.ts`
-- Modify: `package.json`
-- Modify: `.gitignore`
-
-**Step 1: Write minimal Playwright config**
-
-```ts
-import { defineConfig, devices } from "@playwright/test";
-
-export default defineConfig({
-  testDir: "./tests/e2e",
-  timeout: 60_000,
-  expect: { timeout: 10_000 },
-  retries: 1,
-  use: {
-    baseURL: process.env.E2E_BASE_URL ?? "http://localhost:3000",
-    trace: "retain-on-failure",
-    screenshot: "only-on-failure",
-    video: "retain-on-failure",
-  },
-  webServer: {
-    command: "bun dev",
-    url: "http://localhost:3000",
-    reuseExistingServer: !process.env.CI,
-    timeout: 120_000,
-  },
-  projects: [
-    {
-      name: "chromium",
-      use: { ...devices["Desktop Chrome"] },
-    },
-  ],
-});
-```
-
-**Step 2: Add scripts/deps**
-
-- Add devDependency: `@playwright/test`
-- Add script: `"test:e2e": "bunx playwright test"`
-- Add script: `"test:e2e:ui": "bunx playwright test --ui"`
-
-**Step 3: Ignore Playwright artifacts**
-
-Add to `.gitignore`:
-```
-playwright-report/
-test-results/
-.playwright/
-```
-
-**Step 4: Run the failing test again**
-
-Run: `bunx playwright test tests/e2e/feedback-submit.spec.ts`
-Expected: FAIL due to missing/incorrect behavior in the app (if any), or PASS if flow works end-to-end.
-
-### Task 3: Make the test pass (minimal changes)
-
-**Files:**
-- Modify (if needed): `components/portal/create-post-dialog.tsx`
-- Modify (if needed): `components/portal/feedback-board.tsx`
-- Modify (if needed): `app/[organizationSlug]/page.tsx`
-- Modify (if needed): `tests/e2e/feedback-submit.spec.ts`
-
-**Step 1: Observe failure and identify the minimal fix**
-
-Run: `bunx playwright test tests/e2e/feedback-submit.spec.ts`
-Expected: FAIL with a clear reason (e.g., button labels differ, missing fields, redirect to login).
-
-**Step 2: Apply minimal code change**
-
-Examples (only if needed):
-- If button label mismatches, prefer role/label selectors or update labels.
-- If dialog doesn’t open due to auth, ensure register call sets cookies (use `page.request` only, not a separate request context).
-
-**Step 3: Re-run the test**
-
-Run: `bunx playwright test tests/e2e/feedback-submit.spec.ts`
-Expected: PASS.
-
-**Step 4: Commit**
-
-```bash
-git add playwright.config.ts package.json .gitignore tests/e2e/feedback-submit.spec.ts
-# plus any modified app files if needed
-git commit -m "test: add Playwright E2E feedback submission"
-```
-
-### Task 4: Document local E2E prerequisites
-
-**Files:**
-- Modify: `README.md`
-
-**Step 1: Add E2E run instructions**
-
-Add a short section:
-- Set `DATABASE_URL` and `BETTER_AUTH_SECRET`
-- Run migrations: `bun run db:migrate`
-- Run: `bun run test:e2e`
-
-**Step 2: Verify docs**
-
-Run: `rg -n "E2E" README.md`
-Expected: section present.
-
-**Step 3: Commit**
-
-```bash
-git add README.md
-git commit -m "docs: add Playwright E2E setup"
-```

package/docs/plans/2026-01-15-feedback-management-org-context-design.md

@@ -1,82 +0,0 @@
-# Feedback Management Organization Context - Design
-
-Date: 2026-01-15
-
-## Summary
-Refactor Feedback Management to be organization-aware by default. Introduce a unified organization context resolver that reads organization from URL, headers, and cookies (in that priority) and enforces organization membership on server-side. Add an organization switcher only on `/dashboard` that writes the selected org to cookie and URL. All feedback-related pages and APIs must use the resolver to prevent cross-organization data access.
-
-## Goals
-- Enforce organization isolation across all feedback pages and APIs.
-- Centralize organization resolution and authorization on the server.
-- Support multi-organization users with a dashboard switcher.
-- Persist organization selection with cookie and allow URL override.
-
-## Non-Goals
-- No global organization picker outside `/dashboard`.
-- No super-admin global org visibility.
-- No UI redesign beyond adding the switcher on `/dashboard`.
-
-## Current State
-- Some endpoints accept `organizationId` query/header but not consistently enforced.
-- `/dashboard` uses a single organization and some pages still hardcode IDs.
-- Multiple feedback APIs and pages query feedback by ID without consistent org checks.
-
-## Proposed Architecture
-### Organization Context Resolver
-Add a new module (e.g. `lib/auth/org-context.ts`) that provides:
-- `getOrgContext(request, options)`
-  - Resolves `organizationId` from:
-    1) URL query (`organizationId`)
-    2) Header (`x-organization-id`)
-    3) Cookie (`orgId`)
-  - Optionally reads `organizationSlug` for portal routes when provided.
-  - Returns `{ organizationId, memberRole, source }`.
-  - If user is logged in and `organizationId` is present, verifies membership.
-  - If user is anonymous, allows read-only contexts for public routes.
-- `requireOrgContext(request, options)`
-  - Same as above, but throws/returns 403 when membership is missing or invalid.
-
-### Enforcement
-- All feedback list, detail, stats, comments, votes, duplicates, and similarity APIs must call `requireOrgContext`.
-- All feedback pages (dashboard, admin, feedback detail) must use resolver-derived org.
-- Portal pages use slug -> org ID and bypass membership checks for read-only views.
-
-## Data Flow
-1. User lands on `/dashboard`.
-2. Dashboard requests user organizations and renders a switcher.
-3. Switcher selection writes `orgId` cookie and updates URL query (`?organizationId=...`).
-4. Server components and API routes resolve org via URL > header > cookie.
-5. Feedback queries always include `organizationId` constraint and org membership checks.
-
-## Error Handling
-- Missing org: return 400 `MISSING_ORG_ID`.
-- Not a member: return 403 `FORBIDDEN`.
-- Feedback not in org: return 404.
-- Anonymous access to protected endpoints: return 401/403.
-
-## Compatibility
-- Existing callers that pass `organizationId` continue to work.
-- New behavior is more strict; missing org will now fail with 400.
-- Portal routes remain public read-only with explicit org resolution.
-
-## Implementation Scope
-- Add org context resolver and membership utilities.
-- Update all feedback APIs to use resolver.
-- Update feedback pages to consume resolver-derived org ID.
-- Add dashboard organization switcher (only on `/dashboard`).
-- Cookie handling (set on dashboard, read everywhere).
-
-## Risks & Mitigations
-- **Default org on first load**: if cookie is missing, select the first org and persist it.
-- **Portal contamination**: portal routes should not read org cookie; rely on slug-derived org ID.
-- **Incomplete enforcement**: audit all feedback routes and service-layer queries.
-
-## Testing
-- Unit tests for resolver precedence (URL > header > cookie) and membership check.
-- API tests for org isolation on list/detail endpoints.
-- Dashboard switcher test to verify cookie + URL update.
-
-## Rollout
-1. Ship resolver + API enforcement.
-2. Ship dashboard switcher and default org behavior.
-3. Add logging for missing org or forbidden access to validate adoption.