basic-custom-app-build

Domo 基础应用构建手册

适用场景

• 在全新 Domo 自定义应用的项目启动时使用。
• 接手现有应用并将其规范化，使其符合平台最佳实践时使用。

进度检查清单

复制此清单，并在工作过程中更新

Build Progress:
- [ ] Phase 0: Rules loaded
- [ ] Phase 1: Manifest & contracts
- [ ] Phase 2: App shell (domo.js)
- [ ] Phase 3: Data access
- [ ] Phase 4: App storage (if needed)
- [ ] Phase 5: Toolkit clients (if needed)
- [ ] Phase 6: Feature skills (AI / Code Engine / Workflow — as needed)
- [ ] Phase 7: Performance review
- [ ] Phase 8: Build & publish
- [ ] Phase 9: Verification

阶段 0 — 加载规则（始终启用）

编写任何代码之前应用：

• rules/core-custom-apps-rule.md
• rules/custom-app-gotchas.md

阶段 1 — 清单与契约

使用 manifest。

先定义所有外部资源映射——数据集、集合、工作流、Code Engine 包。其他所有内容都依赖这些映射。 仅使用别名安全的名称（^[A-Za-z][A-Za-z0-9]*$），不得包含空格或特殊字符。

除了创建 manifest.json 之外，还要检查根目录中是否已有 thumbnail.png，并将其复制到新应用的 public 文件夹中。

接手现有应用？ 修改前，请根据实际代码用法审查当前的 manifest.json。

阶段 2 — 应用外壳

使用 domo-js。

设置基础配置：导入 ryuu.js、通过 domo.navigate() 导航、添加事件监听器、获取环境信息。

使用 DA CLI 的高级用户？ 请 Agent 同时使用 da-cli 进行脚手架搭建和清单实例工作流。除非用户明确要求 Agent 使用，否则不应使用。

阶段 3 — 数据访问（需要查询 domo 数据集时）

使用 dataset-query（主要工具）和 data-api（路由概览）。

使用 @domoinc/query 构建查询。读取所有数据集时都使用 Query API——它会遵循页面筛选器，并在服务器端进行聚合。

编写 UI / 数据映射逻辑前，获取 manifest.json datasetsMapping 中每个数据集的真实架构，并创建明确的字段映射（日期字段、主要指标、维度字段）。除非已在架构中确认，否则不要使用 sales、category 或 order date 等猜测名称。

如果可视化所需字段缺失，请立即报错并清楚说明映射错误，不要渲染为零。

需要原始 SQL？ 使用 sql-query，但请注意，SQL 会忽略页面筛选器。

阶段 4 — 应用存储（需要 appdb 或任何用户数据录入时）

需要创建存储时，使用 appdb 和 appdb-collection-create。

如果应用只读取数据集，则跳过此阶段。需要持久化应用专属状态、用户偏好或文档式数据时，使用 AppDB。

如果所需集合尚不存在，请先运行 appdb-collection-create，配置数据存储和集合，然后再接入文档 CRUD。

阶段 5 — 工具包客户端（需要 appdb、domo 工作流或 domo SQL 查询时）

使用 toolkit。

在能带来价值时，改用类型化的 @domoinc/toolkit 客户端（结构化响应、类型安全）。简单应用无需使用。

阶段 6 — 功能技能（按需使用）

仅加载应用实际需要的技能（此处列出 3 个示例，但你还可以使用更多技能）：

所需功能	技能
AI 文本生成或文本转 SQL	ai-service-layer
服务器端函数（密钥、外部 API）	code-engine + code-engine-create + code-engine-update
触发自动化工作流	workflow

决策指南： 如果用户没有提到 AI、Code Engine 或 Workflows，则完全跳过此阶段。不要为应用添加不必要的复杂性。

服务器端函数的强制触发条件： 如果应用功能需要服务器端行为（密钥、外部 API 调用、特权转换），请先创建或更新 Code Engine 包，然后同步 manifest.json packagesMapping，最后再在应用代码中接入运行时调用。

第 7 阶段 — 性能审查

使用 performance。

定稿前审查所有查询。检查是否获取了完整数据集、缺少聚合，以及是否包含不必要的列。

第 8 阶段 — 构建与发布

使用 publish。

npm run build → cd dist → domo publish。首次发布时，将生成的 id 复制回源清单。

第 9 阶段 — 验证

发布后，确认：

• 应用在 Domo 中加载时没有控制台错误
• 所有数据集别名均可解析（数据调用没有 404）
• AppDB 集合已在卡片 UI 中接入（如果使用）
• 页面筛选器可正确传递（如果应用嵌入了仪表板）
• 导航使用 domo.navigate()，而不是 <a href>
• 缩略图已复制到 public 文件夹

构建时的防护措施

• 仅限客户端：不使用 SSR／服务器路由／服务器组件。
• 使用 Vite base: './'。
• 除非有意处理重写规则，否则优先使用 HashRouter。
• 仅将 domo.env.* 视为便利功能；进行信任判断时使用经过验证的身份。