LightWork3D/docs/superpowers/plans/2026-05-20-freecad-fcstd-template-authoring.md

# FreeCAD FCStd Template Authoring Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Add a FreeCADExchange Python authoring tool that turns imported STEP/STP/STE geometry into reusable FCStd equipment templates with electrical terminal LCS semantics.

**Architecture:** Keep the feature in the FreeCADExchange Python layer. `TemplateAuthoring.py` owns template terminal creation, validation, and command registration; `TerminalObjects.py` remains the shared low-level semantic property helper; `InitGui.py` registers authoring commands when FreeCAD starts.

**Tech Stack:** FreeCAD Python API, `Part::LocalCoordinateSystem` / `PartDesign::CoordinateSystem`, Python `unittest`, existing FreeCADExchange command registration pattern.

---

## File Structure

- Create: `src/Mod/FreeCADExchange/TemplateAuthoring.py`
  - Build template terminal LCS objects.
  - Write template-only electrical semantics.
  - Validate template terminal objects.
  - Register FreeCAD commands.
- Modify: `src/Mod/FreeCADExchange/CMakeLists.txt`
  - Add `TemplateAuthoring.py` to `FreeCADExchange_Scripts`.
- Modify: `src/Mod/FreeCADExchange/InitGui.py`
  - Import `TemplateAuthoring`.
  - Call `TemplateAuthoring.register_commands()`.
- Create: `tests/python/freecad_exchange_template_authoring_test.py`
  - Fake enough FreeCAD API to test terminal creation and validation without launching FreeCAD.
- Modify: `docs/FreeCAD 端子显示连线保存回写开发文档.md`
  - Add development result entry after implementation.

---

### Task 1: Add Failing Tests For Template Terminal Creation

**Files:**
- Create: `tests/python/freecad_exchange_template_authoring_test.py`

- [ ] **Step 1: Write the failing test file**

Create `tests/python/freecad_exchange_template_authoring_test.py` with:

```python
import importlib
import sys
import types
import unittest
from pathlib import Path


REPO_ROOT = Path(__file__).resolve().parents[2]
MODULE_DIR = REPO_ROOT / "src" / "Mod" / "FreeCADExchange"
if str(MODULE_DIR) not in sys.path:
    sys.path.insert(0, str(MODULE_DIR))


def _install_fake_freecad():
    class Vector:
        def __init__(self, x=0.0, y=0.0, z=0.0):
            self.x = float(x)
            self.y = float(y)
            self.z = float(z)

    class Rotation:
        def __init__(self, axis=None, angle=None):
            self.Axis = axis
            self.Angle = angle

    class Placement:
        def __init__(self, base=None, rotation=None):
            self.Base = base
            self.Rotation = rotation

    fake_freecad = types.ModuleType("FreeCAD")
    fake_freecad.Vector = Vector
    fake_freecad.Rotation = Rotation
    fake_freecad.Placement = Placement
    fake_freecad.ActiveDocument = None
    fake_freecad.Console = types.SimpleNamespace(
        PrintMessage=lambda *args, **kwargs: None,
        PrintWarning=lambda *args, **kwargs: None,
        PrintError=lambda *args, **kwargs: None,
    )
    sys.modules["FreeCAD"] = fake_freecad

    fake_freecadgui = types.ModuleType("FreeCADGui")
    fake_freecadgui.addCommand = lambda *args, **kwargs: None
    fake_freecadgui.Selection = types.SimpleNamespace(getSelectionEx=lambda: [])
    sys.modules["FreeCADGui"] = fake_freecadgui


class FakeViewObject:
    def __init__(self):
        self.Visibility = True
        self.ShapeColor = None


class FakeObject:
    def __init__(self, name, type_id):
        self.Name = name
        self.Label = name
        self.TypeId = type_id
        self.PropertiesList = []
        self.Group = []
        self.ViewObject = FakeViewObject()
        self.Placement = None

    def isDerivedFrom(self, type_name):
        if self.TypeId == type_name:
            return True
        if type_name == "App::DocumentObjectGroup":
            return self.TypeId == "App::DocumentObjectGroup"
        if type_name == "App::LocalCoordinateSystem":
            return self.TypeId in {"Part::LocalCoordinateSystem", "PartDesign::CoordinateSystem"}
        return False

    def addProperty(self, prop_type, prop_name, group_name, description):
        if prop_name not in self.PropertiesList:
            self.PropertiesList.append(prop_name)

    def addObject(self, child):
        if child not in self.Group:
            self.Group.append(child)


class FakeDocument:
    def __init__(self):
        self.Name = "TemplateDoc"
        self.Objects = []
        self.recomputed = False

    def addObject(self, type_name, name):
        obj = FakeObject(name, type_name)
        self.Objects.append(obj)
        return obj

    def getObject(self, name):
        for obj in self.Objects:
            if obj.Name == name:
                return obj
        return None

    def recompute(self):
        self.recomputed = True


def _reload_modules():
    for name in ["TerminalObjects", "TemplateAuthoring"]:
        sys.modules.pop(name, None)
    import TemplateAuthoring
    return TemplateAuthoring


class TemplateAuthoringTest(unittest.TestCase):
    def test_create_template_terminal_writes_lcs_semantics(self):
        _install_fake_freecad()
        template_authoring = _reload_modules()
        app = sys.modules["FreeCAD"]
        doc = FakeDocument()

        terminal = template_authoring.create_template_terminal(
            doc,
            "P1",
            app.Vector(10, 20, 30),
            terminal_type="primary",
        )

        self.assertEqual("Terminal_P1", terminal.Name)
        self.assertEqual("P1", terminal.Label)
        self.assertEqual("Terminal", terminal.Role)
        self.assertTrue(terminal.CanWire)
        self.assertEqual("P1", terminal.QetTemplateSlotName)
        self.assertEqual("P1", terminal.QetTerminalLabel)
        self.assertEqual("primary", terminal.QetTerminalType)
        self.assertEqual(10.0, terminal.Placement.Base.x)
        self.assertEqual(20.0, terminal.Placement.Base.y)
        self.assertEqual(30.0, terminal.Placement.Base.z)
        self.assertTrue(doc.recomputed)

    def test_validate_template_terminals_reports_missing_slot_name(self):
        _install_fake_freecad()
        template_authoring = _reload_modules()
        doc = FakeDocument()
        terminal = doc.addObject("Part::LocalCoordinateSystem", "BrokenTerminal")
        terminal.addProperty("App::PropertyString", "Role", "QET Template", "role")
        terminal.Role = "Terminal"
        terminal.addProperty("App::PropertyBool", "CanWire", "QET Template", "can wire")
        terminal.CanWire = True

        report = template_authoring.validate_template_terminals(doc)

        self.assertEqual(1, report["total_terminals"])
        self.assertEqual(0, report["valid_terminals"])
        self.assertEqual(1, len(report["warnings"]))
        self.assertIn("QetTemplateSlotName", report["warnings"][0])


if __name__ == "__main__":
    unittest.main()
```

- [ ] **Step 2: Run the test and verify RED**

Run:

```powershell
python -m unittest tests.python.freecad_exchange_template_authoring_test -v
```

Expected: fails with `ModuleNotFoundError: No module named 'TemplateAuthoring'`.

---

### Task 2: Implement TemplateAuthoring Core

**Files:**
- Create: `src/Mod/FreeCADExchange/TemplateAuthoring.py`

- [ ] **Step 1: Create the implementation**

Create `src/Mod/FreeCADExchange/TemplateAuthoring.py` with:

```python
# FreeCADExchange FCStd template authoring helpers.

import FreeCAD as App

try:
    import FreeCADGui as Gui
except ImportError:
    Gui = None

import TerminalObjects


TEMPLATE_PROPERTY_GROUP = "QET Template"
DEFAULT_TERMINAL_TYPE = "generic"


class TemplateAuthoringError(RuntimeError):
    pass


def _safe_slot_name(slot_name):
    value = (slot_name or "").strip()
    if not value:
        raise TemplateAuthoringError("Terminal slot name is required.")
    return value


def _terminal_object_name(slot_name):
    return "Terminal_{0}".format(TerminalObjects.safe_token(slot_name))


def _ensure_template_property(obj, prop_name, value, prop_type="App::PropertyString"):
    if prop_type == "App::PropertyBool":
        TerminalObjects.ensure_bool_property(
            obj,
            prop_name,
            TEMPLATE_PROPERTY_GROUP,
            "QET template terminal property",
            bool(value),
        )
    else:
        TerminalObjects.ensure_string_property(
            obj,
            prop_name,
            TEMPLATE_PROPERTY_GROUP,
            "QET template terminal property",
            value,
        )


def set_template_terminal_semantics(obj, slot_name, label="", terminal_type=DEFAULT_TERMINAL_TYPE):
    slot_name = _safe_slot_name(slot_name)
    label = (label or "").strip() or slot_name
    terminal_type = (terminal_type or "").strip() or DEFAULT_TERMINAL_TYPE

    _ensure_template_property(obj, "Role", TerminalObjects.TERMINAL_ROLE)
    _ensure_template_property(obj, "CanWire", True, prop_type="App::PropertyBool")
    _ensure_template_property(obj, "QetTemplateSlotName", slot_name)
    _ensure_template_property(obj, "QetTerminalLabel", label)
    _ensure_template_property(obj, "QetTerminalType", terminal_type)
    obj.Label = label
    return obj


def create_template_terminal(doc, slot_name, position, rotation=None, label="", terminal_type=DEFAULT_TERMINAL_TYPE):
    if doc is None:
        raise TemplateAuthoringError("An active FreeCAD document is required.")

    slot_name = _safe_slot_name(slot_name)
    if position is None:
        raise TemplateAuthoringError("A terminal position is required.")

    if rotation is None:
        rotation = App.Rotation()
    placement = App.Placement(position, rotation)
    terminal = TerminalObjects.create_lcs_object(
        doc,
        _terminal_object_name(slot_name),
        placement=placement,
        label=(label or slot_name),
    )
    set_template_terminal_semantics(
        terminal,
        slot_name,
        label=label or slot_name,
        terminal_type=terminal_type,
    )
    try:
        terminal.ViewObject.ShapeColor = (0.0, 0.75, 1.0)
    except Exception:
        pass
    doc.recompute()
    return terminal


def is_template_terminal(obj):
    if obj is None:
        return False
    return TerminalObjects.is_terminal_hint_object(obj)


def _has_property(obj, prop_name):
    return prop_name in getattr(obj, "PropertiesList", [])


def validate_template_terminals(doc):
    report = {
        "document_name": getattr(doc, "Name", ""),
        "total_terminals": 0,
        "valid_terminals": 0,
        "warnings": [],
        "terminals": [],
    }
    if doc is None:
        report["warnings"].append("No active FreeCAD document.")
        return report

    for obj in list(getattr(doc, "Objects", []) or []):
        if not is_template_terminal(obj):
            continue

        report["total_terminals"] += 1
        slot_name = getattr(obj, "QetTemplateSlotName", "").strip()
        can_wire = bool(getattr(obj, "CanWire", False))
        item = {
            "name": getattr(obj, "Name", ""),
            "label": getattr(obj, "Label", ""),
            "slot_name": slot_name,
            "can_wire": can_wire,
        }
        report["terminals"].append(item)

        valid = True
        if not _has_property(obj, "QetTemplateSlotName") or not slot_name:
            report["warnings"].append(
                "Template terminal {0} is missing QetTemplateSlotName.".format(
                    getattr(obj, "Name", "")
                )
            )
            valid = False
        if not can_wire:
            report["warnings"].append(
                "Template terminal {0} has CanWire disabled.".format(
                    getattr(obj, "Name", "")
                )
            )
            valid = False
        if valid:
            report["valid_terminals"] += 1

    return report


def _selection_position():
    if Gui is None:
        return None
    try:
        selection_ex = Gui.Selection.getSelectionEx()
    except Exception:
        return None
    if not selection_ex:
        return None

    picked = selection_ex[0]
    picked_points = list(getattr(picked, "PickedPoints", []) or [])
    if picked_points:
        return picked_points[0]

    obj = getattr(picked, "Object", None)
    shape = getattr(obj, "Shape", None)
    bound_box = getattr(shape, "BoundBox", None)
    if bound_box is None:
        return None
    return App.Vector(
        (bound_box.XMin + bound_box.XMax) * 0.5,
        (bound_box.YMin + bound_box.YMax) * 0.5,
        (bound_box.ZMin + bound_box.ZMax) * 0.5,
    )
```

- [ ] **Step 2: Run the focused test and verify GREEN**

Run:

```powershell
python -m unittest tests.python.freecad_exchange_template_authoring_test -v
```

Expected: both tests pass.

---

### Task 3: Add FreeCAD Commands And Registration

**Files:**
- Modify: `src/Mod/FreeCADExchange/TemplateAuthoring.py`
- Modify: `src/Mod/FreeCADExchange/InitGui.py`
- Modify: `src/Mod/FreeCADExchange/CMakeLists.txt`

- [ ] **Step 1: Extend TemplateAuthoring.py with commands**

Append this code to `src/Mod/FreeCADExchange/TemplateAuthoring.py`:

```python
class CommandAddTemplateTerminal:
    def GetResources(self):
        return {
            "MenuText": "Add Template Terminal",
            "ToolTip": "Create a reusable electrical terminal LCS for an FCStd equipment template",
        }

    def IsActive(self):
        return App.ActiveDocument is not None and Gui is not None

    def Activated(self):
        if Gui is None:
            return
        position = _selection_position()
        if position is None:
            App.Console.PrintWarning(
                "Select a model point or model object before adding a template terminal.\n"
            )
            return

        slot_name = "T{0}".format(len(validate_template_terminals(App.ActiveDocument)["terminals"]) + 1)
        try:
            create_template_terminal(App.ActiveDocument, slot_name, position)
            App.Console.PrintMessage(
                "[FreeCADExchange] Created template terminal {0}. Rename QetTemplateSlotName if needed.\n".format(slot_name)
            )
        except Exception as exc:
            App.Console.PrintError(
                "[FreeCADExchange] template terminal creation failed: {0}\n".format(exc)
            )


class CommandValidateTemplateTerminals:
    def GetResources(self):
        return {
            "MenuText": "Validate Template Terminals",
            "ToolTip": "Validate electrical terminal LCS objects in the current FCStd template",
        }

    def IsActive(self):
        return App.ActiveDocument is not None

    def Activated(self):
        report = validate_template_terminals(App.ActiveDocument)
        App.Console.PrintMessage(
            "[FreeCADExchange] Template terminals: {0} total, {1} valid\n".format(
                report["total_terminals"],
                report["valid_terminals"],
            )
        )
        for warning in report["warnings"]:
            App.Console.PrintWarning("[FreeCADExchange] {0}\n".format(warning))


_COMMANDS_REGISTERED = False


def register_commands():
    global _COMMANDS_REGISTERED
    if _COMMANDS_REGISTERED:
        return
    if Gui is None:
        return
    Gui.addCommand("QET_Template_AddTerminal", CommandAddTemplateTerminal())
    Gui.addCommand("QET_Template_ValidateTerminals", CommandValidateTemplateTerminals())
    _COMMANDS_REGISTERED = True


register_commands()
```

- [ ] **Step 2: Modify InitGui.py**

Add the import near the existing FreeCADExchange imports:

```python
import TemplateAuthoring
```

Add registration after the existing command registration blocks:

```python
try:
    TemplateAuthoring.register_commands()
except Exception:
    pass
```

- [ ] **Step 3: Modify CMakeLists.txt**

Add `TemplateAuthoring.py` to `FreeCADExchange_Scripts`:

```cmake
    TemplateAuthoring.py
```

Place it beside `TemplateSemantics.py`.

- [ ] **Step 4: Verify syntax and tests**

Run:

```powershell
python -m py_compile src/Mod/FreeCADExchange/TemplateAuthoring.py src/Mod/FreeCADExchange/InitGui.py
python -m unittest tests.python.freecad_exchange_template_authoring_test -v
```

Expected: py_compile exits 0, tests pass.

---

### Task 4: Add Development Result Documentation

**Files:**
- Modify: `docs/FreeCAD 端子显示连线保存回写开发文档.md`

- [ ] **Step 1: Add the result entry**

Append to the development log section:

```markdown
- 2026-05-20：新增 FCStd 设备模板制作基础能力，支持把模型上的点位创建为带 `Role="Terminal"`、`CanWire=true`、`QetTemplateSlotName` 的模板端子 LCS；已用单元测试验证端子语义写入和模板校验逻辑。
```

- [ ] **Step 2: Run final verification**

Run:

```powershell
python -m py_compile src/Mod/FreeCADExchange/TemplateAuthoring.py src/Mod/FreeCADExchange/InitGui.py src/Mod/FreeCADExchange/TerminalObjects.py
python -m unittest tests.python.freecad_exchange_template_authoring_test tests.python.freecad_exchange_template_semantics_test tests.python.freecad_exchange_manual_wiring_test -v
```

Expected: all tests pass.

- [ ] **Step 3: Commit**

Run:

```powershell
git add src/Mod/FreeCADExchange/TemplateAuthoring.py src/Mod/FreeCADExchange/InitGui.py src/Mod/FreeCADExchange/CMakeLists.txt tests/python/freecad_exchange_template_authoring_test.py "docs/FreeCAD 端子显示连线保存回写开发文档.md" "docs/FreeCAD 二次开发说明.md" docs/superpowers/specs/2026-05-20-freecad-fcstd-template-authoring-design.md docs/superpowers/plans/2026-05-20-freecad-fcstd-template-authoring.md
git commit -m "feature/FCStd设备模板端子制作-zwl-0520"
```

Expected: commit succeeds and does not include `artifacts/`, `video_frames/`, or generated cache files.

---

## Self-Review

Spec coverage:

- FCStd as formal asset is covered by Tasks 2 and 4.
- Template-only terminal semantics are covered by Task 1 and Task 2.
- Command entry points are covered by Task 3.
- Existing project import flow remains unchanged.

Placeholder scan:

- The plan contains no unresolved placeholders or open-ended implementation steps.

Type consistency:

- The planned module exposes `create_template_terminal`, `set_template_terminal_semantics`, `validate_template_terminals`, and `register_commands`.
- Command names are `QET_Template_AddTerminal` and `QET_Template_ValidateTerminals`.