220 lines
5.9 KiB
Markdown
220 lines
5.9 KiB
Markdown
# 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` 等
|