My Blog
← Back to home

开发状态与交接文档

开发状态与交接文档

最后更新: 2026-04-21 当前分支: feat/chat-mode 基于分支: master

1. 项目概述

AI 决策思想客厅 — 一个多视角 AI 认知陪练 SaaS 产品。用户可以选择不同的"人物角色"（persona）进行 1v1 或群聊对话，在重大决策前获得多角度分析。

技术栈: Next.js 16 (App Router) + Tailwind CSS 4 + shadcn/ui + PostgreSQL (Neon) + Drizzle ORM + NextAuth.js

2. 当前分支完成的功能

2.1 用户认证系统 (已完成)

  • NextAuth.js + Credentials Provider 登录/注册
  • Session-based 鉴权，middleware 保护路由
  • 所有 chat API 已加 userId 数据隔离

关键文件:

  • auth.config.ts, auth.ts — NextAuth 配置
  • middleware.ts — 路由保护
  • src/app/auth/signin/page.tsx, src/app/auth/register/page.tsx
  • src/components/auth/session-provider.tsx, src/components/auth/user-menu.tsx
  • src/lib/auth/queries.ts

2.2 聊天系统 (已完成)

核心聊天功能已全部打通，包括：

  • 1v1 对话: 选择 persona → 自动创建/复用 conversation → 实时对话
  • 群聊: 多 persona 群组对话，支持创建时预选 persona
  • SSE 流式输出: assistant 回复以 SSE 逐 chunk 推送，前端实时渲染
  • 消息分页: cursor-based 分页，支持加载更多历史消息
  • 消息搜索: sidebar 搜索框，按关键词搜索消息
  • 会话管理: 重命名、删除、sidebar 列表

关键文件:

层 文件 职责
页面 src/app/chat/page.tsx 聊天主页面，状态管理，SSE 解析
组件 src/components/chat/chat-sidebar.tsx 左侧栏：会话列表 + persona 列表 + 搜索
组件 src/components/chat/chat-window.tsx 聊天窗口：消息列表 + 输入框
组件 src/components/chat/chat-input.tsx 消息输入框 + @mention 弹窗
组件 src/components/chat/chat-message.tsx 单条消息气泡
组件 src/components/chat/markdown-renderer.tsx Markdown 渲染（含代码高亮）
组件 src/components/chat/message-actions.tsx 消息操作按钮（复制等）
组件 src/components/chat/group-create-dialog.tsx 群聊创建弹窗
组件 src/components/chat/mention-popover.tsx @提及弹出面板
API src/app/api/chat/conversations/route.ts GET 列表 / POST 创建
API src/app/api/chat/conversations/[id]/route.ts GET 详情 / PATCH 重命名 / DELETE
API src/app/api/chat/conversations/[id]/messages/route.ts GET 分页消息 / POST 发送（SSE 流式）
API src/app/api/chat/search/route.ts 搜索消息
数据 src/lib/chat/queries.ts 数据库查询函数
数据 src/lib/chat/service.ts 业务逻辑：编排 AI 回复、流式输出
数据 src/lib/chat/prompts.ts AI prompt 模板
类型 src/types/index.ts 类型定义（ChatConversation, ChatMessage 等）
Schema src/lib/db/schema.ts 数据库表结构

2.3 主题系统 (进行中)

三主题切换架构已搭建完成，但 配色方案尚未最终确定。

当前状态:

主题 class 名 状态
晨光（浅色） (无 class / light) 已完成，保持不变
深夜（深色） .dark CSS 变量已定义，但配色需重新设计
沙龙（彩色） .color CSS 变量已定义，但配色需重新设计

关键文件:

  • src/app/globals.css — 所有主题 CSS 变量定义（:root, .dark, .color）
  • src/components/theme-provider.tsx — ThemeProvider 组件，class 切换逻辑
  • src/components/theme-switcher.tsx — 主题切换按钮 UI

主题切换机制:

  • ThemeProvider 在 <html> 元素上切换 class: 无 class = light, .dark = dark, .color = color
  • 主题偏好存在 localStorage key theme
  • Tailwind dark mode 通过 @custom-variant dark (&:is(.dark *)) 配置

3. 进行中的任务

3.1 主题配色重新设计 (未完成)

目标:

  • 晨光: 保持现有浅色主题不变
  • 深夜: 亮绿色 + 暗黑色搭配，参考 qoder.com 的深色美学风格
  • 沙龙: 更彩色、更醒目，视觉冲击力强

待完成的具体工作:

  1. 修改 src/app/globals.css 中的 .dark 变量

    • 当前是标准 shadcn 灰色暗色主题
    • 需改为: 深黑背景 + 亮绿色 accent
    • 参考 qoder.com 风格: 近黑底 (#090A0B) + 鲜明 accent 色
    • 需要调整的变量: --primary, --primary-foreground, --accent, --accent-foreground, --background, --card 等

  2. 修改 src/app/globals.css 中的 .color 变量

    • 当前是暖色烛光书房风格 (oklch 暖黄色调)
    • 需改为: 更丰富、更醒目的配色
    • 可考虑赛博朋克/霓虹风格，或大胆的多色搭配

  3. 更新 .prose-chat 相关样式

    • .dark .prose-chat 和 .color .prose-chat 的代码块背景色需同步调整

  4. 视觉验证

    • 三个主题都需要在浏览器中实际验证
    • 重点检查: 消息气泡可读性、代码块对比度、sidebar 高亮、输入框可读性

设计参考:

  • qoder.com 已抓取分析，其 theme-color 为 #8B5CF6(紫色) 配 #090A0B(近黑)
  • 用户要求深夜主题用绿色而非紫色

4. 已修复的 Bug

4.1 React Hooks 顺序违规 + TDZ 错误

commit: f4bda7e

问题: ChatPageContent 组件中 if (status === 'loading') return 早期返回放在了 hooks 声明之前，导致：

  1. React 报 hooks 数量不一致错误
  2. openConversation 函数在 TDZ 中被访问

修复: 将早期返回移到所有 hooks 和函数声明之后、JSX return 之前。

正确顺序:

useState hooks (×7)
→ useCallback(loadConversations)
→ useEffect(loadConversations)
→ useEffect(URL params check)
→ async function openConversation
→ async function loadMoreMessages
→ async function handleSendMessage
→ async function handleSelectPersona
→ async function handleGroupCreated
→ function handleUpgradeToGroup
→ if (status === 'loading') return  ← 早期返回在这里
→ return JSX

5. 数据库

两个 migration 文件:

  • drizzle/0000_clean_harpoon.sql — 初始 schema
  • drizzle/0001_smooth_the_watchers.sql — 用户认证相关表

主要表: users, conversations, conversation_members, messages

6. 开发命令

pnpm dev              # 启动开发服务器 (port 3000)
pnpm build            # 构建
pnpm lint             # ESLint
pnpm db:push          # 推送 schema 到数据库
pnpm db:generate      # 生成 migration
pnpm sync:personas    # 同步人物配置

7. 接手注意事项

  1. Next.js 版本: 本项目用的是 Next.js 16，与常见教程有差异，开发前先读 node_modules/next/dist/docs/ 下的文档
  2. Tailwind CSS 4: 使用新版语法，主题通过 @theme inline 和 CSS 变量定义
  3. SSE 流式: 发送消息后前端解析 SSE 事件流，事件类型: assistant_start, assistant_chunk, assistant_complete, done
  4. 乐观更新: 用户发送消息时先乐观添加到 UI，再等 SSE 流式响应
  5. 数据隔离: 所有 chat API 都通过 session 获取 userId，查询带 userId 条件