元数据项目

元数据项目是 SuccApp 中组织和交付业务资源的顶层单位。一个项目在服务器中表现为一个项目根目录，在本地工作区中表现为一个同名目录；数据模型、数据加工、调度、页面、程序流、应用、仪表板、报表、主题、模板、项目设置和配套素材，都按约定目录保存为元数据文件。

一个元数据项目通常用于交付一个客户、一个组织或一套相互关联的业务应用。企业内部不同业务部门的应用虽然归属不同，但往往共享底层基础数据、统一门户入口、公共模型、主题、模板和项目级配置，这类资源更适合放在同一个元数据项目中，再在项目内部按应用、业务板块和目录结构划分边界。

普通元数据项目用于承载业务项目。系统元数据项目固定为 sysdata，用于承载系统表、系统设置、系统数据源、内置应用和扩展等全局资源。两者共享大部分目录结构规范，但 sysdata 的影响范围更大，专有目录和编辑风险见系统元数据项目。

元数据项目的用途

元数据项目用于把一组业务上紧密相关的资源放在同一个边界内管理：

1. 组织业务资源：把同一业务域内的应用、页面、报表、数据模型、流程、脚本和素材放在同一个项目下，便于查找、复用和整体交付。
2. 沉淀公共底座：把多个业务应用共用的数据模型、加工任务、调度任务、门户入口、公共页面和程序流放在同一个项目内，减少重复建设。
3. 管理项目级配置：在 settings/settings.json 中维护项目名称、可用数据源范围、分析选项、显示格式、国际化和项目级存储等配置。
4. 复用项目资产：在 settings/templates/、settings/themes/、settings/styles/、settings/attachments/ 等目录维护模板、主题、样式和素材库。
5. 支持版本协作：SuccApp CLI 和 SuccApp for VS Code 会把服务器项目克隆为本地目录，团队可以用 Git 管理差异、审查变更、回退版本和发布环境。
6. 控制交付边界：测试环境、生产环境和客户交付包通常按项目维度同步和验收，项目边界越清晰，发布风险越容易控制。

什么时候新建元数据项目

新建元数据项目需要谨慎。项目不是普通文件夹，也不是业务部门的简单分类；它会影响资源引用、项目设置、数据源范围、版本协作、同步发布和后续运维。通常先考虑在现有项目内按应用、目录或业务板块划分，只有确实需要完整隔离时才新建项目。

满足下面情况时，才通常考虑新建普通元数据项目：

1. 两套内容从基础数据、数据模型、加工任务、调度任务到页面、程序流、应用和门户入口都基本独立。
2. 两套内容面向不同客户、不同组织或完全隔离的交付范围，没有共享基础数据、公共页面、项目资源和统一入口。
3. 两套内容需要独立的发布节奏、版本协作、运维流程、备份恢复策略或权限边界。
4. 两套内容需要完全不同的项目级配置，例如可用数据源、数据文件存储、模型附件存储、主题、模板和项目素材。

下面情况通常不需要新建项目：

1. 只是新增一个页面、报表、数据模型、加工任务、调度任务或流程，应优先放入现有项目的对应目录。
2. 只是不同业务部门使用同一套基础数据、统一门户入口或公共模型，应在同一项目内划分应用和业务板块。
3. 只是想用目录分类资源，应在项目内建立业务目录，不要用项目代替文件夹。
4. 资源会被当前项目内大量页面、模型或脚本引用时，拆到新项目会增加跨项目引用和发布成本。
5. 需要修改系统数据源、登录页、系统设置、内置应用或扩展时，应进入 sysdata，不要新建普通项目。

有权限的用户可以通过浏览器中的项目管理页面创建项目，也可以使用 SuccApp CLI：

succapp server project create SALES --desc="Sales demo"

创建项目只是在服务器上生成项目根目录。需要本地开发时，还要用 SuccApp CLI 或 SuccApp for VS Code 把项目克隆到工作区。

项目目录结构规范

元数据文件的位置同时表达资源类型、所属模块和作用范围。不同项目可能只包含下面一部分目录，实际结构以当前工作区为准；如果同类文件已有落盘方式，优先沿用当前项目的做法。

/project/
   ├── .meta                                     # 仅本地工作区存在，保存项目根目录下直接子资源的附加元信息
   ├── data/                                     # 公共数据模型、取数、加工和数据相关资源
   │   ├── tables/SAMPLE_DIM.tbl
   │   ├── tables/SAMPLE_FACT.tbl
   │   ├── tables/process/LOAD_SALES.tbl
   │   ├── tables/process/load-sales.action.ts
   │   └── ...
   ├── app/                                      # 低代码应用、页面和应用内资源
   │   ├── example-web.app/
   │   │   ├── settings.json                     # 应用设置
   │   │   ├── index.tpg
   │   │   ├── data/
   │   │   ├── assets/
   │   │   └── ...
   │   └── ...
   ├── ana/                                      # 仪表板、报表、分析资源
   │   ├── dashboards/EXAMPLE_DASH.dash
   │   ├── reports/EXAMPLE_REPORT.rpt
   │   └── ...
   ├── fapp/                                     # 报表填报应用和流程表单资源
   │   ├── forms/EXAMPLE_FORM.fapp
   │   ├── workflows/EXAMPLE_FLOW.wfl
   │   └── ...
   ├── public/                                   # 项目公开资源
   │   ├── images/example.png
   │   ├── docs/example.docx
   │   └── ...
   ├── settings/                                 # 项目级配置、模板、主题、样式和附件
   │   ├── settings.json
   │   ├── styles.json
   │   ├── styles/
   │   │   ├── componentStyle/button/PRIMARY.json
   │   │   ├── conditionStyle/table/WARNING.json
   │   │   └── tooltipStyle/INFO.json
   │   ├── templates/
   │   │   ├── spg/example-template/template.json
   │   │   ├── spg/example-template/template.spg
   │   │   └── ...
   │   ├── themes/
   │   │   ├── dash/example.theme/theme.json
   │   │   ├── dash/example.theme/thumbnail.png
   │   │   └── ...
   │   ├── attachments/
   │   │   ├── library/images/example.png
   │   │   ├── library/icons/example.svg
   │   │   ├── private/{hash}.png
   │   │   └── ...
   │   ├── dateRoles/YEAR.tbl
   │   ├── geoRoles/REGION.tbl
   │   └── ...
   └── test/                                     # 回归测试脚本和期望结果
       ├── smoke.qunit.ts
       ├── expected/smoke.expected.md
       └── ...

项目目录划分应先判断资源是否属于某个具体应用。低代码应用开发中，只被一个应用使用的页面、模型、脚本、素材、报表和填报资源，应尽量放到对应的 app/{appId}.app/ 目录内部，保持应用目录内聚、独立，便于后续迁移、复制和交付。跨应用共享的基础数据、从第三方系统提取或加工后的公共数据，以及会被多个应用引用的数据模型，放在项目级 data/tables/ 目录下。

ana/ 和 fapp/ 主要用于保存跨应用共用的报表、可视化和填报任务。一般低代码应用开发较少直接使用这两个项目级目录；如果资源只服务于某个应用，应优先放入应用内部，而不是放到项目公共目录。

常见目录和配置文件按下面规则理解：

目录或文件	说明
.meta	保存当前目录下直接子资源的附加元信息，例如资源 id、描述、排序、图标和隐藏状态。.meta 只在 SuccApp CLI / SuccApp for VS Code 克隆到本地后使用，是本地工作目录中的目录级资源元信息索引；服务器项目中不存在同名文件。详见 .meta 资源元信息。
app/	保存低代码应用、门户、页面、应用内数据、应用脚本、应用素材和应用私有资源。应用目录通常以 .app 结尾，应用设置位于 app/**/*.app/settings.json。只被该应用使用的资源应优先放在应用目录内部。
ana/	保存跨应用共用的仪表板、报表和分析资源。应用专属的可视化或报表资源应优先放在对应应用目录内。
data/tables/	保存项目级公共 .tbl 文件。.tbl 文件内部区分具体类型，可以是基础数据模型、取数模型、数据加工模型或脚本相关模型等；系统表模型集中在 sysdata/data/tables/。
data/tables/**/*.action.ts	保存项目级数据加工脚本，可理解为批处理脚本，主要用于模型数据的加工处理，也可以加入计划任务执行。
fapp/	保存跨应用共用的报表填报应用、填报任务、流程表单和工作流资源。应用专属表单资源应优先放在对应应用目录内。
public/	保存可直接作为静态资源访问的项目公开文件，不应放入密码、密钥或本机私有路径。
settings/settings.json	普通项目的项目级配置，保存项目基本信息、数据源范围、分析选项、表单、显示格式、国际化和项目级存储配置。
settings/styles.json、settings/styles/	保存项目级样式入口和组件样式、条件样式、提示样式等可复用样式定义。
settings/templates/{spg,dash,rpt,fapp}/	保存页面、仪表板、报表、表单等模板。模板目录内通常包含 template.json、模板内容文件、缩略图和素材。
settings/themes/{dash,spg,rpt,fapp}/{themeId}.theme/	保存项目级主题。主题目录内通常包含 theme.json、thumbnail.png 和 images/。
settings/attachments/library/	保存项目资源库中的图片、图标、视频等可复用素材。
settings/attachments/private/	保存页面或对象内部引用的私有素材，通常由上传或引用流程维护，文件名可能是内容标识。
settings/dateRoles/、settings/geoRoles/	保存项目级日期角色、地理角色，角色文件通常也是 .tbl。
test/	保存回归测试脚本、测试配置和期望结果。

修改目录或文件时遵守下面规则：

1. 先确认文件属于哪个项目、哪个应用、哪个目录和哪个文件类型，不要只按后缀推断。
2. 只被单个应用使用的资源优先放入对应 .app 目录；跨应用共享的基础数据、第三方系统数据和公共加工模型放入 data/tables/。
3. 新增、移动、重命名或删除资源时，同步检查相关目录 .meta 和引用路径。
4. 修改项目级或应用级配置前，全局搜索配置项名称、资源路径和引用方。
5. 普通项目不直接维护 .jdbc 数据源连接文件；系统数据源通常位于 sysdata/data/sources/*.jdbc，普通项目通过项目设置引用可用数据源。
6. 不把运行时临时文件、真实生产密码、本机绝对路径或不可复现的私有状态写入项目。

系统元数据项目

sysdata 是固定的系统元数据项目，用于保存系统级元数据。它和普通项目一样使用 app/、data/、settings/、public/、fapp/ 等目录；克隆到本地工作区后，也会出现用于记录目录直接子资源附加元信息的 .meta 文件。sysdata 中很多文件会影响整个 SuccApp 环境，不属于普通业务交付项目。

/sysdata/
   ├── data/
   │   ├── sources/default.jdbc                  # 系统数据源连接配置
   │   ├── tables/sec/USERS.tbl
   │   ├── tables/sys/SYS_PROPERTIES.tbl
   │   ├── tables/meta/META_FILES.tbl
   │   ├── tables/flow/FLOW_TASKS.tbl
   │   └── ...
   ├── app/                                      # 系统内置应用
   │   ├── default.app/
   │   ├── monitor.app/
   │   ├── security.app/
   │   └── ...
   ├── ana/                                      # 系统分析资源
   ├── fapp/                                     # 系统级表单资源目录
   ├── extensions/                               # 用户安装或覆盖的系统扩展
   │   ├── example-extension/package.json
   │   ├── example-extension/main.action.ts
   │   └── ...
   ├── public/                                   # 系统公共资源、登录页、Logo 等
   │   ├── logo.png
   │   ├── login/
   │   └── ...
   └── settings/
       ├── settings.json                         # 系统设置
       ├── i18n/
       ├── hooks/
       ├── themes/
       ├── templates/
       ├── dateRoles/
       └── geoRoles/

sysdata 中需要特别区分的目录和文件：

目录或文件	说明
sysdata/settings/settings.json	系统设置，影响整个部署环境。它使用系统设置 schema，不使用普通项目的项目设置 schema。
sysdata/data/sources/*.jdbc	系统数据源连接配置。普通项目只通过项目设置控制哪些系统数据源可用，不直接保存 .jdbc。
sysdata/data/tables/	系统表模型，常见分类包括权限、元数据索引、流程任务、监控、数据治理和系统日志等。很多系统表受升级和保护规则影响。
sysdata/extensions/	系统扩展目录。用户安装或覆盖的扩展通常放在这里，每个扩展通常包含 package.json，并可能包含 *.action、*.action.ts、主题、图片、国际化或说明文件。
sysdata/app/default.app、sysdata/app/monitor.app、sysdata/app/security.app	系统内置应用，通常服务于默认门户、监控、权限、用户和组织管理。
sysdata/public/	系统公共资源，例如 Logo、登录页、公开脚本和页面模板。
sysdata/settings/i18n/、sysdata/settings/hooks/	系统级国际化和系统钩子脚本，修改后可能影响登录、权限、页面渲染或运行时行为。
sysdata/settings/themes/、sysdata/settings/templates/、sysdata/settings/dateRoles/、sysdata/settings/geoRoles/	系统内置或全局可复用主题、模板、日期角色和地理角色。普通项目也可以有同名目录，但作用范围不同。

注意

sysdata 中的文件会影响所有项目和系统运行。修改系统表、系统设置、数据源、扩展、内置应用、登录页或系统公共资源前，应先确认权限、备份、升级覆盖和发布范围；不要把普通项目的配置文件 schema 或编辑风险套用到 sysdata。