231 lines
5.9 KiB
Markdown
231 lines
5.9 KiB
Markdown
# Design Document: CDK Activation
|
||
|
||
## Overview
|
||
|
||
CDK 激活功能允许管理员通过发放激活码（CDK）来控制用户的互动权限。该功能涉及三个主要系统：
|
||
1. **小程序端**：用户激活 CDK、检查激活状态
|
||
2. **后台管理端**：管理员批量生成 CDK、查看使用情况、控制功能开关
|
||
3. **API 服务端**：提供 CDK 验证、激活、管理等接口
|
||
|
||
## Architecture
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "小程序端"
|
||
MP[小程序] --> |检查CDK状态| API
|
||
MP --> |激活CDK| API
|
||
MP --> |互动操作| API
|
||
end
|
||
|
||
subgraph "后台管理端"
|
||
Admin[管理后台] --> |生成CDK| AdminAPI
|
||
Admin --> |查询CDK列表| AdminAPI
|
||
Admin --> |开关CDK功能| AdminAPI
|
||
end
|
||
|
||
subgraph "服务端"
|
||
API[小程序API]
|
||
AdminAPI[后台API]
|
||
API --> DB[(数据库)]
|
||
AdminAPI --> DB
|
||
end
|
||
```
|
||
|
||
## Components and Interfaces
|
||
|
||
### 1. 数据库层
|
||
|
||
#### T_CDKs 表（新建）
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| Id | BIGINT | 主键自增 |
|
||
| Code | NVARCHAR(50) | CDK 码，唯一索引 |
|
||
| BatchNo | NVARCHAR(50) | 批次号 |
|
||
| Status | INT | 状态：0-未使用，1-已使用 |
|
||
| UsedByUserId | BIGINT | 使用者用户ID |
|
||
| UsedAt | DATETIME2 | 使用时间 |
|
||
| CreatedAt | DATETIME2 | 创建时间 |
|
||
| Remark | NVARCHAR(200) | 备注 |
|
||
|
||
#### T_SystemSettings 表（新建）
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| Id | INT | 主键自增 |
|
||
| SettingKey | NVARCHAR(100) | 配置键，唯一索引 |
|
||
| SettingValue | NVARCHAR(500) | 配置值 |
|
||
| Description | NVARCHAR(200) | 描述 |
|
||
| UpdatedAt | DATETIME2 | 更新时间 |
|
||
|
||
#### T_Users 表（修改）
|
||
新增字段：
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| IsCdkActivated | BIT | 是否已激活CDK，默认0 |
|
||
| CdkActivatedAt | DATETIME2 | CDK激活时间 |
|
||
|
||
### 2. 小程序 API 接口
|
||
|
||
#### GET /api/cdk/check-status
|
||
检查用户是否需要激活 CDK
|
||
|
||
**Response:**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"cdkEnabled": true,
|
||
"isActivated": false
|
||
}
|
||
}
|
||
```
|
||
|
||
#### POST /api/cdk/activate
|
||
激活 CDK
|
||
|
||
**Request:**
|
||
```json
|
||
{
|
||
"code": "XXXX-XXXX-XXXX"
|
||
}
|
||
```
|
||
|
||
**Response (成功):**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "CDK 激活成功"
|
||
}
|
||
```
|
||
|
||
**Response (失败):**
|
||
```json
|
||
{
|
||
"code": 400,
|
||
"msg": "该 CDK 已被激活" | "请输入有效 CDK"
|
||
}
|
||
```
|
||
|
||
### 3. 后台管理 API 接口
|
||
|
||
#### POST /api/admin/cdk/generate
|
||
批量生成 CDK
|
||
|
||
**Request:**
|
||
```json
|
||
{
|
||
"count": 100,
|
||
"batchNo": "BATCH-20250125",
|
||
"remark": "第一批测试CDK"
|
||
}
|
||
```
|
||
|
||
#### GET /api/admin/cdk/list
|
||
查询 CDK 列表（分页）
|
||
|
||
**Query Params:** pageNum, pageSize, status, batchNo
|
||
|
||
#### PUT /api/admin/settings/cdk-enabled
|
||
开关 CDK 功能
|
||
|
||
**Request:**
|
||
```json
|
||
{
|
||
"enabled": true
|
||
}
|
||
```
|
||
|
||
#### GET /api/admin/settings/cdk-enabled
|
||
获取 CDK 功能状态
|
||
|
||
## Data Models
|
||
|
||
### C# 实体类
|
||
|
||
```csharp
|
||
// T_CDKs.cs
|
||
public class T_CDKs
|
||
{
|
||
public long Id { get; set; }
|
||
public string Code { get; set; }
|
||
public string BatchNo { get; set; }
|
||
public int Status { get; set; } // 0-未使用, 1-已使用
|
||
public long? UsedByUserId { get; set; }
|
||
public DateTime? UsedAt { get; set; }
|
||
public DateTime CreatedAt { get; set; }
|
||
public string Remark { get; set; }
|
||
}
|
||
|
||
// T_SystemSettings.cs
|
||
public class T_SystemSettings
|
||
{
|
||
public int Id { get; set; }
|
||
public string SettingKey { get; set; }
|
||
public string SettingValue { get; set; }
|
||
public string Description { get; set; }
|
||
public DateTime UpdatedAt { get; set; }
|
||
}
|
||
```
|
||
|
||
### 前端数据模型
|
||
|
||
```javascript
|
||
// CDK 激活状态
|
||
{
|
||
cdkEnabled: Boolean, // CDK功能是否启用
|
||
isActivated: Boolean // 当前用户是否已激活
|
||
}
|
||
```
|
||
|
||
## Correctness Properties
|
||
|
||
*A property is a characteristic or behavior that should hold true across all valid executions of a system-essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.*
|
||
|
||
### Property 1: 未激活用户互动操作拦截
|
||
*For any* user without CDK activation, when the CDK feature is enabled, attempting any interactive operation (post, comment, send flower) SHALL return an error code indicating CDK activation is required.
|
||
**Validates: Requirements 1.2, 1.3**
|
||
|
||
### Property 2: CDK 激活成功更新状态
|
||
*For any* valid and unused CDK, when a user activates it, the system SHALL mark the CDK as used, record the user ID, and update the user's IsCdkActivated to true.
|
||
**Validates: Requirements 2.3, 2.5**
|
||
|
||
### Property 3: CDK 唯一性验证
|
||
*For any* CDK that has been used, attempting to activate it again SHALL return an error indicating the CDK has already been activated.
|
||
**Validates: Requirements 2.2, 3.2**
|
||
|
||
### Property 4: 无效 CDK 拒绝
|
||
*For any* string that does not match an existing CDK code, the activation attempt SHALL return an error indicating invalid CDK.
|
||
**Validates: Requirements 2.4**
|
||
|
||
### Property 5: CDK 批量生成唯一性
|
||
*For any* batch generation request, all generated CDK codes SHALL be unique across the entire system.
|
||
**Validates: Requirements 3.1**
|
||
|
||
### Property 6: CDK 功能开关即时生效
|
||
*For any* change to the CDK feature toggle, the system behavior SHALL immediately reflect the new setting for all subsequent requests.
|
||
**Validates: Requirements 4.2, 4.3, 4.4**
|
||
|
||
## Error Handling
|
||
|
||
| 场景 | 错误码 | 错误信息 |
|
||
|------|--------|----------|
|
||
| CDK 已被使用 | 400 | 该 CDK 已被激活 |
|
||
| CDK 不存在/无效 | 400 | 请输入有效 CDK |
|
||
| 未激活 CDK 进行互动 | 403 | 需要激活 CDK |
|
||
| CDK 功能未启用 | - | 正常放行 |
|
||
|
||
## Testing Strategy
|
||
|
||
### 单元测试
|
||
- CDK 生成算法测试（唯一性、格式）
|
||
- CDK 验证逻辑测试
|
||
- 用户状态更新测试
|
||
|
||
### 属性测试
|
||
使用 xUnit + FsCheck 进行属性测试：
|
||
- 配置每个属性测试运行 100 次迭代
|
||
- 每个测试标注对应的设计属性编号
|
||
|
||
### 集成测试
|
||
- API 端到端测试
|
||
- 数据库事务测试
|