oauth_nest_demo/LICENSE_SYSTEM.md

# 卡密系统使用说明

## 概述

本项目实现了完整的卡密商业化授权系统，用户需要激活有效的卡密才能使用任务管理（Task）模块的功能。

## 功能特性

### 1. 卡密类型

- **试用版 (trial)**: 7天有效期
- **月度订阅 (monthly)**: 30天有效期
- **年度订阅 (yearly)**: 365天有效期
- **终身授权 (lifetime)**: 100年有效期

### 2. 卡密状态

- **未使用 (unused)**: 卡密已生成但未被激活
- **已激活 (active)**: 卡密正在使用中
- **已过期 (expired)**: 卡密有效期已过
- **已撤销 (revoked)**: 卡密被管理员撤销

### 3. 卡密格式

卡密采用 `XXXX-XXXX-XXXX-XXXX` 格式，例如：`ABCD-1234-EFGH-5678`

## API 接口

### 用户接口

#### 1. 激活卡密
```http
POST /license/activate
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "code": "ABCD-1234-EFGH-5678"
}
```

**响应示例：**
```json
{
  "message": "卡密激活成功，有效期至 2026-01-13 10:00:00",
  "license": {
    "id": 1,
    "code": "ABCD-1234-EFGH-5678",
    "type": "monthly",
    "status": "active",
    "validDays": 30,
    "activatedAt": "2025-12-13T10:00:00.000Z",
    "expiresAt": "2026-01-13T10:00:00.000Z",
    "userId": 1
  }
}
```

**特殊说明：**
- 如果用户已有有效授权，新卡密的时间会在原有基础上累加延期
- 已激活、已过期或已撤销的卡密无法重复使用

#### 2. 查询我的授权信息
```http
GET /license/my
Authorization: Bearer {access_token}
```

**响应示例：**
```json
{
  "hasValidLicense": true,
  "license": {
    "id": 1,
    "code": "ABCD-1234-EFGH-5678",
    "type": "monthly",
    "status": "active",
    "validDays": 30,
    "activatedAt": "2025-12-13T10:00:00.000Z",
    "expiresAt": "2026-01-13T10:00:00.000Z",
    "remainingDays": 31
  }
}
```

#### 3. 查询我的卡密历史
```http
GET /license/my/history
Authorization: Bearer {access_token}
```

### 管理员接口

#### 1. 生成卡密
```http
POST /license/generate
Authorization: Bearer {admin_token}
Content-Type: application/json

{
  "type": "monthly",
  "validDays": 30,
  "count": 10,
  "remarks": "批量生成月卡"
}
```

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

#### 2. 查询所有卡密
```http
GET /license?status=active&type=monthly
Authorization: Bearer {admin_token}
```

#### 3. 获取统计信息
```http
GET /license/statistics
Authorization: Bearer {admin_token}
```

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

#### 4. 撤销卡密
```http
POST /license/:id/revoke
Authorization: Bearer {admin_token}
```

#### 5. 删除卡密
```http
DELETE /license/:id
Authorization: Bearer {admin_token}
```

## 使用流程

### 用户激活流程

1. **用户注册/登录**
   ```http
   POST /user/register 或 POST /user/login
   ```

2. **获取卡密**
   - 从管理员处获取卡密码

3. **激活卡密**
   ```http
   POST /license/activate
   {
     "code": "获取到的卡密"
   }
   ```

4. **开始使用任务功能**
   - 激活成功后，所有 Task 相关接口均可正常使用
   - 未激活或授权过期时，Task 接口会返回 403 错误

### 管理员操作流程

1. **生成卡密**
   ```bash
   # 生成 10 个月卡
   POST /license/generate
   {
     "type": "monthly",
     "count": 10
   }
   ```

2. **查看卡密列表**
   ```bash
   GET /license
   ```

3. **分发卡密给用户**
   - 将生成的卡密码发给用户

4. **监控卡密使用情况**
   ```bash
   GET /license/statistics
   ```

## 任务模块授权保护

所有任务相关接口都需要有效的卡密授权：

- `POST /task` - 创建任务
- `GET /task` - 获取任务列表
- `GET /task/:id` - 获取单个任务
- `PATCH /task/:id` - 更新任务
- `PATCH /task/reorder` - 重新排序
- `DELETE /task/:id` - 删除任务

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

## 数据库表结构

### license 表

| 字段 | 类型 | 说明 |
|------|------|------|
| id | INT | 主键 |
| code | VARCHAR(32) | 卡密码（唯一） |
| type | ENUM | 卡密类型 |
| status | ENUM | 卡密状态 |
| validDays | INT | 有效天数 |
| activatedAt | DATETIME | 激活时间 |
| expiresAt | DATETIME | 过期时间 |
| userId | INT | 激活用户ID（外键） |
| remarks | TEXT | 备注信息 |
| createdAt | DATETIME | 创建时间 |
| updatedAt | DATETIME | 更新时间 |

## 技术实现

### 核心组件

1. **LicenseService** - 卡密业务逻辑
   - 生成卡密（确保唯一性）
   - 验证卡密
   - 激活卡密（支持延期）
   - 查询统计

2. **LicenseGuard** - 授权守卫
   - 拦截需要授权的请求
   - 验证用户授权状态
   - 返回 403 错误（未授权）

3. **@RequireLicense** - 装饰器
   - 标记需要卡密授权的 Controller/Method

### 代码示例

在需要授权保护的 Controller 上添加：

```typescript
import { UseGuards } from '@nestjs/common';
import { RequireLicense } from '../license/decorators/require-license.decorator';
import { LicenseGuard } from '../license/guards/license.guard';

@Controller('task')
@UseGuards(LicenseGuard)
@RequireLicense()
export class TaskController {
  // ... 所有接口都需要有效授权
}
```

## 注意事项

1. **安全性**
   - 卡密使用随机生成算法，去除易混淆字符
   - 每个卡密全局唯一
   - 卡密验证在守卫层面统一拦截

2. **用户体验**
   - 支持授权延期（多个卡密叠加）
   - 提供剩余天数查询
   - 清晰的错误提示

3. **管理维护**
   - 支持卡密撤销（无需删除记录）
   - 提供统计接口
   - 支持按状态和类型筛选

## Swagger 文档

启动项目后访问：`http://localhost:3030/api`

在 Swagger 文档中可以查看所有卡密相关接口的详细说明和测试。

## 测试建议

1. **测试用户激活流程**
   ```bash
   # 1. 注册用户
   # 2. 生成测试卡密
   # 3. 激活卡密
   # 4. 访问任务接口
   ```

2. **测试授权过期**
   - 修改数据库中的 expiresAt 为过去时间
   - 访问任务接口应返回 403

3. **测试延期功能**
   - 激活第一个卡密
   - 再激活第二个卡密
   - 验证有效期是否累加

## 未来扩展

1. 支持不同模块的独立授权
2. 支持授权转让
3. 添加卡密使用日志
4. 支持自动续费
5. 添加授权即将过期提醒