CSIS Format

Common Student Information Structure 通用学生信息结构

版本 v26.1.1 | API 版本 1

CSIS 是一个基于 JSON 的 DSL，旨在为随机抽名、排位、积分等教学适用的与学生数据有交集的软件提供一个统一的交换格式。

CSIS 分为多个子语言，每个子语言都适用一类特定软件。它还提供一个通用格式，便于识别。

Common Student List Structure - 通用学生列表结构 CSLS

• 后缀名 | CSLS
• 适用
  • 随机抽名软件
  • 积分软件
  • 值日表软件
• 特性
  • 存储多个班级
  • 小组信息
  • 性别包容
  • 对于每个学生的额外信息

格式范例

• API 1

注：没有标为必填的项目均为选填。

{
  "version": 1,  // API 版本
  "classes": [
    {
      "name": str,  // 必填，班级名称
      "class": int,  // 必填，班级号（如七 (1) 班的 1）
      "grade": int,  // 必填，年级
      "floor": int,  // 楼层 (从1开始)
      "building": str,  // 楼号
      "room": str,  // 房间号
      // 若您的班级房间号包括楼层/楼号信息，我们建议只填写房间号。
      "groups": [  // 组别
        {
          "name": str,  // 必填，小组名
          "tags": [str, ...],  // 标签（如荣誉获得等）
          "extra": {...}  // 额外信息
        }, ...
      ],
      "students": [  // 单个学生
        {
          "id": int,  // 必填，单一序号，建议为学号
          "name": str,  // 必填，学生名称
          "nickname": str,  // 昵称
          "group": str,  // 组别，为外部 groups 字段中 name 之一
          "tags": [str, ...],  // 标签（如荣誉获得等）
          "gender": str,  // 性别（建议为'male', 'female'之一）
          // CSIS 格式制定组支持 LGBTQIA+ 群体，这就是为什么我们没有规定性别必须为这两个值之一。
          "number": int,  // 学号（大于 0 的整数（建议为连续的））
          "extra" : {...}  // 额外信息：您可以基于 CSLS 为您的应用程序制定信息存储格式
          // 若要添加更多信息，我们建议使用 CSAIS 作为格式。它具有更强的扩展性。
        }, ...
      ],
    }, ...
  ]
}

Common Student Placing Structure - 通用学生座位表 CSPS

• 后缀名 | CSPS
• 适用
  • 座位排放软件
  • 其他学生管理软件
• 特性
  • 存储座位信息
  • 单个班级
  • 支持轮换设置
  • 支持“同桌”机制与同桌同时轮换

格式范例

• API: 1

当启用"同桌"时，每组同桌算为一个单元 (一列、一行)，同时在每个学生的单独配置中填写"deskmate_pos"项目

{
  "version": int,  // 必填，API 版本
  "rotation": {  // 轮换配置
    "enabled": bool,  // 必填，是否启用轮换
    "to_left": bool,  // 若启用轮换必填，(讲台为前) 是否是向左方轮换
    "cycle_days": int,  // 若启用轮换必填，轮换周期 (以天为单位)
    "cycle_in_columns": bool  // 若启用轮换必填，是否基于列轮换
  },
  "deskmate": bool,  // 启用同桌功能
  "students":[
    {
      "id": int,  // 必填，单一序号
      "name": str,  // 必填，姓名
      "gender": str,  // 性别
      "deskmate_pos": str,  // 若启用同桌必填，同桌中的位置，必须为 "left"/"right" 之一
      "position": [int, int]  // 必填，以教师最左最靠近讲台的单位为原点，以向右为 +x 轴，以向远离讲台方向为 +y 轴，建立坐标系，并分别填写 x, y 坐标
    }, ...
  ]
}

Extended Student Placing Structure 扩展学生座位表 ESPS

基于 CSPS 的扩展格式，额外增添了适配于座位分配器的统一配置选项。

• 后缀名 | ESPS
• 适用
  • 学生座位排放实用程序
• 扩展特性
  • （基于 CSPS，新增：）
  • 统一化的个体规则描述
  • 特殊化座位（多个左护法与右护法）
  • 软件私有配置位置

格式范例

• API: 1

同桌的特殊规则仍适用。

{
  "version": int,  // 必填，API 版本
  "deskmate": bool,  // 启用同桌功能
  "rotation": {  // 轮换配置
    "enabled": bool,  // 必填，是否启用轮换
    "to_left": bool,  // 若启用轮换必填，(讲台为前) 是否是向左方轮换
    "cycle_days": int,  // 若启用轮换必填，轮换周期 (以天为单位)
    "cycle_in_columns": bool  // 若启用轮换必填，是否基于列轮换
  },
  "students":[
    {
      "id": int,  //必填，单一序号
      "name": str,  // 必填，姓名
      "gender": str,  // 性别，推荐为 `male` `female` 之一
      "height": float,  // 身高，以米为单位
      "group": str,  // 组
      "deskmate_pos": str,  // 若启用同桌必填，同桌中的位置，必须为 "left"/"right" 之一
      "position": [int, int],  // 必填，以教师最左最靠近讲台的单位为原点，以向右为 +x 轴，以向远离讲台方向为 +y 轴，建立坐标系，并分别填写 x, y 坐标。此项目不考虑同桌设置
      // 左护法：[-1, <左护法序号，从 1 开始>]
      // 右护法：[-2, <同上>]
      "tags": [str, ...],  // 程序自定义的标签，如班干部等。参见「标签示例」
      "ruleset": [<object ruleset>, ...],  // 规则集，参见「规则集」
      "ext": ...  // 程序自定义的数据
    }, ...
  ]
}

规则集

<object ruleset> 是一个 JSON 对象，依据不同的 type 设置有不同的内容，具体参考： 所有项目默认必填。

{
  "type": <type>,  // 填写下面的值
  "content": <content>  // 按照每个区块内容填写
}

不与「」接触

在指定的距离内，该学生不应与指定的一群学生接触。若需要对不同学生制定不同距离，指定多个 notwith 项目。

• type: notwith

{
  "ids": [int, ...],  // 不与接触的学生 ID
  "distance": {
    "type": <"manhattan" | "chebyshev">,  // 曼哈顿距离/切比雪夫距离
    "value": int  // 具体值
  }
}

应与「」接触

在指定的范围内，该学生应该与指定的一群学生接触。若需要对不同学生制定不同距离，指定多个 shouldwith 项目。

• type: shouldwith

{
  "ids": [int, ...],  // 需与接触的学生 ID
  "distance": {
    "type": <"manhattan" | "chebyshev">,  // 曼哈顿距离/切比雪夫距离
    "value": int  // 具体值
  }
}

靠近「」行/排

尽量靠近某一横行/竖排。

• type: getnear-linecolumn

{
  "type": <"line" | "column">,  // 行或列
  "value": int  // 要靠近的行/列号
}

靠近「」标签

在指定的范围内，应有至少指定数量的学生具有某个标签/标签组。

• type: getnear-tags

{
  "tags": [str, ...],  // 需有的标签/标签组前缀
  "distance": {
    "type": <"manhattan" | "chebyshev">,  // 曼哈顿距离/切比雪夫距离
    "value": int  // 具体值
  }
}

禁止同桌

若启用了「同桌」，不使某个学生与指定的学生成为同桌。

• type: bandeskmate

{
  "ids": [int, ...]  // 需不与成为同桌的学生 ID
}

独占组/列/行

此学生不应与另一个有此规则的学生在同一行/列/组中。

• type: exclusion

{
  "type": <"group" | "line" | "column">
}

标签示例

标签有 2 个形式：单独标签与带标签组的标签。单独标签是形如 Class Leader 班长 的标签。若要为标签指定标签组，在一个标签中用半角引号分隔标签组与子标签：课代表:英语 此类。

Common Student Additional Information Structure - 通用学生额外信息结构 CSAIS

[TO BE COMPLETED]