mirror of
https://github.com/SECTL/SecScore.git
synced 2026-07-21 18:19:03 +08:00
feat: 初始化SecScore项目基础结构
- 添加Electron + React + TypeScript基础框架 - 实现学生管理、积分流水、理由管理功能 - 添加主题切换和暗黑模式支持 - 配置数据库和WebSocket同步功能 - 完善项目文档和构建配置
This commit is contained in:
Fox_block
@@ -0,0 +1,250 @@
|
||||
# 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:**
|
||||
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
|
||||
```json
|
||||
{
|
||||
"count": 2, // 成功数量
|
||||
"results": [
|
||||
{
|
||||
"index": 0,
|
||||
"success": true,
|
||||
"id": 1001 // 服务端分配的新 ID
|
||||
},
|
||||
{
|
||||
"index": 1,
|
||||
"success": true,
|
||||
"id": 10086
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 4.2 逻辑查询 (Query)
|
||||
|
||||
基于 AST 将 JSON 映射为 C++ Lambda。
|
||||
|
||||
**Request:**
|
||||
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
|
||||
```json
|
||||
{
|
||||
"items": [
|
||||
{
|
||||
"id": 1001,
|
||||
"data": { "name": "Alice", "age": 18, "score": 95.5 }
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 4.3 更新 (Update)
|
||||
|
||||
**Request:**
|
||||
|
||||
```json
|
||||
{
|
||||
"category": "student",
|
||||
"action": "update",
|
||||
"payload": {
|
||||
"id": 1001,
|
||||
"set": {
|
||||
"score": 98.0, // 仅更新指定字段
|
||||
"age": 19
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4.4 删除 (Delete)
|
||||
|
||||
**Request:**
|
||||
|
||||
```json
|
||||
{
|
||||
"category": "student",
|
||||
"action": "delete",
|
||||
"payload": {
|
||||
"id": 1001
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 事件操作 (Event Category)
|
||||
|
||||
### 5.1 添加事件 (Create)
|
||||
|
||||
**Request:**
|
||||
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 501, // 新生成的 Event ID
|
||||
"timestamp": 1710000000
|
||||
}
|
||||
```
|
||||
|
||||
### 5.2 标记擦除 (Update)
|
||||
|
||||
**Request:**
|
||||
|
||||
```json
|
||||
{
|
||||
"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++ 异常 |
|
||||
Reference in New Issue
Block a user