App 模型
App 是平台的最小交付单元。一个 app 可以独立启动、停止、调试、导入、导出、接入 Git，也可以拥有自己的用户、角色、对象、页面、Graph、query、变量、配方和资源文件。
App 包含什么
一个典型的 app 工作区结构：
app/
manifest.json ← app 身份、首页、模块开关
CustomScripts.csproj ← IDE 项目文件（可用 VS/Rider 打开）
objects.json ← 设备与业务对象
variables.json ← 变量定义
saved-variables.json ← 持久变量当前值
recipes.json ← 工艺配方
queries.json ← 外部系统查询合同
i18n.json ← 运行页多语言文案
users.json ← app 用户和角色
pages/
home.qxpage ← 页面源文件
components/
station-card.qxcomponent ← 可复用组件
graphs/
startup.qxgraph ← Graph 源文件
scripts/
MyDevice.cs ← C# 自定义代码
assets/
sample.glb ← 资源文件
data/
record-stores/ ← 表格数据持久化
compiled/ ← 构建产物（不提交 Git）
custom-code/CustomScripts.dll
custom-code/CustomScripts.build.json
实际目录可能按项目调整。启心自动化平台 从 app root 递归扫描 .qxpage、.qxcomponent、.qxgraph 和 .cs 文件。pages/、graphs/、scripts/、assets/ 是创建约定，不是校验边界。
关键文件说明
| 文件 | 用途 | 面向谁 |
|---|---|---|
manifest.json | app 名称、图标、默认首页和模块开关 | 管理员 |
**/*.qxpage | 页面源文件（界面 + 方法 + 权限） | 实施人员 |
**/*.qxcomponent | 可复用组件模板 | 实施人员 |
**/*.qxgraph | Graph 自动化流程 | 实施人员 |
**/*.cs | app-local C# 扩展代码 | 工程人员 |
objects.json | 设备对象和业务对象树 | 实施人员 |
variables.json | 应用变量定义（运行期 / 持久化） | 实施人员 |
saved-variables.json | 持久变量的当前值 | 运行时自动维护 |
recipes.json | 工艺参数配方 | 管理员 |
queries.json | 外部系统集成合同 | 实施人员 |
i18n.json | 运行页多语言文案 | 实施人员 |
users.json | app 用户和角色 | 管理员 |
compiled/custom-code/CustomScripts.dll | C# + Graph 构建产物 | 自动生成 |
Page 在 app 中的位置
Page 是 app 的现场 UI。每个 .qxpage 文件包含页面布局、控件、page method 和权限配置。
Page 用于：
- 设备运行看板
- 工位操作界面
- 报警/状态列表
- 参数维护页
- 文件上传页
- 3D 设备查看页
Page method 是页面内的可调用逻辑单元。分为两种：
| 类型 | 适用场景 | 编辑方式 |
|---|---|---|
| TypeScript method | 复杂逻辑、类型操作、错误处理、算法 | 代码编辑器 + LSP 类型提示 |
| Flow method | 简单顺序调用、对象方法、toast、赋值、条件 | 可视化动作序列编辑器 |
详细操作见页面与组件。
Component 在 app 中的位置
Component 是 app 级 .qxcomponent 可视化模板。适合把一组 widget 做成可重复使用的 item：
- 工站状态卡片
- IO 点位信息行
- 报警条目
- 任务 chip
Repeater 控件通过 componentRef 引用组件，组件可被多个 page 复用。
Graph 在 app 中的位置
Graph 保存为 .qxgraph 文件，编排自动化流程。它适合：
- 启动、停止、复位、换型等流程
- 多个对象方法的顺序和条件
- 查询外部系统后再决定下一步
- 需要断点调试的复杂逻辑
Graph 修改后需要构建 app project 才能进入运行时。详见Graph 自动化和构建流程。
Script 在 app 中的位置
Script 是 app-root-relative .cs 文件，用于扩展平台标准库没有的能力：
- 定义项目专用的设备和业务对象
- 封装 PLC、仪表、扫码枪等协议
- 定义可被 Graph 调用的方法
- 定义复杂数据结构和选项
脚本编译后进入 app 的 callable catalog。page、Graph 和 AI 都可以基于 catalog 使用这些能力。
用户和角色
App 用户和角色保存在 users.json 中，独立于开发者登录。用于控制运行页访问和控件显示。详见用户与权限。
Git 与导入导出
App 工作区可作为独立 Git 仓库管理。ZIP 导出包不携带 .git 历史，但保留 CustomScripts.dll 以支持无源码运行。