secondme-nextjs

SecondMe Next.js 项目生成

基于 /secondme-init 的配置和 /secondme-prd 的需求定义，生成完整的 Next.js 项目。

---

前置条件检查

1. 检查 state.json

首先检查 .secondme/state.json 是否存在：

• 不存在 → 提示：请先运行 /secondme-init 初始化项目配置
• 存在 → 继续

2. 检查执行模式

检查参数是否包含 --quick：

快速模式 (--quick)：

• 跳过 stage 检查
• 使用默认 PRD 配置
• 直接开始生成项目

标准模式：

• 检查 stage >= "prd"
• 如果 stage == "init" → 提示：请先运行 /secondme-prd 定义需求，或使用 /secondme-nextjs --quick 快速生成
• 如果 stage >= "prd" → 继续

---

读取配置

从 .secondme/state.json 读取：

const state = {
  app_name: "secondme-tinder",  // 应用名称
  modules: ["auth", "chat", "profile"],  // 已选模块
  config: {
    client_id: "71658da7-659c-414a-abdf-cb6472037fc2",
    client_secret: "xxx",
    redirect_uri: "http://localhost:3000/api/auth/callback",
    redirect_uris: [...],
    database_url: "postgresql://...",
    allowed_scopes: [...]
  },
  api: {
    base_url: "https://api.mindverse.com/gate/lab",
    oauth_url: "https://go.second.me/oauth/",
    token_endpoint: "https://api.mindverse.com/gate/lab/api/oauth/token/code",
    refresh_endpoint: "https://api.mindverse.com/gate/lab/api/oauth/token/refresh",
    access_token_ttl: 7200,
    refresh_token_ttl: 2592000
  },
  docs: {
    quickstart: "https://develop-docs.second.me/zh/docs",
    oauth2: "...",
    api_reference: "...",
    errors: "..."
  },
  prd: {
    summary: "应用概要",
    features: ["功能1", "功能2"],
    design_preference: "简约现代"
  }
}

重要： 所有 API 端点、文档链接均从 state.api 和 state.docs 读取，不要硬编码。

---

前端设计要求

重要： 在构建前端界面时，必须使用 frontend-design:frontend-design skill 来生成高质量的 UI 组件。

设计原则：

• 亮色主题：仅使用亮色/浅色主题，不使用暗色/深色主题
• 简约优雅：遵循极简设计理念，减少视觉噪音
• 产品特性驱动：UI 设计应紧密结合要实现的功能特性
• 现代感：采用当下流行的设计趋势，避免过时的 UI 模式
• 一致性：保持整体视觉风格统一
• 响应式：适配各种屏幕尺寸
• 中文界面：所有用户可见的文字（按钮、提示、标签、说明等）必须使用中文
• 稳定优先：避免复杂动画效果，仅使用简单的过渡动画（如 hover、fade），确保界面稳定流畅

---

项目生成流程

1. 初始化 Next.js 项目

在当前目录直接初始化 Next.js 项目：

npx create-next-app@latest . --typescript --tailwind --app --src-dir --import-alias "@/*" --yes

2. 安装依赖

npm install prisma @prisma/client
npx prisma init

3. 生成 .env.local

从 state.config 和 state.api 生成环境变量：

# SecondMe OAuth2 配置
SECONDME_CLIENT_ID=[config.client_id]
SECONDME_CLIENT_SECRET=[config.client_secret]
SECONDME_REDIRECT_URI=[config.redirect_uri]

# 数据库
DATABASE_URL=[config.database_url]

# SecondMe API（从 state.api 读取）
SECONDME_API_BASE_URL=[api.base_url]
SECONDME_OAUTH_URL=[api.oauth_url]
SECONDME_TOKEN_ENDPOINT=[api.token_endpoint]
SECONDME_REFRESH_ENDPOINT=[api.refresh_endpoint]

4. 生成 Prisma Schema

根据已选模块动态生成 prisma/schema.prisma。

auth 模块（必有）- User 表必须包含的字段

User 表必须包含 Token 相关字段用于存储和刷新用户凭证：

model User {
  id                String   @id @default(cuid())
  secondmeUserId    String   @unique @map("secondme_user_id")
  accessToken       String   @map("access_token")
  refreshToken      String   @map("refresh_token")
  tokenExpiresAt    DateTime @map("token_expires_at")
  createdAt         DateTime @default(now()) @map("created_at")
  updatedAt         DateTime @updatedAt @map("updated_at")
  // 其他字段根据模块需求自行添加

  @@map("users")
}

其他模块

根据已选模块（profile、chat、note）的实际需求，自行设计相应的数据库表结构和关联关系。

5. 生成代码

根据已选模块生成对应代码：

auth 模块

文件	说明
src/app/api/auth/login/route.ts	OAuth 登录跳转
src/app/api/auth/callback/route.ts	OAuth 回调处理
src/app/api/auth/logout/route.ts	登出处理
src/lib/auth.ts	认证工具函数
src/components/LoginButton.tsx	登录按钮组件

profile 模块

文件	说明
src/app/api/user/info/route.ts	获取用户信息
src/app/api/user/shades/route.ts	获取兴趣标签
src/components/UserProfile.tsx	用户资料组件

chat 模块

文件	说明
src/app/api/chat/route.ts	流式聊天 API
src/app/api/sessions/route.ts	会话列表 API
src/components/ChatWindow.tsx	聊天界面组件

act 模块

文件	说明
src/app/api/act/route.ts	流式动作判断 API（结构化 JSON 输出）
src/lib/act.ts	Act API 工具函数（发送 actionControl、解析 SSE JSON 结果）

note 模块

文件	说明
src/app/api/note/route.ts	添加笔记 API

6. 更新 state.json

{
  "stage": "ready",
  ...
}

---

技术栈

• 框架： Next.js 14+ (App Router)
• 语言： TypeScript
• 样式： Tailwind CSS
• 数据库 ORM： Prisma
• 前端设计： 使用 frontend-design:frontend-design skill 生成
• API 调用： fetch
• 状态管理： React hooks
• 运行端口： 必须使用 3000 端口

---

常见问题与注意事项

CSS @import 顺序问题

问题： 在 globals.css 中使用 @import url(...) 引入 Google Fonts 会导致构建失败。

错误信息：

@import rules must precede all rules aside from @charset and @layer statements

原因： Tailwind CSS 的 @import "tailwindcss" 展开后生成大量规则，导致后续的 @import url(...) 不再是第一个。

正确做法：

1. 使用 <link> 标签（推荐）： 在 layout.tsx 中引入

   <head>
     <link rel="preconnect" href="https://fonts.googleapis.com" />
     <link href="https://fonts.googleapis.com/css2?family=..." rel="stylesheet" />
   </head>
   

2. 使用 next/font（最佳实践）：

   import { Noto_Sans_SC } from 'next/font/google'
   const notoSans = Noto_Sans_SC({ subsets: ['latin'], weight: ['400', '500'] })
   

构建验证

重要： 每次完成代码修改后，必须运行以下命令验证构建：

npm run build

特别关注：

• CSS 解析错误
• TypeScript 类型错误
• 导入路径错误

WebView OAuth 认证问题

问题： 在 WebView 环境中（如移动端 App 内嵌页面、微信小程序等），OAuth state 验证可能失败，因为 WebView 与系统浏览器之间的存储不共享。

解决方案： 使用宽松的 state 验证，验证失败时记录警告但继续处理登录流程。

// 之前：验证失败直接拒绝
if (!isValidState) {
  return NextResponse.redirect('/?error=invalid_state');
}

// 之后：验证失败记录警告，继续处理
if (!isValidState) {
  console.warn('OAuth state 验证失败，可能是跨 WebView 场景');
  // 继续处理，不阻止登录
}

注意： 这种方式降低了 CSRF 防护，仅建议在可信的 WebView 环境中使用

---

输出结果

✅ Next.js 项目已生成！

已生成模块: auth, chat, profile
数据库: PostgreSQL

启动步骤:
1. npm install
2. npx prisma db push
3. npm run dev

项目将在 http://localhost:3000 启动

---

API 响应格式

重要：所有 SecondMe API 响应都遵循统一格式：

{
  "code": 0,
  "data": { ... }
}

本地路由与上游 API 的关系： Next.js 本地路由（如 /api/secondme/user/shades）作为代理层， 将请求转发到上游 SecondMe API（{state.api.base_url}/api/secondme/...），并透传上游的响应格式。 前端代码调用本地路由即可，无需直接访问上游 API。

前端代码必须正确提取数据：

// ✅ 正确写法（调用 Next.js 本地路由，响应格式与上游一致）
const response = await fetch('/api/secondme/user/shades');
const result = await response.json();
if (result.code === 0) {
  const shades = result.data.shades;
  shades.map(item => ...)
}

---

官方文档

从 state.docs 读取文档链接：

文档	配置键
快速入门	docs.quickstart
OAuth2 指南	docs.oauth2
API 参考	docs.api_reference
错误码	docs.errors