SecScore/SecScoreDB-WebSockets.md

SecScoreDB WebSocket JSON Protocol Specification v1.0

1. 协议概述 (Overview)

• 传输层: WebSocket
• 数据格式: JSON (UTF-8)
• 通信模式: 全双工异步通信 (Request-Response)
• 匹配机制: 客户端生成唯一 seq，服务端在响应中原样返回，用于关联请求与响应。

---

2. 通信信封 (Message Envelope)

所有通信消息必须包含以下基础字段。

2.1 客户端请求 (Request)

字段	类型	必填	说明
seq	String	Yes	请求唯一序列号 (如 UUID)
category	String	Yes	资源类别: "system", "student", "group", "event"
action	String	Yes	操作动作: "define", "create", "query", "update", "delete"
payload	Object	Yes	具体操作参数，结构依 action 而定

2.2 服务端响应 (Response)

字段	类型	必填	说明
seq	String	Yes	对应请求的 seq
status	String	Yes	"ok" 或 "error"
code	Int	Yes	状态码 (见第 6 节)
message	String	No	错误描述或提示信息
data	Object	No	成功时的返回数据

---

3. 系统管理 (System Category)

3.1 定义 Schema (Define)

在操作数据前，必须定义动态字段结构。

Request:

{
  "category": "system",
  "action": "define",
  "payload": {
    "target": "student", // 或 "group"
    "schema": {
      "name": "string",
      "age": "int",
      "score": "double",
      "active": "int"
    }
  }
}

---

4. 数据资源操作 (Student & Group Category)

以下示例以 category: "student" 为例，group 同理。

4.1 批量创建/导入 (Batch Create)

核心规则:

1. id 为 null 时，服务端自动分配 ID。
2. id 有值时，强制使用该 ID (导入模式)。
3. 使用 index 锚定请求项，确保批量回包的对应关系。

Request:

{
  "category": "student",
  "action": "create",
  "payload": {
    "items": [
      {
        "index": 0, // 客户端临时索引
        "id": null, // [请求分配ID]
        "data": { "name": "Alice", "age": 18, "score": 95.5 }
      },
      {
        "index": 1,
        "id": 10086, // [强制指定ID]
        "data": { "name": "Bob", "age": 20 }
      }
    ]
  }
}

Response Data:

{
  "count": 2, // 成功数量
  "results": [
    {
      "index": 0,
      "success": true,
      "id": 1001 // 服务端分配的新 ID
    },
    {
      "index": 1,
      "success": true,
      "id": 10086
    }
  ]
}

4.2 逻辑查询 (Query)

基于 AST 将 JSON 映射为 C++ Lambda。

Request:

{
  "category": "student",
  "action": "query",
  "payload": {
    "logic": {
      "op": "AND", // 根节点逻辑: AND, OR
      "rules": [
        { "field": "score", "op": ">=", "val": 90.0 },
        {
          "op": "OR",
          "rules": [
            { "field": "age", "op": "<", "val": 20 },
            { "field": "name", "op": "==", "val": "Alice" }
          ]
        }
      ]
    }
  }
}

支持的操作符 (op): ==, !=, >, <, >=, <=

Response Data:

{
  "items": [
    {
      "id": 1001,
      "data": { "name": "Alice", "age": 18, "score": 95.5 }
    }
  ]
}

4.3 更新 (Update)

Request:

{
  "category": "student",
  "action": "update",
  "payload": {
    "id": 1001,
    "set": {
      "score": 98.0, // 仅更新指定字段
      "age": 19
    }
  }
}

4.4 删除 (Delete)

Request:

{
  "category": "student",
  "action": "delete",
  "payload": {
    "id": 1001
  }
}

---

5. 事件操作 (Event Category)

5.1 添加事件 (Create)

Request:

{
  "category": "event",
  "action": "create",
  "payload": {
    "id": null, // 必须为 null
    "type": 1, // 1=Student, 2=Group
    "ref_id": 1001, // 关联对象的 ID
    "desc": "Score adjustment",
    "val_prev": 95.5,
    "val_curr": 98.0
  }
}

Response Data:

{
  "id": 501, // 新生成的 Event ID
  "timestamp": 1710000000
}

5.2 标记擦除 (Update)

Request:

{
  "category": "event",
  "action": "update",
  "payload": {
    "id": 501,
    "erased": true
  }
}

---

6. 状态码定义 (Status Codes)

Code	Meaning	Description
200	OK	请求成功执行
400	Bad Request	JSON 格式错误、缺少必填字段或 action 不支持
404	Not Found	指定的 ID 不存在
422	Unprocessable	数据类型不匹配 (如给 Int 字段传 String)
500	Internal Error	核心内部 C++ 异常