SuccApp Super JSON

SuccApp Super JSON 是 SuccApp 多种元数据 JSON 文件共同遵守的文件格式规范。它不是某一个文件后缀，而是一套基于JSON的文件格式规范。

本文只说明 Super JSON 总体概念、适用范围和修改原则，真实文件格式细节见DTS定义 types/meta/superjson/base.d.ts 中的 SuperJSON。

适用文件

SuccApp Super JSON 主要适用于这些元数据文件：

类型	文件	用途和细节入口
数据类	.tbl、.query	数据模型和查询 DSL。查看 .tbl、.query、types/meta/file-types/tbl.d.ts、types/meta/file-types/query.d.ts。
页面类	.spg、.dash、.rpt、.fapp、.tpg	SuperPage、仪表板、报表、报表填报应用、超级模板页面。查看 .spg、.dash、.rpt、.fapp、.tpg、types/meta/visual-page/visualpage.d.ts、types/meta/file-types/tpg.d.ts。
流程类	.afl、.wfl	程序流和工作流。查看 .afl、.wfl、types/meta/file-types/afl.d.ts、types/meta/file-types/wfl.d.ts。

其他 JSON 元数据文件例如项目配置、主题和模板配置不属于 SuccApp Super JSON。遇到这些文件时，应回到对应文件类型页和 DTS 判断，不要强行套用本页示意结构。

共同规范

下面是 SuccApp Super JSON 的顶层段落地图。它不是可直接复制的新文件模板；真实文件只保留自己文件类型支持的段落。同名字段在不同文件类型中的位置可能不同，编辑时保持原文件和同类最新版文件的顺序，字段细节以 DTS 为准。

{
  "version": "5.8.2",                  // 大多数 Super JSON 文件的结构版本；修改旧文件前先确认是否已升级到当前版本。
  "settings": {                        // 文件级设置；不同类型的 settings 由各自 DTS 定义。
    "..."
  },
  "params": [                          // 对外输入参数或内部中转参数。
    {
      "id": "deptId",                  // 参数内部 ID，通常自动生成并保持稳定。
      "name": "deptId",                // 参数业务名称，可通过 $params.deptId 引用。
      "dt": "C",                       // 参数数据类型，字段取值见 Param DTS。
      "disablePassIn": false           // 是否禁止外部传入。
    }
  ],
  "sources": [                         // 页面类、.tpg、.tbl 取数模型、.query 和 .wfl 都可能有数据来源。
    {
      "id": "sales",                   // 数据集或来源的稳定 ID。
      "name": "销售明细",               // 数据集显示名或别名。
      "modelType": "dwtable",          // 数据集类型，按 dataset DTS 继续定位分支结构。
      "refType": "query",              // 使用该模型的引用类型。
      "path": "salesModel",            // 外部模型资源代号，真实路径在 referenceResources.salesModel。
      "content": "dataflow1"           // 内嵌数据集资源代号，完整内容在 innerResources.dataflow1；和 path 按类型二选一。
    }
  ],
  "..."                                // 仅 .wfl：流程连线，连接 nodes 中的节点并记录分支条件。
  "referenceResources": {              // 外部资源引用索引；业务字段里通常只写 salesModel、logo 等代号。
    "salesModel": {
      "targetPath": "$DATA:/销售明细.tbl", // 真实目标路径，路径格式见 referenceResources DTS。
      "targetType": "METAFILE",        // 目标资源类型。
      "refType": "query",              // 引用类型。
      "srcProperty": "sources"         // 可选：记录引用来自哪个属性，便于分析和重构。
    }
  },
  "innerResources": {                  // 内嵌资源；使用方记录代号，完整资源内容集中放在这里。
  }
}

需要修改具体段落时，进入对应文件类型页和 DTS，例如 types/meta/file-types/tbl.d.ts、types/meta/file-types/query.d.ts、types/meta/visual-page/visualpage.d.ts、types/meta/superjson/referenceResources.d.ts、types/meta/file-types/afl.d.ts 和 types/meta/file-types/wfl.d.ts。外部资源引用方式、路径前缀、targetType 和 refType 见资源引用与路径；内嵌完整资源内容的写法见内嵌资源。

修改原则

直接修改 SuccApp Super JSON 文件前，先确认文件类型、version、文件类型页、相关 DTS、当前文件内容和同项目同类文件。

修改时遵守这些原则：

1. 先判断文件后缀和业务类型，再进入对应文件类型页和 DTS。
2. 修改前先确认 version。除非非常确定要改什么，并且只是很小范围的兼容修复，否则应先确保文件已经升级到当前最新版；如果不是最新版，应先通过SuccApp CLI工具或浏览器端的可视化设计升级，再按当前 DTS 修改。
3. 不要基于最新 DTS 直接大改老版本 JSON，这容易把历史结构改坏。
4. 字段细节以 DTS 为准，不靠本页示意结构猜字段。
5. 不随意改稳定标识，例如组件 id、数据集 id/name、字段 fld、动作节点 id/name、资源代号和 .meta 中的资源 ID。
6. 改资源目标、移动文件、重命名文件或删除文件时，同步检查 referenceResources、业务字段中的引用代号和 .meta。
7. Git diff 只保留任务相关修改，不混入全文件格式化、字段排序或无关默认值。

老版本文件

老版本文件应先通过SuccApp CLI工具或浏览器端的可视化设计升级再修改。只有在改动范围非常小、目标字段含义非常确定、且不需要按最新结构重写文件时，才按兼容维护方式直接改旧结构。

不确定历史字段含义时，先查同版本同类文件、DTS 和产品实现，再决定是否修改。

检查清单

修改完成后至少检查：

1. 文件仍是可解析的 JSON 或当前文件类型允许的结构化文本。
2. 文件类型、根结构和 DTS 入口匹配。
3. 受影响的 id、fld、数据集名、资源代号和路径能被搜索和追踪。
4. referenceResources 没有明显悬挂条目，业务字段里的引用代号也能找到目标。
5. 对应设计器、预览页、报表、流程或系统功能可以打开验证。

文件格式校验

TODO

这里后续补充 SuccApp Super JSON 的正式校验方法，包括可执行命令、校验范围、错误解释和修复建议。

正式校验方法补齐前，优先使用编辑器的 DTS 类型提示、JSON 解析检查、引用搜索和产品设计器打开验证。