文件类型概述

这些页面说明各类元数据文件的用途、常见位置、根结构、DTS 入口和编辑注意事项。字段、枚举、继承和动态类型分支以 DTS 为准，文件类型页不重复维护完整字段表。

新建元数据文件时，先从要解决的需求选择文件类型，再按文件类型和目录约定确定存放位置。完整选择流程见根据需求判断文件类型；需要按后缀反查根类型时，查看 types/meta/file-types/index.d.ts。

如何判断文件类型

判断文件类型时，先看要解决的需求，不要只看文件内容。SuccApp 元数据文件既包括 Super JSON 类结构化文件，也包括 .js、.ts、.less、.css、.png 等脚本、样式和静态资源；同样是 JSON，不同位置和后缀也可能对应完全不同的根结构。

本页下方按用途列出常见文件类型、位置线索和说明页。需要从需求开始选择文件类型、确认存放位置和学习格式规范时，阅读根据需求判断文件类型；需要了解新建、修改、移动和重命名时的注意事项，阅读文件新建和修改规范。

数据与模型

文件类型	常见位置或线索	说明页	说明
.tbl	data/models/、业务模型目录	查看	数据模型，用来把业务数据整理成页面、报表、仪表板和流程都能共用的数据口径；需要维护业务对象、分析口径、填报数据或接入外部数据时使用。
.query	data/queries/、模型相关查询目录	查看	可复用查询，用来在已有数据模型上沉淀稳定取数口径；多个页面、报表、接口需要按同一规则取数时使用。
.kdb	知识库资源目录	查看	知识库，用来把文档、URL、指标说明等素材变成可检索、可被 AI 使用的知识；需要智能问答、知识检索或 RAG 数据准备时使用。

页面与应用

文件类型	常见位置或线索	说明页	说明
.app	app/{name}.app/	查看	低代码业务应用，用来界定一个相对独立业务系统的资源范围；需要把页面、流程、数据和设置按 CRM、OA 等应用边界组织时使用。
.spg	.app 内或页面资源目录	查看	SuperPage 通用交互页面，用来搭建门户、查询、办理、详情、管理控制台等页面；需要自由编排组件和动作时使用。
.tpg	模板页面或门户页面目录	查看	超级模板页面，用来按统一模板制作门户、站点或专题页；需要共享视觉框架、只配置节点内容时使用。
.fapp	报表填报应用资源目录	查看	报表填报应用，用来承载填报、数据采集、提交、锁定和审批等带状态的业务；需要周期上报或多人协作填报时使用。
.ftl	服务端模板资源目录	查看	服务端模板，用来生成轻量动态页面或自定义文本输出；按文件组织属于视图模板，运行时在服务端渲染。
.html	public/*.html、应用或扩展目录中的 HTML 文件	查看	浏览器端 HTML 文件，用于开放页面、静态片段、自定义展示内容或与脚本、样式配合使用的页面资源。
.ts	custom.ts、*.spg.ts、*.dash.ts、*.rpt.ts	查看	前端脚本源码，用来扩展浏览器端页面交互、页面级工具函数、应用级公共逻辑或项目级钩子逻辑；推荐优先维护 .ts，由系统编译为 .js 后执行。
.js	custom.js、*.spg.js、public/*.js	查看	前端 JavaScript 脚本，通常是 .ts 的编译产物；直接维护可节省编译时间，但会失去 TypeScript 语法和类型辅助，需要自行关注浏览器兼容性。
.less	custom.less、*.spg.less、*.dash.less、*.rpt.less	查看	样式脚本源码，用来编写页面、应用、项目或系统级样式定制；推荐优先维护 .less，由系统编译为 .css。
.css	custom.css、*.spg.css、public/*.css	查看	浏览器直接使用的样式文件，通常是 .less 的编译产物，也可作为兼容样式或外部样式资源直接维护。

报表与可视化

文件类型	常见位置或线索	说明页	说明
.dash	仪表板资源目录	查看	仪表板，用来把指标、图表和筛选交互组织成可视化分析页面；需要看经营状态、做专题分析或搭建大屏时使用。
.rpt	报表资源目录	查看	报表，用来制作固定版式、可打印、可导出、可归档的数据结果；需要复杂表头、明细汇总、套打或 Excel 风格输出时使用。
.theme	settings/themes/ 下的主题目录	查看	主题，用来统一页面、报表和仪表板的视觉风格；需要品牌色、明暗模式、图表配色或字体保持一致时使用。

后端流程与控制

文件类型	常见位置或线索	说明页	说明
.afl	动作流、程序流资源目录	查看	程序流或动作流，用来把一次业务动作编排成可复用的自动化流程；需要读写数据、调用接口、生成文件或响应页面按钮时使用。
.wfl	工作流资源目录	查看	工作流，用来控制人工审批和任务流转；需要请假报销、资料审核、上报确认等多人办理流程时使用。
.action.ts	hooks.action.ts、API/*.action.ts、*.tbl.action.ts	查看	后端脚本源码，用来编写程序流、自定义接口、数据加工、系统事件监听和项目或应用级后端钩子；推荐优先维护 .action.ts。
.action	hooks.action、API/*.action	查看	后端 JavaScript/Rhino 脚本，常见于旧资源兼容或 .action.ts 编译后的运行形式；直接维护时必须遵守 Rhino 支持的语法要求。

配置与元信息

文件类型	常见位置或线索	说明页	说明
.jdbc	sysdata/data/sources/*.jdbc	查看	数据源连接，用来让 SuccApp 接入业务库、数据仓库或外部数据库；部署环境需要新增或调整系统级数据库连接时使用。
/sysdata/settings/settings.json	系统项目 sysdata	查看	系统设置，用来控制整个 SuccApp 部署环境的全局能力；涉及登录、安全、域名、静态资源、文件存储或运维配置时使用。
/{project}/settings/settings.json	普通项目 settings/ 目录	查看	项目设置，用来控制单个元数据项目的可用资源和默认能力；只影响某个项目的数据源范围、显示格式、语言等配置时使用。
/{project}/app/{app}.app/settings.json	应用目录内部	查看	应用设置，用来控制单个低代码应用的入口和应用级覆盖项；需要调整首页、短路由、语言、显示格式或支付配置时使用。
.meta	各级元数据目录中	查看	资源元信息，用来维护目录下资源在产品资源树中的附加信息；需要理解或调整资源说明、图标、排序、隐藏状态时使用。

资源文件

文件类型	常见位置或线索	说明页	说明
图片、字体、附件、压缩包等	public/、images/、主题素材目录、应用素材目录	查看	资源文件通常不是 Super JSON 元数据文件，但会被页面、报表、模板、主题、脚本或配置引用；移动或重命名时要同步检查引用路径和 .meta。