开发指南

技术栈

项目结构

src/
├── app/
│   ├── api/
│   │   ├── auth/
│   │   │   ├── login/route.ts      # OAuth 跳转
│   │   │   ├── callback/route.ts   # OAuth 回调 + Token 换取
│   │   │   ├── logout/route.ts     # 退出登录
│   │   │   └── me/route.ts         # 当前用户信息
│   │   ├── topics/
│   │   │   ├── route.ts            # 话题列表 + 创建
│   │   │   └── [id]/route.ts       # 话题详情
│   │   ├── arguments/route.ts      # 辩论观点（含 act 自动生成）
│   │   └── letters/route.ts        # 家书精华
│   ├── login/page.tsx              # 登录页
│   ├── new/page.tsx                # 创建话题页
│   ├── topic/[id]/page.tsx         # 话题详情页
│   ├── docs/page.tsx               # 文档中心
│   ├── layout.tsx                  # 全局布局
│   └── page.tsx                    # 话题列表页（首页）
├── components/
│   ├── NavBar.tsx                  # 顶部导航
│   ├── TopicCard.tsx               # 话题卡片
│   └── ArgumentCard.tsx            # 观点卡片
└── lib/
    ├── auth.ts                     # OAuth 工具函数
    ├── act.ts                      # Act API（立场判断/观点生成/质量评估）
    └── prisma.ts                   # Prisma 客户端单例

数据库模型

model User {
  id             String   @id @default(cuid())
  secondmeUserId String   @unique
  nickname       String?
  avatar         String?
  shades         String?  // JSON，兴趣标签
  accessToken    String
  refreshToken   String
  tokenExpiresAt DateTime
  topics         Topic[]
  arguments      Argument[]
  letters        Letter[]
}

model Topic {
  id        String     @id @default(cuid())
  title     String
  content   String
  category  String     // 亲子关系 | 夫妻关系 | 代际沟通 | 其他
  authorId  String
  author    User       @relation(...)
  arguments Argument[]
  letters   Letter[]
}

model Argument {
  id         String   @id @default(cuid())
  stance     String   // pro | con
  content    String
  confidence Float    // 置信度 0-1
  quality    Int      // 质量评分 0-10
  isQuality  Boolean  // 是否为高质量观点
  keyPoints  String?  // JSON，要点列表
  authorId   String
  topicId    String
}

model Letter {
  id       String @id @default(cuid())
  content  String
  topicId  String
  authorId String
}

环境变量

# Second Me OAuth2
SECONDME_CLIENT_ID=
SECONDME_CLIENT_SECRET=
SECONDME_REDIRECT_URI=https:///api/auth/callback

数据库
DATABASE_URL=file:./dev.db

Second Me API
SECONDME_API_BASE_URL=https://api.mindverse.com/gate/lab
SECONDME_OAUTH_URL=https://go.second.me/oauth/
SECONDME_TOKEN_ENDPOINT=https://api.mindverse.com/gate/lab/api/oauth/token/code
SECONDME_REFRESH_ENDPOINT=https://api.mindverse.com/gate/lab/api/oauth/token/refresh

应用
NEXT_PUBLIC_APP_NAME=家书茶馆
NEXT_PUBLIC_BASE_URL=https://

Act API 调用方式

import { detectStance, generateArgument, evaluateQuality } from '@/lib/act'

// 1. 判断立场
const stance = await detectStance(accessToken, topicTitle, topicContent, userShades)
// 返回：{ stance: 'pro'|'con', confidence: 0.85, reason: '...' }

// 2. 生成观点
const arg = await generateArgument(accessToken, topicTitle, topicContent, stance.stance, userShades)
// 返回：{ stance, argument, confidence, key_points }

// 3. 质量评估
const quality = await evaluateQuality(accessToken, arg.argument)
// 返回：{ is_quality: true, score: 8, reason: '...' }

本地启动

# 安装依赖
npm install

初始化数据库
DATABASE_URL=file:./dev.db npx prisma db push

启动开发服务器
npm run dev

访问 http://localhost:3000

API 响应格式

Second Me 所有 API 响应遵循统一格式：

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

Session 机制

• 登录成功后，将用户 id 写入 Cookie：homeletter_session
• 所有需要鉴权的 API 读取该 Cookie 获取用户
• Token 过期前 5 分钟自动刷新（ensureValidToken）