304 lines
6.0 KiB
Markdown
304 lines
6.0 KiB
Markdown
# 快速开始 - 卡密系统
|
||
|
||
## 前置要求
|
||
|
||
- Node.js 16+
|
||
- MySQL 5.7+
|
||
- 已配置好的数据库连接
|
||
|
||
## 安装步骤
|
||
|
||
### 1. 安装依赖
|
||
|
||
```bash
|
||
npm install
|
||
# 或
|
||
pnpm install
|
||
```
|
||
|
||
### 2. 启动项目
|
||
|
||
```bash
|
||
npm run start:dev
|
||
```
|
||
|
||
### 3. 访问 Swagger 文档
|
||
|
||
打开浏览器访问: http://localhost:3030/api
|
||
|
||
## 快速测试
|
||
|
||
### 方式一: 使用测试脚本
|
||
|
||
```bash
|
||
# 1. 运行测试脚本
|
||
bash test-license-system.sh
|
||
|
||
# 2. 按照提示输入卡密
|
||
```
|
||
|
||
### 方式二: 使用 Swagger UI
|
||
|
||
#### Step 1: 注册用户
|
||
|
||
1. 找到 `POST /user/register` 接口
|
||
2. 点击 "Try it out"
|
||
3. 输入用户信息:
|
||
```json
|
||
{
|
||
"username": "testuser",
|
||
"password": "password123",
|
||
"email": "test@example.com"
|
||
}
|
||
```
|
||
4. 点击 "Execute"
|
||
5. 复制返回的 `access_token`
|
||
|
||
#### Step 2: 生成卡密（需要管理员权限）
|
||
|
||
**临时方案 - 直接插入数据库:**
|
||
|
||
```sql
|
||
INSERT INTO `license` (`code`, `type`, `status`, `validDays`, `remarks`)
|
||
VALUES
|
||
('ABCD-1234-EFGH-5678', 'monthly', 'unused', 30, '测试卡密'),
|
||
('WXYZ-9876-IJKL-5432', 'yearly', 'unused', 365, '年度测试卡');
|
||
```
|
||
|
||
**或使用 API（需要管理员 Token）:**
|
||
|
||
1. 找到 `POST /license/generate` 接口
|
||
2. 点击右上角 "Authorize"，输入 access_token
|
||
3. 输入生成参数:
|
||
```json
|
||
{
|
||
"type": "monthly",
|
||
"validDays": 30,
|
||
"count": 1,
|
||
"remarks": "测试卡密"
|
||
}
|
||
```
|
||
4. 复制生成的卡密码
|
||
|
||
#### Step 3: 激活卡密
|
||
|
||
1. 找到 `POST /license/activate` 接口
|
||
2. 点击 "Authorize"，输入你的 access_token
|
||
3. 输入卡密:
|
||
```json
|
||
{
|
||
"code": "ABCD-1234-EFGH-5678"
|
||
}
|
||
```
|
||
4. 点击 "Execute"
|
||
5. 验证激活成功
|
||
|
||
#### Step 4: 查询授权状态
|
||
|
||
1. 找到 `GET /license/my` 接口
|
||
2. 点击 "Try it out"
|
||
3. 点击 "Execute"
|
||
4. 查看授权信息和剩余天数
|
||
|
||
#### Step 5: 测试任务功能
|
||
|
||
1. 找到 `POST /task` 接口
|
||
2. 输入任务信息:
|
||
```json
|
||
{
|
||
"title": "测试任务",
|
||
"description": "这是一个测试任务",
|
||
"priority": "high"
|
||
}
|
||
```
|
||
3. 点击 "Execute"
|
||
4. 应该创建成功（之前会返回 403）
|
||
|
||
## 常用 curl 命令
|
||
|
||
### 注册用户
|
||
```bash
|
||
curl -X POST http://localhost:3030/user/register \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"username": "testuser",
|
||
"password": "password123",
|
||
"email": "test@example.com"
|
||
}'
|
||
```
|
||
|
||
### 激活卡密
|
||
```bash
|
||
curl -X POST http://localhost:3030/license/activate \
|
||
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"code": "ABCD-1234-EFGH-5678"
|
||
}'
|
||
```
|
||
|
||
### 查询授权
|
||
```bash
|
||
curl -X GET http://localhost:3030/license/my \
|
||
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
|
||
```
|
||
|
||
### 创建任务（需要有效授权）
|
||
```bash
|
||
curl -X POST http://localhost:3030/task \
|
||
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"title": "完成项目文档",
|
||
"priority": "high"
|
||
}'
|
||
```
|
||
|
||
## 验证授权保护
|
||
|
||
### 测试未授权访问（应该返回 403）
|
||
|
||
```bash
|
||
# 使用未激活卡密的用户 Token
|
||
curl -X GET http://localhost:3030/task \
|
||
-H "Authorization: Bearer UNAUTHORIZED_TOKEN"
|
||
|
||
# 预期响应:
|
||
# {
|
||
# "statusCode": 403,
|
||
# "message": "您的授权已过期或未激活，请联系管理员获取卡密",
|
||
# "error": "Forbidden"
|
||
# }
|
||
```
|
||
|
||
### 测试授权后访问（应该成功）
|
||
|
||
```bash
|
||
# 使用已激活卡密的用户 Token
|
||
curl -X GET http://localhost:3030/task \
|
||
-H "Authorization: Bearer AUTHORIZED_TOKEN"
|
||
|
||
# 预期响应: 任务列表数组
|
||
```
|
||
|
||
## 管理员操作
|
||
|
||
### 生成批量卡密
|
||
|
||
```bash
|
||
curl -X POST http://localhost:3030/license/generate \
|
||
-H "Authorization: Bearer ADMIN_TOKEN" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"type": "monthly",
|
||
"validDays": 30,
|
||
"count": 10,
|
||
"remarks": "批量生成月卡"
|
||
}'
|
||
```
|
||
|
||
### 查看统计信息
|
||
|
||
```bash
|
||
curl -X GET http://localhost:3030/license/statistics \
|
||
-H "Authorization: Bearer ADMIN_TOKEN"
|
||
```
|
||
|
||
### 查询所有卡密
|
||
|
||
```bash
|
||
# 查询所有未使用的月卡
|
||
curl -X GET "http://localhost:3030/license?status=unused&type=monthly" \
|
||
-H "Authorization: Bearer ADMIN_TOKEN"
|
||
```
|
||
|
||
### 撤销卡密
|
||
|
||
```bash
|
||
curl -X POST http://localhost:3030/license/1/revoke \
|
||
-H "Authorization: Bearer ADMIN_TOKEN"
|
||
```
|
||
|
||
## 数据库快速查看
|
||
|
||
### 查看所有卡密
|
||
|
||
```sql
|
||
SELECT
|
||
id, code, type, status, validDays,
|
||
activatedAt, expiresAt, userId, remarks
|
||
FROM license
|
||
ORDER BY createdAt DESC;
|
||
```
|
||
|
||
### 查看有效授权
|
||
|
||
```sql
|
||
SELECT
|
||
l.code, l.type, l.status,
|
||
u.username, u.email,
|
||
l.activatedAt, l.expiresAt,
|
||
DATEDIFF(l.expiresAt, NOW()) as remainingDays
|
||
FROM license l
|
||
LEFT JOIN user u ON l.userId = u.id
|
||
WHERE l.status = 'active' AND l.expiresAt > NOW()
|
||
ORDER BY l.expiresAt;
|
||
```
|
||
|
||
### 查看即将过期的授权（7天内）
|
||
|
||
```sql
|
||
SELECT
|
||
l.code, u.username, u.email,
|
||
l.expiresAt,
|
||
DATEDIFF(l.expiresAt, NOW()) as remainingDays
|
||
FROM license l
|
||
LEFT JOIN user u ON l.userId = u.id
|
||
WHERE
|
||
l.status = 'active'
|
||
AND l.expiresAt > NOW()
|
||
AND l.expiresAt < DATE_ADD(NOW(), INTERVAL 7 DAY)
|
||
ORDER BY l.expiresAt;
|
||
```
|
||
|
||
## 故障排查
|
||
|
||
### 问题: 激活卡密时返回 403
|
||
**原因**: 未登录或 Token 过期
|
||
**解决**: 重新登录获取新的 access_token
|
||
|
||
### 问题: 激活卡密时返回 409
|
||
**原因**: 卡密已被激活
|
||
**解决**: 使用其他未激活的卡密
|
||
|
||
### 问题: 任务接口返回 403
|
||
**原因**: 授权已过期或未激活
|
||
**解决**: 激活新的卡密或检查授权状态
|
||
|
||
### 问题: 生成卡密返回 401
|
||
**原因**: 需要管理员权限
|
||
**解决**: 使用管理员账号或临时从数据库插入
|
||
|
||
## 下一步
|
||
|
||
1. 根据实际业务需求调整卡密类型和有效期
|
||
2. 实现管理员权限验证机制
|
||
3. 添加前端授权管理页面
|
||
4. 配置授权即将过期的邮件提醒
|
||
5. 实现授权使用统计和分析
|
||
|
||
## 相关文档
|
||
|
||
- [LICENSE_SYSTEM.md](LICENSE_SYSTEM.md) - 详细功能说明
|
||
- [LICENSE_IMPLEMENTATION.md](LICENSE_IMPLEMENTATION.md) - 实现总结
|
||
- [Swagger API](http://localhost:3030/api) - 在线 API 文档
|
||
|
||
## 技术支持
|
||
|
||
如有问题，请查看:
|
||
1. Swagger 文档中的接口说明
|
||
2. LICENSE_SYSTEM.md 中的详细文档
|
||
3. 数据库中的卡密状态
|
||
|
||
祝使用愉快！
|