frontend-ui-integration

技能：前端 UI 集成

目的

在我们的主要 Web 应用中实现或扩展面向用户的工作流，集成现有后端 API，并遵循我们的设计系统、路由和测试约定。

适用场景

• 功能主要是由一个或多个现有 API 支持的 UI/UX 变更。
• 后端契约、身份验证模型和核心业务规则已经存在。
• 变更仅影响 Web 前端（不涉及架构或服务归属变更）。

输入

• 功能描述：简要说明用户流程和预期结果。
• 相关 API：端点、请求/响应类型，以及源定义链接。
• 目标路由/组件：路径、组件名称或功能模块。
• 设计参考：Figma 链接或可供参考的现有界面。
• 约束条件：性能限制、无障碍要求及任何安全限制。

不在范围内

• 创建新的后端服务或更改持久化数据模型。
• 修改身份验证/授权流程。
• 引入新的前端框架或设计系统。

约定

• 框架：React 和 TypeScript。
• 路由：使用现有路由器和路由布局模式。
• 样式：使用内部设计系统组件（按钮、输入框、模态框、Toast 等）。
• 状态管理：优先使用现有状态库（例如 React Query、Redux、Zustand），并遵循既有模式。

必需行为

1. 实现 UI 变更，并为所有属性和 API 响应添加强类型。
2. 使用现有基础组件处理加载、空内容、错误和成功状态。
3. 确保 UI 支持键盘操作，并方便屏幕阅读器使用。
4. 在适用情况下遵循功能标志和发布机制。

必需产物

• 在相应功能模块中更新组件和钩子。
• 核心展示逻辑的单元测试。
• 针对新流程的集成测试或组件测试（例如 React Testing Library、Cypress、Playwright；如果仓库已在使用这些工具）。
• 简要的 CHANGELOG 或 PR 描述文本，总结行为变更（应放在 PR 中，而不是此文件中）。

实施清单

1. 找到相关功能模块和现有组件。
2. 确认后端 API 和类型；如有需要，更新共享 TypeScript 类型。
3. 实现 UI，并通过现有数据层接入 API 调用。
4. 添加或更新测试，覆盖新行为和边界情况。
5. 运行所需的验证命令（见下文）。

验证

运行以下命令（根据项目调整）：

• pnpm lint
• pnpm test -- --runInBand --watch=false
• pnpm typecheck（如果单独配置）

满足以下条件时，即表示此技能已完成：

• 所有测试、代码检查和类型检查均通过。
• 新 UI 在正常、错误和边界情况下均按规范运行。
• 未修改无关文件或模块。

安全与升级处理

• 如果所请求的变更需要修改后端契约，请停止，并改为申请一个后端任务。
• 如果设计参考与现有无障碍标准冲突，应优先遵循无障碍标准，并在 PR 描述中指出差异。