{"repo": "chenruiiiii/haha-note", "files": {"README.md": {"7a7237f9fbd6133788d2332064a18d9692c479c8": {"t": 1786068581.9736333, "n": 6288, "h": "0c8a0bc444b44b4c", "c": "# Haha Note\n\nHaha Note 是一个基于 Next.js App Router 的知识笔记与 AI 写作应用。项目集成了文档管理、知识库浏览、收藏、公开笔记、AI 对话生成、对话记录沉淀和推荐内容浏览等能力，数据主要存储在 MongoDB 中。\n\n## 功能概览\n\n- 文档工作台：展示最近编辑、最近浏览的文档，并支持新建文档/知识库入口。\n- 知识库管理：按知识库组织文档，支持知识库列表、详情页、文件侧栏和文档详情查看。\n- AI 写作/对话：基于 AI SDK 和 DeepSeek 模型实现流式对话、自动重试、停止生成、会话标题与摘要生成。\n- 收藏与推荐：支持收藏内容、漫游推荐列表、推荐详情与公开笔记浏览。\n- 公开笔记：通过公开链接查看文档内容。\n- 登录鉴权：内置管理员登录接口，使用 HttpOnly Cookie 保存 access token 和 refresh token。\n- 监控接入：生产环境通过 `@sentry/nextjs` 接入 Sentry。\n\n## 技术栈\n\n- 框架：Next.js 16、React 19、TypeScript\n- UI：Ant Design 6、Sass、Tailwind CSS\n- 状态管理：Redux Toolkit、RTK Query\n- 编辑器：TipTap、`@uiw/react-md-editor`、Vditor\n- AI：AI SDK、`@ai-sdk/deepseek`\n- 数据库：MongoDB\n- 校验：Zod\n- 监控：Sentry\n\n## 项目结构\n\n```text\n.\n├── app/                         # Next.js App Router 页面、布局和 API routes\n│   ├── (home)/                  # 主应用页面组\n│   ├── api/                     # 服务端接口\n│   ├── login/                   # 登录页\n│   ├── public-note/[id]/        # 公开笔记页\n│   └── repo-detail/             # 知识库详情页\n├── public/                      # 静态资源\n├── src/\n│   ├── assets/                  # 样式、图片、iconfont\n│   ├── components/              # 通用组件和业务布局组件\n│   ├── constants/               # 常量配置\n│   ├── hooks/                   # 通用 hooks 和业务 hooks\n│   ├── lib/                     # MongoDB、HTTP、事件总线、鉴权 token 等基础能力\n│   ├── middleware/              # 鉴权路径配置\n│   ├── models/                  # Zod schema 和类型定义\n│   ├── scripts/                 # MongoDB 种子数据脚本\n│   ├── services/                # 客户端请求封装\n│   ├── store/                   # Redux store 与 slices\n│   ├── types/                   # 公共类型\n│   └── utils/                   # 工具函数\n├── proxy.ts                     # Next.js proxy，中间件鉴权逻辑入口\n├── next.config.ts               # Next.js 与 Sentry 配置\n└── package.json\n```\n\n## 环境要求\n\n- Node.js：建议使用 20.x 或更高版本\n- npm：项目当前使用 `package-lock.json`\n- MongoDB：本地或云端 MongoDB 实例\n- DeepSeek API Key：使用 AI 对话与摘要能力时需要\n\n## 环境变量\n\n本地开发建议创建 `.env.development` 或 `.env.local`。不要提交真实密钥。\n\n```env\n# MongoDB 连接地址\nAPP_MONGODB_MONGODB_URI=mongodb+srv://user:password@cluster.example.mongodb.net\n\n# DeepSeek API Key\nDEEPSEEK_API_KEY=your_deepseek_api_key\n\n# JWT 签名密钥。生产环境必须设置为足够随机的长字符串\nAUTH_TOKEN_SECRET=replace-with-a-strong-secret\n\n# 浏览器侧 API 地址\nNEXT_PUBLIC_APP_API_URL=http://localhost:3000/api\n\n# 浏览器侧站点地址，用于公开笔记跳转\nNEXT_PUBLIC_BASE_URL=http://localhost:3000\n```\n\n说明：\n\n- `APP_MONGODB_MONGODB_URI` 是必填项，缺失时 MongoDB 单例会直接抛错。\n- `DEEPSEEK_API_KEY` 影响 `/api/chat-detail` 和 `/api/docs-summary/[docsId]` 等 AI 接口。\n- `AUTH_TOKEN_SECRET` 有开发兜底值，但生产环境必须显式配置。\n\n## 本地启动\n\n安装依赖：\n\n```bash\nnpm install\n```\n\n启动开发服务器：\n\n```bash\nnpm run dev\n```\n\n浏览器打开：\n\n```text\nhttp://localhost:3000\n```\n\n构建生产包：\n\n```bash\nnpm run build\n```\n\n启动生产服务：\n\n```bash\nnpm run start\n```\n\n## 数据初始化\n\n项目提供了 MongoDB 种子脚本。脚本默认读取 `.env.development`：\n\n```bash\nnpm run seed\n```\n\n该命令等价于填充知识库数据：\n\n```bash\nnpx tsx --env-file=.env.development src/scripts/index.ts repos\n```\n\n初始化管理员账号：\n\n```bash\nnpm run seed:admin\n```\n\n可用任务：\n\n```bash\nnpx tsx --env-file=.env.development src/scripts/index.ts repos\nnpx tsx --env-file=.env.development src/scripts/index.ts docs\nnpx tsx --env-file=.env.development src/scripts/index.ts activity\nnpx tsx --env-file=.env.development src/scripts/index.ts favorite\nnpx tsx --env-file=.env.development src/scripts/index.ts ai-chat\nnpx tsx --env-file=.env.development src/scripts/index.ts admin\nnpx tsx --env-file=.env.development src/scripts/index.ts stroll\nnpx tsx --env-file=.env.development src/scripts/index.ts all\n```\n\n开发环境内置演示账号：\n\n| 账号 | 密码 | 角色 |\n| --- | --- | --- |\n| `admin` | `admin` | 管理员 |\n| `editor` | `editor123` | 内容编辑 |\n\n这些账号只适合本地开发或演示，生产环境请改为真实用户体系或至少更换密码。\n\n## 常用脚本\n\n| 命令 | 说明 |\n| --- | --- |\n| `npm run dev` | 启动 Next.js 开发服务器 |\n| `npm run build` | 构建生产版本 |\n| `npm run start` | 启动生产服务 |\n| `npm run lint` | 运行 ESLint |\n| `npm run seed` | 初始化知识库数据 |\n| `npm run seed:admin` | 初始化管理员账号 |\n\n## 主要页面\n\n| 路径 | 说明 |\n| --- | --- |\n| `/` | 开始页，展示文档入口与最近记录 |\n| `/repository` | 知识库列表 |\n| `/repo-detail/[repoId]/home` | 知识库首页 |\n| `/repo-detail/[repoId]/[fileId]` | 知识库文档详情 |\n| `/ai-chat-home` | AI 写作首页 |\n| `/ai-chat/[id]` | AI 对话详情 |\n| `/collect` | 收藏页 |\n| `/stroll` | 漫游推荐 |\n| `/stroll-recommend/[id]` | 推荐详情 |\n| `/public-note/[id]` | 公开笔记 |\n| `/personal-center/[id]` | 个人中心 |\n| `/login` | 登录页 |\n\n## 主要接口\n\n| 接口 | 说明 |\n| --- | --- |\n| `/api/login` | 登录并写入鉴权 Cookie |\n| `/api/logout` | 退出登录并清理 Cookie |\n| `/api/auth/refresh` | 刷新 access token |\n| `/api/repository` | 获取知识库列表 |\n| `/api/repo-detail/[id]` | 获取知识库详情 |\n| `/api/docs-detail/[docsId]` | 获取文档详情 |\n| `/api/docs-summary/[docsId]` | 生成文档摘要 |\n| `/api/chat-detail` | AI 流式对话与会话持久化 |\n| `/api/chat/[id]` | 获取 AI 会话详情 |\n| `/api/chat-latest-mission` | 获取最近 AI 会话 |\n| `/api/chat-collect-mission` | 获取收藏 AI 会话 |\n| `/api/start/edited` | 获取最近编辑记录 |\n| `/api/start/browsed` | 获取最近浏览记录 |\n| `/api/public-note/[id]` | 获取公开笔记 |\n| `/api/stroll/left` | 获取左侧推荐列表 |\n| `/api/stroll/right` | 获取右侧推荐列表 |\n\n## 鉴权说明\n\n登录成功后，服务端会写入两个 HttpOnly Cookie：\n\n- `ha_note_access_token`：短期 access token，默认 15 分钟。\n- `ha_note_refresh_token`：长期 refresh token，默认 7 天。\n\n`src/lib/http.ts` 会在接口返回 401 时尝试调用 `/api/auth/refresh` 自动刷新登录态。`proxy.ts` 中保留了完整的页面级鉴权逻辑，不过当前 `proxy()` 默认直接放行，方便开发调试；需要恢复页面鉴权时，可以将入口切换到 `authProxyWithLogin`。\n\n## 数据库说明\n\n项目会使用多个 MongoDB database/collection：\n\n| Database | Collection | 用途 |\n| --- | --- | --- |\n| `ha_admin` | `users` | 管理员账号 |\n| `repository` | `repo_list` | 知识库列表 |\n| `repository` | `docs_detail` | 文档详情 |\n| `user_activity` | `edit_history` | 编辑历史 |\n| `user_activity` | `browse_history` | 浏览历史 |\n| `user_activity` | `favorite_repos` | 收藏知识库 |\n| `ai-chat` | `latest_mission` | 最近 AI 会话 |\n| `ai-chat` | `collect_mission` | 收藏 AI 会话 |\n| `ai-chat` | `ai_chat_detail` | AI 会话详情 |\n| `stroll-recommend` | `recommend_details` | 漫游推荐详情 |\n\n## 部署注意事项\n\n- 在 Vercel 或其他平台部署时，需要配置 `APP_MONGODB_MONGODB_URI`、`DEEPSEEK_API_KEY`、`AUTH_TOKEN_SECRET`、`NEXT_PUBLIC_APP_API_URL`、`NEXT_PUBLIC_BASE_URL`。\n- 生产环境会启用 Sentry 配置，相关 org/project 在 `next.config.ts` 中维护。\n- `NEXT_PUBLIC_APP_API_URL` 和 `NEXT_PUBLIC_BASE_URL` 需要改为线上域名，避免页面仍请求本地接口。\n- 当前演示账号密码是明文种子数据，不应直接用于生产环境。\n\n## 开发约定\n\n- 客户端请求优先使用 `src/lib/http.ts` 封装，保持错误处理和 refresh token 逻辑一致。\n- API 返回结构建议使用 `ResponseData<T>`，并在 `src/models` 中用 Zod 维护数据模型。\n- 新增页面优先沿用 `app` 目录的 App Router 结构。\n- 新增业务组件放在 `src/components/layout`，可复用基础组件放在 `src/components/common`。\n- 涉及 MongoDB 的新增数据结构，建议同步补充种子脚本和 README 中的数据表说明。\n"}}}}