Spec PDF 空白根因修复 (2026-07-19)

现象

• Spec PDF/JSON 长期空白（"暂无属性定义"），794 字符占位
• 误判为 arasClient 未初始化，但日志显示 SCSAI 查询成功 200 条、doc-agent arasClient 初始化成功

真实根因（三重叠加）

1. LLM 返回空数组未降级：_generateFieldDescriptionsWithLLM 当远程 LLM 返回 success:true, result:'[]' 时，

eturn Array.isArray(parsed) ? parsed : ... 直接返回空数组 [] → fieldDescriptions 空 → 空 spec 存 DB

1. Property 字段名缺失：SCSAI 返回的 Property 对象只有 label 无

ame 字段（keys: type,typeId,id,data_source,data_type,default_value,label,pattern,readonly），

_generateFieldDescriptionsTemplate 用 p.name || p.property_name 全空 → 字段名空白

1. 缓存挡路：首次生成的空 spec 存入 documentService，_findExistingSpec 在 orce 缺失时直接返回旧缓存

修复

• document-generator.js：LLM 解析结果若为空数组，降级到 _generateFieldDescriptionsTemplate(properties)
• Step 0 查询后做字段名归一化：

ame: p.name || p.property_name || p.label || p.keyed_name

• 验证：正常请求 CONTENT_LEN 13276、TABLE_ROWS 201（200 业务字段）；PDF 端点 /generate/spec/pdf 输出 152KB 有效 PDF

关键教训

• Spec PDF 正确端点是 /api/doc-agent/generate/spec/pdf（独立二进制流路由），不是 generate/spec + format:pdf
• 远程 LLM 返回空 result 时必须有非空降级，否则静默产出空文档