156 lines
6.3 KiB
Markdown
156 lines
6.3 KiB
Markdown
# 帽石系统 - 数据表结构设计文档
|
||
|
||
> 适用数据库：MySQL 5.7+
|
||
> 对应建表语句：`capstone_exam.sql`
|
||
> 表名：`t_capstone_exam`
|
||
|
||
---
|
||
|
||
## 1. 业务背景
|
||
|
||
帽石系统用于记录考生对“帽石”进行检测/考试的全程数据。系统可提供的信息包括：
|
||
|
||
- 考生 ID（需同步给对方系统）
|
||
- 帽石编号
|
||
- 实际位置 XY（标准/目标坐标）
|
||
- 实测数据 XY（考生现场实测坐标）
|
||
- 出题人
|
||
- 成绩
|
||
- 考试时间
|
||
- 是否合格
|
||
|
||
本设计围绕以上字段建立单表存储模型，并补充审计字段与同步状态字段，便于跨系统对接与运维。
|
||
|
||
---
|
||
|
||
## 2. 表结构字段说明
|
||
|
||
| 字段名 | 类型 | 允许空 | 默认值 | 说明 |
|
||
| --- | --- | --- | --- | --- |
|
||
| `id` | BIGINT | 否 | 自增 | 主键 ID |
|
||
| `candidate_id` | VARCHAR(64) | 否 | - | 考生 ID（由外部系统同步至对方系统，作为跨系统关联键） |
|
||
| `capstone_no` | VARCHAR(64) | 否 | - | 帽石编号 |
|
||
| `actual_position_x` | DECIMAL(10,3) | 是 | NULL | 实际位置 X（标准/目标坐标） |
|
||
| `actual_position_y` | DECIMAL(10,3) | 是 | NULL | 实际位置 Y（标准/目标坐标） |
|
||
| `measured_x` | DECIMAL(10,3) | 是 | NULL | 实测数据 X（考生现场实测坐标） |
|
||
| `measured_y` | DECIMAL(10,3) | 是 | NULL | 实测数据 Y（考生现场实测坐标） |
|
||
| `setter` | VARCHAR(64) | 是 | NULL | 出题人 |
|
||
| `score` | DECIMAL(6,2) | 是 | NULL | 成绩 |
|
||
| `exam_time` | DATETIME | 否 | - | 考试时间 |
|
||
| `qualified` | TINYINT(1) | 否 | 0 | 是否合格：0-不合格，1-合格 |
|
||
| `sync_status` | TINYINT(1) | 否 | 0 | 同步状态：0-未同步，1-已同步（考生 ID 已同步至对方） |
|
||
| `remark` | VARCHAR(255) | 是 | NULL | 备注 |
|
||
| `create_time` | DATETIME | 否 | CURRENT_TIMESTAMP | 创建时间 |
|
||
| `update_time` | DATETIME | 否 | CURRENT_TIMESTAMP（自动更新） | 更新时间 |
|
||
| `del_flag` | TINYINT(1) | 否 | 0 | 删除标志：0-未删除，1-已删除（软删除） |
|
||
| `deviation_x` | DECIMAL(11,3) | 是 | 派生 | **生成列**：位置偏差 X = `measured_x - actual_position_x` |
|
||
| `deviation_y` | DECIMAL(11,3) | 是 | 派生 | **生成列**：位置偏差 Y = `measured_y - actual_position_y` |
|
||
|
||
### 坐标与偏差说明
|
||
- “实际位置 XY”理解为标准/理论目标坐标；“实测数据 XY”为考生现场测得坐标。
|
||
- `deviation_x / deviation_y` 用 **MySQL 5.7 生成列（VIRTUAL）** 实时计算 `实测 - 实际`，
|
||
不占用额外存储空间，且不会出现“存了偏差却和原始值对不上”的不一致问题。
|
||
- 坐标为 DECIMAL(10,3)，如需更高精度（如亚毫米），可调整为 DECIMAL(12,4) 等。
|
||
|
||
---
|
||
|
||
## 3. 索引设计
|
||
|
||
| 索引名 | 字段 | 类型 | 作用 |
|
||
| --- | --- | --- | --- |
|
||
| `PRIMARY` | `id` | 主键 | 行唯一标识、聚簇索引 |
|
||
| `uk_candidate_capstone_time` | `candidate_id`, `capstone_no`, `exam_time` | 唯一索引 | 防止同一考生在同一时间对同一帽石重复录入 |
|
||
| `idx_candidate` | `candidate_id` | 普通索引 | 按考生维度查询/对账 |
|
||
| `idx_capstone` | `capstone_no` | 普通索引 | 按帽石维度统计 |
|
||
| `idx_exam_time` | `exam_time` | 普通索引 | 按考试时间区间检索 |
|
||
| `idx_qualified` | `qualified` | 普通索引 | 合格/不合格快速筛选 |
|
||
|
||
> 说明：唯一索引包含 `exam_time`（NOT NULL），若业务允许“同一次考试多场次”，可将 `exam_time` 从唯一约束中移除或改为场次字段。
|
||
|
||
---
|
||
|
||
## 4. 关于“考生 ID 同步给对方”
|
||
|
||
- `candidate_id` 是外部系统（对方）的主键/唯一编号，**本表只引用、不生成**。
|
||
- `sync_status` 标记该条记录的考生信息是否已成功同步至对方系统：
|
||
- `0` = 未同步 / 同步中
|
||
- `1` = 已同步
|
||
- 建议同步任务：查询 `sync_status = 0 AND del_flag = 0` 的记录，调用对方接口同步，成功后置 `sync_status = 1`。
|
||
|
||
---
|
||
|
||
## 5. 常用操作示例
|
||
|
||
### 5.1 插入一条考试记录
|
||
```sql
|
||
INSERT INTO t_capstone_exam
|
||
(candidate_id, capstone_no, actual_position_x, actual_position_y,
|
||
measured_x, measured_y, setter, score, exam_time, qualified)
|
||
VALUES
|
||
('STD20260001', 'MS-1001', 12.500, 34.200, 12.480, 34.215,
|
||
'张老师', 92.50, '2026-10-28 09:30:00', 1);
|
||
```
|
||
|
||
### 5.2 查询某考生是否合格
|
||
```sql
|
||
SELECT capstone_no, score, qualified, exam_time
|
||
FROM t_capstone_exam
|
||
WHERE candidate_id = 'STD20260001' AND del_flag = 0
|
||
ORDER BY exam_time DESC;
|
||
```
|
||
|
||
### 5.3 统计合格/不合格人数
|
||
```sql
|
||
SELECT qualified, COUNT(*) AS cnt
|
||
FROM t_capstone_exam
|
||
WHERE del_flag = 0
|
||
GROUP BY qualified;
|
||
```
|
||
|
||
### 5.4 查询偏差较大的记录（实测偏离实际 > 0.1）
|
||
```sql
|
||
SELECT candidate_id, capstone_no,
|
||
actual_position_x, actual_position_y,
|
||
measured_x, measured_y,
|
||
deviation_x, deviation_y
|
||
FROM t_capstone_exam
|
||
WHERE del_flag = 0
|
||
AND (ABS(deviation_x) > 0.1 OR ABS(deviation_y) > 0.1);
|
||
```
|
||
|
||
### 5.5 标记已同步至对方系统
|
||
```sql
|
||
UPDATE t_capstone_exam
|
||
SET sync_status = 1
|
||
WHERE id = 1;
|
||
```
|
||
|
||
### 5.6 软删除（保留数据痕迹）
|
||
```sql
|
||
UPDATE t_capstone_exam
|
||
SET del_flag = 1
|
||
WHERE id = 1;
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 设计要点与扩展建议
|
||
|
||
1. **单表优先**：当前字段均为“一次考试一条记录”的扁平属性，单表即可满足，查询简单、易维护。
|
||
2. **坐标拆分**：XY 拆成独立列而非合并字符串，便于数值计算、偏差统计与范围检索。
|
||
3. **偏差用生成列**：避免冗余存储与数据不一致，MySQL 5.7 原生支持。
|
||
4. **审计字段**：`create_time / update_time / del_flag` 遵循常规后台系统规范，利于排查与软删除。
|
||
5. **可扩展方向**（按需追加）：
|
||
- 若帽石有独立属性（类型、规格、所属区段），可建 `t_capstone`（帽石主数据表），本表 `capstone_no` 作为外键引用；
|
||
- 若需留存每次实测的原始报文/图片，可加 `raw_data` / `image_url` 字段或独立附件表；
|
||
- 若成绩需要分项（理论分、实操分），可拆 `score` 为 `score_theory / score_practice`。
|
||
|
||
---
|
||
|
||
## 7. MySQL 5.7 兼容性确认
|
||
|
||
- `ENGINE=InnoDB` + `utf8mb4`：5.7 原生支持；
|
||
- `DATETIME DEFAULT CURRENT_TIMESTAMP` 与 `ON UPDATE CURRENT_TIMESTAMP`：5.7 支持（5.6 仅 TIMESTAMP 默认可用，故此处用 DATETIME 更稳妥）；
|
||
- `GENERATED ALWAYS AS (...) VIRTUAL` 生成列：5.7 起支持；
|
||
- `TINYINT(1)` 表示布尔：5.7 通用写法。
|