# 帽石系统 - 数据表结构设计文档

> 适用数据库：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 通用写法。