已知限制¶
Cartex 存在影响富化覆盖率和集成就绪度的已知约束。本页将其分为当前管道限制和移植至 Cato-v2 前必须解决的依赖项两类。
当前限制¶
Gemini 模型依赖¶
Cartex 的富化提示词专门针对 Google Gemini。所有专业提示词（AUXILIARY_TABLE_ENRICHMENT、LEGEND_ENRICHMENT 等）均使用 Gemini 的结构化 JSON 输出模式和 Pydantic 模式验证。切换至其他模型（如 GPT-4 Vision）需要重写提示词并修改输出解析逻辑。
影响。 Cartex 无法部署在 Gemini 不可用的环境中。使用 OpenAI 进行提取的 Cato-v2 部署中，富化将使用与提取不同的模型。
解决方案。 富化器维护独立于提取层的模型配置。提示词向其他模型的可移植性不在初始移植范围内。
路由器对提取质量敏感¶
Router 根据紧凑摘要（表格角色、表头、行数、样本单元格值及上下文片段）进行策略选择。表格角色错误分类或缺少上下文条目会导致路由器遗漏适用策略。
影响。 若提取将辅助表标记为 OTHER，T1（辅助表富化）将不会触发。若图像上下文缺少解读文本，T3 和 T4 将被跳过。
解决方案。 改进上游提取质量。单体 ENRICHMENT 回退在路由失败时提供安全网，但精度低于专业策略。
固定合并优先级顺序¶
合并算法使用固定优先级：auxiliary_table > image_legend > text_rule > dimension_card > multi_label。每列由优先级最高的专业策略的第一个非空值决定。
影响。 当低优先级专业策略对某特定列具有更准确的值时，合并无法优先选择它。例如，T3（图例）正确填充了 Operability，但 T1（辅助表）填充有误，则 T1 胜出。
解决方案。 可在 UserTableSchema 中添加逐列优先级覆盖，但会增加复杂性。当前固定顺序反映了测试文件中最可靠的来源层次结构。
Special Notes 去重基于子串匹配¶
合并使用不区分大小写的子串匹配对 Special Notes 片段进行去重。若片段 A 是片段 B 的子串（或反之），较短的片段将被丢弃。
影响。 恰好共享子串的不同备注可能被错误去重。例如，"IBC 2406.4"和"IBC 2406.4.1(2)"——较短字符串是较长字符串的子串，因此即使两者独立相关，较短的也会被丢弃。
解决方案。 改用语义或精确匹配去重。这是 _merge_specialist_results() 中的小改动，但需要针对测试集进行验证以避免备注膨胀。
基于索引的行 ID 禁用行恢复¶
当提取未能检测到 primary_key_column 时，行获得基于索引的 ID（如 table_0_0_row_0）。合并算法将这些表格排除在行恢复之外，以避免误报。
影响。 若主键检测失败，没有任何专业策略产生输出的行将在结果中静默缺失。管道永不丢行的保证依赖于可靠的主键检测。
解决方案。 改进提取阶段的主键检测。或者，在 UserTableSchema 中添加用户可覆盖的 primary_key_column 选项。
单文件范围¶
Cartex 每次只富化一个 ExtractionResult。它无法跨独立文件交叉引用数据（例如，A5.1 图纸上的窗户清单引用了 A9.1 图纸上另一次管道运行中提取的玻璃规格表）。
影响。 辅助表和主清单出现在不同页面的多图纸文件，必须使用 extract_pages() 一起提取，生成单个合并的 ExtractionResult。
解决方案。 extract_pages() 方法已支持带内容去重的多页提取。调用方必须在单次 run() 调用中传入所有相关页码。
开启方式枚举覆盖范围¶
WindowOperabilityType 和 DoorOperabilityType 枚举定义了一组固定的允许值。专业策略必须将所有开启方式描述映射到这些值之一。
影响。 不寻常或新兴的产品类型（如电动百叶系统、自动滑动隔墙）没有匹配的枚举值。专业提示词指示 Gemini 选择最接近的匹配项并在推理中标注歧义，但输出可能存在误导性。
解决方案。 遇到新产品类型时扩展枚举。DoorOperabilityType.SECTIONAL 值即通过此方式在 Fairway VTT 测试后添加。
移植依赖项¶
以下事项必须在 Cartex 能够在 Cato-v2 生产管道中运行之前解决。详见移植计划。
P0 阻断项：图像解读缺失
Cato-v2 将裁剪图像存储在 S3 中，但从不生成文字解读。
缺少 ImageContextModel.interpretation，T3（图例富化）和 T4（尺寸富化）将无法运行。
必须为非清单类证据添加新的 Gemini 视觉调用。
详见图像上下文缺口。
P0 阻断项：缺少 MAIN vs AUXILIARY 表格角色分类
Cato-v2 对所有清单类证据（Window Door Unit、Table）一视同仁。
缺少角色分类，映射层无法填充 TableModel.role，
T1（辅助表富化）将误触发或根本不触发。
详见风险 R1。
P0 阻断项：映射层不存在
目前没有转换器将 Cato-v2 的 TakeOffResult / Evidence 结构
转换为 Cartex 的 ExtractionResult。
必须构建 to_extraction_result() 和 build_user_table_schema() 函数。
详见映射层设计。
富化元数据存储¶
Cato-v2 的 take_off_result_item 表每行存储一个扁平 JSON result 字典。Cartex 的 EnrichedRow 新增了 field_sources、confidence 和 reasoning——这些字段目前没有存储位置。
影响。 富化来源和置信度数据在保存时会丢失。
解决方案。 向 take_off_result_item 添加 cartex_metadata JSON 列，或在关联表中存储审计数据。
字段名对齐¶
Cartex 的 UserTableSchema.columns 必须与 TableModel.rows 中的键完全匹配。若 PromptTemplate 定义的字段与提取实际填充的字段不一致，富化将产生错位结果。
影响。 提取中存在但模式中缺失的列被忽略；模式中存在但提取中缺失的列无警告地保持为空。
解决方案。 在映射层添加验证步骤，将模板字段名与 TakeOffResultItem.result 中的实际键对比，对不匹配字段记录警告。
Product Type 字段要求¶
对于来自立面的条目，Product Type 来自检测模型的标签名称。对于来自清单的条目，取决于当前 PromptTemplate 是否包含带提取规则的 Product Type 字段。
影响。 门行可能在没有 Product Type 的情况下到达富化阶段，降低开启方式和配置映射的富化质量。
解决方案。 确保默认提示词模板始终包含带有完整提取规则的 Product Type 字段。