oauth_nest_demo/QUICKSTART.md

快速开始 - 卡密系统

前置要求

• Node.js 16+
• MySQL 5.7+
• 已配置好的数据库连接

安装步骤

1. 安装依赖

npm install
# 或
pnpm install

2. 启动项目

npm run start:dev

3. 访问 Swagger 文档

打开浏览器访问: http://localhost:3030/api

快速测试

方式一: 使用测试脚本

# 1. 运行测试脚本
bash test-license-system.sh

# 2. 按照提示输入卡密

方式二: 使用 Swagger UI

Step 1: 注册用户

1. 找到 POST /user/register 接口
2. 点击 "Try it out"
3. 输入用户信息:

{
  "username": "testuser",
  "password": "password123",
  "email": "test@example.com"
}

4. 点击 "Execute"
5. 复制返回的 access_token

Step 2: 生成卡密（需要管理员权限）

临时方案 - 直接插入数据库:

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. 输入生成参数:

{
  "type": "monthly",
  "validDays": 30,
  "count": 1,
  "remarks": "测试卡密"
}

4. 复制生成的卡密码

Step 3: 激活卡密

1. 找到 POST /license/activate 接口
2. 点击 "Authorize"，输入你的 access_token
3. 输入卡密:

{
  "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. 输入任务信息:

{
  "title": "测试任务",
  "description": "这是一个测试任务",
  "priority": "high"
}

3. 点击 "Execute"
4. 应该创建成功（之前会返回 403）

常用 curl 命令

注册用户

curl -X POST http://localhost:3030/user/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "password": "password123",
    "email": "test@example.com"
  }'

激活卡密

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"
  }'

查询授权

curl -X GET http://localhost:3030/license/my \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

创建任务（需要有效授权）

curl -X POST http://localhost:3030/task \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "完成项目文档",
    "priority": "high"
  }'

验证授权保护

测试未授权访问（应该返回 403）

# 使用未激活卡密的用户 Token
curl -X GET http://localhost:3030/task \
  -H "Authorization: Bearer UNAUTHORIZED_TOKEN"

# 预期响应:
# {
#   "statusCode": 403,
#   "message": "您的授权已过期或未激活，请联系管理员获取卡密",
#   "error": "Forbidden"
# }

测试授权后访问（应该成功）

# 使用已激活卡密的用户 Token
curl -X GET http://localhost:3030/task \
  -H "Authorization: Bearer AUTHORIZED_TOKEN"

# 预期响应: 任务列表数组

管理员操作

生成批量卡密

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": "批量生成月卡"
  }'

查看统计信息

curl -X GET http://localhost:3030/license/statistics \
  -H "Authorization: Bearer ADMIN_TOKEN"

查询所有卡密

# 查询所有未使用的月卡
curl -X GET "http://localhost:3030/license?status=unused&type=monthly" \
  -H "Authorization: Bearer ADMIN_TOKEN"

撤销卡密

curl -X POST http://localhost:3030/license/1/revoke \
  -H "Authorization: Bearer ADMIN_TOKEN"

数据库快速查看

查看所有卡密

SELECT
  id, code, type, status, validDays,
  activatedAt, expiresAt, userId, remarks
FROM license
ORDER BY createdAt DESC;

查看有效授权

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天内）

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_IMPLEMENTATION.md - 实现总结
• Swagger API - 在线 API 文档

技术支持

如有问题，请查看:

1. Swagger 文档中的接口说明
2. LICENSE_SYSTEM.md 中的详细文档
3. 数据库中的卡密状态

祝使用愉快！