fusion-developer-app

Fusion 应用开发

适用场景

开发 Fusion Framework React 应用的功能、组件、钩子、服务或类型时，使用此技能。

常见触发情形：

• “为……添加组件 / 钩子 / 服务 / 页面”
• “接入 API”
• “配置 Fusion 模块”
• “此应用应使用哪个 Fusion Framework 钩子 / 包？”
• “将此偏好设置保存为应用设置”
• “添加书签 / 分析 / 功能标志支持”
• “为 AG Grid 添加图表 / 人员选择器 / 人员列”
• “如何编写自定义 Fusion Framework 模块？”
• “这应该是 Fusion 模块还是 React context？”
• “为此 Fusion 组件 / 钩子 / 路由编写测试”
• “在此测试中模拟身份验证、context、功能标志或 HTTP”

隐式触发情形：

• 在 src/ 中开发
• 提及 Fusion Framework 模块、EDS、@equinor/fusion-react-* 或 styled-components
• 提及应用设置、书签、分析、app.config.ts
• 添加路由、页面或数据获取层
• 添加或更新 *.test.ts / *.test.tsx、vitest.config.ts 或 Fusion 测试夹具
• 提及图表：@equinor/fusion-framework-react-ag-charts、chart.js、react-chartjs-2

不适用场景

以下情况不要使用此技能：

• 编写 / 分流 Issue → fusion-issue-authoring
• 编写技能 → fusion-skill-authoring
• 后端 / 服务变更（单独的仓库）
• CI/CD 或部署配置
• 架构文档（使用 ADR 模板）

对于 Fusion Framework 包的归属、钩子行为或示例查找 → 先使用 fusion-research。

所需输入

必填

• 要构建的内容：功能、组件、钩子或服务说明
• 所属位置：层级（组件、钩子、服务、类型）以及父级 / 同级上下文

对于有歧义的请求，实施前请查阅 assets/follow-up-questions.md。

视情况提供

• 功能涉及数据获取时的 API 端点详情
• 构建视觉组件时的设计 / 布局细节
• 扩展模块配置时的 Fusion 模块名称
• 状态应按用户持久化、可通过书签分享，还是仅在运行时有效
• 预期的测试层级：纯逻辑、钩子、组件、路由、完整应用或模块图
• 测试必须预置的外部边界：身份验证、context、服务、功能标志、书签或 HTTP

操作说明

步骤 1 — 了解项目约定

编写代码前先检查目标仓库：

1. 阅读 package.json — 包管理器（bun/pnpm/npm）、脚本和依赖项。
2. 阅读 tsconfig.json — TypeScript 设置和路径别名。
3. 扫描 src/ — 目录布局和分层结构。
4. 检查 docs/adr/ 或 contribute/ 中的项目专属编码规范。
5. 检查格式化工具 / 代码检查工具配置（biome.json、.eslintrc、prettier）。
6. 阅读 app.config.ts 和 app.manifest.ts — 端点和环境设置。
7. 对不确定的 Fusion Framework 行为、包归属或示例，先委托 fusion-research 调查，再编写代码。

遵循发现的约定。references/ 中的模式只是默认做法——若与项目专属规则不同，应以项目规则为准。

步骤 2 — 规划实现

从头创建新应用 → 使用 assets/new-app-checklist.md。

1. 将工作拆分为独立的文件 / 变更。
2. 将其映射到正确目录。典型的 Fusion 应用：
   • src/components/ — React 组件（表现层）
   • src/hooks/ — 自定义 React 钩子（状态和副作用逻辑）
   • src/api/ — API 客户端、数据转换和业务逻辑
   • src/types/ — TypeScript 接口、类型别名和枚举
   • src/routes.ts — 路由定义（使用 Fusion Router 时）
   • src/config.ts — Fusion 模块配置
   • src/App.tsx — 根组件和布局外壳
3. 尽早识别共享类型——在引用之前先定义。
4. 项目使用路由 → 遵循 references/using-router.md 中的 DSL 和页面模式。
5. 结构不同 → 遵循项目现有结构。

步骤 3 — 遵循代码规范进行实现

遵循步骤 1 中的项目代码标准。命名、TSDoc、行内注释、类型模式、代码风格和错误处理，请参照 fusion-code-conventions。

实现过程中遇到规范相关问题时，直接调用 fusion-code-conventions。

步骤 4 — 使用 styled-components、EDS 和 Fusion React 组件进行样式设计

遵循 references/styled-components.md、references/styling-with-eds.md、references/using-fusion-react-components.md：

• 使用 styled-components 进行自定义样式设计（Fusion 规范）。
• 除非项目已在使用，否则不要使用 CSS Modules、全局 CSS、Tailwind 或其他 CSS-in-JS 方案。
• 使用 Styled 对象模式，将样式化组件与其所在组件放在一起。
• 标准 UI 优先使用 EDS（@equinor/eds-core-react）。
• 使用 EDS 设计令牌（@equinor/eds-tokens）设置颜色、间距和字体排版。
• 使用 styled() 扩展 EDS，以实现自定义样式。
• 对于 EDS 未涵盖的领域需求（人员展示／选择、侧边面板、进度），使用 @equinor/fusion-react-*。
• 行内 style 属性仅用于一次性微调。
• 对于页面／视图结构（外壳组合、布局区域、空状态／加载状态），调用 agents/design.md。对于组件级 EDS 样式，调用 agents/styling.md。

步骤 5 — 配置数据获取（如适用）

遵循 references/configure-services.md、references/using-react-query.md、references/configure-mocking.md：

• 在 config.ts 或 app.config.ts 中通过 configureHttpClient 注册 HTTP 客户端。
• 使用 @equinor/fusion-framework-react-app/http 中的 useHttpClient(name) 访问客户端。
• 优先使用 @equinor/fusion-framework-react-app/* 钩子，而不是直接访问模块。仅在非 React 上下文中使用 framework.modules.*。
• React Query：将 useQuery 封装在精简的自定义钩子中。
• 查询键：根据 API 路径和参数派生。
• 将客户端 UI 状态保存在 React 状态／上下文中，而不是服务端状态库中。

步骤 6 — 配置 Fusion 模块（如适用）

确定用户需要哪个模块，然后只阅读匹配的参考文档：

需求	参考文档
HTTP 客户端／API 集成	references/configure-services.md
Context 模块	references/using-context.md
路由器和页面	references/using-router.md
AG Grid	references/using-ag-grid.md
AG Charts（独立使用）	references/using-ag-charts.md
AG Grid 集成图表	references/using-ag-grid-charts.md
EDS + Fusion React 组件	references/using-fusion-react-components.md
People 服务（搜索、展示、选择）	references/using-people-service.md
设置	references/using-settings.md
书签	references/using-bookmarks.md
分析	references/using-analytics.md
运行时配置／环境	references/using-assets-and-environment.md
功能标志	references/using-feature-flags.md
通用框架模块	references/using-framework-modules.md
自定义模块编写	references/using-custom-modules.md

• 通过 AppModuleInitiator 回调在 config.ts 中设置模块。
• 通过钩子访问模块：useAppModule、useHttpClient、useCurrentContext。
• 为新的 API 集成在 app.config.ts 中注册 HTTP 端点。
• 如果应用使用路由，则在 config.ts 中通过 enableNavigation 启用导航。
• 使用 Fusion Router DSL（layout、index、route、prefix）定义路由，以实现自动代码拆分。
• 如果框架 API 不明确，在选择实现模式之前使用 fusion-research。

步骤 7 — 添加或更新测试

遵循 references/testing.md。使用 agents/testing.md 专注于测试创建、维护和执行。它会将框架设置／渲染工作转交给 fusion-framework-testing，将模块／HTTP 状态工作转交给 fusion-framework-mocking。

第 8 步 — 验证

使用 assets/review-checklist.md 作为生成后的检查清单。

1. 运行类型检查（bun run typecheck 或 pnpm typecheck）——零错误。
2. 运行 lint/格式检查——零违规。
3. 每个新增的导出符号都有 TSDoc。
4. 样式遵循项目规范。
5. 除非有充分理由并获批准，否则不添加新依赖。

预期输出

• 遵循项目分层结构的新增或修改后的 src/ 文件。
• 所有文件均通过类型检查和 lint。
• 每个导出的函数、组件、hook 和类型都有 TSDoc。
• 样式遵循项目规范。
• 使用 fusion-framework-testing 测试已更改的行为；必要时，测试期间的 Fusion 状态使用 fusion-framework-mocking。
• 简要说明更改内容及原因。

辅助 Agent

可选辅助 Agent 位于 agents/。可用于重点审查或在实现过程中提供指导。不支持技能本地 Agent 的运行环境会直接应用相关标准。

配套技能：

• fusion-research：当实现因不确定性受阻时，用于基于源资料研究 Fusion 生态。

• fusion-framework-testing：用于 Fusion Framework React 测试设置、测试夹具、渲染和故障排查。

• fusion-framework-mocking：用于测试中的确定性模块状态以及 HTTP/OpenAPI 边界。

• agents/testing.md — 创建、维护和执行应用测试；引导使用测试/模拟配套技能。适用于已更改的行为、测试文件、测试夹具、配置或测试失败。

• agents/framework.md — Fusion Framework 集成：模块、HTTP 客户端、引导流程、运行时配置、设置、书签、分析。优先使用 mcp_fusion_search_framework；不可用时改用 mcp_fusion_search_docs。在接入 config.ts、app.config.ts 或框架模块时查阅。

• agents/styling.md — EDS 组件选择、styled-components、设计令牌、无障碍性。优先使用 mcp_fusion_search_eds。构建或修改视觉组件时查阅。

• agents/design.md — 页面/视图结构：Fusion Portal 外壳组合、布局区域、侧边面板用法、空状态/加载状态模式。参考 equinor-design-system 获取布局的权威信息。组件级检查交由 agents/styling.md。搭建新页面或布局包装器时查阅。

• agents/data-display.md — AG Grid 与 AG Charts 的选择、模块设置、列定义、图表选项、集成图表。优先使用 mcp_fusion_search_framework。构建网格、图表或仪表板时查阅。选择库时使用 assets/charts-decision-matrix.md。

• agents/person-components.md — @equinor/fusion-react-person：PersonAvatar、PersonCard、PersonListItem、PersonPicker、PeoplePicker、PeopleViewer、PersonCell（AG Grid）。DOM 事件模式、valueGetter 设置及注意事项。涉及任何人员展示、搜索或选择界面时查阅。

• agents/code-quality.md — 将规范检查（命名、TSDoc、TS 严格性、意图注释）交由 fusion-code-conventions，并汇总检查结果。完成后定稿前，对每个新增或修改的文件运行检查。

安全与约束

• 未经明确批准，不得添加新依赖。
• 不得直接操作 DOM——使用 React 模式。
• 不得使用 any 类型——遵循 TypeScript 严格模式标准。
• 源文件中不得包含机密或凭据。
• 遵循 Conventional Commits（feat:、fix:、refactor: 等）。
• 除非明确要求，否则不得添加基础设施文件（docker-compose、CI 配置）。