dhis2-app-development

DHIS2 应用开发

你正在帮助开发者构建自定义 DHIS2 Web 应用。DHIS2 是一个健康信息管理平台，拥有自己的应用框架、组件库和 Web API。AI 助手经常会弄错 DHIS2——使用已弃用的 API 端点、错误的模式，或是通用库而非 DHIS2 专用工具。本技能旨在避免这些问题。

首先：确定你当前所处的项目状态

开始之前，先确认你是在现有 DHIS2 项目中工作，还是要从头开始。

检查项	方法	结果
项目根目录中存在 d2.config.js	搜索 d2.config.js	现有项目 — 跳过脚手架搭建
package.json 中包含 @dhis2/app-runtime	读取 package.json	现有项目 — 跳过脚手架搭建
两者都未找到	—	新项目 — 读取 references/bootstrapping.md

如果是现有项目，请先读取 d2.config.js 和 package.json，了解已有配置，再进行修改。

用户需要什么？

根据用户的任务阅读相应参考文档。大多数实际任务都同时涉及数据和 UI——阅读所有适用的文档。如果两者都需要，请先阅读 data-fetching.md，以便在构建 UI 之前了解 API 的结构。

场景	参考文档（按顺序阅读）
创建或搭建新的 DHIS2 应用	references/bootstrapping.md
运行、启动或部署 DHIS2 应用	references/running-your-app.md
获取或修改数据，但不构建 UI（钩子、脚本、批量操作）	references/data-fetching.md
构建用于显示数据的页面（列表、表格、详情视图）	references/data-fetching.md → references/ui-patterns.md
构建用于创建或编辑资源的表单	references/data-fetching.md → references/ui-patterns.md
添加导航、页面布局或侧边栏	references/routing.md → references/ui-patterns/sidebar.md
使用小部件构建仪表板或详情页	references/data-fetching.md → references/ui-patterns/widget.md → references/ui-patterns/dashboards.md
构建或设置任何 UI 组件的样式	references/ui-patterns.md
处理不同 DHIS2 版本之间的 API 差异	references/data-fetching.md（§ 功能标志）

规则

无论阅读了哪些参考文档，以下规则都适用于所有 DHIS2 工作：

• 仅使用 React 18。 不要使用 Suspense 获取数据，也不要使用 React 19 API（use()、useFormStatus 等）。使用 isLoading 和 CircularLoader 明确处理加载状态。
• 始终使用 @dhis2/ui 构建 UI 组件。不要使用 MUI、Chakra、Ant Design。仅当 UI 库不提供所需组件时，才使用自定义组件。
• 编写数据获取或 UI 代码前，始终克隆并阅读源代码。 你的训练数据对于 DHIS2 API 和组件属性并不可靠——源代码才是依据。
• 所有面向用户的字符串都使用 @dhis2/d2-i18n 中的 i18n.t()。
• 所有 DHIS2 资源（组织单元、数据元素等）都使用 displayName，而不是 name。
• 样式使用 CSS Modules 和 DHIS2 设计令牌（var(--spacers-dp16)、var(--colors-grey900) 等）。
• 每轮完成后都进行验证。 修改后运行 pnpm exec eslint 和 pnpm exec tsc --noEmit，以便尽早发现错误。继续之前先修复所有问题。无输出表示没有错误。

故障排除

构建 DHIS2 应用时可能遇到的常见错误：

症状	修复方法
ESLint 的 import/named 报错，提示具名导出有误，但这些导出在运行时正常且 IDE 没有报错	安装 eslint-import-resolver-typescript，并在 ESLint 配置中进行配置。