mini-starter/docs/stories/008.004.tenant-ui-package-integration.story.md

Story 008.004: 租户UI包集成到Web

Status

Completed

Story

As a 系统超级管理员 I want 将租户UI包集成到Web应用中 so that Web应用能够支持租户管理操作，包括租户CRUD、配置管理和超级管理员认证

Acceptance Criteria

1. 复制web/src/client/admin目录为web/src/client/tenant
2. 在tenant目录中集成@d8d/tenant-management-ui-mt租户管理UI包
3. 使用超级管理员认证系统（superadmin/admin123）
4. 添加租户管理路由和超级管理员认证逻辑
5. 确保Web应用能够支持租户管理操作

Tasks / Subtasks

• 复制admin目录为tenant目录 (AC: 1)
  • 执行复制命令：cp -r web/src/client/admin web/src/client/tenant
  • 验证目录结构完整性
  • 更新tenant目录中的包引用
• 在tenant-management-ui包中创建租户专用组件 (AC: 2, 4)
  • 在packages/tenant-management-ui中创建租户专用AuthProvider
  • 在packages/tenant-management-ui中创建租户专用登录页面
  • 在packages/tenant-management-ui中创建租户专用路由配置
  • 更新包导出配置
• 修改tenant目录中的关键文件 (AC: 2, 4)
  • 修改web/src/client/tenant/index.tsx：使用租户包导出的AuthProvider
  • 修改web/src/client/tenant/pages/Login.tsx：使用租户包导出的登录页面
  • 修改web/src/client/tenant/routes.tsx：使用租户包导出的路由配置
• 集成租户管理UI包到tenant路由 (AC: 2)
  • 在web/src/client/tenant/routes.tsx中导入租户管理组件
  • 添加租户管理路由配置
  • 验证路由配置正确性
• 初始化租户管理API客户端 (AC: 2)
  • 在web/src/client/tenant/api_init.ts中初始化租户管理客户端
  • 验证客户端初始化正确性
• 实现超级管理员认证逻辑 (AC: 3)
  • 修改AuthProvider使用租户模块的超级管理员登录API
  • 实现超级管理员认证状态管理
  • 验证认证功能正常工作
• 验证租户管理功能 (AC: 5)
  • 测试租户CRUD操作（创建、读取、更新、删除）
  • 测试超级管理员认证功能
  • 验证租户管理界面功能完整
• 执行回归测试 (AC: 5)
  • 运行现有功能回归测试
  • 验证向后兼容性
  • 确保性能无明显下降

Dev Notes

技术栈信息 [Source: architecture/tech-stack.md]

• 前端框架: React 19.1.0
• 路由管理: React Router 7.7.0
• 状态管理: TanStack Query 5.90.9
• 样式: Tailwind CSS 4.1.11
• 认证: JWT 9.0.2

项目结构信息 [Source: architecture/source-tree.md]

• Web应用位置: web/
• 客户端代码: web/src/client/
• 管理后台: web/src/client/admin/
• 租户管理目录: web/src/client/tenant/ (新创建)
• 租户UI包位置: packages/tenant-management-ui/

现有admin目录结构 [基于实际文件检查]

当前web/src/client/admin/目录包含以下关键文件：

• index.tsx - 管理后台入口，包含QueryClientProvider和AuthProvider
• routes.tsx - 路由配置，导入多个多租户UI包组件
• hooks/AuthProvider.tsx - 认证状态管理
• pages/Login.tsx - 登录页面
• api_init.ts - API客户端初始化

租户管理UI包结构 [基于实际包检查]

租户管理UI包（@d8d/tenant-management-ui）提供以下组件：

• TenantsPage - 租户管理页面，支持租户CRUD操作
• TenantForm - 租户表单组件
• TenantConfigPage - 租户配置管理页面

超级管理员认证机制 [Source: packages/tenant-module-mt/src/routes/auth.routes.ts]

• 使用固定的超级管理员账号：用户名 superadmin，密码 admin123
• 超级管理员ID固定为 1
• 登录成功后生成JWT token
• 租户管理操作需要超级管理员权限

租户管理API客户端 [基于租户模块包结构]

租户模块包（@d8d/tenant-module-mt）提供以下API：

• /api/v1/tenants - 租户管理API，支持CRUD操作
• /api/v1/tenant-auth - 租户认证API，支持超级管理员登录

现有集成模式 [基于web/src/client/admin/routes.tsx]

当前admin路由已经集成了多个多租户UI包，集成模式为：

// 包导入
import { UserManagement } from '@d8d/user-management-ui-mt';

// 路由配置
{
  path: 'users',
  element: <UserManagement />,
}

租户管理路由集成模式 [基于现有模式]

// 租户管理UI包导入
import { TenantsPage } from '@d8d/tenant-management-ui';

// 租户管理路由配置
{
  path: 'tenants',
  element: <TenantsPage />,
}

API客户端初始化模式 [基于web/src/client/api_init.ts]

// 租户管理客户端初始化
import { tenantClientManager } from '@d8d/tenant-management-ui/api';

// 初始化租户管理客户端
tenantClientManager.init('/api/v1/tenants');

超级管理员认证集成模式 [基于现有AuthProvider]

// 使用租户模块的超级管理员登录API
const handleLogin = async (username: string, password: string): Promise<void> => {
  const response = await tenantClientManager.get().login.$post({
    json: {
      username,
      password
    }
  });
  // ... 其他登录逻辑
};

基于故事008.002实现经验的注意事项

• 包命名一致性: 确保使用正确的包名@d8d/tenant-management-ui
• 路由配置: 基于故事008.002经验，需要正确配置租户管理路由
• 认证集成: 需要修改AuthProvider使用租户模块的认证API
• 客户端初始化: 需要初始化租户管理客户端
• 向后兼容性: 保持现有admin功能不变，新增tenant功能
• 测试策略: 基于故事008.002经验，需要验证路由、认证和功能测试

测试要求

• 使用Vitest进行集成测试 [Source: architecture/tech-stack.md#新技术添加]
• 验证租户管理路由在tenant环境下的正确性
• 测试超级管理员认证功能
• 确保租户管理界面功能正常工作
• 执行回归测试确保现有admin功能不受影响

Change Log

Date	Version	Description	Author
2025-11-18	1.0	初始故事创建	Bob (Scrum Master)

Dev Agent Record

This section is populated by the development agent during implementation

Agent Model Used

• Claude Code Dev Agent (d8d-model)

Debug Log References

• 成功构建租户管理UI包，所有测试通过
• Web应用在8080端口成功启动，无编译错误
• 租户管理路由配置正确，使用/tenant路径

Completion Notes List

1. 成功复制admin目录为tenant目录
2. 在packages/tenant-management-ui中创建了租户专用组件：
   • TenantAuthProvider：超级管理员认证提供者
   • TenantLoginPage：租户专用登录页面
3. 修改了web/src/client/tenant目录中的关键文件：
   • index.tsx：使用包导出的TenantAuthProvider
   • routes.tsx：配置租户专用路由(/tenant/*)
   • pages/Login.tsx：使用包导出的useAuth钩子
4. 创建了租户管理API客户端初始化文件
5. 更新了租户管理UI包的导出配置，添加了pages和api导出
6. 验证了所有功能正常工作

File List

• web/src/client/tenant/ - 租户管理前端目录
• packages/tenant-management-ui/src/hooks/AuthProvider.tsx - 租户认证提供者
• packages/tenant-management-ui/src/pages/LoginPage.tsx - 租户登录页面
• packages/tenant-management-ui/src/api/tenantClient.ts - 租户API客户端
• packages/tenant-management-ui/src/api/index.ts - API导出文件
• web/src/client/tenant/api_init.ts - 租户API客户端初始化

QA Results

Results from QA Agent QA review of the completed story implementation

• ✅ 所有验收标准已满足
• ✅ 租户管理UI包成功集成到Web应用
• ✅ 超级管理员认证系统正常工作
• ✅ 租户管理路由配置正确
• ✅ 所有测试通过，无回归问题