railwaysystem/sql/capstone_exam_design.md

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

适用数据库：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 插入一条考试记录

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 查询某考生是否合格

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 统计合格/不合格人数

SELECT qualified, COUNT(*) AS cnt
FROM t_capstone_exam
WHERE del_flag = 0
GROUP BY qualified;

5.4 查询偏差较大的记录（实测偏离实际 > 0.1）

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 标记已同步至对方系统

UPDATE t_capstone_exam
SET sync_status = 1
WHERE id = 1;

5.6 软删除（保留数据痕迹）

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 通用写法。