# Pandora 后端 API

这是 Pandora 项目的后端 API 服务，提供完整的用户认证系统和权限管理功能。

## 🚀 功能特性

### 用户认证系统
- ✅ 用户注册和登录
- ✅ JWT 令牌认证
- ✅ 邮箱验证
- ✅ 密码重置
- ✅ TOTP 二步验证
- ✅ 会话管理
- ✅ 密码加密 (bcrypt)

### 权限管理系统
- ✅ 基于角色的权限控制
- ✅ 路径权限验证
- ✅ 用户权限分配
- ✅ 权限审计日志

### 账号管理系统
- ✅ 网站账号管理
- ✅ 账号分配和撤销
- ✅ 账号使用统计
- ✅ 多用户共享控制

### 安全特性
- ✅ API 限流
- ✅ CORS 配置
- ✅ 安全头部 (Helmet)
- ✅ 输入验证
- ✅ 错误处理
- ✅ 审计日志

## 📋 技术栈

- **运行时**: Node.js + TypeScript
- **框架**: Express.js
- **数据库**: PostgreSQL + Prisma ORM
- **缓存**: Redis
- **认证**: JWT + bcrypt
- **二步验证**: TOTP (Google Authenticator)
- **邮件**: Nodemailer
- **日志**: Winston
- **验证**: express-validator

## 🛠️ 安装和设置

### 1. 安装依赖

```bash
cd backend
npm install
```

### 2. 环境配置

复制环境变量文件：

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

编辑 `.env` 文件，配置以下变量：

```env
# 数据库配置
DATABASE_URL="postgresql://username:password@localhost:5432/pandora"

# JWT 配置
JWT_SECRET="your-super-secret-jwt-key-here"
JWT_EXPIRES_IN="7d"

# 邮件配置 (用于邮箱验证和密码重置)
SMTP_HOST="smtp.gmail.com"
SMTP_PORT=587
SMTP_USER="your-email@gmail.com"
SMTP_PASS="your-app-password"
EMAIL_FROM="noreply@pandora.com"

# Redis 配置
REDIS_URL="redis://localhost:6379"

# 服务器配置
PORT=3001
NODE_ENV="development"

# 安全配置
BCRYPT_ROUNDS=12
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX_REQUESTS=100

# TOTP 配置
TOTP_ISSUER="Pandora"
TOTP_LABEL="Pandora Authentication"
```

### 3. 数据库设置

```bash
# 生成 Prisma 客户端
npm run db:generate

# 运行数据库迁移
npm run db:migrate

# 初始化测试数据
npm run db:seed
```

### 4. 启动服务

```bash
# 开发模式
npm run dev

# 生产模式
npm run build
npm start
```

## 📚 API 文档

### 认证相关 API

#### 用户注册
```http
POST /api/auth/register
Content-Type: application/json

{
  "email": "user@example.com",
  "username": "username",
  "password": "password123",
  "firstName": "张",
  "lastName": "三"
}
```

#### 用户登录
```http
POST /api/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password123"
}
```

#### 邮箱验证
```http
POST /api/auth/verify-email
Content-Type: application/json

{
  "token": "verification-token"
}
```

#### 设置 TOTP
```http
POST /api/auth/setup-totp
Authorization: Bearer <token>
```

#### 验证 TOTP
```http
POST /api/auth/verify-totp
Authorization: Bearer <token>
Content-Type: application/json

{
  "token": "123456"
}
```

#### 获取当前用户信息
```http
GET /api/auth/me
Authorization: Bearer <token>
```

### 用户管理 API

#### 获取所有用户 (管理员)
```http
GET /api/users
Authorization: Bearer <admin-token>
```

#### 获取用户详情
```http
GET /api/users/:id
Authorization: Bearer <token>
```

#### 更新用户信息
```http
PUT /api/users/:id
Authorization: Bearer <token>
Content-Type: application/json

{
  "firstName": "新名字",
  "lastName": "新姓氏"
}
```

### 账号管理 API

#### 获取用户账号
```http
GET /api/accounts/user/assigned
Authorization: Bearer <token>
```

#### 创建账号 (管理员)
```http
POST /api/accounts
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "website": "claude.ai",
  "accountName": "claude_pro_1",
  "token": "sk-ant-api03-xxx",
  "maxUsers": 3
}
```

## 🔐 安全说明

### 密码安全
- 使用 bcrypt 进行密码哈希，默认 12 轮加密
- 密码最小长度 8 位
- 支持密码重置功能

### 会话管理
- JWT 令牌有效期 7 天
- 支持令牌刷新
- 会话存储在数据库中，支持强制登出

### 二步验证
- 支持 TOTP (Google Authenticator)
- 提供 10 个备用码
- 可选择性启用

### API 安全
- 所有敏感 API 需要认证
- 管理员 API 需要管理员权限
- 实现 API 限流防止滥用
- 输入验证和清理

## 🧪 测试账户

运行 `npm run db:seed` 后会创建以下测试账户：

### 管理员账户
- 邮箱: `admin@pandora.com`
- 密码: `admin123`
- 权限: 所有账号

### 测试用户账户
- 邮箱: `user@pandora.com`
- 密码: `user123`
- 权限: claude.ai 和 openai.com 账号

## 📝 开发说明

### 项目结构
```
src/
├── config/          # 配置文件
│   ├── database.ts  # 数据库连接
│   └── redis.ts     # Redis 连接
├── controllers/     # 控制器
│   ├── authController.ts
│   ├── userController.ts
│   └── accountController.ts
├── middleware/      # 中间件
│   ├── authMiddleware.ts
│   ├── adminMiddleware.ts
│   ├── validateRequest.ts
│   ├── errorHandler.ts
│   └── notFoundHandler.ts
├── routes/          # 路由
│   ├── auth.ts
│   ├── users.ts
│   └── accounts.ts
├── utils/           # 工具函数
│   └── logger.ts
└── index.ts         # 入口文件
```

### 数据库模型
- `User`: 用户信息
- `WebsiteAccount`: 网站账号
- `AccountAssignment`: 账号分配
- `Session`: 用户会话
- `AuditLog`: 审计日志

### 开发命令
```bash
# 开发模式
npm run dev

# 构建
npm run build

# 数据库操作
npm run db:generate    # 生成 Prisma 客户端
npm run db:migrate     # 运行迁移
npm run db:push        # 推送 schema 到数据库
npm run db:studio      # 打开 Prisma Studio
npm run db:seed        # 初始化测试数据
```

## 🚨 注意事项

1. **环境变量**: 确保所有必需的环境变量都已正确配置
2. **数据库**: 确保 PostgreSQL 数据库正在运行
3. **Redis**: 确保 Redis 服务正在运行
4. **邮件服务**: 如果使用邮箱验证功能，需要配置有效的 SMTP 服务
5. **JWT 密钥**: 生产环境请使用强随机密钥
6. **HTTPS**: 生产环境建议使用 HTTPS

## 📞 支持

如有问题，请查看：
1. 日志文件 (`logs/` 目录)
2. 数据库连接状态
3. Redis 连接状态
4. 环境变量配置

## 🔄 更新日志

### v1.0.0
- ✅ 完整的用户认证系统
- ✅ JWT 令牌认证
- ✅ 邮箱验证功能
- ✅ TOTP 二步验证
- ✅ 权限管理系统
- ✅ 账号管理系统
- ✅ 审计日志
- ✅ API 限流和安全防护