crush-level-web/README.md

# Crushlevel Next.js Application

这是一个基于 Next.js 的现代化Web应用，支持多种社交登录方式。

## 功能特性

- 🎮 **多平台社交登录**: 支持Discord、Google、Apple登录
- 🔐 **完整认证流程**: OAuth2.0认证，JWT token管理
- 📱 **设备管理**: 自动设备ID生成和管理
- 🎭 **开发环境Mock**: 使用MSW进行API模拟
- 🛡️ **中间件保护**: 路由级别的认证保护

## 快速开始

### 1. 安装依赖

```bash
npm install
```

### 2. 环境变量配置

复制 `.env.local.example` 文件为 `.env.local` 并配置相应的环境变量：

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

#### Discord OAuth 配置

要启用Discord登录，你需要在Discord开发者平台创建应用：

1. 访问 [Discord Developer Portal](https://discord.com/developers/applications)
2. 点击 "New Application" 创建新应用
3. 在应用设置页面：
   - 复制 **Application ID** 作为 `NEXT_PUBLIC_DISCORD_CLIENT_ID`
   - 在 "OAuth2" 标签页生成 **Client Secret** 作为 `DISCORD_CLIENT_SECRET`
   - 添加回调URL: `http://localhost:3000/api/auth/discord/callback` （开发环境）
   - 选择 scopes: `identify`, `email`

```env
# Discord OAuth 配置
NEXT_PUBLIC_DISCORD_CLIENT_ID=your_discord_client_id_here
DISCORD_CLIENT_SECRET=your_discord_client_secret_here

# 应用URL（生产环境需要修改）
NEXT_PUBLIC_APP_URL=http://localhost:3000

# 开发环境Mock配置
NEXT_PUBLIC_ENABLE_MOCK=true
```

#### 其他OAuth配置（可选）

```env
# Google OAuth（未来支持）
NEXT_PUBLIC_GOOGLE_CLIENT_ID=your_google_client_id_here
GOOGLE_CLIENT_SECRET=your_google_client_secret_here

# Apple OAuth（未来支持）
NEXT_PUBLIC_APPLE_CLIENT_ID=your_apple_client_id_here
APPLE_CLIENT_SECRET=your_apple_client_secret_here
```

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

```bash
npm run dev
```

应用将在 http://localhost:3000 启动。

## Discord登录流程

### 1. 用户点击Discord登录按钮

- 系统生成随机state参数用于安全验证
- 跳转到Discord授权页面

### 2. Discord授权

用户在Discord页面授权后，Discord重定向到回调URL并携带授权码

### 3. 回调处理

- API路由 `/api/auth/discord/callback` 接收授权码
- 将授权码作为URL参数重定向到前端登录页面

### 4. 前端登录处理

- 前端登录页面检测到URL中的`discord_code`参数
- 使用授权码调用后端API: `POST /web/third/login`
- 后端验证授权码并返回认证token

### 5. 登录完成

- 前端保存token并重定向到首页
- 完成整个登录流程

## 开发环境Mock

项目使用MSW进行API模拟，在开发环境中：

- 设置 `NEXT_PUBLIC_ENABLE_MOCK=true` 启用Mock
- 所有认证API请求都会被MSW拦截并返回模拟数据
- 支持Discord、Google、Apple等第三方登录的模拟

### Mock功能特性

- ✅ 设备ID验证
- ✅ 第三方登录模拟
- ✅ Token管理
- ✅ 用户信息管理
- ✅ 错误场景模拟

## 项目结构

```
src/
├── app/                    # Next.js App Router
│   ├── (auth)/            # 认证相关页面
│   ├── (main)/            # 主应用页面
│   └── api/               # API路由
├── components/            # 可复用组件
├── lib/                   # 工具库
│   ├── auth/             # 认证管理
│   ├── http/             # HTTP客户端
│   └── oauth/            # OAuth服务
├── services/             # 业务服务
├── mocks/               # MSW Mock配置
└── types/               # TypeScript类型定义
```

## API文档

### 认证相关API

#### 第三方登录

```
POST /web/third/login
Content-Type: application/json

{
  "appClient": "WEB",
  "deviceCode": "设备唯一码",
  "thirdToken": "第三方授权码",
  "thirdType": "DISCORD" | "GOOGLE" | "APPLE"
}
```

#### 获取用户信息

```
GET /web/user/base-info
Headers:
  AUTH_TK: "认证token"
  AUTH_DID: "设备ID"
```

#### 登出

```
POST /web/user/logout
Headers:
  AUTH_TK: "认证token"
  AUTH_DID: "设备ID"
```

## 贡献指南

1. Fork本项目
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送分支 (`git push origin feature/AmazingFeature`)
5. 创建Pull Request

## 许可证

本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。

## 文案清单导出（一次性盘点）

为便于产品/运营统一校对当前所有展示文案，项目提供静态扫描脚本，自动抽取源码中的用户可见与可感知文案并导出为 Excel。

### 覆盖范围

- JSX 文本节点与按钮/链接文案
- 属性文案：`placeholder` / `title` / `alt` / `aria-*` / `label`
- 交互文案：`toast.*` / `message.*` / `alert` / `confirm` / `Dialog`/`Tooltip` 等常见调用
- 表单校验与错误提示：`form.setError(..., { message })`、校验链条中的 `{ message: '...' }`

### 运行

```bash
# 生成 docs/copy-audit.xlsx
npx ts-node scripts/extract-copy.ts   # 若 ESM 运行报错，请改用下行
node scripts/extract-copy.cjs
```

输出文件：`docs/copy-audit.xlsx`

### Excel 字段说明（Sheet: copy）

- `route`: Next.js App Router 路由（如 `(main)/home`）或 `shared`
- `file`: 文案所在文件（相对仓库根路径）
- `componentOrFn`: 组件或函数名（无法解析时为文件名）
- `kind`: 文案类型（`text` | `placeholder` | `title` | `alt` | `aria` | `label` | `toast` | `dialog` | `error` | `validation`）
- `keyOrLocator`: 定位信息（如 `Button.placeholder`、`toast.success`）
- `text`: 实际文案内容
- `line`: 文案起始行号（近似定位）
- `count`: 在同一路由下相同文案出现次数（已聚合）
- `notes`: 预留备注

### 说明与边界

- 仅提取可静态分析到的硬编码字符串；运行时拼接（仅变量）无法还原将被忽略
- 会过滤明显的“代码样”字符串（如过长的标识符）
- 扫描目录为 `src/`，忽略 `node_modules/.next/__tests__/mocks` 等