根据需求判断文件类型

新建或维护元数据文件时，先不要从后缀开始猜。更稳妥的方式是先看要解决的需求，确定文件大类，再选择具体文件类型，并按该类型的目录约定放到合适位置。

SuccApp 元数据文件不只包括 JSON，也包括 .js、.ts、.less、.css、.png 等脚本、样式和静态资源。同样是 JSON，不同后缀、约定文件名和存放位置也可能对应不同的格式规范。

先判断需求大类

需求大类	适用需求	常见文件类型	详细说明
数据与模型	维护业务对象、数据模型、复用查询、知识库内容	.tbl、.query、.kdb	数据与模型文件类型
页面与应用	搭建应用边界、业务页面、模板页面、报表填报应用、前端脚本和样式	.app、.spg、.tpg、.fapp、.ts、.js、.less、.css	页面与应用文件类型
报表与可视化	搭建仪表板、报表、主题和可视化分析页面	.dash、.rpt、.theme	报表与可视化文件类型
后端流程与控制	编排程序流、工作流、自定义接口、后端脚本和系统事件逻辑	.afl、.wfl、.action.ts、.action	后端流程与控制文件类型
配置与元信息	配置数据源、系统设置、项目设置、应用设置和资源元信息	.jdbc、settings.json、.meta	配置与元信息文件类型
静态资源	维护图片、字体、附件、压缩包和主题素材	图片、字体、附件、压缩包等	资源文件

再选择具体文件类型

确定大类后，继续根据文件要承担的职责选择具体类型。例如：

1. 需要定义业务对象、字段和分析口径时，通常使用 .tbl。
2. 需要复用一段稳定取数逻辑时，通常使用 .query。
3. 需要搭建通用交互页面时，通常使用 .spg；需要搭建仪表板或报表时，分别使用 .dash、.rpt。
4. 需要编排服务器端业务动作时，通常使用 .afl；需要人工审批和任务流转时，使用 .wfl。
5. 需要编写后端自定义逻辑时，优先使用 .action.ts；需要编写页面前端逻辑时，优先使用 .ts。
6. 需要调整系统、项目或应用配置时，先判断是系统设置、项目设置、应用设置还是数据源连接，不要只按 settings.json 处理。

如果当前项目中已经有同类资源，优先参考同目录同类文件的组织方式、命名方式和字段顺序。

确认存放位置

文件类型决定文件格式，存放位置决定作用范围。选择类型后，再确认文件应该放在哪个项目、应用或目录中：

1. 普通业务资源通常放在对应元数据项目中。
2. 系统级设置、系统数据源、内置应用和全局资源通常放在 sysdata。
3. 只服务某个低代码应用的页面、脚本、配置和素材，优先放在对应 .app 应用目录中。
4. 项目级配置通常放在项目的 settings/ 目录中。
5. 图片、字体、附件等静态资源应放在被引用方能稳定访问的位置，并同步检查引用路径和 .meta。

具体目录以对应文件类型页和当前项目已有结构为准。遇到存放位置不确定的文件，先阅读元数据项目和文件新建和修改规范。

学习格式规范

确定文件类型和位置后，再进入对应文件类型页了解格式规范、DTS 入口、常见位置和编辑注意事项：

1. SuccApp Super JSON 类文件先读SuccApp Super JSON，再结合对应文件类型页和 DTS 确认字段结构。
2. 后端脚本先读 .action.ts 后端脚本文件，再查看后端脚本 API 索引。
3. 前端脚本、样式和静态资源按对应语言、编译产物、加载机制和引用路径规则维护。
4. .meta 按 .meta 资源元信息 维护，不要把它当成业务文件内容本身。

完整文件类型索引见文件类型概述。