元数据文件存储

SuccApp 元数据有两种常见存储形态：服务器运行时的数据库存储，以及 AI 低代码开发（AI building）使用的本地工作区文件存储。理解这两层关系，可以避免把本地 .spg、.dash、.tbl 和 .meta 文件误认为服务器生产环境中的真实落库形态。

服务器中的存储

在生产环境中，元数据文件存储在数据库中。服务器通过元数据仓库服务读写项目、目录、文件内容、版本和资源属性；文件系统路径只是产品和接口层面的资源路径表达，不表示生产环境一定存在同名磁盘文件。

元数据文件的核心存储表是：

系统表	作用
META_FILES 文件表	存放元数据目录结构、文件基本信息和当前文件内容。PROJECT_NAME、PARENT_DIR、NAME 共同表达资源路径；CONTENT 保存当前内容，可能按 IS_GZ 压缩；REVISION、HASH、SIZE 等字段用于版本和内容变化判断。
META_REVISIONS 历史版本表	记录元数据资源历史版本内容和修改信息，用于查看历史、恢复版本和清理版本。
META_FILES_REFLABELS 文件和标签的映射表	记录元数据文件与标签之间的关系，用于按标签检索和统计资源分类。

更多元数据相关系统表可在系统表的 meta 分组中查看。

提示

不要直接修改生产数据库中的元数据系统表。元数据的增删改应通过 SuccApp 设计器、SuccApp CLI、SuccApp for VS Code 或受控的服务端接口完成，这样系统才能同步维护版本、缓存、引用和权限相关信息。

本地工作区中的存储

AI 低代码开发流程会把服务器数据库中的元数据项目拉取到本地，形成一个适合 AI Agent 和 Git 处理的工作目录。克隆或拉取时，SuccApp CLI / SuccApp for VS Code 会读取服务器元数据树和文件内容，再转换成本地目录和文件。

本地工作区通常包含两类信息：

本地内容	说明
元数据文件	页面、仪表板、报表、模型、程序流、脚本、主题、配置和资源等内容以文件形式落在项目目录中，例如 .spg、.dash、.rpt、.tbl、.query、.afl、.wfl、settings.json 和图片资源。AI Agent 主要编辑这些文件。
.meta 文件	保存当前目录下直接子资源的附加属性，例如 id、revision、描述、排序、图标、隐藏状态、标签、option 和 customOption。这些属性在服务器中来自元数据系统表字段，本地则写入对应目录的 .meta 索引文件。

例如本地文件：

DEMO/app/portal.app/index.spg

它的文件内容保存在 index.spg 中；对应的资源属性保存在父目录的 .meta 中：

{
	"index.spg": {
		"id": "UfOoq4xbolMgpuFPItTdcE",
		"revision": 12,
		"desc": "门户首页",
		"order": 6,
		"modifier": "admin",
		"modifyTime": 1760966400000
	}
}

.meta 是本地工作区中的目录级资源元信息索引，不是服务器中的真实元数据文件。完整规则见 .meta 资源元信息。

同步时如何转换

克隆、拉取和推送会在服务器数据库形态与本地文件形态之间转换：

1. 克隆项目：从服务器读取项目、目录、文件内容和资源属性，把内容写成本地文件，把资源属性写入对应目录的 .meta。
2. 拉取变化：把服务器上的最新内容和属性刷新到本地同步基线，再应用到工作区。
3. 本地编辑：AI Agent 或人工修改项目目录中的元数据文件，必要时维护相关目录 .meta。
4. 推送变化：SuccApp 将本地文件内容和 .meta 中允许写回的属性提交给服务器，服务器再写入元数据系统表并返回权威的 id、revision、modifyTime 等信息。

本地工作区还会维护 .succapp/remote/ 下的服务器基线，用于判断本地变化、远端变化和冲突。日常编辑应面向项目目录中的文件和 .meta，不要把 .succapp/remote/ 当作业务工作目录。

编辑注意

1. 不要通过修改本地 .meta 中的 id、revision、creator、createTime、modifier、modifyTime 等服务器控制字段来改变服务器事实；推送时这些字段以服务器返回为准。
2. 新增、移动、重命名或删除元数据文件时，同时检查所在目录或目标目录的 .meta 和文件内部引用路径。
3. 如果只想修改页面、模型、报表等正文内容，优先编辑对应元数据文件；只有描述、排序、隐藏状态、标签、自定义属性等资源属性变化，才需要关注 .meta。
4. AI 低代码开发的完整工作流见元数据即代码和连接服务器与克隆项目。