dhis2-apps

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
创建用户界面	references/ui-patterns.md
处理不同 DHIS2 版本间的 API 差异	references/data-fetching.md（§ 功能标记）
使用 DHIS2 类型为 API 响应添加类型	references/types.md
为钩子或组件编写测试	references/testing.md

如何在此代码库中工作

编写代码前，如果项目根目录中存在 CLAUDE.md（或同等的 Agent 文件），务必先阅读——其中包含特定于应用的决策、约定和结构，这些内容优先于通用模式。

工作时：

• 为新功能和辅助函数编写测试。 阅读 references/testing.md 了解相关模式。测试与源文件放在一起（例如，useApps.test.ts 与 useApps.ts 放在同一目录）。
• 为复杂或不易理解的逻辑添加注释。 注释应解释某段逻辑为何如此运作——例如隐藏的约束、DHIS2 的特殊行为，或针对已知问题的变通方案。不要添加只是复述代码的注释。
• 优先编写易读的代码。 使用 Boolean(value)，而不是 !!value；复杂条件应使用具名变量；使用明确的 return，而不是层层嵌套的三元表达式。为下一位开发者编写代码，而不是一味追求简短。
• 及时更新 CLAUDE.md。 添加新功能、钩子或架构决策后，更新 CLAUDE.md，说明构建的内容及其原因。如果没有 CLAUDE.md，就创建一个。这样后续会话和团队成员才能了解代码库。

库版本：

@dhis2/ui、@dhis2/app-runtime 和应用平台库都随附源代码。直接阅读 node_modules/@dhis2/<package>/——这是了解组件属性、钩子签名和导出的最准确来源。不要依赖训练数据或 opensrc 来了解这些包。

库	源码位置
@dhis2/ui	node_modules/@dhis2/ui/ — 组件属性、导出项、设计令牌
@dhis2/app-runtime	node_modules/@dhis2/app-runtime/ — 钩子签名和上下文 API
@dhis2/cli-app-scripts	构建工具 — 默认情况下，脚手架命令会使用最新版本

opensrc 是查阅 DHIS2 后端（dhis2/dhis2-core）的最后手段——仅当 @dhis2/api-types OpenAPI 规范未涵盖所需内容，或规范看起来有误时才使用。先查阅规范；只有规范不足时才查看 Java 源码。

规则

无论阅读了哪些参考资料，所有 DHIS2 工作都必须遵守以下规则：

• 仅使用 React 18。 不要使用 Suspense 获取数据，也不要使用 React 19 API（use()、useFormStatus 等）。使用 isLoading 和 CircularLoader 明确处理加载状态。
• 始终使用 @dhis2/ui 提供的 UI 组件。不要使用 MUI、Chakra 或 Ant Design。只有当 UI 库未提供所需组件时，才使用自定义组件。
• 编写代码前务必先阅读源代码。 对于 DHIS2 前端库（@dhis2/ui、@dhis2/app-runtime），直接阅读 node_modules/@dhis2/<package>/——这些库随附源代码。对于 DHIS2 后端 API，使用 opensrc（参见 references/data-fetching.md）。训练数据对这两者都不可靠。
• 所有面向用户的字符串都使用 @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 应用时可能遇到的常见错误：

症状	解决方法
对运行时正常且 IDE 中未显示错误的命名导出报 ESLint import/named 错误	安装 eslint-import-resolver-typescript，并在 ESLint 配置中进行配置。