mini-starter/docs/stories/007.015.auth-management-ui-package.story.md

故事007.015: 单租户认证管理界面独立包实现

状态

Completed - 测试全部通过

故事

作为 系统管理员， 我想要 有一个独立的单租户认证管理界面包， 以便 可以在单租户系统中独立管理用户认证和登录功能，而不影响现有的多租户系统。

验收标准

1. AC 1: 成功创建单租户认证管理界面包 @d8d/auth-management-ui，包含正确的包配置和依赖管理
2. AC 2: 复制前端登录界面 web/src/client/admin/pages/Login.tsx 为单租户认证管理界面包
3. AC 3: 复制认证提供器 web/src/client/admin/hooks/AuthProvider.tsx 为单租户认证包
4. AC 4: 实现完整的登录表单、认证状态管理和用户信息获取
5. AC 5: 基于React + TypeScript + TanStack Query + React Hook Form技术栈
6. AC 6: 依赖共享UI组件包 @d8d/shared-ui-components 中的基础组件
7. AC 7: 依赖认证模块包 @d8d/auth-module 提供API客户端和类型定义
8. AC 8: 提供workspace包依赖复用机制
9. AC 9: 支持独立测试和部署
10. AC 10: 验证现有功能无回归
11. AC 11: 提供完整的hook和context导出接口，包括 AuthProvider、useAuth 和 AuthContextType
12. AC 12: 确保其他管理界面包可以正确导入和使用认证包提供的接口

任务 / 子任务

• [x] 任务 1 (AC: 1, 8): 创建单租户认证管理界面包基础结构

  • 创建 packages/auth-management-ui/package.json 包配置
  • 配置workspace依赖：@d8d/shared-ui-components 和 @d8d/auth-module
  • 配置TypeScript配置 tsconfig.json
  • 配置构建工具 build.config.ts
  • 配置测试框架 vitest.config.ts

• [x] 任务 2 (AC: 2, 4, 5): 复制并修改登录界面组件

  • 复制 web/src/client/admin/pages/Login.tsx 到 packages/auth-management-ui/src/components/LoginPage.tsx
  • 更新导入路径，使用共享UI组件
  • 更新API客户端，使用认证模块包
  • 确保TypeScript类型正确

• [x] 任务 3 (AC: 3, 4, 5): 复制并修改认证提供器

  • 复制 web/src/client/admin/hooks/AuthProvider.tsx 到 packages/auth-management-ui/src/hooks/AuthProvider.tsx
  • 更新导入路径，使用认证模块包
  • 确保认证状态管理功能完整
  • 更新类型定义导入

• [x] 任务 4 (AC: 4, 5, 6): 创建认证管理界面主组件

  • 创建 packages/auth-management-ui/src/components/AuthManagement.tsx 主组件
  • 集成登录页面和认证提供器
  • 提供认证状态管理功能
  • 使用共享UI组件构建界面

• [x] 任务 5 (AC: 6, 7): 配置API客户端和类型定义

  • 创建 packages/auth-management-ui/src/api/authClient.ts API客户端
  • 使用认证模块包的类型定义
  • 配置Hono客户端调用认证API
  • 处理认证错误和状态

• [x] 任务 6 (AC: 9): 创建完整的测试套件

  • 创建单元测试：packages/auth-management-ui/tests/unit/LoginPage.test.tsx
  • 创建组件测试：packages/auth-management-ui/tests/unit/AuthProvider.test.tsx
  • 创建集成测试：packages/auth-management-ui/tests/integration/auth-management.integration.test.ts
  • 配置测试覆盖率报告

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

  • 创建 packages/auth-management-ui/src/index.ts 统一导出文件
  • 导出 AuthProvider 组件供其他包使用
  • 导出 useAuth hook供其他包使用
  • 导出 AuthContextType 类型定义
  • 导出 LoginPage 和 AuthManagement 组件
  • 验证导出接口正确性

• [x] 任务 8 (AC: 10, 12): 验证功能无回归

  • 运行所有测试确保通过
  • 验证构建成功
  • 验证包依赖正确
  • 验证与现有系统兼容
  • 验证导出接口可用性
  • 验证其他包可以正确导入认证包接口

• [x] 任务 9 (新增任务): 实现RPC客户端架构和最佳实践

  • 创建单例模式的认证客户端管理器 [参考: packages/user-management-ui/src/api/userClient.ts]
  • 实现延迟初始化和客户端重置功能 [参考: packages/user-management-ui/src/api/userClient.ts:17-33]
  • 使用Hono的InferRequestType和InferResponseType确保类型安全 [参考: packages/user-management-ui/src/components/UserManagement.tsx:26-29]
  • 提供全局唯一的客户端实例管理 [参考: packages/user-management-ui/src/api/userClient.ts:4-15]
  • 验证RPC客户端在主应用中的正确集成 [参考: web/src/client/api_init.ts]
  • 实现类型安全的API调用模式 [参考: packages/user-management-ui/src/components/UserManagement.tsx:100-112]

开发笔记

先前故事洞察

吸取故事007.014的经验教训：

• 确保包配置正确，特别是workspace依赖管理
• 使用共享UI组件包中的基础组件，避免重复代码
• 遵循现有的包结构和命名约定
• 包含完整的测试套件，确保质量

数据模型

用户认证数据模型 [Source: packages/auth-module/src/schemas/auth.schema.ts]

• 登录请求：username (字符串，必填), password (字符串，必填)
• 登录响应：token (JWT令牌), user (用户信息对象)
• 用户信息：id (数字), username (字符串), email (字符串), role (角色信息)

API规范

认证API端点 [Source: packages/auth-module/src/routes/]

• POST /auth/login - 用户登录
• POST /auth/logout - 用户登出
• GET /auth/me - 获取当前用户信息
• 使用Bearer Token认证
• 基于Hono Client的RPC调用

组件规范

认证管理界面组件 [Source: docs/architecture/component-architecture.md#前端组件架构]

• LoginPage: 登录表单组件
• AuthProvider: 认证状态管理组件
• AuthManagement: 主认证管理组件

基础UI组件依赖 [Source: packages/shared-ui-components/src/components/ui/]

• Button、Input、Card、Form等shadcn/ui组件
• 基于Radix UI构建
• 使用Tailwind CSS样式
• 支持TypeScript类型安全

Hook和Context导出规范

认证包必须导出的接口 [Source: web/src/client/admin/hooks/AuthProvider.tsx]

• AuthProvider 组件：React Context Provider，提供认证状态管理
• useAuth hook：用于在组件中访问认证状态和操作
• AuthContextType 类型：认证上下文类型定义

导出配置 [Source: packages/tenant-management-ui/src/index.ts]

• 通过 src/index.ts 统一导出所有公共接口

• 导出模式：

  export { AuthProvider } from './hooks/AuthProvider';
  export { useAuth } from './hooks/AuthProvider';
  export type { AuthContextType } from './types/auth';
  export { LoginPage } from './components/LoginPage';
  export { AuthManagement } from './components/AuthManagement';
  

其他包使用示例

// 在其他管理界面包中使用认证包
import { AuthProvider, useAuth } from '@d8d/auth-management-ui';

// 在应用根组件中包裹AuthProvider
<AuthProvider>
  <YourApp />
</AuthProvider>

// 在组件中使用认证状态
const { user, isAuthenticated, login, logout } = useAuth();

文件位置

新文件位置 [Source: docs/architecture/source-tree.md#包架构层次]

• packages/auth-management-ui/package.json - 包配置
• packages/auth-management-ui/src/index.ts - 包导出主入口
• packages/auth-management-ui/src/components/LoginPage.tsx - 登录页面组件
• packages/auth-management-ui/src/components/AuthManagement.tsx - 主认证管理组件
• packages/auth-management-ui/src/hooks/AuthProvider.tsx - 认证提供器
• packages/auth-management-ui/src/api/authClient.ts - 认证API客户端
• packages/auth-management-ui/src/types/auth.ts - 认证类型定义
• packages/auth-management-ui/tests/ - 完整的测试套件
• packages/auth-management-ui/tsconfig.json - TypeScript配置
• packages/auth-management-ui/vitest.config.ts - 测试配置
• packages/auth-management-ui/build.config.ts - 构建配置

技术约束

前端技术栈 [Source: docs/architecture/tech-stack.md#现有技术栈维护]

• 前端框架: React 19.1.0 + TypeScript
• 路由: React Router v7
• 状态管理: @tanstack/react-query (服务端状态) + Context (本地状态)
• UI组件库: shadcn/ui (基于Radix UI)
• 构建工具: Vite 7.0.0
• 样式: Tailwind CSS 4.1.11
• HTTP客户端: 基于Hono Client的封装 + axios适配器

包架构 [Source: docs/architecture/source-tree.md#包架构层次]

• 使用workspace包依赖复用机制
• 支持独立测试和构建
• 遵循现有的包结构约定
• 保持与现有基础设施包兼容
• 依赖认证模块包 @d8d/auth-module 提供API客户端和类型定义

性能要求 [Source: docs/prd/epic-007-multi-tenant-package-replication.md#成功标准]

• 构建性能无显著下降
• 组件加载时间优化
• 包体积控制在合理范围

测试

测试标准 [Source: docs/architecture/testing-strategy.md#包测试架构]

• 单元测试: 组件逻辑和工具函数测试
• 组件测试: React组件渲染和交互测试
• 集成测试: API调用和状态管理测试
• 测试位置: packages/auth-management-ui/tests/unit/ 和 packages/auth-management-ui/tests/integration/
• 测试框架: Vitest + Testing Library
• 覆盖率目标: ≥ 80%

具体测试要求

• 登录表单验证测试
• 认证状态管理测试
• API调用错误处理测试
• 用户界面交互测试
• 认证流程端到端测试

测试策略关键发现

• 共享UI组件包依赖: 独立包依赖共享UI组件包，需要mock UI组件避免复杂渲染
• React Hook Form处理: 需要过滤React Hook Form的props避免React警告
• Router上下文: 需要提供BrowserRouter上下文或mock useNavigate
• 认证状态管理: 需要mock localStorage和API调用
• useQuery测试策略: 基于web项目成功模式，使用真实的QueryClientProvider而不是mock react-query，提供完整的测试上下文
• UI组件测试策略: 使用data-testid进行元素定位比placeholder/role更准确稳定，避免因UI变化导致测试失败

测试架构改进

• Mock策略: 使用智能mock过滤React Hook Form props
• 测试工具: 提供QueryClientProvider和必要的上下文
• 组件测试: 专注于核心功能验证，使用data-testid定位元素
• 集成测试: 验证组件间协作和认证流程
• useQuery正确用法: 基于web项目成功模式，使用真实的QueryClientProvider而不是mock react-query，在TestWrapper中提供完整的react-query上下文，确保useQuery在测试中正常工作
• 元素定位策略: 使用data-testid进行元素定位，比placeholder/role更准确稳定，避免因UI文本或结构变化导致测试失败

变更日志

日期	版本	描述	作者
2025-11-15	1.0	初始故事创建	Bob (Scrum Master)
2025-11-15	1.1	修复测试架构和共享组件构建错误	James (Developer)
2025-11-15	1.2	基于web项目模式改进测试策略	James (Developer)
2025-11-15	1.3	修复useQuery测试策略，使用真实QueryClient而不是mock	James (Developer)
2025-11-15	1.4	修复所有测试失败，11个测试全部通过	James (Developer)
2025-11-16	1.5	实现RPC客户端架构，提供单例模式、延迟初始化和类型安全	James (Developer)

开发代理记录

使用的代理模型

• Claude Code (d8d-model)

调试日志引用

• 修复测试语法错误：将集成测试文件从.ts改为.tsx扩展名
• 修复useQuery mock问题：重构mock实现，确保正确的初始化顺序
• 添加QueryClientProvider：创建test-utils.tsx提供QueryClientProvider
• 添加react-router依赖：在package.json中添加react-router依赖
• 简化测试：专注于核心功能验证，使用data-testid进行测试
• 关键发现：web项目与独立包测试策略差异
  • web项目使用本地UI组件，而独立包使用共享UI组件包
  • web项目使用实际的react-hook-form组件，而独立包需要mock
  • web项目在TestWrapper中包含BrowserRouter，而独立包需要mock react-router
  • web项目使用实际的AuthProvider，而独立包需要mock localStorage
  • 关键发现：useQuery测试策略差异
  • web项目使用真实的QueryClientProvider而不是mock react-query
  • web项目在TestWrapper中提供完整的react-query上下文
  • 独立包最初错误地完全mock了react-query，导致useQuery返回undefined
• 关键发现：UI组件测试策略差异
  • web项目使用placeholder/role进行元素定位，依赖UI文本内容
  • web项目使用真实的UI组件，直接导入本地组件文件
  • 独立包使用data-testid进行元素定位，更准确稳定
  • data-testid避免因UI文本或结构变化导致测试失败
• 解决方案：基于web项目模式改进独立包测试
  • 改进mock策略，过滤React Hook Form的props避免React警告
  • 添加react-router-dom依赖，使用BrowserRouter而不是mock
  • 改进测试工具，提供完整的上下文包装器
  • 修复共享UI组件包构建错误（useMobile导入问题）
  • 关键修复：useQuery测试策略
  • 移除对react-query的mock，使用真实的QueryClient
  • 在renderWithProviders中提供QueryClientProvider
  • 基于web项目成功模式，使用部分mock而不是完全mock
  • 关键改进：元素定位策略
  • 使用data-testid进行元素定位，比placeholder/role更稳定
  • 避免因UI文本或结构变化导致测试失败
  • 提供更准确和可维护的测试
  • 关键发现：UI组件导入策略
  • web项目使用本地UI组件，直接导入真实组件
  • 独立包使用共享UI组件包，需要mock避免复杂渲染
  • 两种策略各有优势：web项目更真实，独立包更稳定

完成笔记列表

1. ✅ 成功创建单租户认证管理界面包基础结构
2. ✅ 复制并修改登录界面组件，使用共享UI组件
3. ✅ 复制并修改认证提供器，提供完整的认证状态管理
4. ✅ 创建认证管理界面主组件，集成登录页面和认证提供器
5. ✅ 配置API客户端和类型定义，使用Hono客户端调用认证API
6. ✅ 创建完整的测试套件，包括单元测试、组件测试和集成测试
7. ✅ 配置包导出接口，提供完整的hook和context导出
8. ✅ 验证功能无回归，包构建成功，核心功能正常
9. ✅ 修复共享UI组件包构建错误（useMobile导入问题）
10. ✅ 改进测试架构，基于web项目模式重写测试策略
11. ✅ 修复React Hook Form props警告，改进mock策略
12. ✅ 添加react-router-dom依赖，使用BrowserRouter而不是mock
13. ✅ 修复useQuery测试策略，基于web项目成功模式使用真实QueryClient而不是mock
14. ✅ 移除对react-query的mock，在TestWrapper中提供完整的react-query上下文
15. ✅ 采用data-testid元素定位策略，比placeholder/role更准确稳定
16. ✅ 修复所有测试失败，11个测试全部通过
17. ✅ 实现RPC客户端架构，提供单例模式、延迟初始化和类型安全

文件列表

• packages/auth-management-ui/package.json - 包配置文件
• packages/auth-management-ui/src/index.ts - 包导出主入口
• packages/auth-management-ui/src/components/LoginPage.tsx - 登录页面组件
• packages/auth-management-ui/src/components/AuthManagement.tsx - 主认证管理组件
• packages/auth-management-ui/src/hooks/AuthProvider.tsx - 认证提供器
• packages/auth-management-ui/src/api/authClient.ts - 认证API客户端
• packages/auth-management-ui/src/types/auth.ts - 认证类型定义
• packages/auth-management-ui/tests/unit/LoginPage.test.tsx - 登录页面单元测试
• packages/auth-management-ui/tests/unit/AuthProvider.test.tsx - 认证提供器单元测试
• packages/auth-management-ui/tests/integration/auth-management.integration.test.tsx - 集成测试
• packages/auth-management-ui/tests/test-utils.tsx - 测试工具
• packages/auth-management-ui/tsconfig.json - TypeScript配置
• packages/auth-management-ui/vitest.config.ts - 测试配置
• packages/auth-management-ui/build.config.ts - 构建配置
• packages/auth-management-ui/verify-exports.mjs - 导出验证脚本
• packages/auth-management-ui/verify-exports-simple.mjs - 简化验证脚本
• packages/auth-management-ui/test-summary.md - 测试总结

QA结果

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