live-forum/.kiro/specs/cdk-activation/design.md

Design Document: CDK Activation

Overview

CDK 激活功能允许管理员通过发放激活码（CDK）来控制用户的互动权限。该功能涉及三个主要系统：

1. 小程序端：用户激活 CDK、检查激活状态
2. 后台管理端：管理员批量生成 CDK、查看使用情况、控制功能开关
3. API 服务端：提供 CDK 验证、激活、管理等接口

Architecture

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:

{
  "code": 200,
  "data": {
    "cdkEnabled": true,
    "isActivated": false
  }
}

POST /api/cdk/activate

激活 CDK

Request:

{
  "code": "XXXX-XXXX-XXXX"
}

Response (成功):

{
  "code": 200,
  "msg": "CDK 激活成功"
}

Response (失败):

{
  "code": 400,
  "msg": "该 CDK 已被激活" | "请输入有效 CDK"
}

3. 后台管理 API 接口

POST /api/admin/cdk/generate

批量生成 CDK

Request:

{
  "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:

{
  "enabled": true
}

GET /api/admin/settings/cdk-enabled

获取 CDK 功能状态

Data Models

C# 实体类

// 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; }
}

前端数据模型

// 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 端到端测试
• 数据库事务测试