CCXC Engine

Appearance

CCXC Backend Script API 参考 ​

CCXC 后端脚本系统提供了一套强大且灵活的 API 接口，让开发者能够构建复杂的交互式题目和自定义判题逻辑。

概述 ​

后端脚本通过全局变量 ctx 提供所有 API 功能。该上下文对象包含了题目执行所需的数据和方法，是连接前端用户交互与后端逻辑的核心桥梁。

脚本类型架构 ​

CCXC Engine 支持两种不同的脚本执行环境：

题目后端脚本
由 Vue SFC 题目组件中的 backend 函数主动调用，适用于需要实时交互的复杂题目场景。

高级判题脚本
在题目配置的"高级判题"选项中通过脚本 key 自动触发，专门用于自定义答案验证逻辑。

重要提示

题目后端 与 高级判题：不同脚本类型的 ctx 对象提供的属性和方法存在差异。请根据文档中的标识选择合适的 API。

上下文属性 ​

request ​

适用范围: 题目后端

typescript
request: string

描述
前端发送的请求数据，以JSON字符串格式传输。包含用户的交互输入和状态信息。

使用方式

javascript
const requestData = JSON.parse(ctx.request);

注意事项

  • 必须使用 JSON.parse() 进行反序列化
  • 请求格式由前端题目逻辑决定

uid ​

适用范围: 题目后端 高级判题

typescript
uid: number

描述
当前执行脚本的用户唯一标识符。

返回值
用户的数字ID，在系统内全局唯一。

username ​

适用范围: 题目后端 高级判题

typescript
username: string

描述
当前用户的登录用户名。

返回值
用户在系统中注册的用户名字符串。

gid ​

适用范围: 题目后端 高级判题

typescript
gid: number

描述
当前用户所属团队的组织标识符。

返回值
团队的数字ID，用于团队协作和进度共享。

pid ​

适用范围: 高级判题

typescript
pid: number

描述
当前正在执行判题逻辑的题目标识符。

返回值
题目的唯一数字ID。

answer ​

适用范围: 高级判题

typescript
answer: string

描述
经过标准化处理的用户答案。系统自动执行以下清理操作：

  • 移除前后空白字符
  • 移除中间的空格、下划线和减号
  • 保留其他字符（包括大小写）

注意事项
如需原始答案，请使用 originalAnswer 属性。

originalAnswer ​

适用范围: 高级判题

typescript
originalAnswer: string

描述
用户提交的原始答案，未经任何处理或格式化。

使用场景
适用于需要严格验证格式或包含特殊字符的答案。

状态管理方法 ​

getStatus ​

适用范围: 题目后端

typescript
getStatus(key: string): string

功能
读取当前用户的客户端状态存储。

参数

  • key (string): 状态键名

返回值
存储的状态值（字符串格式）

特性

  • 数据加密存储在用户浏览器中
  • 不同用户和不同浏览器实例拥有独立的状态空间
  • 适用于用户个人进度和临时数据存储

setStatus ​

适用范围: 题目后端

typescript
setStatus(key: string, value: string): void

功能
写入当前用户的客户端状态存储。

参数

  • key (string): 状态键名
  • value (string): 要存储的值

使用场景
保存用户的题目进度、选择状态或临时计算结果。

getProgress ​

适用范围: 题目后端 高级判题

typescript
getProgress(pid: number, key: string): string

功能
读取指定题目的团队进度数据。

参数

  • pid (number): 题目ID
  • key (string): 进度键名

返回值
存储的进度值（字符串格式）

特性

  • 数据存储在服务器数据库中
  • 团队成员共享访问
  • 每个题目拥有独立的进度命名空间

setProgress ​

适用范围: 题目后端 高级判题

typescript
setProgress(pid: number, key: string, value: string): void

功能
写入指定题目的团队进度数据。

参数

  • pid (number): 题目ID
  • key (string): 进度键名
  • value (string): 要存储的值

使用场景
记录团队解题进度、中间结果或协作状态。

getStorage ​

适用范围: 题目后端 高级判题

typescript
getStorage(key: string): string

功能
读取全局共享存储数据。

参数

  • key (string): 存储键名

返回值
存储的值（字符串格式）

特性

  • 服务器端持久化存储
  • 所有用户和团队共享访问
  • 适用于全局统计、排行榜等场景

setStorage ​

适用范围: 题目后端 高级判题

typescript
setStorage(key: string, value: string): void

功能
写入全局共享存储数据。

参数

  • key (string): 存储键名
  • value (string): 要存储的值

注意事项
全局存储会影响所有用户，请谨慎使用并考虑并发访问问题。

数据获取方法 ​

getPuzzleData ​

适用范围: 题目后端 高级判题

typescript
getPuzzleData(pid: number): string

功能
获取指定题目的配置数据片段。

参数

  • pid (number): 题目ID

返回值
题目详情中 <data></data> 标签内的原始内容

使用场景
访问题目的静态配置信息、预设数据或元数据。

getGroupName ​

适用范围: 题目后端 高级判题

typescript
getGroupName(gid: number): string

功能
查询指定团队的名称。

参数

  • gid (number): 团队ID

返回值
团队的显示名称

getRankAndWinner ​

适用范围: 题目后端

typescript
getRankAndWinner(gid: number): { rank: number; champion: string }

功能
获取指定团队的比赛排名信息和冠军团队名称。

参数

  • gid (number): 团队ID

返回值
包含以下属性的对象：

  • rank (number): 团队的完赛排名
  • champion (string): 冠军团队名称

使用场景
生成结局剧情、排行榜显示或比赛总结。

积分系统 ​

costCredit ​

适用范围: 题目后端

typescript
costCredit(gid: number, cost: number): boolean

功能
扣减指定团队的信用点数。

参数

  • gid (number): 团队ID
  • cost (number): 要扣减的点数

返回值

  • true: 扣减成功
  • false: 扣减失败（可能由于余额不足）

使用场景
实现付费提示、道具购买或惩罚机制。

响应输出方法 ​

response ​

适用范围: 题目后端

typescript
response(body: string): void

功能
向前端返回响应数据。

参数

  • body (string): 响应内容，必须是有效的JSON字符串

重要提示

  • 必须调用: 每个题目后端脚本都必须至少调用一次此方法
  • 格式要求: 传入参数必须是通过 JSON.stringify() 序列化的字符串
  • 最低调用: 即使无数据返回，也需调用 ctx.response("{}")

示例

javascript
const result = { success: true, message: "操作完成" };
ctx.response(JSON.stringify(result));

判题控制方法 ​

setResult ​

适用范围: 高级判题

typescript
setResult(result: boolean): void

功能
设置判题的最终结果。

参数

  • result (boolean): 判题结果
    • true: 答案正确
    • false: 答案错误

重要提示
高级判题脚本必须至少调用一次此方法来确定判题结果。

setExtraMessage ​

适用范围: 高级判题

typescript
setExtraMessage(message: string): void

功能
设置返回给用户的附加提示信息。

参数

  • message (string): 要显示的消息内容

使用场景
为用户提供解题提示、错误说明或进度反馈。

hitMilestone ​

适用范围: 高级判题

typescript
hitMilestone(hit: boolean): void

功能
设置里程碑状态，用于标记解题进度。

参数

  • hit (boolean): 是否触发里程碑

重要约束
只有当判题结果为 false 时，里程碑状态才会生效。

使用场景
实现分阶段解题、进度奖励或中间成就系统。

setShowAnswer ​

适用范围: 高级判题

typescript
setShowAnswer(answer: string): void

功能
自定义用户查看答案时显示的内容。

参数

  • answer (string): 要显示的答案内容

默认行为
若未调用此方法，系统将显示题目配置中的标准答案。

网络请求方法 ​

httpPostForm ​

适用范围: 题目后端

typescript
httpPostForm(url: string, form: object, headers: object): string

功能
由服务器端发起HTTP POST请求，调用外部API或服务。

参数

  • url (string): 目标URL地址
  • form (object): 请求参数对象
  • headers (object): 请求头配置

返回值
远程服务器的响应内容（字符串格式）

使用场景
集成第三方服务、验证外部数据或触发远程操作。

安全提示
请求将从服务器端发出，确保目标URL的安全性和可信度。

游戏进度方法 ​

addAnswerLog ​

适用范围: 题目后端

typescript
addAnswerLog(uid: number, gid: number, pid: number, answer: string, status: number, message: string): void

功能
手动添加答案提交记录到系统日志。

参数

  • uid (number): 用户ID
  • gid (number): 团队ID
  • pid (number): 题目ID
  • answer (string): 提交的答案
  • status (number): 提交状态码
    • 1: 正确
    • 2: 答案错误
    • 3: 答题次数用尽
    • 4: 里程碑
  • message (string): 附加消息

使用场景
记录非标准答案框的提交行为，如交互式游戏中的操作记录。

makePuzzleFinished ​

适用范围: 题目后端

typescript
makePuzzleFinished(gid: number, pid: number, message: string): {
  status: number;
  message: string;
  answer_status: number;
  extend_flag: number;
  location: string;
}

警告

使用 makePuzzleFinished 时，不能同时使用其他的保存数据库的方法，如setProgress或costCredit。否则会造成写入存档冲突。

功能
直接将指定题目标记为完成状态。

参数

  • gid (number): 团队ID
  • pid (number): 题目ID
  • message (string): 完成时的附加信息

返回值
返回对象包含以下属性：

  • status (number): 操作状态码
  • message (string): 状态消息
  • answer_status (number): 答案状态
  • extend_flag (number): 扩展标志
  • location (string): 位置信息

使用场景
交互式游戏题目中，当玩家完成特定任务时自动标记题目完成。

API兼容性
返回格式与 /check-answer API 保持一致，确保前端处理的统一性。

最佳实践 ​

错误处理 ​

始终验证输入参数的有效性，特别是来自 ctx.request 的用户数据。

性能优化 ​

合理使用存储方法，避免频繁的数据库操作。优先使用客户端状态存储处理临时数据。

安全考虑 ​

  • 验证用户权限，确保操作的合法性
  • 对外部HTTP请求进行适当的安全检查
  • 避免在全局存储中泄露敏感信息

调试技巧 ​

利用 setExtraMessage 方法在开发阶段输出调试信息，便于问题定位和逻辑验证。

Released under the MIT License. Powered by VitePress.

Copyright © 2025 密码菌 (CipherPuzzles) and contributors