From 600ae67c0b6c57e789f4d62252be9e9e4f38de0c Mon Sep 17 00:00:00 2001
From: Zhaowenlong <zhaowenlong@gdngsk.com>
Date: Tue, 26 May 2026 16:02:24 +0800
Subject: [PATCH] docs: design terminal block model asset

---
 .../2026-05-26-terminal-block-model-design.md | 95 +++++++++++++++++++
 1 file changed, 95 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-05-26-terminal-block-model-design.md

diff --git a/docs/superpowers/specs/2026-05-26-terminal-block-model-design.md b/docs/superpowers/specs/2026-05-26-terminal-block-model-design.md
new file mode 100644
index 0000000..855acbf
--- /dev/null
+++ b/docs/superpowers/specs/2026-05-26-terminal-block-model-design.md
@@ -0,0 +1,95 @@
+# DIN 导轨端子片模型设计
+
+## 目标
+
+生成一个可复用的单片 DIN 导轨端子模型，用于后续复制排列成端子排。交付物同时包含 `.FCStd` 和 `.step`：
+
+- `.FCStd` 作为正式 FreeCAD 设备模板，保存几何和模板端子 LCS 语义。
+- `.step` 作为纯几何交换文件，方便外部软件预览或复用。
+
+## 参考与外观
+
+参考视频中的端子排形态：多个窄端子片紧贴排列，安装在 DIN 导轨上，主体为绿色，上下有接线区域，中间有绿色窗口/主体分隔。
+
+第一版采用可复用端子片深度，不追求品牌级完全复刻。模型需要清楚表达：
+
+- 绿色主体外壳。
+- 白色上接线区。
+- 黑色下接线区。
+- 绿色透明或浅绿色中窗。
+- 背部 DIN 导轨卡槽/让位。
+- 上下各一个接线孔/螺钉视觉特征。
+
+## 尺寸
+
+单片端子采用常见模块端子比例：
+
+- 宽度：5.2 mm，作为后续端子排复制间距。
+- 高度：36 mm。
+- 深度：42 mm。
+
+坐标约定：
+
+- X 轴为宽度方向，后续端子排按 X 方向复制。
+- Y 轴为深度方向。
+- Z 轴为高度方向。
+- 模型原点位于端子片底部中心附近，便于在 DIN 导轨上排列。
+
+## FreeCAD 模板端子语义
+
+`.FCStd` 内包含两个模板端子 LCS：
+
+| 对象名 | 槽位名 | 标签 | 位置语义 |
+| --- | --- | --- | --- |
+| `Terminal_Top` | `Top` | `Top` | 上接线口中心 |
+| `Terminal_Bottom` | `Bottom` | `Bottom` | 下接线口中心 |
+
+每个 LCS 写入：
+
+- `Role = "Terminal"`
+- `CanWire = true`
+- `QetTemplateSlotName`
+- `QetTerminalLabel`
+- `QetTerminalType = "generic"`
+
+模板端子禁止写入工程级字段：
+
+- `QetProjectUuid`
+- `QetElementUuid`
+- `QetTerminalUuid`
+- `QetInstanceId`
+
+端子方向采用现有 FreeCADExchange 约定：LCS 本地 `+Z` 表示出线方向。第一版上下端子均让 `+Z` 朝模型正面外侧的可接线方向，避免后续手动布线从设备内部穿出。
+
+## 输出位置
+
+生成文件放在：
+
+```text
+data/examples/qet_terminal_block/
+```
+
+计划文件：
+
+- `qet_terminal_slice.FCStd`
+- `qet_terminal_slice.step`
+- `create_qet_terminal_slice.py`
+- `README.md`
+
+`create_qet_terminal_slice.py` 用 FreeCAD Python API 生成几何、端子 LCS 和导出文件，便于后续调整尺寸或重新生成。
+
+## 验收标准
+
+1. 生成的 `.FCStd` 能被 FreeCAD 打开。
+2. 文档中能看到端子片几何主体。
+3. 文档中存在 `Terminal_Top` 和 `Terminal_Bottom` 两个模板端子对象。
+4. 两个模板端子对象包含 `Role="Terminal"` 和 `CanWire=true`。
+5. `.step` 文件成功导出并包含端子片主要几何。
+6. 文件生成不修改现有代码模块，也不依赖数据库或旧 3D 场景表。
+
+## 自检
+
+- 本设计只创建模型资产，不改 QET/FreeCAD 协同代码。
+- 端子绑定语义遵守第一版约束，只在 FCStd 模板中保存模板槽位，不保存工程绑定字段。
+- `.FCStd` 是正式资产，`.step` 是同步几何交换文件。
+- 尺寸、输出路径、对象命名和验收标准均已明确。