@@ -0,0 +1,263 @@
""" #9 孔型：hole_wizard.thread（装饰螺纹）必须可执行并降级为光滑孔。
中文说明
--------
这个文件在测试什么（issue #9「HoleSpec 仅支持简单圆柱、沉头、沉孔」的回归测试）：
1. 背景：SolidWorks 螺纹孔（hole_wizard + thread，如 " M5 螺纹孔 " 、
" 底部螺纹孔 " ）在真实语料里大量存在，修复前 capabilities 把 thread
误判为 " 当前 CDSL runtime 无法表示的几何 " 而报 unsupported_hole_subtype
blocker，≈712 个带 thread 的孔特征因此整体被拒（runtime_eligible=False），
零件无法重建。
实际上 thread 只是装饰信息：
- 数据形态只有 { diameter_mm, depth_mm, class}，没有螺距；
- SolidWorks/STEP 的螺纹孔实体几何就是光滑圆柱孔（装饰螺纹不进
实体、不进 STEP）；
- HoleSpec.from_feature 只读直径/深度/位置/沉头/沉孔，thread 天然
不参与几何计算。
因此正确合同是 " 接受 thread、按光滑孔执行 " ，并在 runtime 记录
info 级诊断（thread_decoration_ignored）便于批量报告追溯降级数量。
2. 本测试套件把 " thread 孔必须可执行且降级为光滑孔 " 固定下来：
- 主契约：带 thread 的 hole_wizard → runtime_eligible=True
（不再被拒绝）；
- 回归护栏：不带 thread 的 hole_wizard → 仍可执行（防止把检查
加过头，所有孔都被拒）；
- 文档契约：hole_wizard + thread 通过 cdsl_schema.json 校验
（字段本就在 holeWizardParams 里）；
- 几何契约：thread 孔切出的体积 = 光滑圆柱孔体积（thread 不建模，
与 SolidWorks/STEP 语义一致）；
- 可追溯：rebuild 结果里带 thread_decoration_ignored 信息诊断
（降级不是静默发生的）。
3. sys.path 说明：把 backend/engine 加入搜索路径，是为了直接 import
cdsl_engine 包做端到端测试（与 test_engine_hole_thread_contract 等
既有测试风格一致）。
函数功能一览
------------
_workplane() 构造默认草图工作平面（XY 平面）。
_rectangle() 构造 XY 平面内的矩形轮廓（2D 多边形）。
_base_block() 构造 10×10×10 拉伸主体文档（体积 1000）。
_thread_wizard_feature() 构造 hole_wizard 特征（with_thread 决定
是否携带 thread 装饰字段）。
_validate_against_cdsl_schema() 对整张文档跑 cdsl_schema.json 校验。
HoleThreadContractTests 见各测试方法 docstring。
"""
from __future__ import annotations
import json
import math
import sys
import tempfile
import unittest
from copy import deepcopy
from pathlib import Path
ROOT = Path ( __file__ ) . resolve ( ) . parents [ 2 ]
sys . path . insert ( 0 , str ( ROOT / " backend " ) )
sys . path . insert ( 0 , str ( ROOT / " backend " / " engine " ) )
import jsonschema # noqa: E402
import cdsl_engine # noqa: E402
from cdsl_engine . runtime import analyze_cdsl , rebuild_cdsl # noqa: E402
# cdsl_schema.json 路径：随 cdsl_engine 包部署。
_SCHEMA_PATH = Path ( cdsl_engine . __file__ ) . parent / " cdsl_schema.json "
_SCHEMA = json . loads ( _SCHEMA_PATH . read_text ( encoding = " utf-8 " ) )
try :
import build123d # noqa: F401
_HAS_BUILD123D = True
except ImportError :
_HAS_BUILD123D = False
# ---------------------------------------------------------------------------
# 测试夹具
# ---------------------------------------------------------------------------
def _workplane ( ) - > dict :
""" 默认草图工作平面：原点在 (0,0,0)、x 轴沿 +X、法向沿 +Z。 """
return { " origin_mm " : [ 0 , 0 , 0 ] , " x_dir " : [ 1 , 0 , 0 ] , " normal " : [ 0 , 0 , 1 ] }
def _rectangle ( minimum : list [ float ] , maximum : list [ float ] ) - > dict :
""" XY 平面内的矩形轮廓（2D 多边形），顶点逆时针。 """
return { " type " : " polygon " , " vertices " : [
[ minimum [ 0 ] , minimum [ 1 ] ] , [ maximum [ 0 ] , minimum [ 1 ] ] ,
[ maximum [ 0 ] , maximum [ 1 ] ] , [ minimum [ 0 ] , maximum [ 1 ] ] ,
] }
def _base_block ( ) - > dict :
""" 10×10×10 拉伸主体：体积 1000，顶面位于 z=10。 """
return {
" schema " : " cad.cdsl.llm.v1 " , " schema_version " : " 1.1.0 " , " kind " : " part " ,
" part_id " : " hole-thread-contract " , " meta " : { " unit " : " mm " } ,
" geometry " : { " sketches " : [ {
" id " : " base " , " workplane " : _workplane ( ) ,
" profile " : _rectangle ( [ - 5 , - 5 ] , [ 5 , 5 ] ) ,
} ] } ,
" features " : [ {
" id " : " base_add " , " atomic_id " : " extrude_add_blind " , " depends_on " : [ ] ,
" params " : { " distance_mm " : 10 } , " sketch_id " : " base " ,
} ] ,
}
def _thread_wizard_feature ( * , with_thread : bool = True ) - > dict :
""" 构造 hole_wizard 特征（仿真实数据 " M5 螺纹孔 " ）。
- with_thread=True：携带 thread 装饰字段
{ " diameter_mm " , " depth_mm " , " class " }（真实语料形态，无螺距）；
- with_thread=False：不写 thread（回归护栏用）。
"""
params : dict = {
" hole_type " : " 底部螺纹孔 " , " diameter_mm " : 5.0 , " depth_mm " : 10.0 ,
" end_condition " : { " type " : " blind " , " solidworks_code " : 0 } ,
" positions " : [ { " mm " : [ 0.0 , 0.0 , 0.0 ] } ] ,
# 合法的 selectorRef（
# 满足机器 schema 的 required: [kind, stable_id, source, confidence]。
" host_face " : { " kind " : " face " , " stable_id " : " top " , " source " : " inferred_from_step " , " confidence " : 1 } ,
}
if with_thread :
params [ " thread " ] = { " diameter_mm " : 5.0 , " depth_mm " : 10.0 , " class " : " 1B " }
return { " id " : " hole " , " atomic_id " : " hole_wizard " , " depends_on " : [ " base_add " ] , " params " : params }
def _validate_against_cdsl_schema ( doc : dict ) - > None :
""" 对整张 CDSL 文档跑 cdsl_schema.json 校验；任何字段不通过都会抛 ValidationError。 """
jsonschema . validate ( instance = doc , schema = _SCHEMA )
# ---------------------------------------------------------------------------
# 测试套件
# ---------------------------------------------------------------------------
class HoleThreadContractTests ( unittest . TestCase ) :
""" thread 装饰螺纹「文档格式-能力边界-运行时-几何」四方合同的回归测试。 """
def test_thread_hole_wizard_is_executable ( self ) - > None :
""" 主契约：带 thread 的 hole_wizard 必须 runtime_eligible。
修复前（当前）：capabilities 报 unsupported_hole_subtype →
runtime_eligible=False → 零件无法重建 → 本测试红灯。
修复后：capabilities 不再拒绝 thread → runtime_eligible=True，
hole 特征无任何 blocker → 绿灯。
"""
cdsl = _base_block ( )
cdsl [ " features " ] . append ( _thread_wizard_feature ( with_thread = True ) )
analysis = analyze_cdsl ( cdsl )
hole = next ( item for item in analysis . feature_results if item . feature_id == " hole " )
self . assertTrue ( analysis . runtime_eligible )
self . assertTrue ( hole . executable )
self . assertNotIn ( " unsupported_hole_subtype " , [ blocker . code for blocker in hole . blockers ] )
def test_threadless_hole_wizard_stays_eligible ( self ) - > None :
""" 回归护栏：不带 thread 的 hole_wizard 仍必须 runtime_eligible。
修复前/修复后均应通过。这条测试防止我们把修复做成 " 所有孔都被拒 "
（例如误删 hole 检查整段）。
"""
cdsl = _base_block ( )
cdsl [ " features " ] . append ( _thread_wizard_feature ( with_thread = False ) )
analysis = analyze_cdsl ( cdsl )
self . assertTrue ( analysis . runtime_eligible )
def test_thread_hole_passes_machine_schema ( self ) - > None :
""" 文档契约：hole_wizard + thread 必须通过 cdsl_schema.json 校验。
thread 字段本就在 holeWizardParams.properties 里（允许携带），
修复策略是 " 能力层接受并降级 " ，不是 " schema 层拒绝 " ——这条测试锁死
文档格式对 thread 的认可，防止未来把 schema 改过头。
"""
cdsl = _base_block ( )
cdsl [ " features " ] . append ( _thread_wizard_feature ( with_thread = True ) )
_validate_against_cdsl_schema ( cdsl )
@unittest.skipUnless ( _HAS_BUILD123D , " build123d is not available " )
def test_thread_hole_cuts_plain_cylindrical_bore ( self ) - > None :
""" 几何契约：thread 孔切出的体积 = 光滑圆柱孔体积（thread 不建模）。
10×10×10 主体，在顶面（z=10）中心打一个 d=2、深 5 的 thread 盲孔：
体积 = 1000 - π·1²·5。若 thread 参与几何（或孔整体被拒），体积断言
都会失败。这条测试锁死 " 降级为光滑孔 " 的几何语义——与 SolidWorks/
STEP 的螺纹孔表示一致。
"""
base = _base_block ( )
with tempfile . TemporaryDirectory ( ) as directory :
root = Path ( directory )
baseline = rebuild_cdsl ( base , root / " baseline.step " )
top_face = next (
item for item in baseline [ " topology_records " ]
if item [ " kind " ] == " face "
and item [ " geometry " ] [ " surface_type " ] == " plane "
and item [ " geometry " ] [ " normal " ] [ 2 ] > 0.9
)
feature = _thread_wizard_feature ( with_thread = True )
feature [ " params " ] [ " diameter_mm " ] = 2.0
feature [ " params " ] [ " depth_mm " ] = 5.0
feature [ " params " ] [ " positions " ] = [ { " mm " : [ 0.0 , 0.0 , 10.0 ] } ]
feature [ " params " ] [ " host_face " ] = {
" kind " : " face " , " stable_id " : " top " , " source " : " inferred_from_step " ,
" confidence " : 1 , " geometry " : top_face [ " geometry " ] ,
}
feature [ " selectors " ] = [
{ " kind " : " face " , " stable_id " : " top " , " source " : " inferred_from_step " ,
" confidence " : 1 , " geometry " : top_face [ " geometry " ] } ,
]
with_hole = deepcopy ( base )
with_hole [ " features " ] . append ( feature )
holed = rebuild_cdsl ( with_hole , root / " thread-hole.step " )
self . assertAlmostEqual ( holed [ " volume_mm3 " ] , 1000 - 5 * math . pi , places = 5 )
@unittest.skipUnless ( _HAS_BUILD123D , " build123d is not available " )
def test_thread_fallback_reports_info_diagnostic ( self ) - > None :
""" 可追溯：thread 降级必须留下 thread_decoration_ignored 信息诊断。
降级不是静默发生的：runtime 在 wizard 模式且携带 thread 时记录
info 级诊断，批量报告（summary-by-diagnostic 或 per-part report）
可以统计降级数量。这条测试锁死 " 降级可观测 " 。
"""
base = _base_block ( )
with tempfile . TemporaryDirectory ( ) as directory :
root = Path ( directory )
baseline = rebuild_cdsl ( base , root / " baseline.step " )
top_face = next (
item for item in baseline [ " topology_records " ]
if item [ " kind " ] == " face "
and item [ " geometry " ] [ " surface_type " ] == " plane "
and item [ " geometry " ] [ " normal " ] [ 2 ] > 0.9
)
feature = _thread_wizard_feature ( with_thread = True )
feature [ " params " ] [ " positions " ] = [ { " mm " : [ 0.0 , 0.0 , 10.0 ] } ]
feature [ " params " ] [ " host_face " ] = {
" kind " : " face " , " stable_id " : " top " , " source " : " inferred_from_step " ,
" confidence " : 1 , " geometry " : top_face [ " geometry " ] ,
}
feature [ " selectors " ] = [
{ " kind " : " face " , " stable_id " : " top " , " source " : " inferred_from_step " ,
" confidence " : 1 , " geometry " : top_face [ " geometry " ] } ,
]
with_hole = deepcopy ( base )
with_hole [ " features " ] . append ( feature )
holed = rebuild_cdsl ( with_hole , root / " thread-hole.step " )
hole_result = next ( item for item in holed [ " feature_results " ] if item [ " feature_id " ] == " hole " )
codes = [ diagnostic [ " code " ] for diagnostic in hole_result [ " diagnostics " ] ]
self . assertIn ( " thread_decoration_ignored " , codes )
if __name__ == " __main__ " :
unittest . main ( )