数据与集成参考
先按数据形状、生命周期和所有者选择能力，再开始配置。不要因为所有能力都“能存数据”，就把状态、配方、表格和外部系统记录放进同一个位置。
何时查这页
- 不确定应该使用 Variable、Recipe、RecordStore 还是 Query；
- 运行后数值重置、持久值没有保留，或部署到另一 target 后数据不同；
- Page 和 Graph 需要复用同一个外部 HTTP 调用；
- 运行页多语言、表格数据或 Asset 路径不符合预期；
- Query 测试成功，但现场参数、认证或写入结果不正确。
能力选择
| 需求 | 使用能力 | 例子 |
|---|---|---|
| 当前已加载运行时中的小型共享状态 | App Variable | 当前工单、运行模式、临时结果 |
| 需要由该 Runtime target 保留的小型值 | Saved Variable | 标定值、阈值、累计计数 |
| 只在一个 Graph 实例中使用的临时值 | Graph Variable | 循环索引、中间判断结果 |
| 一组可命名、切换的工艺参数 | Recipe | 产品型号、温度和压力组合 |
| 当前设备上的轻量多行数据 | RecordStore | 点位表、物料表、批次行 |
| 外部系统数据或跨设备共享记录 | HTTP Query | MES 工单、ERP 配方、生产报工 |
| 运行页翻译 | i18n | 按钮、报警和状态文案 |
| 图片、视频、3D 模型和上传文件 | Asset | 工艺图、设备模型、附件 |
大量历史、复杂检索和跨设备共享不应放在 Variable 或 RecordStore；应由外部数据库或业务系统负责，再通过 Query 访问。
入口与核心对象
| 能力 | 编辑入口 |
|---|---|
| App / Saved Variable | App Settings → Variables |
| Recipe | App Settings → Recipes；Object tree 中需要一个 RecipeManager |
| RecordStore | 在 Object tree 添加 RecordStore，从 Properties 配置字段、主键和存储模式 |
| HTTP Query | App Settings → Queries |
| i18n | App Settings → i18n；Widget 文本属性也可就地选择翻译 key |
| Asset | Resources → Assets 或 Files |
Variable
| 类型 | 当前值在哪里 | 重要行为 |
|---|---|---|
| App Variable | 当前 materialized runtime | Page 和 Graph 可共享；重新加载或重新部署后从定义的初始值开始 |
| Saved Variable | 当前 Runtime target 的 App 状态 | 重新启动后继续使用；迁移到另一 target 时不会自动带走当前值 |
| Graph Variable | 单个 Graph 实例 | 不与其他 Graph 实例共享，不用于长期保留 |
Page 表达式和 method 通过 QX.variables 读取 App Variable。Graph 使用 Get Variable / Set Variable 明确选择 graph、app 或 saved scope。需要改变 Object 自身状态时调用 Object method，不要把 Object 运行状态复制成多份 Variable 真相源。
Recipe 与 RecordStore
Recipe 适合字段固定、需要按名称整体保存和切换的参数组。每个 App 只需要一个 RecipeManager；运行流程应明确何时选择、应用和保存 Recipe。
RecordStore 适合在设备端维护多行结构化数据：
File模式用于需要在该 target 上保留的行数据；Memory模式用于当前运行实例的临时表；- 字段 schema 和 Primary Key 在 Object Properties 中配置；
- 页面表格通过 Object method 读取、添加、更新和删除行。
RecordStore 不是外部数据库。数据量、查询复杂度或共享范围增大时，改用外部系统和 Query。
HTTP Query
当前 Query 类型是 HTTP，支持 GET、POST、PUT、DELETE 和 PATCH。在 Settings 中维护：
- URL 与
{{parameter}}运行参数； - Headers 和固定 URL Params；
- JSON、Form 或 Raw Body；
- None、Bearer 或 Basic Auth；
- Timeout。
Page method 使用 QX.queries.<name>.run(...)，Graph 使用 Query 节点。两处都引用同一份 App Query，不复制请求配置。
Settings 中的 Send 会从当前 Runtime target 执行请求并显示状态和响应。写入型 Query 应先对测试环境或可撤销数据验证；不要用生产数据做第一次 Send。
Bearer token、Basic 用户名和密码属于 Query 配置。不要把生产凭据提交到不受控 Git、源 ZIP 或普通 AI 对话；交付前按项目的凭据策略检查和清理。
i18n 与 Asset
- i18n 先定义语言和默认语言，再维护 key。缺少目标语言时回退到默认语言，仍缺少时显示 key。
- Widget 文本应引用 i18n key，不要为每种语言复制一套 Page。
- Asset 使用 App 内相对路径，不使用开发机绝对路径。
- 运行页只能访问已包含在 runtime package 中的 Asset；上传文件应通过专用 Upload Widget。
关键规则
- Variable 适合小值，不适合图片、历史表或大 JSON。
- Saved Variable 当前值是 target-specific runtime state，不是 App 源文件。
- Query 是外部调用合同，不是数据副本，也不是数据库。
- Recipe 适合成套参数，RecordStore 适合本机行数据，两者不要互相代替。
- 外部写入必须定义超时、错误处理、幂等或重复提交策略。
- 数据能力保存后仍要从正确 Runtime target 验证，不只看编辑器表单。
如何验证
- 在 Settings 或 Object Properties 确认名称、类型、默认值、字段和参数。
- 保存后检查 Problems，确认 Page / Graph 引用没有失效。
- App Variable 验证当前运行内共享，以及重新加载后的初始值。
- Saved Variable 验证重启后保留，并确认换 target 后不会误用旧值。
- Recipe 验证选择、应用、保存和重新打开；RecordStore 验证增删改查和主键。
- Query 先用已知参数执行无副作用 Send，再验证失败、超时和写入去重。
- 切换运行页语言，并从目标运行页检查 Asset 下载或上传。