diff --git a/docs/LIMS质检接口字段清单.md b/docs/LIMS质检接口字段清单.md new file mode 100644 index 0000000..ce01109 --- /dev/null +++ b/docs/LIMS质检接口字段清单.md @@ -0,0 +1,127 @@ +# LIMS / 质检接口字段与推送频率清单 + +> 对应 EPIC #2「[M1] 数据准备」子任务 **#17**(0.5d): +> 编制向客户 LIMS/质检系统收集接口字段与推送频率的标准化清单。 +> 质量标签是监督模型(PRD 5.3 质量预测,目标指标如 `Ti_purity`)的 +> **训练目标来源**;一期允许人工录入/批量导入过渡(PRD 13 章风险缓解)。 + +--- + +## 1. 文档目的 + +平台质量预测/寻优模型需要「质量标签」作为监督目标(PRD 5.3): +`工艺参数(DCS 采集) + 质量指标(LIMS/质检) → 质量预测`。 + +本清单用于 M1 阶段向客户收集 **LIMS / 质检系统** 的接口字段与推送频率, +统一质量标签的字段规范与对接方式,避免各批次人工录入口径不一致。 + +--- + +## 2. LIMS / 质检系统对接信息(每套系统填写一份) + +| 字段 | 说明 | 示例 | +| --- | --- | --- | +| 系统名称 | LIMS / 质检系统名称 | 化验中心 LIMS | +| 厂家/版本 | 软件厂家与版本 | 某 LIMS v6.2 | +| 数据库 | 底层数据库类型 | Oracle / SQL Server / MySQL | +| 接口方式 | 支持的数据接口 | 数据库视图 / REST API / 文件导出(CSV/Excel) | +| 接口地址 | 服务地址(如可用) | jdbc:oracle:thin:@10.20.2.15:1521/LIMS | +| 质检流程 | 检验-审核-发布流程 | 化验员录入 → 班长审核 → 发布 | +| 对接负责人 | 客户侧接口人 | 李工(质检科) | + +> 接口方案未定时:**一期先用人工录入/批量导入质量标签,二期补接口**(PRD 13 章)。 + +--- + +## 3. 批次与样品主数据字段 + +| 字段 | 类型 | 约束 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| batch_id | string | 必填,唯一 | 生产批次号(对齐工艺模板 batchKey) | B20260901-001 | +| sample_id | string | 必填,唯一 | 化验样品编号 | S20260901-015 | +| product | string | 必填 | 产品/中间品名称 | 海绵钛 / 四氯化钛 | +| stage | string | 选填 | 工序/工段 | 氯化 / 还蒸 | +| sample_time | datetime | 必填 | 取样时间 | 2026-09-01 08:00 | +| report_time | datetime | 必填 | 检验报告发布时间 | 2026-09-01 14:30 | +| operator | string | 选填 | 检验员/审核人 | 李工 | + +--- + +## 4. 质量指标字段清单(Ti 场景示例) + +客户按质检项目逐行填写(**字段规范对齐工艺模板 `qualityTag` 命名**): + +| 字段 | 类型 | 约束 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| tag_id | string | 必填,唯一 | 质量指标标识(qualityTag) | LIMS.Ti_purity | +| name | string | 必填 | 指标中文名 | 钛纯度 | +| unit | enum | 必填 | 量纲 | % | +| dataType | enum | 必填 | float / int | float | +| pushFrequency | enum | 必填 | 推送频率(见 §6) | per_batch | +| source | enum | 必填 | lims / manual | lims | +| description | string | 选填 | 检测方法/标准 | GB/T 4698(海绵钛化学分析方法) | + +**Ti 一期建议指标(示例,按客户实际化验项目调整)**: + +| tag_id | name | unit | dataType | pushFrequency | source | +| --- | --- | --- | --- | --- | --- | +| LIMS.Ti_purity | 钛纯度 | % | float | per_batch | lims | +| LIMS.Fe | 铁含量 | % | float | per_batch | lims | +| LIMS.Si | 硅含量 | % | float | per_batch | lims | +| LIMS.Mg | 镁含量 | % | float | per_batch | lims | +| LIMS.Cl | 氯含量 | % | float | per_batch | lims | +| LIMS.Granularity | 粒度 | mm | float | per_batch | manual | + +> `qualityTag` 命名约定:`LIMS.<指标标识>`(对齐 PRD 5.3 工艺模板示例 +> `qualityTag: "LIMS.Ti_purity"`),模型目标/特征统一引用该标识。 + +--- + +## 5. 与工艺侧字段的关联 + +质量标签需与工艺侧(DCS 采集)字段按 **batch_id + 时间窗** 对齐: + +- 工艺模板示例:`{processType: "continuous", featureWindow: "shift", + qualityTag: "LIMS.Ti_purity", batchKey: "batch_id"}`(PRD 5.3); +- 特征窗口:质量指标按 **班/批次** 对齐工艺特征(`featureWindow: shift`); +- 对不齐的批次:平台丢弃并告警(防止脏标签污染模型训练)。 + +--- + +## 6. 推送频率分级(pushFrequency) + +| 级别 | 频率 | 适用场景 | +| --- | --- | --- | +| per_batch | 每批次发布后推送 | 常规质量指标(钛纯度、杂质含量) | +| per_shift | 每班汇总推送 | 过程质量快检指标 | +| scheduled | 定时(如每日 08:00) | 日报式质量汇总 | +| realtime | 化验完成后实时推送 | 关键过程控制指标(如在线粒度) | +| manual | 人工录入(60s+ 或按批次) | 一期过渡 / 无接口指标 | + +> 一期未接 LIMS 时:所有指标 `source=manual`,由化验员按批次录入或批量导入 +> (Excel 模板与 §4 字段一致),平台落库后与工艺数据按 batch_id 对齐。 + +--- + +## 7. 填写规范与常见错误 + +| 规范 | 常见错误 | 处理 | +| --- | --- | --- | +| `tag_id` 全局唯一 | 不同批次同一指标命名不一致 | 统一为 `LIMS.<指标>`,导入校验拒绝重复 | +| `batch_id` 与工艺侧一致 | 批次号加前缀/后缀对不齐 | 与 DCS/生产系统确认同一批次口径 | +| `pushFrequency` 用分级枚举 | 自定义频率(如"每两小时") | 归入 scheduled 或新增分级(评审) | +| `report_time` 必填 | 空值导致时间窗对不齐 | 校验拒绝,按 sample_time 兜底并告警 | +| 指标单位统一 | 百分比/小数混用 | 统一为 %(小数转百分比,配置台归一化) | + +--- + +## 8. 收集与校验流程 + +1. 实施工程师发出本清单(可与《数据准备清单》#18 同步); +2. 客户填写 §2–§4 后回传(含指标清单与推送频率); +3. 配置台**导入校验**:tag_id 唯一性、单位枚举、推送频率、batch_id 口径; +4. 校验通过 → 建立 LIMS 对接(二期)或人工录入模板(一期过渡); +5. 质量标签按 `batch_id + featureWindow` 与工艺特征对齐后进入模型训练。 + +> 依赖提示:质量预测需 ≥ 6 个月标注数据(LIMS 对接后补标,PRD 13 章); +> 标注不足时监控类模型(异常检测)可先以阈值+无监督上线。 diff --git a/docs/_check_lims_doc.py b/docs/_check_lims_doc.py new file mode 100644 index 0000000..a08b05a --- /dev/null +++ b/docs/_check_lims_doc.py @@ -0,0 +1,58 @@ +# -*- coding: utf-8 -*- +"""LIMS/质检接口字段清单(docs/LIMS质检接口字段清单.md)一致性检查。 + +检查项: +1. 文档必备章节齐全(对接信息 / 批次主数据 / 质量指标字段 / 推送频率分级); +2. qualityTag 命名约定与 PRD 5.3 工艺模板示例一致(LIMS.Ti_purity); +3. pushFrequency 分级枚举完整(per_batch / per_shift / scheduled / realtime / manual)。 + +用法:python _check_lims_doc.py +""" +import os +import re +import sys + +HERE = os.path.dirname(os.path.abspath(__file__)) +DOC_PATH = os.path.join(HERE, "LIMS质检接口字段清单.md") + +REQUIRED_SECTIONS = [ + "## 2. LIMS / 质检系统对接信息", + "## 3. 批次与样品主数据字段", + "## 4. 质量指标字段清单", + "## 6. 推送频率分级", +] + +PUSH_FREQ = {"per_batch", "per_shift", "scheduled", "realtime", "manual"} + + +def main() -> int: + failures = [] + text = open(DOC_PATH, "r", encoding="utf-8").read() + + # 1) 必备章节 + for sec in REQUIRED_SECTIONS: + if sec not in text: + failures.append(f"缺少必备章节:{sec}") + + # 2) qualityTag 命名约定与 PRD 5.3 一致 + if "LIMS.Ti_purity" not in text: + failures.append("缺少 qualityTag 示例 LIMS.Ti_purity(PRD 5.3 对齐)") + if "`LIMS.<指标标识>`" not in text: + failures.append("缺少 qualityTag 命名约定 `LIMS.<指标标识>`") + + # 3) pushFrequency 枚举完整(从文档表格行抽取枚举值) + declared = set(re.findall(r"\b(per_batch|per_shift|scheduled|realtime|manual)\b", text)) + if declared != PUSH_FREQ: + failures.append(f"pushFrequency 枚举不完整:{sorted(declared)} != {sorted(PUSH_FREQ)}") + + if failures: + print("FAIL") + for f in failures: + print(" -", f) + return 1 + print("OK: 章节/qualityTag 命名/pushFrequency 枚举校验通过") + return 0 + + +if __name__ == "__main__": + sys.exit(main())