# 快速开始 - 卡密系统

## 前置要求

- 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. 数据库中的卡密状态

祝使用愉快！