6.6 KiB

Raw Permalink Blame History

卡密系统使用说明

概述

本项目实现了完整的卡密商业化授权系统，用户需要激活有效的卡密才能使用任务管理（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. 激活卡密

POST /license/activate
Authorization: Bearer {access_token}
Content-Type: application/json

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

响应示例：

{
  "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. 查询我的授权信息

GET /license/my
Authorization: Bearer {access_token}

响应示例：

{
  "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. 查询我的卡密历史

GET /license/my/history
Authorization: Bearer {access_token}

管理员接口

1. 生成卡密

POST /license/generate
Authorization: Bearer {admin_token}
Content-Type: application/json

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

响应示例：

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

2. 查询所有卡密

GET /license?status=active&type=monthly
Authorization: Bearer {admin_token}

3. 获取统计信息

GET /license/statistics
Authorization: Bearer {admin_token}

响应示例：

{
  "total": 100,
  "unused": 50,
  "active": 30,
  "expired": 15,
  "revoked": 5
}

4. 撤销卡密

POST /license/:id/revoke
Authorization: Bearer {admin_token}

5. 删除卡密

DELETE /license/:id
Authorization: Bearer {admin_token}

使用流程

用户激活流程

用户注册/登录

POST /user/register 或 POST /user/login

获取卡密
- 从管理员处获取卡密码

激活卡密

POST /license/activate
{
  "code": "获取到的卡密"
}

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

管理员操作流程

生成卡密

# 生成 10 个月卡
POST /license/generate
{
  "type": "monthly",
  "count": 10
}

查看卡密列表
```
GET /license
```
分发卡密给用户
- 将生成的卡密码发给用户
监控卡密使用情况
```
GET /license/statistics
```

任务模块授权保护

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

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

未授权时的响应：

{
  "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	更新时间

技术实现

核心组件

LicenseService - 卡密业务逻辑
- 生成卡密（确保唯一性）
- 验证卡密
- 激活卡密（支持延期）
- 查询统计
LicenseGuard - 授权守卫
- 拦截需要授权的请求
- 验证用户授权状态
- 返回 403 错误（未授权）
@RequireLicense - 装饰器
- 标记需要卡密授权的 Controller/Method

代码示例

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

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 {
  // ... 所有接口都需要有效授权
}

注意事项

安全性
- 卡密使用随机生成算法，去除易混淆字符
- 每个卡密全局唯一
- 卡密验证在守卫层面统一拦截
用户体验
- 支持授权延期（多个卡密叠加）
- 提供剩余天数查询
- 清晰的错误提示
管理维护
- 支持卡密撤销（无需删除记录）
- 提供统计接口
- 支持按状态和类型筛选

Swagger 文档

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

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

测试建议

测试用户激活流程

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

测试授权过期
- 修改数据库中的 expiresAt 为过去时间
- 访问任务接口应返回 403
测试延期功能
- 激活第一个卡密
- 再激活第二个卡密
- 验证有效期是否累加

未来扩展

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

6.6 KiB Raw Permalink Blame History Unescape Escape

卡密系统使用说明

概述

功能特性

1. 卡密类型

2. 卡密状态

3. 卡密格式

API 接口

用户接口

1. 激活卡密

2. 查询我的授权信息

3. 查询我的卡密历史

管理员接口

1. 生成卡密

2. 查询所有卡密

3. 获取统计信息

4. 撤销卡密

5. 删除卡密

使用流程

用户激活流程

管理员操作流程

任务模块授权保护

数据库表结构

license 表

技术实现

核心组件

代码示例

注意事项

Swagger 文档

测试建议

未来扩展

6.6 KiB

Raw Permalink Blame History