oauth_nest_demo/GENERATE_LICENSE_GUIDE.md

# 生成卡密操作指南

## 概述

现在系统已经实现了完整的管理员权限验证。管理员可以通过 API 生成卡密，普通用户无法访问生成接口。

## 管理员权限规则

系统会自动识别以下用户为管理员：
1. 用户名为 `admin`
2. 邮箱包含 `admin`（如 `admin@example.com`）
3. 用户名以 `admin_` 开头（如 `admin_user`）

## 方法一：注册管理员账号（推荐）

### 步骤 1: 注册管理员账号

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

**响应示例：**
```json
{
  "message": "User registered successfully",
  "user": {
    "id": 1,
    "username": "admin",
    "email": "admin@example.com",
    "isActive": true,
    "provider": "local"
  },
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

**保存 `access_token`，后续生成卡密时需要使用！**

### 步骤 2: 使用管理员账号生成卡密

#### 生成单个月卡

```bash
curl -X POST http://localhost:3030/license/generate \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "monthly",
    "validDays": 30,
    "count": 1,
    "remarks": "测试月卡"
  }'
```

#### 批量生成卡密

```bash
# 生成 10 个月卡
curl -X POST http://localhost:3030/license/generate \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "monthly",
    "validDays": 30,
    "count": 10,
    "remarks": "批量生成月卡"
  }'
```

#### 生成不同类型的卡密

```bash
# 试用卡 (7天)
curl -X POST http://localhost:3030/license/generate \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "trial",
    "validDays": 7,
    "count": 5,
    "remarks": "试用卡"
  }'

# 年卡 (365天)
curl -X POST http://localhost:3030/license/generate \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "yearly",
    "validDays": 365,
    "count": 2,
    "remarks": "年度授权"
  }'

# 终身卡
curl -X POST http://localhost:3030/license/generate \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "lifetime",
    "validDays": 36500,
    "count": 1,
    "remarks": "VIP终身授权"
  }'
```

**响应示例：**
```json
[
  {
    "id": 1,
    "code": "ABCD-1234-EFGH-5678",
    "type": "monthly",
    "status": "unused",
    "validDays": 30,
    "remarks": "测试月卡",
    "createdAt": "2025-12-13T10:00:00.000Z"
  }
]
```

### 步骤 3: 将卡密分发给用户

将生成的 `code` 发送给用户，用户可以使用以下方式激活：

```bash
curl -X POST http://localhost:3030/license/activate \
  -H "Authorization: Bearer USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "ABCD-1234-EFGH-5678"
  }'
```

## 方法二：使用 Swagger UI

### 步骤 1: 访问 Swagger

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

### 步骤 2: 注册管理员账号

1. 找到 `POST /user/register` 接口
2. 点击 "Try it out"
3. 输入管理员信息：
   ```json
   {
     "username": "admin",
     "password": "admin123",
     "email": "admin@example.com"
   }
   ```
4. 点击 "Execute"
5. 复制响应中的 `access_token`

### 步骤 3: 授权 Swagger

1. 点击页面右上角的 "Authorize" 按钮
2. 在弹出框中输入：`Bearer YOUR_ACCESS_TOKEN`
3. 点击 "Authorize"
4. 点击 "Close"

### 步骤 4: 生成卡密

1. 找到 `POST /license/generate` 接口
2. 点击 "Try it out"
3. 输入生成参数：
   ```json
   {
     "type": "monthly",
     "validDays": 30,
     "count": 1,
     "remarks": "测试卡密"
   }
   ```
4. 点击 "Execute"
5. 在响应中复制生成的卡密码

### 步骤 5: 查看已生成的卡密

1. 找到 `GET /license` 接口
2. 点击 "Try it out"
3. 可选：筛选条件
   - status: unused (查看未使用的)
   - type: monthly (查看月卡)
4. 点击 "Execute"
5. 查看所有卡密列表

## 方法三：直接插入数据库（临时方案）

如果还没有管理员账号，可以直接在数据库中插入卡密：

```sql
-- 插入测试卡密
INSERT INTO `license` (
  `code`,
  `type`,
  `status`,
  `validDays`,
  `remarks`,
  `createdAt`,
  `updatedAt`
) VALUES
  ('ABCD-1234-EFGH-5678', 'monthly', 'unused', 30, '测试月卡', NOW(), NOW()),
  ('WXYZ-9876-IJKL-5432', 'yearly', 'unused', 365, '测试年卡', NOW(), NOW()),
  ('TEST-0000-FREE-TRIAL', 'trial', 'unused', 7, '试用卡', NOW(), NOW());
```

**注意：** 卡密格式必须是 `XXXX-XXXX-XXXX-XXXX`（19个字符，包含3个连字符）

## 管理员其他操作

### 查看卡密统计

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

**响应示例：**
```json
{
  "total": 100,
  "unused": 50,
  "active": 30,
  "expired": 15,
  "revoked": 5
}
```

### 查询所有卡密

```bash
# 查询所有卡密
curl -X GET http://localhost:3030/license \
  -H "Authorization: Bearer ADMIN_TOKEN"

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

# 查询已激活的月卡
curl -X GET "http://localhost:3030/license?status=active&type=monthly" \
  -H "Authorization: Bearer ADMIN_TOKEN"
```

### 查询单个卡密详情

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

### 撤销卡密

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

### 删除卡密

```bash
curl -X DELETE http://localhost:3030/license/1 \
  -H "Authorization: Bearer ADMIN_TOKEN"
```

## 常见问题

### Q: 非管理员用户能生成卡密吗？
A: 不能。系统会返回 403 错误：
```json
{
  "statusCode": 403,
  "message": "需要管理员权限",
  "error": "Forbidden"
}
```

### Q: 如何修改管理员权限规则？
A: 编辑 [src/common/services/admin.service.ts](src/common/services/admin.service.ts:23-30)，修改 `isAdmin` 方法中的判断逻辑。

### Q: 可以有多个管理员吗？
A: 可以。所有满足管理员规则的用户都拥有管理员权限。

### Q: 生成的卡密可以重复使用吗？
A: 不可以。每个卡密只能激活一次，激活后状态变为 `active`。

### Q: 如何批量生成大量卡密？
A: 使用 `count` 参数，建议每次不超过 100 个：
```json
{
  "type": "monthly",
  "count": 100
}
```

## 完整示例流程

### 场景：销售100个月卡

```bash
# 1. 使用管理员账号登录
curl -X POST http://localhost:3030/user/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "admin123"
  }'
# 获取 access_token

# 2. 批量生成 100 个月卡
curl -X POST http://localhost:3030/license/generate \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "monthly",
    "validDays": 30,
    "count": 100,
    "remarks": "2025年1月批次"
  }'

# 3. 查询已生成的卡密
curl -X GET "http://localhost:3030/license?status=unused&type=monthly" \
  -H "Authorization: Bearer ADMIN_TOKEN"

# 4. 导出卡密（可以通过数据库查询或API获取）
# SQL 查询未使用的卡密
# SELECT code FROM license WHERE status = 'unused' AND type = 'monthly'

# 5. 将卡密分发给客户

# 6. 监控卡密使用情况
curl -X GET http://localhost:3030/license/statistics \
  -H "Authorization: Bearer ADMIN_TOKEN"
```

## 数据库直接查询卡密

### 查询所有未使用的卡密

```sql
SELECT
  id, code, type, validDays, remarks, createdAt
FROM license
WHERE status = 'unused'
ORDER BY createdAt DESC;
```

### 导出卡密列表（用于分发）

```sql
SELECT
  code as '卡密码',
  CASE type
    WHEN 'trial' THEN '试用版'
    WHEN 'monthly' THEN '月卡'
    WHEN 'yearly' THEN '年卡'
    WHEN 'lifetime' THEN '终身版'
  END as '类型',
  validDays as '有效天数',
  remarks as '备注'
FROM license
WHERE status = 'unused'
ORDER BY type, createdAt DESC;
```

### 统计卡密使用情况

```sql
SELECT
  type as '类型',
  COUNT(*) as '总数',
  SUM(CASE WHEN status = 'unused' THEN 1 ELSE 0 END) as '未使用',
  SUM(CASE WHEN status = 'active' THEN 1 ELSE 0 END) as '已激活',
  SUM(CASE WHEN status = 'expired' THEN 1 ELSE 0 END) as '已过期',
  SUM(CASE WHEN status = 'revoked' THEN 1 ELSE 0 END) as '已撤销'
FROM license
GROUP BY type;
```

## 安全建议

1. **保护管理员账号**
   - 使用强密码
   - 定期更换密码
   - 不要分享管理员凭证

2. **卡密分发**
   - 通过安全渠道发送（邮件、加密通讯）
   - 记录卡密分发情况
   - 及时撤销未使用的卡密

3. **监控使用**
   - 定期查看统计信息
   - 检查异常激活
   - 审计管理员操作日志

## 下一步

完成卡密生成后，可以：
1. 将卡密分发给用户
2. 用户使用 `POST /license/activate` 激活
3. 激活后用户可以使用任务功能
4. 管理员可以通过统计接口监控使用情况

## 相关文档

- [LICENSE_SYSTEM.md](LICENSE_SYSTEM.md) - 卡密系统详细说明
- [QUICKSTART.md](QUICKSTART.md) - 快速开始指南
- [Swagger API](http://localhost:3030/api) - 在线 API 文档