主题
文件新建和修改规范
直接维护元数据文件前，先确认文件类型，再按该类型的规范修改。不同文件类型的格式、存放位置、编译方式、引用关系和校验方式不同，不能只按后缀或 JSON 字段猜测。
基本流程
新建或修改文件时，建议按下面顺序处理：
- 根据需求确认文件大类和具体文件类型。判断方法见根据需求判断文件类型。
- 打开对应文件类型页，确认用途、常见位置、格式规范、DTS 入口和编辑注意事项。
- 新建文件时，先确认所属项目、应用目录和存放位置，再参考同目录同类文件确定命名、字段顺序和伴随文件。
- 修改文件时，先读取当前文件、同目录同类文件、相关
.meta、引用方和被引用资源，避免只改一个文件造成引用断裂。 - 修改完成后检查 diff，确认没有无意义格式化、字段顺序大幅扰动、路径遗漏或伴随文件遗漏。
按类型读取规范
| 文件类型 | 修改前先读 |
|---|---|
SuccApp Super JSON 类文件，例如 .tbl、.query、.spg、.dash、.rpt、.fapp、.tpg、.afl、.wfl | 对应文件类型页、SuccApp Super JSON 和页面中的 DTS 链接。字段结构、枚举、动态类型分支和可选项以 DTS 为准。 |
| 系统设置、项目设置、应用设置、数据源连接等配置文件 | 对应配置文件类型页和 DTS。先确认作用范围是系统、项目、应用还是数据源。 |
后端脚本 .action.ts、.action | .action.ts 后端脚本文件、.action 后端脚本文件 和后端脚本 API 索引。 |
前端脚本 .ts、.js | 对应脚本文件类型页。确认脚本运行在浏览器端，不要使用后端脚本 API。 |
样式 .less、.css | 对应样式文件类型页。确认源码文件和编译产物的关系，避免只改编译产物导致后续被覆盖。 |
| 图片、字体、附件、压缩包等资源文件 | 资源文件、资源引用与路径和当前资源的引用方。 |
.meta | .meta 资源元信息。它维护同级子资源的附加信息，不是某个业务文件的主体内容。 |
新建文件
新建文件时，先确认它是否真的需要新增。能复用已有页面、模型、查询、脚本或主题时，优先复用；需要新增时再按文件类型创建。
新建时至少确认：
- 文件属于哪个项目、
sysdata，还是某个.app应用目录。 - 文件名、后缀、约定文件名和目录位置是否符合对应文件类型页。
- 是否需要同步创建同名脚本、样式、说明文件或素材目录。
- 是否需要维护父目录或子目录中的
.meta。 - 是否需要在其他页面、配置、脚本或资源中新增引用路径。
修改文件
修改已有文件时，优先小步修改，保持原有格式和字段顺序。不要为了局部调整格式化整份元数据文件。
修改时至少确认：
- 当前文件类型和格式规范是否已经确认。
- 同目录同类文件是否有可参考的字段顺序、命名方式和引用写法。
- 修改字段是否被其他资源、脚本、表达式、数据集或动作节点引用。
- 重命名、移动或删除文件时，是否同步维护
.meta、同名伴随文件和引用路径。 - 修改后是否需要在设计器、预览页面、脚本日志或业务功能中验证效果。
校验结果
文件修改完成后，至少做这些检查：
- 使用 SuccApp CLI 或 SuccApp for VS Code 的 Changes / diff 视图检查差异。
- 确认没有无关格式化、无关字段重排或临时调试内容。
- 确认
.meta、引用路径、同名伴随文件和静态资源引用仍然一致。 - 推送到测试环境后，在对应设计器、预览页面、脚本日志或业务功能中验证运行结果。
工具入口见 SuccApp CLI 和 SuccApp for VS Code。
