已知限制¶
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 回退在路由失败时提供安全网，但精度低于专业策略。
字段权威矩阵校准风险¶
Cartex 现已通过 FIELD_AUTHORITY_MATRIX（全局排序 + 模板覆盖）进行字段级决策，不再使用全局策略一刀切优先级。但矩阵质量会直接影响结果。
影响。 若某模板下字段来源排序不合理，resolver 会稳定选中“看起来合理但并非最佳”的来源。
解决方案。 以各模板真值集持续校准矩阵，并将例外规则明确维护在 src/pipeline/field_authority.yaml。
Special Notes 语义综合的召回漂移¶
Special Notes 由 SpecialNotesAdjudicator 通过 FAST 模型分批语义整合生成。
影响。 可读性与去重效果提升，但在多来源竞争时，低频技术条款（如某些规范子条款）可能被压缩或遗漏。
解决方案。 保留确定性回退逻辑，持续监控基准样本的条款级召回，并对“必须保留事实类型”收紧综合提示约束。
隐含产品知识缺口（品牌/型号推断）¶
部分字段依赖外部产品知识，而非文档显式文本。例如：由某品牌系统名推断 uPVC/vinyl。
影响。 当证据不显式存在于提取表格/上下文时，模型可能留空或给出泛化值。
解决方案。 在未引入可控品牌知识层（维护型映射表 + 可追溯规则 + 置信度标注）前，将其作为平台已知限制。
模板源字段契约语义重叠¶
部分模板字段契约存在语义重叠（例如 Glass Width 与 Glass Layer 都被描述为厚度相关）。
影响。 专业策略可能将同一证据填入多个字段，形成结构上可解释但语义上不理想的输出。
解决方案。 在模板源定义中先澄清字段语义，再重新生成并注入更新后的字段契约提示块。
遮挡行引发的提取伪行¶
当清单尾部被叠印备注或打印伪影遮挡时，提取阶段可能生成“看似合理但不具权威性”的额外行。以 Kingsbrook 类版式为例，不稳定区域集中在检测到的主表最后约 5 行。
影响。 结果中可能出现人工审核不接受的附加行（某次 run 可能是 W75B），但伪行 ID 与字段值会随 run 变化。该问题尚未修复。
解决方案。 在报告层维护样本级伪行抑制/忽略元数据，同时持续改进提取阶段对遮挡表格的处理；不要把单一 row_id 视为该问题的完整特征。
基于索引的行 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 在与 Cartex 集成的版本中不支持自动上下文条目检测。用户必须手动框选
上下文区域（辅助表、图例图像、通用备注、条目卡片图）。用户标记的 evidence
在 DrawingAIService 的第 7 步之后被截获，并通过 Gemini CONTEXT_EXTRACTION
调用处理后再传入 Cartex。drawing_ai.py:523 中的 valid_types 过滤器保持不变。
详见上下文条目集成方案。
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() 函数。
详见映射层设计。
上下文条目质量依赖用户认真程度¶
上下文条目现可通过方案 A 中描述的用户标记工作流获取。之前的限制——上下文条目完全不可用——已解决。剩余约束是上下文条目质量取决于用户标记相关区域的认真程度。
影响。 若用户未标记辅助表或图例图像，该上下文将在 ExtractionResult 中缺失，相应的专业策略将不会触发。富化覆盖率随用户标记的全面程度而变化。
解决方案。 这是初始版本中已知且可接受的约束。未来的自主上下文检测（详见未来：自主上下文检测）将消除对用户认真程度的依赖。
富化元数据存储¶
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 字段。