主题
命名约定
元数据项目中的文件名通常由资源名称和固定后缀组成。后缀决定文件类型，目录位置表达资源归属；资源的中文说明、业务描述、排序、图标等附加信息应放在资源元信息中，而不是依赖很长的文件名表达。
命名时优先考虑两件事：资源路径是否会出现在 URL 中，以及资源名是否需要和外部系统、物理表或长期引用保持一致。
基本规则
| 约定 | 说明 |
|---|---|
| 后缀固定 | .spg、.dash、.rpt、.tbl 等后缀用于匹配文件类型说明和 DTS 根结构。 |
| 同目录唯一 | 同一目录下文件名和目录名应保持唯一，避免资源引用和同步状态混淆。 |
| 名称稳定 | 项目名、应用名、文件夹名、关键数据模型名等会被长期引用，应稳定、简短、有意义，避免频繁调整。 |
| 描述进元信息 | 资源中文描述、业务口径、使用说明优先写入资源描述、.meta 或同名说明文件中，不把说明性长句塞进文件名。 |
| 引用字段稳定 | 文件内部的 id、name、字段名、组件名等可能被其他资源引用，重命名前要全局搜索调用方。 |
按资源类型命名
不同资源对名称的要求不同。常见做法如下：
| 资源 | 推荐命名 | 示例 | 说明 |
|---|---|---|---|
| 可能出现在地址栏中的资源 | 小写、短横线分隔、简短且符合 URL 习惯 | sales-analysis、customer-portal | 适用于项目名、应用名、门户模板名、spg 页面名、目录名等。这些资源可能被用户通过 URL 直接访问，中文描述写到资源元信息中。 |
| 数据模型 | 大写、下划线分隔、尽量不超过 32 个字符 | SALES_ORDER、DIM_CUSTOMER | 适用于 .tbl 等和数据库表强相关的模型。模型名建议和物理表名保持一致，表描述写到资源描述或模型说明中。 |
| 普通页面、报表和脚本 | 简短、可读、能表达用途 | monthly-sales.rpt、order-detail.spg | 面向 URL 或外部引用的资源优先使用英文小写短横线；只在内部维护的资源也应避免过长和频繁变化。 |
文件名可以使用中文，SuccApp 也能正常工作。但中文名通常表达业务含义，业务叫法变化后容易引起资源重命名、引用调整和同步冲突。对项目、应用、目录和关键模型这类基础资源，建议使用更稳定的英文或约定缩写，把中文展示名、业务说明写入元信息。
.meta 资源元信息
.meta 是 SuccApp 克隆到本地工作目录后，在各级目录中维护的资源元信息索引文件，用来保存该目录下直接子资源的 id、描述、排序、图标、隐藏状态等属性。服务器上不存在名为 .meta 的文件；系统运行时，这些信息保存在后台数据库字段中。
新增、删除、重命名或移动本地资源时，需要同步检查相关目录 .meta：
- 文件资源的元信息保存在父目录
.meta中对应文件名的条目里，例如demo.app/.meta中的index.tpg条目描述demo.app/index.tpg。 - 目录资源自身的元信息保存在父目录
.meta中对应目录名的条目里；目录内部.meta记录该目录自己的直接子资源。 - 手工移动或重命名文件时，应同步更新原目录和目标目录
.meta中的对应条目。
更多字段和维护规则见 .meta 资源元信息。
同名伴随文件
很多元数据资源可以带同名伴随文件。伴随文件和主资源共享同一个基础文件名，只是在主后缀后继续追加脚本、样式或说明后缀。
常见伴随文件如下：
| 伴随文件 | 用途 | 示例 |
|---|---|---|
<资源名>.<类型>.ts、<资源名>.<类型>.action.ts | 页面、报表、数据模型等资源的脚本文件，按资源类型和运行机制加载或执行。 | order-detail.spg.ts、monthly-sales.rpt.ts、SALES_ORDER.tbl.action.ts |
<资源名>.<类型>.less、<资源名>.<类型>.css | 页面或资源级样式文件，按资源类型和运行机制加载。 | order-detail.spg.less、sales-dashboard.dash.less |
<资源名>.<类型>.md | 资源说明文档，可描述使用场景、做法、注意事项和实现方式，也可帮助 AI agent 理解资源。 | order-detail.spg.md、SALES_ORDER.tbl.md |
目录资源内的 README.md | 目录型资源的说明文档。 | demo.app/README.md |
伴随文件是否会被自动加载，取决于资源类型和运行机制。例如 page1.spg.ts、page1.spg.less 是 page1.spg 的页面级脚本和样式；*.spg.ts、*.rpt.ts、*.dash.ts 等页面脚本也有对应模板；脚本模型可能使用 *.tbl.action.ts。不要只重命名主文件而遗漏同名伴随文件。
重命名和移动
重命名或移动元数据资源前，先判断操作入口：
- 在浏览器图形化界面中重命名或移动在线资源时，系统会自动重构受影响资源中的路径引用。
- 在 SuccApp CLI 或 SuccApp for VS Code 中直接修改本地文件名、目录名后再 push 时，系统不会替本地改动重构引用。用户或 AI agent 需要在本地同步完成引用调整，再一起提交。
本地重构时至少检查：
- 主资源文件、同名伴随文件和相关目录
.meta是否一起维护。 - 旧文件名、旧路径、资源 id、组件 id、数据集 id 是否被其他资源引用。
- 页面、报表、模型、脚本、样式和说明文件中的相对路径是否仍然有效。
- 关键数据模型名是否仍和物理表、SQL、接口或外部系统约定一致。
批量重命名资源前，建议先全局搜索旧名称、文件路径、组件 id 和数据集 id，确认引用影响后再修改。
