# DXFKit 本次交付范围

SPLINE 次数（71）必须显式给出；缺失时保留记录、拒绝轮廓并报告不完整。`bounds()` 只估计原始字段，不等于 checked 几何验证；见 [r2 收敛](r2-submission-20261022.md)。

本页范围基础上，当前 main 已补[最近一次顾问整改](advisor-review-20261022.md)：Closed/Periodic SPLINE 明确拒绝、权重严格匹配、缺 ENDBLK 显式恢复、椭圆轴比限 `(0,1]`、多段线非零宽度/厚度报告中心线检查限制，以及全局展开预算。旧申报标签保持历史提交。

本次交付定位：**面向 MoonBit 开发者的 ASCII DXF 二维轮廓读取与辅助检查库**。核心为七类轮廓实体、受限二维 SOLID/TRACE 边界和普通 INSERT，附带 `check`、`svg`、`stats` 三个 CLI 命令、浏览器演示、公开接口调用示例及回归案例。

本文是项目的交付约定，不是主办方的额外要求。源码版本为 0.1.1，本次修订尚未发布到 Mooncakes。

## 处理阶段和完成含义

ASCII 字节 → 组码及诊断 → 段、记录和子类 → 范围内实体字段 → XY 折线及块展开 → 报告和 SVG。

文件可读取、实体已解码、几何已参与检查是三个不同结论。文件头中的 ACADVER 不会使一个文件自动获得全版本、全实体或全部字段的兼容保证。47 个第三方文件仅验证这些具体输入；六类最小问题案例另有预期、实际结果和自动断言，见[修复验证](delivery-verification.md)。

输入恢复或覆盖限制通过 `Report::has_incomplete_checks()` 统一标记；正常轮廓不会掩盖同文件的未检查部分，strict 必须失败。详见[检查完整性](check-completeness.md)。

| 功能 | 输入 | 输出 | 关键限制 | 验证入口 |
| --- | --- | --- | --- | --- |
| F1 读取和结构解析 | ASCII DXF 字节、LF/CRLF/CR 换行 | TagScan、Drawing、HEADER、图层和块记录及诊断 | 未知记录保留不等于字节级无损往返；不读二进制 DXF | reader_ascii、structure、header、tables、stream 测试及 47 文件回归 |
| F2 核心实体解码 | 下表列明的组码和普通 INSERT | EntityCommon、Geometry 或未解码记录 | 字段未列出即不承诺其完整语义；损坏顶点不得静默拼成新轮廓 | entity、delivery_regression 测试 |
| F3 曲线离散 | 范围内几何及正有限 tol | checked 接口的 Flat 或错误原因 | XY 近似，受数值尺度和资源上限约束；不是精确 CAD 内核 | flatten、geometry_regression、spline_oracle 测试 |
| F4 块展开 | BLOCKS、普通单实例 INSERT、tol | 世界坐标折线、有效图层及警告 | 二维仿射变换，最多 8 层；阵列只展开首实例 | expand、insert_ocs、delivery_regression 测试 |
| F5 辅助检查 | Drawing、tol、min_gap | 带检查项、严重程度和说明的 Report | 只承诺下表列明的检查关系，非可加工认证 | check、coverage 测试及 CLI 实际文件回归 |
| F6 报告和预览 | 已展开几何 | 文字报告、SVG | 文字简化显示；数值使用 Double 往返表示，不固定四位小数 | preview 测试、六类实际网页编译产物验证 |
| F7 流式扫描统计 | 分块字节流 | TagStream 结果、stats 统计 | 不构造全量图纸；超长行、警告和不同统计项仍可占用更多内存 | 两种分块大小逐 tag 对照及 CLI stats |

核心库仅使用 MoonBit core；CLI 和语料工具使用 x、async。公开接口简例位于 [`examples/library`](../examples/library/main.mbt)，它是同模块中的单独包。可复制到仓库外的独立工程位于 [`examples/consumer`](../examples/consumer/README.md)，自带 moon.mod、moon.pkg、moon.work、文件样例和读取/实体/离散/检查流程，不复制内部算法。Wasm 和 Native 均通过外部工程验收。

## 实体与字段矩阵

按“记录读取、语义解码、离散/预览、参与检查、未承诺语义”逐实体展开的[分层能力矩阵](entity-capabilities.md)，配合下表使用。[再次申报材料索引](resubmission-evidence.md)提供实际报告和 SVG。

所有实体公共信息包括类型名、图层（8）、句柄（5；相关记录可用 105）及原始 Record。几何按 XY 分析，读取 Z 不表示支持三维几何语义。

| 实体 | 正式交付字段和行为 | 不包含或失败策略 |
| --- | --- | --- |
| LINE | 起点 10/20/30、终点 11/21/31；XY 线段 | 缺 X/Y 警告并跳过；不解释厚度和完整线型语义 |
| CIRCLE | 圆心 10/20/30、半径 40；整圆离散、非正半径诊断 | 非默认 OCS 未转换；不把 XY 结果称为真实空间圆 |
| ARC | 圆心、半径、角度 50/51；内部弧度和逆时针离散 | 不是通用三维圆弧；不自动修复所有异常角度数据 |
| ELLIPSE | 圆心 10/20/30；相对圆心的长轴向量 11/21/31；短长轴比 40；参数 41/42 | 长轴字段直接作为向量，不再次减圆心；仅分析支持的 XY 椭圆及椭圆弧 |
| LWPOLYLINE | X/Y 10/20、标高 38、bulge 42、闭合标志 70；核对声明顶点数 90 | 输出中心线，不生成宽度区域；坐标缺失则保留记录、拒绝该实体轮廓并诊断；仅数量声明不一致时保留完整坐标并警告 |
| 普通二维 POLYLINE | VERTEX 的 10/20/30、42；主记录闭合位 1，允许不改变中心线的线型生成位 128 | 拟合、空间和网格标志及非普通 VERTEX 标志不作为普通折线；损坏顶点拒绝整条轮廓；缺 SEQEND 可保留完整顶点并报告恢复 |
| SPLINE | 次数 71、节点 40、控制点 10/20/30、权重 41；连续 B 样条或正权重 NURBS 的 checked XY 离散 | 不从仅有拟合点的数据重建；不重建闭合/周期标志的全部语义；非法、非连续、非正权重或超限输入明确失败 |
| INSERT | 块名 2、插入点、块基点、缩放 41/42/43、旋转 50、图层 0 继承、有限嵌套 | 只使用 XY 变换；非默认 OCS 整个引用及子实体跳过并报告来源；行列数 70/71 超出单实例时提示其余实例未展开 |

块变换次序为减块基点、XY 缩放、旋转、平移；嵌套用仿射矩阵复合，按累计拉伸调整局部离散容差。8 层内允许展开，第 9 层截断并警告。

## 保留字段但不承诺轮廓检查

| 类型 | 本次行为 |
| --- | --- |
| POINT | 提取位置和点预览；孤点不是闭合轮廓 |
| TEXT / MTEXT / ATTRIB / ATTDEF | 提取现有内容、位置、字高、旋转字段；简化预览并提示未转轮廓，不做字体轮廓或完整排版 |
| HATCH / DIMENSION 及相关标注 | 保留原始记录和已提取元数据，报告填充边界或关联几何未检查 |
| 3DFACE | 保留 WCS Face 原始角点顺序；不套用 SOLID/TRACE 重排，不生成检查或 SVG 轮廓，报告未覆盖 |
| 未知实体和未支持的 POLYLINE 变体 | 保留原始记录、类型身份并报告未覆盖；不静默当作已检查 |

其他实体的非默认 OCS 仍报告未转换，其 XY 投影可能参与部分计算；这类输入超出正式几何承诺。INSERT 的非默认 OCS 在展开前整体拒绝。两者都不能用局部结果代表整张图纸检查完成。

## 检查语义与参数

2026-10-22 按追加审查补充 **SOLID/TRACE 二维边界**：保留原始 10/20/30～13/23/33 字段；Entity::flatten_checked 按 0→1→3→2 连接，第三/第四角点相同时只输出一次。正式边界限于默认 OCS、厚度 39 为 0、全部角点 Z 相等。缺整个第四点仅带诊断恢复三角形，不算完整；残缺第四点拒绝。不是填充区域、通用面或三维体检查。裸 Geometry::Face 仍为空结果；当前完整约定和案例见[追加验收](review-cases.md)。此前仅保留面字段的降级记录是历史状态。

| 检查 | 本次范围 |
| --- | --- |
| 退化 | 非正圆/弧半径、空或单点轮廓、零长度段 |
| 端点闭合 | 同图层开放轮廓按端点容差串链，识别未闭合链；不重建区域内外关系 |
| 自交 | 同一轮廓内非相邻折线段的内部真交叉；不承诺全部相切或自接触情况 |
| 重复/重叠 | 同图层线段的共线重叠，排除同实体相邻段；不自动去重 |
| 指定净距 | 同图层不同实体的离散线段距离，跳过容差内端点接触；不等于单实体窄颈或材料壁厚 |
| 文字、图层和覆盖提示 | 未转轮廓文字、图层引用/状态、列明的未支持实体和坐标语义、实例、解析恢复及离散失败 |

`tol > 0`、`min_gap >= 0` 且均有限；`min_gap = 0` 不执行净距检查。单位沿用图纸原始坐标，HEADER 只显示声明，不自动换算毫米。曲线近似误差影响阈值附近结果。关闭/冻结图层的筛选是本工具约定，不代表下游 CAM 行为。

UTF-8 使用宽容解码；CP1252 可解码；其他声明代码页以 Latin-1 降级并警告。编码探测只看开头 1024 字节。

资源边界：样条次数为 1–32、输入控制点不超过 4096、细分深度 16、单次样条输出不超过 65536 点、圆弧最多 4096 段。checked 入口无法满足容差或超限时返回原因；这些上限不保证任意数值尺度的精度或整份图纸的常数内存。

## 交付和验收

- 核心库及公开调用示例；三个 CLI 命令；正常、问题、未覆盖三种浏览器示例。
- 范围内实体、变换、异常和覆盖诊断的自动测试；47 个外部输入回归，不称为完整标准认证。
- 六类最小技术用例的修复前/后结果、实际 CLI 和网页编译产物断言，见[修复验证](delivery-verification.md)。
- README、接口文档、案例、来源和申报稿对应同一源码与网页构建；已提交源码、Mooncakes 发布、网站部署和报名表提交分别核实。

完成标准是在列明验证集中得到预期字段、几何和诊断，正常案例无预期外告警；不是对所有可能输入承诺零误报。二进制 DXF、写回编辑、完整 OCS、填充/标注重建、通用面实体及三维体检查、通用三维内核、字体轮廓、刀路及加工可行性认证不属于本次交付。

字段语义参考 Autodesk 的 [ELLIPSE](https://help.autodesk.com/cloudhelp/2020/ENU/AutoCAD-DXF/files/GUID-107CB04F-AD4D-4D2F-8EC9-AC90888063AB.htm)、[POLYLINE](https://help.autodesk.com/cloudhelp/2024/ENU/AutoCAD-DXF/files/GUID-ABF6B778-BE20-4B49-9B58-A94E64CEFFF3.htm) 和 [VERTEX](https://help.autodesk.com/cloudhelp/2024/ENU/AutoCAD-DXF/files/GUID-0741E831-599E-4CBF-91E1-8ADBCFD6556D.htm) 定义。本矩阵列出的是实际交付子集。