项目技术栈说明 (Tech Stack Documentation)

本项目旨在构建一个高性能、现代化、具备 AI 能力的 Next.js 全栈应用。

1. 核心框架 (Core Framework)

Next.js 16 (App Router)

• 选择原因:
  • 前沿特性: 使用 Next.js 最新版本，利用 React Server Components (RSC) 提高首屏加载速度和 SEO 性能。
  • 全栈能力: 通过 Server Actions 和 API Routes 直接处理后端逻辑，无需单独维护后端服务。
  • 路由系统: App Router 提供了更强大的布局嵌套及数据获取模式。

React 19

• 选择原因: 配合 Next.js 16，利用最新的 Hooks (useActionState, useOptimistic) 和并发特性，提升用户交互体验。

TypeScript

• 选择原因: 提供静态类型检查，显著减少运行时错误，提高代码可维护性和开发体验，特别是在处理复杂的 API 响应和数据库模型时。

2. 数据库与后端 (Database & Backend)

PostgreSQL

• 选择原因: 成熟、稳定、功能强大的关系型数据库，适合存储结构化数据（用户、文章、评论等）。

Prisma ORM

• 选择原因:
  • 类型安全: 自动生成 TypeScript 类型定义，确保数据库操作的类型安全。
  • 开发体验: 直观的 Schema 定义 (schema.prisma) 和强大的迁移工具 (Migrate)。
  • 加速: 使用了 @prisma/extension-accelerate 优化查询性能。

Better Auth

• 选择原因:
  • 现代化: 相比 NextAuth.js (Auth.js)，Better Auth 提供了更现代的 API 设计和更好的 TypeScript 支持。
  • 安全性: 内置多种安全实践，易于扩展用户角色和权限管理。

3. 人工智能与向量搜索 (AI & Vector Search)

OpenAI API

• 选择原因: 目前业界领先的大语言模型能力，用于处理复杂的自然语言任务（如聊天机器人、内容分析）。

Pinecone

• 选择原因:
  • 云原生向量数据库: 专为高性能向量搜索设计，无需自行运维。
  • RAG 支持: 配合 OpenAI Embeddings，实现检索增强生成 (RAG)，让 AI 能基于项目特定的知识库（如“记忆”或文档）进行回答。

4. 界面与交互 (UI & UX)

Tailwind CSS v4

• 选择原因:
  • 原子化 CSS: 快速构建界面，减少 CSS 体积。
  • v4 新特性: 更快的编译速度，更简洁的配置（无需复杂的 tailwind.config.js）。

Shadcn UI (基于 Radix UI)

• 选择原因:
  • 可定制性: 不是打包好的组件库，而是直接复制代码到项目中，拥有完全的控制权。
  • 无障碍: 底层使用 Radix UI，确保组件符合 WAI-ARIA 标准。
  • 依赖: 使用了 clsx, tailwind-merge, class-variance-authority 进行样式管理。

动画库 (Motion & GSAP)

• Motion (原 Framer Motion): 用于 React 组件的声明式动画，适合复杂的交互效果（如页面切换、元素布局动画）。
• GSAP: 业界最强大的动画库，用于高性能的复杂序列动画。

Sonner

• 选择原因: 轻量、美观、可定制的 Toast 通知组件，体验优于传统的 react-hot-toast。

5. 文件存储与处理 (File Storage & Processing)

AWS S3 SDK (配合 Cloudflare R2)

• 选择原因:
  • 成本效益: Cloudflare R2 兼容 S3 API，但免流量费，非常适合个人和中小型项目。
  • 通用性: 使用标准的 AWS SDK，未来迁移方便。

Sharp

• 选择原因: 高性能的 Node.js 图片处理库，用于在上传前或服务端优化图片尺寸和格式（如转换为 WebP）。

6. 开发工具与规范 (Dev Tools)

• ESLint & Prettier: 保持代码风格一致，避免低级错误。
• Husky: Git Hooks 工具，确保提交前代码通过检查。
• Vercel: 零配置部署，与 Next.js 完美契合，提供边缘计算能力。

总结

本项目的技术选型遵循“性能优先、类型安全、开发高效”的原则。Next.js 全栈架构降低了运维复杂度，Prisma + TypeScript 保证了数据流的稳健，而 Tailwind + Shadcn UI + Motion 则确保了现代化的用户界面体验。引入 Pinecone 和 OpenAI 则让应用具备了面向未来的 AI 能力。