mini-starter/docs/stories/007.017.user-management-ui-package.story.md

故事007.017: 单租户用户管理界面独立包实现

状态

Draft

故事

作为 系统管理员， 我想要 有一个独立的单租户用户管理界面包， 以便 可以在单租户系统中独立管理用户和角色权限，而不影响现有的多租户系统。

验收标准

1. AC 1: 成功创建单租户用户管理界面包 @d8d/user-management-ui，包含正确的包配置和依赖管理
2. AC 2: 复制前端用户管理界面 web/src/client/admin/pages/Users.tsx 为单租户用户管理界面包
3. AC 3: 实现完整的用户CRUD操作、角色权限管理和用户状态管理
4. AC 4: 基于React + TypeScript + TanStack Query + React Hook Form技术栈
5. AC 5: 依赖共享UI组件包 @d8d/shared-ui-components 中的基础组件
6. AC 6: 依赖用户模块包 @d8d/user-module 提供API客户端和类型定义
7. AC 7: 提供workspace包依赖复用机制
8. AC 8: 支持独立测试和部署
9. AC 9: 验证现有功能无回归

任务 / 子任务

• [ ] 任务 1 (AC: 1, 7): 创建单租户用户管理界面包结构

  • 创建包目录：packages/user-management-ui/
  • 创建基础包结构：src/、tests/、package.json
  • 配置包依赖和构建脚本

• [ ] 任务 2 (AC: 1): 配置包依赖和构建

  • 创建 packages/user-management-ui/package.json 包配置
  • 添加依赖：@d8d/shared-ui-components、@d8d/user-module
  • 配置构建脚本和TypeScript配置

• [ ] 任务 3 (AC: 2, 3): 复制并调整用户管理界面组件

  • 复制 web/src/client/admin/pages/Users.tsx 为 packages/user-management-ui/src/components/UserManagement.tsx
  • 更新组件导入路径，使用共享UI组件包
  • 调整API客户端，使用用户模块包

• [ ] 任务 4 (AC: 3, 6): 创建API客户端和类型定义

  • 创建 packages/user-management-ui/src/api/userClient.ts API客户端
  • 创建 packages/user-management-ui/src/types/user.ts 类型定义
  • 确保所有类型定义与用户模块包对齐

• [ ] 任务 5 (AC: 3, 4): 实现完整的用户管理功能

  • 实现用户列表查询和分页功能
  • 实现用户创建、编辑、删除功能
  • 实现用户状态管理和角色权限管理
  • 实现搜索和过滤功能

• [ ] 任务 6 (AC: 8): 创建测试套件

  • 创建单元测试：packages/user-management-ui/tests/unit/UserManagement.test.tsx
  • 创建集成测试：packages/user-management-ui/tests/integration/user-management.integration.test.tsx
  • 创建测试工具：packages/user-management-ui/tests/test-utils.tsx

• [ ] 任务 7 (AC: 1, 7): 配置包导出接口

  • 创建 packages/user-management-ui/src/index.ts 包导出主入口
  • 确保所有导出组件、hook和类型定义正确
  • 验证导出脚本正常工作

• [ ] 任务 8 (AC: 9): 验证功能无回归

  • 运行包构建：pnpm build
  • 运行所有测试：pnpm test
  • 验证用户管理功能正常
  • 验证与现有系统兼容性

Dev Notes

技术栈和架构上下文

• 技术栈: React 19 + TypeScript + TanStack Query + React Hook Form [Source: architecture/tech-stack.md#现有技术栈维护]
• 前端框架: React 19.1.0 用于用户界面构建 [Source: architecture/tech-stack.md#现有技术栈维护]
• 状态管理: React Query 5.83.0 用于服务端状态管理 [Source: architecture/tech-stack.md#现有技术栈维护]
• 构建工具: Vite 7.0.0 用于开发服务器和构建 [Source: architecture/tech-stack.md#现有技术栈维护]

项目结构

• 包位置: packages/user-management-ui/ [Source: architecture/source-tree.md#实际项目结构]
• 源码结构:
  • src/components/ - React组件
  • src/hooks/ - 自定义React hooks
  • src/api/ - API客户端
  • src/types/ - TypeScript类型定义
  • tests/unit/ - 单元测试
  • tests/integration/ - 集成测试
• 依赖管理: 使用pnpm workspace依赖管理 [Source: architecture/source-tree.md#集成指南]

依赖关系

• 共享UI组件包: @d8d/shared-ui-components - 提供基础UI组件 [Source: architecture/source-tree.md#实际项目结构]
• 单租户用户模块: @d8d/user-module - 提供用户管理API [Source: docs/prd/epic-007-multi-tenant-package-replication.md#用户管理界面包]

从前一个故事吸取的经验教训

• useQuery测试策略: 使用真实的QueryClientProvider而不是mock react-query，在TestWrapper中提供完整的react-query上下文 [Source: docs/stories/007.015.auth-management-ui-package.story.md#测试策略关键发现]
• UI组件测试策略: 使用data-testid进行元素定位比placeholder/role更准确稳定，避免因UI变化导致测试失败 [Source: docs/stories/007.015.auth-management-ui-package.story.md#测试策略关键发现]
• React Hook Form处理: 需要过滤React Hook Form的props避免React警告，改进mock策略 [Source: docs/stories/007.015.auth-management-ui-package.story.md#测试策略关键发现]
• Router上下文: 需要提供BrowserRouter上下文或mock useNavigate [Source: docs/stories/007.015.auth-management-ui-package.story.md#测试策略关键发现]

测试标准

• 测试框架: Vitest + Testing Library [Source: architecture/testing-strategy.md#单元测试]
• 测试位置: packages/user-management-ui/tests/unit/ 和 packages/user-management-ui/tests/integration/ [Source: architecture/testing-strategy.md#单元测试]
• 测试覆盖率目标: ≥ 80% 单元测试覆盖率 [Source: architecture/testing-strategy.md#各层覆盖率要求]
• 测试执行: 使用 pnpm test 运行所有测试 [Source: architecture/testing-strategy.md#本地开发测试]
• 测试模式: 遵循测试金字塔模型，包含单元测试、组件测试和集成测试 [Source: architecture/testing-strategy.md#测试金字塔策略]

关键实施要点

• 包命名: 使用标准命名约定，不添加特殊后缀 [Source: docs/prd/epic-007-multi-tenant-package-replication.md#包命名约定]
• API客户端: 使用Hono客户端调用单租户用户API [Source: docs/stories/007.015.auth-management-ui-package.story.md#任务-5]
• 导出接口: 提供完整的组件、hook和类型定义导出 [Source: docs/stories/007.015.auth-management-ui-package.story.md#任务-7]
• 组件复用: 基于现有用户管理界面实现，确保功能完整性和一致性

用户管理功能特性

• 用户列表: 支持分页、搜索、过滤功能
• 用户CRUD: 完整的创建、读取、更新、删除操作
• 角色管理: 用户角色分配和权限管理
• 状态管理: 用户启用/禁用状态控制
• 头像管理: 支持头像上传和显示
• 表单验证: 完整的表单验证和错误处理

测试

测试标准和框架

• 测试框架: Vitest 3.2.4 + Testing Library 16.3.0 [Source: architecture/testing-strategy.md#工具版本]
• 测试位置:
  • 单元测试: packages/user-management-ui/tests/unit/**/*.test.tsx
  • 集成测试: packages/user-management-ui/tests/integration/**/*.test.tsx [Source: architecture/testing-strategy.md#单元测试]

测试模式和策略

• useQuery测试: 使用真实的QueryClientProvider而不是mock react-query [Source: docs/stories/007.015.auth-management-ui-package.story.md#测试策略关键发现]
• 元素定位: 使用data-testid进行元素定位，比placeholder/role更准确稳定 [Source: docs/stories/007.015.auth-management-ui-package.story.md#测试策略关键发现]
• Mock策略: 使用智能mock过滤React Hook Form props [Source: docs/stories/007.015.auth-management-ui-package.story.md#测试架构改进]
• 测试工具: 提供QueryClientProvider和必要的上下文 [Source: docs/stories/007.015.auth-management-ui-package.story.md#测试架构改进]

特定测试要求

• 用户CRUD测试: 验证用户创建、读取、更新、删除功能
• 角色权限测试: 验证用户角色分配和权限管理
• 搜索过滤测试: 验证搜索和过滤功能正常工作
• 表单验证测试: 验证表单验证和错误处理
• API集成测试: 验证与用户模块的API集成

测试执行命令

• 运行所有测试: cd packages/user-management-ui && pnpm test
• 运行单元测试: cd packages/user-management-ui && pnpm test:unit
• 运行集成测试: cd packages/user-management-ui && pnpm test:integration
• 生成覆盖率报告: cd packages/user-management-ui && pnpm test:coverage

变更日志

日期	版本	描述	作者
2025-11-15	1.0	初始故事创建	Bob (Scrum Master)

Dev Agent Record

此部分将在实施过程中由开发代理填充

Agent Model Used

将在实施过程中填充

Debug Log References

将在实施过程中填充

Completion Notes List

将在实施过程中填充

File List

将在实施过程中填充

QA Results

此部分将在质量保证审查过程中由QA代理填充