# 故事007.016: 多租户认证管理界面独立包实现

## 状态

Ready for Review

## 故事

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

## 验收标准

1. **AC 1**: 成功创建多租户认证管理界面包 `@d8d/auth-management-ui-mt`，包含正确的包配置和依赖管理
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-mt` 提供API客户端和类型定义
8. **AC 8**: 提供workspace包依赖复用机制
9. **AC 9**: 支持独立测试和部署
10. **AC 10**: 验证现有功能无回归

## 任务 / 子任务

- [x] 任务 1 (AC: 1, 8): 直接复制单租户认证管理界面包
  - [x] 复制整个包：`cp -r packages/auth-management-ui/ packages/auth-management-ui-mt/`
  - [x] 清理构建产物：删除 `packages/auth-management-ui-mt/dist/` 和 `packages/auth-management-ui-mt/node_modules/`

- [x] 任务 2 (AC: 1): 更新包配置和依赖
  - [x] 更新 `packages/auth-management-ui-mt/package.json` 包名：`@d8d/auth-management-ui-mt`
  - [x] 更新依赖：将 `@d8d/auth-module` 改为 `@d8d/auth-module-mt`
  - [x] 更新包描述和版本信息

- [x] 任务 3 (AC: 1): 安装包依赖
  - [x] 在包目录中运行 `pnpm install` 安装依赖
  - [x] 验证依赖安装成功，没有错误

- [x] 任务 4 (AC: 4, 7): 更新API客户端和类型定义
  - [x] 更新 `packages/auth-management-ui-mt/src/api/authClient.ts` 使用多租户认证模块包
  - [x] 更新 `packages/auth-management-ui-mt/src/types/auth.ts` 类型定义
  - [x] 确保所有导入路径指向多租户包

- [x] 任务 5 (AC: 4, 5, 6): 更新组件支持多租户上下文
  - [x] 更新 `packages/auth-management-ui-mt/src/components/LoginPage.tsx` 支持租户数据隔离
  - [x] 更新 `packages/auth-management-ui-mt/src/hooks/AuthProvider.tsx` 支持多租户认证状态管理
  - [x] 确保 `packages/auth-management-ui-mt/src/components/AuthManagement.tsx` 支持租户上下文

- [x] 任务 6 (AC: 9): 更新测试套件
  - [x] 复制并更新单元测试：`packages/auth-management-ui-mt/tests/unit/LoginPage.test.tsx`
  - [x] 复制并更新单元测试：`packages/auth-management-ui-mt/tests/unit/AuthProvider.test.tsx`
  - [x] 复制并更新集成测试：`packages/auth-management-ui-mt/tests/integration/auth-management.integration.test.tsx`
  - [x] 更新测试工具：`packages/auth-management-ui-mt/tests/test-utils.tsx`

- [x] 任务 7 (AC: 1, 8): 更新包导出接口
  - [x] 更新 `packages/auth-management-ui-mt/src/index.ts` 包导出主入口
  - [x] 确保所有导出组件、hook和类型定义正确
  - [x] 验证导出脚本正常工作

- [x] 任务 8 (AC: 10): 验证功能无回归
  - [x] 运行包构建：`pnpm build`
  - [x] 运行所有测试：`pnpm test`
  - [x] 验证多租户认证功能正常
  - [x] 验证租户数据隔离机制正常工作

- [x] 任务 9 (新增任务): 修复客户端路由引用问题
  - [x] 修复认证管理UI包中的客户端路由引用，从手动定义类型改为导入认证模块包的实际路由定义
  - [x] 更新 `packages/auth-management-ui/src/api/authClient.ts` 导入 `authRoutes` 并使用 `typeof authRoutes`
  - [x] 移除手动定义的路由类型，确保类型安全
  - [x] 验证代码编译和测试通过
  - [x] 确保与用户管理UI包的客户端实现保持一致

## 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/auth-management-ui-mt/` [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/auth-module-mt` - 提供多租户认证API [Source: docs/prd/epic-007-multi-tenant-package-replication.md#认证管理界面包]

### 从前一个故事吸取的经验教训
- **直接复制包策略**: 基于故事007.015的成功实现，采用直接复制包的方法，避免重复开发相同的基础结构 [Source: docs/prd/epic-007-multi-tenant-package-replication.md#故事16]
- **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#测试策略关键发现]
- **认证状态管理**: 需要mock localStorage和API调用 [Source: docs/stories/007.015.auth-management-ui-package.story.md#测试策略关键发现]

### 测试标准
- **测试框架**: Vitest + Testing Library [Source: architecture/testing-strategy.md#单元测试]
- **测试位置**: `packages/auth-management-ui-mt/tests/unit/` 和 `packages/auth-management-ui-mt/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#测试金字塔策略]

### 关键实施要点
- **直接复制包策略**: 基于故事007.015的成功实现，直接复制整个包结构，然后进行必要的修改，避免重复开发相同的基础结构 [Source: docs/prd/epic-007-multi-tenant-package-replication.md#故事16]
- **包命名**: 使用 `-mt` 后缀区分多租户包 [Source: docs/prd/epic-007-multi-tenant-package-replication.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]

### 直接复制包策略优势
- **快速启动**: 基于现有成功实现，避免重复开发相同的基础结构
- **减少错误**: 复用经过验证的代码和测试架构
- **效率提升**: 从逐个开发改为批量修改，显著减少开发时间
- **经验复用**: 直接应用故事007.015中积累的测试策略和最佳实践

### 测试

#### 测试标准和框架
- **测试框架**: Vitest 3.2.4 + Testing Library 16.3.0 [Source: architecture/testing-strategy.md#工具版本]
- **测试位置**:
  - 单元测试: `packages/auth-management-ui-mt/tests/unit/**/*.test.tsx`
  - 集成测试: `packages/auth-management-ui-mt/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#测试架构改进]

#### 特定测试要求
- **认证流程测试**: 验证登录、登出、认证状态管理功能
- **租户数据隔离测试**: 确保不同租户的认证数据正确隔离
- **API集成测试**: 验证与多租户认证模块的API集成
- **组件交互测试**: 验证组件间协作和认证流程

#### 测试执行命令
- 运行所有测试: `cd packages/auth-management-ui-mt && pnpm test`
- 运行单元测试: `cd packages/auth-management-ui-mt && pnpm test:unit`
- 运行集成测试: `cd packages/auth-management-ui-mt && pnpm test:integration`
- 生成覆盖率报告: `cd packages/auth-management-ui-mt && pnpm test:coverage`

## 变更日志

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

## Dev Agent Record

### Agent Model Used

- **开发代理**: James (Full Stack Developer)
- **模型**: d8d-model
- **任务**: 修复认证管理UI包中的客户端路由引用问题

### Debug Log References

- **问题发现**: 认证管理UI包中的客户端手动定义了路由类型，而不是从认证模块包导入实际的路由定义
- **参考实现**: 用户管理UI包 (`packages/user-management-ui/src/api/userClient.ts`) 正确使用了 `typeof userRoutes`
- **修复验证**: 代码编译成功，测试通过，类型安全得到保证

### Completion Notes List

1. **问题修复**: 将手动定义的 `AuthRoutes` 类型替换为从 `@d8d/auth-module` 导入的 `authRoutes`
2. **类型安全**: 使用 `typeof authRoutes` 确保客户端与后端API的类型一致性
3. **代码简化**: 移除了冗余的手动类型定义，简化了导出逻辑
4. **一致性**: 确保与用户管理UI包的客户端实现模式保持一致
5. **验证通过**: 构建成功，测试运行正常

### File List

- **修改文件**: `packages/auth-management-ui/src/api/authClient.ts`
- **参考文件**: `packages/user-management-ui/src/api/userClient.ts`
- **依赖文件**: `packages/auth-module/src/routes/index.ts`

## QA Results

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