aivfo-tl-3.0/sql/migrations/2026-06-17-autofocus-data-layer.sql

-- =============================================================================
-- 自动对焦数据层迁移（依据 需求文档/12-工作计划表与自动对焦数据设计.md §2.7/2.8）
-- 库：aivfo_tl_setting（与 tl_setting/house_well_setting/house_photograph_setting 同库）
-- 引擎/字符集：InnoDB / utf8mb4 / utf8mb4_0900_ai_ci（MySQL 8）
--
-- ★适用场景（G4-2 已合并 base）：
--   · 全新部署 → 不需要本文件：base 脚本 sql/aivfo_tl_setting.sql 已含本表+扩列，
--     跑 sql/init-database.sh 一次到位。
--   · 已部署旧库增量升级 → 才跑本文件（旧库无这些表/列时）。
--   ⚠️ MySQL 8 的 ADD COLUMN 不支持 IF NOT EXISTS：旧库重跑前先手动 DESC 判断列是否已存在，
--      否则报 Duplicate column。本地 SQLite 列迁移另见 待验证清单 V-046 / G4-3。
-- =============================================================================

-- -----------------------------------------------------------------------------
-- 1) 新增表：house_autofocus_calibration
--    本地自动对焦标定结果的库内镜像。真相源仍为机旁 autofocustool/calibration.json。
--    scene 区分：0=出厂基准(每well一条,upsert)  1=日常对焦(append,受清理周期约束)。
--    清理约定：tl_setting.clean_autofocus_data(默认30天) 的清理任务【只删 scene=1】，
--    scene=0 基准永久保留（见 §2.7 约束1）。
-- -----------------------------------------------------------------------------
DROP TABLE IF EXISTS `house_autofocus_calibration`;
CREATE TABLE `house_autofocus_calibration` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '自增id',
  `tl_sn` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NOT NULL COMMENT 'tl设备sn',
  `house_sn` int NOT NULL COMMENT '仓室编号:1-11(11号为缓冲瓶,无相机不对焦)',
  `well_sn` int NOT NULL COMMENT 'well编号:1-16',
  `scene` int NOT NULL COMMENT '场景:0=出厂基准 1=日常对焦',
  `focus_z` int NOT NULL COMMENT '对焦算出的最清晰层Z脉冲(锚点)',
  `exposure` int NULL DEFAULT NULL COMMENT '曝光(100us单位)',
  `horizontal_pulse` int NULL DEFAULT NULL COMMENT '水平电机位置脉冲',
  `peak_ratio` decimal(10, 3) NULL DEFAULT NULL COMMENT '清晰度峰比(合格判据,阈值见tl_setting.focus_peak_ratio_threshold)',
  `circle_found` tinyint NULL DEFAULT NULL COMMENT '是否检到well圆:0否1是',
  `center_offset_pct` decimal(10, 3) NULL DEFAULT NULL COMMENT '居中偏移百分比',
  `calib_time` datetime NOT NULL COMMENT '标定时间',
  `source` varchar(32) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NOT NULL DEFAULT 'LOCAL_JSON' COMMENT '结果来源(LOCAL_JSON=本地标定镜像)',
  `note` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NULL DEFAULT NULL COMMENT '备注',
  `create_by` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NULL DEFAULT NULL COMMENT '创建人',
  `create_time` datetime NULL DEFAULT NULL COMMENT '创建时间',
  `update_by` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NULL DEFAULT NULL COMMENT '修改人',
  `update_time` datetime NULL DEFAULT NULL COMMENT '修改时间',
  `deleted` timestamp NULL DEFAULT NULL COMMENT '已删除:操作时间戳(mybatis-plus逻辑删除约定)',
  `platform_id` int NULL DEFAULT NULL COMMENT '操作终端',
  PRIMARY KEY (`id`) USING BTREE,
  INDEX `idx_query`(`tl_sn`, `house_sn`, `well_sn`, `calib_time`) USING BTREE COMMENT '按设备/well/时间查询',
  INDEX `idx_scene`(`tl_sn`, `scene`, `deleted`) USING BTREE COMMENT '区分基准/日常+清理'
) ENGINE = InnoDB CHARACTER SET = utf8mb4 COLLATE = utf8mb4_0900_ai_ci COMMENT = '本地自动对焦标定结果镜像(scene:0基准/1日常);真相源为机旁calibration.json' ROW_FORMAT = Dynamic;
-- 注：scene=0 基准"每well唯一(upsert)"的唯一性，由 M2-04 实现时按 mybatis-plus 逻辑删除
--     (deleted) 与业务 upsert 逻辑保证；此处不加 (tl_sn,house_sn,well_sn,scene) 硬唯一键，
--     以免与 scene=1 的多条追加/逻辑删除占位冲突。最终策略在 M2-04 子计划确认。

-- -----------------------------------------------------------------------------
-- 2) tl_setting 设备级对焦配置扩列（依据 §2.5/2.8）
--    层间距=机器工艺值,不给默认(缺失须报错,不用魔法数;EEPROM仅参考);
--    层数/下移/峰比阈值=业务参数,给默认。
-- -----------------------------------------------------------------------------
ALTER TABLE `tl_setting`
  ADD COLUMN `focus_layer_spacing_pulse` int NULL DEFAULT NULL COMMENT '拍照层间距脉冲(工艺值,权威来源;缺失须报错,EEPROM仅参考)',
  ADD COLUMN `focus_layer_count` int NOT NULL DEFAULT 5 COMMENT '拍照总层数(业务参数)' AFTER `focus_layer_spacing_pulse`,
  ADD COLUMN `focus_layer_down` int NOT NULL DEFAULT 2 COMMENT '对焦起点下移层数(清晰层在第几层之上)' AFTER `focus_layer_count`,
  ADD COLUMN `focus_peak_ratio_threshold` decimal(10, 3) NOT NULL DEFAULT 1.200 COMMENT '标定合格峰比阈值(不同客户可松紧)' AFTER `focus_layer_down`;

-- -----------------------------------------------------------------------------
-- 2b) tl_setting 场景B产线本地自动对焦安全门（M2-06，依据 计划 M2-06 小节 + 03 §6 三上线前置）
--    设备级安全门：算法严谨性未在真机验证通过前(74000 伪峰/真胚胎峰比/EEPROM 回写三前置)，
--    默认 0=关闭本地自动对焦 → 场景B走降级(按 scene=0 基准/既有位置拍照，不做实际对焦)，
--    避免错误对焦污染真实胚胎拍摄；三前置有结论后人工置 1=启用本地对焦(场景B正式上线)。
--    ⚠ 默认 0(安全)：与 03 §2「场景B 稳定后再启用」一致，不在 M2 强行打开。
-- -----------------------------------------------------------------------------
ALTER TABLE `tl_setting`
  ADD COLUMN `local_autofocus_enabled` int NOT NULL DEFAULT 0 COMMENT '场景B本地自动对焦安全门:0关闭(降级按基准/既有位置拍照,默认安全) 1启用(本地四步标定对焦);三上线前置有结论后再开' AFTER `focus_peak_ratio_threshold`;

-- -----------------------------------------------------------------------------
-- 3) house_well_setting well级可选覆盖列（依据 §2.5）
--    留空=继承 tl_setting 设备级。下移层数复用现有 move_down_layer，不新增。
-- -----------------------------------------------------------------------------
ALTER TABLE `house_well_setting`
  ADD COLUMN `focus_layer_spacing_pulse` int NULL DEFAULT NULL COMMENT 'well级层间距覆盖(空=继承设备级)',
  ADD COLUMN `focus_layer_count` int NULL DEFAULT NULL COMMENT 'well级层数覆盖(空=继承设备级)' AFTER `focus_layer_spacing_pulse`;

-- =============================================================================
-- 配置解析就近优先(§2.5)：well级(house_well_setting,非空) > 设备级(tl_setting) > 报错。
--   层间距 focus_layer_spacing_pulse：两级皆空 → 报错"设备{tl_sn}对焦层间距未配置,请先初始化"。
--   下移层数：house_well_setting.move_down_layer 非空则覆盖 tl_setting.focus_layer_down。
-- 拍摄层位置公式(§2.4)：
--   对焦起点(第0层)=FocusZ - focus_layer_down × focus_layer_spacing_pulse
--   第i层=对焦起点 + i × focus_layer_spacing_pulse  (i=0..focus_layer_count-1)
-- =============================================================================