用途
odata-vocabularies-sync 用于让 packages/odata-vocabularies 包与上游 OData 词汇表来源保持同步。
主要能力
- 不带参数运行时，更新所有现有词汇表资源文件到其最新发布版本。
- 带 URL 参数运行时，先注册并新增该词汇表，然后更新全部内容。
- 所有文件修改均相对于 packages/odata-vocabularies/ 目录。
使用方式
步骤 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
完成全部六项添加。六项均为强制项 — 缺少任意一项都会导致运行时错误。
- Import — 在单个 import 块中按 alias 字母顺序插入（OASIS 和 SAP 导入按 alias 交错排列，而非按族分组）：
import <Alias> from './<namespace>.js';
使用 JSON 中的 $Alias 值作为 import 标识符。例外：如果 alias 是保留 JS 关键字或内置对象（例如 JSON、Map、Error），则添加前缀以构成有效标识符（例如 JSON → ODataJSON）。同时检查现有导入以寻找先例 — 某些 alias 为简洁起见被缩短（例如 Authorization → Auth）。
- Namespace 联合类型 — 添加到匹配的族类型：
OASIS → OasisVocabularyNamespace SAP → SapVocabularyNamespace
| '<namespace>'
- Alias 联合类型 — 添加到匹配的族类型：
OASIS → OasisVocabularyAlias SAP → SapVocabularyAlias
| '<Alias>'
- NAMESPACE_TO_ALIAS Map：
['<namespace>', '<Alias>'],
- ALIAS_TO_NAMESPACE Map：
['<Alias>', '<namespace>'],
- vocabularies Record：
'<namespace>': <Alias>,
1d. 编辑 src/loader.ts
在其族块中按字母顺序将 namespace 添加到 SUPPORTED_VOCABULARY_NAMESPACES：
'<namespace>',
1e. 编辑 README.md
在 "Supported Vocabularies" 部分中正确的项目符号列表中按字母顺序添加 alias：
- 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 并添加任何缺失的条目。
读取 src/resources/index.ts 并从 NAMESPACE_TO_ALIAS 收集所有 namespace，按族拆分：
- OASIS：以 Org.OData. 开头的 namespace。
- SAP：以 com.sap.vocabularies. 开头的 namespace，排除 com.sap.vocabularies.CDS.v1
- 跳过所有 com.sap.cds. namespace（手工编写，不在 README 中列出）
对于收集到的每个 namespace，读取对应生成的资源文件 src/resources/<namespace>.ts 并提取 $Alias 值 — 这是权威的已发布 alias，用作 README 中的显示名称。
读取 README.md 并找到 "Supported Vocabularies" 下的两个项目符号列表：
- OASIS Vocabularies 列表
- SAP Vocabularies 列表
对于尚未出现在正确列表中的每个 alias，按字母顺序插入。
如果 README 已完整，则不执行任何操作。
步骤 4 — 运行测试并更新快照
pnpm --filter @sap-ux/odata-vocabularies test -- -u
报告任何非快照相关的测试失败。仅当词汇表内容实际发生变化时（更新工具检测到的上游漂移，或新增词汇表），才预期快照更新。如果快照变化超出已更新的范围，请在接受之前检查 diff — 这可能表明存在回归。
步骤 5 — 报告
总结已完成的工作：
- 如果新增了词汇表：确认 namespace、alias、族以及所有更改的文件。
- 如果添加了任何缺失的 README 条目，请列出它们。
- 列出由更新工具重新生成的词汇表资源文件。
- 确认测试通过。
适用场景
适用于维护 packages/odata-vocabularies 包、需要将 OData 词汇表资源文件同步至上游最新发布版本、或需要注册新增 OASIS/SAP 词汇表的开发场景。
限制
- XML URL 不受更新工具支持，URL 必须以 .json 结尾。
- com.sap.cds.vocabularies.* 文件（ObjectModel、AnalyticsDetails）为手工编写，不由本技能管理，不能通过 URL 添加。
- com.sap.cds. 开头的 namespace 无法通过本技能添加。
- 非 OASIS/SAP/CDS 的 namespace 需用户确认词汇表族后才能继续。