docs: 更新项目文档和README

03_Python_OpenSource_DXF/README.md

@@ -44,55 +44,113 @@
 -   `convert_dxf_to_pdf.py`: **高级示例**。演示如何将 DXF 文件内容渲染为 PDF。
 -   `图签测试.dxf`: 用于测试的源 DXF 文件。
 -   `extract_entities_to_json.py`: **(步骤1)** 从一个作为“模板”的DXF文件中，提取所有线、文字及其完整属性（坐标、图层、颜色、对齐方式），并保存为一个JSON文件（“数字快照”）。
--   `generate_template_from_json.py`: **(步骤2)** 读取“数字快照”，分析其结构和样式（包括表头内部的所有复杂线段），并生成一个可复用的 `bom_template.json` 表格定义模板。
--   `draw_table_from_template.py`: **(步骤3)** 最终执行脚本。它会加载`bom_template.json`模板，结合外部数据（脚本内预设），在目标DXF文件中精确绘制出完整的、几何上完全一致的表格。
--   `bom_template.json`: 由步骤2生成的核心“蓝图”文件。它以机器可读的方式，精确定义了表格的所有几何与样式规范。**通过修改和使用此模板，可以实现对DXF文件的精准、自动化写入，是本方案最重要的部分**。
+-   `generate_template_from_json.py`: **(步骤2)** 读取“数字快照”，分析其结构和样式，并生成**两个**独立的、模块化的模板文件：`header_template.json` (定义表头几何) 和 `columns_template.json` (定义数据列样式)。
+-   `draw_table_from_template.py`: **(步骤3)** 最终的“绘图引擎”。它会加载模块化的模板，并结合外部数据源 (一个JSON文件)，在目标DXF中精确绘制表格。
+-   `header_template.json` / `columns_template.json`: 由步骤2生成的核心模板文件，实现了表头样式和数据列样式的分离。
+-   `test_workflow.py`: **(测试)** 一个自动化的测试脚本，用于执行完整的“绘图 -> 提取 -> 验证”流程，确保整个工作流的正确性和稳定性。
+-   `test_bom_data.json`: 为测试脚本提供标准化的输入数据。
 
 ## 🚀 如何运行 (模板化绘图工作流)
+## 如何用于您自己的图纸 (分步指南)
 
-### 1. 准备工作 (仅需一次)
+本指南将向您展示如何使用您自己的DXF文件（包含一个您想复制的表格样式），来为您自己的数据创建模板，并最终将其绘制到任何目标DXF文件中。
 
-确保 `requirements.txt` 中的依赖已安装：
-```shell
-./venv/Scripts/pip install -r requirements.txt
-```
+### 准备工作：制作一个符合规范的“模板源DXF文件”
 
-### 2. (可选) 生成或更新模板
+为了让脚本能正确工作，您需要准备一个DXF文件，它**必须**包含一个结构清晰的表格，并且这个表格应满足以下条件：
 
-如果您有一个新的、符合规范的DXF文件 (`source.dxf`)，并希望基于它来创建或更新绘图模板，请按顺序执行以下脚本：
+1.  **包含完整的表头**：位于表格的最底部。
+2.  **至少包含一行示例数据**：位于表头的正上方。
+
+您可以参考项目中的 `04_Test_Files/Drawing1.dxf` 作为标准示例。
+
+### 第1步：从您的DXF中创建表格模板
+
+假设您有一个名为 `My_Table_Style.dxf` 的文件，其中包含一个几何、样式都非常标准的表格。我们的目标就是将这个表格的“外观”提取出来，做成可复用的模板。
+
+**1.1. 将DXF的几何信息提取为JSON快照**
+
+运行 `extract_entities_to_json.py` 脚本，告诉它读取您的DXF文件，并将结果保存为一个“数字快照”JSON文件。
 
 ```shell
-# 步骤 1: 将DXF文件的几何信息提取为JSON
-# 注意：需要修改脚本内的源文件路径
-./venv/Scripts/python extract_entities_to_json.py
-
-# 步骤 2: 从JSON信息生成可复用的bom_template.json
-./venv/Scripts/python generate_template_from_json.py
+# 用法: python extract_entities_to_json.py <您的源DXF> <输出的JSON快照>
+./venv/Scripts/python 03_Python_OpenSource_DXF/extract_entities_to_json.py "C:/path/to/My_Table_Style.dxf" 03_Python_OpenSource_DXF/my_snapshot.json
 ```
 
-### 3. 使用模板绘制表格
+**1.2. 从JSON快照生成模块化模板**
 
-这是最终的执行步骤。此脚本会加载 `bom_template.json` 和内置的示例数据，在 `04_Test_Files/料表.dxf` 中绘制一个新表格，并输出到 `04_Test_Files/料表_with_template_table.dxf`。
+现在，运行 `generate_template_from_json.py` 脚本，它会读取上一步生成的快照文件，并自动分析、拆分，生成两个核心模板。
 
 ```shell
-# 步骤 3: 执行绘图
-./venv/Scripts/python draw_table_from_template.py
+# 用法: python generate_template_from_json.py <输入的JSON快照> <输出的表头模板> <输出的列模板>
+./venv/Scripts/python 03_Python_OpenSource_DXF/generate_template_from_json.py 03_Python_OpenSource_DXF/my_snapshot.json 03_Python_OpenSource_DXF/my_header_template.json 03_Python_OpenSource_DXF/my_columns_template.json
 ```
 
-### 4. 查看结果
+完成这一步后，您就已经成功地将您图纸中的表格样式“数字化”并保存为了 `my_header_template.json` 和 `my_columns_template.json`。
 
-脚本执行后，生成的目标文件 `料表_with_template_table.dxf` 会被保存在 `04_Test_Files/` 文件夹中。
+### 第2步：准备您的数据
+
+接下来，您需要按照指定的格式创建一个JSON文件来存放您想填入表格的数据。您可以参考项目中的 `test_bom_data.json` 文件。
+
+核心格式是一个列表，其中每个对象代表一行。对象的键（Key）必须与您的 `columns_template.json` 中定义的 `name` 相匹配。
+
+**`my_data.json` 示例:**
+```json
+[
+    {
+        "件 号": {"main": "A-001"},
+        "名   称": {"chinese_name": "轴承", "english_name": "Bearing"},
+        "数量": {"main": "10"},
+        "材  料": {"main": "GCr15"},
+        "单": {"main": "5.5"},
+        "总": {"main": "55.0"},
+        "备 注": {"main": "进口"}
+    },
+    {
+        "件 号": {"main": "A-002"},
+        "名   称": {"chinese_name": "螺栓", "english_name": "Bolt"},
+        "数量": {"main": "100"},
+        "材  料": {"main": "35#"},
+        "单": {"main": "0.2"},
+        "总": {"main": "20.0"},
+        "备 注": {"main": "M8x20"}
+    }
+]
+```
+请将您的数据保存为一个文件，例如 `my_data.json`。
+
+### 第3步：将数据绘制到目标DXF文件
+
+万事俱备！现在运行 `draw_table_from_template.py` 脚本，将**您的模板**、您的数据和您的目标文件作为参数传入。
+
+最重要的，您现在可以通过 `--x` 和 `--y` 参数来精确指定表格**左下角的插入坐标**。
+
+```shell
+# 用法: python draw_table_from_template.py <目标DXF> <您的表头模板> <您的列模板> <您的数据JSON> <输出DXF> --x <X坐标> --y <Y坐标>
+./venv/Scripts/python 03_Python_OpenSource_DXF/draw_table_from_template.py "C:/path/to/target_drawing.dxf" "C:/path/to/my_header_template.json" "C:/path/to/my_columns_template.json" "C:/path/to/my_data.json" "C:/path/to/output_with_table.dxf" --x 300 --y 100
+```
+
+执行完毕后，`output_with_table.dxf` 文件中就会在 (300, 100) 的位置出现一个根据您的样式和数据绘制好的、崭新的表格。
 
 ---
 
+### (附) 运行自动化测试
+
+为了确保所有脚本功能正常，可以随时运行测试套件。
+
+```shell
+# 运行端到端测试
+./venv/Scripts/python 03_Python_OpenSource_DXF/test_workflow.py
+```
+
 ## 📘 核心概念：模板化绘图
 
-我们的解决方案核心是将CAD设计规范转化为一个机器可读的JSON模板 (`bom_template.json`)。
+我们的解决方案核心是将CAD设计规范转化为一个机器可读的JSON模板。当前版本的核心工作原理基于一个简单而明确的几何假设：
 
-- **几何与样式分离**: 模板定义了表格的“外观”（线的位置、文字的相对位置、大小、字体、图层、颜色、**对齐方式**），而数据（如“新零件-A”、“Q345R”）则由外部提供。
-- **精确复制**: 通过提取现有图纸的完整几何属性（包括**每一根线段**和每一个文本的**对齐方式**），模板可以确保新生成的表格在每一个细节上都与原始设计意图保持一致，完美处理合并单元格等复杂样式。
-- **自动化**: 一旦模板建立，就可以用程序结合任意数据源（Excel, 数据库等），批量、快速、无差错地生成符合规范的图纸。
-- **模板复用与拆分**: `bom_template.json` 文件本身也可以被视为一个基础模板。在实际应用中，可以将其中定义的 `header_definition` (表头) 和 `column_definitions` (列样式) 拆分保存。这样，同一个表头可以方便地与多批次、不同来源的数据结合，生成不同的物料清单，进一步提高自动化效率。
+- **基于几何的区域识别**: 脚本通过分析DXF文件中的所有**水平线**来识别表格的行结构。
+- **“表头在底部”的核心假设**: 脚本**假定表格最底部的区域是表头**，而表头之上的区域是数据区。为了让模板能被正确提取，您作为模板的源DXF文件应遵循此结构。
+- **精确复制**: 脚本会提取出表头区域内所有的文字、线条及其完整的几何属性（坐标、尺寸、对齐方式、颜色、图层等），确保生成的表头与原始设计100%一致。
+- **数据模板化**: 脚本会分析紧邻表头上方的第一行数据，并将其样式（文字的相对位置、字体、高度等）作为后续所有数据行的统一模板。
 
 ## 📘 核心操作指南 (ezdxf)