---
url: /packages/logger.md
---
# @fullstackpack/logger

通用的日志工具包，支持时间戳显示和应用前缀配置。

## 特性

* ✅ 可配置时间戳显示
* ✅ 可配置应用前缀
* ✅ 支持颜色输出（终端）
* ✅ 支持多种日志级别：debug, info, warn, error
* ✅ TypeScript 完整支持
* ✅ 零依赖

## 安装

```bash
pnpm add @fullstackpack/logger
```

## 使用

### 基础用法

```typescript
import { createLogger } from '@fullstackpack/logger'

const logger = createLogger({
  prefix: 'web',
  showTime: true,
  enableColors: true
})

logger.info('Server started')
logger.warn('This is a warning')
logger.error('An error occurred')
```

### 配置选项

```typescript
interface LoggerOptions {
  /** 应用前缀，例如 'web', 'server' */
  prefix?: string
  /** 是否显示时间戳 */
  showTime?: boolean
  /** 是否启用颜色输出 */
  enableColors?: boolean
}
```

### 示例输出

```
[2024-01-01T12:00:00.000Z] [INFO] [web] Server started
[2024-01-01T12:00:01.000Z] [WARN] [web] This is a warning
[2024-01-01T12:00:02.000Z] [ERROR] [web] An error occurred
```

## API

### createLogger(options?)

创建一个新的 Logger 实例。

### Logger 方法

* `logger.debug(message, ...args)` - 调试信息
* `logger.info(message, ...args)` - 一般信息
* `logger.warn(message, ...args)` - 警告信息
* `logger.error(message, ...args)` - 错误信息

---

---
url: /packages/shared.md
---
# @fullstackpack/shared

共享类型和 schemas 包，提供跨应用的类型定义和验证。

## 特性

* ✅ Zod schemas - 数据验证
* ✅ TypeScript 类型 - 类型定义
* ✅ 工具函数 - 认证工具等
* ✅ 错误码定义 - 统一错误码

## 安装

```bash
pnpm add @fullstackpack/shared
```

## 使用

### Schemas

```typescript
import { loginSchema, registerSchema } from '@fullstackpack/shared/schemas/auth'

const loginData = loginSchema.parse({ email: 'user@example.com', password: 'password' })
```

### 类型

```typescript
import type { LoginInput, RegisterInput } from '@fullstackpack/shared/schemas/auth'
```

### 认证工具

```typescript
import {
  extractTokenFromHash,
  clearTokenFromHash,
  redirectToAuthPortal,
  redirectToAuthPortalForLogout
} from '@fullstackpack/shared'

// 从 URL hash 提取 token
const token = extractTokenFromHash()

// 清除 URL hash 中的 token
clearTokenFromHash()

// 跳转到认证门户
redirectToAuthPortal('http://app.example.com/dashboard')

// 退出登录
redirectToAuthPortalForLogout()
```

## 目录结构

```
packages/shared/
├── src/
│   ├── schemas/         # Zod schemas
│   ├── types/           # TypeScript 类型
│   ├── lib/             # 工具函数
│   └── errors/          # 错误码定义
```

---

---
url: /apps/auth-portal.md
---
# Auth Portal

认证门户是统一登录入口，提供 SSO 单点登录功能。

## 特性

* ✅ **统一登录** - 所有应用共享同一个登录入口
* ✅ **自动跳转** - 登录后自动跳转回目标应用
* ✅ **SSO 支持** - 已登录用户自动识别，无需重复登录
* ✅ **统一注销** - 退出登录统一处理

## 技术栈

* **React 19** + **TypeScript**
* **Vite** - 构建工具
* **shadcn/ui** - UI 组件库
* **TanStack Query** - 数据获取
* **Zustand** - 状态管理

## 开发

```bash
pnpm dev
```

访问：`http://localhost:7777`

## 构建

```bash
pnpm build
```

## 部署

```bash
pnpm deploy
```

## 使用方式

### 1. 从其他应用跳转

其他应用未登录时，会自动跳转到认证门户：

```
http://auth.example.com?redirect=http://app.example.com/dashboard
```

### 2. 登录后跳转

登录成功后，会自动跳转回目标应用，并在 URL hash 中传递 token：

```
http://app.example.com/dashboard#token=xxx
```

### 3. 统一注销

退出登录时，会跳转到认证门户进行统一注销：

```
http://auth.example.com?logout=true
```

## 环境变量

详细环境变量配置请查看 [Auth Portal README](/apps/auth-portal#环境变量)。

**可选：**

* `VITE_API_URL` - 后端 API 地址（开发环境自动使用代理）

---

---
url: /deployment/cicd.md
---
# CI/CD 配置

## GitHub Actions

项目已配置 GitHub Actions，push 到 `main` 分支后会自动部署到 Cloudflare。

## 配置步骤

### 1. 配置 GitHub Secrets

在 GitHub 仓库 Settings → Secrets and variables → Actions 中添加：

**部署相关（必需）：**

* `CLOUDFLARE_API_TOKEN` - Cloudflare API Token（需要 `Account:Cloudflare Workers:Edit` 权限）
* `CLOUDFLARE_ACCOUNT_ID` - Cloudflare Account ID（可在 Dashboard 右侧找到）

**构建时环境变量（必需）：**

* `VITE_API_URL` - 后端 API 地址（完整 URL，如：`https://api.example.com`）
* `VITE_AUTH_PORTAL_URL` - 认证门户地址（完整 URL，如：`https://auth.example.com`，web 应用需要）

**获取 API Token：**

1. 访问 [Cloudflare Dashboard](https://dash.cloudflare.com/profile/api-tokens)
2. 创建 Token，权限选择：
   * `Account:Cloudflare Workers:Edit`
   * `Account:Cloudflare Pages:Edit`
   * `Zone:Zone:Read`（如果使用自定义域名）

### 2. 创建 Cloudflare Pages 项目（首次部署前）

首次部署前需要先创建 Cloudflare Pages 项目（在 Dashboard 或使用 `wrangler pages project create`）。

### 3. 配置 Cloudflare Workers Secrets

使用 `wrangler secret put` 配置后端运行时环境变量：

```bash
cd apps/server

# 必需
wrangler secret put JWT_SECRET          # JWT 密钥（至少 32 字符）
wrangler secret put ACCELERATE_URL      # Prisma Accelerate URL
wrangler secret put ALLOWED_DOMAIN      # 允许的域名（如：exuils.com）

# 可选
wrangler secret put CORS_ORIGIN         # CORS 允许的源
wrangler secret put JWT_EXPIRES_IN      # JWT 过期时间（默认：7d）
```

**环境变量说明：**

* `ALLOWED_DOMAIN`：允许的域名，会允许该域名及其所有子域名（如：`exuils.com` 允许 `*.exuils.com`）
* `CORS_ORIGIN`：精确匹配的 CORS 源（可选，如果设置了 `ALLOWED_DOMAIN` 可省略）

### 4. Push 代码触发部署

```bash
git push origin main
```

## 工作流说明

### 智能路径触发 ⭐

CI/CD 配置了**路径触发**功能，只有相关应用变更时才会部署：

* **只修改 `apps/server/**`** → 只部署后端
* **只修改 `apps/web/**`** → 只部署前端
* **只修改 `apps/auth-portal/**`** → 只部署认证门户
* **只修改 `apps/docs/**`** → 只部署文档站点
* **修改 `packages/**`** → 部署所有依赖的应用（server、web、auth-portal）

这样可以：

* ✅ 节省 CI/CD 时间
* ✅ 减少不必要的部署
* ✅ 独立部署各个应用

### 部署流程

1. **检测变更** → 分析哪些应用需要部署
2. **构建依赖** → 构建共享的 packages
3. **构建应用** → 只构建变更的应用
4. **部署** → 只部署变更的应用

### 手动触发

如果需要强制部署所有应用，可以在 GitHub Actions 页面：

1. 进入 `Actions` 标签页
2. 选择 `Deploy to Cloudflare` workflow
3. 点击 `Run workflow`

## 查看部署状态

在 GitHub Actions 标签页中查看部署状态和日志。

---

---
url: /deployment/cloudflare.md
---
# Cloudflare 部署

## 概述

Cloudflare 部署使用 Cloudflare Workers（后端）和 Cloudflare Pages（前端），提供全球边缘计算能力。

## 前置要求

* Cloudflare 账户
* GitHub 仓库（用于 CI/CD）
* Prisma Accelerate 账户（用于数据库连接）

## 手动部署

### 1. 后端部署（Cloudflare Workers）

#### 1.1 设置环境变量

```bash
cd apps/server
wrangler secret put JWT_SECRET
wrangler secret put ACCELERATE_URL  # 或 DATABASE_URL
```

#### 1.2 部署

```bash
pnpm deploy:server
# 或
cd apps/server
pnpm build
wrangler deploy
```

### 2. 前端部署（Cloudflare Pages）

#### 2.1 构建

```bash
cd apps/web
pnpm build
```

#### 2.2 部署

```bash
pnpm deploy:web
# 或使用 wrangler
wrangler pages deploy dist
```

#### 2.3 配置环境变量（可选）

在 Cloudflare Pages Dashboard 中配置环境变量，详见各应用的 README。

### 3. 认证门户部署

```bash
cd apps/auth-portal
pnpm build
wrangler pages deploy dist --project-name=fullstackpack-auth-portal
```

### 4. 文档站点部署

```bash
cd apps/docs
pnpm build
wrangler pages deploy .vitepress/dist --project-name=fullstackpack-docs
```

**注意**：首次部署前需要先创建 Cloudflare Pages 项目。

## 自动部署（CI/CD）⭐ 推荐

项目已配置 GitHub Actions，push 到 `main` 分支后会自动部署。

### 1. 配置 GitHub Secrets

在 GitHub 仓库设置中添加以下 Secrets：

* `CLOUDFLARE_API_TOKEN` - Cloudflare API Token（需要 `Account:Cloudflare Workers:Edit` 权限）
* `CLOUDFLARE_ACCOUNT_ID` - Cloudflare Account ID（可在 Dashboard 右侧找到）

**获取 API Token：**

1. 访问 [Cloudflare Dashboard](https://dash.cloudflare.com/profile/api-tokens)
2. 创建 Token，权限选择：
   * `Account:Cloudflare Workers:Edit`
   * `Account:Cloudflare Pages:Edit`
   * `Zone:Zone:Read`（如果使用自定义域名）

### 2. 配置 Cloudflare Workers 环境变量

```bash
cd apps/server
wrangler secret put JWT_SECRET
wrangler secret put ACCELERATE_URL
```

### 3. Push 代码触发部署

```bash
git push origin main
```

GitHub Actions 会自动：

* 构建后端并部署到 Cloudflare Workers
* 构建前端并部署到 Cloudflare Pages
* 构建认证门户并部署到 Cloudflare Pages
* 构建文档站点并部署到 Cloudflare Pages

**注意**：首次部署前，需要先创建 Cloudflare Pages 项目（见上方手动部署步骤）。

## 数据库配置

### Prisma Accelerate（推荐）

1. 访问 https://accelerate.prisma.io/
2. 注册并创建项目
3. 获取 Accelerate URL
4. 设置为环境变量：`ACCELERATE_URL`

### 数据库迁移

```bash
cd apps/server
npx prisma migrate deploy
```

## 自定义域名

### Workers（后端）

在 `wrangler.toml` 中配置：

```toml
routes = [
  { pattern = "api.yourdomain.com/*", zone_name = "yourdomain.com" }
]
```

### Pages（前端）

在 Cloudflare Pages Dashboard 中配置自定义域名。

## 注意事项

1. **环境变量**：前端环境变量在 Cloudflare Pages Dashboard 中配置
2. **CORS**：确保后端 CORS 设置允许前端域名
3. **HTTPS**：Cloudflare 自动提供 HTTPS
4. **路由**：前端 SPA 路由需要在 Pages 中配置重写规则

---

---
url: /apps/front-template.md
---
# Front Template

基于 React + Vite 的前端应用模板，已集成 SSO 单点登录功能。

## 特性

* ✅ **SSO 单点登录** - 统一使用认证门户进行登录
* ✅ **自动跳转** - 未登录时自动跳转到认证门户
* ✅ **Token 管理** - 自动从 URL hash 提取 token
* ✅ **统一注销** - 退出登录统一跳转到认证门户

## 技术栈

* **React 19** + **TypeScript**
* **Vite** - 构建工具
* **shadcn/ui** - UI 组件库
* **TanStack Query** - 数据获取
* **Zustand** - 状态管理
* **React Router DOM v7** - 路由
* **Tailwind CSS** - 样式

## 如何使用此模板

1. **复制模板**：
   ```bash
   cp -r apps/front-template apps/your-app-name
   ```

2. **修改配置**：
   * 修改 `package.json` 中的 `name` 字段
   * 修改 `vite.config.ts` 中的端口（建议使用 8000+）
   * 修改 `vite.config.ts` 中的 `VITE_AUTH_PORTAL_URL`（如果需要）

3. **自定义应用**：
   * 修改 `src/pages/dashboard/Home.tsx` - 你的 Dashboard 页面
   * 修改 `src/components/layouts/DashboardLayout.tsx` - 你的布局
   * 添加你的业务页面和路由

## 环境变量

**可选：**

* `VITE_API_URL` - 后端 API 地址（开发环境自动使用代理）
* `VITE_AUTH_PORTAL_URL` - 认证门户 URL（开发环境默认 `http://localhost:7777`）

## 开发

```bash
pnpm dev
```

## 构建

```bash
pnpm build
```

## 部署

```bash
pnpm deploy
```

## SSO 集成说明

### 1. 路由守卫

使用 `ProtectedRoute` 组件保护需要登录的路由：

```tsx
import { ProtectedRoute } from '@/components/auth/ProtectedRoute'

<ProtectedRoute>
  <YourPage />
</ProtectedRoute>
```

### 2. 退出登录

退出登录会自动跳转到认证门户：

```tsx
import { useLogout } from '@/hooks/queries/auth'
import { redirectToAuthPortalForLogout } from '@fullstackpack/shared'
import { AUTH_PORTAL_URL } from '@/constants'

const logoutMutation = useLogout()

const handleLogout = async () => {
  await logoutMutation.mutateAsync()
  redirectToAuthPortalForLogout(AUTH_PORTAL_URL)
}
```

### 3. 获取用户信息

```tsx
import { useAuth } from '@/hooks/queries/auth'

const { user, isAuthenticated } = useAuth()
```

---

---
url: /apps/server.md
---
# Server

基于 Hono 框架的后端服务，运行在 Cloudflare Workers 上。

## 技术栈

* **Hono** - Web 框架（专为边缘环境优化）
* **Cloudflare Workers** - 边缘计算平台
* **Prisma 7** - ORM（使用 Accelerate 或 Adapter）
* **Zod** - Schema 验证
* **Vitest** - 测试框架

## 开发

```bash
pnpm dev
```

## 构建

```bash
pnpm build
```

## 部署

```bash
pnpm deploy
```

## 数据库

### 连接方案

Cloudflare Workers 运行在 V8 isolate 环境中，**不支持直接的 TCP 连接**。项目支持两种数据库连接方案：

1. **Prisma Accelerate**（推荐）- 通过 HTTP API 连接数据库
2. **Prisma Adapter** - 使用 PostgreSQL adapter（仅 Node.js 环境）

### 配置

```bash
# 推送 schema
pnpm db:push

# 生成 Prisma Client
pnpm db:generate
```

详细数据库配置请查看 [数据库文档](/apps/server#数据库连接方案)。

## API 路由

* `POST /api/v1/auth/login` - 用户登录
* `POST /api/v1/auth/register` - 用户注册
* `POST /api/v1/auth/verify` - 验证 token
* `GET /api/v1/auth/me` - 获取当前用户信息

## 环境变量

详细环境变量配置请查看 [Server README](/apps/server#环境变量)。

**必需：**

* `JWT_SECRET` - JWT 密钥（至少 32 字符）
* `ACCELERATE_URL` 或 `DATABASE_URL` - 数据库连接

**注意**：Cloudflare Workers 环境使用 `ACCELERATE_URL`，自托管 Node.js 环境使用 `DATABASE_URL`。

## 数据库连接方案

### Prisma Accelerate（推荐）✅

**当前项目使用的方案**

Prisma Accelerate 是一个连接池和缓存服务，通过 HTTP API 连接数据库：

**优点：**

* ✅ 专为边缘环境设计
* ✅ 连接池管理（避免连接数限制）
* ✅ 查询缓存（提升性能）
* ✅ 支持所有 Prisma 功能
* ✅ 有免费开发计划

**获取方式：**

1. 访问 https://accelerate.prisma.io/
2. 注册并创建项目
3. 获取 Accelerate URL

### Prisma Adapter（已实现）✅

Prisma 7 支持通过 adapter 连接数据库：

**注意：**

* ⚠️ **在 Cloudflare Workers 中可能不工作**：PostgreSQL adapter 需要 TCP 连接，而 Workers 只支持 fetch API
* ⚠️ 如果 adapter 失败，会自动提示使用 Prisma Accelerate
* ✅ 在 Node.js 环境中可以正常工作

**使用方式：**

* 如果设置了 `ACCELERATE_URL`，优先使用 Accelerate
* 如果没有 `ACCELERATE_URL` 但有 `DATABASE_URL`，会尝试使用 adapter
* 如果 adapter 失败，会提示使用 Accelerate

## 总结

| 方案 | 支持 PostgreSQL | 成熟度 | 推荐度 |
|------|----------------|--------|--------|
| Prisma Accelerate | ✅ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| Prisma Adapter | ✅ | ⭐⭐ | ⭐ |

**结论：** 对于 PostgreSQL + Cloudflare Workers，**Prisma Accelerate 是最佳选择**。

---

---
url: /guide/sso-dev.md
---
# SSO 本地开发指南

## 本地开发注意事项

### 1. 清除旧的认证信息

如果之前测试过登录功能，浏览器 localStorage 中可能保存了旧的 token，导致应用认为已登录。

**解决方法**：

1. 打开浏览器开发者工具（F12）
2. 进入 Application/存储 → Local Storage
3. 找到对应的域名（如 `http://localhost:8000`）
4. 删除 `auth-storage` 键
5. 刷新页面

或者直接在浏览器控制台执行：

```javascript
localStorage.removeItem('auth-storage')
```

### 2. 端口配置

本地开发时，各应用的端口：

* **认证门户** (`apps/auth-portal`): `http://localhost:7777`
* **Web 应用** (`apps/web`): `http://localhost:8000`
* **应用模板** (`apps/front-template`): `http://localhost:8001`
* **后端服务** (`apps/server`): `http://localhost:8787`

### 3. 环境变量配置

开发环境已自动配置：

* `VITE_AUTH_PORTAL_URL` = `http://localhost:7777`（开发环境）
* `VITE_API_URL` = `/api`（开发环境，通过代理到 `http://localhost:8787`）

生产环境需要设置环境变量：

* `VITE_AUTH_PORTAL_URL` = 生产环境的认证门户 URL（如 `https://auth.example.com`）
* `VITE_API_URL` = 生产环境的 API URL

### 4. 测试流程

1. **启动所有服务**：
   ```bash
   pnpm dev:all
   ```

2. **测试 SSO 流程**：
   * 访问 `http://localhost:8000/dashboard`（web 应用）
   * 应该自动跳转到 `http://localhost:7777?redirect=http://localhost:8000/dashboard`
   * 在认证门户登录
   * 登录成功后自动跳转回 `http://localhost:8000/dashboard#token=xxx`
   * web 应用从 hash 中提取 token 并存储

3. **测试跨应用 SSO**：
   * 在 web 应用登录后
   * 访问 `http://localhost:8001/dashboard`（front-template）
   * 如果 localStorage 中有 token，应该直接显示 Dashboard
   * 如果没有 token，会跳转到认证门户

### 5. 常见问题

**Q: 为什么访问 web 应用没有跳转到认证门户？**
A: 可能的原因：

* localStorage 中有旧的 token（解决方法见第 1 点）
* 访问的不是受保护的路由（如 `/dashboard`）
* 检查浏览器控制台是否有错误

**Q: 登录后没有跳转回目标应用？**
A: 检查：

* 认证门户的 redirect 参数是否正确
* 浏览器控制台是否有错误
* 网络请求是否成功

**Q: Token 验证失败？**
A: 检查：

* 后端服务是否正常运行（`http://localhost:8787`）
* Token 是否过期
* 浏览器控制台的网络请求错误

### 6. 调试技巧

1. **查看 localStorage**：
   ```javascript
   // 浏览器控制台
   JSON.parse(localStorage.getItem('auth-storage'))
   ```

2. **清除所有认证信息**：
   ```javascript
   // 浏览器控制台
   localStorage.removeItem('auth-storage')
   ```

3. **手动设置 token（测试用）**：
   ```javascript
   // 浏览器控制台
   localStorage.setItem('auth-storage', JSON.stringify({
     state: {
       token: 'your-token-here',
       user: null,
       isLoading: false
     },
     version: 0
   }))
   ```

4. **查看当前 URL hash**：
   ```javascript
   // 浏览器控制台
   window.location.hash
   ```

---

---
url: /apps/web.md
---
# Web

基于 React + Vite 的前端应用。

## 技术栈

* **React 19** + **TypeScript**
* **Vite** - 构建工具
* **shadcn/ui** - UI 组件库
* **TanStack Query** - 数据获取
* **Zustand** - 状态管理
* **React Router DOM v7** - 路由
* **Tailwind CSS** - 样式

## 开发

```bash
pnpm dev
```

## 构建

```bash
pnpm build
```

## 部署

```bash
pnpm deploy
```

## SSO 集成

Web 应用已集成 SSO 单点登录功能：

* ✅ **自动跳转** - 未登录时自动跳转到认证门户
* ✅ **Token 管理** - 自动从 URL hash 提取 token
* ✅ **统一注销** - 退出登录统一跳转到认证门户

## 环境变量

详细环境变量配置请查看 [Web README](/apps/web#环境变量)。

**可选：**

* `VITE_API_URL` - 后端 API 地址（开发环境自动使用代理）
* `VITE_AUTH_PORTAL_URL` - 认证门户 URL（开发环境默认 `http://localhost:7777`）

---

---
url: /apps.md
---
# 应用文档

## 应用列表

* [Server](/apps/server) - 后端服务（Hono + Cloudflare Workers）
* [Web](/apps/web) - Web 应用（React + Vite）
* [Auth Portal](/apps/auth-portal) - 认证门户（统一登录入口）
* [Front Template](/apps/front-template) - 前端应用模板

## 应用架构

```
apps/
├── server/          # 后端 API 服务
├── web/             # Web 应用实例
├── auth-portal/     # SSO 认证门户
├── front-template/  # 前端应用模板
└── docs/            # 文档站点
```

---

---
url: /guide/development.md
---
# 开发指南

## 开发流程

### TDD 开发模式 ⭐ 优先采用

1. **Red**: 先写测试，运行看到失败
2. **Green**: 写最少代码让测试通过
3. **Refactor**: 重构代码，保持测试通过

### 开发流程

1. **后端**: 先写测试 → 实现业务逻辑 → 添加路由测试 → 实现路由
2. **前端**: 先写组件测试 → 实现组件 → 添加 hooks 测试 → 实现 hooks
3. **共享**: 先写 schema 测试 → 定义 schemas

## 测试

### 运行测试

```bash
# 运行所有测试
pnpm test

# 运行特定包的测试
pnpm --filter server test
pnpm --filter web test

# 监听模式
pnpm --filter server test:watch
```

### 测试规范

* 测试文件：`__tests__` 目录，与源码结构对应
* 命名：`*.test.ts` 或 `*.spec.ts`
* 工具：Vitest（后端）+ Vitest + React Testing Library（前端）
* Mock：使用 Vitest 的 `vi.mock()` 和 `vi.fn()`

## 代码规范

### TypeScript

* **禁止使用 `any` 类型**：必须使用明确的类型定义
* 优先使用类型推断，减少显式类型注解
* 使用 `interface` 定义对象类型
* 使用 `type` 定义联合类型、工具类型等

### Git 提交规范

格式：`类型(模块): 描述`

**类型**: `feat` | `fix` | `docs` | `refactor` | `test` | `chore` | `perf` | `ci`

**模块**: `auth` | `user` | `api` | `ui` | `config` | `deploy` | `deps` | `init`

**示例**:

```bash
feat(auth): 添加用户登录功能
fix(api): 修复 CORS 错误
docs(readme): 更新部署文档
```

## 调试技巧

### 后端调试

```bash
# 使用 wrangler dev 进行调试
cd apps/server
pnpm dev

# 查看日志
wrangler tail
```

### 前端调试

* 使用浏览器开发者工具
* React DevTools
* TanStack Query DevTools

## 常见问题

### 端口冲突

如果端口被占用，可以修改：

* `apps/web/vite.config.ts` - Web 应用端口
* `apps/auth-portal/vite.config.ts` - 认证门户端口
* `apps/server/wrangler.toml` - 后端端口

### 数据库连接失败

* 检查 `DATABASE_URL` 或 `ACCELERATE_URL` 是否正确
* 确认数据库服务是否运行
* 查看 [数据库文档](/apps/server#数据库)

---

---
url: /guide/conventions.md
---
# 开发规范

## 核心原则

* ⭐ **TDD 优先**：先写测试，再写代码
* 🎨 **UI 组件**：必须使用 shadcn/ui
* 📦 **包管理**：使用 pnpm workspace
* 🔒 **类型安全**：TypeScript 严格模式

## 后端开发规范

### 技术栈

* **Web 框架**: Hono（专为边缘环境优化）
* **运行时**: Cloudflare Workers
* **ORM**: Prisma 7（使用 Prisma Accelerate 或 Adapter）
* **验证**: Zod（schema 验证）
* **认证**: JWT + bcryptjs

### 目录结构

```
apps/server/src/
├── config/          # 配置模块
├── db/              # Prisma client
├── lib/             # 工具函数
├── middlewares/     # Hono 中间件
├── routes/v1/       # API 路由
├── services/        # 业务逻辑层
└── __tests__/       # 测试文件（与源码结构对应）
```

### 代码组织

* **分层**: Routes → Services → Database
* **路由层**: 只处理请求/响应，调用 Service
* **服务层**: 业务逻辑，不直接处理 HTTP

### API 设计

* RESTful，版本前缀 `/api/v1/`
* 统一响应格式：`success()` 包装器
* 错误处理：`AppError` + 统一错误中间件
* 类型安全：Hono RPC 客户端自动类型推断

## 前端开发规范

### 技术栈

* **UI 框架**: React 19 + Vite
* **路由**: React Router DOM v7
* **状态管理**: Zustand（全局）+ TanStack Query（服务端）
* **UI 组件**: shadcn/ui（必须使用，禁止其他 UI 库）
* **样式**: Tailwind CSS（布局优先，少用颜色类）
* **表单**: react-hook-form + zod

### 目录结构

```
apps/web/src/
├── components/      # React 组件（auth/, layouts/, ui/）
├── hooks/queries/   # React Query hooks
├── lib/             # 工具函数（api, api-error）
├── pages/           # 页面组件
├── routes/          # 路由配置
└── stores/          # Zustand stores
```

### UI 组件

* **必须使用 shadcn/ui**：`pnpm dlx shadcn@latest add [component-name]`
* 组件位置：`components/ui/`
* 禁止：Material-UI、Ant Design 等

### 路由守卫

* `ProtectedRoute`：保护需要登录的路由
* `PublicRoute`：已登录用户访问登录页时重定向

### API 调用

* 使用 Hono RPC 客户端（`hc`），自动类型推断
* 位置：`lib/api.ts`
* 自动添加 Authorization header
* API hooks：封装在 `hooks/queries/` 中

## 类型安全规范 ⚠️ 严格遵循

### TypeScript 严格模式

* **禁止使用 `any` 类型**：必须使用明确的类型定义
* 如果类型推断失败，应该：
  1. 检查类型定义是否正确
  2. 使用 `unknown` 进行类型守卫
  3. 定义明确的接口或类型别名
  4. 使用泛型提高类型复用性

### 类型定义原则

* 优先使用类型推断，减少显式类型注解
* 使用 `interface` 定义对象类型
* 使用 `type` 定义联合类型、工具类型等
* 避免使用类型断言（`as`），除非确实必要且类型安全

### 示例

```typescript
// ❌ 错误：使用 any
function process(data: any) { ... }

// ✅ 正确：使用明确的类型
function process<T>(data: T) { ... }
// 或
function process(data: unknown) {
  if (isValidData(data)) { ... }
}
```

## Git 提交规范

### 格式

`类型(模块): 描述`

**类型**: `feat` | `fix` | `docs` | `refactor` | `test` | `chore` | `perf` | `ci`

**模块**: `auth` | `user` | `api` | `ui` | `config` | `deploy` | `deps` | `init`

**示例**:

```bash
feat(auth): 添加用户登录功能
fix(api): 修复 CORS 错误
docs(readme): 更新部署文档
chore(deps): 更新依赖版本
test(auth): 添加登录测试用例
```

## 包管理规范

### 包管理器

* 使用 pnpm（workspace 模式）
* 安装：`pnpm add [package]` 或 `pnpm add -D [package]`
* 工作区：使用 `--filter` 指定工作区

### 禁止使用的包

* **UI 库**: Material-UI、Ant Design 等（使用 shadcn/ui）
* **CSS 框架**: Bootstrap、Bulma 等（使用 Tailwind）
* **状态管理**: Redux（使用 Zustand + TanStack Query）

## 注意事项

1. 不要提交敏感信息（环境变量、密钥）
2. 不要提交构建产物（`dist/`, `.wrangler/`）
3. 遵循 TDD 流程：先写测试，再写代码
4. 使用 shadcn/ui，不要使用其他 UI 库
5. 保持代码简洁，遵循单一职责原则
6. **严格类型安全**：禁止使用 `any`，必须使用明确的类型定义

---

---
url: /guide/getting-started.md
---
# 快速开始

本指南将帮助你快速启动 Fullstack Pack 项目。

## 前置要求

* Node.js >= 18.0.0
* pnpm >= 8.0.0
* PostgreSQL 数据库（或使用 Prisma Accelerate）

## 安装步骤

### 1. 克隆项目

```bash
git clone <repository-url>
cd fullstackpack
```

### 2. 安装依赖

```bash
pnpm install
```

### 3. 配置环境变量

复制 `.env.example` 到 `.env` 并填写配置：

```bash
cp .env.example .env
```

**必需配置：**

* `DATABASE_URL` - PostgreSQL 数据库连接字符串
* `JWT_SECRET` - JWT 密钥（至少 32 字符）

**可选配置：**

* `ACCELERATE_URL` - Prisma Accelerate URL（Cloudflare Workers 推荐）
* `CORS_ORIGIN` - CORS 允许的源
* `JWT_EXPIRES_IN` - JWT 过期时间（默认：7d）

### 4. 初始化数据库

```bash
# 推送 schema 到数据库
pnpm db:push

# 或使用 migrations（生产环境推荐）
cd apps/server
npx prisma migrate dev
```

### 5. 启动开发服务器

```bash
# 同时启动所有应用（推荐）
pnpm dev:all

# 单独启动
pnpm dev:server    # 后端：http://localhost:8787
pnpm dev:web       # Web 应用：http://localhost:8000
pnpm dev:auth-portal  # 认证门户：http://localhost:7777
pnpm docs:dev      # 文档站点：http://localhost:9000
```

## 验证安装

1. 访问 `http://localhost:8000` - 应该看到 Web 应用
2. 访问 `http://localhost:7777` - 应该看到认证门户
3. 访问 `http://localhost:9000` - 应该看到文档站点
4. 访问 `http://localhost:8787/api/v1/health` - 应该看到 API 响应

## 下一步

* [开发指南](/guide/development) - 了解开发流程
* [项目结构](/guide/structure) - 了解项目组织
* [开发规范](/guide/conventions) - 遵循开发规范

---

---
url: /README.md
---
# 文档站点

Fullstack Pack 项目文档站点，使用 VitePress 构建。

## 开发

```bash
pnpm dev
```

访问：http://localhost:9000

## 构建

```bash
pnpm build
```

构建产物在 `.vitepress/dist/` 目录。

## LLMs 文档

插件会自动生成 LLM 友好的文档文件：

* **llms.txt** - 文档索引（简洁版）
* **llms-full.txt** - 完整文档内容

### 访问地址

**开发环境：**

* `/llms.txt`
* `/llms-full.txt`

**生产环境：**

* `https://your-domain.com/llms.txt`
* `https://your-domain.com/llms-full.txt`

### 文件位置

构建后的文件位于：

* `.vitepress/dist/llms.txt`
* `.vitepress/dist/llms-full.txt`

## 环境变量

文档站点是静态站点，**无需配置环境变量**。

## 功能

* ✅ 本地搜索（VitePress 内置）
* ✅ LLMs 支持（vitepress-plugin-llms）
* ✅ 响应式设计
* ✅ 中文界面

---

---
url: /deployment/self-hosted.md
---
# 自托管部署

## 概述

自托管部署允许你在自有服务器上运行 Fullstack Pack，提供更多控制和灵活性。

## 架构说明

### 自托管部署

* **后端**: Node.js 服务器（使用 `@hono/node-server`）
* **前端**: 任何静态文件服务器（Nginx、Apache、Node.js 等）
* **数据库**: PostgreSQL（直接 TCP 连接）

## 部署步骤

### 1. 后端部署

#### 1.1 环境要求

* Node.js >= 18.0.0
* PostgreSQL 数据库
* pnpm >= 8.0.0

#### 1.2 安装依赖

```bash
cd apps/server
pnpm install
```

#### 1.3 配置环境变量

创建 `.env` 文件：

```bash
# 必需
DATABASE_URL=postgresql://user:password@localhost:5432/dbname
JWT_SECRET=your-secret-key-at-least-32-characters-long

# 可选
NODE_ENV=production
SERVER_PORT=3000
SERVER_HOST=0.0.0.0
JWT_EXPIRES_IN=7d
CORS_ORIGIN=https://your-frontend-domain.com
```

#### 1.4 数据库迁移

```bash
# 生成 Prisma Client
pnpm db:generate

# 推送数据库 schema（开发环境）
pnpm db:push

# 或使用 migrations（生产环境推荐）
npx prisma migrate deploy
```

#### 1.5 构建和启动

```bash
# 构建
pnpm build

# 启动（使用 Node.js）
pnpm start

# 或使用 PM2（推荐生产环境）
pm2 start dist/server.js --name fullstackpack-api
```

#### 1.6 使用 Docker（可选）

创建 `Dockerfile`：

```dockerfile
FROM node:20-alpine

WORKDIR /app

# 安装 pnpm
RUN npm install -g pnpm

# 复制依赖文件
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
COPY apps/server/package.json ./apps/server/
COPY packages/*/package.json ./packages/*/

# 安装依赖
RUN pnpm install --frozen-lockfile

# 复制源代码
COPY . .

# 构建
RUN pnpm --filter server build

WORKDIR /app/apps/server

# 暴露端口
EXPOSE 3000

# 启动
CMD ["node", "dist/server.js"]
```

构建和运行：

```bash
docker build -t fullstackpack-api .
docker run -p 3000:3000 --env-file .env fullstackpack-api
```

### 2. 前端部署

#### 2.1 构建前端应用

**Web 应用**：

```bash
cd apps/web
pnpm install
pnpm build
# 构建产物在 dist/ 目录
```

**认证门户**：

```bash
cd apps/auth-portal
pnpm install
pnpm build
# 构建产物在 dist/ 目录
```

#### 2.2 配置环境变量

在构建前设置环境变量：

```bash
# Web 应用
export VITE_API_URL=https://api.yourdomain.com
export VITE_AUTH_PORTAL_URL=https://auth.yourdomain.com

# 认证门户
export VITE_API_URL=https://api.yourdomain.com

pnpm build
```

或创建 `.env.production` 文件：

```bash
# apps/web/.env.production
VITE_API_URL=https://api.yourdomain.com
VITE_AUTH_PORTAL_URL=https://auth.yourdomain.com

# apps/auth-portal/.env.production
VITE_API_URL=https://api.yourdomain.com
```

#### 2.3 使用 Nginx 部署

**Nginx 配置示例**：

```nginx
# Web 应用
server {
    listen 80;
    server_name app.yourdomain.com;

    root /var/www/fullstackpack/web/dist;
    index index.html;

    # SPA 路由支持
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 静态资源缓存
    location /assets {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

# 认证门户
server {
    listen 80;
    server_name auth.yourdomain.com;

    root /var/www/fullstackpack/auth-portal/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /assets {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

# API 代理（可选，如果前端和后端在同一服务器）
server {
    listen 80;
    server_name api.yourdomain.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

#### 2.4 使用 Node.js 静态服务器（开发/测试）

```bash
# 安装 serve
npm install -g serve

# 启动 Web 应用
serve -s apps/web/dist -l 8000

# 启动认证门户
serve -s apps/auth-portal/dist -l 7777
```

### 3. 完整部署示例

#### 3.1 使用 Docker Compose

创建 `docker-compose.yml`：

```yaml
version: '3.8'

services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: fullstackpack
      POSTGRES_PASSWORD: your-password
      POSTGRES_DB: fullstackpack
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"

  api:
    build:
      context: .
      dockerfile: apps/server/Dockerfile
    environment:
      DATABASE_URL: postgresql://fullstackpack:your-password@postgres:5432/fullstackpack
      JWT_SECRET: your-secret-key-at-least-32-characters-long
      NODE_ENV: production
      SERVER_PORT: 3000
      SERVER_HOST: 0.0.0.0
    ports:
      - "3000:3000"
    depends_on:
      - postgres

  nginx:
    image: nginx:alpine
    volumes:
      - ./apps/web/dist:/usr/share/nginx/html/web:ro
      - ./apps/auth-portal/dist:/usr/share/nginx/html/auth:ro
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    ports:
      - "80:80"
      - "443:443"
    depends_on:
      - api

volumes:
  postgres_data:
```

#### 3.2 使用 PM2 部署

**ecosystem.config.js**：

```javascript
module.exports = {
  apps: [
    {
      name: 'fullstackpack-api',
      script: './apps/server/dist/server.js',
      cwd: '/path/to/fullstackpack',
      env: {
        NODE_ENV: 'production',
        DATABASE_URL: 'postgresql://...',
        JWT_SECRET: '...',
        SERVER_PORT: 3000,
        SERVER_HOST: '0.0.0.0',
      },
      instances: 'max',
      exec_mode: 'cluster',
    },
  ],
}
```

启动：

```bash
pm2 start ecosystem.config.js
pm2 save
pm2 startup
```

## 环境变量对比

### Cloudflare Workers（后端）

```bash
# 必需
ACCELERATE_URL=prisma://accelerate.prisma.io/?api_key=...
JWT_SECRET=...

# 可选
NODE_ENV=production
CORS_ORIGIN=https://your-frontend.com
JWT_EXPIRES_IN=7d
```

### 自托管 Node.js（后端）

```bash
# 必需
DATABASE_URL=postgresql://user:password@host:5432/dbname
JWT_SECRET=...

# 可选
NODE_ENV=production
SERVER_PORT=3000
SERVER_HOST=0.0.0.0
CORS_ORIGIN=https://your-frontend.com
JWT_EXPIRES_IN=7d
```

### 前端（两种方式相同）

```bash
VITE_API_URL=https://api.yourdomain.com
VITE_AUTH_PORTAL_URL=https://auth.yourdomain.com
```

## 数据库连接差异

### Cloudflare Workers

* **必须使用**: Prisma Accelerate（通过 HTTP API）
* **原因**: Workers 不支持 TCP 连接

### 自托管 Node.js

* **推荐使用**: DATABASE\_URL + Prisma Adapter（直接 TCP 连接）
* **也可以使用**: Prisma Accelerate（如果需要）

## 性能对比

| 特性 | Cloudflare Workers | 自托管 Node.js |
|------|-------------------|----------------|
| **延迟** | 边缘计算，全球低延迟 | 取决于服务器位置 |
| **扩展性** | 自动扩展 | 需要手动配置 |
| **成本** | 按请求计费 | 固定服务器成本 |
| **数据库连接** | 必须使用 Accelerate | 直接 TCP 连接 |
| **维护** | 无需维护 | 需要服务器维护 |

## 推荐方案

* **小型项目/原型**: Cloudflare 部署（简单、快速）
* **大型项目/企业**: 自托管（更多控制、成本可控）
* **混合方案**: 前端 Cloudflare Pages + 后端自托管

## 注意事项

1. **CORS 配置**: 确保后端 CORS 设置允许前端域名
2. **HTTPS**: 生产环境必须使用 HTTPS
3. **环境变量**: 不要在代码中硬编码敏感信息
4. **数据库迁移**: 生产环境使用 `prisma migrate deploy` 而不是 `db:push`
5. **日志**: 配置适当的日志收集和监控

---

---
url: /deployment.md
---
# 部署概述

Fullstack Pack 支持两种部署方式：

1. **Cloudflare 部署**（推荐）- 使用 Cloudflare Workers + Pages
2. **自托管部署** - 在自有服务器上运行

## 部署方式对比

| 特性 | Cloudflare | 自托管 |
|------|-----------|--------|
| **后端运行时** | Cloudflare Workers | Node.js |
| **数据库连接** | Prisma Accelerate（HTTP） | DATABASE\_URL（TCP） |
| **前端托管** | Cloudflare Pages | Nginx/Apache/Node.js |
| **扩展性** | 自动扩展 | 手动配置 |
| **成本** | 按请求计费 | 固定服务器成本 |
| **延迟** | 边缘计算，全球低延迟 | 取决于服务器位置 |

## 推荐方案

* **小型项目/原型**: Cloudflare 部署（简单、快速）
* **大型项目/企业**: 自托管（更多控制、成本可控）
* **混合方案**: 前端 Cloudflare Pages + 后端自托管

## 文档导航

* [Cloudflare 部署](/deployment/cloudflare) - Cloudflare Workers + Pages 部署指南
* [自托管部署](/deployment/self-hosted) - 自有服务器部署指南
* [CI/CD](/deployment/cicd) - 自动化部署配置

---

---
url: /guide/structure.md
---
# 项目结构

## Monorepo 结构

```
fullstackpack/
├── apps/
│   ├── web/              # Web 应用（React + Vite）
│   ├── auth-portal/      # 认证门户（统一登录入口）
│   ├── front-template/   # 前端应用模板
│   └── server/           # 后端服务（Hono + Cloudflare Workers）
├── packages/
│   ├── logger/           # 通用日志包
│   └── shared/           # 共享类型和 schemas
├── apps/docs/            # 文档站点（VitePress）
├── pnpm-workspace.yaml   # pnpm workspace 配置
└── package.json          # 根 package.json
```

## 应用结构

### Server (`apps/server`)

```
apps/server/
├── src/
│   ├── config/          # 配置模块
│   ├── db/              # Prisma client
│   ├── lib/             # 工具函数
│   ├── middlewares/     # Hono 中间件
│   ├── routes/v1/       # API 路由
│   ├── services/        # 业务逻辑层
│   └── __tests__/       # 测试文件
├── prisma/
│   └── schema.prisma    # 数据库 schema
└── wrangler.toml        # Cloudflare Workers 配置
```

### Web (`apps/web`)

```
apps/web/
├── src/
│   ├── components/      # React 组件
│   │   ├── auth/        # 认证相关组件
│   │   ├── layouts/     # 布局组件
│   │   └── ui/          # shadcn/ui 组件
│   ├── hooks/queries/   # React Query hooks
│   ├── lib/             # 工具函数
│   ├── pages/           # 页面组件
│   ├── routes/          # 路由配置
│   └── stores/          # Zustand stores
└── vite.config.ts       # Vite 配置
```

### Auth Portal (`apps/auth-portal`)

```
apps/auth-portal/
├── src/
│   ├── components/      # React 组件
│   ├── pages/           # 页面（主要是 Auth.tsx）
│   ├── routes/          # 路由配置
│   └── stores/          # 认证状态管理
└── vite.config.ts
```

## 包结构

### Shared (`packages/shared`)

```
packages/shared/
├── src/
│   ├── schemas/         # Zod schemas
│   ├── types/           # TypeScript 类型
│   ├── lib/             # 工具函数（如 auth 工具）
│   └── errors/          # 错误码定义
└── package.json
```

### Logger (`packages/logger`)

```
packages/logger/
├── src/
│   └── index.ts         # Logger 实现
└── package.json
```

## 代码组织原则

### 分层架构

* **Routes** → **Services** → **Database**
* 路由层：只处理请求/响应，调用 Service
* 服务层：业务逻辑，不直接处理 HTTP

### 共享代码

* 类型定义：`packages/shared`
* 工具函数：`packages/shared/lib`
* 日志工具：`packages/logger`

### 测试

* 测试文件与源码结构对应
* 使用 `__tests__` 目录
* 命名：`*.test.ts` 或 `*.spec.ts`