接口文档字段解析器

解决的问题

对接 ERP、开放平台或内部中台时，字段说明常常散落在 Markdown 表格、JSON Schema、示例 JSON 或一段纯文本里：字段名可能是 sku_id 也可能是 商品ID，类型和必填信息也不统一。直接靠人眼摘录容易漏字段，做采集或入库时又会因为命名不一致反复改映射。parse-api-doc 的目标是把这类文档变成可程序处理的字段清单和字段映射。

工作方式

核心入口是纯函数 parseErpDocument(content, options?)，Node ESM、零依赖，可在本地脚本里 import，也可以给 AI 作为字段抽取的参考实现。调用后会先自动探测输入格式，然后从四种常见结构中提取信息：

• Markdown 表格：| 字段 | 类型 | 必填 | 说明 |
• JSON Schema：读取 properties 和 type
• 示例 JSON：按键值结构提取字段名和类型线索
• 纯文本字段列表：识别 asin: 商品ID / title (string) 商品标题 这类写法

解析结果返回 DocParseResult，包含 detectedFormat、productFields、endpoint、requestStructure、responseStructure 和 fieldMappings。字段名不一致时，可用 matchField(name, vocabulary?) 做别名模糊匹配，它会归一化大小写、_ 和 -；需要对接自家系统时，用 loadVocabulary(text) 注入自定义词汇表，默认则覆盖常见电商/API 字段。

适用边界

它适合做结构抽取，不调用网络、不发送数据，也不保证理解业务语义。文档格式过于口语化、字段缺少类型线索或完全非结构化时，可能返回 PARSE_ERROR 或 NO_FIELDS_FOUND；此时应按 error.suggestion 调整输入，而不是把它当作完整解析器。