odata-vocabularies-sync

odata-vocabularies-sync

使 packages/odata-vocabularies 包与上游 OData 词汇表源保持同步。

• 不带参数 — 将所有现有词汇表资源文件更新到最新发布版本。
• 带 URL 参数 — 先注册并添加新词汇表，然后更新所有内容。

所有文件编辑均相对于 packages/odata-vocabularies/ 进行。

注意： com.sap.cds.vocabularies.* 文件（ObjectModel、AnalyticsDetails）是手工编写的，不由此技能管理。不要尝试通过 URL 添加这些文件。

---

第 1 步 — 添加新词汇表（仅在提供 URL 参数时）

1a. 获取并检查词汇表 JSON

获取提供的 URL 中的 JSON（必须以 .json 结尾 — 更新工具不支持 XML URL）。提取：

• namespace — 顶层 schema 对象的键（例如 Org.OData.NewThing.V1 或 com.sap.vocabularies.NewThing.v1）
• alias — 该 schema 对象中 $Alias 的值（例如 NewThing）

根据 namespace 确定词汇表系列：

• 以 Org.OData. 开头 → OASIS 词汇表
• 以 com.sap.vocabularies. 开头 → SAP 词汇表
• 以 com.sap.cds. 开头 → CDS 词汇表 — 停止。 这些文件是手工编写的，不能通过此技能添加。向用户说明这一点。
• 其他任何情况 → 停止并请用户确认所属系列后再继续。

1b. 编辑 tools/update.ts

按字母顺序在现有条目中向 SUPPORTED_VOCABULARIES 添加一项：

'<namespace>': {
    uri: '<the provided URL>'
},

注意： 条目可以包含 update: false，以固定该词汇表并将其排除在今后的自动更新之外（例如，com.sap.vocabularies.CDS.v1 因为由人工维护而使用此设置）。正常自动更新时省略此字段。

1c. 编辑 src/resources/index.ts

完成全部六项添加。六项缺一不可 — 任何一项缺失都会导致运行时错误。

1. 导入 — 按别名的字母顺序插入到单个导入代码块中（OASIS 和 SAP 导入按别名交错排列，而不是按系列分组）：

   import <Alias> from './<namespace>.js';
   

   使用 JSON 中的 $Alias 值作为导入标识符。例外： 如果别名是保留的 JS 关键字或内置对象（例如 JSON、Map、Error），则添加前缀，使其成为有效标识符（例如，JSON → ODataJSON）。同时检查现有导入中的先例 — 某些别名为简洁起见使用了缩写（例如，Authorization → Auth）。

2. Namespace 联合类型 — 添加到匹配的系列类型：

   • OASIS → OasisVocabularyNamespace
   • SAP → SapVocabularyNamespace

   | '<namespace>'
   

3. Alias 联合类型 — 添加到匹配的系列类型：

   • OASIS → OasisVocabularyAlias
   • SAP → SapVocabularyAlias

   | '<Alias>'
   

4. NAMESPACE_TO_ALIAS Map：

   ['<namespace>', '<Alias>'],
   

5. ALIAS_TO_NAMESPACE Map：

   ['<Alias>', '<namespace>'],
   

6. vocabularies Record：

   '<namespace>': <Alias>,
   

1d. 编辑 src/loader.ts

按字母顺序将 namespace 添加到所属系列代码块中的 SUPPORTED_VOCABULARY_NAMESPACES：

'<namespace>',

1e. 编辑 README.md

按字母顺序将别名添加到 “Supported Vocabularies” 部分中正确的项目符号列表：

• OASIS namespace → OASIS Vocabularies 列表
• SAP namespace → SAP Vocabularies 列表

* <Alias>

---

第 2 步 — 运行更新工具

此操作会获取每个已注册词汇表（包括任何新添加的词汇表）的最新 JSON，并重新生成所有 src/resources/*.ts 资源文件。

从仓库根目录运行：

pnpm --filter @sap-ux/odata-vocabularies update:vocabularies

如果工具失败，请停止并在继续之前报告完整的错误输出。

---

步骤 3 — 审核并修正 README

对照已注册的词汇表检查 README，并补充所有缺少的条目。

1. 阅读 src/resources/index.ts，收集 NAMESPACE_TO_ALIAS 中的所有命名空间，并按系列分类：

   • OASIS：以 Org.OData. 开头的命名空间
   • SAP：以 com.sap.vocabularies. 开头，但不包括 com.sap.vocabularies.CDS.v1
   • 跳过所有 com.sap.cds. 命名空间（这些是手动编写的，不会列在 README 中）

2. 对于收集到的每个命名空间，阅读对应的生成资源文件 src/resources/<namespace>.ts，并提取 $Alias 值——这是 README 中用作显示名称的权威发布别名。

3. 阅读 README.md，找到「支持的词汇表」下的两个项目符号列表：

   • OASIS 词汇表列表
   • SAP 词汇表列表

4. 对于尚未出现在对应列表中的每个别名，按字母顺序插入。

如果 README 已经完整，则无需操作。

---

步骤 4 — 运行测试并更新快照

pnpm --filter @sap-ux/odata-vocabularies test -- -u

报告所有与快照无关的测试失败。只有在词汇表内容确实发生变化时，才应更新快照（由更新工具检测到上游差异，或新增词汇表）。如果快照发生的变化超出已更新的内容，请在接受前检查差异——这可能表示存在回归。

---

步骤 5 — 汇报

总结完成的工作：

• 如果新增了词汇表：确认其命名空间、别名、所属系列以及所有变更的文件。
• 如果发现并补充了缺失的 README 条目，请列出这些条目。
• 列出更新工具重新生成的词汇表资源文件。
• 确认测试通过。