# supavolt

**Repository Path**: houlonglong/supavolt

## Basic Information

- **Project Name**: supavolt
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-10
- **Last Updated**: 2026-09-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Supavolt

pnpm monorepo：NestJS API + Next.js 前端。目标是迷你 BaaS——账号、组织、项目。后端 Drizzle 连 Neon Postgres；认证用 httpOnly Cookie 里的 JWT。

## 仓库结构

```
apps/api              NestJS API（http://localhost:3000，全局前缀 /api）
web                   Next.js 16（http://localhost:3001）
packages/types        共享类型（@supavolt/types）
packages/constants    Cookie 名、错误文案等（@supavolt/constants）
```

## 技术栈

| 部分 | 技术 |
|------|------|
| 包管理 | pnpm workspace（`pnpm-workspace.yaml`） |
| API | NestJS 10、@nestjs/config 4、JWT、cookie-parser |
| 前端 | Next.js 16、React 19、Tailwind 4、shadcn、RHF、Zod 4 |
| 数据库 | Neon Postgres、Drizzle ORM |
| 认证 | 邮箱密码（bcrypt）+ Google / GitHub OAuth（进行中） |

## 环境要求

- Node.js 20+
- pnpm 10.22.0（根目录 `packageManager`）
- Neon 或任意 Postgres

## 快速开始

```bash
pnpm install
```

### 环境变量

`apps/api/.env`（不要把真实密钥提交进 git）：

```env
PORT=3000
WEB_URL=http://localhost:3001
DATABASE_URL=postgresql://USER:PASSWORD@HOST/neondb?sslmode=require

JWT_ACCESS_SECRET=
JWT_REFRESH_SECRET=
JWT_ACCESS_EXPIRES_IN=15m
JWT_REFRESH_EXPIRES_IN=7d

GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GOOGLE_CALLBACK_URL=http://localhost:3000/api/auth/google/callback

GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=
GITHUB_CALLBACK_URL=http://localhost:3000/api/auth/github/callback
```

`web/.env`：

```env
NEXT_PUBLIC_API_URL=http://localhost:3000/api
```

`WEB_URL` 给 API 做 CORS（`credentials: true`）。`NEXT_PUBLIC_API_URL` 给前端和 Server Action 调接口。

签发 JWT 用 `JWT_ACCESS_SECRET`。`JwtAuthGuard` 必须验同一把钥匙，不要写成另一个 `JWT_SECRET`。

### 数据库

schema：`apps/api/src/db/schema/`
迁移：`apps/api/drizzle/`

```bash
pnpm --filter api run db:generate
pnpm --filter api run db:migrate
pnpm --filter api run db:push
pnpm --filter api run db:studio
```

表关系：

```
users ──< org_members >── organizations ──< projects
                 role: admin | developer
```

- `users.id`：UUID（`gen_random_uuid()`），只当主键，不要用来按时间排序
- 新用户在前：`ORDER BY created_at DESC`
- 注册时会：建用户 → 建默认组织 → `org_members` 里挂成 `admin`

在 VS Code Database Client 里连 **PostgreSQL / `neondb`**（不要 `neondb_meta`）。看表用 GUI 时建议 Neon **direct** 地址；应用可以继续用 pooler。

### 启动

```bash
pnpm dev          # API + Web
pnpm dev:api
pnpm dev:web
```

- API：http://localhost:3000
- Web：http://localhost:3001
- 健康检查：`GET /api/health`
- 登录页：http://localhost:3001/login

Cursor 调试：`.vscode/launch.json` 里选 **API + Web**（compound，两个进程）。不要对单个 `.ts` 点 Run。

## API

约定：前缀 `/api`，`ValidationPipe`，Cookie 读写 JWT。

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/health` | 存活检查 |
| POST | `/api/auth/register` | 注册，写 Cookie |
| POST | `/api/auth/login` | 登录，写 Cookie |
| POST | `/api/auth/logout` | 清 Cookie |
| POST | `/api/auth/refresh` | 用 refresh Cookie 换新 token |
| GET | `/api/auth/me` | 当前用户（`JwtAuthGuard`） |
| GET | `/api/auth/google` | 跳转 Google |
| GET | `/api/auth/google/callback` | Google 回调（看 `code`，不要挂 JWT Guard） |
| GET | `/api/auth/github` | 跳转 GitHub |
| GET | `/api/auth/github/callback` | GitHub 回调 |

换 Google/GitHub token 时 body 用 `application/x-www-form-urlencoded`，不要用全局 JSON `headers`。

组织和项目表已有，还没有对应 CRUD 接口。

## 前端

- `web/src/app/login/page.tsx`：账密 + Google / GitHub 入口
- `web/src/features/auth/`：Zod schema、Server Action

注意：Server Action 里 `fetch` API 时，`Set-Cookie` 落在 Next 服务端，不会自动进浏览器。要在 Action 里把 Cookie 转到 `cookies()`，或让浏览器直打 API（`credentials: 'include'`）。登录闭环还没完全打通。

装 shadcn 前删掉 `web/package-lock.json`，用 `pnpm dlx shadcn@latest add ...`，否则会走 npm 并撞上 `workspace:*`。

## 常用命令

```bash
pnpm --filter api add "<pkg>"
pnpm --filter web add "<pkg>"
```

zsh 里带 `^` 的版本号必须加引号。

## 共享包

- `@supavolt/types`：`User`、`Organization`、`OrgMember`、`Project`、`LoginInput`、`RegisterInput`、`JwtPayload`
- `@supavolt/constants`：`COOKIE_KEYS`、`ERROR_MESSAGES`

两端都是 `"workspace:*"`。