74 lines
4.7 KiB
Markdown
74 lines
4.7 KiB
Markdown
# 啡跃 Endoleap
|
||
|
||
本地 Next.js App Router + TypeScript + Tailwind CSS + shadcn/ui 项目。首页和账户页参考 qyof 的 PROMPT 文件，工作台使用合并后的单侧栏，参考 Notion 的留白与账户菜单组织方式。Other Designs 用于首页叙事与版式参考。
|
||
|
||
项目目录：`/Users/zzyang/endoleap`。
|
||
|
||
## 启动
|
||
|
||
```sh
|
||
npm ci
|
||
npm run dev
|
||
```
|
||
|
||
默认仅监听本机 localhost:17321。生产模式：`npm run build && npm start`。
|
||
|
||
- 首页：/
|
||
- 登录、注册：/login
|
||
- 登录回调：/auth/callback
|
||
- 真实工作台：/dashboard
|
||
- 本地演示：/dashboard?demo=1
|
||
- 无限图谱：/dashboard/{workspace}/{board}
|
||
|
||
## 路由结构
|
||
|
||
- `src/app/layout.tsx`：根布局、中文语言标记、全局样式与页面元信息。
|
||
- `src/app/page.tsx`：首页。
|
||
- `src/app/login/page.tsx`、`src/app/auth/callback/page.tsx`：账户页与登录回调。
|
||
- `src/app/dashboard/layout.tsx`：共享单侧栏；`page.tsx` 保留空白工作区。
|
||
- `src/app/dashboard/dashboard.tsx`：侧栏收起/展开、页面搜索、新建图谱与底部账户弹出框。
|
||
- `src/app/dashboard/[workspace]/[board]/page.tsx`：按 workspace 和图谱 ID 打开页面，重新读取后端资料。
|
||
- `src/components/ui/icon-button.tsx`：Lucide 图标按钮，图标为 16×16px，上下 4px、左右 6px 内边距，总尺寸为 28×24px。
|
||
- `src/app/api/**/route.ts`：Foundry 代理与 OAuth 跳转，使用 App Router Route Handlers。
|
||
|
||
## 配置
|
||
|
||
复制 .env.example 为 .env.local，按实际部署填写：
|
||
|
||
- FOUNDRY_API_ORIGIN：仅供 Next 服务端请求后端，默认 https://api.foundry.entroia.com。
|
||
- NEXT_PUBLIC_FOUNDRY_PROJECT：项目标识，默认 endoleap。
|
||
|
||
Slack Client Secret、Signing Secret、Verification Token、用户令牌与 app token 均不需要放入此前端。浏览器调用同源 Next API，由服务端转发到 Foundry。Foundry 会话保存在 HttpOnly / SameSite=Lax Cookie，生产 HTTPS 反向代理需传 X-Forwarded-Proto=https。不要将原始会话写入客户端存储。
|
||
|
||
Google / Slack 的提供方回调仍是 Foundry 后端地址；后端的项目回调映射必须指向本前端 /auth/callback。协议、主机名、端口必须与启动第三方登录时一致，否则 sessionStorage 中的 verifier 无法恢复。正式账号授权、邮件验证与 OAuth 全流程尚未完成真人验收；HTTP 302 跳转成功不能代表登录成功。
|
||
|
||
## 当前功能与范围
|
||
|
||
- 响应式首页、锚点导航与 FAQ。
|
||
- 邮箱注册 / 登录 / 邮件验证兑换，Google 和 Slack 的 PKCE 登录入口及回调处理。
|
||
- 真实用户资料、空间列表与创建、画布列表与创建。资料和空间并行读取；首次创建画布时自动建立个人空间。
|
||
- 单侧栏第一行提供完全收起/恢复与新建页面，第二行为当前空间页面列表搜索，底部账户弹出框提供空间切换和退出登录。
|
||
- 新建页面使用 Foundry Core 的 `POST /workspaces/{workspace}/materials`，提交 `kind: board`、默认名称“未命名图谱”和内容版本；由后端生成 ID。没有空间时先创建“个人空间”，成功后跳转到图谱的独立地址。
|
||
- 本地演示提供示例图谱、搜索、新建和浏览器保存，支持图谱独立地址与刷新。
|
||
- 图形编辑、连接线、分享、Agent、收藏及完整布局持久化尚未接入。图谱页面目前只显示已保存的名称和空白图谱区域；演示数据不写入线上。
|
||
- 本地演示仅用于查看界面，不提供后端认证与权限。
|
||
|
||
Figma 原始 Logo、人物插画与图标已下载到 public/assets，不依赖临时 Figma URL。品牌保持啡跃 Endoleap；shadcn Button / Dialog 使用官方 registry 源码。依赖版本固定，package-lock.json 可用于 npm ci。
|
||
|
||
## 验证
|
||
|
||
```sh
|
||
npm run build
|
||
node tests/api-smoke.mjs
|
||
```
|
||
|
||
API 测试使用本机临时后端和独立前端进程，检查会话 Cookie、令牌不泄漏、同源校验和路径白名单，不访问线上账号。构建需先完成。冒烟测试还覆盖所有页面地址、元信息、OAuth 跳转、请求体限制及退出会话。此前的浏览器验收覆盖登录/注册切换、演示画布创建、搜索空状态、笔记保存、桌面与 390px 手机布局；本次迁移的验证结果见 VALIDATION.md。
|
||
|
||
若执行环境限制 Turbopack 的 CSS 工作进程绑定本地端口，可使用官方 Webpack 模式：`npm run build -- --webpack`。
|
||
|
||
项目已同步至 `ssh://git@gitea.entroia.com:22222/Zayden-Jung/endoleap.git`；尚未部署。
|
||
|
||
|
||
性能分析、实测耗时和修复说明见 [PERFORMANCE.md](PERFORMANCE.md)。
|
||
流程回归可在支持 TypeScript 类型擦除的 Node 版本执行：`node --experimental-strip-types --test tests/workspace.test.mjs`。
|