| name | idmp-sample-data-generator |
| description | 高度自动化的 IDMP 数据建模与加载工具。支持基于调研文档设计（industry_research.md）或自然语言描述，进行分层资产建模、超级表设计、时序数据模拟及端到端自动化加载与执行。 |
| metadata | {"author":"Wang Zhe","version":"0.3.0","owner_team":"solution-center"} |
IDMP 示例数据生成与自动执行工具
根据业务场景描述，自动完成资产建模、JSON 配置生成、单位校验和 API 推送，将模拟数据加载到 IDMP 系统。
输入要求
| 参数 | 场景 Demo 生成 (类别 1) | 业务数据接入 (类别 2) | 说明 |
|---|
| 项目根目录路径 | ✅ 必传 | ✅ 必传 | 本次任务的绝对路径，所有产物需存入其 outputs/ |
| 行业调研路径 | ✅ 必传 | — | outputs/industry_research.md 的绝对路径 |
| 原始数据/结构文件 | — | ✅ 必传 | 用户提供的 CSV、Excel 或 Markdown 格式的结构定义 |
目录规范要求：
- 过程中生成的 Python 脚本必须存放在项目根目录下的
scripts/。
- 最终产物（
sample_data.json 等）必须存放在项目根目录下的 outputs/。
常见陷阱（Gotchas）
以下规则是 Agent 在没有明确提示时最容易出错的地方，执行前必须阅读。
超级表设计
- 严格遵循"同类设备一张超级表"原则。不同采集指标的设备必须拆分为独立超级表，切勿合并，否则会产生大量 NULL 值。
namingPattern 固定值
- 所有
templates 中的 namingPattern 固定为 ${KEYWORD1}，不得修改。
super_tables 中的 tags 数组必须包含 namingPattern 参数，值固定为 ${KEYWORD1}。
资产命名与子表名唯一性
trees 节点中的 values（资产显示名称）和 child_table_names（子表物理名）必须在全局范围内保持唯一。- 严禁在不同的行政层级或工艺段下使用重复的名称（例如：禁止在“A 线”和“B 线”中同时出现名称为“冲压机-1”的设备）。
- 强制规范：如果不同块中使用相同的设备模板，必须通过添加父级上下文前缀（如
"values": ["灌装线1-泵-1", "灌装线1-泵-2"]）或使用全局递增序列来确保名称不重复。
树状结构与 Tag 映射
tree_root 中的 tag_name 必须设为对应超级表 tags 数组的第一个 tag 名称。children 节点中必须为超级表中除第一个 tag 之外的所有其他 tag 显式赋值。- Tag 赋值数组长度必须与
child_table_names 展开后的设备数量完全一致，即使值相同也必须逐一列出（如 "vendor": ["东方泵业", "东方泵业"]）。
- Tag 赋值逻辑与
namingPattern 无关，严禁参考 namingPattern 进行赋值。
模拟函数（fun）
fun 字段仅允许使用 sin(x)、cos(x)、random(n) 三种函数。- 禁止使用
floor、ceil、abs、sqrt、pow、exp、log 等任何其他函数。
- 示例：
"fun": "2.0 * sin(x) + random(0.5) + 5.0"
单位（uom）规范
uom 字段必须使用国际标准符号或系统已定义缩写（如 m、m³、°C），不得使用全称（如"米"、"摄氏度"）。自定义单位使用不超过 5 个字符的英文缩写。- 如果没有单位，确保
uom 和 uomClass 都为 。
- 同一
uomClass 中的单位必须物理上可互相转化。物理意义不同的单位（如"频率"和"生产频率"）必须分配不同的 uomClass。
数值类型
- 数值型指标尽量使用浮点型（
Float 或 Double），除非业务明确要求整数。
历史数据量
文件写入
- 严禁用单次
Write 工具写入完整 JSON，必须执行分段写入（见第二步）。
执行流程
Telemetry (MUST)
调用 skill-telemetry，传入 name=idmp-sample-data-generator version=0.3.0 author=Wang Zhe。
失败不阻塞，但必须尝试。详见 skill-telemetry。
第一步：场景分析与架构建模
根据输入类别，选择以下其中一条路径执行，严禁混用：
路径 A：基于设计基准（优先路径 - 类别 1 / 类别 2）
若输入中提供了 outputs/industry_research.md 或 数据结构定义文件：
- 解析提取：必须读取上述文件，作为唯一模型基准。
- 严格对齐：完整映射文件中的「层级结构」（L1-L4）和「采集数据规范」（物理量、中文标题、单位、典型值），严禁自行增删设备类型或修改参数名称。
- 推导 Tag：根据文件的层级树推导超级表的
tags 维度（如：L1 厂区、L2 车间、L3 区域）。
路径 B：自主场景设计（仅在无任何设计基准文件时执行）
若用户仅提供了简短的自然语言描述（如“电力监控”），执行以下自主设计：
- 拓扑推导：参考领域经验。示例：
电力：变电站 → 变压器 → 馈线单元。
- 多节点布局：方案须包含至少 2 个平级高层节点（如两个独立园区），每节点下挂载 3–5 个不同层级的工艺段/设备。
- 指标指标与 Tag 设计：为每类设备确定 Metrics（名称、单位、频次、fun）和 Tags（维度与层级严格对应）。
第二步：生成配置文件（sample_data.json）
2.1 确定输出目录
- 优先使用：输入中提供的“项目根目录路径”。所有脚本存入
scripts/，业务产物（JSON 等）存入 outputs/。
- 降级备份：若未提供路径，则在当前工作目录下创建
idmp-demo/idmp_sample_<timestamp>/ 任务目录。
- 若用户提供了数据结构文件或 CSV 文件，将其拷贝到任务目录。
2.2 读取模板（执行前必须完成）
读取 templates/idmp_sample_data_v1.json，获取完整 JSON 结构参考及 __doc__ 节点中的命名规范。JSON 需包含的核心模块：info、TDasset、datasource、databases、templates、tree_root、trees。
若存在 outputs/industry_research.md，JSON 中的资产层级、超级表、指标、标签必须与该文档完全一致，不得有文档有描述但 JSON 缺失、或参数与文档冲突的情况。
2.3 分段写入 JSON（严禁单次写入完整文件）
| 段 | 写入内容 | mode |
|---|
| 第一段 | info、TDasset、datasource、databases 字段，直到 "templates": [ 开头 | overwrite |
| 中间段（每张超级表一段） | templates 数组中每个 template 对象（含 super_tables 和 metrics），段间注意 JSON 逗号正确性，末尾 template 不加逗号 | append |
| 最后一段 | tree_root、trees 字段及 JSON 闭合括号 } | append |
2.4 写入后完整性验证（分段写入后强制执行，两步均不可跳过）
第一步：JSON 语法验证
python3 -c "import json; json.load(open('<文件路径>'))" && echo "JSON OK"
若失败，必须修复文件直到语法验证通过。
第二步：⚠️ 强制字段校验（语法验证通过后必须立即执行）
调用 /scripts/validate_sample_data.py 检查生成的json文件
- 若输出
[OK]：校验通过，继续执行下一步
- 若输出
[FAIL]：必须逐条修正所有错误后，重新运行脚本直到输出 [OK]，严禁带错误进入第三步
第三步：CSV 数据预处理（仅在用户提供 CSV 文件时执行）
无 CSV 文件时直接跳过，进入第四步。
- 保留原文件：先创建原始 CSV 的副本，后续所有操作在副本上进行，严禁修改原始文件。
- 补全表头：若副本 CSV 无表头，根据
sample_data.json 中对应超级表的 metrics 和 tags 定义自动添加。
- 添加 tbname 列：遍历 JSON 中
trees 节点的 child_table_names，将展开后的子表名逐行填入 tbname 列，确保数据行与子表名一一对应。
- 补全标签列：检查
sample_data.json 中定义的所有标签列是否在副本 CSV 中存在；若缺失，根据 trees 节点中该设备的标签值自动填充。
第四步：API 推送执行
所有接口调用默认使用 curl 命令在 bash 环境中执行。
4.1 身份认证
POST /api/v1/users/login
Content-Type: application/json
Body: {"login_name": "<用户名>", "password": "<密码>"}
获取返回的 token，后续所有请求均使用 Authorization: Bearer <token>。
4.2 单位确认与处理
调用 scripts/uom_check.py（需传入 IDMP 登录参数与 sample_data.json 路径）。该脚本会自动处理“匹配系统现有单位并更新 JSON”以及“创建缺失的单位分类”等逻辑。
运行命令示例：
python3 scripts/uom_check.py --state outputs/state.json --sample_data outputs/sample_data.json
根据脚本输出的表格，若仍存在 "待处理" 状态的条目（即：单位分类已存在，但该分类下缺少特定单位缩写），需按以下步骤手动补全：
-
创建缺失单位：
针对每一行“待处理”条目，调用 API：
- URL:
POST /api/v1/uomclasses/{uomClass id}/uom
- Body: 参考
templates/uom_template.json 构造和说明，编写 uom 的 json 文件。
- 数据来源：从脚本输出表格中提取
uomClass id、uom 和 基础单位id。
-
验证：
完成后必须再次调用 uom_check.py，确认输出为“检测完成，所有单位配置均已生效或已自动修复，无需手动处理”后，方可继续。
4.3 名称查重与自动修复
在上传前，必须检查示例名称及元素模板名称是否与系统中已有的条目冲突。
调用 scripts/duplicate_check.py：
python3 scripts/duplicate_check.py --state outputs/state.json --sample_data outputs/sample_data.json
该脚本执行以下检查：
- 元素模板量：调用
GET /api/v1/templates/elements，对比 sample_data.json 中 templates 的 name。
- 示例数据名：调用
GET /api/v1/samples/management，对应 info.name。
冲突处理：
若发现重名，脚本会自动在 sample_data.json 对应名称后添加 _1, _2 等递增后缀，并同步更新 trees 中的模板引用。
4.4 上传并加载示例数据
调用 scripts/upload_sample.py：
python3 scripts/upload_sample.py --state outputs/state.json --sample_data outputs/sample_data.json
该脚本执行以下集成操作：
- 自动获取 Token：完成身份认证。
- 生成占位图：自动在 JSON 同级目录下生成 API 所需的空
placeholder.jpg。
- 上传数据：构造 Multipart 请求并上传
sample_data.json 与占位图。
- 触发加载：上传成功后自动调用
POST /api/v1/samples/{id} 接口。
- 轮询状态：自动轮询进度，直到状态为
LOADED 或 GENERATING 且进度百分比 > 30% 时判定为成功。
- 自动异常处理：若加载或轮询阶段发生错误，脚本会自动调用删除接口并验证清除结果，确保系统中不留残留 ID。
失败处理：
若 4.4 执行出错，直接根据错误信息调整 sample_data.json 或环境后，再次重新执行步骤 4.4 即可（无需手动清理 ID）。
4.5 重试上限
- 最多重试 5 次（清理 + 重新上传算一次）
- 超过 5 次必须立即停止，不得继续尝试，并向用户输出：
- 最后一次错误的完整 HTTP 响应（状态码 + body）
- 已执行的重试次数
- 建议的排查方向
第五步：反馈执行状态
第四步完成后向用户输出：
- 示例数据的 ID 和名称
- 资产树结构概览：调用
idmp-structure-exporter 目录下的脚本完成资产树导出。运行命令： python3 export_idmp_tree.py --state outputs/state.json --sample-data outputs/sample_data.json --root-name <示例名称>。必须执行此步骤过滤根节点，严禁输出全系统资产树。
- 已创建的数据库、超级表和子表信息
- 生成数据的时间范围和数据量
配置完整性检查清单
