Ccxc.Core.Plugins 包

Ccxc.Core.Plugins 是插件系统的核心包，提供了插件开发所需的基础接口和数据模型。

命名空间结构

• Ccxc.Core.Plugins - 核心插件接口
• Ccxc.Core.Plugins.DataModels - 数据模型

核心接口

IConfig 接口

配置接口，定义了系统所需的基础配置项。

public interface IConfig

属性

属性名	类型	描述
RedisConnStr	string	Redis连接字符串，用于缓存和会话管理
DbConnStr	string	数据库连接字符串，用于数据持久化
ImageStorage	string	图片存储路径，定义图片文件的存储位置
ImagePrefix	string	图片引用前缀，用于生成图片访问URL

IPlugin 接口

插件接口，所有插件都必须实现此接口。

public interface IPlugin

属性

属性名	类型	描述
Name	string	插件名称，作为插件的唯一标识符

方法

方法名	返回类型	描述
Initialize()	Task	异步初始化插件，在插件加载时调用
RegisterControllers()	Task<IEnumerable<HttpController>>	注册HTTP控制器到系统中，返回需要注册的控制器列表

IPluginAPI 接口

插件API接口，为插件提供与系统核心功能交互的能力。

public interface IPluginAPI

方法

方法名	返回类型	描述
CheckAuth	Task<UserSession>	检查用户登录状态和权限
GetProgressData	Task<ProgressData>	获取用户进度数据
SavePuzzleProgress	Task	保存题目额外状态信息
CostCredit	Task<bool>	消耗或增加队伍信用点
AddAnswerLog	Task	添加题目提交日志
MakePuzzleFinished	Task<(int, int, int, string, string)>	标记题目为已完成并推进进度

详细方法说明

CheckAuth 方法

检查用户的登录状态和权限。

Task<UserSession> CheckAuth(Request request, Response response, AuthLevel authLevel, bool onlyInGaming = false)

参数:

• request (Request): HTTP请求对象
• response (Response): HTTP响应对象
• authLevel (AuthLevel): 此接口最低允许使用的权限级别
• onlyInGaming (bool, 可选): 是否仅允许比赛中调用，默认为 false

返回值:

• Task<UserSession>: 如果用户已登录且权限足够，返回用户Session；否则返回 null

注意: 如果此方法返回 null，调用方应该直接返回，不继续执行后续逻辑。

GetProgressData 方法

获取当前用户组队和题目存档状态。

Task<ProgressData> GetProgressData(int uid)

参数:

• uid (int): 用户UID

返回值:

• Task<ProgressData>: 用户的进度数据

注意: 未开赛前只会返回 gid 字段。

SavePuzzleProgress 方法

保存题目的额外状态信息。

Task SavePuzzleProgress(int gid, int pid, string key, string value)

参数:

• gid (int): 队伍GID
• pid (int): 题目PID
• key (string): 状态信息的键
• value (string): 状态信息的值

CostCredit 方法

消耗队伍信用点（负数时为增加信用点）。

Task<bool> CostCredit(int gid, int cost)

参数:

• gid (int): 队伍GID
• cost (int): 信用点数量（负数表示增加信用点）

返回值:

• Task<bool>: 操作成功返回 true，失败返回 false（通常因为信用点余额不足）

AddAnswerLog 方法

添加题目提交日志记录。

Task AddAnswerLog(int uid, int gid, int pid, string answer, int status, string message)

参数:

• uid (int): 用户UID
• gid (int): 队伍GID
• pid (int): 题目PID
• answer (string): 提交的答案
• status (int): 判题结果状态码
• message (string): 附加消息

判题结果状态码:

• 1 - 正确
• 2 - 答案错误
• 3 - 答题次数用尽
• 4 - 里程碑
• 5 - 发生存档错误而未判定
• 6 - 该题目不可见而无法回答
• 7 - 解锁提示

MakePuzzleFinished 方法

将题目标记为已完成并继续推进题目进度。

Task<(int code, int answerStatus, int extendFlag, string message, string location)> MakePuzzleFinished(int uid, string username, int gid, int pid, string message)

参数:

• uid (int): 用户UID
• username (string): 用户名（用于推送消息生成）
• gid (int): 队伍GID
• pid (int): 题目PID
• message (string): 附加消息

返回值: 返回一个包含五个元素的元组：

• code (int): 操作结果码（0-成功，1-失败）
• answerStatus (int): 判题结果（仅为1-正确，因为此方法只用于标记成功）
• extendFlag (int): 判题额外消息标志
  • 0 - 默认
  • 1 - 跳转
  • 16 - 重载当前页
• message (string): 返回消息
• location (string): 跳转时的目标位置

数据模型

AuthLevel 枚举

定义用户的权限级别。

public enum AuthLevel

枚举值

值	数值	描述
Banned	-1	被禁用的用户
NeedActivate	0	需要激活的用户
Normal	1	普通用户
Member	2	成员用户
TeamLeader	3	队长
Organizer	4	组织者
Administrator	5	管理员

UserSession 类

用户会话信息类，存储当前登录用户的基本信息。

public class UserSession

属性

属性名	类型	默认值	描述
uid	int	0	用户ID
username	string	""	用户名
roleid	int	0	角色ID

ProgressData 类

进度数据类，用于跟踪和管理用户或团队的游戏/竞赛进度。

public class ProgressData

属性

属性名	类型	默认值	描述
gid	int	0	队伍ID
FinishedProblems	HashSet<int>	new HashSet<int>()	已完成的题目ID集合
UnlockedProblems	HashSet<int>	new HashSet<int>()	已解锁的题目ID集合
FinishedGroups	HashSet<int>	new HashSet<int>()	已完成的分区ID集合
UnlockedGroups	HashSet<int>	new HashSet<int>()	已解锁的分区ID集合
ProblemUnlockTime	Dictionary<int, DateTime>	new Dictionary<int, DateTime>()	题目解锁时间映射（题目ID → 解锁时间）
ProblemAnswerSubmissionsCount	Dictionary<int, int>	new Dictionary<int, int>()	各题目的答案提交次数（题目ID → 提交次数）
AdditionalProblemAttemptsCount	Dictionary<int, int>	new Dictionary<int, int>()	已购买的额外题目回答次数（题目ID → 额外次数）
OpenedHints	Dictionary<int, HashSet<int>>	new Dictionary<int, HashSet<int>>()	已兑换的提示（题目ID → 提示ID集合）
ProblemStatus	Dictionary<int, Dictionary<string, string>>	new Dictionary<int, Dictionary<string, string>>()	题目当前状态（题目ID → 状态键值对）
IsFinish	bool	false	是否完成所有内容
FinishTime	DateTime	DateTime.MinValue	完成时间