cowork-local/docs/architecture/co4e-split-map-node-property.md

Bản đồ tách StepConfigPanel (ui/co4e_config_panel.py → presentation/co4e/)

• Phạm vi lượt này: chỉ StepConfigPanel (nguyên bản dòng 1-528 của ui/co4e_config_panel.py). Không đụng file nào khác thuộc làn N1 (ui/co4e_tab.py, ui/co4e_canvas.py, docs/architecture/co4e-split-map.md/.json).
• Lý do phải tách thêm, dù chỉ 1 class: StepConfigPanel một mình đã 396 dòng (133-528); cộng thêm module docstring + khối import của một file riêng sẽ vượt trần 400 dòng (CASAN Check 2). Giải pháp: cắt-dán (không viết lại logic) thành 3 file theo trách nhiệm.

File đích

symbol	dòng gốc	file đích	ghi chú
_SECTION_ANIM_MS	27	presentation/co4e/step_config_section.py	hằng số dùng bởi _add_section
_SectionHeader	30-52	presentation/co4e/step_config_section.py	QLabel clickable, không có hành vi nghiệp vụ riêng
_add_section	55-130	presentation/co4e/step_config_section.py	khung ▶/▼ dùng chung cho 4 nhóm trường của StepConfigPanel; không đọc/ghi state của panel
StepConfigPanel (Signal + __init__)	133-313	presentation/co4e/node_property_panel.py	4 Signal (changed/run_node/run_from/delete_node) + dựng toàn bộ form
StepConfigPanel.load_step	316-354	presentation/co4e/node_property_panel.py	nạp Step vào form
StepConfigPanel.clear_step	356-359	presentation/co4e/node_property_panel.py	xoá state, tắt panel
StepConfigPanel._on_edit	362-378	presentation/co4e/node_property_panel.py	ghi field UI ngược vào Step
StepConfigPanel._available_agent_names	380-390	presentation/co4e/node_property_actions_mixin.py (_StepConfigActionsMixin)	staticmethod, dùng bởi _add_subagent/_edit_subagent
StepConfigPanel._add_subagent	392-408	presentation/co4e/node_property_actions_mixin.py
StepConfigPanel._edit_subagent	410-428	presentation/co4e/node_property_actions_mixin.py
StepConfigPanel._del_subagent	430-437	presentation/co4e/node_property_actions_mixin.py
StepConfigPanel._add_attachment	439-453	presentation/co4e/node_property_actions_mixin.py
StepConfigPanel._del_attachment	455-462	presentation/co4e/node_property_actions_mixin.py
StepConfigPanel._ai_draft	464-498	presentation/co4e/node_property_actions_mixin.py	dùng AgentWorker thật (không mock trong __init__)
StepConfigPanel._load_models	500-528	presentation/co4e/node_property_actions_mixin.py	dùng AgentWorker thật

Cách ghép lại: mixin + đa kế thừa

node_property_panel.py:

class StepConfigPanel(_StepConfigActionsMixin, QScrollArea):
    ...

_StepConfigActionsMixin là mixin THUẦN — không __init__ riêng, chỉ đọc/ghi state có sẵn trên self do StepConfigPanel.__init__ định nghĩa (self._step, self._node_id, self.ctx, self.sub_list, self.attach_list, self.instructions_edit, self.gen_btn, self.model_combo, self.load_models_btn).

Khác với bước co4e_canvas_widget.py (Co4ECanvas override nhiều method Qt như paintEvent/mousePressEvent, nên thứ tự mixin-trước-base là bắt buộc để MRO ưu tiên override của mixin): ở đây không có method nào của _StepConfigActionsMixin trùng tên với QScrollArea, nên thứ tự kế thừa không ảnh hưởng hành vi. Giữ thứ tự mixin-trước chỉ để nhất quán quy ước, không phải yêu cầu kỹ thuật bắt buộc.

Import thừa cố ý giữ nguyên

PROVIDER_LABELS (nguyên bản dòng 21, from ..config import PROVIDER_LABELS) không được dùng ở đâu trong toàn bộ ui/co4e_config_panel.py gốc (đã xác minh bằng grep). Vẫn giữ nguyên import này trong node_property_panel.py (chỉ đổi số cấp .. → ...), không xoá, để đúng phạm vi "chỉ dời chỗ" của lượt tách này — xoá một import "thừa" là một quyết định dọn dẹp ngoài phạm vi được giao.

Thay đổi comment/test ngoài phạm vi "chỉ dời chỗ" (ghi riêng, không lẫn vào phần move)

1. Docstring module của 3 file mới (step_config_section.py, node_property_actions_mixin.py, node_property_panel.py) — viết MỚI hoàn toàn bằng tiếng Việt theo quy ước CASAN cho file mới trong presentation/ (mẫu infrastructure/persistence/json/atomic_json_file.py). Đây không phải sửa một comment cũ bị sai do dời chỗ — module docstring nguyên bản (dòng 1-9 của ui/co4e_config_panel.py) mô tả cả file cũ (đã bị chia làm 3), nên mỗi file mới cần một docstring kiến trúc riêng thay vì copy y hệt bản gốc.
2. ui/co4e_config_panel.py (file cũ) — docstring được viết lại (vẫn tiếng Anh, khớp quy ước "sửa file cũ tiếng Anh thì giữ tiếng Anh") để nói rõ StepConfigPanel đã dời đi đâu, thay vì mô tả hành vi như thể class còn định nghĩa tại chỗ — comment cũ sẽ SAI (nói rằng lớp "ở đây" trong khi không còn) nếu giữ nguyên.
3. tests/characterization/test_node_property_panel.py (dòng ~296-307 nguyên bản) — SỬA kỹ thuật patch/restore của case CASE_ADD_SUBAGENT_EMPTY_NAMES_USES_GETTEXT_QUIRK_OK, không đổi bất kỳ assert/hành vi nào. Bản gốc dùng StepConfigPanel.__dict__["_available_agent_names"] để lưu lại method gốc trước khi monkey-patch, rồi gán lại y hệt lúc restore. Sau khi _available_agent_names chuyển vào _StepConfigActionsMixin (mixin riêng), nó không còn nằm trong StepConfigPanel.__dict__ (chỉ được kế thừa qua MRO) → KeyError. Thay bằng: gán đè trực tiếp lên StepConfigPanel (vẫn shadow đúng như cũ), và khi xong dùng del StepConfigPanel._available_agent_names để nó rơi trở lại đúng method kế thừa từ mixin — hành vi quan sát được của test (các assert sub_agents) giữ nguyên 100%, chỉ đổi CÁCH lưu/khôi phục attribute bị monkey-patch. Đây là hệ quả tất yếu của yêu cầu tách mixin trong lượt này (test được viết khi class còn nguyên khối), không phải sửa test để che một thay đổi hành vi.

Xác minh

• .venv/Scripts/python.exe tools/check_co4e.py — chạy TRƯỚC và SAU khi sửa, output giống hệt nhau cả 2 lần (KET QUA: Co4E sap xep lai, khong mat control nao).
• .venv/Scripts/python.exe -m pytest tests/characterization/test_node_property_panel.py -q — 1 passed cả trước (đo trên code gốc, class còn ở ui/co4e_config_panel.py) lẫn sau khi tách.
• .venv/Scripts/python.exe -m pytest tests -q --tb=short -rf --continue-on-collection-errors — 287 passed, 1 skipped sau khi tách (không có test nào khác vỡ vì import StepConfigPanel từ ui/co4e_config_panel.py).
• AST-scan domain/+application/ cho import PySide6/PyQt: KHONG CO.
• Số dòng file mới: node_property_panel.py 293, node_property_actions_mixin.py 202, step_config_section.py 134 — cả 3 đều ≤ 400.