@nexttylabs/echo 0.2.0

package/docs/architecture.md

@@ -0,0 +1,259 @@
+# Architecture Documentation
+
+**Project:** Echo
+**Type:** Web Application (Next.js + React + TypeScript)
+**Generated:** 2025-12-31
+
+## Executive Summary
+
+Echo 是一个基于 Next.js 16 和 React 19 的现代 Web 应用，使用 App Router 架构和 React Server Components。项目采用 TypeScript 严格模式，使用 Shadcn/ui 作为组件库，Tailwind CSS v4 进行样式管理。
+
+## Technology Stack
+
+### Core Framework
+
+| 技术 | 版本 | 用途 |
+|------|------|------|
+| **Next.js** | 16.1.1 | React 框架（App Router）|
+| **React** | 19.2.3 | UI 库（RSC enabled）|
+| **TypeScript** | 5.x | 类型系统（strict mode）|
+
+### Styling
+
+| 技术 | 版本 | 用途 |
+|------|------|------|
+| **Tailwind CSS** | 4.x | 实用优先的 CSS 框架 |
+| **tw-animate-css** | 1.4.0 | 动画支持 |
+
+### Component Library
+
+| 技术 | 版本 | 用途 |
+|------|------|------|
+| **Shadcn/ui** | 3.6.2 | 组件系统 |
+| **Radix UI** | 1.4.3 | 无障碍基础组件 |
+| **Base UI** | 1.0.0 | React 基础组件 |
+| **Lucide React** | 0.562.0 | 图标库 |
+
+### Utilities
+
+| 技术 | 用途 |
+|------|------|
+| **clsx** | 条件类名 |
+| **tailwind-merge** | 合并 Tailwind 类名 |
+| **class-variance-authority** | 组件变体管理 |
+
+## Architecture Pattern
+
+### Next.js App Router
+
+项目使用 Next.js 13+ 引入的 App Router 架构：
+
+```
+app/
+├── layout.tsx       # 根布局（持久 UI）
+├── page.tsx         # 首页路由
+└── globals.css      # 全局样式
+```
+
+**特点：**
+- 基于文件系统的路由
+- 支持嵌套布局
+- React Server Components (RSC)
+- 流式渲染
+- 并行路由
+
+### React Server Components
+
+| 特性 | 说明 |
+|------|------|
+| **默认服务器组件** | 减少客户端 JavaScript |
+| **选择性客户端组件** | 使用 'use client' 指令 |
+| **数据获取** | 在服务器组件中直接获取 |
+
+### Component Architecture
+
+```
+components/
+├── ui/                    # Shadcn/ui 基础组件（14 个）
+│   ├── alert-dialog.tsx
+│   ├── badge.tsx
+│   ├── button.tsx
+│   ├── card.tsx
+│   ├── combobox.tsx
+│   ├── dropdown-menu.tsx
+│   ├── field.tsx
+│   ├── input-group.tsx
+│   ├── input.tsx
+│   ├── label.tsx
+│   ├── select.tsx
+│   ├── separator.tsx
+│   └── textarea.tsx
+├── component-example.tsx  # 自定义组件
+└── example.tsx
+```
+
+## Data Architecture
+
+### 当前状态
+
+**无数据层实现** - 项目目前是纯前端应用，没有：
+
+- ❌ 数据库连接
+- ❌ ORM/数据模型
+- ❌ API 集成
+- ❌ 状态管理
+
+### 扩展点
+
+当需要添加数据功能时：
+
+1. **API 路由** - 在 `app/api/` 创建 RESTful 端点
+2. **数据获取** - 在 Server Components 中获取
+3. **状态管理** - 添加 React Context 或 Zustand
+4. **数据库** - 集成 Prisma + PostgreSQL
+
+## API Design
+
+### 当前状态
+
+**无 API 实现** - 项目未定义 API 端点。
+
+### 推荐扩展
+
+在 `app/api/` 目录添加路由：
+
+```
+app/api/
+├── auth/
+│   └── route.ts      # POST /api/auth
+├── feedback/
+│   └── route.ts      # POST /api/feedback
+└── users/
+    └── route.ts      # GET/POST /api/users
+```
+
+## Component Overview
+
+### Shadcn/ui Components
+
+| 组件 | 用途 | 状态 |
+|------|------|------|
+| alert-dialog | 警告/确认对话框 | ✅ 已安装 |
+| badge | 徽章/标签 | ✅ 已安装 |
+| button | 按钮 | ✅ 已安装 |
+| card | 卡片容器 | ✅ 已安装 |
+| combobox | 组合输入框 | ✅ 已安装 |
+| dropdown-menu | 下拉菜单 | ✅ 已安装 |
+| field | 表单字段包装器 | ✅ 已安装 |
+| input-group | 输入组 | ✅ 已安装 |
+| input | 文本输入 | ✅ 已安装 |
+| label | 表单标签 | ✅ 已安装 |
+| select | 选择器 | ✅ 已安装 |
+| separator | 分隔线 | ✅ 已安装 |
+| textarea | 多行文本输入 | ✅ 已安装 |
+
+### Custom Components
+
+| 组件 | 位置 | 状态 |
+|------|------|------|
+| ComponentExample | components/component-example.tsx | ✅ 示例 |
+| Example | components/example.tsx | ✅ 示例 |
+
+## Source Tree
+
+完整源代码树请参阅：[Source Tree Analysis](./source-tree-analysis.md)
+
+## Development Workflow
+
+开发流程请参阅：[Development Guide](./development-guide.md)
+
+## Deployment Architecture
+
+### 当前配置
+
+| 项目 | 状态 |
+|------|------|
+| **构建输出** | `.next/` 目录 |
+| **启动命令** | `bun start` |
+| **环境变量** | `.env.local` |
+| **Docker** | ❌ 未配置 |
+| **CI/CD** | ❌ 未配置 |
+
+### 推荐部署
+
+- **Vercel** - Next.js 官方平台（零配置）
+- **Netlify** - 支持 Next.js
+- **自托管** - 使用 Docker 容器化
+
+## Security Considerations
+
+### 当前状态
+
+| 安全措施 | 状态 |
+|----------|------|
+| **环境变量** | `NEXT_PUBLIC_*` 前缀 |
+| **TypeScript** | Strict mode（类型安全）|
+| **ESLint** | 已配置 |
+| **认证/授权** | ❌ 未实现 |
+| **HTTPS** | 部署平台处理 |
+
+### 推荐添加
+
+1. **认证** - NextAuth.js 或 Clerk
+2. **API 安全** - CSRF 保护、速率限制
+3. **输入验证** - Zod schema 验证
+4. **CORS** - API 路由配置
+
+## Performance Considerations
+
+### 优化措施
+
+| 优化 | 说明 |
+|------|------|
+| **Server Components** | 减少客户端 JavaScript |
+| **字体优化** | next/font (Geist, Inter) |
+| **图片优化** | next/image（未使用）|
+| **代码分割** | App Router 自动处理 |
+
+### 推荐添加
+
+1. **图片优化** - 使用 `next/image`
+2. **动态导入** - `next/dynamic`
+3. **缓存策略** - Next.js 缓存配置
+4. **性能监控** - Vercel Analytics
+
+## Testing Strategy
+
+### 当前状态
+
+❌ **无测试配置**
+
+### 推荐添加
+
+1. **单元测试** - Vitest + Testing Library
+2. **组件测试** - Playwright 或 Cypress
+3. **E2E 测试** - Playwright
+4. **类型检查** - TypeScript + tsc
+
+## Future Enhancements
+
+### 短期（1-2 周）
+
+1. 添加测试套件
+2. 实现 API 路由
+3. 添加状态管理
+4. 配置 CI/CD
+
+### 中期（1-2 月）
+
+1. 数据库集成
+2. 用户认证
+3. 错误处理
+4. 性能监控
+
+### 长期（3+ 月）
+
+1. 微服务架构（如需要）
+2. 国际化 (i18n)
+3. PWA 支持
+4. 离线功能

package/docs/component-inventory.md

@@ -0,0 +1,261 @@
+# Component Inventory
+
+**Project:** Echo
+**Generated:** 2025-12-31
+
+## Overview
+
+项目使用 **Shadcn/ui 3.6.2** 组件库，基于 Radix UI primitives 和 Base UI 构建。
+
+## Design System Configuration
+
+| 配置 | 值 |
+|------|-----|
+| **样式变体** | radix-maia |
+| **基础颜色** | neutral |
+| **图标库** | lucide-react |
+| **RSC** | enabled |
+| **CSS 变量** | enabled |
+
+## Shadcn/ui Components (14 个)
+
+### Form Components
+
+| 组件 | 文件 | 描述 |
+|------|------|------|
+| **Input** | `input.tsx` | 单行文本输入 |
+| **Textarea** | `textarea.tsx` | 多行文本输入 |
+| **Label** | `label.tsx` | 表单标签 |
+| **Field** | `field.tsx` | 表单字段包装器 |
+| **Input Group** | `input-group.tsx` | 输入组容器 |
+| **Select** | `select.tsx` | 下拉选择器 |
+| **Combobox** | `combobox.tsx` | 组合输入/搜索 |
+
+### Action Components
+
+| 组件 | 文件 | 描述 |
+|------|------|------|
+| **Button** | `button.tsx` | 按钮（多种变体）|
+| **Dropdown Menu** | `dropdown-menu.tsx` | 下拉菜单 |
+| **Alert Dialog** | `alert-dialog.tsx` | 警告/确认对话框 |
+
+### Layout Components
+
+| 组件 | 文件 | 描述 |
+|------|------|------|
+| **Card** | `card.tsx` | 卡片容器 |
+| **Separator** | `separator.tsx` | 分隔线 |
+
+### Display Components
+
+| 组件 | 文件 | 描述 |
+|------|------|------|
+| **Badge** | `badge.tsx` | 徽章/标签 |
+
+## Component Usage
+
+### Button
+
+```tsx
+import { Button } from "@/components/ui/button";
+
+<Button variant="default">Click me</Button>
+<Button variant="outline">Outline</Button>
+<Button variant="ghost">Ghost</Button>
+```
+
+### Card
+
+```tsx
+import { Card } from "@/components/ui/card";
+
+<Card>
+  <CardHeader>
+    <CardTitle>Title</CardTitle>
+  </CardHeader>
+  <CardContent>Content</CardContent>
+</Card>
+```
+
+### Input
+
+```tsx
+import { Input } from "@/components/ui/input";
+
+<Input type="text" placeholder="Enter text..." />
+```
+
+## Custom Components
+
+| 组件 | 文件 | 描述 | 状态 |
+|------|------|------|------|
+| **ComponentExample** | `component-example.tsx` | 示例组件 | ✅ |
+| **Example** | `example.tsx` | 简单示例 | ✅ |
+
+## Reusable Patterns
+
+### cn() Utility
+
+合并 Tailwind 类名：
+
+```tsx
+import { cn } from "@/lib/utils";
+
+className={cn(
+  "base-class",
+  condition && "conditional-class",
+  "another-class"
+)}
+```
+
+### Component Variants
+
+使用 `class-variance-authority` 管理变体：
+
+```tsx
+const buttonVariants = cva(
+  "base-classes",
+  {
+    variants: {
+      variant: {
+        default: "default-classes",
+        outline: "outline-classes",
+      },
+    },
+  }
+);
+```
+
+## Component Organization
+
+```
+components/
+├── ui/                    # Shadcn/ui 基础组件（不要直接修改）
+│   ├── alert-dialog.tsx
+│   ├── badge.tsx
+│   ├── button.tsx
+│   ├── card.tsx
+│   ├── combobox.tsx
+│   ├── dropdown-menu.tsx
+│   ├── field.tsx
+│   ├── input-group.tsx
+│   ├── input.tsx
+│   ├── label.tsx
+│   ├── select.tsx
+│   ├── separator.tsx
+│   └── textarea.tsx
+├── component-example.tsx  # 自定义组件
+└── example.tsx
+```
+
+## Adding New Components
+
+### Option 1: Add Shadcn/ui Component
+
+使用 Shadcn CLI 添加新组件：
+
+```bash
+npx shadcn@latest add [component-name]
+```
+
+例如：
+```bash
+npx shadcn@latest add dialog
+npx shadcn@latest add tooltip
+npx shadcn@latest add switch
+```
+
+### Option 2: Create Custom Component
+
+1. 在 `components/` 创建新文件
+2. 使用 Shadcn/ui 组件作为基础
+3. 应用项目样式变体
+
+```tsx
+// components/my-feature.tsx
+import { Button } from "@/components/ui/button";
+import { Card } from "@/components/ui/card";
+
+export function MyFeature() {
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>My Feature</CardTitle>
+      </CardHeader>
+      <CardContent>
+        <Button>Action</Button>
+      </CardContent>
+    </Card>
+  );
+}
+```
+
+## Styling Conventions
+
+### Tailwind Integration
+
+所有组件使用 Tailwind CSS 实用类：
+
+```tsx
+className="flex items-center justify-between p-4 rounded-lg"
+```
+
+### Theme Variables
+
+使用 CSS 自定义属性：
+
+```tsx
+className="bg-primary text-primary-foreground"
+```
+
+可用变量：
+- `background`, `foreground`
+- `primary`, `primary-foreground`
+- `secondary`, `secondary-foreground`
+- `accent`, `accent-foreground`
+- `muted`, `muted-foreground`
+- `card`, `card-foreground`
+- `popover`, `popover-foreground`
+- `border`, `input`, `ring`
+
+## Icon Usage
+
+使用 Lucide React 图标：
+
+```tsx
+import { ChevronLeft, Search, User } from "lucide-react";
+
+<ChevronLeft className="h-4 w-4" />
+<Search className="h-5 w-5" />
+<User className="h-6 w-6" />
+```
+
+## Component Best Practices
+
+1. **优先使用 Shadcn/ui 组件** - 避免重复造轮
+2. **直接修改 ui/ 组件** - 项目采用直接修改方式，不是重新安装
+3. **使用 cn() 合并类名** - 保持类名可预测
+4. **遵循命名约定** - PascalCase 用于组件
+5. **保持组件小而专注** - 单一职责原则
+
+## Missing Components
+
+以下常用组件未安装，可以根据需要添加：
+
+- dialog（对话框）
+- tooltip（工具提示）
+- toast（通知）
+- switch（开关）
+- checkbox（复选框）
+- radio（单选框）
+- tabs（选项卡）
+- table（表格）
+- avatar（头像）
+- progress（进度条）
+- slider（滑块）
+- calendar（日历）
+
+要添加这些组件，运行：
+```bash
+npx shadcn@latest add [component-name]
+```

package/docs/database-migrations.md

@@ -0,0 +1,76 @@
+# Database Migration Guide
+
+## Generating Migrations
+
+After changing the schema in `lib/db/schema/`, run:
+
+```bash
+bun run db:generate
+```
+
+This creates a new migration in `lib/db/migrations/`.
+
+## Applying Migrations
+
+**Development:**
+
+```bash
+bun run db:push
+```
+
+`db:push` applies schema changes directly and is useful for local iteration.
+
+**Production:**
+
+```bash
+bun run db:migrate
+```
+
+`db:migrate` applies generated migration files in order.
+
+## Checking Schema
+
+```bash
+bun run db:check
+```
+
+Verifies the database schema matches your Drizzle schema.
+
+## Database Studio
+
+```bash
+bun run db:studio
+```
+
+Opens Drizzle Studio (default: http://localhost:4983).
+
+## Rollback
+
+Drizzle does not generate down migrations automatically. To rollback:
+
+1. Create a rollback SQL file alongside the migration:
+   `lib/db/migrations/<migration-name>-rollback.sql`
+2. Run the rollback script:
+
+```bash
+bun run scripts/rollback.ts 1
+```
+
+## Pre-deploy Migration
+
+Use the pre-deploy script in CI/CD or release automation to verify connectivity,
+optionally run backups, apply migrations, and validate the resulting schema:
+
+```bash
+bun run scripts/pre-deploy.ts
+```
+
+Set `DB_BACKUP_BEFORE_MIGRATE=true` to enable backup integration (Story 8.5).
+
+## Best Practices
+
+1. Test migrations on a production-like copy first
+2. Keep migrations small and reversible when possible
+3. Prefer additive changes (`ADD COLUMN` with defaults) to avoid data loss
+4. Avoid long-running migrations during peak traffic
+5. Document any manual steps in the PR description