资源引用与路径

SuccApp 元数据文件经常会用到其他资源，例如页面查询模型、按钮跳转页面、组件使用图片、程序流调用脚本、模型关联维表。外部资源引用不要散落在各个业务字段里，而是先在文件级 referenceResources 中建立引用列表，再由业务字段引用列表中的代号。

本文只讲外部资源引用。把另一个资源的完整内容嵌入当前文件的写法，见内嵌资源。

外部资源先进入引用列表

Super JSON 文件通过 referenceResources 统一记录外部资源引用。每个条目的 key 是当前文件内部使用的引用代号，值描述真实目标资源。

{
  "referenceResources": {
    "salesModel": {
      "targetPath": "$DATA:/common/FACT_SALE.tbl",
      "targetType": "METAFILE",
      "refType": "query",
      "fields": {
        "SALE_AMOUNT": "r"
      },
      "srcProperty": "sources"
    }
  }
}

这个结构解决两件事：

1. 让引用分析、影响分析、权限检查、重构和升级可以从一个稳定位置读取外部依赖。
2. 让业务字段不用直接保存完整路径，避免同一个目标路径在文件中重复出现。

referenceResources 的字段以 DTS 为准，重点查看 types/meta/superjson/referenceResources.d.ts 中的 ReferenceResources 和 ReferenceResource。

使用处只保存代号

建立引用列表以后，页面、模型、组件、动作、节点等真正使用资源的位置通常只保存引用代号。

{
  "sources": [
    {
      "id": "sales",
      "name": "销售明细",
      "modelType": "dwtable",
      "refType": "query",
      "path": "salesModel"
    }
  ],
  "referenceResources": {
    "salesModel": {
      "targetPath": "$DATA:/common/FACT_SALE.tbl",
      "targetType": "METAFILE",
      "refType": "query"
    }
  }
}

上例中，sources[0].path 写的是 salesModel，不是 $DATA:/common/FACT_SALE.tbl。salesModel 再到 referenceResources.salesModel 中找到真实目标。

不同文件类型的使用点字段不同。例如数据集可能用 path，页面样式可能用 url(refId)，动作或程序流节点可能用自己的目标字段。直接编辑时先看当前文件类型 DTS，再回到 referenceResources 确认引用代号是否存在。

代号应尽量稳定。移动或重命名目标资源时，通常只改 targetPath，不要顺手改代号；否则还要同步修改所有使用点字段。

目标路径写在 targetPath

targetPath 是外部目标资源的路径。它不是普通文件系统路径，而是 SuccApp 元数据引用路径。常见形态有四类：

1. / 开头：元数据绝对路径，例如 /DEMO/data/tables/common/DIM_DATE.tbl。
2. . 开头或不带 $ 前缀：相对当前元数据文件解析，例如 ../detail.spg、models/order.tbl。
3. $XXX: 开头：元数据引用 URI，例如 $DATA:/common/DIM_DATE.tbl、$TAPP:/pages/detail.spg、$DB:/defdw/_def_/FACT_SALE。
4. URL：外部链接或内联资源，例如 https://example.com/report、mailto:help@example.com、data:image/png;base64,...，通常配合 targetType: "URL" 和 refType: "link" 使用。

相对路径适合当前文件附近的资源。解析时以当前元数据文件为起点，. 开头和普通路径都会按相对路径处理；/ 开头则直接表示元数据绝对路径。跨项目引用通常使用绝对路径。

$DATA:、$ANA:、$FAPP:、$APP:、$TAPP: 这类路径前缀多用于缩短同项目内的元数据文件路径。它们只是路径写法，不一定等于资源类型。例如 $DATA:/common/FACT_SALE.tbl 指向模型文件，targetType 仍应写 METAFILE。

完整路径规则、模块别名、资源类型路径和归一化说明见 types/api/succ.meta.d.ts 中的 ReferenceResourcePath。

类型表达引用语义

外部引用至少要判断两个类型字段：

字段	作用	主要 DTS
targetType	目标资源是什么，例如元数据文件、扩展点、数据库对象、文件数据源、主题资源。	types/api/succ.meta.d.ts 的 MetaResourceType
refType	当前文件怎么使用目标，例如查询、更新、链接、嵌入。	types/metadata-meta-types.d.ts 的 MetaRefType

不要只按路径前缀猜 targetType。先判断目标本质是什么，再看同类文件和设计器保存结果。ReferenceResource.targetType 和 ReferenceResource.refType 的选择建议见 types/meta/superjson/referenceResources.d.ts。

修改引用时的顺序

AI 或人工直接修改外部资源引用时，按这个顺序处理：

1. 先确认当前文件类型，打开对应文件类型 DTS，找到真正的使用点字段。
2. 判断使用点字段保存的是引用代号还是完整路径。Super JSON 中的外部资源通常应保存引用代号。
3. 在 referenceResources 中新增或复用同名条目。
4. 在条目里填写 targetPath、targetType、refType；数据资源按需填写 fields。
5. 移动、重命名或删除资源时，同步搜索引用代号、旧路径、文件名、组件 ID 和 .meta 中的伴随信息。
6. 不确定前缀、类型或字段读写关系时，优先查同类型真实文件和设计器保存后的结果。

内嵌资源不是外部引用

innerResources 看起来也通过代号使用资源，但它的含义不同：它是把另一个元数据资源的完整内容嵌入当前文件。内嵌资源不是外部资源依赖，不写 targetPath，也不应该作为同名条目放进当前文件的 referenceResources。

内嵌资源的完整说明见内嵌资源。根结构定义见 types/meta/superjson/base.d.ts 中的 SuperJSON.innerResources。

应该查看的 DTS

DTS	重点查看
types/meta/superjson/base.d.ts	SuperJSON.referenceResources、SuperJSON.innerResources 的边界。
types/meta/superjson/referenceResources.d.ts	ReferenceResources、ReferenceResource，以及修改外部引用时的同步规则。
types/api/succ.meta.d.ts	ReferenceResourcePath、ReferenceResourceId、MetaResourceType，以及路径前缀规则。
types/metadata-meta-types.d.ts	MetaRefType、ReadWriteMode 等引用用途和字段读写关系。
具体文件类型 DTS	当前文件的业务字段如何保存引用代号。

示例和实现

真实写法优先查同类型元数据文件和 metadata-examples/DEMO/index.json。

需要核对实现时，看这些入口：

• 服务端：MetaResourceType.java、MetaUtils.relativeReferencePath、MetaUtils.resolveReferencePath、MetaPathUtilsImpl.resolveMetaReferencePath、MetaRefPathResolver 实现类。
• 前端：relativeReferencePath、resolveReferencePath、getModuleReferencePath。

parseMetaRefType 只解析原始 $XXX: 前缀，不能用来决定 referenceResources.targetType。