shuangying0001-beep/parse-api-doc

parse-api-doc —— 接口文档字段智能解析

把任意格式的接口/字段文档，解析成结构化字段清单 + 字段映射，用于对接第三方系统。 纯函数实现（Node ESM，零依赖），可直接 import 使用，也可作为 AI 抽取字段映射的参考实现。

适用场景

• 拿到一份 ERP / 开放平台 / 内部中台的接口说明，要快速知道「有哪些字段、什么类型、哪些必填」
• 要把对方文档字段映射到自己的采集/存储字段（字段名不一致时的别名模糊匹配）
• 从 Markdown 表格、JSON Schema、示例 JSON、纯文本字段列表里批量提取字段

支持的输入格式（自动探测）

1. Markdown 表格：| 字段 | 类型 | 必填 | 说明 |
2. JSON Schema：含 "properties" + "type"
3. 示例 JSON：{ "asin": "B0XXX", "title": "标题" }
4. 纯文本字段列表：asin: 商品ID / title (string) 商品标题

用法

import { parseErpDocument, matchField, loadVocabulary } from './scripts/doc-parser.mjs';

const doc = `
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| asin | string | 是 | 商品ID |
| title | string | 否 | 商品标题 |
`;

const result = parseErpDocument(doc);
console.log(result.detectedFormat);   // markdown_table
console.log(result.productFields);    // [{name,type,required,description}]
console.log(result.fieldMappings);    // [{erpField,erpType,erpRequired,erpDescription,collectorField}]
console.log(result.endpoint);         // 自动推断的 方法+路径

核心 API

• parseErpDocument(content, options?) → DocParseResult
  • options.vocabulary：自定义字段词汇表（默认内置一组常见电商/API 字段，可注入你自己的）
  • 返回：{ success, detectedFormat, productFields[], endpoint, requestStructure, responseStructure, fieldMappings[], error? }
• matchField(name, vocabulary?) → 命中的标准字段 key（模糊/别名匹配，归一化大小写与 _-）
• loadVocabulary(text) → 从文本构建词汇表（便于按需扩展）

字段映射词汇表（可注入）

默认词汇表覆盖常见字段（asin/title/price/rating/bsr/image/brand...）。对接自家系统时，传入你自己的词汇表即可：

const myVocab = [
  { key: 'sku', aliases: ['sku', '货号', '商品编码'] },
  { key: 'stock', aliases: ['stock', '库存', 'quantity'] },
];
parseErpDocument(doc, { vocabulary: myVocab });

注意

• 解析失败时 success=false 且带 error.code（EMPTY_CONTENT / PARSE_ERROR / NO_FIELDS_FOUND），error.suggestion 给出针对性修改建议。
• 这是结构抽取工具，不调用网络、不发送任何数据，纯本地解析。